Wrhs Next MCP

Warehouse.ai MCP 服务器

一个MCP（模型上下文协议）服务器，它将Warehouse.ai API端点作为工具暴露出来，供像Cursor这样的AI助手使用。

什么是MCP？

MCP（模型上下文协议）允许AI助手通过标准化工具与外部系统进行交互。此服务器使您的Warehouse.ai API对AI助手可用，从而使它们能够代表您获取数据。

快速启动

设置

遵循 安装 按照以下说明在Cursor中配置MCP服务器。

使用示例

安装后，您可以向Cursor中的AI助手提出问题，例如：

检查不同环境中的版本：

• “生产环境中@ux/application-sidebar的仓库版本是什么？”
• “测试环境中使用的是哪个版本的无页眉（no-header）？”
• “比较开发环境与生产环境中utility-header的版本”
• “在 wrhs 中，哪个版本的 application-sidebar 是最新的？”（自动查找 @ux/application-sidebar）

查找可用版本：

• “@ux/application-sidebar 有哪些可用版本？”
• “显示所有无标题版本”
• “列出 @ux/application-sidebar 的版本历史”

查找软件包的部署位置：

• “@ux/application-sidebar 部署在哪里？”
• “哪些环境中使用了无头包（或无标题包）？”
• “@ux/button 是否已投入生产？”

获取详细信息：

• “列出 wrhs 生产环境中 @ux/application-sidebar 模块在 \_default 变体下的所有文件”
• “请比较并告诉我，在测试环境中，wrhs 项目中 @ux/application-sidebar 目录下的 application-sidebar.css 文件在 7.2.0 版本和 7.0.0 版本之间的差异。”
• “在生产环境中显示@ux/application-sidebar的环境详情”
• “获取测试中无标题的配置”

特点/特性

• 📦 箱子/包裹 查询软件包版本 - 检查在开发、测试或生产环境中部署了哪些版本
• 🔍 翻译为中文是：放大镜（或表示正在查看、搜索等含义的符号，具体根据上下文确定）。 列出可用版本 - 查看任何包的所有已发布版本
• 🌍 表示地球或全球。 探索环境 - 查找软件包的部署位置
• 📊（图表） 获取环境详情 - 查看特定环境的配置
• 🔄 翻译成中文是：循环、重复 比较部署 - 轻松比较不同环境中的内容
• 🎯（瞄准目标） 智能包裹查询 - 自动重试 @ux/ 如果未找到包，则添加前缀（例如，“application-sidebar” → “@ux/application-sidebar”）

安装

1. 克隆仓库：

   git clone https://github.com/your-org/wrhs-next-mcp.git
   cd wrhs-next-mcp

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

1. 配置光标：

在您的Cursor MCP设置中添加以下内容：设置... → 光标设置 → 工具与MCP（主控面板/多点触控面板，具体含义根据上下文确定）):

   {
     "mcpServers": {
       "wrhs-next-api": {
         "command": "node",
         "args": ["/absolute/path/to/wrhs-next-mcp/dist/index.js"],
         "env": {
           "WRHS_NEXT_ENDPOINT": "https://your-warehouse-api.com",
           "WRHS_NEXT_USERNAME": "your-username",
           "WRHS_NEXT_PASSWORD": "your-password"
         }
       }
     }
   }

重要提示： 替换 /absolute/path/to/wrhs-next-mcp 以及你克隆仓库的实际路径。

1. 重启光标 加载MCP服务器。

为Claude桌面添加MCP服务器

要使用此MCP服务器与Claude Desktop配合，请按照以下步骤操作：

1. 打开Claude桌面版 并且前往 设置.

1. 导航至 开发者 表（或表格）。

1. 点击 编辑配置 按钮。这将在Finder中打开包含配置文件的文件夹。

1. 打开配置文件（通常 claude_desktop_config.json并添加MCP服务器配置：

   {
     "mcpServers": {
       "wrhs-next-api": {
         "command": "node",
         "args": ["/absolute/path/to/wrhs-next-mcp/dist/index.js"],
         "env": {
           "WRHS_NEXT_ENDPOINT": "https://your-warehouse-api.com",
           "WRHS_NEXT_USERNAME": "your-username",
           "WRHS_NEXT_PASSWORD": "your-password"
         }
       }
     }
   }

1. 保存 配置文件。

注：

• 替换 /absolute/path/to/wrhs-next-mcp 使用你克隆仓库的实际路径。
• 请使用您实际的仓库API终端和凭据。

1. 重启Claude桌面版 加载新的MCP服务器配置。

更新至最新版本

cd wrhs-next-mcp
git pull
npm install
npm run build
# Restart Cursor

可用工具

get_object

从仓库API中获取对象数据。

参数：

• name （字符串，必填）：要检索的对象的名称
• env （字符串，必填）：环境（例如，开发、预生产、生产）
• acceptedVariants （数组，可选）：接受的变体数组（例如，\['en-US', 'en-GB'\]）
• version （字符串，可选）：对象的特定版本（例如，'1.0.0'）

get_head

获取特定名称和环境下的头部信息（不下载完整对象的元数据）。

参数：

• name （字符串，必填）：对象的名称
• env (字符串，必填)：环境（例如，开发、预生产、生产）

list_versions

列出特定软件包的所有可用版本。

参数：

• name （字符串，必填）：包的名称（例如，“@ux/application-sidebar”）

list_environments

列出所有已部署特定包的环境。

参数：

• name (字符串，必填)：包的名称（例如，“@ux/application-sidebar”）

get_environment_details

获取特定环境中软件包的详细信息，包括元数据和配置。

参数：

• name （字符串，必填）：包的名称（例如，“@ux/application-sidebar”）
• env (字符串，必填)：环境（例如，开发、预生产、生产）

发展

先决条件

• Node.js 24及以上版本
• npm（Node Package Manager，节点包管理器）
• 访问Warehouse.ai API

本地开发环境设置

1. 克隆并安装依赖项（见上文）

1. 创建环境文件：

   cp .env.example .env

编辑 .env 并添加您的凭据：

   WRHS_NEXT_ENDPOINT=https://your-warehouse-api.com
   WRHS_NEXT_USERNAME=your-username
   WRHS_NEXT_PASSWORD=your-password

1. 在开发模式下运行：

   npm run dev

建筑

npm run build

这个将TypeScript编译成JavaScript在 dist/ 目录。

测试

方法1：在光标处测试

1. 确保服务器已在Cursor中进行配置（参见安装指南）
2. 重启光标
3. 检查MCP连接状态 设置... → 光标设置 → 工具与MCP（手动控制面板/多点触控面板，具体含义根据上下文确定）
4. 通过询问Cursor进行测试：

- "使用 wrhs-api 获取名为 'test' 的对象" - “在‘生产’环境中获取‘myapp’的头部信息”

方法2：MCP Inspector（开发推荐）

全局安装 MCP Inspector：

npm install -g @modelcontextprotocol/inspector

运行检查器：

mcp-inspector node dist/index.js

这会打开一个网页用户界面，在其中你可以：

• 查看所有可用工具
• 使用不同参数调用测试工具
• 实时查看回复

方法3：基于日志的调试

添加 console.error() （文件、报告等中的）陈述 src/index.ts 用于调试。这些日志会出现在 Cursor 的 MCP 日志中。

单元测试与代码质量

有关单元测试、代码规范检查和代码质量工具的信息，请参阅 TESTING.md 翻译为中文是：“测试说明.md” 或 “测试文档.md”（具体翻译可能根据上下文有所调整，但基本意思是文件名表示这是一个关于测试的说明或文档）。

快捷命令：

npm test              # Run unit tests
npm run test:coverage # Run with coverage
npm run lint          # Check code quality
npm run validate      # Run all checks

项目结构

wrhs-next-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── .env.example          # Environment variable template
├── .gitignore           # Git ignore rules
└── README.md            # This file

它是如何运作的

1. 服务器生命周期MCP服务器作为由Cursor启动的子进程运行。它

- 在Cursor打开时启动 - 在光标运行时保持存活 - 当光标关闭时终止

1. 交流使用stdio（标准输入/输出）与Cursor进行通信

1. 认证凭据通过 Cursor 配置中的环境变量传递

1. API客户端使用现有的 warehouse.ai-api-client npm包，用于与仓库API进行交互

故障排除

“服务器未找到”错误

• 原因游标配置中的路径错误
• 修复使用绝对路径（运行 pwd （在项目目录中）并确保它指向 dist/index.js

“身份验证错误”

• 原因无效的凭据
• 修复验证 WRHS_NEXT_USERNAME 并且 WRHS_NEXT_PASSWORD 在Cursor MCP配置中

“没有工具显示”

• 原因构建失败或服务器崩溃
• 修复：

1. 跑 npm run build 并检查错误 1. 检查 Cursor 的 MCP 日志设置... → 光标设置 → 工具与MCP）

“更改未显示”

• 原因服务器未重新加载
• 修复代码更改后，运行 npm run build 然后重启 Cursor

失踪 warehouse.ai-api-client 包（或包裹）

• 原因软件包未安装或无法访问
• 修复确保该包在您的npm注册表中可用，或者从您的内部源进行安装

安全注意事项

⚠️ 永远不要将凭据提交到版本控制系统中！

• 真实的凭证应该仅存在于：

- 本地 .env 文件（已忽略在Git中） - 每个团队成员的独立光标MCP配置

• 这个（或“该”） .env.example 文件中应仅包含占位符
• 每个团队成员使用自己的凭据

未来改进

• \[ \] 添加写操作（POST、PUT、DELETE）
• \[ \] 响应缓存以提高性能
• \[ \] 为AI提供更好的错误信息
• \[ \] 用于调试的请求/响应日志记录
• 支持额外的API端点
• \[ \] 限流和重试逻辑

做出贡献

1. 做出改变于 src/
2. 构建： npm run build
3. 使用MCP检查器或光标进行测试
4. 提交拉取请求

许可证

ISC（国际空间站）

支持

对于问题或疑问：

• 检查一下 故障排除 部分；章节
• 在Cursor设置中查看MCP日志

资源：

• MCP 文档

-