cito-mcp 0.1.0 → 0.2.2

package/dist/index.js

@@ -1,196 +1,84 @@
 #!/usr/bin/env node
 /**
- * cito-mcp — standalone MCP server for the Cito esports API.
+ * cito-mcp — curated 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.
+ * 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, CITO_OPENAPI_URL, CITO_SPEC_REFRESH_MINUTES.
+ * Optional env: CITO_API_BASE (default https://api.citoapi.com/api/v1).
  */
 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';
+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';
+const PACKAGE_VERSION = '0.2.2';
 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');
+        '  claude mcp add cito -e 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));
-}
+const ctx = {
+    apiKey: API_KEY,
+    baseUrl: API_BASE,
+};
 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,
-        },
-    ];
+    const server = new Server({
+        name: 'cito-mcp',
+        version: PACKAGE_VERSION,
+    }, {
+        capabilities: { tools: {}, resources: {} },
+        instructions: SERVER_INSTRUCTIONS,
+    });
     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 })),
-        ],
+        tools: allTools.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);
+        const tool = getTool(name);
+        if (!tool) {
+            return toMcpResult(errorEnvelope({
+                code: 'VALIDATION',
+                message: `Unknown tool: ${name}`,
+                game: null,
+                source: 'cito-mcp',
+                recover: ['Call list_capabilities to see available tools'],
+            }));
         }
+        return runTool(tool, args, ctx);
     });
     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.',
+                description: 'The Cito API llms.txt file — curated context about the API for AI agents (fetched on read).',
                 mimeType: 'text/plain',
             },
+            {
+                uri: 'cito://capabilities',
+                name: 'cito-mcp capabilities summary',
+                description: 'Static summary of curated tools, games, and preferred workflow.',
+                mimeType: 'application/json',
+            },
             {
                 uri: 'cito://openapi.json',
-                name: 'Cito OpenAPI spec (current)',
-                description: 'The OpenAPI spec this server generated its tools from (post-refresh).',
+                name: 'Cito OpenAPI (public fetch)',
+                description: 'Live public OpenAPI snapshot for typed clients (not the tool catalog source).',
                 mimeType: 'application/json',
             },
         ],
@@ -198,56 +86,71 @@ async function main() {
     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() }],
-            };
+            const origin = new URL(API_BASE.endsWith('/api/v1') ? API_BASE.slice(0, -'/api/v1'.length) || API_BASE : API_BASE).origin;
+            try {
+                const response = await fetch(`${origin}/llms.txt`);
+                return {
+                    contents: [{ uri, mimeType: 'text/plain', text: await response.text() }],
+                };
+            }
+            catch (error) {
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'text/plain',
+                            text: `llms.txt unavailable: ${error.message}`,
+                        },
+                    ],
+                };
+            }
         }
-        if (uri === 'cito://openapi.json') {
+        if (uri === 'cito://capabilities') {
             return {
-                contents: [{
+                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])),
+                            version: PACKAGE_VERSION,
+                            tools: allTools.map((t) => t.name),
+                            games: ['lol', 'cs2', 'dota2', 'cod', 'ufc'],
+                            workflow: [
+                                'list_capabilities / api_health',
+                                'resolve_entity → profiles / match tools',
+                                'live_matches / upcoming_schedule',
+                                'match_summary → match_details',
+                                'call_api escape hatch only',
+                            ],
                         }, null, 2),
-                    }],
+                    },
+                ],
             };
         }
+        if (uri === 'cito://openapi.json') {
+            try {
+                const response = await fetch(`${API_BASE}/openapi.json`, {
+                    headers: { 'x-api-key': API_KEY, accept: 'application/json' },
+                });
+                const text = await response.text();
+                return {
+                    contents: [{ uri, mimeType: 'application/json', text }],
+                };
+            }
+            catch (error) {
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'application/json',
+                            text: JSON.stringify({ error: error.message }),
+                        },
+                    ],
+                };
+            }
+        }
         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)
@@ -256,7 +159,6 @@ async function main() {
         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) => {
@@ -280,12 +182,12 @@ async function main() {
             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)`);
+            log(`cito-mcp ${PACKAGE_VERSION} listening on http://127.0.0.1:${httpPort}/mcp (${allTools.length} curated tools)`);
         });
     }
     else {
         await server.connect(new StdioServerTransport());
-        log(`cito-mcp on stdio (${tools.size} spec tools + ${CURATED_TOOLS.length} curated)`);
+        log(`cito-mcp ${PACKAGE_VERSION} on stdio (${allTools.length} curated tools)`);
     }
 }
 await main();

package/dist/instructions.js

@@ -0,0 +1,80 @@
+/**
+ * MCP server instructions — agent operating manual (embedded at connect).
+ * Keep under ~1.5k tokens. Tool names match the curated catalog (no cito_ prefix).
+ */
+export const SERVER_INSTRUCTIONS = `# Cito MCP — agent operating manual
+
+You are connected to Cito esports data (read-only). Prefer curated outcome tools over raw REST. Production apps must call Cito REST with the user's API key; use this MCP to design, prototype, and resolve IDs — not as a multi-tenant runtime bus.
+
+## Hard rules
+
+1. **Never invent IDs.** Do not guess matchId, gameId, playerId, team slug, eventId, or boutId. Always obtain IDs from a prior tool result (resolve, live, schedule, search, or list). If the user gives a name ("T1", "s1mple", "UFC 300"), call resolve_entity/search_entities first.
+2. **Resolve before deep.** Name → ID/slug → summary/page → deep stats. Skip resolve only when the user already provided a Cito ID/slug.
+3. **One screen, one composite.** Prefer a page/summary tool over stitching 4–6 thin GETs.
+4. **Honor the envelope.** Parse ok, data, pagination, partial, error, meta.rateLimit, meta.entities. Partial section failures are not total failures — use successful sections.
+5. **Read-only.** All curated tools are safe to retry except where error.retryable is false for bad args / entitlement.
+
+## Game parameter
+
+game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | 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.
+- Fortnite and other titles may appear via call_api/resources; do not assume they are in the curated enum until list_capabilities says so.
+
+## Preferred tool order
+
+1. Unsure → list_capabilities (filter by game or job). Optional: api_health for key/tier/included games.
+2. Name without ID → resolve_entity (best match) or search_entities (browse). Reuse returned id/slug.
+3. Live / upcoming → live_matches; upcoming_schedule.
+4. Match UI / recap → match_summary first. match_details only for timelines, full maps, demos, live state.
+5. Team page → team_profile. Player form → player_profile. Tables/ranks → standings.
+6. Pre-match → match_preview. Rivalry → head_to_head. Event / fight-night card → event_card.
+7. Escape hatch → call_api (allowlisted path prefixes; prefer GET). Prefer curated tools.
+
+Mnemonic: resolve → live/schedule → summary → deep.
+
+## Parallel vs sequence
+
+Parallel-safe: independent reads (team_profile A ∥ team_profile B; live_matches ∥ api_health). Cap ~3–5 concurrent agent tools; check meta.rateLimit.remaining.
+
+Serial required: resolve → detail; pagination (cursor from page N only); live board → selected match deep-dive.
+
+Prefer server-side fan-out inside composites (partial[] recovery) over agent N+1.
+
+## Pagination
+
+Lists use pagination: { limit, offset?, total?, hasMore, nextCursor, prevCursor }. Default limit 20, max 50. Loop with cursor: pagination.nextCursor and the same filters. Never invent cursors. Empty list is ok:true with items:[].
+
+## Errors
+
+ok:false → read error.code (VALIDATION, NOT_FOUND, UNSUPPORTED_GAME, RATE_LIMIT, UNAUTHORIZED, UPSTREAM, PATH_NOT_ALLOWED, NOT_IMPLEMENTED). Follow error.recover[]. Retry only when retryable.
+
+ok:true with partial[] → use successful sections; do not treat partial as total fail.
+ok:true with meta.warnings[] → filters or depth degraded; do not assume ignored filters applied.
+resolve_entity ambiguity is soft: ok:true with data.needsDisambiguation and data.candidates — pick a candidate; do not wait for AMBIGUOUS_ENTITY.
+
+## Recipes
+
+Live board: api_health (optional) → live_matches → match_summary for selected matchId.
+Team page: resolve_entity {type:team} → team_profile.
+Player card: resolve_entity {type:player|fighter} → player_profile.
+Fight night / event card: resolve_entity {type:event} → event_card {includeBouts:true} → match_preview for a featured bout.
+Match preview (named sides): resolve_entity each side (optional) → match_preview {teamA, teamB}.
+App scaffold: list_capabilities ∥ api_health ∥ live_matches, then one composite per screen.
+
+## Resources
+
+- cito://llms.txt — product context when available
+- cito://capabilities — catalog summary
+- cito://openapi.json — optional public OpenAPI fetch for typed clients
+
+## What not to do
+
+- Invent match/player/team IDs from memory.
+- Parallel-paginate the same list with different cursors.
+- N+1 match_details for every live row.
+- Retry UNSUPPORTED_GAME or VALIDATION unchanged.
+- Ship production traffic through MCP.
+- Flood odds/timelines when a summary answers the question.
+`;

package/dist/tools/index.js

@@ -0,0 +1,23 @@
+import { metaTools } from './meta.js';
+import { resolveTools } from './resolve.js';
+import { liveTools } from './live.js';
+import { matchTools } from './match.js';
+import { playerTools } from './player.js';
+import { teamTools } from './team.js';
+import { standingsTools } from './standings.js';
+import { insightTools } from './insight.js';
+/** Curated outcome-tool catalog (15 tools). Order matches preferred cold-start ladder. */
+export const allTools = [
+    ...metaTools.filter((t) => t.name === 'list_capabilities' || t.name === 'api_health'),
+    ...resolveTools,
+    ...liveTools,
+    ...matchTools,
+    ...playerTools,
+    ...teamTools,
+    ...standingsTools,
+    ...insightTools,
+    ...metaTools.filter((t) => t.name === 'call_api'),
+];
+export function getTool(name) {
+    return allTools.find((t) => t.name === name);
+}