JinDaGe - magento-graphql-docs-mcp MCP Details

article

README

🚀 Magento 2 GraphQL文档MCP服务器

这是一个本地的STDIO MCP服务器，可提供从本地Markdown文件中搜索和检索Magento 2 GraphQL API文档的工具。

📖 初次设置？ 请参阅 SETUP.md 获取分步快速入门指南。

✨ 主要特性

搜索文档：对350多个GraphQL文档页面进行全文搜索。
获取完整文档：检索带有元数据的完整文档。
搜索GraphQL元素：查找查询、突变、类型和接口。
查看元素详情：查看带有示例的完整模式元素定义。
浏览分类：浏览文档层次结构（模式、开发、使用、教程）。
访问教程：获取分步学习路径（例如，结账流程）。
搜索代码示例：查找GraphQL、JSON、JavaScript中的有效代码示例。
发现相关文档：自动查找相关文档。
离线操作：完全使用本地Markdown文件进行离线工作。
快速启动：仅在文档文件发生更改时重新索引（<5秒）。

🔧 技术细节

工作原理

解析：启动时，服务器会解析带有YAML前置元数据的Markdown文件。
提取：提取元数据、代码块和GraphQL模式元素。
索引：使用FTS5全文搜索索引将数据存储在SQLite中。
搜索：提供对文档、代码和模式的智能搜索。

🚀 快速开始

步骤1：克隆文档仓库

MCP服务器需要访问Adobe Commerce GraphQL文档的Markdown文件。请克隆官方仓库：

# 克隆commerce-webapi仓库
git clone https://github.com/AdobeDocs/commerce-webapi.git

# GraphQL文档位于：
# commerce-webapi/src/pages/graphql/

步骤2：设置文档路径

你可以通过以下两种方式配置文档路径： 选项A：使用符号链接（推荐） 在项目目录中创建符号链接：

cd magento-graphql-docs-mcp
ln -s /path/to/commerce-webapi/src/pages/graphql data

选项B：使用环境变量 设置 MAGENTO_GRAPHQL_DOCS_PATH 环境变量：

export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"

若要使其永久生效，请将其添加到你的shell配置文件（如 ~/.bashrc、~/.zshrc 等）：

echo 'export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"' >> ~/.zshrc
source ~/.zshrc

步骤3：验证文档访问权限

检查文档路径是否可访问：

# 若使用符号链接：
ls -la data/

# 若使用环境变量：
ls -la $MAGENTO_GRAPHQL_DOCS_PATH/

# 你应该会看到如下文件：
# - index.md
# - release-notes.md
# - schema/（目录）
# - tutorials/（目录）
# - develop/（目录）

步骤4：安装MCP服务器

cd magento-graphql-docs-mcp
pip install -e .

（可选）使用Docker构建并运行

如果你倾向于使用Docker，可以构建镜像并将文档路径挂载到 /data（或者设置 MAGENTO_GRAPHQL_DOCS_PATH 到其他位置）：

docker build -t magento-graphql-docs-mcp -f docker/Dockerfile .
docker run --rm -it \
  -v /absolute/path/to/commerce-webapi/src/pages/graphql:/data \
  magento-graphql-docs-mcp

自动获取回退机制：如果你没有挂载文档，容器可以在启动时克隆它们。可以通过 MAGENTO_GRAPHQL_DOCS_AUTO_FETCH 进行控制（默认值：true）：

# 让容器克隆文档（使用 /tmp/commerce-webapi/src/pages/graphql）
docker run --rm -it magento-graphql-docs-mcp

# 禁用自动获取；需要挂载路径或预设 MAGENTO_GRAPHQL_DOCS_PATH
docker run --rm -it \
  -e MAGENTO_GRAPHQL_DOCS_AUTO_FETCH=false \
  -v /absolute/path/to/commerce-webapi/src/pages/graphql:/data \
  magento-graphql-docs-mcp

主机端Docker包装器（STDIO）

使用提供的包装器来运行容器，并为MCP客户端转发标准输入/输出（不添加TTY）：

# 从仓库根目录执行
./run-docker-mcp.sh

其功能如下：

如果 magento-graphql-docs-mcp 镜像缺失，会自动构建。
如果 MAGENTO_GRAPHQL_DOCS_PATH（或 ./data）存在，则将其挂载到 /data；否则依赖自动获取。
为MCP客户端保持标准输入/输出的清洁；启动时打印连接说明。
遵循 MAGENTO_GRAPHQL_DOCS_AUTO_FETCH（设置为 false 以要求挂载路径）。

将你的MCP客户端命令指向包装器路径。例如Claude Desktop的配置：

{
  "mcpServers": {
    "magento-graphql-docs": {
      "command": "/absolute/path/to/run-docker-mcp.sh"
    }
  }
}

VS Code MCP配置

使用Docker包装器的VS Code MCP配置示例：

{
  "servers": {
    "magento-webapi-docs": {
      "type": "stdio",
      "command": "/absolute/path/to/run-docker-mcp.sh"
    }
  }
}

添加服务器条目后，打开VS Code MCP/工具面板，然后为 magento-webapi-docs 点击“启动”以启动基于容器的STDIO服务器。

Docker Compose（HTTP/SSE）

使用提供的 docker-compose.yml 在HTTP/SSE上运行服务器：

docker compose up --build

这将从 docker/Dockerfile 进行构建，映射 8765:8765，并设置 MAGENTO_GRAPHQL_DOCS_TRANSPORT=http 和 MAGENTO_GRAPHQL_DOCS_HOST=0.0.0.0。在 docker-compose.yml 中取消注释 volumes 块以绑定本地文档检出；否则镜像可以自动获取文档。选择端口8765是为了避免常见的8080冲突；可根据需要进行调整。

步骤5：运行并验证

# 运行服务器（首次运行时将解析并索引350个文档）
magento-graphql-docs-mcp

# 在另一个终端中，运行验证测试：
python3 tests/verify_parser.py
python3 tests/verify_db.py
python3 tests/verify_server.py

📦 安装指南

要求

Python 3.10或更高版本。
Git（用于克隆文档仓库）。
从 AdobeDocs/commerce-webapi 获取的350多个Magento 2 GraphQL文档Markdown文件。

详细设置

1. 克隆两个仓库

# 克隆文档源仓库
git clone https://github.com/AdobeDocs/commerce-webapi.git

# 克隆此MCP服务器仓库
cd magento-graphql-docs-mcp

2. 配置文档路径

服务器按以下顺序查找文档（启动时进行路径验证）：

环境变量 MAGENTO_GRAPHQL_DOCS_PATH（如果设置，验证路径是否存在）。
./data/ 目录（项目根目录中的符号链接或包含 .md 文件的目录）。
../commerce-webapi/src/pages/graphql/（自动检测兄弟目录）。

如果未找到有效路径，服务器将失败，并显示一条有用的错误消息，解释所有三种设置选项。

选择最适合你设置的方法：

# 方法1：符号链接（推荐用于开发）
ln -s ~/projects/commerce-webapi/src/pages/graphql data

# 方法2：环境变量（推荐用于部署）
export MAGENTO_GRAPHQL_DOCS_PATH="$HOME/projects/commerce-webapi/src/pages/graphql"

# 方法3：将commerce-webapi克隆为兄弟目录
# magento-graphql-docs-mcp/
# commerce-webapi/
#   └── src/pages/graphql/

3. 安装依赖项

pip install -e .

这将安装以下依赖项：

fastmcp - MCP服务器框架。
sqlite-utils - 数据库管理。
pydantic - 数据验证。
python-frontmatter - YAML前置元数据解析。
markdown-it-py - Markdown处理。

💻 使用示例

运行服务器

配置完成后，启动服务器：

# 启动MCP服务器
magento-graphql-docs-mcp

# 服务器将：
# 1. 检查文档是否已更改（比较文件修改时间）。
# 2. 如果需要，解析Markdown文件（350个文件，约3 - 5秒）。
# 3. 使用FTS5在SQLite中索引内容。
# 4. 开始通过STDIO监听MCP请求。

在后续运行中，如果文档未更改，启动几乎是瞬间完成（约0.87秒）。

通过HTTP/SSE运行

STDIO仍然是默认设置。若要通过带有SSE的HTTP公开服务器（适用于期望通过SSE使用MCP的客户端），请设置传输变量：

MAGENTO_GRAPHQL_DOCS_TRANSPORT=http \
MAGENTO_GRAPHQL_DOCS_HOST=0.0.0.0 \
MAGENTO_GRAPHQL_DOCS_PORT=8765 \
magento-graphql-docs-mcp

MAGENTO_GRAPHQL_DOCS_HOST 默认值为 127.0.0.1，MAGENTO_GRAPHQL_DOCS_PORT 默认值为 8765（如果未设置）。端口8765经常被其他服务使用；请选择任何可用端口（上面的示例使用默认端口8765）。

配置

服务器使用环境变量进行配置：

文档路径

设置GraphQL文档的位置：

# 选项1：绝对路径（推荐）
export MAGENTO_GRAPHQL_DOCS_PATH="/Users/you/projects/commerce-webapi/src/pages/graphql"

# 选项2：相对路径（从项目根目录）
export MAGENTO_GRAPHQL_DOCS_PATH="./data"

# 选项3：相对于主目录
export MAGENTO_GRAPHQL_DOCS_PATH="~/repos/commerce-webapi/src/pages/graphql"

默认值：服务器按以下顺序查找文档（进行验证）：

MAGENTO_GRAPHQL_DOCS_PATH 环境变量（启动时验证）。
项目根目录中的 ./data/ 目录（必须包含 .md 文件）。
../commerce-webapi/src/pages/graphql/（自动检测兄弟目录）。

数据库位置

自定义SQLite数据库的存储位置：

# 默认值：~/.mcp/magento-graphql-docs/database.db
export MAGENTO_GRAPHQL_DOCS_DB_PATH="/custom/path/magento-graphql.db"

如果数据库目录不存在，将自动创建。

性能调优（可选）

自定义搜索行为和限制：

# 返回的搜索结果数量（默认值：5）
export MAGENTO_GRAPHQL_DOCS_TOP_K=10

# 每个GraphQL元素的最大字段数（默认值：20）
export MAGENTO_GRAPHQL_DOCS_MAX_FIELDS=30

# 代码预览的最大字符长度（默认值：400）
export MAGENTO_GRAPHQL_DOCS_CODE_PREVIEW=600

传输和端口

控制MCP服务器的公开方式：

MAGENTO_GRAPHQL_DOCS_TRANSPORT：stdio（默认值）或 http/sse 以启用HTTP + SSE。
MAGENTO_GRAPHQL_DOCS_HOST：HTTP/SSE模式的绑定地址（默认值：127.0.0.1）。
MAGENTO_GRAPHQL_DOCS_PORT：HTTP/SSE端口（默认值：8765）。

当 transport="http" 时，FastMCP提供SSE服务。

与MCP客户端一起使用

配置你的MCP客户端（例如Claude Desktop、Cline等）以使用此服务器。

示例：Claude Desktop配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "magento-graphql-docs": {
      "command": "magento-graphql-docs-mcp",
      "env": {
        "MAGENTO_GRAPHQL_DOCS_PATH": "/Users/you/projects/commerce-webapi/src/pages/graphql"
      }
    }
  }
}

示例：直接使用Python模块

{
  "mcpServers": {
    "magento-graphql-docs": {
      "command": "python3",
      "args": ["-m", "magento_graphql_docs_mcp.server"],
      "env": {
        "MAGENTO_GRAPHQL_DOCS_PATH": "/path/to/commerce-webapi/src/pages/graphql"
      }
    }
  }
}

示例：使用自定义数据库路径

{
  "mcpServers": {
    "magento-graphql-docs": {
      "command": "magento-graphql-docs-mcp",
      "env": {
        "MAGENTO_GRAPHQL_DOCS_PATH": "/path/to/commerce-webapi/src/pages/graphql",
        "MAGENTO_GRAPHQL_DOCS_DB_PATH": "/custom/databases/magento-graphql.db"
      }
    }
  }
}

配置完成后，重启你的MCP客户端以激活服务器。

可用示例

examples/ 目录包含实用的使用示例，展示了所有MCP工具：

产品查询 (examples/example_products.py)
- 搜索产品文档。
- 查找产品GraphQL查询和类型。
- 探索ProductInterface详情。
- 搜索产品代码示例。
客户查询 (examples/example_customer.py)
- 搜索客户文档。
- 查找客户突变（创建、更新）。
- 探索身份验证和令牌。
- 查找客户地址操作。
购物车和结账 (examples/example_cart_checkout.py)
- 搜索购物车文档。
- 完成结账流程教程。
- 查找购物车突变和查询。
- 逐步探索结账过程。

运行示例

# 运行单个示例
python3 examples/example_products.py
python3 examples/example_customer.py
python3 examples/example_cart_checkout.py

# 或者一次性运行所有示例
bash examples/run_all_examples.sh

详细文档请参阅 examples/README.md。

📚 详细文档

MCP工具

1. `search_documentation`

使用关键字搜索文档页面。参数：

queries：1 - 3个短关键字查询列表（例如，["product", "cart"]）。
category：可选过滤器（模式、开发、使用、教程）。
subcategory：可选过滤器（产品、购物车、客户等）。
content_type：可选过滤器（指南、参考、教程、模式）。示例：

search_documentation(queries=["checkout"], category="tutorials")

2. `get_document`

按文件路径获取完整的文档页面。参数：

file_path：文档的相对路径（例如，"schema/products/queries/products.md"）。 返回值：包含元数据、前置元数据和Markdown的完整文档内容。

3. `search_graphql_elements`

搜索GraphQL查询、突变、类型或接口。参数：

query：搜索词。
element_type：可选过滤器（查询、突变、类型、接口、联合）。示例：

search_graphql_elements(query="products", element_type="query")

4. `get_element_details`

获取特定GraphQL元素的完整详细信息。参数：

element_name：元素名称（例如，"products"、"createCustomer"）。
element_type：可选类型过滤器。 返回值：包含字段、参数、源文档和代码示例的完整元素定义。

5. `list_categories`

列出所有文档分类及其文档数量。 返回值：显示所有可用文档区域的分层分类树。

6. `get_tutorial`

按顺序获取包含所有步骤的完整教程。参数：

tutorial_name：教程名称（例如，"checkout"）。 返回值：包含代码示例和解释的顺序教程步骤。

7. `search_examples`

按主题和语言搜索代码示例。参数：

query：搜索词。
language：可选语言过滤器（graphql、json、javascript、php、bash）。示例：

search_examples(query="add to cart", language="graphql")

8. `get_related_documents`

查找与指定文档相关的文档。参数：

file_path：源文档的文件路径。 返回值：基于分类和关键字的相关文档。

验证脚本

独立测试每个组件。 重要提示：请从项目根目录运行所有测试：

# 导航到项目根目录
cd magento-graphql-docs-mcp

# 测试Markdown解析器
python3 tests/verify_parser.py

# 测试数据库摄入
python3 tests/verify_db.py

# 测试MCP服务器和所有8个工具
python3 tests/verify_server.py

# 运行性能基准测试
python3 tests/benchmark_performance.py

从其他目录运行测试将导致导入错误。

数据库架构

服务器使用SQLite，包含以下表：

documents：所有带有FTS5索引的文档页面。
code_blocks：文档中的代码示例。
graphql_elements：提取的带有FTS5索引的GraphQL模式元素。
metadata：摄入跟踪。

性能

根据基准测试（运行 python3 tests/benchmark_performance.py）：

启动时间：0.87秒（数据未更改时）| 3 - 5秒（首次运行或文件更改时）。
搜索速度：平均5.5毫秒（FTS5直接查询：0.7毫秒）。
文档检索：8.2毫秒。
GraphQL元素搜索：3.4毫秒。
数据库大小：350个文档约30 MB。
索引内容：350个文档、963个代码块、51个GraphQL元素。

所有性能目标均已达成：启动时间 <5秒 ✓，搜索时间 <100毫秒 ✓。

示例查询

| 查询 | 工具 | 结果 | |-------|------|--------| | "如何查询产品？" | search_documentation | 产品查询文档 | | "显示产品查询详情" | search_graphql_elements | 产品查询定义 | | "完整的结账流程" | get_tutorial | 分步结账指南 | | "购物车突变示例" | search_examples | 有效的GraphQL购物车示例 | | "所有B2B文档" | list_categories + search | B2B模式文档 |

开发

项目结构

magento-graphql-docs-mcp/
├── magento_graphql_docs_mcp/
│   ├── __init__.py
│   ├── config.py          # 配置
│   ├── parser.py          # Markdown + GraphQL解析器
│   ├── ingest.py          # 数据库摄入
│   └── server.py          # 带有8个工具的MCP服务器
├── tests/
│   ├── verify_parser.py   # 解析器验证
│   ├── verify_db.py       # 数据库验证
│   └── verify_server.py   # 服务器验证
├── data/
│   └── (指向文档的符号链接)
├── pyproject.toml
├── README.md
└── CLAUDE.md

架构

Markdown文件 (350个)
    ↓
解析器 (前置元数据 + 内容 + GraphQL提取)
    ↓
SQLite (文档 + 代码块 + GraphQL元素 + FTS5)
    ↓
FastMCP服务器 (通过STDIO提供8个工具)
    ↓
MCP客户端 (Claude、IDE等)

优势

与网页抓取相比

✅ 离线操作（无需网络）。
✅ 快速启动（3 - 5秒 vs 30 - 60秒）。
✅ 本地控制（可使用自定义文档）。
✅ 无HTML解析复杂性。

与REST API MCP相比

✅ 包含教程和指南（不仅仅是API规范）。
✅ 代码示例可搜索。
✅ 提供用于学习的叙述性内容。
✅ 支持教程工作流程。

独特特性

📚 索引了350个文档。
🔍 8个专门的搜索工具。
💡 支持教程。
📝 代码示例搜索。
🔗 相关文档发现。
⚡ 快速FTS5搜索。
🎯 支持GraphQL感知解析。

故障排除

文档未找到错误

错误：FileNotFoundError: Documentation directory not found! 服务器现在会提供一条有用的错误消息，显示所有三种设置方法。 解决方案：

验证文档仓库是否已克隆：

git clone https://github.com/AdobeDocs/commerce-webapi.git

检查路径是否正确：

# 若使用环境变量：
echo $MAGENTO_GRAPHQL_DOCS_PATH
ls -la $MAGENTO_GRAPHQL_DOCS_PATH

# 若使用符号链接：
ls -la data/
# 应显示指向GraphQL文档的符号链接

# 你应该会看到350多个Markdown文件和如下目录：
# - schema/
# - tutorials/
# - develop/
# - index.md

设置正确的路径（选择一种方法）：

# 方法1：环境变量（推荐用于部署）
export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"

# 方法2：创建符号链接（推荐用于开发）
cd magento-graphql-docs-mcp
ln -s /path/to/commerce-webapi/src/pages/graphql data
# 验证：ls -la data/ 应显示符号链接

# 方法3：作为兄弟目录克隆
cd parent-directory
git clone https://github.com/AdobeDocs/commerce-webapi.git
# 服务器将自动找到它

验证设置：

# 服务器在启动时会验证路径，并显示有用的错误信息
magento-graphql-docs-mcp
# 如果路径无效，你将看到具体尝试了哪些方法

服务器无法启动

错误：ModuleNotFoundError: No module named 'magento_graphql_docs_mcp' 解决方案：以开发模式安装软件包：

cd magento-graphql-docs-mcp
pip install -e .

错误：服务器启动后立即退出 解决方案：检查Python版本（需要3.10+）：

python3 --version  # 应为3.10或更高版本

无搜索结果

问题：即使文档存在，搜索也没有返回结果 解决方案：

使用更短、更简单的关键字：

# 不要使用："customer authentication token generation"
# 尝试：["customer", "token"]

# 不要使用："how to add products to cart"
# 尝试：["cart", "add"]

检查数据库是否已创建：

ls -la ~/.mcp/magento-graphql-docs/
# 应显示 database.db（约30 MB）

验证数据是否已索引：

python3 tests/verify_db.py
# 应显示：350个文档、963个代码块、51个GraphQL元素

重新索引数据库：

rm ~/.mcp/magento-graphql-docs/database.db
magento-graphql-docs-mcp  # 将解析并重新索引所有内容

数据库错误

错误：sqlite3.OperationalError: database is locked 解决方案：另一个进程正在使用数据库：

# 查找并终止该进程
lsof ~/.mcp/magento-graphql-docs/database.db
kill <PID>

# 或者简单地删除并重新创建
rm ~/.mcp/magento-graphql-docs/database.db
magento-graphql-docs-mcp

错误：sqlite3.DatabaseError: database disk image is malformed 解决方案：数据库已损坏，重新创建：

rm -rf ~/.mcp/magento-graphql-docs/
magento-graphql-docs-mcp  # 将从头开始重新创建

性能缓慢

问题：首次启动需要超过10秒 解决方案：这是正常现象！首次运行会解析350个文件。后续运行时间小于1秒。问题：每次启动都很慢 解决方案：文档修改时间正在更改。检查：

# 验证git是否未更改文件时间
cd /path/to/commerce-webapi
git status
git pull  # 如果需要，更新到最新版本

验证失败

问题：verify_server.py 因连接错误而失败 解决方案：

# 确保依赖项已安装
pip install -e ".[dev]"

# 检查MCP客户端库
pip list | grep mcp

# 重新运行单个验证
python3 tests/verify_parser.py   # 测试解析
python3 tests/verify_db.py       # 测试数据库
python3 tests/verify_server.py   # 测试MCP服务器

MCP客户端集成问题

问题：MCP客户端显示“未找到服务器”或“连接失败” 解决方案：

验证命令是否正确：

# 直接测试命令
which magento-graphql-docs-mcp
# 或者
python3 -m magento_graphql_docs_mcp.server

检查MCP配置中的环境变量：

{
  "mcpServers": {
    "magento-graphql-docs": {
      "command": "magento-graphql-docs-mcp",
      "env": {
        "MAGENTO_GRAPHQL_DOCS_PATH": "/FULL/PATH/to/commerce-webapi/src/pages/graphql"
      }
    }
  }
}

重要提示：在MCP配置中使用绝对路径，而不是 ~ 或相对路径。 3. 检查日志：

Claude Desktop：~/Library/Logs/Claude/（macOS）
查找与服务器相关的错误消息

获取帮助

如果你仍然遇到问题：

运行所有验证脚本：

python3 tests/verify_parser.py
python3 tests/verify_db.py
python3 tests/verify_server.py
python3 tests/benchmark_performance.py

检查你的设置：

# Python版本
python3 --version

# 文档路径
echo $MAGENTO_GRAPHQL_DOCS_PATH
ls -la $MAGENTO_GRAPHQL_DOCS_PATH | head -20

# 数据库
ls -la ~/.mcp/magento-graphql-docs/

# 软件包安装
pip show magento-graphql-docs-mcp

创建一个GitHub问题，并附上上述命令的输出。

📄 许可证

本项目采用MIT许可证。

贡献

欢迎贡献代码！请在提交更改之前使用验证脚本来测试所有更改。

支持

如果你遇到问题或有疑问：

运行验证脚本来诊断问题。
检查数据库位置和权限。
验证文档路径是否正确。