gomag-mcp

gomag-mcp

A production-ready Model Context Protocol (MCP) server for the Gomag Public API, giving AI assistants like Claude direct, audited access to your Gomag e-commerce store.

Gomag is a Romanian e-commerce platform. This server exposes its entire public REST API as 48 typed MCP tools across 10 categories — from product and order management to shipping (AWB), invoicing, and loyalty points.

Features

• 48 MCP tools covering every Gomag Public API endpoint
• Full structured audit logging — every tool call produces an immutable JSON Lines record (file + stderr)
• Sensitive-field redaction — passwords, tokens, and API keys are masked in logs
• Rate-limit awareness — tracks Gomag's Leaky Bucket headers and backs off automatically on 429
• Exponential back-off retry for transient 429 / 5xx failures (configurable retries and factor)
• Connection pooling via httpx.AsyncClient (keep-alive, max connections)
• Fully async — non-blocking from transport to tool handler
• Two MCP resources — gomag://health and gomag://rate-limit for observability
• Zero secrets in code — all credentials come from environment variables

Requirements

• Python ≥ 3.10
• A Gomag store with Public API access enabled
• Your API Key and Shop URL from the Gomag admin panel

Installation

From source (recommended while in beta)

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 .

Using pip (once published)

pip install gomag-mcp

Configuration

All configuration is via environment variables (prefix GOMAG_). Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Required

Optional

Integration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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

Run manually

# 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

Available Tools

Products (/api/v1/product/)

Categories (/api/v1/category/)

Orders (/api/v1/order/)

Customers (/api/v1/customer/)

Shipping / AWB (/api/v1/awb/)

AWB = Air Waybill — the tracking/shipping label used by Romanian courier services.

Invoices (/api/v1/invoice/)

Attributes (/api/v1/attribute/)

Reviews (/api/v1/review/)

Wishlist (/api/v1/wishlist/)

Store Reference Data

MCP Resources

Two read-only resources are exposed for observability:

Audit Logging

Every tool call — success or failure — writes one JSON Lines record to gomag_audit.jsonl (and optionally stderr). The file rotates automatically at 10 MB (5 backups kept by default).

Log record schema

{
  "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
}

On error, event_type is "tool_error", success is false, and error_message contains the exception text.

Sensitive field redaction

The following parameter names are always replaced with ***REDACTED*** in audit records, regardless of case:

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

Rate Limiting

The Gomag API implements a Leaky Bucket algorithm applied per shop across all API access.

Response headers (present on every response until the limit is reached):

This server:

1. Parses all six headers after every request
2. Exposes the latest values via gomag://rate-limit
3. On a 429 response, waits at least 1 second before the first retry, then uses exponential back-off for subsequent retries
4. On 5xx responses, uses pure exponential back-off (factor × 2^attempt)

Gomag API Reference

The Gomag Public API is documented within the included Postman collection (Gomag Public API.postman_collection.json). Key details:

Authentication

All requests require the ApiShop header. Write operations (POST) additionally require the Apikey header.

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

Both values are obtained from your Gomag admin panel under Settings → API.

Request format

Base URL

https://api.gomag.ro

Response format

All endpoints return JSON. Paginated list endpoints include:

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

Multi-language fields

Products, categories, and attributes support localised names. Language codes follow ISO 639-1 (ro, en, hu, etc.) and are configured per shop:

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

Security

Password handling

The following tools accept plaintext passwords in their parameters:

Important notes:

• Passwords are transmitted to the Gomag API over HTTPS. Never call these tools over an unencrypted connection.
• Passwords are never written to audit logs — only the email field is logged for these calls.
• Do not pass plaintext passwords to an AI assistant in contexts where chat history is persisted or shared.

Audit log security

• The audit log file (gomag_audit.jsonl) contains API call metadata. Restrict file permissions appropriately.
• The startup log prints the absolute path to the audit file — check this to confirm where logs are written.
• .env files and *.jsonl log files are excluded from git via .gitignore.

Development

Running tests

pip install -e ".[dev]"
pytest

Tests use respx to mock HTTP responses — no live credentials required.

Project layout

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

Adding a new tool

1. Find (or create) the appropriate module in src/gomag_mcp/tools/
2. Add a function inside the register(mcp) function decorated with @mcp.tool()
3. Call get_context() to access the shared GomagClient and AuditLogger
4. Wrap the API call with async with ctx.audit.tool_call(...) — all logging is automatic

@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"]

License

MIT © 2026 florinel-chis