使用说明

Magento 2 GraphQL文档MCP服务器

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

📖 新安装？ 看设置.md 获取分步快速入门指南。

特性

搜索文档：在350多个GraphQL文档页面上进行全文搜索
获取完整文档：检索包含元数据的完整文档
搜索GraphQL元素：查找查询、突变、类型和接口
获取元素详细信息：查看完整的架构元素定义及其示例
浏览分类：导航文档层次结构（模式、开发、使用、教程）
访问教程：获得循序渐进的学习路径（例如，结账工作流程）
搜索代码示例：查找GraphQL、JSON、JavaScript中的工作代码示例
发现相关文档：自动查找相关文档
离线操作：使用本地markdown文件完全脱机工作
快速启动：只有在文档文件发生更改（<5秒）时才重新索引

它是如何工作的

解析：启动时，服务器使用YAML frontmatter解析markdown文件
提取：提取元数据、代码块和GraphQL架构元素
索引：使用FTS5全文搜索索引在SQLite中存储数据
搜索：提供跨文档、代码和模式的智能搜索

快速开始

步骤1：克隆文档库

MCP服务器需要访问Adobe Commerce GraphQL文档标记文件。克隆官方存储库：

# Clone the commerce-webapi repository
git clone https://github.com/AdobeDocs/commerce-webapi.git

# The GraphQL docs are located at:
# commerce-webapi/src/pages/graphql/

步骤2：设置文档路径

配置文档路径有两个选项：

选项A：使用Symlink（推荐）

在项目目录中创建符号链接：

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：验证文档访问权限

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

# If using symlink:
ls -la data/

# If using environment variable:
ls -la $MAGENTO_GRAPHQL_DOCS_PATH/

# You should see files like:
# - index.md
# - release-notes.md
# - schema/ (directory)
# - tutorials/ (directory)
# - develop/ (directory)

步骤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):

# Let the container clone docs (uses /tmp/commerce-webapi/src/pages/graphql)
docker run --rm -it magento-graphql-docs-mcp

# Disable auto-fetch; require a mount or preset 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客户端转发STDIN/STDOUT（未添加TTY）：

# From repo root
./run-docker-mcp.sh

它的作用：

构建 magento-graphql-docs-mcp 如果图像丢失，则自动生成
底座 MAGENTO_GRAPHQL_DOCS_PATH （或 ./data)to /data 如果存在；否则依赖于自动获取
为MCP客户保持STDIO的清洁；启动时打印连接说明
尊重 MAGENTO_GRAPHQL_DOCS_AUTO_FETCH （设置为 false 需要安装路径）

将MCP客户端命令指向包装器路径。Claude桌面配置示例：

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

VS代码MCP配置

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

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

添加服务器条目后，打开VS Code MCP/工具面板，按“开始” magento-webapi-docs 启动容器支持的STDIO服务器。

Docker编写（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.取消注释 volumes 挡住 docker-compose.yml 绑定本地文档签出；否则，图像可以自动获取文档。选择端口8765是为了避免常见的8080冲突；根据需要进行调整。

步骤5：运行并验证

# Run the server (will parse and index 350 documents on first run)
magento-graphql-docs-mcp

# In another terminal, run verification tests:
python3 tests/verify_parser.py
python3 tests/verify_db.py
python3 tests/verify_server.py

安装

需求

Python 3.10或更高版本
Git（用于克隆文档存储库）
350多个Magento 2 GraphQL文档标记文件 AdobeDocs/commerce网络应用程序接口

详细设置

1.克隆两个存储库

# Clone the documentation source
git clone https://github.com/AdobeDocs/commerce-webapi.git

# Clone this MCP server
cd magento-graphql-docs-mcp

2.配置文档路径

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

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

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

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

# Method 1: Symlink (recommended for development)
ln -s ~/projects/commerce-webapi/src/pages/graphql data

# Method 2: Environment variable (recommended for deployment)
export MAGENTO_GRAPHQL_DOCS_PATH="$HOME/projects/commerce-webapi/src/pages/graphql"

# Method 3: Clone commerce-webapi as sibling directory
# 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处理

用法

运行服务器

配置后，启动服务器：

# Start the MCP server
magento-graphql-docs-mcp

# The server will:
# 1. Check if documentation has changed (compares file modification times)
# 2. Parse markdown files if needed (350 files, ~3-5 seconds)
# 3. Index content in SQLite with FTS5
# 4. Start listening for MCP requests over STDIO

在后续运行中，如果文档没有更改，启动几乎是即时的（~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文档的位置：

# Option 1: Absolute path (recommended)
export MAGENTO_GRAPHQL_DOCS_PATH="/Users/you/projects/commerce-webapi/src/pages/graphql"

# Option 2: Relative path (from project root)
export MAGENTO_GRAPHQL_DOCS_PATH="./data"

# Option 3: Home directory relative
export MAGENTO_GRAPHQL_DOCS_PATH="~/repos/commerce-webapi/src/pages/graphql"

默认：服务器在以下位置查找文档（按顺序，并进行验证）：

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

数据库位置

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

# Default: ~/.mcp/magento-graphql-docs/database.db
export MAGENTO_GRAPHQL_DOCS_DB_PATH="/custom/path/magento-graphql.db"

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

性能调整（可选）

自定义搜索行为和限制：

# Number of search results to return (default: 5)
export MAGENTO_GRAPHQL_DOCS_TOP_K=10

# Max fields per GraphQL element (default: 20)
export MAGENTO_GRAPHQL_DOCS_MAX_FIELDS=30

# Max code preview length in characters (default: 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)

FastMCP在以下情况下为SSE提供服务 transport="http".

与MCP客户端一起使用

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

示例：Claude桌面配置

增添 ~/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查询和类型
- 查看产品界面详细信息
- 搜索产品代码示例
客户查询 (examples/example_customer.py)
- 搜索客户文档
- 查找客户突变（创建、更新）
- 探索身份验证和令牌
- 查找客户地址操作
购物车和结账 (examples/example_cart_checkout.py)
- 搜索购物车文档
- 完成结账工作流程教程
- 查找购物车突变和查询
- 逐步探索结账

运行示例

# Run individual examples
python3 examples/example_products.py
python3 examples/example_customer.py
python3 examples/example_cart_checkout.py

# Or run all examples at once
bash examples/run_all_examples.sh

看示例/README.md 详细文档。

MCP工具

1. `search_documentation`

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

参数：

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

例子：

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

2. `get_document`

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

参数：

file_path：文档的相对路径（例如，“schema/products/queries/products.md”）

退货： 包含元数据、frontmatter和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：源文档的文件路径

退货： 基于类别和关键字的相关文档。

验证脚本

独立测试每个组件。

重要：从项目根目录运行所有测试：

# Navigate to project root
cd magento-graphql-docs-mcp

# Test the markdown parser
python3 tests/verify_parser.py

# Test database ingestion
python3 tests/verify_db.py

# Test MCP server and all 8 tools
python3 tests/verify_server.py

# Run performance benchmarks
python3 tests/benchmark_performance.py

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

数据库模式

服务器使用SQLite和下表：

文件：所有带有FTS5索引的文档页面
代码块：文档中的代码示例
graphql_elements：提取具有FTS5索引的GraphQL模式元素
元数据：摄入追踪

演出

基于基准（运行 python3 tests/benchmark_performance.py):

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

超过所有性能目标：启动时间<5s✓,<100ms搜索✓

查询示例

查询	工具	结果
“如何查询产品？”	search_documentation	产品查询文档
“显示产品查询详细信息”	search_graphql_elements	产品查询定义
“完整结账流程”	get_tutorial	分步结账指南
“购物车突变示例”	search_examples	GraphQL购物车示例
“所有B2B文档”	列表_类别+搜索	B2B模式文档

发展

项目结构

magento-graphql-docs-mcp/
├── magento_graphql_docs_mcp/
│   ├── __init__.py
│   ├── config.py          # Configuration
│   ├── parser.py          # Markdown + GraphQL parser
│   ├── ingest.py          # Database ingestion
│   └── server.py          # MCP server with 8 tools
├── tests/
│   ├── verify_parser.py   # Parser verification
│   ├── verify_db.py       # Database verification
│   └── verify_server.py   # Server verification
├── data/
│   └── (symlink to docs)
├── pyproject.toml
├── README.md
└── CLAUDE.md

建筑

Markdown Files (350)
    ↓
Parser (frontmatter + content + GraphQL extraction)
    ↓
SQLite (documents + code_blocks + graphql_elements + FTS5)
    ↓
FastMCP Server (8 tools via STDIO)
    ↓
MCP Client (Claude, IDE, etc.)

优势

vs网络剪贴

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

与REST API MCP

✅ 包括教程和指南（不仅仅是API规范）
✅ 代码示例可搜索
✅ 学习叙事内容
✅ 教程工作流程

特点

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

故障排除

找不到文档错误

错误: FileNotFoundError: Documentation directory not found!

服务器现在提供了一条有用的错误消息，显示了所有三种设置方法。

解决方案:

验证文档存储库是否已克隆：

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

检查路径是否正确：

# If using environment variable:
echo $MAGENTO_GRAPHQL_DOCS_PATH
ls -la $MAGENTO_GRAPHQL_DOCS_PATH

# If using symlink:
ls -la data/
# Should show a symlink pointing to the GraphQL docs

# You should see 350+ markdown files and directories like:
# - schema/
# - tutorials/
# - develop/
# - index.md

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

# Method 1: Environment variable (recommended for deployment)
export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"

# Method 2: Create symlink (recommended for development)
cd magento-graphql-docs-mcp
ln -s /path/to/commerce-webapi/src/pages/graphql data
# Verify: ls -la data/ should show the symlink

# Method 3: Clone as sibling directory (automatic)
cd parent-directory
git clone https://github.com/AdobeDocs/commerce-webapi.git
# Server will automatically find it

验证设置：

# The server validates paths on startup and will show helpful errors
magento-graphql-docs-mcp
# If path is invalid, you'll see exactly which methods were tried

服务器无法启动

错误: ModuleNotFoundError: No module named 'magento_graphql_docs_mcp'

解决方案：在开发模式下安装软件包：

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

错误：服务器启动但立即退出

解决方案：检查Python版本（需要3.10+）：

python3 --version  # Should be 3.10 or higher

没有搜索结果

问题：即使文档存在，搜索也不会返回任何结果

解决方案:

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

# Instead of: "customer authentication token generation"
# Try: ["customer", "token"]

# Instead of: "how to add products to cart"
# Try: ["cart", "add"]

检查数据库是否已创建：

ls -la ~/.mcp/magento-graphql-docs/
# Should show database.db (around 30 MB)

验证数据是否已编入索引：

python3 tests/verify_db.py
# Should show: 350 documents, 963 code blocks, 51 GraphQL elements

重新索引数据库：

rm ~/.mcp/magento-graphql-docs/database.db
magento-graphql-docs-mcp  # Will parse and re-index everything

数据库错误

错误: sqlite3.OperationalError: database is locked

解决方案：另一个进程正在使用数据库：

# Find and kill the process
lsof ~/.mcp/magento-graphql-docs/database.db
kill <PID>

# Or simply remove and recreate
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  # Will recreate from scratch

性能缓慢

问题：首次启动需要>10秒

解决方案：这很正常！第一次运行解析350个文件。后续运行时间<1s。

问题：每次启动都很慢

解决方案：文档时间正在发生变化。检查：

# Verify git isn't changing file times
cd /path/to/commerce-webapi
git status
git pull  # Update to latest if needed

验证失败

问题: verify_server.py 由于连接错误而失败

解决方案:

# Ensure dependencies are installed
pip install -e ".[dev]"

# Check MCP client libraries
pip list | grep mcp

# Re-run individual verifications
python3 tests/verify_parser.py   # Test parsing
python3 tests/verify_db.py       # Test database
python3 tests/verify_server.py   # Test MCP server

MCP客户端集成问题

问题：MCP客户端显示“找不到服务器”或“连接失败”

解决方案:

验证命令是否正确：

# Test the command directly
which magento-graphql-docs-mcp
# or
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配置中的相对路径。

检查日志：
- 克劳德桌面： ~/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 version
python3 --version

# Documentation path
echo $MAGENTO_GRAPHQL_DOCS_PATH
ls -la $MAGENTO_GRAPHQL_DOCS_PATH | head -20

# Database
ls -la ~/.mcp/magento-graphql-docs/

# Package installation
pip show magento-graphql-docs-mcp

创建GitHub问题 根据上述命令的输出。

许可证

麻省理工学院

贡献

欢迎投稿！请在提交之前使用验证脚本测试所有更改。

支持

对于问题或疑问：

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

使用说明

Magento 2 GraphQL文档MCP服务器

特性

它是如何工作的

快速开始

步骤1：克隆文档库

步骤2：设置文档路径

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

步骤4：安装MCP服务器

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

主机端Docker包装器（STDIO）

VS代码MCP配置

Docker编写（HTTP/SSE）

步骤5：运行并验证

安装

需求

详细设置

1.克隆两个存储库

2.配置文档路径

3.安装依赖项

用法

运行服务器

通过HTTP/SSE运行

配置

文档路径

数据库位置

性能调整（可选）

运输和港口

与MCP客户端一起使用

示例：Claude桌面配置

示例：直接使用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

验证脚本

数据库模式

演出

查询示例

发展

项目结构

建筑

优势

vs网络剪贴

与REST API MCP

特点

故障排除

找不到文档错误

服务器无法启动

没有搜索结果

数据库错误

性能缓慢

验证失败

MCP客户端集成问题

获取帮助

许可证

贡献

支持

相关 MCP

开发者辅助工具

Gemini API文档搜索服务

GraphQL API交互服务

GraphQL模式分析工具

文档搜索服务器

文件内容读取器

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`