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

必需

可选的

______________________________________________________________________

整合

克劳德桌面

添加 ~/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/)

类别(/api/v1/category/)

订单(/api/v1/order/)

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

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

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

发票(/api/v1/invoice/)

属性(/api/v1/attribute/)

评论(/api/v1/review/)

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

存储参考数据

______________________________________________________________________

MCP资源

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

______________________________________________________________________

审计日志

每次工具调用（成功或失败）都会将一条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访问中每个商店应用的算法。

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

此服务器：

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:                 # must not be PostmanRuntime/…

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

请求格式

基本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"
  }
}

______________________________________________________________________

安全

密码处理

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

重要提示：

• 密码通过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弗洛里内尔·奇斯