cito-mcp 0.1.0 → 0.2.2

package/dist/tools/match.js

@@ -0,0 +1,464 @@
+/**
+ * match_summary + match_details
+ */
+import { extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
+import { normalizeMatch } from './normalize.js';
+import { boolSchema, gameSchema, isPrimaryGame, parseGame, stringSchema, } from './types.js';
+async function getSection(ctx, path, query) {
+    return fetchJson(ctx, path, { query });
+}
+function matchCore(game, matchId, raw) {
+    const m = normalizeMatch(game, raw);
+    const r = asRecord(raw) ?? {};
+    return {
+        matchId: m.matchId !== 'unknown' ? m.matchId : matchId,
+        game,
+        status: m.status,
+        startTime: m.startTime,
+        endTime: pickString(r.endTime, r.endedAt, r.finishedAt) ?? null,
+        bestOf: r.bestOf ?? r.bo ?? null,
+        score: {
+            team1: m.team1?.score ?? null,
+            team2: m.team2?.score ?? null,
+        },
+        team1: m.team1,
+        team2: m.team2,
+        event: m.event,
+        league: m.league,
+        rawStatus: pickString(r.status, r.state) ?? null,
+    };
+}
+function primaryPath(game, matchId) {
+    switch (game) {
+        case 'lol':
+            return `/lol/matches/${encodeURIComponent(matchId)}`;
+        case 'cs2':
+            return `/cs2/matches/${encodeURIComponent(matchId)}`;
+        case 'dota2':
+            return `/dota2/matches/${encodeURIComponent(matchId)}`;
+        case 'cod':
+            return `/cod/matches/${encodeURIComponent(matchId)}`;
+        case 'ufc':
+            return `/ufc/bouts/${encodeURIComponent(matchId)}`;
+    }
+}
+export const matchSummary = {
+    name: 'match_summary',
+    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
+
+When to use:
+- Match recap / default match UI
+- After user selects a live or completed matchId
+
+Prefer over match_details for chat answers and default UIs.
+Prefer match_details for timelines, full map trees, live state, advanced packages.
+
+Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
+
+Parallel-safe: yes. Upstream cost: 2–5.
+Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includePlayerStats": true }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'matchId'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            matchId: stringSchema('Game-native match id (UFC: boutId). Example: "cs2-match-123".', 'cs2-match-123'),
+            view: {
+                type: 'string',
+                enum: ['summary', 'full'],
+                default: 'summary',
+                description: 'Payload weight. Default summary.',
+            },
+            includePlayerStats: boolSchema('Include player performances when available.', true),
+            includeMedia: boolSchema('Include demos/VODs when the API provides them.', true),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'match_summary',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        const matchId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+        if (!matchId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'matchId is required',
+                game,
+                source: 'match_summary',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const includePlayerStats = args.includePlayerStats !== false;
+        const includeMedia = args.includeMedia !== false;
+        const view = args.view === 'full' ? 'full' : 'summary';
+        const partial = [];
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        const primary = await getSection(ctx, primaryPath(game, matchId));
+        upstreamCalls += 1;
+        rateLimit = primary.headers;
+        if (!primary.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(primary.status, { gameNotIncluded: gameNotIncludedHint(primary.data) }),
+                message: `Match not found or unavailable: ${matchId}`,
+                game,
+                source: 'match_summary',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                rateLimit: primary.headers,
+                httpStatus: primary.status,
+            });
+        }
+        const match = matchCore(game, matchId, primary.data);
+        let playerPerformances = [];
+        let media = {
+            demos: [],
+            vods: [],
+            notes: null,
+        };
+        let gamesOrMaps = [];
+        let keyEvents = [];
+        const enrich = [];
+        if (includePlayerStats) {
+            enrich.push((async () => {
+                const paths = [];
+                if (game === 'lol')
+                    paths.push(`/lol/matches/${encodeURIComponent(matchId)}/player-stats`);
+                if (game === 'cs2')
+                    paths.push(`/cs2/matches/${encodeURIComponent(matchId)}/player-stats`);
+                if (game === 'dota2')
+                    paths.push(`/dota2/matches/${encodeURIComponent(matchId)}/player-stats`);
+                if (game === 'cod')
+                    paths.push(`/cod/matches/${encodeURIComponent(matchId)}/player-stats`);
+                if (game === 'ufc')
+                    paths.push(`/ufc/bouts/${encodeURIComponent(matchId)}/stats`);
+                for (const p of paths) {
+                    const res = await getSection(ctx, p);
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...res.headers };
+                    if (!res.ok) {
+                        partial.push(partialFromRejection('playerPerformances', {
+                            code: mapHttpToCode(res.status),
+                            message: `player stats HTTP ${res.status}`,
+                            httpStatus: res.status,
+                        }));
+                    }
+                    else {
+                        playerPerformances = extractRows(res.data);
+                        if (playerPerformances.length === 0 && asRecord(res.data)) {
+                            playerPerformances = [res.data];
+                        }
+                    }
+                }
+            })());
+        }
+        if (includeMedia && game === 'cs2') {
+            enrich.push((async () => {
+                const res = await getSection(ctx, `/cs2/matches/${encodeURIComponent(matchId)}/demos`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok)
+                    media.demos = extractRows(res.data);
+                else {
+                    partial.push(partialFromRejection('media', {
+                        code: mapHttpToCode(res.status),
+                        message: `demos HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+        }
+        // games/maps
+        enrich.push((async () => {
+            let path = null;
+            if (game === 'lol')
+                path = `/lol/matches/${encodeURIComponent(matchId)}/games`;
+            if (game === 'cod')
+                path = `/cod/matches/${encodeURIComponent(matchId)}/maps`;
+            if (game === 'ufc')
+                path = `/ufc/bouts/${encodeURIComponent(matchId)}/rounds`;
+            if (!path)
+                return;
+            const res = await getSection(ctx, path);
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...res.headers };
+            if (res.ok) {
+                gamesOrMaps = extractRows(res.data);
+                if (view === 'summary')
+                    gamesOrMaps = gamesOrMaps.slice(0, 5);
+            }
+            else {
+                partial.push(partialFromRejection('gamesOrMaps', {
+                    code: mapHttpToCode(res.status),
+                    message: `games/maps HTTP ${res.status}`,
+                    httpStatus: res.status,
+                }));
+            }
+        })());
+        await Promise.all(enrich);
+        const scoreline = {
+            display: `${match.team1?.name ?? '?'} ${match.score.team1 ?? '-'} : ${match.score.team2 ?? '-'} ${match.team2?.name ?? '?'}`,
+            team1: match.score.team1,
+            team2: match.score.team2,
+        };
+        if (view === 'summary' && playerPerformances.length > 10) {
+            playerPerformances = playerPerformances.slice(0, 10);
+        }
+        return successEnvelope({
+            source: 'match_summary',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            partial: partial.length ? partial : undefined,
+            entities: { games: [game], ids: { matchId: match.matchId } },
+            data: {
+                match,
+                scoreline,
+                keyEvents,
+                playerPerformances,
+                media,
+                gamesOrMaps,
+            },
+        });
+    },
+};
+export const matchDetails = {
+    name: 'match_details',
+    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
+
+When to use:
+- Analyst deep dive
+- Live in-game window (LoL/CS2/UFC)
+- Full demo list
+
+Prefer over match_summary only when summary is insufficient.
+Prefer match_summary for short answers and default cards.
+
+Do not use when: first-pass live board (use live_matches + match_summary).
+
+Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
+If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
+
+Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
+Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "includeLiveState": false }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'matchId'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            matchId: stringSchema('Game-native match id (UFC boutId).', 'lol-match-1'),
+            gameId: stringSchema('LoL per-game live window target when distinct from matchId.'),
+            sections: {
+                type: 'array',
+                items: {
+                    type: 'string',
+                    enum: ['base', 'playerStats', 'gamesOrMaps', 'timeline', 'liveState', 'media', 'advanced'],
+                },
+                description: 'Explicit section list; defaults to base+playerStats+gamesOrMaps+media.',
+            },
+            includeTimeline: boolSchema('Include timeline section (heavy).', false),
+            includeLiveState: boolSchema('Include live state/snapshots.', false),
+            includeAdvanced: boolSchema('Include advanced packages when available (LoL).', false),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'match_details',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        const matchId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+        if (!matchId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'matchId is required',
+                game,
+                source: 'match_details',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const gameId = typeof args.gameId === 'string' ? args.gameId : undefined;
+        let wanted;
+        if (Array.isArray(args.sections) && args.sections.length) {
+            wanted = new Set(args.sections.map(String));
+        }
+        else {
+            wanted = new Set(['base', 'playerStats', 'gamesOrMaps', 'media']);
+            if (args.includeTimeline === true)
+                wanted.add('timeline');
+            if (args.includeLiveState === true)
+                wanted.add('liveState');
+            if (args.includeAdvanced === true)
+                wanted.add('advanced');
+        }
+        const partial = [];
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        const sections = {
+            base: null,
+            playerStats: null,
+            gamesOrMaps: null,
+            timeline: null,
+            liveState: null,
+            media: null,
+            advanced: null,
+        };
+        // base is primary
+        if (wanted.has('base')) {
+            const res = await getSection(ctx, primaryPath(game, matchId));
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `Match not found or unavailable: ${matchId}`,
+                    game,
+                    source: 'match_details',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit: res.headers,
+                    httpStatus: res.status,
+                });
+            }
+            sections.base = matchCore(game, matchId, res.data);
+        }
+        const tasks = [];
+        const load = (section, path, query) => {
+            tasks.push((async () => {
+                const res = await getSection(ctx, path, query);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (!res.ok) {
+                    partial.push(partialFromRejection(section, {
+                        code: mapHttpToCode(res.status),
+                        message: `${section} HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                    sections[section] = null;
+                }
+                else {
+                    sections[section] = res.data;
+                }
+            })());
+        };
+        if (wanted.has('playerStats')) {
+            if (game === 'lol')
+                load('playerStats', `/lol/matches/${encodeURIComponent(matchId)}/player-stats`);
+            if (game === 'cs2')
+                load('playerStats', `/cs2/matches/${encodeURIComponent(matchId)}/player-stats`);
+            if (game === 'dota2')
+                load('playerStats', `/dota2/matches/${encodeURIComponent(matchId)}/player-stats`);
+            if (game === 'cod')
+                load('playerStats', `/cod/matches/${encodeURIComponent(matchId)}/player-stats`);
+            if (game === 'ufc')
+                load('playerStats', `/ufc/bouts/${encodeURIComponent(matchId)}/stats`);
+        }
+        if (wanted.has('gamesOrMaps')) {
+            if (game === 'lol')
+                load('gamesOrMaps', `/lol/matches/${encodeURIComponent(matchId)}/games`);
+            if (game === 'cod')
+                load('gamesOrMaps', `/cod/matches/${encodeURIComponent(matchId)}/maps`);
+            if (game === 'ufc')
+                load('gamesOrMaps', `/ufc/bouts/${encodeURIComponent(matchId)}/rounds`);
+            if (game === 'cs2' || game === 'dota2') {
+                // no dedicated maps list — leave null with note via partial only if requested alone
+                sections.gamesOrMaps = sections.base;
+            }
+        }
+        if (wanted.has('timeline')) {
+            if (game === 'lol')
+                load('timeline', `/lol/matches/${encodeURIComponent(matchId)}/timeline`);
+            else {
+                partial.push(partialFromRejection('timeline', {
+                    code: 'NOT_IMPLEMENTED',
+                    message: `Timeline not available for ${game} via curated paths`,
+                }));
+            }
+        }
+        if (wanted.has('liveState')) {
+            if (game === 'lol' && gameId) {
+                load('liveState', `/lol/live/${encodeURIComponent(gameId)}/window`);
+            }
+            else if (game === 'cs2') {
+                load('liveState', `/cs2/live/${encodeURIComponent(matchId)}/state`);
+            }
+            else if (game === 'ufc') {
+                load('liveState', `/ufc/live/${encodeURIComponent(matchId)}/state`);
+            }
+            else {
+                partial.push(partialFromRejection('liveState', {
+                    code: 'NOT_IMPLEMENTED',
+                    message: game === 'lol'
+                        ? 'Pass gameId for LoL live window'
+                        : `Live state not curated for ${game}`,
+                }));
+            }
+        }
+        if (wanted.has('media')) {
+            if (game === 'cs2')
+                load('media', `/cs2/matches/${encodeURIComponent(matchId)}/demos`);
+            else
+                sections.media = { demos: [], vods: [], notes: 'No media endpoint for this game' };
+        }
+        if (wanted.has('advanced')) {
+            if (game === 'lol' && gameId)
+                load('advanced', `/lol/games/${encodeURIComponent(gameId)}/advanced`);
+            else if (game === 'lol') {
+                partial.push(partialFromRejection('advanced', {
+                    code: 'VALIDATION',
+                    message: 'gameId required for LoL advanced package',
+                }));
+            }
+            else {
+                partial.push(partialFromRejection('advanced', {
+                    code: 'NOT_IMPLEMENTED',
+                    message: `Advanced package not curated for ${game}`,
+                }));
+            }
+        }
+        await Promise.all(tasks);
+        return successEnvelope({
+            source: 'match_details',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            partial: partial.length ? partial : undefined,
+            entities: { games: [game], ids: { matchId, ...(gameId ? { gameId } : {}) } },
+            data: {
+                match: sections.base,
+                sections,
+            },
+        });
+    },
+};
+export const matchTools = [matchSummary, matchDetails];