Magento API MCP

Magento 2 REST API MCP服务器

一个本地STDIO MCP服务器，提供了从OpenAPI（swagger）规范中搜索和检索Magento 2 REST API文档的工具。

特性

• 搜索端点：在所有Magento 2 REST API端点上进行全文搜索
• 获取端点详细信息：检索特定API终结点的完整文档
• 列表类别：按类别标签（购物车、客户、产品等）浏览端点
• 搜索模式：查找数据模型和模式定义
• 获取架构详细信息：查看包含所有属性的完整架构/模型定义
• 离线操作：使用本地swagger.json文件完全脱机工作
• 快速启动：只有在swagger.json被修改后才重新解析

工作原理

1. 解析：启动时，服务器解析OpenAPI 3.0 swagger.json文件
2. 索引：提取端点、参数、响应和模式
3. 存储：使用FTS5索引将数据存储在本地SQLite数据库中
4. 搜索：提供跨路径、描述、参数和架构的全文搜索

安装

需求

• Python 3.10或更高版本
• uv（推荐）或pip

从源代码安装

cd magento-api-mcp
pip install -e .

用法

运行服务器

magento-api-mcp

服务器会立即启动，并在第一次运行或文件被修改时解析swagger.json文件。

配置

• 数据库位置：默认值为 ~/.mcp/magento-api/database.db

- 覆盖 MAGENTO_API_DB_PATH 环境变量

• Swagger文件：默认值为 data/swagger.json 在包目录中

- 覆盖 MAGENTO_API_SWAGGER_PATH 环境变量

与MCP客户端一起使用

配置您的MCP客户端以运行 magento-api-mcp 命令：

{
  "mcpServers": {
    "magento-api": {
      "command": "magento-api-mcp"
    }
  }
}

或者使用自定义swagger文件：

{
  "mcpServers": {
    "magento-api": {
      "command": "magento-api-mcp",
      "env": {
        "MAGENTO_API_SWAGGER_PATH": "/path/to/your/swagger.json"
      }
    }
  }
}

MCP工具

1. search_endpoints

使用关键字搜索API端点。

参数：

• queries：1-3个简短关键字查询列表（例如，\[“购物车”、“客户”\]）
• filter_by_method：可选HTTP方法筛选器（GET、POST、PUT、DELETE）
• filter_by_tag：可选类别过滤器（例如“购物车/矿山”）

例子：

search_endpoints(queries=["cart operations"], filter_by_method="GET")

2. get_endpoint_details

获取特定端点的完整文档。

参数：

• path：准确的API路径（例如“/V1/推车/矿”）
• method：可选HTTP方法（如果省略，则返回此路径的所有方法）

例子：

get_endpoint_details(path="/V1/carts/mine", method="GET")

退货：

• HTTP方法和路径
• 类别和操作ID
• 摘要和说明
• 带类型和说明的参数表
• 请求正文架构（如适用）
• 响应代码和模式

3. list_tags

列出所有可用的API类别标记。

退货： 带有计数的所有端点类别的分层列表。

4. search_schemas

按关键字搜索数据模式/模型。

参数：

• query：要搜索的关键字

例子：

search_schemas(query="customer")

5. get_schema

获取模式/模型的完整定义。

参数：

• schema_name：精确的模式名称（例如，“报价数据购物车界面”）

退货： 具有JSON格式的类型、描述和所有属性的完整模式。

验证脚本

独立测试每个组件：

# Test the OpenAPI parser
python3 tests/verify_parser.py

# Test database ingestion
python3 tests/verify_db.py

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

数据库模式

服务器使用SQLite和下表：

• 端点：具有FTS5索引的所有API端点
• 参数：端点参数
• 回复：响应定义
• 模式：带有FTS5索引的数据模型定义
• 元数据：摄入追踪

相对于网络剪贴的优势

1. 无网络依赖性：完全离线工作
2. 即时启动：约2-5秒vs网络抓取分钟
3. 结构化数据：访问完整的OpenAPI元数据
4. 精确搜索：按方法、类别、响应代码筛选
5. 模式解析：浏览复杂的嵌套数据结构
6. 确定性的：没有HTML解析或网站结构更改

查询示例

发展

项目结构

magento-api-mcp/
├── magento_api_mcp/
│   ├── __init__.py
│   ├── config.py          # Configuration
│   ├── parser.py          # OpenAPI parser
│   ├── ingest.py          # Database ingestion
│   └── server.py          # MCP server with tools
├── tests/
│   ├── verify_parser.py   # Parser verification
│   ├── verify_db.py       # Database verification
│   └── verify_server.py   # Server verification
├── data/
│   └── swagger.json       # OpenAPI specification
├── pyproject.toml
└── README.md

添加新工具

要添加新的MCP工具，请编辑 magento_api_mcp/server.py 并使用 @mcp.tool() 装饰师。

使用不同的Swagger文件

服务器可以使用任何OpenAPI 3.0 swaggle文件。只需设置 MAGENTO_API_SWAGGER_PATH 环境变量：

export MAGENTO_API_SWAGGER_PATH=/path/to/different-api-swagger.json
magento-api-mcp

许可证

麻省理工学院

贡献

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

支持

有关问题或疑问，请查看：

1. 运行验证脚本以诊断问题
2. 检查数据库位置和权限
3. 验证swagger.json是有效的OpenAPI 3.0格式