@cloudcart/site-diagnostics

Read-only MCP server with 8 diagnostic tools scoped to one CloudCart merchant store. Used by the CloudCart support / debugging agents to investigate one store's state — errors, job queue, payments, shipping, emails, imports, exports — without ever issuing a write.

Tools

| Tool | Purpose | |---|---| | find_site_by_domain | Resolve a storefront domain to a numeric site_id. Call first when only the domain is known. | | search_site_errors | Recorded errors with source enum (exceptions / payment_errors / warnings / all) and mode (summary default, list for drill-down). | | inspect_site_queue | Job queue state per site; with a queue arg, also queue-global totals + FIFO position. | | search_site_payments | Payment-gateway request/response per payment_id. Embeds payment_status, provider, amount, currency, order_ref. | | search_site_shipping | Courier API request/response per order_id. | | search_site_emails | Outbound email log, incl. 2FA verification codes. | | search_site_imports | Import-task outcomes (total/created/updated/unchanged/errors). | | search_site_exports | Export-task status. |

All tools are strictly read-only by code (find / aggregate / count for Mongo; parameterised SELECT for MySQL). Lean by default — heavy fields (full stack traces, request/response payloads, PII) are gated behind include_trace / include_payload for drill-down only.

Wiring as an MCP server

{
  "mcpServers": {
    "site-diagnostics": {
      "command": "npx",
      "args": ["-y", "@cloudcart/site-diagnostics@latest"],
      "env": {
        "MONGO_LOGS_URI": "mongodb://logging:<password>@<host>:27017/logging?authSource=logging",
        "QUEUE_DB_URI": "mongodb://queue:<password>@<host>:27017/queue?authSource=queue",
        "ROUTER_DB_HOST": "<host>",
        "ROUTER_DB_USER": "router",
        "ROUTER_DB_PASSWORD": "<password>",
        "ROUTER_DB_NAME": "eu_cc_router"
      }
    }
  }
}

See .env.example for the full configuration reference, including guidance on internal vs public hosts and the directConnection=true flag for the queue replica set when connecting from outside the cluster.

Local install

npm install @cloudcart/site-diagnostics
# or run directly without install:
npx -y @cloudcart/site-diagnostics

For local development you can drop a .env file next to index.js (gitignored) instead of passing the values via the MCP host's env block.

Response shape

Responses are compact JSON (no pretty-print), default limit: 5, default since: "7d". A typical exploration flow (domain → site_id → grouped errors → list → single full trace) totals around 3,000 tokens.

Requirements

Node 18+.