mcpField
A
adobe-commerce-docs-mcp

adobe-commerce-docs-mcp

本地服务
github.com/jigarkkarangiya开发工具07 周前更新
代码仓库

关于 adobe-commerce-docs-mcp

为编码助手提供 Adobe Commerce 和 Magento 官方文档检索的 MCP 服务，支持浏览页面、查询错误，并提供结构化结果与可复用提示词。

主要功能

  1. 01BM25 搜索，支持同义词和拼写纠错
  2. 02读取页面、章节和代码示例
  3. 03浏览文档资源
  4. 04查询错误代码和消息
  5. 05提供故障排查与升级提示词
  6. 06缓存索引并在后台刷新

适用场景

  1. 01查找 Commerce 配置说明
  2. 02无需读取整页即可查看代码示例
  3. 03调查 Commerce 错误消息
  4. 04依据官方文档准备升级清单

MCP 相关

向 MCP 客户端提供文档搜索和读取工具、可浏览资源及可复用提示词，并支持 stdio 和 Streamable HTTP 传输。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "jigarkkarangiya-adobe-commerce-docs": {
      "command": "npx",
      "args": [
        "-y",
        "adobe-commerce-docs-mcp"
      ],
      "env": {
        "CACHE_DIR": "<CACHE_DIR>",
        "SITEMAP_URL": "<SITEMAP_URL>",
        "EXTRA_COMMERCE_SLUGS": "<EXTRA_COMMERCE_SLUGS>"
      }
    }
  }
}
启动命令npx -y adobe-commerce-docs-mcp
需要配置的环境变量
CACHE_DIRDirectory for the on-disk sitemap and page cache. Defaults to ~/.cache/adobe-commerce-docs-mcp.
SITEMAP_URLOverride the Adobe Experience League sitemap URL to index. Defaults to https://experienceleague.adobe.com/en/sitemap.xml.
EXTRA_COMMERCE_SLUGSComma-separated list of extra Experience League product slugs to index beyond the auto-detected commerce/commerce-* sections.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npmadobe-commerce-docs-mcp2.0.3

工具

9

收录的工具列表 · 更新于 3 周前

参数类型必填说明
limitnumber否最大结果数（默认：15）
querystring是搜索关键词（例如，'graphql product query'、'checkout configuration'）
sectionstring否按章节 slug 筛选（例如，commerce-admin、commerce-cloud-service、commerce-on-cloud）

详细介绍

Adobe Commerce Docs MCP 徽标

Adobe Commerce Docs MCP 服务

npm version CI License: Source-Available Node.js

一个 MCP（Model Context Protocol） 服务，可让 AI 助手直接访问官方 Adobe Commerce / Magento 文档。它会为 Adobe Experience League 站点地图建立索引，并提供工具、资源和提示词，用于搜索、浏览和阅读文档页面——所有操作都可在 AI 编码助手中完成。

功能

  • 10 个工具 — 搜索、阅读页面、浏览版块、获取长页面中的单个版块、查找相关文档、提取代码示例、获取页面目录、查询错误、多查询搜索和刷新
  • 结构化工具输出 — 每个工具都会返回类型化的 structuredContent（JSON Schema outputSchema），并附带人类可读的 Markdown，方便客户端以编程方式解析结果
  • 工具注解 — 所有工具都声明了 readOnlyHint/openWorldHint/idempotentHint，让 MCP 客户端在执行安全的只读操作时减少确认步骤
  • MCP 资源 — 可浏览用于版块和文档页面的 commerce:// URI；每次读取版块最多返回 300 个条目，以确保内容不会超出上下文限制
  • MCP 提示词 — 可复用的工作流，适用于故障排查、代码审查、升级和概念说明
  • BM25 搜索 — 按相关性排序的结果，并采用 IDF 加权和文档长度归一化
  • 同义词扩展 — graphql 也会匹配 gql，cloud 会匹配 ece，module 会匹配 extension，此外还有 40 多组
  • 模糊匹配 — 可容忍拼写错误，例如 chekout → checkout、catlog → catalog
  • 智能截断 — 在标题边界处截断，而不是截断句子
  • 即时冷启动 — 从随软件包附带的站点地图快照建立索引，然后在后台刷新实时数据；回答首次查询时无需等待获取实时站点地图
  • 持久化缓存 — 站点地图（24 小时）和页面内容（7 天）均采用磁盘缓存，重启后仍然保留
  • HTTP 传输 — 使用 --http 标志，通过 Streamable HTTP 进行远程部署或团队部署
  • 支持 Docker — 提供用于容器化部署的多阶段 Dockerfile
  • 可配置 — 所有设置均可通过环境变量调整
  • 零配置 — 只需在 MCP 配置中添加一行即可使用

工具

search_adobe_commerce_docs

支持同义词扩展和模糊匹配的 BM25 排序搜索。

参数类型必填描述
querystring是搜索关键词（例如："graphql product query"、"checkout configuration"）
limitnumber否返回结果的上限（1–50，默认值：15）
sectionstring否按版块 slug 筛选（参见可用版块）
get_doc_content

以干净的 Markdown 格式获取文档页面的完整内容。

参数类型必填描述
urlstring是搜索结果中的文档页面完整 URL
get_code_examples

仅提取文档页面中的代码块。返回不含周围说明文字的围栏代码片段；与获取完整页面相比，可大幅节省 token。

参数类型必填描述
urlstring是文档页面的完整 URL
get_page_toc

获取页面的标题层级（目录）。在获取完整内容前，可用于了解页面结构。

参数类型必填说明
urlstring是文档页面的完整 URL
get_doc_section

按标题名称（不区分大小写，匹配子字符串）仅获取页面的一个章节，包括其嵌套子标题。对于较长的页面，如果 get_doc_content 获取整页内容时会在到达所需章节前被截断，可使用此工具；请先检查 get_page_toc，找到标题名称。

参数类型必填说明
urlstring是文档页面的完整 URL
headingstring是要查找的标题文本（例如，"tunnel"、"SSH Tunnel Setup"）
get_related_docs

查找文档树中同一章节内的同级或相关页面。

参数类型必填说明
urlstring是文档页面的完整 URL
limitnumber否相关页面的最大数量（1–30，默认值：10）
lookup_error_code

在知识库中搜索错误代码或消息。会自动获取排名最高的结果，以便立即提供答案。

参数类型必填说明
errorstring是错误代码或消息（例如，"MDVA-43395"、"Unable to serialize value"）
multi_page_search

在一次调用中使用多个查询进行搜索。返回去重后的结果，减少从多个角度进行研究时的往返次数。

参数类型必填说明
queriesstring[]是搜索查询数组（1–5）
limit_per_querynumber否每个查询的最大结果数（1–20，默认值：5）
sectionstring否应用于所有查询的可选章节筛选条件
list_doc_sections

列出所有可用的文档章节及页面数量。无需参数。

refresh_sitemap

强制刷新缓存的站点地图数据，并清除磁盘上的页面内容缓存（每个页面单独缓存，最长 7 天），使之后获取的页面返回最新内容，而不是过时内容。无需参数。

可用章节

将这些 slug 用作 section 参数：

章节 Slug说明
commerce-admin管理面板、目录、客户、订单、商店配置
commerce-operations安装、升级、配置、CLI 工具、补丁
commerce-cloud-service云基础设施、部署、环境
commerce-on-cloud云架构、CLI/分支、CDN 和 Fastly VCL、开发工具和集成
commerce-merchant-servicesLive Search、Product Recommendations、Payment Services
commerce-channelsAmazon Sales Channel、Channel Manager
commerce-knowledge-base故障排查文章和已知问题
commerce-learn教程和视频指南
commerce-business-intelligence报告和分析

资源

MCP 资源允许 AI 客户端通过 URI 直接浏览数据，无需调用工具。

URI说明
commerce://sections所有文档章节及页面数量
commerce://stats服务状态：版本、运行时间、索引大小
commerce://docs/{section}浏览某个章节内的所有页面（支持自动补全）

提示词

MCP 提示词是可在所有 MCP 客户端（Cursor、Claude Desktop、VS Code、Windsurf 等）中使用的可复用工作流。

提示词参数说明
troubleshoot-commerce-errorerror_message搜索知识库，并提供根本原因、解决方案和预防措施
explain-commerce-concepttopic结合官方文档中的代码示例和最佳实践解释概念
commerce-code-reviewcode根据官方 Commerce 编码标准审查 PHP/XML/JS 代码
commerce-upgrade-guidefrom_version、to_version生成升级清单，包括破坏性变更和回滚计划

Cursor 快速设置

选项 A：自动设置脚本（Linux / macOS）

在终端中运行此命令：

bash <(curl -sS https://raw.githubusercontent.com/jigarkkarangiya/adobe-commerce-docs-mcp/main/setup-cursor.sh)

或者，如果你已经克隆了仓库：

bash setup-cursor.sh

脚本将：

  • 检查是否已安装 Node.js 18+
  • 创建或更新你的 ~/.cursor/mcp.json
  • 提示你重启 Cursor
选项 B：手动设置（所有平台 — 3 步）
前提条件

你需要安装 Node.js 18+。运行以下命令进行检查：

node --version

如果尚未安装，请从 nodejs.org 安装。

第 1 步：在 Cursor 中打开 MCP 设置
  1. 打开 Cursor
  2. 前往 设置（左下角的齿轮图标，或按 Ctrl + , / Cmd + ,）
  3. 在左侧边栏中，点击 “MCP”
  4. 点击 “+ Add new MCP server”
第 2 步：添加服务

此时会出现一个对话框。填写以下内容：

字段值
名称adobe-commerce-docs
类型command
命令npx -y adobe-commerce-docs-mcp

点击 “Add”。

第 3 步：验证

你应该会在 MCP 列表中看到 adobe-commerce-docs，旁边有一个绿色圆点（表示已启用）。

在 Agent 模式下打开任意聊天并尝试提问：

“搜索 Adobe Commerce 文档，查找结账配置”

选项 C：直接编辑配置文件

打开（或创建）MCP 配置文件：

操作系统路径
Linux~/.cursor/mcp.json
macOS~/.cursor/mcp.json
Windows%USERPROFILE%\.cursor\mcp.json

添加以下 JSON（如果文件中已有其他服务，请将 adobe-commerce-docs 块合并到现有的 mcpServers 对象中）：

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

保存后重启 Cursor。

其他工具的设置

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

操作系统配置路径
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "adobe-commerce-docs": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-docs-mcp"]
    }
  }
}
VS Code / GitHub Copilot

将以下内容添加到项目根目录下的 .vscode/mcp.json：

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

将以下内容添加到 ~/.codeium/windsurf/mcp_config.json：

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

使用示例

连接后，只需在任意 AI 聊天中自然提问：

你提出的问题执行的操作
“搜索 Adobe Commerce 文档，查找 GraphQL 产品查询”使用同义词扩展进行 BM25 排序搜索
“获取支付方式的文档页面”获取完整页面，并转换为整洁的 Markdown
“只显示 DI 文档中的代码示例”仅提取代码块（节省 token）
“结账页面的目录是什么？”返回标题层级
“查找与此 Cloud 部署文档相关的页面”返回文档树中的同级页面
“查找错误 MDVA-43395”搜索知识库，并自动获取排名最高的匹配项
“搜索 REST API、GraphQL mutations 和 webhooks”在一次调用中执行多查询搜索
“Commerce 对目录价格规则有什么说明？”搜索后读取最匹配的页面
“帮助我从 2.4.6 升级到 2.4.7”使用升级指南提示词工作流

工作原理

┌─────────────┐     ┌──────────────────────────┐     ┌─────────────────────────┐
│  AI Client   │────▶│  MCP Server (v2.0)        │────▶│  Adobe Experience League │
│  (Cursor,    │◀────│                          │◀────│  sitemap.xml + .md pages │
│   Claude,    │     │  10 Tools                │     │                         │
│   VS Code)   │     │  3 Resources             │     └─────────────────────────┘
│              │     │  4 Prompts               │
└─────────────┘     └──────────────────────────┘
                      │
                      ├─ BM25 search with synonym expansion + fuzzy matching
                      ├─ Pre-warms sitemap on startup
                      ├─ Fetches .md endpoints (native markdown)
                      ├─ Memory LRU cache: 100 pages, 1h TTL
                      ├─ Disk page cache: 7-day TTL (survives restarts)
                      └─ Disk sitemap cache: 24h TTL
  1. 启动时，立即从随软件包附带的站点地图快照建立索引（每次发布 npm 时都会重新生成），随后在后台从 Adobe Experience League 获取最新数据并刷新索引。这样搜索无需等待实时获取约 77MB 的站点地图即可立即使用，并会在数秒内自动校正为完整的实时数据。若存在有效的 24 小时磁盘缓存，则跳过此过程，直接从磁盘加载。
  2. 使用 BM25 评分、同义词映射和文档频率统计构建倒排索引
  3. 搜索时，使用同义词扩展搜索词，并针对拼写错误进行模糊匹配回退
  4. 请求页面内容时，获取原生 .md 版本（整洁的 Markdown，无需解析 HTML）
  5. 若 .md 不可用，则回退到获取 HTML 并进行转换
  6. 智能截断会在标题边界处截断，而非截断句子
  7. 页面会缓存到磁盘（7 天）和内存中（LRU，100 个页面，1 小时）

HTTP 传输

对于团队/远程部署，请以 HTTP 模式运行服务：

npm run start:http
# or
npx adobe-commerce-docs-mcp --http

这会在端口 3000 上启动 Streamable HTTP 服务（可通过 PORT 环境变量配置）。

Docker
docker build -t adobe-commerce-docs-mcp .
docker run -p 3000:3000 adobe-commerce-docs-mcp

配置

所有设置均可通过环境变量配置：

变量默认值描述
SITEMAP_URLAdobe Experience League URL覆盖站点地图来源
CACHE_DIR~/.cache/adobe-commerce-docs-mcp缓存目录路径
SITEMAP_CACHE_TTL_MS86400000 (24h)站点地图缓存时长
PAGE_CACHE_MAX100内存 LRU 缓存中的最大页面数
PAGE_CACHE_TTL_MS3600000 (1h)内存缓存页面时长
PAGE_DISK_CACHE_TTL_MS604800000 (7d)磁盘缓存页面时长
MAX_CONTENT_LENGTH15000每个页面响应的最大字符数
MAX_CONCURRENT_FETCHES5并发获取的站点地图数
PORT3000HTTP 服务端口（使用 --http 时）
LOG_LEVELinfo日志级别：debug、info、warn、error

故障排除

MCP 服务无法启动
  • 确认已安装 Node.js 18+：node --version
  • 在终端中手动测试命令： 
    npx -y adobe-commerce-docs-mcp
  • 如果你使用企业代理，请确保 npm 可以访问注册表： 
    npm config set registry https://registry.npmjs.org/
Cursor 中未显示绿点
  • 点击 MCP 设置中服务名称旁边的刷新图标
  • 完全重启 Cursor
  • 查看 Cursor 的输出面板，检查是否有错误消息
搜索显示“未找到结果”
  • 首次使用时会加载站点地图（需要几秒钟）。请稍候再试。
  • 使用更宽泛的关键词：用 "checkout" 代替 "checkout multishipping step 3"
  • 同义词扩展会自动处理许多别名（gql → graphql、ece → cloud 等）
  • 请 AI 运行 refresh_sitemap，以重新加载最新数据
首次响应较慢
  • 首次查询会触发站点地图加载（约 2–5 秒）。后续查询会立即返回。
  • 站点地图会在磁盘上缓存 24 小时，页面内容会缓存 7 天，因此重启后速度很快。

开发

从源代码运行
git clone https://github.com/jigarkkarangiya/adobe-commerce-docs-mcp.git
cd adobe-commerce-docs-mcp
npm install
npm run build
npm start
开发模式（自动重新加载）
npm run dev          # stdio transport
npm run dev:http     # HTTP transport
运行测试
npm test
项目结构
adobe-commerce-docs-mcp/
├── src/
│   ├── index.ts          # MCP server: tools, resources, prompts, transport
│   ├── sitemap.ts        # Sitemap loading, BM25 search, synonyms, fuzzy matching
│   ├── content.ts        # Page fetching, markdown/HTML parsing, structured extraction
│   └── config.ts         # Environment variable configuration
├── tests/
│   ├── search.test.ts    # Search, Levenshtein, synonym expansion tests
│   └── content.test.ts   # Content extraction, TOC, smart truncation tests
├── dist/                 # Compiled JS (generated by `npm run build`)
├── .cursor/
│   ├── rules/            # Cursor auto-apply rules for this MCP
│   └── prompts/          # Cursor slash commands (/commerce-search, etc.)
├── .github/workflows/    # CI/CD: build, test, publish
├── Dockerfile            # Multi-stage Docker build for HTTP deployment
├── setup-cursor.sh       # One-command Cursor setup script
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md
参与贡献
  1. Fork 此代码库
  2. 创建分支：git checkout -b my-feature
  3. 进行修改
  4. 构建并测试：npm run build && npm test
  5. 提交并推送
  6. 创建 Pull Request

要求

  • Node.js 18 或更高版本

查找此 MCP

注册表链接
npmnpmjs.com/package/adobe-commerce-docs-mcp
GitHubgithub.com/jigarkkarangiya/adobe-commerce-docs-mcp
官方 MCP 注册表io.github.jigarkkarangiya/adobe-commerce-docs-mcp — 查看 server.json
Cursorcursor.directory — 搜索 adobe-commerce-docs
mcp.somcp.so — 搜索 adobe-commerce-docs
Smitherysmithery.ai — 搜索 adobe-commerce-docs
Glamaglama.ai/mcp/servers — 搜索 adobe commerce

相关 MCP

更新日志

请参阅 CHANGELOG.md，了解各个版本新增、修复、更改和改进的内容。

许可证

源代码公开 — 保留所有权利

源代码公开，便于透明审查和评估。您可以安装并运行未经修改的软件包，用于个人、教育或内部非商业用途。未经事先书面许可，不得修改、分叉、再分发或用于商业用途。完整条款请参阅 LICENSE。

© 2026 Jigar Karangiya · LinkedIn

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。