Adobe Commerce MCP

adobe-commerce-mcp

面向 PHP Adobe Commerce 模块的 MCP 服务，无网络连接，无需凭据。

安装

claude mcp add adobe-commerce -- npx -y adobe-commerce-mcp

需要 Node >= 18。客户端会使用 npx 运行服务，因此无需安装。对于 Claude Desktop、Cursor、Windsurf、VS Code 和其他客户端，请参阅其他客户端。

快速使用

重启客户端，然后用自然语言提出需求。助手会选择相应工具：

• “创建依赖于 Magento_Catalog 的模块 Acme_Reviews”
• “为 Magento\Catalog\Model\Product::getName 添加一个 after 插件”
• “system.xml 应该放在哪里，它的 XSD 是什么？”
• “创建表 acme_review，并为 catalog_product_entity 添加外键”
• “bin/magento setup:static-content:deploy 有哪些选项？”
• “mutation addProductsToCart 接受哪些参数？”

包含的内容

适用于在 PaaS 或自有服务器上编写 Adobe Commerce（Magento Open Source）模块的开发者：di.xml、插件、观察者、布局、db_schema.xml、webapi.xml，以及日常 PHP 开发所需的其他内容。

• 离线官方文档：来自四个 AdobeDocs 仓库的 1,896 个页面，支持按章节进行 BM25 搜索。每条结果均包含标题、公开 URL 和源仓库中的路径。
• 配置文件：每个文件的用途、放置位置（目录和区域）、文档提供的 XSD URN，以及相关说明页面。
• CLI 和 Web API：bin/magento 的 147 个命令（2.4.9）及其选项、OpenAPI 架构中的 614 个 REST 端点，以及 225 个 GraphQL 查询和 mutation。
• 脚手架生成：模块、插件、观察者、控制器和 db_schema.xml 表。工具会返回文件（路径和内容），供客户端写入；每个文件都会注明其来源文档页面。
• 本地运行，无需凭据：不建立连接、不要求登录，也不写入磁盘。所有知识都在 data/ 中。

兼容 Claude Code、Claude Desktop、Cursor、VS Code、Windsurf 和任何使用 stdio 传输的 MCP 客户端。

为什么开发这个项目

Adobe 官方 MCP @adobe-commerce/commerce-extensibility-tools 面向使用 App Builder（aio 命令）进行开发。它要求登录 Adobe IMS（aio auth login），即使只是搜索文档也不例外；其许可证为专有许可证（EULA），并且其中一个工具会将对话历史发送给 Adobe。如果你使用 App Builder 进行开发，请使用它。对于 PHP 开发，目前没有官方服务：本项目面向这一需求，使用 Adobe Commerce 公开文档，采用 MIT 许可证，无需账户，也无需网络连接。

文档

其他客户端

对于 claude_desktop_config.json（Claude Desktop）、~/.cursor/mcp.json 或 .cursor/mcp.json（Cursor），以及 ~/.codeium/windsurf/mcp_config.json（Windsurf）：

{
  "mcpServers": {
    "adobe-commerce": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-mcp"]
    }
  }
}

对于 VS Code，使用 .vscode/mcp.json：

{
  "servers": {
    "adobe-commerce": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "adobe-commerce-mcp"]
    }
  }
}

任何使用 stdio 传输的客户端都可以使用：命令为 npx，参数为 -y adobe-commerce-mcp。如果全局安装（npm install -g adobe-commerce-mcp），命令为 adobe-commerce-mcp。在 Claude Code 中，--scope project 会将配置保存在 .mcp.json 中，方便与团队共享。

工具

入口 src/index.ts 通过 stdio 连接服务，十个工具在 src/tools/index.ts 中注册。

文档和参考

工具	参数	功能
search-docs	query, area?, limit?	搜索文档；area 为 php、frontend、webapi 或 operations。返回包含标题、URL 和源路径的摘录。
read-doc	ref, section?	根据 id、源路径或公开 URL 返回完整页面或其中的一个章节。
explain-config-file	file	说明配置文件：di.xml、events.xml、webapi.xml、db_schema.xml、crontab.xml、routes.xml、system.xml、acl.xml、布局文件以及另外 32 种文件。
lookup-cli-command	command	提供 bin/magento 命令的说明、用法、参数和选项；支持快捷写法（s:up）和关键词。
lookup-webapi	query, api?, method?, limit?	REST 端点（参数、请求体、调用它的令牌）以及 GraphQL 查询和变更（参数、返回值、示例、指南）。

脚手架

工具	参数	生成内容
scaffold-module	module, description?, packageName?, version?, license?, sequence?, php?, basePath?	registration.php、etc/module.xml 和 composer.json。
add-plugin	module, targetClass, method, type, pluginClass?, pluginName?, area?, sortOrder?, basePath?	插件类（before、after 或 around）及其 di.xml。
add-observer	module, event, observerClass?, observerName?, area?, basePath?	observer 类及其 events.xml。
add-controller	module, area, frontName, routeId?, controller?, action?, method?, title?, aclResource?, basePath?	routes.xml 和 controller（GET 页面或 POST 返回的 JSON）；对于页面，还会生成布局和模板；在 adminhtml 中，还会生成 ADMIN_RESOURCE 和 acl.xml。
add-db-schema	module, table, columns?, primaryKey?, unique?, indexes?, foreignKeys?, comment?, resource?, engine?, basePath?	在 etc/db_schema.xml 中定义表，并包含 whitelist 和 setup:upgrade 步骤。
脚手架工具还会返回包含 files（path、content、source）和 notes 的 structuredContent。路径相对于安装根目录（默认为 app/code/<Vendor>/<Module>）。工具无法查看模块：如果文件已存在，新节点会与现有内容合并，备注会对此作出提示。

资源

URI	内容
adobe-commerce://docs	按领域和文件夹整理的文档索引。
adobe-commerce://docs/{id}	单个页面，例如 adobe-commerce://docs/php/development/components/plugins.md。
adobe-commerce://config-files	目录中的配置文件列表。
adobe-commerce://sources	数据的存储库、提交记录和许可证。

数据来源

所有数据均来自 Adobe Commerce 的公开文档存储库，使用 data/fonte.json 中固定的提交记录：

存储库	许可证	提供内容
AdobeDocs/commerce-php	Apache-2.0	807 个页面：PHP 扩展、架构、教程、代码规范、模块参考。
AdobeDocs/commerce-frontend-core	Apache-2.0	262 个页面：主题、布局、模板、UI 组件、JavaScript、Page Builder。
AdobeDocs/commerce-webapi	Apache-2.0	532 个 REST 和 GraphQL 指南页面、OpenAPI 2.4.9 架构，以及生成的 GraphQL 2.4.9 参考文档。
AdobeDocs/commerce-operations.en	MIT	295 个页面：配置、CLI、安装、性能、安全、升级以及 bin/magento 参考文档。

未包含发行说明、Quality Patches Tool 中 900 多个补丁页面、云监控工具以及旧版 GraphQL 参考文档。未使用 magento/magento2 的代码和 XSD：其许可证（OSL-3.0）与此软件包的 MIT 许可证不兼容。脚手架模板改编自文档示例。

源许可证位于 data/licenses/，详情见 NOTICE。本项目与 Adobe 无关联，也未获得 Adobe 背书。

结构

src/
├── index.ts            # entry point del binario (stdio)
├── server.ts           # McpServer: registra tools y resources
├── tools/              # una herramienta por archivo, registradas en tools/index.ts
├── scaffold/           # validación de nombres y formato de los archivos generados
├── resources/          # adobe-commerce://docs, config-files y sources
└── knowledge/          # carga de data/ y búsqueda BM25
scripts/
├── ingerir.ts          # genera data/ a partir de los clones de AdobeDocs
├── catalogo-config.ts  # catálogo de archivos de configuración, con sus fuentes
├── probar-mcp.mjs      # arranca el servidor por stdio y comprueba las herramientas
└── rastros.mjs         # busca rutas locales, correos personales y nombres de clientes
data/                   # generado: docs, cli.json, webapi/, config-files.json, licencias
test/                   # node --test sobre el build

开发

npm install
npm run check

命令	作用
npm run build	将 TypeScript 编译到 build/，并将二进制文件标记为可执行。
npm run lint	检查 src/ 和 scripts/ 的类型。
npm test	使用 node --test 对构建产物运行测试。
npm run probar-mcp	通过 stdio 启动编译后的服务；若缺少预期工具则失败。
npm run rastros	在 node_modules 之外搜索本地路径、个人邮箱和客户名称。
npm run check	门禁：prettier --check、lint、构建、测试、probar-mcp 和 rastros。
npm run ingerir -- <carpeta>	根据克隆的仓库重新生成 data/（也可使用 FONTES_DIR）。
npm run inspect	在构建产物上启动 MCP Inspector。

要在客户端中测试本地版本，请将命令指向构建产物：

claude mcp add adobe-commerce-local -- node /ruta/a/adobe-commerce-mcp/build/index.js

约定：使用 ESM 模块的 TypeScript；Prettier 不加分号，使用单引号。工具描述使用英文，因为模型会读取这些描述来选择工具。知识在运行时为只读：不会写入磁盘，也不会下载内容。

更新文档

1. 将 AdobeDocs/commerce-php、commerce-frontend-core、commerce-webapi 和 commerce-operations.en 克隆到同一个文件夹中（浅克隆即可）。
2. 运行 npm run ingerir -- <carpeta>。该脚本只读取文本文件；不会执行克隆的仓库中的任何内容。
3. 如果配置目录中的条目引用了不存在的页面，或引用了源文件中未出现的 URN，内容摄取就会失败。
4. 运行 npm run check 并提交 data/：软件包需要这些数据。

分支与发布

工作从 dev 分支创建新分支，并向 dev 提交 PR。之后将其合并到 qa，测试通过后再合并到 main；每次都合并整个分支。CI 会在 Node 18、20 和 22 上运行 npm run check。

要发布，请更新 package.json、server.json 和 CHANGELOG.md 中的版本，然后推送 v* 标签：publish.yml 工作流会运行门禁、通过 provenance 发布到 npm、创建 GitHub Release，并将 server.json 发布到 MCP Registry。每个版本的变更记录见 CHANGELOG.md。

贡献 · 许可证

向 dev 提交 PR，使用 Conventional Commits，并确保 npm run check 全部通过。

MIT。data/ 中的数据保留其来源的许可证（Apache-2.0 和 MIT）：请参阅 NOTICE。

---

由 commente.me 制作 · [email protected]