cito-mcp 0.2.7 → 0.3.0

package/README.md

@@ -382,6 +382,9 @@ CITO_API_KEY=cito_your_key_here node dist/index.js --http 8787
 # → http://127.0.0.1:8787/mcp
 ```
 
+Hosted (production): `https://api.citoapi.com/mcp`  
+Send the user's Cito key as `x-api-key`. Initialize and `list_capabilities` work without a key so Smithery can scan.
+
 ---
 
 ## Migration from 0.1 (auto-generated tools)

package/dist/envelope.js

@@ -201,10 +201,33 @@ export function sealEnvelope(envelope) {
         },
     };
 }
+/** Shared tool output for OpenAI plugin scan. Matches the JSON envelope. */
+export const ENVELOPE_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: true,
+    required: ['ok', 'meta'],
+    properties: {
+        ok: { type: 'boolean', description: 'true if the tool succeeded' },
+        data: { description: 'Result payload when ok is true; null on error' },
+        error: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+                code: { type: 'string' },
+                message: { type: 'string' },
+                recover: { type: 'array', items: { type: 'string' } },
+            },
+        },
+        meta: { type: 'object', additionalProperties: true },
+        pagination: { type: 'object', additionalProperties: true },
+        partial: { type: 'array', items: { type: 'object', additionalProperties: true } },
+    },
+};
 export function toMcpResult(envelope) {
     const sealed = sealEnvelope(envelope);
     return {
         content: [{ type: 'text', text: JSON.stringify(sealed, null, 2) }],
+        structuredContent: sealed,
         ...(sealed.ok ? {} : { isError: true }),
     };
 }

package/dist/http.js

@@ -0,0 +1,150 @@
+/**
+ * Hosted Streamable HTTP helpers.
+ *
+ * stdio is unchanged. This is only the public HTTPS surface:
+ * pathname matching, per-request API key, CORS, Smithery well-known docs.
+ * Never log the key.
+ */
+import { allTools } from './tools/index.js';
+import { toolListing } from './tools/types.js';
+import { PACKAGE_VERSION } from './version.js';
+export const MCP_PATH = '/mcp';
+export const MCP_CONFIG_PATH = '/.well-known/mcp-config';
+export const MCP_SERVER_CARD_PATH = '/.well-known/mcp/server-card.json';
+const CORS_HEADERS = {
+    'access-control-allow-origin': '*',
+    'access-control-allow-methods': 'GET, POST, DELETE, OPTIONS, HEAD',
+    'access-control-allow-headers': 'Content-Type, Accept, Authorization, x-api-key, x-cito-api-key, mcp-session-id, mcp-protocol-version, last-event-id',
+    'access-control-expose-headers': 'mcp-session-id, mcp-protocol-version',
+};
+export function requestPathname(url) {
+    if (!url)
+        return '';
+    try {
+        return new URL(url, 'http://127.0.0.1').pathname;
+    }
+    catch {
+        const q = url.indexOf('?');
+        return q === -1 ? url : url.slice(0, q);
+    }
+}
+function headerValue(headers, name) {
+    const raw = headers[name] ?? headers[name.toLowerCase()];
+    if (Array.isArray(raw))
+        return (raw[0] ?? '').trim();
+    return typeof raw === 'string' ? raw.trim() : '';
+}
+/**
+ * Per-request Cito key. Header first (Smithery x-from), then Bearer, then query.
+ * Query is last so nginx access logs are not the intended path.
+ */
+export function extractApiKey(req) {
+    const fromHeader = headerValue(req.headers, 'x-api-key') || headerValue(req.headers, 'x-cito-api-key');
+    if (fromHeader)
+        return fromHeader;
+    const auth = headerValue(req.headers, 'authorization');
+    const bearer = /^bearer\s+/i.exec(auth);
+    if (bearer) {
+        const token = auth.slice(bearer[0].length).trim();
+        if (token)
+            return token;
+    }
+    try {
+        const u = new URL(req.url ?? '', 'http://127.0.0.1');
+        return (u.searchParams.get('apiKey') ?? u.searchParams.get('CITO_API_KEY') ?? '').trim();
+    }
+    catch {
+        return '';
+    }
+}
+export function corsHeaders() {
+    return { ...CORS_HEADERS };
+}
+const MCP_ACCEPT = 'application/json, text/event-stream';
+const LEGACY_PROTOCOL = '2025-11-25';
+/** Node reads Accept from rawHeaders; mutating headers.accept alone is not enough. */
+export function setIncomingHeader(req, name, value) {
+    req.headers[name.toLowerCase()] = value;
+    const raw = req.rawHeaders;
+    if (!Array.isArray(raw))
+        return;
+    const lower = name.toLowerCase();
+    for (let i = 0; i < raw.length; i += 2) {
+        if (String(raw[i]).toLowerCase() === lower) {
+            raw[i + 1] = value;
+            return;
+        }
+    }
+    raw.push(name, value);
+}
+/** SDK 406s POSTs that omit MCP Accept. OpenAI's scanner often omits it. */
+export function ensureMcpAccept(headers, req) {
+    const raw = headers.accept ?? headers.Accept;
+    const value = Array.isArray(raw) ? raw.join(',') : typeof raw === 'string' ? raw : '';
+    const lower = value.toLowerCase();
+    if (lower.includes('application/json') && lower.includes('text/event-stream'))
+        return;
+    if (req)
+        setIncomingHeader(req, 'accept', MCP_ACCEPT);
+    else
+        headers.accept = MCP_ACCEPT;
+}
+/** OpenAI Scan Tools sends 2026-07-28; this SDK only speaks 2025-era. */
+export function rewriteMcpProtocolMessage(body) {
+    if (!body || typeof body !== 'object')
+        return body;
+    const msg = body;
+    const params = msg.params;
+    if (params && typeof params === 'object') {
+        const p = params;
+        if (p.protocolVersion === '2026-07-28')
+            p.protocolVersion = LEGACY_PROTOCOL;
+        const meta = p._meta;
+        if (meta && typeof meta === 'object') {
+            const m = meta;
+            const key = 'io.modelcontextprotocol/protocolVersion';
+            if (m[key] === '2026-07-28')
+                m[key] = LEGACY_PROTOCOL;
+        }
+    }
+    return body;
+}
+/** Smithery session config: API key as x-api-key, not OAuth. */
+export function mcpConfigSchema() {
+    return {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        title: 'Cito API',
+        description: 'Cito esports data for agents. Get a key at https://citoapi.com/dashboard',
+        required: ['apiKey'],
+        properties: {
+            apiKey: {
+                type: 'string',
+                title: 'Cito API Key',
+                description: 'Your Cito API key from https://citoapi.com/dashboard',
+                'x-from': { header: 'x-api-key' },
+            },
+        },
+    };
+}
+/** Scan fallback if Smithery cannot complete initialize. No OAuth. */
+export function mcpServerCard() {
+    return {
+        serverInfo: {
+            name: 'cito-mcp',
+            version: PACKAGE_VERSION,
+            title: 'Cito API',
+            websiteUrl: 'https://citoapi.com',
+        },
+        authentication: {
+            required: false,
+        },
+        tools: allTools.map(toolListing),
+        resources: [
+            { uri: 'cito://capabilities', name: 'cito-mcp capabilities summary' },
+            { uri: 'cito://llms.txt', name: 'Cito API agent context (llms.txt)' },
+            { uri: 'cito://openapi.json', name: 'Cito OpenAPI (public fetch)' },
+        ],
+        prompts: [],
+    };
+}

package/dist/index.js

@@ -5,9 +5,10 @@
  * 14 outcome tools (not OpenAPI mass-generation). stdio by default;
  * `--http <port>` serves a stateless Streamable HTTP endpoint.
  *
- * Required env: CITO_API_KEY (never logged).
- * Optional env: CITO_API_BASE (default https://api.citoapi.com/api/v1).
+ * Env: CITO_API_KEY (stdio / local). Hosted HTTP reads x-api-key per request.
+ * Optional: CITO_API_BASE, CITO_MCP_LISTEN (default 127.0.0.1).
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer as createHttpServer } from 'node:http';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -17,8 +18,9 @@ import { DEFAULT_API_BASE, log } from './client.js';
 import { errorEnvelope, toMcpResult } from './envelope.js';
 import { SERVER_INSTRUCTIONS } from './instructions.js';
 import { allTools, getTool } from './tools/index.js';
-import { runTool } from './tools/types.js';
+import { runTool, toolListing } from './tools/types.js';
 import { PACKAGE_VERSION } from './version.js';
+import { MCP_CONFIG_PATH, MCP_PATH, MCP_SERVER_CARD_PATH, corsHeaders, ensureMcpAccept, extractApiKey, rewriteMcpProtocolMessage, setIncomingHeader, mcpConfigSchema, mcpServerCard, requestPathname, } from './http.js';
 /**
  * Subcommands run and exit before any transport exists.
  *
@@ -31,7 +33,11 @@ if (process.argv[2] === 'install') {
     const { runInstall } = await import('./install.js');
     process.exit(await runInstall(process.argv.slice(3)));
 }
-const API_KEY = process.env.CITO_API_KEY;
+const ENV_API_KEY = process.env.CITO_API_KEY ?? '';
+const requestAuth = new AsyncLocalStorage();
+function currentApiKey() {
+    return requestAuth.getStore()?.apiKey || ENV_API_KEY;
+}
 /**
  * Tools that need no API key. These must keep working with the server
  * unconfigured, so a user can add it and immediately see what it does.
@@ -50,20 +56,21 @@ const OFFLINE_TOOLS = new Set(['list_capabilities']);
  * recovery steps, which the model can read out; list_capabilities keeps working
  * offline so the server is browsable before it is configured.
  */
-if (!API_KEY) {
+if (!ENV_API_KEY) {
     // stderr only — stdout is the JSON-RPC channel and must stay clean.
     console.error('[cito-mcp] CITO_API_KEY is not set. Serving tool catalog only; ' +
-        'API-backed tools will return MISSING_API_KEY until a key is provided. ' +
-        'Get one at https://citoapi.com/dashboard and set CITO_API_KEY.');
+        'API-backed tools will return MISSING_API_KEY until a key is provided ' +
+        '(env CITO_API_KEY, or x-api-key on hosted HTTP). ' +
+        'Get one at https://citoapi.com/dashboard.');
 }
 const API_BASE = (process.env.CITO_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
 const ctx = {
     // Empty string when unconfigured; the dispatcher blocks API-backed tools
     // before any request is attempted, so this is never sent as a credential.
-    apiKey: API_KEY ?? '',
+    apiKey: ENV_API_KEY,
     baseUrl: API_BASE,
 };
-async function main() {
+function createCitoServer() {
     const server = new Server({
         name: 'cito-mcp',
         version: PACKAGE_VERSION,
@@ -72,11 +79,7 @@ async function main() {
         instructions: SERVER_INSTRUCTIONS,
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: allTools.map(({ name, description, inputSchema }) => ({
-            name,
-            description,
-            inputSchema,
-        })),
+        tools: allTools.map(toolListing),
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name } = request.params;
@@ -93,7 +96,8 @@ async function main() {
         }
         // Fail the CALL, not the process. The model gets an actionable envelope it
         // can relay verbatim instead of the client reporting a dead server.
-        if (!API_KEY && !OFFLINE_TOOLS.has(name)) {
+        const apiKey = currentApiKey();
+        if (!apiKey && !OFFLINE_TOOLS.has(name)) {
             return toMcpResult(errorEnvelope({
                 code: 'UNAUTHORIZED',
                 message: 'CITO_API_KEY is not set, so this tool cannot reach the Cito API. ' +
@@ -104,13 +108,14 @@ async function main() {
                 retryable: false,
                 recover: [
                     'Create a key at https://citoapi.com/dashboard',
-                    'claude mcp add cito -e CITO_API_KEY=cito_... -- npx cito-mcp',
+                    'Hosted: send it as the x-api-key header to https://api.citoapi.com/mcp',
+                    'Local: claude mcp add cito -e CITO_API_KEY=cito_... -- npx cito-mcp',
                     'Or set CITO_API_KEY in the mcpServers env block of your client config',
                     'Call list_capabilities to browse available tools without a key',
                 ],
             }));
         }
-        return runTool(tool, args, ctx);
+        return runTool(tool, args, { ...ctx, apiKey });
     });
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({
         resources: [
@@ -181,7 +186,7 @@ async function main() {
         if (uri === 'cito://openapi.json') {
             try {
                 const response = await fetch(`${API_BASE}/openapi.json`, {
-                    headers: { 'x-api-key': API_KEY, accept: 'application/json' },
+                    headers: { 'x-api-key': currentApiKey(), accept: 'application/json' },
                 });
                 const text = await response.text();
                 return {
@@ -202,6 +207,9 @@ async function main() {
         }
         throw new Error(`unknown resource: ${uri}`);
     });
+    return server;
+}
+async function main() {
     const httpPort = (() => {
         const index = process.argv.indexOf('--http');
         if (index === -1)
@@ -210,33 +218,93 @@ async function main() {
         return Number.isInteger(port) && port > 0 ? port : null;
     })();
     if (httpPort) {
-        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-        await server.connect(transport);
+        const listenHost = process.env.CITO_MCP_LISTEN || '127.0.0.1';
         const httpServer = createHttpServer(async (req, res) => {
-            if (req.url !== '/mcp') {
+            const path = requestPathname(req.url);
+            const cors = corsHeaders();
+            for (const [k, v] of Object.entries(cors))
+                res.setHeader(k, v);
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            if ((path === MCP_CONFIG_PATH || path === MCP_SERVER_CARD_PATH) &&
+                (req.method === 'GET' || req.method === 'HEAD')) {
+                const payload = path === MCP_CONFIG_PATH ? mcpConfigSchema() : mcpServerCard();
+                const body = JSON.stringify(payload);
+                res.writeHead(200, {
+                    'content-type': 'application/json; charset=utf-8',
+                    'cache-control': 'public, max-age=60',
+                });
+                if (req.method === 'HEAD') {
+                    res.end();
+                    return;
+                }
+                res.end(body);
+                return;
+            }
+            if (path !== MCP_PATH) {
                 res.writeHead(404, { 'content-type': 'application/json' });
                 res.end(JSON.stringify({ error: 'use POST /mcp' }));
                 return;
             }
-            let raw = '';
-            for await (const chunk of req)
-                raw += chunk;
-            let body;
+            const apiKey = extractApiKey(req);
+            ensureMcpAccept(req.headers, req);
+            const proto = req.headers['mcp-protocol-version'];
+            const protoVal = Array.isArray(proto) ? proto[0] : proto;
+            if (protoVal === '2026-07-28') {
+                setIncomingHeader(req, 'mcp-protocol-version', '2025-11-25');
+            }
+            const server = createCitoServer();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+            });
+            transport.onerror = (error) => {
+                log(`http transport: ${error instanceof Error ? error.message : String(error)}`);
+            };
+            res.on('close', () => {
+                void transport.close();
+            });
             try {
-                body = JSON.parse(raw || 'null');
+                await server.connect(transport);
+                await requestAuth.run({ apiKey }, async () => {
+                    if (req.method === 'POST') {
+                        let raw = '';
+                        for await (const chunk of req)
+                            raw += chunk;
+                        let parsed = null;
+                        if (raw.trim()) {
+                            try {
+                                parsed = rewriteMcpProtocolMessage(JSON.parse(raw));
+                            }
+                            catch {
+                                res.writeHead(400, { 'content-type': 'application/json' });
+                                res.end(JSON.stringify({ error: 'invalid JSON body' }));
+                                return;
+                            }
+                        }
+                        await transport.handleRequest(req, res, parsed);
+                        return;
+                    }
+                    await transport.handleRequest(req, res);
+                });
             }
-            catch {
-                res.writeHead(400, { 'content-type': 'application/json' });
-                res.end(JSON.stringify({ error: 'invalid JSON body' }));
-                return;
+            catch (err) {
+                log(`http handler error: ${err.message}`);
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'mcp handler failed' }));
+                }
             }
-            await transport.handleRequest(req, res, body);
         });
-        httpServer.listen(httpPort, () => {
-            log(`cito-mcp ${PACKAGE_VERSION} listening on http://127.0.0.1:${httpPort}/mcp (${allTools.length} curated tools)`);
+        httpServer.listen(httpPort, listenHost, () => {
+            log(`cito-mcp ${PACKAGE_VERSION} listening on http://${listenHost}:${httpPort}/mcp (${allTools.length} curated tools)`);
         });
     }
     else {
+        const server = createCitoServer();
         await server.connect(new StdioServerTransport());
         log(`cito-mcp ${PACKAGE_VERSION} on stdio (${allTools.length} curated tools)`);
     }

package/dist/install.js

@@ -75,6 +75,14 @@ function clientsFor() {
             detectPath: join(home, '.codex'),
             format: 'toml-mcp_servers',
         },
+        {
+            id: 'grok',
+            label: 'Grok CLI',
+            configPath: join(home, '.grok', 'config.toml'),
+            detectPath: join(home, '.grok'),
+            // Same [mcp_servers.x] / [mcp_servers.x.env] layout as Codex.
+            format: 'toml-mcp_servers',
+        },
     ];
 }
 export function maskKey(key) {
@@ -265,7 +273,7 @@ Usage:
 
 Options:
   --key <key>       Cito API key. Falls back to $CITO_API_KEY.
-  --client <ids>    Comma-separated: claude-code, claude-desktop, cursor, windsurf, codex.
+  --client <ids>    Comma-separated: claude-code, claude-desktop, cursor, windsurf, codex, grok.
                     Default: every client detected on this machine.
   --base <url>      Override API base (staging / self-hosted).
   --dry-run, -n     Show what would change; write nothing.

package/dist/instructions.js

@@ -16,7 +16,7 @@ You are connected to Cito esports data (read-only). Prefer curated outcome tools
 
 ## Game parameter
 
-game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | all
+game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | tennis | all
 
 - Default when the user named one title: that game. Default for "what's live?" / multi-title: omit game or all on tools that accept it.
 - On UNSUPPORTED_GAME / 403 for a title: stop retrying that game; call api_health; report plan gaps.

package/dist/tools/live.js

@@ -11,6 +11,7 @@ const LIVE_PATHS = {
     dota2: '/dota2/matches/live',
     cod: '/cod/matches/live',
     ufc: '/ufc/live',
+    tennis: '/tennis/matches/live',
 };
 /**
  * Extract live match/bout rows. UFC /ufc/live returns
@@ -502,6 +503,22 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
             if (tournamentId)
                 noteIgnored('tournamentId', 'pass event slug via event_card instead');
         }
+        else if (game === 'tennis') {
+            // Tennis has no upcoming-fixtures endpoint; the archive is results-only.
+            return errorEnvelope({
+                code: 'UNSUPPORTED_GAME',
+                message: 'Tennis has no upcoming-fixtures feed. Live matches: live_matches { game: "tennis" }. Recent results: call_api GET /tennis/matches/recent. Season calendar: call_api GET /tennis/tournaments/calendar?year=YYYY.',
+                game,
+                source: 'upcoming_schedule',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use live_matches with game "tennis" for in-progress matches',
+                    'Use call_api GET /tennis/matches/recent for latest results',
+                    'Use call_api GET /tennis/tournaments/calendar?year=YYYY for the season schedule',
+                ],
+            });
+        }
         const res = await fetchJson(ctx, path, { query });
         if (!res.ok) {
             return errorEnvelope({

package/dist/tools/match.js

@@ -99,22 +99,24 @@ function primaryPath(game, matchId) {
             return `/cod/matches/${encodeURIComponent(matchId)}`;
         case 'ufc':
             return `/ufc/bouts/${encodeURIComponent(matchId)}`;
+        case 'tennis':
+            return `/tennis/matches/${encodeURIComponent(matchId)}`;
     }
 }
 export const matchSummary = {
     name: 'match_summary',
-    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
-
-When to use:
-- Match recap / default match UI
-- After user selects a live or completed matchId
-
-Prefer over match_details for chat answers and default UIs.
-Prefer match_details for timelines, full map trees, live state, advanced packages.
-
-Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
-
-Parallel-safe: yes. Upstream cost: 2–5.
+    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
+
+When to use:
+- Match recap / default match UI
+- After user selects a live or completed matchId
+
+Prefer over match_details for chat answers and default UIs.
+Prefer match_details for timelines, full map trees, live state, advanced packages.
+
+Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
+
+Parallel-safe: yes. Upstream cost: 2–5.
 Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includePlayerStats": true }`,
     inputSchema: {
         type: 'object',
@@ -204,6 +206,8 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
                     paths.push(`/cod/matches/${encodeURIComponent(matchId)}/player-stats`);
                 if (game === 'ufc')
                     paths.push(`/ufc/bouts/${encodeURIComponent(matchId)}/stats`);
+                if (game === 'tennis')
+                    paths.push(`/tennis/matches/${encodeURIComponent(matchId)}/stats`);
                 for (const p of paths) {
                     const res = await getSection(ctx, p);
                     upstreamCalls += 1;
@@ -298,22 +302,22 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
 };
 export const matchDetails = {
     name: 'match_details',
-    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
-
-When to use:
-- Analyst deep dive
-- Live in-game window (LoL/CS2/UFC)
-- Full demo list
-
-Prefer over match_summary only when summary is insufficient.
-Prefer match_summary for short answers and default cards.
-
-Do not use when: first-pass live board (use live_matches + match_summary).
-
-Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
-If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
-
-Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
+    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
+
+When to use:
+- Analyst deep dive
+- Live in-game window (LoL/CS2/UFC)
+- Full demo list
+
+Prefer over match_summary only when summary is insufficient.
+Prefer match_summary for short answers and default cards.
+
+Do not use when: first-pass live board (use live_matches + match_summary).
+
+Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
+If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
+
+Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
 Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "includeLiveState": false }`,
     inputSchema: {
         type: 'object',

package/dist/tools/meta.js

@@ -480,6 +480,7 @@ const ALLOWLIST_PREFIXES = [
     '/cod',
     '/ufc',
     '/fortnite',
+    '/tennis',
     // The spec describes the surface call_api is allowed to reach; refusing to
     // serve it left route discovery impossible except by guessing.
     '/openapi.json',
@@ -505,7 +506,7 @@ Prefer curated tools for all standard jobs (live, schedule, profiles, standings,
 
 Do not use when: a curated tool covers the outcome. Avoid parallel storms; same plan rate limits apply.
 
-Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite.
+Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /tennis.
 Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
 
 Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
@@ -566,7 +567,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
                 source: 'call_api',
                 requestId,
                 tookMs: Date.now() - started,
-                hint: 'Use prefixes /health /lol /cs2 /dota2 /cod /ufc /fortnite',
+                hint: 'Use prefixes /health /lol /cs2 /dota2 /cod /ufc /fortnite /tennis',
             });
         }
         let query = {};
@@ -646,6 +647,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
  * explicitly rather than returning an empty list that reads as a verdict.
  */
 const SPEC_OMITS = {
+    tennis: 'The published OpenAPI spec documents no /tennis paths, but tennis routes exist and work (players, matches, h2h, rankings, tournaments, live). Use the curated tools with game tennis, or call_api with /tennis/* paths.',
     lol: 'The published OpenAPI spec documents no /lol paths, but LoL routes exist and work. Use the curated LoL tools (live_matches, upcoming_schedule, team_profile, standings, player_profile); for raw access, /lol/* is allowlisted for call_api even though it is undocumented.',
 };
 export const listRoutes = {

package/dist/tools/normalize.js

@@ -154,7 +154,7 @@ function scoreNum(v) {
 export function normalizeMatch(game, row, forcedStatus) {
     // Always peel { success, data } so UFC bout fighters[] / status are visible.
     const r = asRecord(unwrapPayload(row)) ?? asRecord(row) ?? {};
-    const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.fightMetricId, r.ufcFightId) ?? 'unknown';
+    const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.fightMetricId, r.ufcFightId, r.live_match_id) ?? 'unknown';
     let team1 = nestedSide(r.team1, game) ??
         sideFrom(pickString(r.team1Name, r.team_a_name, r.redName, r.fighter1Name, r.homeName), pickString(r.team1Id, r.team1_id, r.redId, r.fighter1Id), pickString(r.team1Slug, r.redSlug, r.fighter1Slug), scoreNum(r.team1Score ?? r.score1 ?? r.team1Maps ?? r.redScore));
     let team2 = nestedSide(r.team2, game) ??
@@ -171,6 +171,24 @@ export function normalizeMatch(game, row, forcedStatus) {
         if (s != null)
             team2 = { ...team2, score: s };
     }
+    // Tennis: live rows carry player1_name/player2_name; archive rows only carry
+    // winner_id/loser_id (ids, no names). Map both onto sides so labels are never "? vs ?".
+    if (game === 'tennis' && !team1 && !team2) {
+        const p1 = pickString(r.player1_name);
+        const p2 = pickString(r.player2_name);
+        if (p1 || p2) {
+            team1 = sideFrom(p1, pickString(r.player1_id), undefined, undefined);
+            team2 = sideFrom(p2, pickString(r.player2_id), undefined, undefined);
+        }
+        else {
+            const w = pickString(r.winner_id);
+            const l = pickString(r.loser_id);
+            if (w || l) {
+                team1 = sideFrom(w, w, undefined, undefined);
+                team2 = sideFrom(l, l, undefined, undefined);
+            }
+        }
+    }
     // UFC / live corners: red/blue objects, corner arrays, or fighters[] with corner field.
     // Public API serializeBout uses fighters:[{ corner, fighterName, fighterSlug, profile:{name,slug} }].
     // Live tracking uses red/blue + fighters[] (not team1/team2).
@@ -373,12 +391,12 @@ export function sortByCardOrder(rows) {
 }
 export function entityRef(row, type, game) {
     const r = asRecord(row) ?? {};
-    const id = pickString(r.id, r.teamId, r.playerId, r.lolPlayerId, r.codPlayerId, r.matchId, r.boutId, r.eventId, r.tournamentId, r.leagueId) ??
+    const id = pickString(r.id, r.teamId, r.playerId, r.player_id, r.lolPlayerId, r.codPlayerId, r.matchId, r.boutId, r.eventId, r.tournamentId, r.leagueId) ??
         pickString(r.slug) ??
         'unknown';
     const slug = pickString(r.slug, r.orgSlug, r.teamSlug);
     // Events often use `title` not `name` (UFC)
-    const name = pickString(r.name, r.title, r.nickname, r.displayName, r.tag, r.code, slug, id) ?? id;
+    const name = pickString(r.name, r.full_name, r.player_name, r.title, r.nickname, r.displayName, r.tag, r.code, slug, id) ?? id;
     const nickname = pickString(r.nickname, asRecord(r.profile)?.nickname);
     return {
         game,

package/dist/tools/player.js

@@ -9,7 +9,7 @@ function identityFrom(game, raw, idHint, slugHint) {
     const r = asRecord(raw) ?? {};
     const id = pickString(r.id, r.playerId, r.lolPlayerId, r.codPlayerId, idHint, slugHint) ?? 'unknown';
     const slug = pickString(r.slug, slugHint);
-    const name = pickString(r.name, r.nickname, r.displayName, r.tag, slug, id) ?? id;
+    const name = pickString(r.name, r.full_name, r.nickname, r.displayName, r.tag, slug, id) ?? id;
     const team = asRecord(r.team) ??
         asRecord(r.currentTeam) ??
         (r.teamName || r.orgSlug
@@ -146,6 +146,8 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             primaryPath = `/cod/players/${encodeURIComponent(idOrSlug)}`;
         else if (game === 'ufc')
             primaryPath = `/ufc/fighters/${encodeURIComponent(slug || idOrSlug)}`;
+        else if (game === 'tennis')
+            primaryPath = `/tennis/players/${encodeURIComponent(idOrSlug)}`;
         let playerRaw = null;
         if (game === 'dota2') {
             // Prefer radar as primary signal; try list filter
@@ -218,6 +220,43 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 }
             })());
         }
+        if (game === 'tennis') {
+            if (includeTrends) {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(idOrSlug)}/stats`);
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...res.headers };
+                    if (res.ok)
+                        career = unwrapPayload(res.data);
+                    else {
+                        partial.push(partialFromRejection('career', {
+                            code: mapHttpToCode(res.status),
+                            message: `player stats HTTP ${res.status}`,
+                            httpStatus: res.status,
+                        }));
+                    }
+                })());
+            }
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(idOrSlug)}/matches`, {
+                    query: { page_size: recentLimit },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    const envelope = asRecord(res.data) ?? {};
+                    const data = asRecord(envelope.data) ?? envelope;
+                    recentMatches = extractRows(data.items ?? data).slice(0, recentLimit);
+                }
+                else {
+                    partial.push(partialFromRejection('recentMatches', {
+                        code: mapHttpToCode(res.status),
+                        message: `player matches HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+        }
         if (game === 'cs2' && includeTrends) {
             for (const [section, path] of [
                 ['career', `/cs2/players/${encodeURIComponent(idOrSlug)}/career`],

package/dist/tools/resolve.js

@@ -230,6 +230,33 @@ async function searchGame(ctx, game, q, type, limit) {
             }
             pushCandidates(candidates, game, type === 'any' ? 'unknown' : type, extractRows(res.data), q, limit);
         }
+        else if (game === 'tennis') {
+            // Tennis has no combined /search; players and competitions are separate lookups.
+            const tasks = [];
+            if (type === 'any' || type === 'player') {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, '/tennis/players/search', { query: { q, limit } });
+                    calls += 1;
+                    if (res.ok) {
+                        const envelope = asRecord(res.data) ?? {};
+                        const data = asRecord(envelope.data) ?? envelope;
+                        pushCandidates(candidates, game, 'player', extractRows(data.items ?? data), q, limit);
+                    }
+                })());
+            }
+            if (type === 'any' || type === 'tournament' || type === 'event') {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, '/tennis/competitions', { query: { q, page_size: limit } });
+                    calls += 1;
+                    if (res.ok) {
+                        const envelope = asRecord(res.data) ?? {};
+                        const data = asRecord(envelope.data) ?? envelope;
+                        pushCandidates(candidates, game, 'tournament', extractRows(data.items ?? data), q, limit);
+                    }
+                })());
+            }
+            await Promise.all(tasks);
+        }
         else if (game === 'lol') {
             const tasks = [];
             if (type === 'any' || type === 'team') {
@@ -593,6 +620,26 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                         await listPath('/dota2/tournaments', 'tournament');
                 }
             }
+            else if (game === 'tennis') {
+                if (type === 'player' || type === 'any') {
+                    const res = await fetchJson(ctx, '/tennis/players/search', { query: { q, limit } });
+                    upstreamCalls += 1;
+                    if (res.ok) {
+                        const envelope = asRecord(res.data) ?? {};
+                        const data = asRecord(envelope.data) ?? envelope;
+                        items.push(...extractRows(data.items ?? data).map((r) => entityRef(r, 'player', game)));
+                    }
+                }
+                if (type === 'tournament' || type === 'event' || type === 'any') {
+                    const res = await fetchJson(ctx, '/tennis/competitions', { query: { q, page_size: limit } });
+                    upstreamCalls += 1;
+                    if (res.ok) {
+                        const envelope = asRecord(res.data) ?? {};
+                        const data = asRecord(envelope.data) ?? envelope;
+                        items.push(...extractRows(data.items ?? data).map((r) => entityRef(r, 'tournament', game)));
+                    }
+                }
+            }
             else if (game === 'cod') {
                 if (q) {
                     const res = await fetchJson(ctx, '/cod/search', {

package/dist/tools/standings.js

@@ -8,7 +8,7 @@ import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from
 export function normalizeStandingRow(row, index) {
     const r = asRecord(row) ?? {};
     const entity = asRecord(r.team) ?? asRecord(r.fighter) ?? asRecord(r.org) ?? r;
-    const name = pickString(asRecord(entity)?.name, r.teamName, r.name, r.orgName, r.fighterName, asRecord(entity)?.slug) ?? `row-${index + 1}`;
+    const name = pickString(asRecord(entity)?.name, r.teamName, r.name, r.orgName, r.fighterName, r.player_name, asRecord(entity)?.slug) ?? `row-${index + 1}`;
     // UFC official lists: champion has rank=null + rankText="C" (interim "IC"); contenders 1..15.
     // Never fall back to index+1 for explicit null ranks — that produced two "#1" rows (champ + #1).
     const championStatus = pickString(r.championStatus, asRecord(entity)?.championStatus);
@@ -234,6 +234,14 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 title = 'UFC rankings';
             }
         }
+        else if (game === 'tennis') {
+            // Tennis "standings" = the latest ATP/WTA singles rankings. Pass tour via division.
+            const tour = String(division ?? 'ATP').toUpperCase() === 'WTA' ? 'WTA' : 'ATP';
+            path = '/tennis/rankings/top';
+            query = { tour, top_n: Math.min(limit, 100) };
+            effectiveScope = 'world';
+            title = `${tour} singles rankings`;
+        }
         else if (game === 'dota2') {
             // No first-class standings — try team list worldRanking
             const res = await fetchJson(ctx, '/dota2/teams', { query: { limit } });

package/dist/tools/team.js

@@ -21,18 +21,18 @@ function teamIdentity(game, raw, idHint, slugHint) {
 }
 export const teamProfile = {
     name: 'team_profile',
-    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
-
-When to use:
-- Team page / "who is on this roster?"
-- Builder team screen sample
-
-Prefer over: separate roster + matches + detail via call_api.
-
-Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
-Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
-
-Parallel-safe: yes. Upstream cost: 2–4.
+    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
+
+When to use:
+- Team page / "who is on this roster?"
+- Builder team screen sample
+
+Prefer over: separate roster + matches + detail via call_api.
+
+Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
+Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
+
+Parallel-safe: yes. Upstream cost: 2–4.
 Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -81,6 +81,20 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
                 ],
             });
         }
+        if (game === 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: 'Tennis has players, not team profiles',
+                game,
+                source: 'team_profile',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use player_profile with a tennis player id (e.g. atp_104745)',
+                    'Use standings with game "tennis" for ATP/WTA rankings',
+                ],
+            });
+        }
         const teamId = typeof args.teamId === 'string' ? args.teamId.trim() : '';
         const slug = typeof args.slug === 'string' ? args.slug.trim() : '';
         if (!teamId && !slug) {
@@ -486,19 +500,19 @@ function winnerSide(match, a) {
 }
 export const headToHead = {
     name: 'head_to_head',
-    description: `Composed head-to-head record between two teams (or two UFC fighters). No first-class REST H2H exists — this tool filters match history server-side.
-
-When to use:
-- Rivalry / series record questions
-- Supporting context for previews
-
-Prefer over: agent-side double match-list filtering.
-
-Do not use when: single-side form only → team_profile or player_profile.
-
-Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
-
-Parallel-safe: yes. Upstream cost: 2–4.
+    description: `Composed head-to-head record between two teams, two UFC fighters, or two tennis players. No first-class REST H2H exists — this tool filters match history server-side.
+
+When to use:
+- Rivalry / series record questions
+- Supporting context for previews
+
+Prefer over: agent-side double match-list filtering.
+
+Do not use when: single-side form only → team_profile or player_profile.
+
+Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
+
+Parallel-safe: yes. Upstream cost: 2–4.
 Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
     inputSchema: {
         type: 'object',
@@ -508,9 +522,9 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
             game: gameSchema({ allowAll: false, required: true }),
             entityType: {
                 type: 'string',
-                enum: ['team', 'fighter'],
+                enum: ['team', 'fighter', 'player'],
                 default: 'team',
-                description: 'team (default) or fighter (UFC).',
+                description: 'team (default), fighter (UFC), or player (tennis).',
             },
             sideA: stringSchema('Id or slug for side A.', 'faze'),
             sideB: stringSchema('Id or slug for side B.', 'navi'),
@@ -734,6 +748,74 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
                 warnings.push('No fight history rows returned for either fighter; H2H may be empty');
             }
         }
+        if (game === 'tennis') {
+            // Tennis has a first-class H2H endpoint; resolve names to player ids first when needed.
+            const resolveTennisSide = async (side) => {
+                if (/^(atp|wta)_\d+$/i.test(side))
+                    return { id: side, name: side };
+                const res = await fetchJson(ctx, '/tennis/players/search', { query: { q: side, limit: 3 } });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (!res.ok)
+                    return null;
+                const envelope = asRecord(res.data) ?? {};
+                const data = asRecord(envelope.data) ?? envelope;
+                const first = asRecord(extractRows(data.items ?? data)[0]);
+                const id = pickString(first?.id, first?.player_id);
+                return id ? { id, name: pickString(first?.full_name, first?.name) ?? side } : null;
+            };
+            const [tA, tB] = await Promise.all([resolveTennisSide(sideA), resolveTennisSide(sideB)]);
+            if (!tA || !tB) {
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: 'One or both tennis players not found — pass names or ids like atp_104745',
+                    game,
+                    source: 'head_to_head',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit,
+                    recover: [
+                        'resolve_entity { game: "tennis", type: "player", q } for each name',
+                        'Retry head_to_head with returned ids as sideA/sideB',
+                    ],
+                });
+            }
+            const res = await fetchJson(ctx, '/tennis/h2h', {
+                query: { player1_id: tA.id, player2_id: tB.id },
+            });
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...res.headers };
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `Tennis H2H fetch failed (HTTP ${res.status})`,
+                    game,
+                    source: 'head_to_head',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    httpStatus: res.status,
+                    rateLimit,
+                });
+            }
+            const envelope = asRecord(res.data) ?? {};
+            const h2h = asRecord(envelope.data) ?? envelope;
+            return successEnvelope({
+                source: 'head_to_head',
+                game,
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                rateLimit,
+                data: {
+                    sideA: { idOrSlug: tA.id, name: tA.name },
+                    sideB: { idOrSlug: tB.id, name: tB.name },
+                    h2h,
+                    notes: ['Record and meetings come from the first-class /tennis/h2h endpoint'],
+                },
+            });
+        }
         const meetings = rows
             .map((row) => normalizeMatch(game, row))
             .filter((m) => sidesMatch(m, matchA, matchB))

package/dist/tools/types.js

@@ -1,5 +1,20 @@
-import { toMcpResult } from '../envelope.js';
-export const PRIMARY_GAMES = ['lol', 'cs2', 'dota2', 'cod', 'ufc'];
+import { ENVELOPE_OUTPUT_SCHEMA, toMcpResult } from '../envelope.js';
+/** All curated tools fetch Cito data. None delete, post, or mutate user state. */
+export const READ_TOOL_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+};
+export function toolListing(def) {
+    return {
+        name: def.name,
+        description: def.description,
+        inputSchema: def.inputSchema,
+        outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+        annotations: def.annotations ?? READ_TOOL_ANNOTATIONS,
+    };
+}
+export const PRIMARY_GAMES = ['lol', 'cs2', 'dota2', 'cod', 'ufc', 'tennis'];
 export const GAME_ENUM = [...PRIMARY_GAMES, 'all'];
 export function isPrimaryGame(value) {
     return typeof value === 'string' && PRIMARY_GAMES.includes(value);
@@ -15,7 +30,7 @@ export function parseGame(value, opts) {
     const g = value.toLowerCase();
     if (g === 'all') {
         if (opts?.allowAll === false) {
-            return { error: 'game=all is not valid for this tool; pick lol|cs2|dota2|cod|ufc' };
+            return { error: 'game=all is not valid for this tool; pick lol|cs2|dota2|cod|ufc|tennis' };
         }
         return { game: 'all' };
     }
@@ -23,7 +38,7 @@ export function parseGame(value, opts) {
         return { game: g };
     }
     return {
-        error: `unsupported game "${value}"; use lol|cs2|dota2|cod|ufc${opts?.allowAll !== false ? '|all' : ''}`,
+        error: `unsupported game "${value}"; use lol|cs2|dota2|cod|ufc|tennis${opts?.allowAll !== false ? '|all' : ''}`,
     };
 }
 export function gameSchema(opts) {
@@ -33,8 +48,8 @@ export function gameSchema(opts) {
         enum: values,
         description: opts?.description ??
             (opts?.allowAll === false
-                ? 'Game title: lol | cs2 | dota2 | cod | ufc. Example: "cs2".'
-                : 'Game title: lol | cs2 | dota2 | cod | ufc | all. Omit or all for multi-game tools. Example: "lol".'),
+                ? 'Game title: lol | cs2 | dota2 | cod | ufc | tennis. Example: "cs2".'
+                : 'Game title: lol | cs2 | dota2 | cod | ufc | tennis | all. Omit or all for multi-game tools. Example: "lol".'),
     };
 }
 export function limitSchema(opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Standalone MCP server for the Cito esports API — 15 curated outcome tools for agents (live, schedule, profiles, standings, previews, event cards).",
   "type": "module",
   "bin": {