@coinrithm/mcp-trading 0.7.18 → 0.7.19

package/CHANGELOG.md

@@ -5,6 +5,25 @@ ships two binaries — `coinrithm-mcp` (the MCP server) and `coinrithm-agent` (t
 self-host agent runner) — versioned together. The CoinRithm **API contract** is
 versioned separately (see `openapi.yaml` `info.version`, currently `1.9.0`).
 
+## 0.7.19 (2026-10-16)
+
+MCP server:
+
+- The local stdio server starts without `COINRITHM_API_KEY` in data-only
+  mode, like the hosted server: `npx -y @coinrithm/mcp-trading` works with no
+  account. Keyless data tools (`pm_data_*`, `get_arena_*`,
+  `get_crypto_movers`) answer; every keyed tool returns the structured
+  `missing_api_key` result, which now also names `COINRITHM_API_KEY` for the
+  local server. `server.json` marks the key optional.
+- Upstream requests time out after 35 s and report `upstream_timeout`
+  instead of hanging the tool call.
+- Hosted HTTP entry: per-client admission (120 requests a minute) and an
+  in-flight cap (64), answered as JSON-RPC 429/503 with `Retry-After`; a stop
+  signal drains open requests for up to 8 s while `/healthz` answers 503;
+  `/health` and `/healthz` report `version`.
+
+The default surface stays at 41 tools. Generated against API contract 1.9.0.
+
 ## 0.7.18 (2026-10-15)
 
 MCP server:

package/README.md

@@ -44,10 +44,18 @@ This package ships two binaries:
 
 > **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
 
-## Version 0.7.17
-
-The default tool surface is unchanged at 41 tools. Two server-wide opt-in
-flags add tools that stay off unless enabled: the
+## Version 0.7.19
+
+The local server starts without `COINRITHM_API_KEY` in data-only mode, so
+`npx -y @coinrithm/mcp-trading` gives prediction-market and crypto data with
+no account; keyed tools return a structured `missing_api_key` result until a
+key is set. Upstream calls time out after 35 s (`upstream_timeout`). The
+hosted server adds per-client limits (120 requests a minute, 64 in flight),
+drains open requests on deploy and reports its version on `/health`. The
+default surface stays at 41 tools. See [CHANGELOG.md](./CHANGELOG.md).
+
+Version 0.7.17 kept the default tool surface at 41 tools. Two server-wide
+opt-in flags add tools that stay off unless enabled: the
 [PM paper v2 tools](#opt-in-pm-paper-v2-tools) for configured house keys and
 the [spot reference tool](#opt-in-spot-reference-tool).
 
@@ -95,7 +103,10 @@ for the exact opt-in policy and persistence contract.
 ## Quick start
 
 ```bash
-# Run the MCP server with your CoinRithm key (no install needed):
+# Prediction-market and crypto data only, no account or key needed:
+npx -y @coinrithm/mcp-trading
+
+# Add your CoinRithm key to enable paper trading (no install needed):
 COINRITHM_API_KEY=crk_live_… npx -y @coinrithm/mcp-trading
 ```
 
@@ -178,13 +189,13 @@ agent file.
 
 ## Configure (stdio)
 
-| Env var                                  | Required         | Default                     | Notes                                                                                     |
-| ---------------------------------------- | ---------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
-| `COINRITHM_API_KEY`                      | yes (stdio only) | —                           | A `crk_live_…` key from CoinRithm → Settings → API Keys. **Ignored by the HTTP entry.**    |
-| `COINRITHM_API_URL`                      | no               | `https://api.coinrithm.com` | Upstream base URL (live)                                                                  |
-| `PORT`                                   | no               | `8787`                      | HTTP entry only                                                                           |
-| `COINRITHM_PM_PAPER_V2_TOOLS_ENABLED`    | no               | off                         | `true` adds the [PM paper v2 tools](#opt-in-pm-paper-v2-tools) for configured house keys. |
-| `COINRITHM_SPOT_REFERENCE_TOOLS_ENABLED` | no               | off                         | `true` adds [`get_spot_reference`](#opt-in-spot-reference-tool).                          |
+| Env var                                  | Required        | Default                     | Notes                                                                                                                |
+| ---------------------------------------- | --------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `COINRITHM_API_KEY`                      | no (stdio only) | —                           | A `crk_live_…` key from CoinRithm → Settings → API Keys. Without it, data tools only. **Ignored by the HTTP entry.** |
+| `COINRITHM_API_URL`                      | no              | `https://api.coinrithm.com` | Upstream base URL (live)                                                                                             |
+| `PORT`                                   | no              | `8787`                      | HTTP entry only                                                                                                      |
+| `COINRITHM_PM_PAPER_V2_TOOLS_ENABLED`    | no              | off                         | `true` adds the [PM paper v2 tools](#opt-in-pm-paper-v2-tools) for configured house keys.                            |
+| `COINRITHM_SPOT_REFERENCE_TOOLS_ENABLED` | no              | off                         | `true` adds [`get_spot_reference`](#opt-in-spot-reference-tool).                                                     |
 
 ## Run
 

package/dist/client.d.ts

@@ -41,6 +41,7 @@ export type ProvenanceReport = {
     };
 };
 export declare const API_KEY_MINT_URL = "https://www.coinrithm.com/en/settings/api-keys";
+export declare const UPSTREAM_TIMEOUT_MS = 35000;
 export declare class CoinRithmClient {
     private readonly defaultApiKey?;
     private readonly baseUrl;

package/dist/client.js

@@ -27,12 +27,17 @@ export function log(...args) {
 function resolveBaseUrl() {
     return (process.env.COINRITHM_API_URL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, "");
 }
-// stdio path: a startup key is REQUIRED (single user).
+// stdio path (single user). The key is OPTIONAL since 2026-10-16 (audit):
+// without one the server starts in data-only mode, exactly like the hosted
+// server: keyless tools (pm_data_*, get_arena_*, get_crypto_movers) work and
+// every keyed tool returns the structured missing_api_key result. Requiring a
+// key blocked the one-line `npx -y @coinrithm/mcp-trading` data install.
 export function loadConfig() {
     const apiKey = process.env.COINRITHM_API_KEY?.trim();
     if (!apiKey) {
-        throw new Error("COINRITHM_API_KEY is not set. Mint a key in CoinRithm → Settings → API Keys " +
-            "and expose it to this MCP server as the COINRITHM_API_KEY environment variable.");
+        log("no COINRITHM_API_KEY: data-only mode. Keyless data tools work; paper-trading " +
+            "tools need a key from CoinRithm → Settings → API Keys.");
+        return { baseUrl: resolveBaseUrl() };
     }
     if (!apiKey.startsWith("crk_live_")) {
         log("warning: COINRITHM_API_KEY does not start with 'crk_live_' — it will likely be rejected.");
@@ -75,6 +80,28 @@ const traceFromBody = (body) => body && typeof body === "object" && "agentTrace"
 // Where a user mints an API key (Settings -> API Keys). Named in every
 // missing-key error so an assistant can tell its user where to go.
 export const API_KEY_MINT_URL = "https://www.coinrithm.com/en/settings/api-keys";
+// Upstream ceiling for every API call (audit 2026-10-16: none existed, so a
+// hung upstream held the tool call open until undici's ~300 s default).
+// Measured before choosing it: the slowest successful hosted calls in 24 h
+// took 26-29 s (cold heavy reads), so 35 s cuts hangs without failing them.
+export const UPSTREAM_TIMEOUT_MS = 35_000;
+const upstreamFailure = (err) => {
+    const timedOut = err instanceof Error &&
+        (err.name === "TimeoutError" || err.name === "AbortError");
+    return {
+        ok: false,
+        status: 0,
+        data: timedOut
+            ? {
+                error: "upstream_timeout",
+                message: `CoinRithm API did not answer within ${UPSTREAM_TIMEOUT_MS / 1000} s. Retry shortly.`,
+            }
+            : {
+                error: "network_error",
+                message: err instanceof Error ? err.message : String(err),
+            },
+    };
+};
 export class CoinRithmClient {
     // Default key for the stdio (single-user) path. Undefined in the multi-user
     // HTTP path, where every call must pass a per-request `apiKey` override.
@@ -94,7 +121,8 @@ export class CoinRithmClient {
                     error: "missing_api_key",
                     message: "No API key for this request. Mint a free key at " +
                         `${API_KEY_MINT_URL}, then on the hosted MCP send ` +
-                        "`Authorization: Bearer crk_live_…`. Public data tools " +
+                        "`Authorization: Bearer crk_live_…`, or for the local server " +
+                        "set COINRITHM_API_KEY. Public data tools " +
                         "(pm_data_*, get_arena_*, get_crypto_movers) need no key.",
                 },
             };
@@ -120,18 +148,12 @@ export class CoinRithmClient {
                 method,
                 headers,
                 body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
             });
         }
         catch (err) {
             log(`network error calling ${method} ${path}:`, err);
-            return {
-                ok: false,
-                status: 0,
-                data: {
-                    error: "network_error",
-                    message: err instanceof Error ? err.message : String(err),
-                },
-            };
+            return upstreamFailure(err);
         }
         const text = await res.text();
         let data = text;
@@ -181,18 +203,12 @@ export class CoinRithmClient {
             res = await fetch(url.toString(), {
                 method: "GET",
                 headers: { Accept: "application/json" },
+                signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
             });
         }
         catch (err) {
             log(`network error calling GET ${path}:`, err);
-            return {
-                ok: false,
-                status: 0,
-                data: {
-                    error: "network_error",
-                    message: err instanceof Error ? err.message : String(err),
-                },
-            };
+            return upstreamFailure(err);
         }
         const text = await res.text();
         let data = text;

package/dist/http.d.ts

@@ -2,8 +2,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CoinRithmClient } from "./client.js";
 import { type CompletionLogger } from "./httpCompletion.js";
+import { type McpLimitOptions } from "./httpLimits.js";
+import { type DrainState } from "./httpShutdown.js";
 export declare const MALFORMED_MCP_LINK: RegExp;
 export declare function createHttpApp(client: CoinRithmClient, options?: {
     completionLogger?: CompletionLogger;
     createServer?: () => McpServer;
+    limits?: McpLimitOptions;
+    drain?: DrainState;
 }): import("express-serve-static-core").Express;

package/dist/http.js

@@ -43,12 +43,16 @@ import { CoinRithmClient, bearerFromHeader, loadHttpConfig, log, } from "./clien
 import { registerTools } from "./tools.js";
 import { SERVER_VERSION } from "./version.js";
 import { observeHttpCompletion, } from "./httpCompletion.js";
+import { createMcpAdmission } from "./httpLimits.js";
+import { installGracefulShutdown } from "./httpShutdown.js";
 // "/mcp" immediately followed by the markdown "](" of a pasted link, literal or
 // percent-encoded. Anything else under /mcp is not this family.
 export const MALFORMED_MCP_LINK = /^\/mcp(?:\]|%5d)(?:\(|%28)/i;
 // Factory permits isolated localhost SDK tests without opening a listener on import.
 export function createHttpApp(client, options = {}) {
     const app = express();
+    // Behind Cloudflare and Traefik (audit 2026-10-16: no limit existed).
+    const admission = createMcpAdmission(options.limits);
     const completions = new WeakMap();
     app.use((req, res, next) => {
         if (req.method === "POST" && /^\/mcp\/?$/i.test(req.path)) {
@@ -60,11 +64,16 @@ export function createHttpApp(client, options = {}) {
     // Lightweight, unauthenticated liveness probe (handy for Coolify/uptime checks).
     // Keep `/healthz` as the deployment contract and expose `/health` as a
     // compatibility alias for agents and generic uptime monitors.
+    // While a stop signal drains the process it answers 503, so the proxy and
+    // the image HEALTHCHECK stop sending new work here (httpShutdown.ts).
     app.get(["/health", "/healthz"], (_req, res) => {
-        res.json({
-            ok: true,
+        const draining = options.drain?.draining === true;
+        res.status(draining ? 503 : 200).json({
+            ok: !draining,
             service: "coinrithm-mcp",
             transport: "streamable-http",
+            version: SERVER_VERSION,
+            ...(draining ? { draining: true } : {}),
         });
     });
     // Self-describing landing for humans and validate-before-recommend agents.
@@ -129,7 +138,7 @@ export function createHttpApp(client, options = {}) {
             message: "This is a POST-only streamable-HTTP MCP endpoint. Connect with an MCP client, or GET / for service info.",
         });
     });
-    app.post(["/mcp", MALFORMED_MCP_LINK], async (req, res) => {
+    app.post(["/mcp", MALFORMED_MCP_LINK], admission, async (req, res) => {
         // Per-request auth: read THIS caller's key from the Authorization header,
         // or from Smithery's non-reserved forwarding header.
         // It is optional at the transport layer so registries can initialize the
@@ -180,12 +189,14 @@ export function createHttpApp(client, options = {}) {
 async function main() {
     const config = loadHttpConfig(); // no global key — keys arrive per request
     const client = new CoinRithmClient(config); // constructed WITHOUT a default key
-    const app = createHttpApp(client);
+    const drain = { draining: false };
+    const app = createHttpApp(client, { drain });
     const port = Number(process.env.PORT) || 8787;
-    app.listen(port, () => {
+    const listener = app.listen(port, () => {
         log(`HTTP MCP listening on :${port}/mcp (multi-user, per-request key). ` +
             `upstream=${config.baseUrl}. Paper only.`);
     });
+    installGracefulShutdown(listener, { state: drain, log });
 }
 if (process.argv[1] &&
     import.meta.url === pathToFileURL(process.argv[1]).href) {

package/dist/httpLimits.d.ts

@@ -0,0 +1,10 @@
+import type { NextFunction, Request, Response } from "express";
+export type McpLimitOptions = {
+    perClientPerMinute?: number;
+    maxInFlight?: number;
+    now?: () => number;
+};
+export declare const DEFAULT_PER_CLIENT_PER_MINUTE = 120;
+export declare const DEFAULT_MAX_IN_FLIGHT = 64;
+export declare function clientKey(req: Request): string;
+export declare function createMcpAdmission(options?: McpLimitOptions): (req: Request, res: Response, next: NextFunction) => void;

package/dist/httpLimits.js

@@ -0,0 +1,76 @@
+// Admission limits for the hosted multi-user MCP (POST /mcp).
+//
+// Audit 2026-10-16: POST /mcp had no rate limit and no concurrency cap, and
+// keyless pm_data_* tools reach the internal API directly (past Cloudflare),
+// so one anonymous client could drive unbounded load into the single-host API.
+// Measured before choosing the numbers (container logs, 24 h to 2026-10-16
+// 01:30 UTC): 3,861 requests, peak about 16 per minute across ALL clients.
+// A per-client allowance of 120 per minute (the API's own per-key baseline)
+// leaves ordinary agents untouched; the in-flight cap bounds a burst.
+//
+// In-memory and per-process on purpose: the service runs as one container.
+// No dependency is added for this (supply-chain surface of an npx package).
+export const DEFAULT_PER_CLIENT_PER_MINUTE = 120;
+export const DEFAULT_MAX_IN_FLIGHT = 64;
+const WINDOW_MS = 60_000;
+const firstHeader = (value) => {
+    const raw = Array.isArray(value) ? value[0] : value;
+    const first = raw?.split(",")[0]?.trim();
+    return first ? first : null;
+};
+// Behind Cloudflare and Traefik: Cloudflare's connecting-IP header names the
+// real client; X-Forwarded-For is the fallback; the socket address last.
+export function clientKey(req) {
+    return (firstHeader(req.headers["cf-connecting-ip"]) ??
+        firstHeader(req.headers["x-forwarded-for"]) ??
+        req.socket?.remoteAddress ??
+        "unknown");
+}
+const rpcError = (res, status, retryAfterSeconds, message) => {
+    res.setHeader("Retry-After", String(retryAfterSeconds));
+    res.status(status).json({
+        jsonrpc: "2.0",
+        error: { code: -32000, message, data: { retryAfterSeconds } },
+        id: null,
+    });
+};
+export function createMcpAdmission(options = {}) {
+    const perClient = options.perClientPerMinute ?? DEFAULT_PER_CLIENT_PER_MINUTE;
+    const maxInFlight = options.maxInFlight ?? DEFAULT_MAX_IN_FLIGHT;
+    const now = options.now ?? Date.now;
+    let windowStart = now();
+    let counts = new Map();
+    let inFlight = 0;
+    return function mcpAdmission(req, res, next) {
+        const t = now();
+        if (t - windowStart >= WINDOW_MS) {
+            // Fixed window: dropping the whole map bounds memory to one minute of
+            // distinct clients.
+            windowStart = t;
+            counts = new Map();
+        }
+        const key = clientKey(req);
+        const used = (counts.get(key) ?? 0) + 1;
+        counts.set(key, used);
+        if (used > perClient) {
+            const retry = Math.max(1, Math.ceil((windowStart + WINDOW_MS - t) / 1000));
+            rpcError(res, 429, retry, `Rate limited: at most ${perClient} MCP requests per minute per client. Retry after ${retry} s.`);
+            return;
+        }
+        if (inFlight >= maxInFlight) {
+            rpcError(res, 503, 2, "Server busy: too many MCP requests in flight. Retry shortly.");
+            return;
+        }
+        inFlight += 1;
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            inFlight -= 1;
+        };
+        res.on("finish", release);
+        res.on("close", release);
+        next();
+    };
+}

package/dist/httpShutdown.d.ts

@@ -0,0 +1,13 @@
+import type { Server } from "node:http";
+export declare const SHUTDOWN_GRACE_MS = 8000;
+export type DrainState = {
+    draining: boolean;
+};
+export declare function installGracefulShutdown(server: Pick<Server, "close" | "closeAllConnections">, options: {
+    state: DrainState;
+    graceMs?: number;
+    log?: (...args: unknown[]) => void;
+    exit?: (code: number) => void;
+    signals?: NodeJS.Signals[];
+    onSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
+}): (signal: NodeJS.Signals) => void;

package/dist/httpShutdown.js

@@ -0,0 +1,34 @@
+export const SHUTDOWN_GRACE_MS = 8_000;
+export function installGracefulShutdown(server, options) {
+    const graceMs = options.graceMs ?? SHUTDOWN_GRACE_MS;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const say = options.log ?? (() => { });
+    let done = false;
+    const finish = (reason) => {
+        if (done)
+            return;
+        done = true;
+        say(`shutdown: ${reason}`);
+        exit(0);
+    };
+    const begin = (signal) => {
+        if (options.state.draining)
+            return;
+        options.state.draining = true;
+        say(`${signal}: draining, up to ${graceMs} ms for open requests`);
+        server.close(() => finish("all requests closed"));
+        const timer = setTimeout(() => {
+            server.closeAllConnections();
+            finish("grace period ended");
+        }, graceMs);
+        timer.unref?.();
+    };
+    const listen = options.onSignal ??
+        ((signal, handler) => {
+            process.once(signal, handler);
+        });
+    for (const signal of options.signals ?? ["SIGTERM", "SIGINT"]) {
+        listen(signal, () => begin(signal));
+    }
+    return begin;
+}

package/dist/index.js

@@ -6,7 +6,8 @@
 // paper account and place simulated trades using a user-minted API key.
 //
 // Config (env):
-//   COINRITHM_API_KEY  (required)  crk_live_… key minted in your profile.
+//   COINRITHM_API_KEY  (optional)  crk_live_… key minted in your profile.
+//                                  Without it: data-only mode (keyless tools).
 //   COINRITHM_API_URL  (optional)  base URL; defaults to https://api.coinrithm.com
 //
 // stdout is the JSON-RPC channel — we log ONLY to stderr.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinrithm/mcp-trading",
-  "version": "0.7.18",
+  "version": "0.7.19",
   "mcpName": "io.github.CoinRithm/mcp-trading",
   "description": "CoinRithm MCP server (coinrithm-mcp) and self-host agent runner (coinrithm-agent): keyless prediction-market data across 12 venues, plus paper trading of crypto spot, futures, and prediction markets with a user-minted API key.",
   "type": "module",