星战科技xingzhan.cloud
返回市场
Magento-API-MCP服务器

Magento-API-MCP服务器

作者：florinel-chis4 星标更新：2025-11-04
安装使用来源：spider==github.com

项目介绍

Magento 2 REST API MCP Server

一个本地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个短关键词查询列表（例如，["cart", "customer"）]
  • filter_by_method：可选的HTTP方法过滤器（GET, POST, PUT, DELETE）
  • filter_by_tag：可选的类别过滤器（例如，“carts/mine”）

示例：

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

2. get_endpoint_details

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

参数：

  • path：确切的API路径（例如，“/V1/carts/mine”）
  • 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：确切的模式名称（例如，“quote-data-cart-interface”）

返回： 包含类型、描述及所有属性的完整模式，以JSON格式呈现。

验证脚本

独立测试每个组件：

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

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

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

数据库模式

服务器使用SQLite，具有以下表：

  • endpoints：所有API端点，带有FTS5索引
  • parameters：端点参数
  • responses：响应定义
  • schemas：数据模型定义，带有FTS5索引
  • metadata：导入跟踪

相比网络抓取的优势

  1. 无网络依赖：完全离线工作
  2. 即时启动：约2-5秒，而非几分钟的网络抓取
  3. 结构化数据：访问完整的OpenAPI元数据
  4. 精确搜索：按方法、类别、响应代码过滤
  5. 模式解析：导航复杂的嵌套数据结构
  6. 确定性：无需HTML解析或网站结构变化

示例查询

查询工具目的
["cart"]search_endpoints查找所有与购物车相关的端点
["customer", "authentication"]search_endpoints查找客户认证端点
/V1/carts/mineget_endpoint_details获取完整的购物车端点文档
customersearch_schemas查找与客户相关的模式
quote-data-cart-interfaceget_schema查看购物车数据结构

开发

项目结构

magento-api-mcp/
├── magento_api_mcp/
│   ├── __init__.py
│   ├── config.py          # 配置
│   ├── parser.py          # OpenAPI解析器
│   ├── ingest.py          # 数据库导入
│   └── server.py          # 带有工具的MCP服务器
├── tests/
│   ├── verify_parser.py   # 解析器验证
│   ├── verify_db.py       # 数据库验证
│   └── verify_server.py   # 服务器验证
├── data/
│   └── swagger.json       # OpenAPI规范
├── pyproject.toml
└── README.md

添加新工具

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

使用不同的Swagger文件

服务器可以与任何OpenAPI 3.0的swagger文件一起工作。只需设置MAGENTO_API_SWAGGER_PATH环境变量：

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

许可

MIT

贡献

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

支持

对于问题或疑问，请检查：

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