AI导哈

电商API服务协议

一个生产就绪的模型上下文协议（MCP）服务器，为Gomag公共API提供支持，使AI助手如Claude能够直接、经过审计地访问您的Gomag电商店铺。

  • by florinel-chis
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 florinel-chis/gomag-mcp

使用说明

戈马格·麦克普

生产准备就绪 模型上下文协议（MCP） 服务器 Gomag公用API，让像克劳德这样的人工智能助手直接、经过审核地访问您的Gomag电子商务商店。

戈马格 是罗马尼亚的一个电子商务平台。该服务器将其整个公共REST API公开为48种类型的MCP工具，涵盖10个类别，从产品和订单管理到发货（AWB）、发票和忠诚度积分。

特性

  • 48个MCP工具 覆盖每个Gomag Public API端点
  • 全结构化审计日志记录 --每次工具调用都会生成一个不可变的JSON Lines记录（文件+stderr）
  • 敏感字段编辑 -密码、令牌和API密钥在日志中被屏蔽
  • 限速意识 --追踪Gomag的Leaky Bucket标头，并在429上自动后退
  • 指数回退重试 用于瞬态429/5xx故障（可配置的重试次数和系数）
  • 连接池 通过 httpx.AsyncClient （保持活动，最大连接数）
  • 完全异步 --从运输到工具搬运器的无阻塞
  • 两个MCP资源 — gomag://health 和 gomag://rate-limit 可观察性
  • 代码中没有秘密 --所有凭据都来自环境变量

需求

  • Python≥3.10
  • 启用公共API访问的Gomag商店
  • 你的 API密钥 和 店铺URL 从Gomag管理面板

安装

来源（建议在测试版中使用）

git clone https://github.com/florinel-chis/gomag-mcp.git
cd gomag-mcp

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install
pip install -e .

使用pip（一旦发布）

pip install gomag-mcp

配置

所有配置都是通过环境变量（前缀 GOMAG_).复制 .env.example 到 .env 并填写您的凭据：

cp .env.example .env

必需

变量 描述
GOMAG_API_KEY 您的Gomag API密钥(Apikey 标题）--来自 管理员→ API设置
GOMAG_API_SHOP 您的店铺URL，例如。 https://yourshop.gomag.ro (ApiShop 头球

可选的

变量 默认值 描述
GOMAG_BASE_URL https://api.gomag.ro gomag API基础URL
GOMAG_USER_AGENT GomagMCP/1.0 自定义用户代理（不得 PostmanRuntime/…)
GOMAG_REQUEST_TIMEOUT 30.0 HTTP超时（秒）
GOMAG_MAX_RETRIES 3 重试429/5xx响应
GOMAG_RETRY_BACKOFF_FACTOR 1.0 指数回退倍数（秒）
GOMAG_AUDIT_LOG_FILE gomag_audit.jsonl 旋转JSON行审计日志的路径
GOMAG_AUDIT_LOG_MAX_BYTES 10485760 旋转前的最大日志文件大小（10 MB）
GOMAG_AUDIT_LOG_BACKUP_COUNT 5 要保留的轮换备份文件数
GOMAG_AUDIT_LOG_TO_STDERR true 还向stderr发出审核事件

整合

克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "gomag": {
      "command": "gomag-mcp",
      "env": {
        "GOMAG_API_KEY": "your_api_key_here",
        "GOMAG_API_SHOP": "https://yourshop.gomag.ro"
      }
    }
  }
}

Claude CLI(claude)

# Run once to register
claude mcp add gomag -- gomag-mcp

# Or with environment variables inline
GOMAG_API_KEY=xxx GOMAG_API_SHOP=https://yourshop.gomag.ro gomag-mcp

手动运行

# With .env file in current directory
gomag-mcp

# Or explicit env vars
GOMAG_API_KEY=xxx GOMAG_API_SHOP=https://yourshop.gomag.ro gomag-mcp

可用工具

产品中心(/api/v1/product/)

工具 方法 端点 描述
product_list 得到 /read/json 列出产品--按id、sku、类别、品牌、更新日期、促销标签、语言筛选
product_create 职位 /write/json 创建产品——支持多语言名称/描述和产品变体
product_update 职位 /patch/json 按id或sku修补现有产品
product_update_inventory 职位 /inventory/json 批量更新价格、特价和库存水平
product_delete 职位 /delete/json 按id或sku删除产品

类别(/api/v1/category/)

工具 方法 端点 描述
category_list 得到 /read/json 列表类别--按id、父级、语言筛选
category_create 职位 /write/json 创建具有多语言名称的类别
category_update 职位 /patch/json 修补现有类别
category_delete 职位 /delete/json 删除空类别

订单(/api/v1/order/)

工具 方法 端点 描述
order_list 得到 /read/json 列出订单--按id、编号、状态、日期范围、电子邮件、电话筛选
order_status_types 得到 /status/read/json 获取所有可用的订单状态类型
order_create 职位 /add/json 创建包含账单、运费、产品和折扣的订单
order_update_status 职位 /status/json 通过可选的客户通知更改订单状态
order_add_note 职位 /note/add/json 在订单上附上公开或私人便条
order_add_file 职位 /file/add/json 将文件（通过URL）附加到订单

客户群(/api/v1/customer/)

工具 方法 端点 描述
customer_list 得到 /read/json 列出客户--按id、电子邮件、电话、修改日期筛选
customer_ordered_products 得到 /orderedproducts/json 客户之前订购的产品
customer_create 职位 /add/json 注册新客户帐户
customer_update 职位 /update/json 更新客户详细信息
customer_login 职位 /login/json 对客户进行身份验证
customer_change_password 职位 /passwordchange/json 更改客户密码
customer_password_recovery 职位 /passwordrecovery/json 触发密码恢复电子邮件
customer_delete_request 职位 /deleterequest/json 提交GDPR帐户删除请求

发货/AWB(/api/v1/awb/)

AWB=航空运单——罗马尼亚快递服务使用的跟踪/运输标签。

工具 方法 端点 描述
awb_carrier_list 得到 /carrier/read/json 列出已配置的快递/承运商集成
awb_list 得到 /read/json 列出AWB记录——按订单、跟踪号、承运商过滤
awb_create 职位 /add/json 手动注册AWB跟踪号
awb_generate 职位 /generate/json 通过运营商API自动生成AWB
awb_delete 职位 /delete/json 删除AWB记录
awb_print 职位 /print/json 生成可打印的发货标签
awb_update_status 职位 /status/update/json 更新AWB交付状态

发票(/api/v1/invoice/)

工具 方法 端点 描述
invoice_create 职位 /add/json 为订单注册发票
invoice_generate 职位 /generate/json 使用商店设置自动生成发票
invoice_cancel 职位 /cancel/json 取消（作废）发票

属性(/api/v1/attribute/)

工具 方法 端点 描述
attribute_list 得到 /read/json 列出产品属性
attribute_create 职位 /write/json 创建具有多语言名称和值的属性
attribute_update 职位 /patch/json 修补现有属性

评论(/api/v1/review/)

工具 方法 端点 描述
review_list 得到 /read/json 列出评论--按产品、客户、批准状态筛选
review_create 职位 /write/json 提交产品评论（1-5星）

愿望清单(/api/v1/wishlist/)

工具 方法 端点 描述
wishlist_list 得到 /read/json 列出客户保存的产品
wishlist_add 职位 /add/json 将产品添加到客户的愿望清单中
wishlist_remove 职位 /delete/json 从愿望清单中删除产品

存储参考数据

工具 方法 端点 描述
currency_list 得到 /api/v1/currency/read/json 列出已配置的货币
payment_list 得到 /api/v1/payment/read/json 列出付款方式
brand_list 得到 /api/v1/brand/read/json 列出品牌/制造商
filter_list 得到 /api/v1/filter/read/json 类别的可过滤属性
banner_list 得到 /api/v1/banner/read/json 宣传横幅
fidelity_read 职位 /api/v1/fidelity/read/json 客户忠诚度积分平衡
rulecart_add 职位 /api/v1/rulecart/add/json 创建购物车折扣规则

MCP资源

为了可观察性，公开了两个只读资源：

URI 描述
gomag://health 服务器状态、配置的店铺URL和当前速率限制快照
gomag://rate-limit 最新API响应中的实时速率限制计数器

审计日志

每次工具调用（成功或失败）都会将一条JSON Lines记录写入 gomag_audit.jsonl （以及可选的stderr）。文件以10 MB的速度自动旋转（默认情况下保留5个备份）。

日志记录架构

{
  "timestamp": "2026-03-27T10:00:00.123456+00:00",
  "level": "AUDIT",
  "event_type": "tool_call",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "tool_name": "product_list",
  "parameters": { "page": 1, "limit": 10 },
  "api_method": "GET",
  "api_path": "/api/v1/product/read/json",
  "http_status": 200,
  "duration_ms": 123.456,
  "success": true,
  "error_message": null,
  "rate_limit_remaining_read": 45,
  "rate_limit_remaining_write": 10
}

在出错时， event_type 是 "tool_error", success 是 false，以及 error_message 包含异常文本。

敏感字段编辑

以下参数名称为 总是 替换为 ***REDACTED*** 在审计记录中，无论何种情况：

password · confirmpassword · apikey · api_key · token · secret · authorization

速率限制

Gomag API实现了 漏桶算法 在所有API访问中每个商店应用的算法。

响应头 （出现在每次响应中，直到达到限制）：

标题 描述
Api-RateLimit-Read 读取请求处理速率（req/s，默认值1）
Api-RateLimit-Read-Burst 突发事件中的最大读取请求数
Api-RateLimit-Read-Remaining 限制前剩余的读取请求
Api-RateLimit-Write 写入请求处理速率（req/s，默认值1）
Api-RateLimit-Write-Burst 突发事件中的最大写入请求数
Api-RateLimit-Write-Remaining 限制前剩余的写入请求

此服务器：

  1. 在每次请求后解析所有六个标头
  2. 通过以下方式显示最新值 gomag://rate-limit
  3. 在a 429 响应，在第一次重试前至少等待1秒，然后对后续重试使用指数回退
  4. 开 5xx 响应，使用纯指数回退(factor × 2^attempt)

Gomag API参考

Gomag Public API包含在Postman系列中(Gomag Public API.postman_collection.json).关键细节：

认证

所有请求都需要 ApiShop 头球写操作（POST）还需要 Apikey 头球

ApiShop: https://yourshop.gomag.ro        # every request
Apikey:  your_api_key_here                # POST requests only
User-Agent: <custom value>                # must not be PostmanRuntime/…

这两个值都是从您的Gomag管理面板中获得的 设置→ API.

请求格式

HTTP方法 参数
GET URL查询字符串
POST multipart/form-data 只有一个字段 data 其值是JSON序列化的有效载荷

基本URL

https://api.gomag.ro

响应格式

所有端点都返回JSON。分页列表端点包括：

{
  "total": 1250,
  "page": 1,
  "pages": 13,
  "items": [ ... ]
}

多语言字段

产品、类别和属性支持本地化名称。语言代码遵循ISO 639-1(ro, en, hu等等），并按店铺配置：

{
  "name": {
    "ro": "Geacă softshell",
    "en": "Softshell jacket"
  }
}

安全

密码处理

以下工具接受 明文密码 在其参数中：

工具 敏感参数
customer_create password, confirm_password
customer_login password
customer_change_password old_password, new_password, confirm_new_password

重要提示：

  • 密码通过HTTPS传输到Gomag API。切勿通过未加密的连接调用这些工具。
  • 密码是 从未写入审计日志 --只有 email 记录这些调用的字段。
  • 在聊天记录被持久化或共享的情况下，不要将明文密码传递给人工智能助手。

审核日志安全

  • 审核日志文件(gomag_audit.jsonl)包含API调用元数据。适当限制文件权限。
  • 启动日志打印审计文件的绝对路径——检查此项以确认日志的写入位置。
  • .env 文件和 *.jsonl 日志文件通过以下方式从git中排除 .gitignore.

发展

运行测试

pip install -e ".[dev]"
pytest

测试使用 respx 模拟HTTP响应——不需要实时凭据。

项目布局

src/gomag_mcp/
├── __init__.py       # package version
├── __main__.py       # enables `python -m gomag_mcp`
├── server.py         # FastMCP entry point, lifespan, resources
├── config.py         # Pydantic settings (GOMAG_* env vars)
├── audit.py          # Structured JSON audit logger
├── client.py         # Async HTTP client (retry, rate-limit, pooling)
├── context.py        # Shared AppContext (avoids circular imports)
└── tools/
    ├── product.py    # 5 tools
    ├── category.py   # 4 tools
    ├── order.py      # 6 tools
    ├── customer.py   # 8 tools
    ├── awb.py        # 7 tools
    ├── invoice.py    # 3 tools
    ├── attribute.py  # 3 tools
    ├── review.py     # 2 tools
    ├── wishlist.py   # 3 tools
    └── misc.py       # 7 tools

添加新工具

  1. 在中查找（或创建）相应的模块 src/gomag_mcp/tools/
  2. 在内部添加一个函数 register(mcp) 功能装饰 @mcp.tool()
  3. 呼叫 get_context() 访问共享 GomagClient 和 AuditLogger
  4. 用包装API调用 async with ctx.audit.tool_call(...) --所有日志记录都是自动的
@mcp.tool()
async def my_new_tool(param: str) -> dict[str, Any]:
    """Clear docstring — this becomes the tool description visible to Claude."""
    ctx = get_context()
    params = {"param": param}
    async with ctx.audit.tool_call("my_new_tool", params, "GET", "/api/v1/...") as ar:
        result = await ctx.client.get("/api/v1/...", params=params)
        ar.update(result)
        return result["data"]

许可证

麻省理工学院 ©2026弗洛里内尔·奇斯

相关 MCP