Magento 2 GraphQL Documentation MCP Server

Magento 2 GraphQL文档MCP服务器

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

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

特性

• 搜索文档：在350多个GraphQL文档页面上进行全文搜索
• 获取完整文档：检索包含元数据的完整文档
• 搜索GraphQL元素：查找查询、突变、类型和接口
• 获取元素详细信息：查看完整的架构元素定义及其示例
• 浏览分类：导航文档层次结构（模式、开发、使用、教程）
• 访问教程：获得循序渐进的学习路径（例如，结账工作流程）
• 搜索代码示例：查找GraphQL、JSON、JavaScript中的工作代码示例
• 发现相关文档：自动查找相关文档
• 离线操作：使用本地markdown文件完全脱机工作
• 快速启动：只有在文档文件发生更改（\> ~/.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网络应用程序接口](https://github.com/AdobeDocs/commerce-webapi)

### 详细设置

#### 1.克隆两个存储库

Clone the documentation source

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

Clone this MCP server

cd magento-graphql-docs-mcp

#### 2.配置文档路径

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

1. **环境变量** `MAGENTO_GRAPHQL_DOCS_PATH` （如果设置，则验证路径是否存在）
1. **`./data/` 目录** （符号链接或项目根目录中有.md文件的目录）
1. **`../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"

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

1. `MAGENTO_GRAPHQL_DOCS_PATH` 环境变量（启动时验证）
1. `./data/` 项目根目录中的目录（必须包含.md文件）
1. `../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工具的实际使用示例：

### 可用示例

1. **产品查询** (`examples/example_products.py`)

   - 搜索产品文档
   - 查找产品GraphQL查询和类型
   - 查看产品界面详细信息
   - 搜索产品代码示例

1. **客户查询** (`examples/example_customer.py`)

   - 搜索客户文档
   - 查找客户突变（创建、更新）
   - 探索身份验证和令牌
   - 查找客户地址操作

1. **购物车和结账** (`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](examples/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元素

超过所有性能目标：启动时间\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客户端显示“找不到服务器”或“连接失败”

**解决方案**:

1. **验证命令是否正确：**

# Test the command directly which magento-graphql-docs-mcp # or python3 -m magento_graphql_docs_mcp.server

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

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

   **重要**：使用绝对路径，而不是 `~` 或MCP配置中的相对路径。

1. **检查日志：**

   - 克劳德桌面： `~/Library/Logs/Claude/` （macOS）
   - 查找与服务器相关的错误消息

### 获取帮助

如果你仍然有问题：

1. **运行所有验证脚本：**

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

1. **检查您的设置：**

# 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

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

## 许可证

麻省理工学院

## 贡献

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

## 支持

对于问题或疑问：

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