mercury402-mcp 0.1.1 → 0.1.2

package/README.md

@@ -129,8 +129,15 @@ claude mcp add mercury402 -- node /absolute/path/to/mercury402/mcp-server/dist/i
 npx -y mercury402-mcp --http   # http://127.0.0.1:3402/mcp (stateless, JSON responses)
 ```
 
-The HTTP endpoint has no authentication. It binds to `127.0.0.1` by default, and the server refuses to start
-in paid mode on a non-loopback `MCP_HTTP_HOST`.
+Stateless streamable HTTP: `POST /mcp` speaks MCP, `GET /` describes the server, and `GET /healthz` is a local
+health check. The HTTP endpoint has no authentication. It binds to `127.0.0.1` by default, checks the `Host`
+header against an allowlist (loopback names plus `MCP_HTTP_ALLOWED_HOSTS`), rate-limits per client IP and
+globally, and caps request bodies.
+
+Paid mode over HTTP is loopback-only. The server refuses to start with `MERCURY402_PAYER_PRIVATE_KEY` set
+together with a non-loopback `MCP_HTTP_HOST`, a public `MCP_HTTP_ALLOWED_HOSTS` entry, `MCP_HTTP_TRUST_PROXY`,
+or `MCP_PUBLIC_URL`. In paid mode it also rejects browser requests (any `Origin` header). To serve it publicly
+behind a reverse proxy in free mode, see [`deploy/HOSTED.md`](./deploy/HOSTED.md).
 
 ## Environment variables
 
@@ -141,6 +148,12 @@ in paid mode on a non-loopback `MCP_HTTP_HOST`.
 | `MERCURY402_API_URL` | `https://api.mercury402.com` | API base URL (`https://mercury402.uk` also works) |
 | `MERCURY402_TIMEOUT_MS` | `60000` | Per-request timeout (paid calls wait for on-chain settlement) |
 | `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `127.0.0.1` / `3402` | HTTP transport bind address (only with `--http`) |
+| `MCP_HTTP_ALLOWED_HOSTS` | unset | Comma-separated extra `Host` header names to accept (e.g. `mcp.example.com` behind a proxy). Loopback names are always accepted; anything else gets 403 |
+| `MCP_HTTP_TRUST_PROXY` | `false` | Rate-limit on Cloudflare's `CF-Connecting-IP` instead of the socket address. Enable only behind cloudflared/Cloudflare: the header is spoofable otherwise. `X-Forwarded-For` is never used |
+| `MCP_HTTP_RATE_LIMIT_PER_MIN` | `60` | `POST /mcp` requests per client IP per minute (`0` disables) |
+| `MCP_HTTP_GLOBAL_RATE_LIMIT_PER_MIN` | `600` | `POST /mcp` requests per minute across all clients (`0` disables) |
+| `MCP_HTTP_MAX_BODY_BYTES` | `65536` | Largest accepted request body; larger gets 413 |
+| `MCP_PUBLIC_URL` | unset | Public `/mcp` URL that `GET /` advertises. Setting it marks the server as public, so paid mode refuses to start |
 
 ## Example tool calls
 
@@ -236,7 +249,8 @@ npm run generate:catalog    # regenerate src/catalog.json after changing ../src/
 npm pack --dry-run          # inspect the publish tarball
 ```
 
-The endpoint catalog (`src/catalog.json`) is generated from the API source in this repo (`src/pricing.js`,
-`src/new-routes.js`, `src/ai-routes.js`, plus descriptions mirrored from `src/server.js`). A test fails if it
-drifts from `src/pricing.js`. `tsc` bakes the catalog into `dist/catalog.json`, so the published package never
-reads the repo at runtime; `prepublishOnly` regenerates the catalog, rebuilds, and runs the tests.
+The endpoint catalog (`src/catalog.json`) is generated from `../src/catalog.js`, the same module that builds the
+API's JSON manifest and `/llms.txt` (it reads `src/pricing.js`, `src/new-routes.js` and `src/ai-routes.js`). Tests
+in both packages fail if it drifts from `src/pricing.js`. `tsc` bakes the catalog into `dist/catalog.json`, so the
+published package never reads the repo at runtime; `prepublishOnly` regenerates the catalog, rebuilds, and runs the
+tests.

package/dist/config.js

@@ -7,8 +7,25 @@ function num(value, fallback, name) {
         throw new Error(`${name} must be a non-negative number`);
     return n;
 }
+function bool(value, fallback, name) {
+    if (value === undefined || value.trim() === '')
+        return fallback;
+    const v = value.trim().toLowerCase();
+    if (['1', 'true', 'yes'].includes(v))
+        return true;
+    if (['0', 'false', 'no'].includes(v))
+        return false;
+    throw new Error(`${name} must be true or false`);
+}
+function list(value) {
+    return (value ?? '')
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+}
 export function loadConfig(env = process.env) {
     const key = env.MERCURY402_PAYER_PRIVATE_KEY?.trim();
+    const publicUrl = env.MCP_PUBLIC_URL?.trim();
     return {
         apiUrl: (env.MERCURY402_API_URL?.trim() || DEFAULT_API_URL).replace(/\/+$/, ''),
         payerPrivateKey: key ? key : undefined,
@@ -16,5 +33,11 @@ export function loadConfig(env = process.env) {
         timeoutMs: num(env.MERCURY402_TIMEOUT_MS, 60_000, 'MERCURY402_TIMEOUT_MS'),
         httpHost: env.MCP_HTTP_HOST?.trim() || '127.0.0.1',
         httpPort: num(env.MCP_HTTP_PORT, 3402, 'MCP_HTTP_PORT'),
+        httpAllowedHosts: list(env.MCP_HTTP_ALLOWED_HOSTS),
+        httpTrustProxy: bool(env.MCP_HTTP_TRUST_PROXY, false, 'MCP_HTTP_TRUST_PROXY'),
+        httpRateLimitPerMin: num(env.MCP_HTTP_RATE_LIMIT_PER_MIN, 60, 'MCP_HTTP_RATE_LIMIT_PER_MIN'),
+        httpGlobalRateLimitPerMin: num(env.MCP_HTTP_GLOBAL_RATE_LIMIT_PER_MIN, 600, 'MCP_HTTP_GLOBAL_RATE_LIMIT_PER_MIN'),
+        httpMaxBodyBytes: num(env.MCP_HTTP_MAX_BODY_BYTES, 64 * 1024, 'MCP_HTTP_MAX_BODY_BYTES'),
+        publicUrl: publicUrl ? publicUrl : undefined,
     };
 }

package/dist/http.js

@@ -0,0 +1,228 @@
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { CATALOG } from './catalog.js';
+import { createMercuryServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+// Streamable HTTP transport, stateless: a fresh McpServer + transport per POST /mcp.
+// Built to sit behind a reverse proxy (cloudflared) as a public, free-mode endpoint:
+// Host allowlist (DNS rebinding), per-IP + global rate limits, a body cap, and CORS
+// for browser-based MCP clients. Paid mode is loopback-only and refuses browsers.
+/** Bind addresses only the local machine can reach. */
+const LOOPBACK_BINDS = new Set(['127.0.0.1', '::1', 'localhost']);
+/** Host header names that mean "reached over loopback"; always accepted. */
+const LOOPBACK_HOSTNAMES = ['127.0.0.1', 'localhost', '[::1]'];
+/** Tools registered by createMercuryServer(), advertised by GET /. Tested against tools/list. */
+export const TOOL_NAMES = ['list_endpoints', 'get_endpoint_data'];
+const CORS_HEADERS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID',
+    'Access-Control-Expose-Headers': 'Mcp-Session-Id, Mcp-Protocol-Version',
+    'Access-Control-Max-Age': '86400',
+};
+/** Lowercased hostname of a Host header, without the port ("[::1]:3402" -> "[::1]"). */
+export function hostnameOf(hostHeader) {
+    const h = (hostHeader ?? '').trim().toLowerCase();
+    if (h.startsWith('[')) {
+        const end = h.indexOf(']');
+        return end === -1 ? h : h.slice(0, end + 1);
+    }
+    return h.split(':')[0];
+}
+/**
+ * Paid mode signs payments from a hot wallet, and HTTP has no auth: anyone who can
+ * reach the endpoint could spend it. So paid mode is allowed only on a loopback bind
+ * that nothing public points at.
+ */
+export function assertSafeHttpConfig(config, paid = !!config.payerPrivateKey) {
+    if (!paid)
+        return;
+    if (!LOOPBACK_BINDS.has(config.httpHost)) {
+        throw new Error('Refusing to serve paid mode over HTTP on a non-loopback host (MCP_HTTP_HOST). Use stdio or 127.0.0.1.');
+    }
+    const publicHost = config.httpAllowedHosts.map(hostnameOf).find((h) => !LOOPBACK_HOSTNAMES.includes(h));
+    if (publicHost) {
+        throw new Error(`Refusing to serve paid mode with a public MCP_HTTP_ALLOWED_HOSTS entry (${publicHost}): anyone who can reach it could spend the payer wallet.`);
+    }
+    if (config.httpTrustProxy) {
+        throw new Error('Refusing to serve paid mode with MCP_HTTP_TRUST_PROXY: a proxy in front of the server means others can reach it.');
+    }
+    if (config.publicUrl) {
+        throw new Error('Refusing to serve paid mode with MCP_PUBLIC_URL set: a public endpoint must run in free mode.');
+    }
+}
+/** Fixed-window counter per key. take() returns 0 when allowed, else seconds until the window resets. */
+export class FixedWindowLimiter {
+    limit;
+    windowMs;
+    now;
+    maxKeys;
+    hits = new Map();
+    constructor(limit, windowMs = 60_000, now = Date.now, maxKeys = 10_000) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+        this.now = now;
+        this.maxKeys = maxKeys;
+    }
+    take(key) {
+        if (this.limit <= 0)
+            return 0;
+        const t = this.now();
+        let entry = this.hits.get(key);
+        if (!entry || t - entry.start >= this.windowMs) {
+            if (!entry && this.hits.size >= this.maxKeys)
+                this.prune(t);
+            entry = { start: t, count: 0 };
+            this.hits.set(key, entry);
+        }
+        if (entry.count >= this.limit)
+            return Math.max(1, Math.ceil((entry.start + this.windowMs - t) / 1000));
+        entry.count++;
+        return 0;
+    }
+    prune(t) {
+        for (const [k, e] of this.hits)
+            if (t - e.start >= this.windowMs)
+                this.hits.delete(k);
+        // Still full of live windows: drop them rather than grow without bound. The global limiter still applies.
+        if (this.hits.size >= this.maxKeys)
+            this.hits.clear();
+    }
+}
+/**
+ * Client IP for rate limiting. Behind cloudflared every connection comes from 127.0.0.1,
+ * so with trustProxy the CF-Connecting-IP header (set by Cloudflare's edge) is used.
+ * X-Forwarded-For is deliberately ignored: its first entry is client-controlled.
+ */
+export function clientIp(req, trustProxy) {
+    if (trustProxy) {
+        const cf = req.headers['cf-connecting-ip'];
+        if (typeof cf === 'string' && cf.trim())
+            return cf.trim();
+    }
+    return req.socket.remoteAddress ?? 'unknown';
+}
+class BodyTooLargeError extends Error {
+}
+async function readBody(req, maxBytes) {
+    const declared = Number(req.headers['content-length']);
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw new BodyTooLargeError();
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > maxBytes)
+            throw new BodyTooLargeError();
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function rpcError(code, message) {
+    return { jsonrpc: '2.0', error: { code, message }, id: null };
+}
+function send(res, status, body, opts = {}) {
+    res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', ...opts.headers });
+    res.end(opts.head ? undefined : JSON.stringify(body));
+}
+export function createHttpServer(config, options = {}) {
+    const deps = options.deps ?? {};
+    const paid = !!(deps.payer ?? config.payerPrivateKey);
+    assertSafeHttpConfig(config, paid);
+    const log = options.log ?? (() => { });
+    const allowedHosts = new Set([...LOOPBACK_HOSTNAMES, ...config.httpAllowedHosts.map(hostnameOf)]);
+    const perIp = new FixedWindowLimiter(config.httpRateLimitPerMin, 60_000, options.now);
+    const global = new FixedWindowLimiter(config.httpGlobalRateLimitPerMin, 60_000, options.now);
+    const stats = { mcp_requests: 0, rate_limited: 0, rejected_host: 0, rejected_origin: 0, too_large: 0 };
+    const info = {
+        name: 'mercury402-mcp',
+        server: SERVER_NAME,
+        version: SERVER_VERSION,
+        description: 'MCP server for Mercury402: discover and call pay-per-call financial data endpoints (x402, USDC on Base).',
+        transport: 'streamable-http',
+        stateless: true,
+        mcp_endpoint: config.publicUrl ?? '/mcp',
+        paid_mode: paid,
+        tools: [...TOOL_NAMES],
+        endpoint_count: CATALOG.count,
+        api_url: config.apiUrl,
+        local_install: 'npx -y mercury402-mcp',
+        docs: 'https://github.com/dudman1/mercury402/tree/master/mcp-server#readme',
+    };
+    async function handleMcp(req, res) {
+        const wait = perIp.take(clientIp(req, config.httpTrustProxy)) || global.take('*');
+        if (wait > 0) {
+            stats.rate_limited++;
+            return send(res, 429, rpcError(-32000, 'Too many requests'), { headers: { 'Retry-After': String(wait) } });
+        }
+        let body;
+        try {
+            const raw = await readBody(req, config.httpMaxBodyBytes);
+            body = raw ? JSON.parse(raw) : undefined;
+        }
+        catch (err) {
+            if (err instanceof BodyTooLargeError) {
+                stats.too_large++;
+                return send(res, 413, rpcError(-32000, `Request body exceeds ${config.httpMaxBodyBytes} bytes`), { headers: { Connection: 'close' } });
+            }
+            return send(res, 400, rpcError(-32700, 'Parse error'));
+        }
+        stats.mcp_requests++;
+        const server = createMercuryServer(config, deps);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        res.on('close', () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    }
+    async function handle(req, res) {
+        const method = req.method ?? 'GET';
+        const path = (req.url ?? '/').split('?')[0].replace(/\/+$/, '') || '/';
+        if (!allowedHosts.has(hostnameOf(req.headers.host))) {
+            stats.rejected_host++;
+            return send(res, 403, rpcError(-32000, 'Forbidden: Host not allowed'));
+        }
+        if (paid && req.headers.origin !== undefined) {
+            stats.rejected_origin++;
+            return send(res, 403, rpcError(-32000, 'Forbidden: browser (Origin) requests are refused in paid mode'));
+        }
+        if (!paid)
+            for (const [k, v] of Object.entries(CORS_HEADERS))
+                res.setHeader(k, v);
+        if (path === '/mcp') {
+            if (method === 'POST')
+                return handleMcp(req, res);
+            if (method === 'OPTIONS') {
+                res.writeHead(204).end();
+                return;
+            }
+            return send(res, 405, rpcError(-32000, 'Method not allowed: this server is stateless, use POST'), { headers: { Allow: 'POST, OPTIONS' } });
+        }
+        if (path === '/' || path === '/healthz') {
+            if (method === 'OPTIONS') {
+                res.writeHead(204).end();
+                return;
+            }
+            if (method !== 'GET' && method !== 'HEAD') {
+                return send(res, 405, { error: 'method_not_allowed' }, { headers: { Allow: 'GET, HEAD, OPTIONS' } });
+            }
+            // /healthz never calls the upstream API: it reports this process only.
+            const body = path === '/' ? info : { status: 'ok', version: SERVER_VERSION, paid_mode: paid, endpoint_count: CATALOG.count, stats };
+            return send(res, 200, body, { head: method === 'HEAD' });
+        }
+        return send(res, 404, { error: 'not_found', mcp_endpoint: '/mcp' });
+    }
+    const server = createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            log(`HTTP request failed: ${err instanceof Error ? err.message : String(err)}`);
+            if (!res.headersSent)
+                send(res, 500, rpcError(-32603, 'Internal error'));
+            else
+                res.end();
+        });
+    });
+    server.headersTimeout = 15_000;
+    server.requestTimeout = config.timeoutMs + 30_000;
+    return { server, stats };
+}

package/dist/index.js

@@ -1,56 +1,36 @@
 #!/usr/bin/env node
-import { createServer } from 'node:http';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { loadConfig } from './config.js';
+import { createHttpServer } from './http.js';
 import { createMercuryServer } from './server.js';
 // stdout carries the MCP protocol in stdio mode: log to stderr only, and never log config values.
 function log(msg) {
     process.stderr.write(`[mercury402-mcp] ${msg}\n`);
 }
-async function readJson(req) {
-    const chunks = [];
-    for await (const chunk of req)
-        chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf8');
-    return raw ? JSON.parse(raw) : undefined;
-}
-// Stateless streamable HTTP: a fresh server + transport per request.
 async function startHttp(config) {
-    // The HTTP endpoint has no auth: anyone who can reach it could spend the payer wallet.
-    const loopback = ['127.0.0.1', '::1', 'localhost'].includes(config.httpHost);
-    if (config.payerPrivateKey && !loopback) {
-        throw new Error('Refusing to serve paid mode over HTTP on a non-loopback host (MCP_HTTP_HOST). Use stdio or 127.0.0.1.');
-    }
-    const http = createServer(async (req, res) => {
-        if (!req.url?.startsWith('/mcp')) {
-            res.writeHead(404).end();
-            return;
-        }
-        if (req.method !== 'POST') {
-            res.writeHead(405, { Allow: 'POST' }).end();
-            return;
-        }
-        try {
-            const body = await readJson(req);
-            const server = createMercuryServer(config);
-            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
-            res.on('close', () => {
-                void transport.close();
-                void server.close();
-            });
-            await server.connect(transport);
-            await transport.handleRequest(req, res, body);
-        }
-        catch (err) {
-            log(`HTTP request failed: ${err instanceof Error ? err.message : String(err)}`);
-            if (!res.headersSent)
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32700, message: 'Bad request' }, id: null }));
-        }
+    const { server } = createHttpServer(config, { log });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(config.httpPort, config.httpHost, resolve);
     });
-    await new Promise((resolve) => http.listen(config.httpPort, config.httpHost, resolve));
-    log(`streamable HTTP listening on http://${config.httpHost}:${config.httpPort}/mcp`);
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : config.httpPort;
+    const hosts = ['loopback', ...config.httpAllowedHosts].join(', ');
+    const perIp = config.httpRateLimitPerMin ? `${config.httpRateLimitPerMin}/min per IP${config.httpTrustProxy ? ' (CF-Connecting-IP)' : ''}` : 'no per-IP limit';
+    const total = config.httpGlobalRateLimitPerMin ? `${config.httpGlobalRateLimitPerMin}/min total` : 'no global limit';
+    log(`streamable HTTP listening on http://${config.httpHost}:${port}/mcp; hosts: ${hosts}; ${perIp}, ${total}`);
+    // PM2 wait_ready: report "online" only once the port is bound.
+    if (typeof process.send === 'function')
+        process.send('ready');
+    // PM2 6.x stops apps with SIGINT, not SIGTERM: handle both. Requests are short (stateless JSON).
+    const shutdown = (signal) => {
+        log(`${signal} received, closing HTTP server`);
+        server.close(() => process.exit(0));
+        server.closeIdleConnections();
+        setTimeout(() => process.exit(0), 5_000).unref();
+    };
+    process.once('SIGINT', () => shutdown('SIGINT'));
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
 }
 async function main() {
     const config = loadConfig();

package/dist/server.js

@@ -4,7 +4,7 @@ import { CATALOG, resolveRequest } from './catalog.js';
 import { MercuryClient } from './client.js';
 import { createEvmPayer } from './payment.js';
 export const SERVER_NAME = 'mercury402';
-export const SERVER_VERSION = '0.1.1';
+export const SERVER_VERSION = '0.1.2';
 function json(value) {
     return JSON.stringify(value, null, 2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury402-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "MCP server for Mercury402: discover and call 78 pay-per-call (x402, USDC on Base) financial data endpoints — Treasury, FRED, forex, yield spreads, breakeven inflation, macro composites",
   "license": "MIT",
   "author": "Mercury402",