Frankencoin MCP Server

Real-time Frankencoin (ZCHF) protocol data for AI agents and developers. One read-only server, several ways to reach it — supply, prices, peg health, savings, minting positions, liquidation challenges, governance, insurance products, and historical analytics across every supported chain.

Public endpoint: https://mcp.frankencoin.com

No authentication. No API key required. Read-only.

Quick start

MCP (Claude Desktop / Cursor)

{
  "mcpServers": {
    "frankencoin": {
      "url": "https://mcp.frankencoin.com/mcp"
    }
  }
}

Then ask your assistant things like "What's the current state of the Frankencoin protocol?" or "How healthy is the ZCHF peg versus other CHF stablecoins?".

REST (curl / scripts)

# Full protocol snapshot — the best starting point
curl https://mcp.frankencoin.com/api/get_protocol_snapshot

# Market data + peg health
curl https://mcp.frankencoin.com/api/get_market_data

# Governance: pending minter applications
curl "https://mcp.frankencoin.com/api/get_governance?type=minters&status=pending"

# Positions with full on-chain detail
curl "https://mcp.frankencoin.com/api/get_positions?detail=true&limit=10"

# 30 days of protocol analytics
curl "https://mcp.frankencoin.com/api/get_analytics?type=time_series&days=30"

# Raw read-only GraphQL against the on-chain indexer
curl -X POST https://mcp.frankencoin.com/api/query_ponder \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ analyticDailyLogs(limit:3){ items { date totalSupply } } }"}'

Every REST response is a JSON envelope: { "ok": true, "tool": "<name>", "result": { … } }.

CLI

npx frankencoin-mcp snapshot
npx frankencoin-mcp market
npx frankencoin-mcp positions --detail --limit 10
npx frankencoin-mcp analytics --type trades --limit 5
npx frankencoin-mcp knowledge --topic governance
npx frankencoin-mcp ponder '{ equityTrades(limit:3){ items { kind trader shares } } }'

Discover everything

GET /health and GET /api are self-describing manifests, and GET /llms.txt is a compact, always-current guide generated from the live tool registry.

Tools

Organised by what the agent needs, not where the data comes from — one tool per responsibility, each aggregating from multiple sources internally.

Parameter details live in each tool's MCP inputSchema (via tools/list) and in GET /api.

Data sources

All aggregated server-side — callers never talk to these directly:

When an optional key is absent, the affected tool (get_market_data, get_dune_stats, get_risk) returns partial data plus a note rather than failing.

Self-hosting

No build step. Node ≥ 20, that's it.

git clone https://github.com/Frankencoin-ZCHF/frankencoin-mcp.git
cd frankencoin-mcp
npm install

node src/index.js --http     # HTTP mode (default port 3000)
node src/index.js            # stdio mode (for local MCP clients)
npm test                     # run the test suite

Health check: curl http://localhost:3000/health

Environment variables

Nothing is required to boot. Every variable is optional; missing secrets only degrade the tools that depend on them.

See src/config.js for the full list (cache, timeouts, session and query_ponder limits).

Architecture

Node.js ESM, no build step, no database — stateless between restarts and safe to restart anytime. Strictly layered, with one place that performs network I/O:

src/
  index.js            entrypoint — stdio vs --http, signals
  config.js           env read once, frozen; nothing required to boot
  cli.js              terminal client
  cache.js            in-memory TTL cache: single-flight + LRU bound
  lib/                pure utilities (number encoding, envelopes, errors, concurrency)
  upstream/           the ONLY layer that calls fetch() — one client per source
  services/           per-domain logic: compose upstreams, transform, shape output
  tools/              registry (zod-validated tool defs) + one dispatch path
  server/             http router, MCP registration, sessions, rate limiting, llms.txt
test/                 node:test suites (offline / hermetic)

Why it's fast: caching sits at the upstream boundary, so a single /prices/list fetch is shared across every tool that needs it, and concurrent identical fetches are coalesced (single-flight). Warm responses are ~1–2 ms.

Adding a tool

1. Add the definition (name, description, zod input, params, handler) to src/tools/registry.js.

2. Implement its logic in the relevant src/services/*.js, using an src/upstream/*.js client for any network call.

That's it — MCP, REST, /health, /api, and /llms.txt all pick it up automatically from the registry.

Security

Public, unauthenticated, read-only — hardened accordingly:

• query_ponder is AST-validated: read-only only (no mutations/subscriptions), no introspection or batched queries, with depth/field/alias/length and limit caps and a result-size cap.

• Rate limiting derives the client IP from the trusted proxy hop (never the attacker-controllable left-most X-Forwarded-For).

• Request-body caps (413), slowloris timeouts, session caps with idle/absolute expiry, prototype-pollution rejection, and a single error mapper that never leaks stack traces, upstream URLs, secrets, or file paths.

• Security headers and a strict CORS policy on every response.

Threat model and controls: docs/rebuild/SECURITY.md.

Deployment

Runs on Railway and auto-deploys from main via nixpacks — no build phase, no dashboard configuration, no required env vars. railway.toml sets startCommand = node src/index.js --http and health-checks /health.

License

MIT — Frankencoin Association