Magento GraphQL 文档 MCP

Name: Magento GraphQL 文档 MCP
Author: florinel-chis

作者：florinel-chis7 星标更新：2025-11-21

安装使用来源：spider==github.com

项目介绍

Magento 2 GraphQL 文档 MCP 服务器

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

📖 新手入门？ 请参阅 SETUP.md，获取逐步快速入门指南。

功能

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

工作原理

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

快速开始

步骤 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 /绝对路径/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 /绝对路径/to/commerce-webapi/src/pages/graphql:/data \
  magento-graphql-docs-mcp

主机端 Docker 包装器（STDIO）

使用提供的包装器运行容器并转发 STDIN/STDOUT 给 MCP 客户端（不添加 TTY）：

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

它执行以下操作：

自动构建 magento-graphql-docs-mcp 镜像（如果缺失）
挂载 MAGENTO_GRAPHQL_DOCS_PATH（或 ./data）到 /data（如果存在）；否则依赖于自动获取
保持 STDIO 清洁供 MCP 客户端使用；启动时打印连接指令
尊重 MAGENTO_GRAPHQL_DOCS_AUTO_FETCH（设置为 false 以强制要求挂载路径）

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

{
  "mcpServers": {
    "magento-graphql-docs": {
      "command": "/绝对路径/to/run-docker-mcp.sh"
    }
  }
}

VS Code MCP 配置

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

{
  "servers": {
    "magento-webapi-docs": {
      "type": "stdio",
      "command": "/绝对路径/to/run-docker-mcp.sh"
    }
  }
}

添加服务器条目后，在 VS Code MCP/Tools 面板中点击 magento-webapi-docs 的“启动”按钮以启动容器支持的 STDIO 服务器。

步骤 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（用于克隆文档仓库）
350 多个来自 AdobeDocs/commerce-webapi 的 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. 在 SQLite 中使用 FTS5 索引内容
# 4. 开始通过 STDIO 监听 MCP 请求

后续运行时，如果文档没有更改，启动几乎是瞬时的（约 0.87 秒）。

配置

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

文档路径

设置 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=1
0

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

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

与 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：可选过滤器（schema, develop, usage, tutorials）
subcategory：可选过滤器（products, cart, customer 等）
content_type：可选过滤器（guide, reference, tutorial, schema）

示例：

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：可选过滤器（query, mutation, type, interface, union）

示例：

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：提取的 GraphQL 模式元素，带有 FTS5 索引
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 + 搜索	B2B 模式文档

开发

项目结构

magento-graphql-docs-mcp/
├── magento_graphql_docs_mcp/
│   ├── __init__.py
│   ├── config.py          # 配置
│   ├── parser.py          # Markdown + GraphQL 解析器
│   ├── ingest.py          # 数据库导入
│

Magento GraphQL 文档 MCP

项目介绍

Magento 2 GraphQL 文档 MCP 服务器

功能

工作原理

快速开始

步骤 1：克隆文档仓库

步骤 2：设置文档路径

步骤 3：验证文档访问

步骤 4：安装 MCP 服务器

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

主机端 Docker 包装器（STDIO）

VS Code MCP 配置

步骤 5：运行和验证

安装

要求

详细设置

1. 克隆两个仓库

2. 配置文档路径

3. 安装依赖项

使用

运行服务器

配置

文档路径

数据库位置

性能调整（可选）

与 MCP 客户端一起使用

示例：Claude Desktop 配置

示例：直接使用 Python 模块

示例：具有自定义数据库路径

使用示例

可用示例

运行示例

MCP 工具

1. search_documentation

2. get_document

3. search_graphql_elements

4. get_element_details

5. list_categories

6. get_tutorial

7. search_examples

8. get_related_documents

验证脚本

数据库模式

性能

示例查询

开发

项目结构

1. `search_documentation`

2. `get_document`

3. `search_graphql_elements`

4. `get_element_details`

5. `list_categories`

6. `get_tutorial`

7. `search_examples`

8. `get_related_documents`