cito-mcp 0.1.0 → 0.2.2

package/dist/tools/meta.js

@@ -0,0 +1,609 @@
+/**
+ * Meta / power tools: list_capabilities, api_health, call_api.
+ */
+import { extractRows, fetchJson, gameNotIncludedHint, present } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
+import { boolSchema, gameSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
+const CATALOG_VERSION = '0.2.2';
+const TOOL_CATALOG = [
+    {
+        name: 'list_capabilities',
+        outcome: 'Curated catalog of tools, games, jobs, and recipes',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['app_scaffold'],
+        exampleArgs: { game: 'cs2', job: 'live_board' },
+        preferOver: ['call_api for discovery'],
+        doNotUse: 'When you already know the tool and have IDs',
+    },
+    {
+        name: 'api_health',
+        outcome: 'API reachability, key validity, tier, rate limits, included games',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['app_scaffold'],
+        exampleArgs: { includeGameProbes: true },
+        preferOver: ['probing random game endpoints'],
+        doNotUse: 'When you only need live scores — use live_matches',
+    },
+    {
+        name: 'resolve_entity',
+        outcome: 'Name → best typed entity ID(s) + game',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['team_page', 'player_form', 'match_page'],
+        exampleArgs: { q: 'T1', game: 'lol', type: 'team', limit: 5 },
+        preferOver: ['search_entities when chaining one ID'],
+        doNotUse: 'When you already have a stable id/slug',
+    },
+    {
+        name: 'search_entities',
+        outcome: 'Browse/search entities with type filter and pagination',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['team_page', 'player_form'],
+        exampleArgs: { game: 'cs2', q: 'vitality', type: 'team', limit: 20 },
+        preferOver: ['resolve_entity when browsing lists'],
+        doNotUse: 'For known entity profiles — use team_profile or player_profile',
+    },
+    {
+        name: 'live_matches',
+        outcome: 'Live matches board (single game or all primary)',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['live_board'],
+        exampleArgs: { game: 'all', limitPerGame: 10 },
+        preferOver: ['per-game call_api live probes'],
+        doNotUse: 'For upcoming fixtures — use upcoming_schedule',
+    },
+    {
+        name: 'upcoming_schedule',
+        outcome: 'Upcoming matches/events with filters',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['schedule'],
+        exampleArgs: { game: 'lol', hours: 72, team: 't1' },
+        preferOver: ['live_matches for future fixtures'],
+        doNotUse: 'For in-progress only — use live_matches',
+    },
+    {
+        name: 'match_summary',
+        outcome: 'Scoreline + performances + media stubs (match card)',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['match_page'],
+        exampleArgs: { game: 'cs2', matchId: 'cs2-match-123', view: 'summary' },
+        preferOver: ['match_details for chat/default UI'],
+        doNotUse: 'Without matchId; pre-match only → match_preview',
+    },
+    {
+        name: 'match_details',
+        outcome: 'Deep match package (timelines, live state, maps, media)',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['match_page'],
+        exampleArgs: { game: 'lol', matchId: 'lol-match-1', includeTimeline: true },
+        preferOver: ['match_summary only when summary is insufficient'],
+        doNotUse: 'First-pass live board — use live_matches + match_summary',
+    },
+    {
+        name: 'player_profile',
+        outcome: 'Player/fighter identity + recent form',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['player_form'],
+        exampleArgs: { game: 'cs2', playerId: 'cs2-player-1', recentLimit: 10 },
+        preferOver: ['manual multi-call career/trends via call_api'],
+        doNotUse: 'Full team roster → team_profile; unresolved name → resolve_entity',
+    },
+    {
+        name: 'team_profile',
+        outcome: 'Team/org card: identity, roster, recent form',
+        parallelSafe: true,
+        games: ['lol', 'cs2', 'dota2', 'cod'],
+        jobs: ['team_page'],
+        exampleArgs: { game: 'lol', slug: 't1' },
+        preferOver: ['separate roster + matches via call_api'],
+        doNotUse: 'UFC fighters → player_profile; unknown name → resolve_entity',
+    },
+    {
+        name: 'head_to_head',
+        outcome: 'Composed H2H record between two teams or fighters',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['h2h', 'preview'],
+        exampleArgs: { game: 'cs2', sideA: 'faze', sideB: 'navi', limit: 20 },
+        preferOver: ['agent-side double match-list filtering'],
+        doNotUse: 'Single-side form only → team_profile or player_profile',
+    },
+    {
+        name: 'standings',
+        outcome: 'League/event standings or world/division rankings',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['standings'],
+        exampleArgs: { game: 'cod', season: '2026' },
+        preferOver: ['raw standings via call_api'],
+        doNotUse: 'Single team form → team_profile; live scores → live_matches',
+    },
+    {
+        name: 'match_preview',
+        outcome: 'Pre-match briefing: sides, rosters/form, H2H stub',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['preview', 'match_page', 'app_scaffold'],
+        exampleArgs: { game: 'lol', teamA: 't1', teamB: 'gen-g', includeH2H: true },
+        preferOver: ['manual team_profile ×2 + head_to_head'],
+        doNotUse: 'Completed match recaps → match_summary',
+    },
+    {
+        name: 'event_card',
+        outcome: 'Event / fight-night card: identity + bout/match list (+ optional standings)',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES],
+        jobs: ['event_card', 'schedule', 'app_scaffold'],
+        exampleArgs: { game: 'ufc', eventIdOrSlug: 'ufc-300', includeBouts: true },
+        preferOver: ['call_api /ufc/events + bout expansion', 'N+1 match_summary for card list'],
+        doNotUse: 'Live-only strip → live_matches; single match recap → match_summary',
+    },
+    {
+        name: 'call_api',
+        outcome: 'Allowlisted raw REST escape hatch (unshaped data.raw)',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES, 'fortnite'],
+        jobs: ['app_scaffold'],
+        exampleArgs: { method: 'GET', path: '/cs2/rankings/teams', queryJson: '{"limit":20}' },
+        preferOver: [],
+        doNotUse: 'Any job covered by a curated tool',
+    },
+];
+const JOBS = [
+    { id: 'live_board', description: 'Ops/dashboard live strip', recommendedTools: ['live_matches', 'match_summary'] },
+    { id: 'match_page', description: 'Match center / recap', recommendedTools: ['match_summary', 'match_details', 'match_preview'] },
+    { id: 'team_page', description: 'Team/org profile screen', recommendedTools: ['resolve_entity', 'team_profile'] },
+    { id: 'player_form', description: 'Player/fighter form card', recommendedTools: ['resolve_entity', 'player_profile'] },
+    { id: 'standings', description: 'Tables and rankings', recommendedTools: ['standings'] },
+    { id: 'h2h', description: 'Historical rivalry record', recommendedTools: ['head_to_head'] },
+    { id: 'schedule', description: 'Upcoming fixtures/events', recommendedTools: ['upcoming_schedule', 'event_card'] },
+    { id: 'preview', description: 'Pre-match briefing', recommendedTools: ['match_preview'] },
+    { id: 'event_card', description: 'Event / fight-night card page', recommendedTools: ['event_card', 'resolve_entity', 'match_preview'] },
+    { id: 'app_scaffold', description: 'Design-time multi-screen prototype', recommendedTools: ['list_capabilities', 'api_health', 'live_matches'] },
+];
+const RECIPES = [
+    {
+        id: 'live_ops_board',
+        steps: ['api_health (optional)', 'live_matches', 'match_summary or match_details for selected matchId'],
+    },
+    {
+        id: 'team_page',
+        steps: ['resolve_entity { q, game, type: "team" }', 'team_profile with returned id/slug'],
+    },
+    {
+        id: 'match_center_completed',
+        steps: ['upcoming_schedule or live_matches for matchId', 'match_summary', 'optional match_details'],
+    },
+    {
+        id: 'ufc_fight_night_card',
+        steps: [
+            'resolve_entity { game: "ufc", type: "event", q } OR pass known eventIdOrSlug',
+            'event_card { game: "ufc", eventIdOrSlug, includeBouts: true }',
+            'optional match_preview for featured bout; standings { game: "ufc", scope: "division" }',
+        ],
+    },
+    {
+        id: 'player_form_lately',
+        steps: ['resolve_entity { type: "player"|"fighter", q, game }', 'player_profile with playerId|slug, includeTrends: true'],
+    },
+    {
+        id: 'match_preview_sides',
+        steps: [
+            'resolve_entity for each side (or use known slugs)',
+            'match_preview { game, teamA, teamB, includeH2H: true }',
+            'optional head_to_head for deeper rivalry list',
+        ],
+    },
+    {
+        id: 'app_scaffold',
+        steps: [
+            'list_capabilities + api_health (parallel)',
+            'Sample: live_matches, team_profile, standings, event_card',
+            'Production: typed REST client; MCP not in request path',
+        ],
+    },
+];
+const GAMES_META = [
+    { id: 'lol', label: 'League of Legends', depth: 'deep', notes: 'Slug teams; matchId lol-match-*; no native search' },
+    { id: 'cs2', label: 'Counter-Strike 2', depth: 'deep', notes: 'Prefixed ids; live path /cs2/live; trends/rankings' },
+    { id: 'dota2', label: 'Dota 2', depth: 'thin', notes: 'Numeric ids; radar; no standings/roster endpoints' },
+    { id: 'cod', label: 'Call of Duty (CDL)', depth: 'medium', notes: 'Org slugs; CDL standings; UUID match ids' },
+    { id: 'ufc', label: 'UFC / MMA', depth: 'medium', notes: 'Fighter slugs; boutId; live + rankings' },
+];
+export const listCapabilities = {
+    name: 'list_capabilities',
+    description: `Curated catalog of cito-mcp tools, games, jobs, and builder recipes.
+
+When to use:
+- Session start or "what can you do?"
+- Mapping app screens to tools
+- Filtering by game or job (live_board, match_page, team_page, player_form, standings, h2h, schedule, preview, event_card, app_scaffold)
+
+Prefer over: guessing from memory; exploring raw OpenAPI via call_api.
+
+Do not use when: you already know the tool and have IDs — call that tool directly.
+
+Parallel-safe: yes. Upstream cost: 0.
+Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            game: gameSchema({ allowAll: false, description: 'Filter catalog to one primary game; omit for all.' }),
+            job: {
+                type: 'string',
+                enum: JOBS.map((j) => j.id),
+                description: 'Filter by agent/builder job. Example: "team_page".',
+            },
+            q: stringSchema('Free-text filter over tool names and outcomes.', 'live'),
+            includeExamples: boolSchema('Include exampleArgs on each tool.', true),
+            includeRecipes: boolSchema('Include multi-step recipes.', true),
+        },
+    },
+    handler: async (args) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false });
+        if (gameParse.error && args.game != null && args.game !== '') {
+            return errorEnvelope({
+                code: 'UNSUPPORTED_GAME',
+                message: gameParse.error,
+                game: null,
+                source: 'list_capabilities',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const job = typeof args.job === 'string' ? args.job : undefined;
+        const q = typeof args.q === 'string' ? args.q.toLowerCase() : '';
+        const includeExamples = args.includeExamples !== false;
+        const includeRecipes = args.includeRecipes !== false;
+        let tools = TOOL_CATALOG.map((t) => {
+            const row = {
+                name: t.name,
+                outcome: t.outcome,
+                parallelSafe: t.parallelSafe,
+                games: t.games,
+                preferOver: t.preferOver,
+                doNotUse: t.doNotUse,
+            };
+            if (includeExamples)
+                row.exampleArgs = t.exampleArgs;
+            return row;
+        });
+        if (gameParse.game) {
+            tools = tools.filter((t) => {
+                const games = t.games;
+                return games.includes(gameParse.game) || games.includes('fortnite');
+            });
+        }
+        if (job) {
+            const jobDef = JOBS.find((j) => j.id === job);
+            if (jobDef) {
+                const set = new Set(jobDef.recommendedTools);
+                tools = tools.filter((t) => set.has(t.name) || t.name === 'list_capabilities');
+            }
+        }
+        if (q) {
+            tools = tools.filter((t) => String(t.name).includes(q) ||
+                String(t.outcome).toLowerCase().includes(q));
+        }
+        return successEnvelope({
+            source: 'list_capabilities',
+            game: gameParse.game ?? null,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 0,
+            data: {
+                version: CATALOG_VERSION,
+                tools,
+                games: GAMES_META.filter((g) => !gameParse.game || g.id === gameParse.game),
+                jobs: job ? JOBS.filter((j) => j.id === job) : JOBS,
+                ...(includeRecipes ? { recipes: RECIPES } : {}),
+            },
+        });
+    },
+};
+export const apiHealth = {
+    name: 'api_health',
+    description: `API reachability, API key validity, plan tier, rate-limit headers, and best-effort included games.
+
+When to use:
+- Once per session before heavy work
+- After 401/403/UNSUPPORTED_GAME/RATE_LIMIT
+- App scaffolding entitlement checks
+
+Prefer over: probing random game endpoints to test the key.
+
+Do not use when: you only need live scores — use live_matches.
+
+Parallel-safe: yes. Upstream cost: 1–6.
+Example: { "includeGameProbes": true }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            includeGameProbes: boolSchema('If true, light allSettled probes per primary game product/status path.', false),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        const health = await fetchJson(ctx, '/health');
+        upstreamCalls += 1;
+        rateLimit = health.headers;
+        let keyValid = false;
+        let reachable = health.ok;
+        let answeredBy = '/health';
+        let authedStatus = health.status;
+        if (!health.ok) {
+            const fallback = await fetchJson(ctx, '/lol/leagues');
+            upstreamCalls += 1;
+            rateLimit = fallback.headers;
+            if (fallback.ok) {
+                keyValid = true;
+                reachable = true;
+                answeredBy = '/lol/leagues';
+                authedStatus = fallback.status;
+            }
+            else if (fallback.status === 401 || fallback.status === 403) {
+                return errorEnvelope({
+                    code: mapHttpToCode(fallback.status),
+                    message: 'API key invalid or unauthorized',
+                    game: null,
+                    source: 'api_health',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit: fallback.headers,
+                    httpStatus: fallback.status,
+                });
+            }
+            else {
+                // try product root
+                const cs2 = await fetchJson(ctx, '/cs2');
+                upstreamCalls += 1;
+                rateLimit = cs2.headers;
+                if (cs2.ok) {
+                    keyValid = true;
+                    reachable = true;
+                    answeredBy = '/cs2';
+                    authedStatus = cs2.status;
+                }
+                else {
+                    keyValid = false;
+                    authedStatus = cs2.status;
+                }
+            }
+        }
+        else {
+            // health may be unauthenticated — confirm key with light authed probe
+            const probe = await fetchJson(ctx, '/lol/leagues');
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...probe.headers };
+            keyValid = probe.ok || probe.status === 403; // 403 may still mean key accepted but gated
+            if (probe.ok)
+                answeredBy = '/health+/lol/leagues';
+            if (probe.status === 401) {
+                keyValid = false;
+            }
+            authedStatus = probe.ok ? probe.status : health.status;
+        }
+        const includedGames = [];
+        const probes = [];
+        if (args.includeGameProbes === true) {
+            const paths = [
+                { game: 'lol', path: '/lol/status' },
+                { game: 'cs2', path: '/cs2' },
+                { game: 'dota2', path: '/dota2' },
+                { game: 'cod', path: '/cod' },
+                { game: 'ufc', path: '/ufc/live/health' },
+            ];
+            const results = await Promise.all(paths.map(async ({ game, path }) => {
+                const res = await fetchJson(ctx, path);
+                return { game, path, res };
+            }));
+            upstreamCalls += results.length;
+            for (const { game, res } of results) {
+                probes.push({ game, ok: res.ok, httpStatus: res.status });
+                if (res.ok)
+                    includedGames.push(game);
+                else if (res.status === 403 && gameNotIncludedHint(res.data)) {
+                    // not included
+                }
+                else if (res.status !== 401 && res.status !== 404) {
+                    // ambiguous — still list as probed
+                }
+                rateLimit = { ...rateLimit, ...res.headers };
+            }
+        }
+        else if (keyValid) {
+            includedGames.push(...PRIMARY_GAMES);
+        }
+        return successEnvelope({
+            source: 'api_health',
+            game: null,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            data: {
+                reachable,
+                keyValid,
+                answeredBy,
+                httpStatus: authedStatus,
+                tier: rateLimit.tier ?? null,
+                rateLimit,
+                includedGames,
+                ...(probes.length ? { probes } : {}),
+            },
+        });
+    },
+};
+const ALLOWLIST_PREFIXES = ['/health', '/lol', '/cs2', '/dota2', '/cod', '/ufc', '/fortnite'];
+function pathAllowed(path) {
+    if (!path.startsWith('/') || path.startsWith('//'))
+        return false;
+    if (path.includes('://') || path.includes('..'))
+        return false;
+    const normalized = path.split('?')[0].replace(/\/+$/, '') || '/';
+    return ALLOWLIST_PREFIXES.some((p) => normalized === p || normalized.startsWith(`${p}/`));
+}
+export const callApi = {
+    name: 'call_api',
+    description: `Power escape hatch: allowlisted Cito REST call with unshaped raw JSON in data.raw.
+
+When to use:
+- Long-tail paths not yet curated (Fortnite, CS2 leaderboards, niche stats)
+- Debugging payloads while building an app
+- User explicitly knows an OpenAPI path
+
+Prefer curated tools for all standard jobs (live, schedule, profiles, standings, H2H, previews).
+
+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.
+Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
+
+Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
+Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"page\\":1,\\"limit\\":20}" }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['path'],
+        properties: {
+            method: {
+                type: 'string',
+                enum: ['GET', 'POST'],
+                default: 'GET',
+                description: 'HTTP method. Prefer GET. Example: "GET".',
+            },
+            path: stringSchema('Path starting with /. Allowlisted prefixes only. Example: "/cs2/rankings/teams".', '/cs2/rankings/teams'),
+            queryJson: {
+                type: 'string',
+                default: '{}',
+                description: 'Stringified JSON object of query params. Example: "{\\"page\\":1,\\"limit\\":20}".',
+            },
+            bodyJson: {
+                type: 'string',
+                description: 'Stringified JSON body for POST only (rare).',
+            },
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const method = String(args.method ?? 'GET').toUpperCase();
+        const path = typeof args.path === 'string' ? args.path.trim() : '';
+        if (!path) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'path is required',
+                game: null,
+                source: 'call_api',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        if (method !== 'GET' && method !== 'POST') {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'method must be GET or POST',
+                game: null,
+                source: 'call_api',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        if (!pathAllowed(path)) {
+            return errorEnvelope({
+                code: 'PATH_NOT_ALLOWED',
+                message: `Path not allowlisted: ${path}`,
+                game: null,
+                source: 'call_api',
+                requestId,
+                tookMs: Date.now() - started,
+                hint: 'Use prefixes /health /lol /cs2 /dota2 /cod /ufc /fortnite',
+            });
+        }
+        let query = {};
+        if (typeof args.queryJson === 'string' && args.queryJson.trim()) {
+            try {
+                const parsed = JSON.parse(args.queryJson);
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                    throw new Error('queryJson must be a JSON object');
+                }
+                query = parsed;
+            }
+            catch (e) {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: `Invalid queryJson: ${e.message}`,
+                    game: null,
+                    source: 'call_api',
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+        }
+        let body;
+        if (method === 'POST' && typeof args.bodyJson === 'string' && args.bodyJson.trim()) {
+            try {
+                body = JSON.parse(args.bodyJson);
+            }
+            catch (e) {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: `Invalid bodyJson: ${e.message}`,
+                    game: null,
+                    source: 'call_api',
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+        }
+        const res = await fetchJson(ctx, path, { method, query, body });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Upstream HTTP ${res.status} for ${method} ${path}`,
+                game: null,
+                source: 'call_api',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                rateLimit: res.headers,
+                httpStatus: res.status,
+                details: { path, method, bodyPreview: present(res.text, 2000) },
+            });
+        }
+        return successEnvelope({
+            source: 'call_api',
+            game: null,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            warnings: ['Unshaped raw response — prefer curated tools when available'],
+            data: {
+                raw: res.data,
+                httpStatus: res.status,
+                path,
+                method,
+            },
+        });
+    },
+};
+export const metaTools = [listCapabilities, apiHealth, callApi];
+// silence unused import in case extractRows needed later
+void extractRows;