cito-mcp 0.2.6 → 0.3.0

package/README.md

@@ -38,33 +38,39 @@ Composites multi-fetch server-side, return a **stable JSON envelope**, and isola
 
 ## Install
 
-### One-liner (published package)
+### One command (recommended)
 
 ```bash
-npx cito-mcp
+npx cito-mcp install --key cito_your_key_here
 ```
 
-Requires `CITO_API_KEY` in the environment (see [Environment](#environment)). Most hosts inject env via their MCP config rather than a bare shell.
+Detects the MCP clients installed on your machine — Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI — and writes the config for each. Then restart your editor.
 
-### Claude Code
+It is safe to re-run: existing config is merged, not replaced, your other MCP servers are left alone, a `.cito-bak` backup is written before the first change, and running it again just rotates the key rather than adding a second entry.
 
 ```bash
-claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- npx cito-mcp
+npx cito-mcp install --dry-run                     # show the plan, write nothing
+npx cito-mcp install --key … --client cursor       # one client only
+npx cito-mcp install --help
 ```
 
-Windows — if `npx` fails under Claude:
+Get a key at [citoapi.com/dashboard](https://citoapi.com/dashboard).
+
+### Manual — Claude Code
 
 ```bash
-claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- cmd /c npx cito-mcp
+claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" npx -y cito-mcp
 ```
 
+**Quote the `--`.** PowerShell 5.1 strips a bare `--` before the CLI sees it; because `-e` takes a variable number of values it then swallows `npx -y cito-mcp` as env vars and fails with `unknown option '-y'`. The quoted form works in PowerShell, cmd, bash and zsh alike. `npx cito-mcp install` avoids the problem entirely.
+
 From a local clone (development):
 
 ```bash
 cd mcp
 npm install
 npm run build
-claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- node "%CD%\dist\index.js"
+claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" node "%CD%\dist\index.js"
 ```
 
 ### Cursor
@@ -376,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)
@@ -460,13 +469,20 @@ Package: **`cito-mcp@0.2.4`**
    - `live_matches`
    - `resolve_entity` (e.g. T1 / s1mple)
    - `match_summary` with a real `matchId` from live/schedule
-4. Confirm `package.json` version and README match the shipped tool list (15).
+4. Confirm `package.json` version and README match the shipped tool list.
 5. `npm publish` from `mcp/` (or your release pipeline) with appropriate npm auth / access.
+   `prepublishOnly` runs build + tests + smoke, so a broken build cannot ship.
 
 ### Install line for docs & marketing
 
 ```bash
-claude mcp add cito -e CITO_API_KEY=cito_… -- npx cito-mcp
+npx cito-mcp install --key cito_…
+```
+
+Manual fallback (note the quoted `--`, required for PowerShell):
+
+```bash
+claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 ```
 
 ```json

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,9 +18,26 @@ 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';
-const API_KEY = process.env.CITO_API_KEY;
+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.
+ *
+ * `install` writes editor config and prints to stdout, which would corrupt the
+ * JSON-RPC channel if it ran alongside the server — hence the early return.
+ * Handled here rather than in a second binary so the documented entry point
+ * stays `npx cito-mcp`.
+ */
+if (process.argv[2] === 'install') {
+    const { runInstall } = await import('./install.js');
+    process.exit(await runInstall(process.argv.slice(3)));
+}
+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.
@@ -38,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,
@@ -60,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;
@@ -81,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. ' +
@@ -92,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: [
@@ -169,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 {
@@ -190,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)
@@ -198,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)`);
     }