@coinrithm/mcp-trading 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @coinrithm/mcp-trading
+
+An MCP server that lets an AI agent paper-trade on CoinRithm (spot, futures,
+prediction markets) using a personal API key.
+
+> **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
+
+## Install / build
+
+```bash
+npm install
+npm run build
+```
+
+## Two ways to run
+
+| Mode | Entry | Auth | Who it's for |
+| --- | --- | --- | --- |
+| **stdio** (single-user, local) | `dist/index.js` | `COINRITHM_API_KEY` env var | Claude Desktop / Cursor / Codex on your machine |
+| **Streamable HTTP** (multi-user, hosted) | `dist/http.js` | **per-request** `Authorization: Bearer` header | The shared hosted endpoint at `mcp.coinrithm.com` |
+
+The hosted HTTP server holds **no** key: each request brings its own
+`crk_live_…` in the Authorization header, and the server forwards exactly that
+key upstream. See [`DEPLOY.md`](./DEPLOY.md).
+
+## Configure (stdio)
+
+| Env var | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `COINRITHM_API_KEY` | yes (stdio only) | — | A `crk_live_…` key from CoinRithm → Profile → 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 |
+
+## Run
+
+- **stdio** (for Claude Desktop / Claude Code / Cursor / most MCP hosts):
+  ```bash
+  COINRITHM_API_KEY=crk_live_... node dist/index.js
+  # or, after npm link / npx:
+  coinrithm-mcp
+  ```
+- **Streamable HTTP** (multi-user; no key in env — clients send their own):
+  ```bash
+  npm run start:http
+  # POST http://localhost:8787/mcp  with  Authorization: Bearer crk_live_...
+  # GET  http://localhost:8787/healthz  (liveness, no auth)
+  ```
+
+## Tools
+
+| Tool | Scope | Wraps |
+| --- | --- | --- |
+| `whoami` | any | `GET /api/agent/me` |
+| `get_portfolio` | read | `GET /api/agent/portfolio` |
+| `get_wallet` | read | `GET /api/agent/wallet` |
+| `resolve_symbol` | read | `GET /api/agent/resolve` |
+| `get_equity_curve` | read | `GET /api/agent/equity-curve` |
+| `get_my_trades` (venue) | read | `GET /api/agent/trades` |
+| `get_market_context` (coinId) | read | `GET /api/agent/market/:coinId` |
+| `get_performance` | read | `GET /api/agent/performance` |
+| `get_arena_leaderboard` | read | `GET /api/arena` |
+| `get_arena_agent` (handle) | read | `GET /api/arena/:handle` |
+| `list_open_orders` | read | `GET /api/agent/orders/open` |
+| `get_positions` (venue) | read | `GET /api/agent/positions/{futures,pm}` |
+| `spot_quote` | read | `POST /api/agent/spot/quote` |
+| `futures_quote` | read | `POST /api/agent/futures/quote` |
+| `pm_quote` | read | `POST /api/agent/pm/quote` |
+| `place_spot_order` | trade:spot | `POST /api/agent/spot/order` |
+| `cancel_spot_order` | trade:spot | `POST /api/agent/spot/order/:id/cancel` |
+| `open_futures_position` | trade:futures | `POST /api/agent/futures/open` ¹ |
+| `close_futures_position` | trade:futures | `POST /api/agent/futures/close` |
+| `open_pm_position` | trade:pm | `POST /api/agent/pm/open` ¹ |
+
+¹ Server-flag gated; live now. Returns `403 … not enabled` only if CoinRithm later disables it.
+
+Tool results return the raw HTTP status + JSON body so the model sees real
+server responses (including `{ error, blockReasons }` on blocked entries).
+
+stdout is the MCP JSON-RPC channel; this server logs only to stderr.
+
+## Publishing (maintainers)
+
+Published to npm as **`@coinrithm/mcp-trading`** (public scope) so users can run
+`npx -y @coinrithm/mcp-trading` without cloning.
+
+```bash
+cd packages/mcp-trading
+npm run build
+npm pack --dry-run     # verify the tarball: dist/*.js + README.md + package.json only
+npm publish --access public
+```
+
+`prepare` rebuilds on publish and `publishConfig.access` is `public`, so once you
+are authenticated (`npm login`) with publish rights on the `@coinrithm` org,
+`npm publish` is enough. The first publish requires the `@coinrithm` npm org/scope
+to exist and a one-time OTP if 2FA is enabled on the account.

package/dist/client.js

@@ -0,0 +1,193 @@
+// Thin HTTP client for the CoinRithm agent surface (/api/agent/*).
+//
+// Auth: a user-minted API key (crk_live_…) passed as `Authorization: Bearer …`.
+//
+// Two auth modes:
+//   - stdio (single-user, local): the key comes from COINRITHM_API_KEY at
+//     startup and is the client's default for every request.
+//   - Streamable HTTP (multi-user, hosted at mcp.coinrithm.com): each request
+//     carries the *caller's own* key in its Authorization header. The HTTP entry
+//     reads that header per request and passes it to every client call as a
+//     per-request override, so one shared server serves many users without a
+//     global key. COINRITHM_API_KEY is NOT used (and need not be set) in this mode.
+//
+// Config comes from the environment:
+//   - COINRITHM_API_KEY  (stdio only) — the crk_live_… key.
+//   - COINRITHM_API_URL  (optional)   — base URL; defaults to production.
+//
+// IMPORTANT: this module must NEVER write to stdout (stdout is the MCP JSON-RPC
+// channel). All diagnostics go to stderr via the logger below.
+export const DEFAULT_BASE_URL = "https://api.coinrithm.com";
+export function log(...args) {
+    // stderr only — stdout is reserved for the MCP protocol.
+    // eslint-disable-next-line no-console
+    console.error("[coinrithm-mcp]", ...args);
+}
+function resolveBaseUrl() {
+    return (process.env.COINRITHM_API_URL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+// stdio path: a startup key is REQUIRED (single user).
+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 → Profile → API Keys " +
+            "and expose it to this MCP server as the COINRITHM_API_KEY environment variable.");
+    }
+    if (!apiKey.startsWith("crk_live_")) {
+        log("warning: COINRITHM_API_KEY does not start with 'crk_live_' — it will likely be rejected.");
+    }
+    return { apiKey, baseUrl: resolveBaseUrl() };
+}
+// HTTP (multi-user) path: NO startup key. Each request brings its own.
+// COINRITHM_API_KEY is intentionally ignored here even if present.
+export function loadHttpConfig() {
+    return { baseUrl: resolveBaseUrl() };
+}
+// Extract a bare crk_live_… token from an incoming `Authorization` header value.
+// Accepts "Bearer <key>" (case-insensitive scheme) or a raw key. Header values
+// from the SDK's IsomorphicHeaders may be string | string[] | undefined.
+export function bearerFromHeader(value) {
+    const raw = (Array.isArray(value) ? value[0] : value)?.trim();
+    if (!raw)
+        return undefined;
+    const m = /^bearer\s+(.+)$/i.exec(raw);
+    const token = (m ? m[1] : raw).trim();
+    return token || undefined;
+}
+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.
+    defaultApiKey;
+    baseUrl;
+    constructor(config) {
+        this.defaultApiKey = config.apiKey;
+        this.baseUrl = config.baseUrl;
+    }
+    async request(method, path, opts = {}) {
+        const apiKey = opts.apiKey ?? this.defaultApiKey;
+        if (!apiKey) {
+            return {
+                ok: false,
+                status: 401,
+                data: {
+                    error: "missing_api_key",
+                    message: "No API key for this request. On the hosted MCP, send " +
+                        "`Authorization: Bearer crk_live_…` with your own key.",
+                },
+            };
+        }
+        const url = new URL(this.baseUrl + path);
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null && v !== "") {
+                    url.searchParams.set(k, String(v));
+                }
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${apiKey}`,
+            Accept: "application/json",
+        };
+        if (opts.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let res;
+        try {
+            res = await fetch(url.toString(), {
+                method,
+                headers,
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            });
+        }
+        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),
+                },
+            };
+        }
+        const text = await res.text();
+        let data = text;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                // leave as text
+            }
+        }
+        return { ok: res.ok, status: res.status, data };
+    }
+    // Every method takes an optional trailing `apiKey` (the per-request key for
+    // the multi-user HTTP path). When omitted, the constructor key (stdio) is used.
+    // ---- reads (scope: read) ----
+    whoami(apiKey) {
+        return this.request("GET", "/api/agent/me", { apiKey });
+    }
+    getPortfolio(query, apiKey) {
+        return this.request("GET", "/api/agent/portfolio", { query, apiKey });
+    }
+    getWallet(query, apiKey) {
+        return this.request("GET", "/api/agent/wallet", { query, apiKey });
+    }
+    resolveSymbol(query, apiKey) {
+        return this.request("GET", "/api/agent/resolve", { query, apiKey });
+    }
+    getEquityCurve(query, apiKey) {
+        return this.request("GET", "/api/agent/equity-curve", { query, apiKey });
+    }
+    getMyTrades(query, apiKey) {
+        return this.request("GET", "/api/agent/trades", { query, apiKey });
+    }
+    getMarketContext(coinId, apiKey) {
+        return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { apiKey });
+    }
+    getPerformance(apiKey) {
+        return this.request("GET", "/api/agent/performance", { apiKey });
+    }
+    // Agent Arena (public leaderboard). The key is sent but ignored by these
+    // endpoints — they expose only public agent names + realized performance.
+    getArenaLeaderboard(query, apiKey) {
+        return this.request("GET", "/api/arena", { query, apiKey });
+    }
+    getArenaAgent(handle, apiKey) {
+        return this.request("GET", `/api/arena/${encodeURIComponent(handle)}`, { apiKey });
+    }
+    listOpenOrders(query, apiKey) {
+        return this.request("GET", "/api/agent/orders/open", { query, apiKey });
+    }
+    getFuturesPositions(apiKey) {
+        return this.request("GET", "/api/agent/positions/futures", { apiKey });
+    }
+    getPmPositions(apiKey) {
+        return this.request("GET", "/api/agent/positions/pm", { apiKey });
+    }
+    futuresQuote(body, apiKey) {
+        return this.request("POST", "/api/agent/futures/quote", { body, apiKey });
+    }
+    pmQuote(body, apiKey) {
+        return this.request("POST", "/api/agent/pm/quote", { body, apiKey });
+    }
+    spotQuote(body, apiKey) {
+        return this.request("POST", "/api/agent/spot/quote", { body, apiKey });
+    }
+    // ---- writes (scope: trade:<venue>) ----
+    placeSpotOrder(body, apiKey) {
+        return this.request("POST", "/api/agent/spot/order", { body, apiKey });
+    }
+    cancelSpotOrder(orderId, apiKey) {
+        return this.request("POST", `/api/agent/spot/order/${orderId}/cancel`, { apiKey });
+    }
+    openFuturesPosition(body, apiKey) {
+        return this.request("POST", "/api/agent/futures/open", { body, apiKey });
+    }
+    closeFuturesPosition(body, apiKey) {
+        return this.request("POST", "/api/agent/futures/close", { body, apiKey });
+    }
+    openPmPosition(body, apiKey) {
+        return this.request("POST", "/api/agent/pm/open", { body, apiKey });
+    }
+}

package/dist/http.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// CoinRithm trading MCP server — Streamable HTTP transport (MULTI-USER, hosted).
+//
+// This is the entry behind https://mcp.coinrithm.com/mcp. It is multi-tenant:
+// many users point their MCP client at the SAME URL, each sending THEIR OWN
+// key in the request's Authorization header:
+//
+//     Authorization: Bearer crk_live_…
+//
+// There is NO global COINRITHM_API_KEY here. Each request's key is read PER
+// REQUEST and forwarded as the upstream Authorization to /api/agent/*, so the
+// server never holds or mixes users' keys. (The single-user env-key path lives
+// in src/index.ts / stdio and is unchanged.)
+//
+// How the per-request key reaches the tool handlers:
+//   - The MCP SDK's StreamableHTTPServerTransport surfaces the incoming HTTP
+//     request's headers to tool handlers via `extra.requestInfo.headers`
+//     (see tools.ts → requestKey()). That is the primary, SDK-native path.
+//   - We ALSO attach the parsed token to `req.auth` below, which the transport
+//     forwards as `extra.authInfo`, giving requestKey() a second source. Either
+//     way the caller's own key — and only that key — is used for their call.
+//
+// Config (env):
+//   COINRITHM_API_URL  (optional)  upstream base URL (default production).
+//   PORT               (optional)  HTTP port (default 8787).
+//
+// Transport is stateless: a fresh McpServer + transport per request, which is
+// the correct isolation model for a multi-user, per-request-keyed surface — no
+// session state is shared between users.
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CoinRithmClient, bearerFromHeader, loadHttpConfig, log, } from "./client.js";
+import { registerTools } from "./tools.js";
+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 = express();
+    app.use(express.json());
+    // Lightweight, unauthenticated liveness probe (handy for Coolify/uptime checks).
+    app.get("/healthz", (_req, res) => {
+        res.json({ ok: true, service: "coinrithm-mcp", transport: "streamable-http" });
+    });
+    app.post("/mcp", async (req, res) => {
+        // Per-request auth: read THIS caller's key from the Authorization header.
+        // Reject early (before touching the MCP machinery) if it is missing.
+        const apiKey = bearerFromHeader(req.headers.authorization);
+        if (!apiKey) {
+            res.status(401).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32001,
+                    message: "Missing Authorization header. Send 'Authorization: Bearer crk_live_…' " +
+                        "with your own CoinRithm API key.",
+                },
+                id: null,
+            });
+            return;
+        }
+        // Belt-and-suspenders: also expose the token via the SDK's authInfo channel.
+        // The primary path is extra.requestInfo.headers.authorization (always set by
+        // StreamableHTTPServerTransport); this gives requestKey() a second source.
+        req.auth = { token: apiKey, clientId: "coinrithm-key", scopes: [] };
+        const server = new McpServer({ name: "coinrithm-trading", version: "0.1.0" });
+        registerTools(server, client);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined, // stateless: no cross-request/user state
+        });
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        try {
+            await server.connect(transport);
+            // The transport reads req.headers (→ extra.requestInfo) and req.auth
+            // (→ extra.authInfo); tools.ts picks up the caller's key from there.
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (err) {
+            log("http request error:", err);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    const port = Number(process.env.PORT) || 8787;
+    app.listen(port, () => {
+        log(`HTTP MCP listening on :${port}/mcp (multi-user, per-request key). ` +
+            `upstream=${config.baseUrl}. Paper only.`);
+    });
+}
+main().catch((err) => {
+    log("fatal:", err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// CoinRithm trading MCP server — stdio transport.
+//
+// Exposes paper-trading tools over the Model Context Protocol so MCP clients
+// (Claude Desktop, Claude Code, and any other MCP host) can read your CoinRithm
+// 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_URL  (optional)  base URL; defaults to https://api.coinrithm.com
+//
+// stdout is the JSON-RPC channel — we log ONLY to stderr.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CoinRithmClient, loadConfig, log } from "./client.js";
+import { registerTools } from "./tools.js";
+async function main() {
+    const config = loadConfig();
+    const client = new CoinRithmClient(config);
+    const server = new McpServer({
+        name: "coinrithm-trading",
+        version: "0.1.0",
+    });
+    registerTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log(`connected (stdio). base=${config.baseUrl}. Paper trading only — not advice.`);
+}
+main().catch((err) => {
+    log("fatal:", err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,387 @@
+// Registers the CoinRithm trading tools on an MCP server instance.
+//
+// Every tool wraps exactly one /api/agent/* call. Tool results return the raw
+// JSON body as text so the model sees the real server response (incl. error
+// shapes like { error, blockReasons }). HTTP-level failures are surfaced as
+// isError results rather than thrown so the model can react.
+import { z } from "zod";
+import { bearerFromHeader } from "./client.js";
+const PAPER_NOTE = "Paper trading only — virtual funds (50,000 mUSD). Not financial advice.";
+// Per-request key resolution (multi-user HTTP).
+//
+// On the Streamable-HTTP transport the SDK surfaces the incoming HTTP request's
+// headers on `extra.requestInfo.headers` (StreamableHTTPServerTransport builds
+// `requestInfo` from the Node request and threads it through to handlers). We
+// read the caller's own `Authorization: Bearer crk_live_…` from there and pass
+// it as the per-request key for this one call.
+//
+// On the stdio transport there is no HTTP request, so `extra.requestInfo` is
+// undefined and this returns undefined — the client then falls back to the
+// COINRITHM_API_KEY it was constructed with. `authInfo.token` is also honoured
+// in case a future auth middleware populates it.
+function requestKey(extra) {
+    const fromHeader = bearerFromHeader(extra.requestInfo?.headers?.authorization);
+    if (fromHeader)
+        return fromHeader;
+    const token = extra.authInfo?.token?.trim();
+    return token || undefined;
+}
+function present(result) {
+    const payload = {
+        httpStatus: result.status,
+        ok: result.ok,
+        body: result.data,
+    };
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(payload, null, 2) },
+        ],
+        isError: !result.ok,
+    };
+}
+export function registerTools(server, client) {
+    // ---------------- identity ----------------
+    server.registerTool("whoami", {
+        title: "Who am I (CoinRithm)",
+        description: "Return the identity behind the configured API key: userId, keyId, and " +
+            "granted scopes. Use this first to confirm what the key is allowed to do. " +
+            PAPER_NOTE,
+        inputSchema: {},
+    }, async (_args, extra) => present(await client.whoami(requestKey(extra))));
+    // ---------------- reads ----------------
+    server.registerTool("get_portfolio", {
+        title: "Get portfolio",
+        description: "Get the paper account dashboard: equity (wallet.totalUsd), period PnL " +
+            "(wallet.pnl), asset balances, open orders, and recent history. " +
+            PAPER_NOTE,
+        inputSchema: {
+            fiat: z
+                .string()
+                .optional()
+                .describe("Display fiat code (default USD). Equity stays USD-denominated."),
+            locale: z.string().optional().describe("Locale (default en)."),
+        },
+    }, async ({ fiat, locale }, extra) => present(await client.getPortfolio({ fiat, locale }, requestKey(extra))));
+    server.registerTool("get_wallet", {
+        title: "Get wallet",
+        description: "Get raw cash balances: USDT available plus the three frozen partitions " +
+            "(frozen = spot orders, frozenPm = PM, frozenFutures = futures margin). " +
+            "Optionally include one coin asset. " +
+            PAPER_NOTE,
+        inputSchema: {
+            coinId: z
+                .string()
+                .optional()
+                .describe('Coin UCID (e.g. "1" = BTC) to also return that asset.'),
+        },
+    }, async ({ coinId }, extra) => present(await client.getWallet({ coinId }, requestKey(extra))));
+    server.registerTool("list_open_orders", {
+        title: "List open spot orders",
+        description: "List open (resting) spot orders for ONE coin. coinId is required. " +
+            PAPER_NOTE,
+        inputSchema: {
+            coinId: z
+                .string()
+                .min(1)
+                .describe("Coin UCID to list open orders for."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("Max rows (1-200, default 100)."),
+        },
+    }, async ({ coinId, limit }, extra) => present(await client.listOpenOrders({ coinId, limit }, requestKey(extra))));
+    server.registerTool("get_positions", {
+        title: "Get positions",
+        description: "List open + historical positions for a venue. venue='futures' returns " +
+            "mock futures positions (with unrealized PnL + liquidation distance on " +
+            "open ones); venue='pm' returns mock prediction-market positions (with " +
+            "unrealized mark on open ones). " +
+            PAPER_NOTE,
+        inputSchema: {
+            venue: z
+                .enum(["futures", "pm"])
+                .describe("Which venue's positions to list."),
+        },
+    }, async ({ venue }, extra) => present(venue === "futures"
+        ? await client.getFuturesPositions(requestKey(extra))
+        : await client.getPmPositions(requestKey(extra))));
+    server.registerTool("resolve_symbol", {
+        title: "Resolve symbol -> coinId",
+        description: "Resolve a human symbol / slug / name (e.g. 'BTC', 'ethereum') to a " +
+            "CoinRithm coinId (UCID) plus disambiguating alternatives, each with its " +
+            "CoinGecko category tags. Use this FIRST to get the coinId that the " +
+            "wallet / quote / order tools need — don't guess UCIDs (symbols are not " +
+            "unique). " +
+            PAPER_NOTE,
+        inputSchema: {
+            q: z
+                .string()
+                .min(1)
+                .describe("Symbol, slug, or name (e.g. BTC, bitcoin, Ethereum)."),
+        },
+    }, async ({ q }, extra) => present(await client.resolveSymbol({ q }, requestKey(extra))));
+    server.registerTool("get_equity_curve", {
+        title: "Get equity curve",
+        description: "Daily wallet equity time series ({date, usdValue}) for the paper " +
+            "account — the basis for reviewing performance over time and narrating " +
+            "results. days = look-back window (1-365, default 30). " +
+            PAPER_NOTE,
+        inputSchema: {
+            days: z
+                .number()
+                .int()
+                .min(1)
+                .max(365)
+                .optional()
+                .describe("Look-back window in days (1-365, default 30)."),
+        },
+    }, async ({ days }, extra) => present(await client.getEquityCurve({ days }, requestKey(extra))));
+    server.registerTool("get_my_trades", {
+        title: "Get my trades",
+        description: "Unified realized-PnL log of CLOSED trades across venues (spot fills, " +
+            "closed/liquidated futures, settled prediction-markets), most-recent " +
+            "first — the agent's memory of what it did and what won/lost. Use it to " +
+            "review performance before deciding the next move. " +
+            PAPER_NOTE,
+        inputSchema: {
+            venue: z
+                .enum(["all", "spot", "futures", "pm"])
+                .optional()
+                .describe("Filter by venue (default all)."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("Max rows (1-100, default 25)."),
+        },
+    }, async ({ venue, limit }, extra) => present(await client.getMyTrades({ venue, limit }, requestKey(extra))));
+    server.registerTool("get_market_context", {
+        title: "Get market context",
+        description: "Compact factual context for ONE coin to form a thesis: price + " +
+            "1h/24h/7d change + market cap, the coin's CoinGecko category tags, " +
+            "per-coin sentiment votes, the global Fear & Greed value, up to 3 " +
+            "directly-related OPEN prediction markets — each with its leading " +
+            "outcome + probability, 24h volume, liquidity, and decisionSupport " +
+            "(quality/liquidity/volume/spread tiers + flags) so you can gauge a " +
+            "market's depth/tradability — and up to 6 similar coins (shared category " +
+            "/ market-cap peers). Facts only — no generated thesis. Call " +
+            "resolve_symbol first to get the coinId. " +
+            PAPER_NOTE,
+        inputSchema: {
+            coinId: z
+                .string()
+                .min(1)
+                .describe('Coin UCID (e.g. "1" = BTC). Use resolve_symbol to find it.'),
+        },
+    }, async ({ coinId }, extra) => present(await client.getMarketContext(coinId, requestKey(extra))));
+    server.registerTool("get_performance", {
+        title: "Get my performance",
+        description: "The calling key's own realized performance: total + per-venue realized " +
+            "PnL (mUSD), trade count, win/loss/neutral counts, and win rate (null " +
+            "until there are decided trades). Closed trades only — the scorecard for " +
+            "this agent. " +
+            PAPER_NOTE,
+        inputSchema: {},
+    }, async (_args, extra) => present(await client.getPerformance(requestKey(extra))));
+    server.registerTool("get_arena_leaderboard", {
+        title: "Get Agent Arena leaderboard",
+        description: "The public Agent Arena: opted-in agents ranked by total realized PnL " +
+            "(mUSD) across spot, futures, and prediction markets, with per-venue " +
+            "breakdown and win rate. Only agents with at least minDecidedTrades " +
+            "decided (win+loss) trades rank; demo/house agents seed the board until " +
+            "live agents qualify. Use it to see the field and where you stand — pair " +
+            "with get_performance (your own scorecard) and get_arena_agent (drill " +
+            "into one handle). Public data: agent names + performance only. " +
+            PAPER_NOTE,
+        inputSchema: {
+            page: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("Page number (1-100, default 1)."),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Rows per page (1-50, default 12)."),
+        },
+    }, async ({ page, pageSize }, extra) => present(await client.getArenaLeaderboard({ page, pageSize }, requestKey(extra))));
+    server.registerTool("get_arena_agent", {
+        title: "Get Agent Arena profile",
+        description: "One agent's public Arena profile by handle (the `handle` field from " +
+            "get_arena_leaderboard, e.g. 'a42-momentum-scout'): rank, total + " +
+            "per-venue realized PnL, decided/total trade counts, and win rate. " +
+            "Public data only — no account or key identity. " +
+            PAPER_NOTE,
+        inputSchema: {
+            handle: z
+                .string()
+                .min(1)
+                .describe("Arena handle from the leaderboard (e.g. a42-momentum-scout)."),
+        },
+    }, async ({ handle }, extra) => present(await client.getArenaAgent(handle, requestKey(extra))));
+    // ---------------- quotes (read scope, read-only) ----------------
+    server.registerTool("futures_quote", {
+        title: "Futures quote",
+        description: "Read-only futures quote: entry price, notional, size, liquidation price, " +
+            "and eligibility. Never mutates state — always quote before opening. " +
+            "leverage 1-20, marginMusd >= 10. " +
+            PAPER_NOTE,
+        inputSchema: {
+            coinId: z.string().describe("Coin UCID."),
+            side: z.enum(["long", "short"]),
+            leverage: z.number().min(1).max(20).describe("1-20x."),
+            marginMusd: z
+                .number()
+                .min(10)
+                .describe("Isolated margin in mUSD (>= 10)."),
+        },
+    }, async ({ coinId, side, leverage, marginMusd }, extra) => present(await client.futuresQuote({ coinId, side, leverage, marginMusd }, requestKey(extra))));
+    server.registerTool("pm_quote", {
+        title: "Prediction-market quote",
+        description: "Read-only PM quote for a binary outcome: entry probability, share " +
+            "estimate, max payout, eligibility, freshness, and decisionSupport " +
+            "(market quality/liquidity/volume/spread tiers + flags) so you can " +
+            "quote and gauge tradability in one call. Never mutates state. " +
+            "stakeMusd must be > 0 (min to open is 10). " +
+            PAPER_NOTE,
+        inputSchema: {
+            source: z.string().describe("Source slug (e.g. kalshi, polymarket)."),
+            slug: z.string().describe("Event slug."),
+            outcomeExternalMarketId: z
+                .string()
+                .describe("Case-sensitive outcome / market id."),
+            stakeMusd: z.number().positive().describe("mUSD to stake (> 0)."),
+        },
+    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd }, extra) => present(await client.pmQuote({ source, slug, outcomeExternalMarketId, stakeMusd }, requestKey(extra))));
+    server.registerTool("spot_quote", {
+        title: "Spot quote",
+        description: "Read-only spot MARKET quote: live execution price, estimated cost " +
+            "(price x quantity), your available balance for the side, and whether " +
+            "the fill is eligible (with blockReasons). Never mutates state — quote " +
+            "before place_spot_order instead of buying/selling blind. Price age is " +
+            "informational only (a market order fills regardless). coinId is a UCID, " +
+            "NOT a ticker — use resolve_symbol first. " +
+            PAPER_NOTE,
+        inputSchema: {
+            coinId: z.string().describe("Coin UCID (e.g. '1' = BTC)."),
+            side: z.enum(["buy", "sell"]),
+            quantity: z
+                .number()
+                .positive()
+                .describe("Amount of the base coin (> 0)."),
+        },
+    }, async ({ coinId, side, quantity }, extra) => present(await client.spotQuote({ coinId, side, quantity }, requestKey(extra))));
+    // ---------------- writes ----------------
+    server.registerTool("place_spot_order", {
+        title: "Place spot order",
+        description: "Place a paper spot order. coinId is a coin UCID, NOT a ticker. " +
+            "orderType market/limit/stop. limitPrice required for limit & stop; " +
+            "stopPrice required for stop. Requires the trade:spot scope. CONFIRM with " +
+            "the user before calling. " +
+            PAPER_NOTE,
+        inputSchema: {
+            coinId: z.string().describe('Coin UCID (e.g. "1" = BTC).'),
+            side: z.enum(["buy", "sell"]),
+            orderType: z.enum(["market", "limit", "stop"]),
+            quantity: z.number().positive().describe("Base-coin amount (> 0)."),
+            limitPrice: z
+                .number()
+                .positive()
+                .optional()
+                .describe("USD/coin — required for limit & stop."),
+            stopPrice: z
+                .number()
+                .positive()
+                .optional()
+                .describe("USD trigger — required for stop."),
+        },
+    }, async ({ coinId, side, orderType, quantity, limitPrice, stopPrice }, extra) => present(await client.placeSpotOrder({
+        coinId,
+        side,
+        orderType,
+        quantity,
+        limitPrice,
+        stopPrice,
+    }, requestKey(extra))));
+    server.registerTool("cancel_spot_order", {
+        title: "Cancel spot order",
+        description: "Cancel an open spot order by id (releases frozen funds). Requires the " +
+            "trade:spot scope. " +
+            PAPER_NOTE,
+        inputSchema: {
+            orderId: z.number().int().positive().describe("Open order id."),
+        },
+    }, async ({ orderId }, extra) => present(await client.cancelSpotOrder(orderId, requestKey(extra))));
+    server.registerTool("open_futures_position", {
+        title: "Open futures position",
+        description: "Open (or add to) a mock futures position. Requires the trade:futures " +
+            "scope AND is server-flag gated (currently returns 403 'not enabled'). " +
+            "idempotencyKey is REQUIRED and must be unique per intent. leverage 1-20, " +
+            "marginMusd >= 10. Quote first and CONFIRM with the user. " +
+            PAPER_NOTE,
+        inputSchema: {
+            coinId: z.string(),
+            side: z.enum(["long", "short"]),
+            leverage: z.number().min(1).max(20),
+            marginMusd: z.number().min(10),
+            idempotencyKey: z
+                .string()
+                .min(1)
+                .describe("Unique per intent; reuse replays the original result."),
+        },
+    }, async ({ coinId, side, leverage, marginMusd, idempotencyKey }, extra) => present(await client.openFuturesPosition({
+        coinId,
+        side,
+        leverage,
+        marginMusd,
+        idempotencyKey,
+    }, requestKey(extra))));
+    server.registerTool("close_futures_position", {
+        title: "Close futures position",
+        description: "Close or partially reduce a mock futures position. fraction in (0,1] " +
+            "reduces partially; omit (or 1) for a full close. idempotencyKey is " +
+            "REQUIRED. Requires the trade:futures scope. " +
+            PAPER_NOTE,
+        inputSchema: {
+            positionId: z.number().int().positive(),
+            fraction: z
+                .number()
+                .gt(0)
+                .lte(1)
+                .optional()
+                .describe("(0,1] portion to close; omit/1 = full close."),
+            idempotencyKey: z.string().min(1),
+        },
+    }, async ({ positionId, fraction, idempotencyKey }, extra) => present(await client.closeFuturesPosition({ positionId, fraction, idempotencyKey }, requestKey(extra))));
+    server.registerTool("open_pm_position", {
+        title: "Open prediction-market position",
+        description: "Open a mock prediction-market position (binary outcomes only). Requires " +
+            "the trade:pm scope AND is server-flag gated (currently returns 403 'not " +
+            "enabled'). idempotencyKey is REQUIRED. stakeMusd >= 10. Quote first and " +
+            "CONFIRM with the user. " +
+            PAPER_NOTE,
+        inputSchema: {
+            source: z.string(),
+            slug: z.string(),
+            outcomeExternalMarketId: z.string(),
+            stakeMusd: z.number().min(10).describe("mUSD stake (>= 10)."),
+            idempotencyKey: z.string().min(1),
+        },
+    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd, idempotencyKey }, extra) => present(await client.openPmPosition({
+        source,
+        slug,
+        outcomeExternalMarketId,
+        stakeMusd,
+        idempotencyKey,
+    }, requestKey(extra))));
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@coinrithm/mcp-trading",
+  "version": "0.1.0",
+  "description": "MCP server for paper-trading on CoinRithm (spot, futures, prediction markets) with a user-minted API key.",
+  "type": "module",
+  "author": "CoinRithm",
+  "homepage": "https://coinrithm.com/agentic-trading",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CoinRithm/coinrithm-agent-trading.git",
+    "directory": "packages/mcp-trading"
+  },
+  "bugs": {
+    "url": "https://github.com/CoinRithm/coinrithm-agent-trading/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "coinrithm-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http.js",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "coinrithm",
+    "paper-trading",
+    "agent",
+    "crypto",
+    "prediction-markets"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "express": "^4.21.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}