Grips Intelligence MCP 服务器 (v2)

一个模型上下文协议 (MCP) 服务器，将 Grips Intelligence 电子商务数据 API 暴露给任何 MCP 客户端（如 Claude Desktop、Cowork、Claude Code 等）。

v2 是对 v1 的彻底重构，从一开始就内置了防御性数据处理。它修复了 v1.x 需要运行时补丁才能解决的“.map is not a function”类错误——现在，对于数据稀疏或未知的领域，工具调用会降级为清晰的“无数据”响应，而不是崩溃。

包含内容

所有工具默认输出 Markdown 格式以提高可读性。传入 format: "json" 可获取机器可解析的输出。

安装

npm install

当你运行 npm install 时，prepare 脚本会自动构建 dist/。

配置

在 MCP 客户端的服务器配置中设置你的 Grips API 密钥。对于 Claude Desktop，该文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "grips": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/grips-mcp-server-v2/dist/index.js"
      ],
      "env": {
        "GRIPS_API_KEY": "your-api-key-here",
        "GRIPS_DEFAULT_COUNTRY": "US"
      }
    }
  }
}

必需的环境变量：

• GRIPS_API_KEY — 你的 Grips API 令牌（作为 grips-api-key 请求头发送）。

可选的环境变量：

• GRIPS_DEFAULT_COUNTRY — US、GB 或 DE。如果未设置或无效，默认为 US。

编辑配置后，请完全退出 Claude Desktop（使用 Cmd+Q，而不仅仅是关闭窗口）并重新打开。

与 v1 的区别

v1 在特定的 API 响应格式下会崩溃：当 Grips 返回一个覆盖范围很小或未知的领域时，timeseries 字段返回的是 {} 而不是 null、undefined 或 []。代码中使用了 (data.timeseries ?? []).map(...)，这只能防止 null/undefined，无法防止 {}。结果导致："data.timeseries ?? []).map is not a function"。

v2 在使用前会将每个有效载荷字段通过 toArray<T>()（针对数组）或 toObject<T>()（针对设备端点等字典型响应）进行处理。任何非数组/非对象的值都会回退到一个安全的空默认值，工具会返回清晰的“无数据”响应，而不是抛出异常。

其他更改：

• 日期标准化：所有工具的日期格式统一为 UTC 下的 YYYY-MM-DD，因此在非 UTC 时区中，行数据不会跨越日期边界。

• 货币 / 整数 / 百分比格式化程序：缺失值显示为 —，而不是 $NaN 或 0.00%。

• 错误消息：现在包含可操作的提示 — 401 → “检查你的 API 密钥”，429 → “速率受限，缩小查询窗口”等。

• 领域级错误隔离：在 grips_compare_domains 中，8 个领域对比中某一个领域的数据缺失不再导致其他七个领域的结果中断。

• 字符预算截断：响应上限约为 200KB 并带有可见提示，防止多领域拉取导致上下文窗口溢出。

开发

npm run dev    # watch mode, rebuilds on change
npm run build  # one-shot build to dist/

命令行测试

测试服务器是否能无错误启动（它会在 stdin 收到 EOF 时退出）：

GRIPS_API_KEY=your-key node dist/index.js < /dev/null

你应该在 stderr 中看到 [grips-mcp] grips-mcp-server v2.0.0 ready (default country: US). 且没有崩溃。

如需交互式测试，请使用 @modelcontextprotocol/inspector：

npx @modelcontextprotocol/inspector node dist/index.js

API 参考

Grips 在 https://gripsintelligence.com/knowledge-base/api 上记录了其公共架构。此服务器使用的查询直接复制自该页面。

目前支持的国家/地区：US、GB、DE。其他任何国家/地区在 API 调用时都会报错。

许可

私有 — 不得对外分发。