cito-mcp 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# cito-mcp
+
+Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports API](https://api.citoapi.com) (LoL, Dota 2, CS2, COD, Fortnite, UFC, and more).
+
+**Zero per-endpoint code:** on boot the server fetches the live OpenAPI specs from the API and generates one MCP tool per operation (105 tools today from the global + LoL specs). When the API ships a new endpoint, it appears here automatically on the next spec refresh — restart to pick it up immediately.
+
+## Requirements
+
+- Node.js >= 20
+- A Cito API key (`CITO_API_KEY`)
+
+## Quickstart (Claude Code)
+
+```bash
+claude mcp add cito -- env CITO_API_KEY=cito_your_key_here npx cito-mcp
+```
+
+Or run it straight from a clone of this repo (no publish needed):
+
+```bash
+cd mcp && npm install && npm run build
+claude mcp add cito -- env CITO_API_KEY=cito_your_key_here node "$PWD/dist/index.js"
+```
+
+## Cursor / Windsurf
+
+Add to your MCP config JSON (e.g. `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "cito": {
+      "command": "npx",
+      "args": ["cito-mcp"],
+      "env": {
+        "CITO_API_KEY": "cito_your_key_here"
+      }
+    }
+  }
+}
+```
+
+The server exits immediately with a clear stderr message if `CITO_API_KEY` is missing. The key is sent only as the `x-api-key` header to the API and is never logged.
+
+## How tool updates work (multi-spec)
+
+The server merges **multiple OpenAPI specs** at boot — the global spec does not cover every game:
+
+- **Default sources**: the global spec (`$CITO_API_BASE/openapi.json`) + the LoL spec (`$CITO_API_BASE/lol/openapi.json`). Today: 71 + 34 = 105 generated tools.
+- **Opportunistic per-game specs**: at boot the server also probes `$CITO_API_BASE/{cod,fortnite,dota2,cs2,ufc}/openapi.json` **with your `x-api-key`** and merges any that return 200. 401/404s are skipped quietly (one stderr line each).
+- **Add or replace sources via env**:
+  - `CITO_OPENAPI_URLS` — comma-separated list, replaces the defaults entirely (e.g. `CITO_OPENAPI_URLS=https://api.citoapi.com/api/v1/openapi.json,https://api.citoapi.com/api/v1/cod/openapi.json`).
+  - `CITO_OPENAPI_URL` (singular) — single-spec override (legacy, still works).
+- **Per-spec base URLs**: each spec's `servers[0].url` is used as the base for its tools (the global spec's paths are relative to `/api/v1`; the LoL spec's paths already include `/api/v1/lol` and its servers entry is the bare origin — so `servers[0].url` + verbatim paths is correct for both). Escape hatch: `CITO_SPEC_BASE_<KEY>` (e.g. `CITO_SPEC_BASE_LOL=https://staging.example.com/api/v1`).
+- **Collisions**: merge is path/operation concatenation. On an `operationId` collision across specs, the later spec's tool is prefixed with its game key (`cito_lol_…`) and logged to stderr.
+- **No operationId?** Fallback names are derived from method + path (`get /api/v1/lol/live/{gameId}/stats` → `cito_getlollivebygameidstats`). The real LoL spec currently ships no operationIds, so all its tools use fallback names.
+- The last good specs are cached to `mcp/.spec-cache.json` (one merged file, per-source entries) — a failed fetch falls back to the cached copy per source.
+- Specs are refreshed every `CITO_SPEC_REFRESH_MINUTES` (default 60); tools are regenerated in place and clients are notified via `tools/list_changed`. **Restart the server to pick up brand-new endpoints immediately.**
+- Tool names: `cito_` + sanitized name. Descriptions preserve the spec's summaries and per-parameter docs.
+- All logs go to **stderr only** (stdout is the MCP channel).
+
+## Curated extras
+
+Hand-written, on top of the generated tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `cito_live_overview` | One merged "what's live right now" across all games (`/lol/live`, `/dota2/matches/live`, `/cs2/matches/live`, `/cod/matches/live`): per-game count + first few match labels. Games that 4xx are skipped, not fatal. |
+| `cito_api_health` | Authenticated probe proving your key works: tries `$CITO_API_BASE/health`, falls back to `$CITO_API_BASE/lol/leagues`, reports which probe answered, plus rate-limit/tier headers when present. |
+
+Resources:
+
+- `cito://llms.txt` — the API's agent-context file, fetched on read.
+- `cito://openapi.json` — the current spec this server generated its tools from.
+
+## Behavior notes
+
+- Path params are interpolated into the URL, query props become the query string, `body` becomes the JSON body.
+- Non-2xx responses are returned as-is with `isError: true` — agents can read the API's own error codes (quota, tier gates, 404s).
+- Responses over ~100KB are truncated with a note telling the agent to narrow with query parameters.
+- Adding new endpoints to the API = **zero MCP code**. The spec is the contract.
+
+## HTTP transport (optional)
+
+stdio is the default (what Claude Code / Cursor use). A stateless Streamable HTTP endpoint is available:
+
+```bash
+CITO_API_KEY=cito_your_key_here node dist/index.js --http 8787
+# → http://127.0.0.1:8787/mcp
+```
+
+## Development
+
+```bash
+npm install
+npm run build     # tsc → dist/
+npm test          # node:test via tsx, no network
+```
+
+Environment variables: `CITO_API_KEY` (required), `CITO_API_BASE` (default `https://api.citoapi.com/api/v1`), `CITO_OPENAPI_URLS` / `CITO_OPENAPI_URL` (spec source overrides), `CITO_SPEC_BASE_<KEY>` (per-spec base override), `CITO_SPEC_REFRESH_MINUTES` (default 60).

package/dist/executor.js

@@ -0,0 +1,75 @@
+export const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024;
+export function buildRequestUrl(baseUrl, tool, args) {
+    let path = tool.path;
+    for (const param of tool.pathParams) {
+        const value = args[param];
+        if (value === undefined || value === null) {
+            throw new Error(`missing required path parameter: ${param}`);
+        }
+        path = path.split(`{${param}}`).join(encodeURIComponent(String(value)));
+    }
+    const query = new URLSearchParams();
+    for (const param of tool.queryParams) {
+        const value = args[param];
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                query.append(param, String(item));
+        }
+        else {
+            query.append(param, String(value));
+        }
+    }
+    const qs = query.toString();
+    const base = baseUrl.replace(/\/+$/, '');
+    return `${base}${path}${qs ? `?${qs}` : ''}`;
+}
+export async function executeApiCall(opts) {
+    const fetcher = opts.fetchImpl ?? fetch;
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    let url;
+    try {
+        // Per-tool base: each source spec declares its own servers[0].url (LoL
+        // paths already include /api/v1/lol; global paths are relative to /api/v1).
+        const baseUrl = opts.tool.baseUrl || opts.baseUrl;
+        url = buildRequestUrl(baseUrl, opts.tool, opts.args);
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: error.message }], isError: true };
+    }
+    const headers = {
+        'x-api-key': opts.apiKey,
+        accept: 'application/json',
+    };
+    let body;
+    if (opts.tool.hasBody && opts.args.body !== undefined) {
+        headers['content-type'] = 'application/json';
+        body = JSON.stringify(opts.args.body);
+    }
+    const response = await fetcher(url, { method: opts.tool.method, headers, body });
+    const text = await response.text();
+    if (!response.ok) {
+        return {
+            content: [{ type: 'text', text: `HTTP ${response.status}\n\n${text}` }],
+            isError: true,
+        };
+    }
+    return { content: [{ type: 'text', text: present(text, maxBytes) }] };
+}
+/** Pretty-print JSON; truncate oversized bodies with an agent-actionable note. */
+export function present(text, maxBytes) {
+    let out = text;
+    try {
+        out = JSON.stringify(JSON.parse(text), null, 2);
+    }
+    catch {
+        // Not JSON — return as-is.
+    }
+    if (out.length > maxBytes) {
+        return (`${out.slice(0, maxBytes)}\n\n` +
+            `[cito-mcp] Response truncated at ${maxBytes} bytes (full body was ${out.length}). ` +
+            `Narrow the result with query parameters (e.g. smaller limit, date range, or an id filter) and retry.`);
+    }
+    return out;
+}

package/dist/index.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+/**
+ * cito-mcp — standalone MCP server for the Cito esports API.
+ *
+ * Tools are generated from the live OpenAPI spec at boot (zero per-endpoint
+ * code) and refreshed every CITO_SPEC_REFRESH_MINUTES. stdio transport by
+ * default (Claude Code / Cursor); `--http <port>` serves a stateless
+ * Streamable HTTP endpoint instead.
+ *
+ * Required env: CITO_API_KEY (never logged).
+ * Optional env: CITO_API_BASE, CITO_OPENAPI_URL, CITO_SPEC_REFRESH_MINUTES.
+ */
+import { createServer as createHttpServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { DEFAULT_API_BASE, OPPORTUNISTIC_SPEC_KEYS, defaultSourceDefs, loadSpecSources, log, refreshSpecSourcesIfDue, specRefreshMinutes, } from './spec.js';
+import { generateAllTools } from './tools.js';
+import { executeApiCall, present } from './executor.js';
+const API_KEY = process.env.CITO_API_KEY;
+if (!API_KEY) {
+    console.error('[cito-mcp] CITO_API_KEY is required.\n' +
+        'Set it to your Cito API key, e.g.:\n' +
+        '  claude mcp add cito -- env CITO_API_KEY=cito_... npx cito-mcp');
+    process.exit(1);
+}
+const API_BASE = (process.env.CITO_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
+const CACHE_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '.spec-cache.json');
+const REFRESH_MINUTES = specRefreshMinutes();
+const PACKAGE_VERSION = '0.1.0';
+function textResult(text, isError = false) {
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
+}
+async function fetchJson(url) {
+    const response = await fetch(url, {
+        headers: { 'x-api-key': API_KEY, accept: 'application/json' },
+    });
+    const text = await response.text();
+    let data = null;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        data = text;
+    }
+    return { ok: response.ok, status: response.status, data };
+}
+/** Curated: one merged "what's live right now" answer across all games. */
+async function liveOverview() {
+    const games = [
+        { game: 'lol', path: '/lol/live', label: (m) => `${m.league ?? ''} ${m.team1 ?? m.teams?.[0] ?? '?'} vs ${m.team2 ?? m.teams?.[1] ?? '?'}` },
+        { game: 'dota2', path: '/dota2/matches/live', label: (m) => `${m.team1 ?? m.team1Name ?? '?'} vs ${m.team2 ?? m.team2Name ?? '?'}` },
+        { game: 'cs2', path: '/cs2/matches/live', label: (m) => `${m.team1 ?? m.team1Name ?? '?'} vs ${m.team2 ?? m.team2Name ?? '?'}` },
+        { game: 'cod', path: '/cod/matches/live', label: (m) => `${m.team1 ?? m.team1Name ?? '?'} vs ${m.team2 ?? m.team2Name ?? '?'}` },
+    ];
+    const sections = await Promise.all(games.map(async ({ game, path, label }) => {
+        const { ok, status, data } = await fetchJson(`${API_BASE}${path}`);
+        if (!ok)
+            return { game, count: null, note: `unavailable (HTTP ${status})`, matches: [] };
+        const rows = Array.isArray(data) ? data : Array.isArray(data?.data) ? data.data : [];
+        return {
+            game,
+            count: rows.length,
+            note: null,
+            matches: rows.slice(0, 5).map((row) => label(row).replace(/\s+/g, ' ').trim()),
+        };
+    }));
+    return textResult(JSON.stringify({ liveNow: sections }, null, 2));
+}
+/** Curated: /health plus a fallback authed probe to prove the key works. */
+async function apiHealth() {
+    async function probe(path) {
+        try {
+            const response = await fetch(`${API_BASE}${path}`, {
+                headers: { 'x-api-key': API_KEY, accept: 'application/json' },
+            });
+            return { ok: response.ok, status: response.status, body: await response.text(), headers: response.headers };
+        }
+        catch (error) {
+            return { ok: false, status: 0, body: error.message };
+        }
+    }
+    let answeredBy = 'health';
+    let result = await probe('/health');
+    if (!result.ok) {
+        const fallback = await probe('/lol/leagues');
+        if (fallback.ok) {
+            answeredBy = 'lol/leagues';
+            result = fallback;
+        }
+    }
+    return textResult(JSON.stringify({
+        probe: {
+            answeredBy,
+            ok: result.ok,
+            status: result.status,
+            body: present(result.body, 4096),
+        },
+        apiKey: {
+            valid: result.ok,
+            ...(result.ok ? {} : { hint: 'check CITO_API_KEY' }),
+        },
+        rateLimit: result.headers
+            ? {
+                tier: result.headers.get('x-cito-tier') ?? undefined,
+                limit: result.headers.get('x-ratelimit-limit') ?? undefined,
+                remaining: result.headers.get('x-ratelimit-remaining') ?? undefined,
+            }
+            : undefined,
+    }, null, 2));
+}
+async function main() {
+    const defs = defaultSourceDefs(API_BASE);
+    let state;
+    try {
+        state = await loadSpecSources({
+            defs,
+            apiBase: API_BASE,
+            cachePath: CACHE_PATH,
+            apiKey: API_KEY,
+            opportunisticKeys: OPPORTUNISTIC_SPEC_KEYS,
+        });
+    }
+    catch (error) {
+        console.error(`[cito-mcp] could not load any OpenAPI spec (no cache at ${CACHE_PATH}): ${error.message}`);
+        process.exit(1);
+    }
+    if (state.sources.length === 0) {
+        console.error(`[cito-mcp] no OpenAPI specs available (all skipped, no cache at ${CACHE_PATH})`);
+        process.exit(1);
+    }
+    for (const source of state.sources) {
+        log(`spec '${source.key}' loaded from ${source.origin} (${Object.keys(source.spec.paths).length} paths, base ${source.baseUrl})`);
+    }
+    log(`refreshing specs every ${REFRESH_MINUTES}min`);
+    let tools = new Map(generateAllTools(state.sources).map((tool) => [tool.name, tool]));
+    log(`generated ${tools.size} tools from ${state.sources.length} spec source(s)`);
+    const server = new Server({ name: 'cito-mcp', version: PACKAGE_VERSION }, { capabilities: { tools: {}, resources: {} } });
+    const CURATED_TOOLS = [
+        {
+            name: 'cito_live_overview',
+            description: 'Merged "what is live right now" across all games (LoL, Dota 2, CS2, COD): per-game live match count and the first few match labels. Use this before diving into per-game live endpoints.',
+            inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+            handler: liveOverview,
+        },
+        {
+            name: 'cito_api_health',
+            description: 'API gateway health plus an authenticated probe proving CITO_API_KEY works (returns key validity and rate-limit/tier headers when present).',
+            inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+            handler: apiHealth,
+        },
+    ];
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            ...[...tools.values()].map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            })),
+            ...CURATED_TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name } = request.params;
+        const args = (request.params.arguments ?? {});
+        const curated = CURATED_TOOLS.find((tool) => tool.name === name);
+        if (curated)
+            return curated.handler();
+        const tool = tools.get(name);
+        if (!tool)
+            return textResult(`unknown tool: ${name}`, true);
+        try {
+            return await executeApiCall({ tool, args, baseUrl: API_BASE, apiKey: API_KEY });
+        }
+        catch (error) {
+            return textResult(`request failed: ${error.message}`, true);
+        }
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [
+            {
+                uri: 'cito://llms.txt',
+                name: 'Cito API agent context (llms.txt)',
+                description: 'The Cito API llms.txt file — curated context about the API for AI agents.',
+                mimeType: 'text/plain',
+            },
+            {
+                uri: 'cito://openapi.json',
+                name: 'Cito OpenAPI spec (current)',
+                description: 'The OpenAPI spec this server generated its tools from (post-refresh).',
+                mimeType: 'application/json',
+            },
+        ],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        if (uri === 'cito://llms.txt') {
+            const origin = new URL(API_BASE).origin;
+            const response = await fetch(`${origin}/llms.txt`);
+            return {
+                contents: [{ uri, mimeType: 'text/plain', text: await response.text() }],
+            };
+        }
+        if (uri === 'cito://openapi.json') {
+            return {
+                contents: [{
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            sources: state.sources.map((source) => ({
+                                key: source.key,
+                                url: source.url,
+                                baseUrl: source.baseUrl,
+                                origin: source.origin,
+                                paths: Object.keys(source.spec.paths).length,
+                            })),
+                            specs: Object.fromEntries(state.sources.map((source) => [source.key, source.spec])),
+                        }, null, 2),
+                    }],
+            };
+        }
+        throw new Error(`unknown resource: ${uri}`);
+    });
+    const refreshTimer = setInterval(() => {
+        void (async () => {
+            const next = await refreshSpecSourcesIfDue(state, {
+                defs,
+                apiBase: API_BASE,
+                cachePath: CACHE_PATH,
+                apiKey: API_KEY,
+                refreshMinutes: REFRESH_MINUTES,
+                opportunisticKeys: OPPORTUNISTIC_SPEC_KEYS,
+            });
+            if (next) {
+                state = next;
+                tools = new Map(generateAllTools(state.sources).map((tool) => [tool.name, tool]));
+                log(`tools regenerated (${tools.size}) after spec refresh`);
+                try {
+                    void server.sendToolListChanged();
+                }
+                catch {
+                    // Client may not support list_changed — it will re-list on next use.
+                }
+            }
+        })();
+    }, 60_000);
+    refreshTimer.unref();
+    const httpPort = (() => {
+        const index = process.argv.indexOf('--http');
+        if (index === -1)
+            return null;
+        const port = Number(process.argv[index + 1]);
+        return Number.isInteger(port) && port > 0 ? port : null;
+    })();
+    if (httpPort) {
+        // Stateless Streamable HTTP: one transport, no session tracking.
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        await server.connect(transport);
+        const httpServer = createHttpServer(async (req, res) => {
+            if (req.url !== '/mcp') {
+                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;
+            try {
+                body = JSON.parse(raw || 'null');
+            }
+            catch {
+                res.writeHead(400, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ error: 'invalid JSON body' }));
+                return;
+            }
+            await transport.handleRequest(req, res, body);
+        });
+        httpServer.listen(httpPort, () => {
+            log(`cito-mcp listening on http://127.0.0.1:${httpPort}/mcp (${tools.size} spec tools + ${CURATED_TOOLS.length} curated)`);
+        });
+    }
+    else {
+        await server.connect(new StdioServerTransport());
+        log(`cito-mcp on stdio (${tools.size} spec tools + ${CURATED_TOOLS.length} curated)`);
+    }
+}
+await main();

package/dist/spec.js

@@ -0,0 +1,193 @@
+/**
+ * Multi-spec loading for cito-mcp.
+ *
+ * The global spec (…/api/v1/openapi.json) does NOT cover every game — LoL has
+ * its own spec (…/api/v1/lol/openapi.json) and other games may ship keyed
+ * specs later. Boot fetches a list of spec sources, opportunistically probes
+ * per-game spec URLs WITH the x-api-key header (skips 401/404 quietly), and
+ * merges everything that answered.
+ *
+ * Per-source base URL rule (data-driven, documented in README):
+ *   baseUrl = spec.servers[0].url when absolute, else CITO_API_BASE.
+ * The global spec's paths are relative to /api/v1 (its servers entry); the
+ * LoL spec's paths already include /api/v1/lol and its servers entry is the
+ * bare origin — so using servers[0].url + verbatim paths is correct for both.
+ * Escape hatch: CITO_SPEC_BASE_<KEY> (uppercased key, dashes → underscores).
+ *
+ * Cache: one merged .spec-cache.json storing per-source entries; any source
+ * that fails to fetch falls back to its cached entry.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+export const DEFAULT_API_BASE = 'https://api.citoapi.com/api/v1';
+/** Games probed opportunistically for keyed specs at boot (with the API key). */
+export const OPPORTUNISTIC_SPEC_KEYS = ['cod', 'fortnite', 'dota2', 'cs2', 'ufc'];
+/** stderr ONLY — stdout is the MCP stdio channel. */
+export function log(message) {
+    console.error(`[cito-mcp] ${message}`);
+}
+export function specRefreshMinutes() {
+    const parsed = Number(process.env.CITO_SPEC_REFRESH_MINUTES);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 60;
+}
+/** Key from a spec URL: the path segment before openapi.json ('global' when none). */
+export function specKeyFromUrl(url, apiBase) {
+    const base = apiBase.replace(/\/+$/, '');
+    if (url === `${base}/openapi.json`)
+        return 'global';
+    const match = url.replace(/\/+$/, '').match(/\/([^/]+)\/openapi\.json$/);
+    return match?.[1] ?? 'global';
+}
+/**
+ * Source list resolution:
+ *  - CITO_OPENAPI_URLS (comma-separated) overrides entirely.
+ *  - CITO_OPENAPI_URL (singular) overrides to a single source.
+ *  - Default: global + lol specs on CITO_API_BASE.
+ */
+export function defaultSourceDefs(apiBase, env = process.env) {
+    const base = apiBase.replace(/\/+$/, '');
+    if (env.CITO_OPENAPI_URLS) {
+        return env.CITO_OPENAPI_URLS
+            .split(',')
+            .map((url) => url.trim())
+            .filter(Boolean)
+            .map((url) => ({ key: specKeyFromUrl(url, base), url }));
+    }
+    if (env.CITO_OPENAPI_URL) {
+        const url = env.CITO_OPENAPI_URL.trim();
+        return [{ key: specKeyFromUrl(url, base), url }];
+    }
+    return [
+        { key: 'global', url: `${base}/openapi.json` },
+        { key: 'lol', url: `${base}/lol/openapi.json` },
+    ];
+}
+/** Per-source base URL: env escape hatch → servers[0].url when absolute → apiBase. */
+export function baseUrlForSpec(key, spec, apiBase, env = process.env) {
+    const envKey = `CITO_SPEC_BASE_${key.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
+    const override = env[envKey];
+    if (override)
+        return override.replace(/\/+$/, '');
+    const server = spec.servers?.[0]?.url;
+    if (server && /^https?:\/\//.test(server))
+        return server.replace(/\/+$/, '');
+    return apiBase.replace(/\/+$/, '');
+}
+export async function fetchSpec(url, opts = {}) {
+    const fetcher = opts.fetchImpl ?? fetch;
+    const headers = { accept: 'application/json' };
+    if (opts.apiKey)
+        headers['x-api-key'] = opts.apiKey;
+    const response = await fetcher(url, { headers });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+    }
+    const spec = (await response.json());
+    if (!spec || typeof spec !== 'object' || !spec.paths) {
+        throw new Error('response is not an OpenAPI document');
+    }
+    return spec;
+}
+export async function readSpecCache(cachePath) {
+    try {
+        const raw = await readFile(cachePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed && Array.isArray(parsed.sources) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeSpecCache(cachePath, sources) {
+    try {
+        const file = {
+            fetchedAt: new Date().toISOString(),
+            sources: sources.map((source) => ({
+                key: source.key,
+                url: source.url,
+                baseUrl: source.baseUrl,
+                spec: source.spec,
+            })),
+        };
+        await writeFile(cachePath, JSON.stringify(file), 'utf8');
+    }
+    catch (error) {
+        log(`spec cache write failed: ${error.message}`);
+    }
+}
+/**
+ * Load all sources: declared defs (network → cache fallback per source), then
+ * opportunistic per-game probes with the API key (skip non-200 quietly).
+ */
+export async function loadSpecSources(opts) {
+    const cache = await readSpecCache(opts.cachePath);
+    const sources = [];
+    const skipped = [];
+    let cacheDirty = false;
+    for (const def of opts.defs) {
+        try {
+            const spec = await fetchSpec(def.url, { apiKey: opts.apiKey, fetchImpl: opts.fetchImpl });
+            sources.push({
+                ...def,
+                spec,
+                baseUrl: baseUrlForSpec(def.key, spec, opts.apiBase),
+                origin: 'network',
+            });
+            cacheDirty = true;
+        }
+        catch (error) {
+            const cached = cache?.sources.find((entry) => entry.key === def.key);
+            if (cached) {
+                log(`spec '${def.key}' fetch failed (${error.message}) — using cached copy`);
+                sources.push({ ...def, spec: cached.spec, baseUrl: cached.baseUrl, origin: 'cache' });
+            }
+            else {
+                skipped.push({ ...def, reason: error.message });
+                log(`spec '${def.key}' skipped: ${error.message} (no cache)`);
+            }
+        }
+    }
+    const declaredKeys = new Set(opts.defs.map((def) => def.key));
+    const base = opts.apiBase.replace(/\/+$/, '');
+    for (const key of opts.opportunisticKeys ?? []) {
+        if (declaredKeys.has(key))
+            continue;
+        const url = `${base}/${key}/openapi.json`;
+        try {
+            const spec = await fetchSpec(url, { apiKey: opts.apiKey, fetchImpl: opts.fetchImpl });
+            log(`spec '${key}' discovered at ${url}`);
+            sources.push({ key, url, spec, baseUrl: baseUrlForSpec(key, spec, opts.apiBase), origin: 'network' });
+            cacheDirty = true;
+        }
+        catch (error) {
+            skipped.push({ key, url, reason: error.message });
+            log(`spec '${key}' skipped: ${error.message}`);
+        }
+    }
+    const networkSources = sources.filter((source) => source.origin === 'network');
+    if (cacheDirty && networkSources.length > 0) {
+        // Merge fresh sources over the previous cache so skipped keys keep theirs.
+        const merged = [...networkSources];
+        for (const cachedEntry of cache?.sources ?? []) {
+            if (!merged.some((source) => source.key === cachedEntry.key)) {
+                merged.push({ key: cachedEntry.key, url: cachedEntry.url, spec: cachedEntry.spec, baseUrl: cachedEntry.baseUrl, origin: 'cache' });
+            }
+        }
+        await writeSpecCache(opts.cachePath, merged);
+    }
+    return { sources, skipped, fetchedAt: Date.now() };
+}
+/** Re-fetch all sources when the refresh interval elapsed; null = not due. */
+export async function refreshSpecSourcesIfDue(state, opts) {
+    if (Date.now() - state.fetchedAt < opts.refreshMinutes * 60_000)
+        return null;
+    const next = await loadSpecSources(opts);
+    const changed = next.sources.length !== state.sources.length
+        || next.sources.some((source) => {
+            const previous = state.sources.find((entry) => entry.key === source.key);
+            return !previous || previous.spec !== source.spec;
+        });
+    if (!changed)
+        return { ...next, sources: state.sources, fetchedAt: Date.now() };
+    log(`specs refreshed (${next.sources.length} sources)`);
+    return next;
+}

package/dist/tools.js

@@ -0,0 +1,203 @@
+import { log } from './spec.js';
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options']);
+const MAX_REF_DEPTH = 4;
+/** Resolve local #/components/... $refs (bounded depth; cycles returned as-is). */
+export function resolveRefs(node, spec, depth = 0) {
+    if (depth > MAX_REF_DEPTH || node === null || typeof node !== 'object')
+        return node;
+    if (Array.isArray(node))
+        return node.map((item) => resolveRefs(item, spec, depth + 1));
+    const record = node;
+    if (typeof record.$ref === 'string' && record.$ref.startsWith('#/')) {
+        const target = record.$ref
+            .slice(2)
+            .split('/')
+            .reduce((acc, key) => {
+            if (acc && typeof acc === 'object')
+                return acc[key];
+            return undefined;
+        }, spec);
+        if (target === undefined)
+            return record;
+        return resolveRefs(target, spec, depth + 1);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        out[key] = resolveRefs(value, spec, depth + 1);
+    }
+    return out;
+}
+/** Body schema passthrough: refs resolved, readOnly stripped (agents can't send those). */
+export function simplifyBodySchema(schema, spec) {
+    const resolved = resolveRefs(schema, spec);
+    if (resolved === null || typeof resolved !== 'object')
+        return resolved;
+    if (Array.isArray(resolved))
+        return resolved.map((item) => simplifyBodySchema(item, spec));
+    const out = {};
+    for (const [key, value] of Object.entries(resolved)) {
+        if (key === 'readOnly')
+            continue;
+        out[key] = simplifyBodySchema(value, spec);
+    }
+    return out;
+}
+function capitalize(segment) {
+    return segment ? segment[0].toUpperCase() + segment.slice(1) : segment;
+}
+/**
+ * Fallback operation name when the spec has no operationId (the LoL spec
+ * ships none): method + capitalized path segments, {param} → By<Param>,
+ * leading api/version segments dropped.
+ * get /api/v1/lol/live/{gameId}/stats → getLolLiveStatsByGameId
+ */
+export function operationNameFromPath(method, path) {
+    const segments = path.split('/').filter(Boolean);
+    const parts = [method.toLowerCase()];
+    for (const segment of segments) {
+        if (segment === 'api' || /^v\d+$/.test(segment))
+            continue; // api + version segments
+        const param = segment.match(/^\{(.+)\}$/);
+        if (param) {
+            parts.push(`By${capitalize(param[1])}`);
+        }
+        else {
+            parts.push(capitalize(segment));
+        }
+    }
+    return parts.join('');
+}
+function sanitizeBase(operationName) {
+    return operationName.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+/**
+ * Tool name: cito_ + sanitized operation name. Exact sanitized collisions
+ * append the HTTP method, then a counter. (Cross-spec operationId collisions
+ * are handled earlier with the spec-key prefix — see generateAllTools.)
+ */
+export function sanitizeToolName(operationName, method, used) {
+    const base = `cito_${sanitizeBase(operationName)}`;
+    if (!used.has(base)) {
+        used.add(base);
+        return base;
+    }
+    const withMethod = `${base}_${method.toLowerCase()}`;
+    if (!used.has(withMethod)) {
+        used.add(withMethod);
+        return withMethod;
+    }
+    let counter = 2;
+    while (used.has(`${withMethod}_${counter}`))
+        counter += 1;
+    const name = `${withMethod}_${counter}`;
+    used.add(name);
+    return name;
+}
+function parameterDescription(param) {
+    const required = param.in === 'path' ? true : param.required === true;
+    const flags = [param.in, required ? 'required' : 'optional'].join(', ');
+    return `- ${param.name} (${flags})${param.description ? `: ${param.description}` : ''}`;
+}
+export function buildToolDescription(op) {
+    const parts = [];
+    if (op.summary)
+        parts.push(op.summary);
+    if (op.description && op.description !== op.summary)
+        parts.push(op.description);
+    const params = op.parameters ?? [];
+    if (params.length > 0) {
+        parts.push(`Parameters:\n${params.map(parameterDescription).join('\n')}`);
+    }
+    if (op.requestBody)
+        parts.push('Accepts a JSON request body (see the `body` argument).');
+    return parts.join('\n\n') || 'Cito API operation';
+}
+function jsonBodySchema(op, spec) {
+    const content = op.requestBody?.content ?? {};
+    const json = content['application/json'] ?? Object.values(content)[0];
+    return json?.schema ? simplifyBodySchema(json.schema, spec) : { type: 'object' };
+}
+export function buildOperationTool(method, path, op, source, used, namePrefix = '') {
+    const operationName = op.operationId || operationNameFromPath(method, path);
+    const pathParams = [];
+    const queryParams = [];
+    const properties = {};
+    const required = [];
+    for (const param of op.parameters ?? []) {
+        const schema = resolveRefs(param.schema ?? { type: 'string' }, source.spec);
+        properties[param.name] = {
+            ...schema,
+            ...(param.description ? { description: param.description } : {}),
+        };
+        if (param.in === 'path') {
+            pathParams.push(param.name);
+            required.push(param.name);
+        }
+        else if (param.in === 'query') {
+            queryParams.push(param.name);
+            if (param.required === true)
+                required.push(param.name);
+        }
+        // header/cookie params are not exposed as tool args (auth is server-side).
+    }
+    const hasBody = Boolean(op.requestBody);
+    if (hasBody) {
+        properties.body = {
+            ...jsonBodySchema(op, source.spec),
+            description: 'JSON request body.',
+        };
+        if (op.requestBody?.required === true)
+            required.push('body');
+    }
+    return {
+        name: sanitizeToolName(`${namePrefix}${operationName}`, method, used),
+        description: buildToolDescription(op),
+        inputSchema: {
+            type: 'object',
+            properties,
+            ...(required.length > 0 ? { required } : {}),
+            additionalProperties: false,
+        },
+        method: method.toUpperCase(),
+        path,
+        baseUrl: source.baseUrl,
+        sourceKey: source.key,
+        pathParams,
+        queryParams,
+        hasBody,
+    };
+}
+/**
+ * Generate tools for all loaded spec sources. On an operationId collision
+ * across sources, the LATER source's tool is prefixed with its spec key
+ * (cito_<key>_...) and the collision is logged to stderr.
+ */
+export function generateAllTools(sources) {
+    const tools = [];
+    const used = new Set();
+    const claimedOperationIds = new Set();
+    for (const source of sources) {
+        for (const [path, item] of Object.entries(source.spec.paths ?? {})) {
+            for (const [method, op] of Object.entries(item ?? {})) {
+                if (!HTTP_METHODS.has(method.toLowerCase()) || !op || typeof op !== 'object')
+                    continue;
+                let namePrefix = '';
+                if (op.operationId && claimedOperationIds.has(op.operationId)) {
+                    namePrefix = `${source.key}_`;
+                    log(`operationId collision: '${op.operationId}' also in spec '${source.key}' — tool prefixed cito_${source.key}_…`);
+                }
+                const tool = buildOperationTool(method, path, op, source, used, namePrefix);
+                if (tool) {
+                    tools.push(tool);
+                    if (op.operationId)
+                        claimedOperationIds.add(op.operationId);
+                }
+            }
+        }
+    }
+    return tools;
+}
+/** Single-spec convenience wrapper (tests / single-source setups). */
+export function generateTools(spec, baseUrl = '') {
+    return generateAllTools([{ key: 'global', baseUrl, spec }]);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "cito-mcp",
+  "version": "0.1.0",
+  "description": "Standalone MCP server for the Cito esports API — tools generated from the live OpenAPI spec, zero per-endpoint code.",
+  "type": "module",
+  "bin": {
+    "cito-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsx --test src/*.test.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.2"
+  }
+}