commercetools Knowledge MCP Server

什么是 commercetools Knowledge MCP Server？

commercetools Knowledge MCP Server 是 commercetools 官方提供的免费 MCP 服务器，面向开发者文档和 API 规范：AI 代理可以搜索文档、获取 GraphQL 和 OpenAPI 模式，并校验查询和 REST 请求，无需任何认证。

commercetools 提供两个 MCP 服务器。Commerce MCP 操作你 Project 中的 Cart、Order 等资源，需要 API 客户端凭据。本文介绍的 Knowledge MCP 是一个无状态服务器，只提供公开的文档和 API 模式内容，因此无需访问任何 commercetools Project 即可使用。它的目标是缩短上手时间，帮助 AI 编码助手写出正确的 commercetools 代码，而不是猜测字段名。

如何使用 commercetools Knowledge MCP Server？

该服务器仅通过 Streamable HTTP 提供（没有本地 stdio，也没有 SSE），地址为：

https://docs.commercetools.com/apis/mcp

不需要 API 密钥、登录或 Project。commercetools 建议使用 commercetools-knowledge 作为本地服务器名称。

Claude Code

claude mcp add --transport http commercetools-knowledge https://docs.commercetools.com/apis/mcp

Claude Desktop 和 claude.ai

进入 Customize > Connectors > Add custom connector，名称填写 commercetools-knowledge，远程 MCP 服务器 URL 填写 https://docs.commercetools.com/apis/mcp。

Cursor

在 Cursor Settings > Tools & MCP > New MCP Server 中添加：

{
  "mcpServers": {
    "commercetools-knowledge": {
      "type": "http",
      "url": "https://docs.commercetools.com/apis/mcp"
    }
  }
}

VS Code

将其添加到用户级 mcp.json 或工作区的 .vscode/mcp.json：

{
  "servers": {
    "commercetools-knowledge": {
      "type": "http",
      "url": "https://docs.commercetools.com/apis/mcp"
    }
  }
}

对于只支持本地 stdio 服务器的客户端，commercetools 文档给出了用 mcp-remote 包装端点的方式：

"commercetools-knowledge": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://docs.commercetools.com/apis/mcp"]
}

JetBrains IDE 可以通过支持 MCP 的插件（例如 AI Assistant）连接。

commercetools Knowledge MCP Server 的主要功能

• 语义文档搜索：覆盖 commercetools 文档，可按内容类型和产品（Composable Commerce、Frontend、Checkout、Connect、InStore）过滤。
• 按资源的 GraphQL 模式：包含可按需展开的存根类型，代理只加载需要的部分。
• 按资源的 OpenAPI 规范：提供读、写或统一变体，用于构建 REST 请求或客户端。
• 离线校验：在接触任何 Project 之前，对照公开的 commercetools 模式校验 GraphQL 查询/变更和 REST 请求。
• commercetools-developer-tips 提示词：加载 key 与 id、centAmount 最小货币单位、LocalizedString、查询谓词、排序和常见陷阱等约定。
• 免费且匿名：无需认证，每个 IP 地址限制为每 15 分钟 100 次请求。

commercetools Knowledge MCP Server 工具

该服务器提供六个工具，分为三组。

• 文档：commercetools-documentation-search 返回与你的问题语义相近的文档片段；commercetools-documentation-by-id 在你已知内容 ID（例如 ctp:api:type:ProductProjection）时获取完整条目。
• 模式：commercetools-graphql-schemata 返回某个资源（如 Cart）的部分 GraphQL 模式；commercetools-oas-schemata 返回某个资源（如 api-Customer-write）的自包含 OpenAPI 规范。
• 校验：commercetools-graphql-validate 检查查询或变更，并返回带行号和列号的错误；commercetools-rest-validate 检查方法、路径和请求体，包括更新操作的判别字段。两者都是只读的，校验依据是公开模式，而不是你 Project 的配置。

官方推荐的流程是：先搜索，再获取模式，然后校验，最后生成代码或执行调用。

commercetools Knowledge MCP Server 的使用场景

• 实现 GraphQL 功能：“如何创建一个带初始商品的购物车？写出并校验这个 mutation。”
• 构建 REST 调用：“找到更新客户信息的端点，并校验一个 changeEmail 更新操作。”
• 查询概念：“Product 和 ProductProjection 有什么区别？”
• 项目脚手架：“如何设置 Checkout？列出涉及的资源及其模式。”
• 拦截幻觉字段：让代理在生成的每个查询进入代码库之前先进行校验。

commercetools Knowledge MCP Server 常见问题排查

• 429 Too Many Requests：你触发了每个 IP 每 15 分钟 100 次请求的限制（与 Knowledge REST API 共享）。请等待 Retry-After 头中给出的时间。
• 搜索结果为空：把 input 改得更宽泛或更具体，并放宽 contentTypes 或 products 过滤条件。
• 资源名称无效：检查拼写；MCP 客户端可以在工具模式中看到允许的 resourceName 取值。
• 响应缓慢：服务器位于 europe-west1，其他地区可能延迟更高。