protofire / safe-client-gateway / 41631416433

89%

Build Type

push

github

Committed by web-flow

Commit Message

feat(mcp): read-only MCP server for AI agents (#60)

Summary
Read-only MCP server for AI agents (feature 022, phase 1). It runs from the same image as the gateway, as a separate process: node dist/src/mcp-main.js. The regular gateway entry point and its modules are unchanged.

Agents (Claude Code, Codex, Cursor) connect over HTTP to /mcp and can read multisigs: chains, owners' multisigs, settings, balances, queue, history, transaction details, calldata decoding, proposers. Nothing is signed or proposed in this phase.

Changes
McpAppModule root and src/mcp-main.ts entry: no Postgres, AMQP, BullMQ; health checks Redis only (2 s timeout).
configureMcpApp: validates MCP_TRUST_PROXY_HOPS (default 1) and serves only /mcp, /mcp/usage.json, /health/live, /health/ready; every other path is 404.
/mcp: MCP 2026-07-28 (stateless) and 2025-11-25 on one endpoint via @modelcontextprotocol/server createMcpHandler.
Nine read tools reusing existing gateway services: list_chains, find_safes_by_owner, get_safe, get_balances, list_queued_transactions, list_transaction_history, get_transaction, decode_calldata, list_proposers. One error envelope (INVALID_INPUT, NOT_FOUND, FORBIDDEN, RATE_LIMITED, UPSTREAM_ERROR, INTERNAL_ERROR); untrusted-data notice on results; large decoded data and hex capped.
Sanctions blocklist: the same IBlocklistService check as REST BlocklistGuard, applied to safeAddress and to the account inside transaction ids; FORBIDDEN, logged without address or IP.
JSON-RPC batch arrays are rejected (400), so one POST is one call.
Limits: 60 requests/min per client IP (also on /mcp/usage.json); fan-out tools without chainIds 5/min per IP, at most 5 chainIds.
Logging: tool arguments, URLs, paths, cache keys and hex values are dropped or scrubbed; no IP or address in logs.
Usage: daily Redis counters per tool, chain, client label (claude-code, codex, cursor, other) and outcome, plus a HyperLogLog of salted client ids; written fire-and-forget.
GET /mcp/usage.json... (continued)

Coverage Stats

3625 of 4526 branches covered (80.09%)

Branch coverage included in aggregate %.

593 of 607 new or added lines in 30 files covered. (97.69%)

1 existing line in 1 file now uncovered.

15742 of 17161 relevant lines covered (91.73%)

497.27 hits per line