cito-mcp 0.3.21 → 0.4.0

package/dist/tools/player.js

@@ -769,4 +769,343 @@ Parallel-safe: yes. Upstream cost: 1.`,
         });
     },
 };
-export const playerTools = [playerProfile, playerForm];
+export const playerMatches = {
+    name: 'player_matches',
+    description: `Tennis player match log: every archived match for one player, newest first, with opponent, tournament, round, surface and score.
+
+When to use:
+- "Show me Shelton's last 20 matches"; full match history; every match at a given tournament; filtering a player's record by surface.
+
+Prefer over: player_form (a W/L summary with a small window and a streak, not the log); call_api for /tennis/players/{id}/matches.
+
+Do not use when: aggregate totals, titles, or win% → player_stats; identity → player_profile; one match's box score → match_details.
+
+Tennis-only. Limit defaults to 20 (max 50). Rows arrive newest-first. Use
+surface to narrow to Hard/Clay/Grass; tournamentId pins one event.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'playerId'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            playerId: stringSchema('Tennis player id, e.g. "atp_210097".', 'atp_210097'),
+            surface: stringSchema('Filter to one surface: Hard, Clay, or Grass.', 'Hard'),
+            tournamentId: stringSchema('Only matches at this tournament edition, e.g. "atp_2026_560".', 'atp_2026_560'),
+            limit: limitSchema({ default: 20, max: 50, description: 'Match rows (default 20, max 50).' }),
+        },
+    },
+    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: 'player_matches',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `player_matches is tennis-only (game '${game}' has its own match-log shape)`,
+                game,
+                source: 'player_matches',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use match_summary or call_api for this game', 'Retry with game tennis'],
+            });
+        }
+        const playerId = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        if (!playerId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'playerId is required',
+                game,
+                source: 'player_matches',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Find an id with search_entities or resolve_entity'],
+            });
+        }
+        const limit = clampInt(args.limit, 20, 1, 50);
+        const surfaceRaw = typeof args.surface === 'string' ? args.surface.trim() : '';
+        const tournamentId = typeof args.tournamentId === 'string' && args.tournamentId.trim()
+            ? args.tournamentId.trim()
+            : '';
+        const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(playerId)}/matches`, {
+            query: {
+                limit,
+                ...(surfaceRaw ? { surface: surfaceRaw } : {}),
+                ...(tournamentId ? { tournament_id: tournamentId } : {}),
+            },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Player match log failed for '${playerId}' (HTTP ${res.status})`,
+                game,
+                source: 'player_matches',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+                recover: ['Check the player id with search_entities'],
+            });
+        }
+        const root = asRecord(res.data);
+        const body = asRecord(root?.data) ?? root ?? {};
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        const allRows = Array.isArray(body.items) ? body.items : [];
+        /**
+         * Derive the player's display name from their own side of any match.
+         *
+         * The match-log payload carries no player_name at all (verified against the
+         * live route: top-level keys are just items/total/page/page_size/has_next/
+         * has_prev/success/total_pages), so the earlier version titled every log
+         * "<id> match log" and reported playerName: null. Each row does carry the
+         * winner and loser objects, so whichever side matches the requested id gives
+         * a real name with no extra upstream call.
+         */
+        let derivedName = null;
+        for (const row of allRows) {
+            const r = asRecord(row) ?? {};
+            const w = asRecord(r.winner) ?? {};
+            const l = asRecord(r.loser) ?? {};
+            if (pickString(r.winner_id, w.id) === playerId) {
+                derivedName = pickString(w.name) ?? null;
+            }
+            else if (pickString(r.loser_id, l.id) === playerId) {
+                derivedName = pickString(l.name) ?? null;
+            }
+            if (derivedName)
+                break;
+        }
+        /**
+         * The route ignores ?limit= (verified: limit=5 returned 20), so the bound is
+         * applied here. total comes from the upstream header so callers still learn
+         * how many matches exist beyond this page.
+         */
+        const total = typeof body.total === 'number' ? body.total : allRows.length;
+        const rows = allRows.slice(0, limit).map((row) => {
+            const r = asRecord(row) ?? {};
+            const winner = asRecord(r.winner) ?? {};
+            const loser = asRecord(r.loser) ?? {};
+            const winnerId = pickString(r.winner_id, winner.id);
+            const lost = winnerId !== null && winnerId !== playerId;
+            // Opponent is whichever side is not this player. When the row's winner
+            // does not match the requested id the player lost, so the opponent is the
+            // winner.
+            const opponent = lost ? winner : loser;
+            return {
+                matchId: pickString(r.id, r.match_id) ?? null,
+                date: pickString(r.match_date, r.date) ?? null,
+                tournamentId: pickString(r.tournament_id) ?? null,
+                tournamentName: pickString(r.tournament_name, r.name) ?? null,
+                level: pickString(r.level) ?? null,
+                category: pickString(r.category) ?? null,
+                surface: pickString(r.surface) ?? null,
+                round: pickString(r.round) ?? null,
+                roundName: pickString(r.round_name) ?? null,
+                bestOf: num(r.best_of),
+                score: pickString(r.score, r.score_raw) ?? null,
+                outcome: pickString(r.outcome, r.status) ?? null,
+                result: lost ? 'L' : 'W',
+                opponent: {
+                    id: pickString(opponent.id) ?? null,
+                    name: pickString(opponent.name) ?? null,
+                    country: pickString(opponent.ioc) ?? null,
+                    rank: num(opponent.rank),
+                    seed: opponent.seed ?? null,
+                },
+            };
+        });
+        return successEnvelope({
+            pagination: {
+                limit,
+                offset: 0,
+                total,
+                hasMore: total > rows.length,
+                nextCursor: null,
+                prevCursor: null,
+            },
+            source: 'player_matches',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            entities: { games: [game], ids: { playerId } },
+            data: {
+                title: `${derivedName ?? playerId} match log`,
+                playerId,
+                playerName: derivedName,
+                surfaceFilter: surfaceRaw || null,
+                tournamentFilter: tournamentId || null,
+                matches: rows,
+                total,
+                // Named explicitly because the bound is applied locally: the upstream
+                // route returns everything and ignores ?limit=.
+                returned: rows.length,
+            },
+        });
+    },
+};
+export const playerStats = {
+    name: 'player_stats',
+    description: `Tennis player career statistics: W/L totals, win percentage, titles, Grand Slam and Masters titles, plus per-surface and per-level breakdowns. Optional surface/year filters.
+
+When to use:
+- "How many titles does Alcaraz have?"; career win%; Grand Slam title count; record on clay; a season-scoped record.
+
+Prefer over: player_profile (identity + a summary block, no breakdowns); player_matches (individual rows, no aggregates).
+
+Do not use when: the match log → player_matches; ranking over time → player_rankings_history.
+
+Tennis-only. Filters are surface (Hard/Clay/Grass/Carpet) and yearFrom/yearTo.
+Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'playerId'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            playerId: stringSchema('Tennis player id, e.g. "atp_207989".', 'atp_207989'),
+            surface: stringSchema('Filter to one surface: Hard, Clay, Grass, or Carpet.', 'Clay'),
+            yearFrom: { type: 'integer', minimum: 1877, maximum: 2100, description: 'Inclusive start year, e.g. 2020.' },
+            yearTo: { type: 'integer', minimum: 1877, maximum: 2100, description: 'Inclusive end year, e.g. 2026.' },
+        },
+    },
+    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: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `player_stats is tennis-only (game '${game}' exposes stats elsewhere)`,
+                game,
+                source: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use player_profile for this game', 'Retry with game tennis'],
+            });
+        }
+        const playerId = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        if (!playerId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'playerId is required',
+                game,
+                source: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Find an id with search_entities or resolve_entity'],
+            });
+        }
+        const surfaceRaw = typeof args.surface === 'string' ? args.surface.trim() : '';
+        const yf = typeof args.yearFrom === 'number' && Number.isFinite(args.yearFrom) ? Math.trunc(args.yearFrom) : null;
+        const yt = typeof args.yearTo === 'number' && Number.isFinite(args.yearTo) ? Math.trunc(args.yearTo) : null;
+        if (yf !== null && yt !== null && yf > yt) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `yearFrom (${yf}) must not be greater than yearTo (${yt})`,
+                game,
+                source: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(playerId)}/stats`, {
+            query: {
+                ...(surfaceRaw ? { surface: surfaceRaw } : {}),
+                ...(yf !== null ? { year_from: yf } : {}),
+                ...(yt !== null ? { year_to: yt } : {}),
+            },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Player stats failed for '${playerId}' (HTTP ${res.status})`,
+                game,
+                source: 'player_stats',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+                recover: ['Check the player id with search_entities'],
+            });
+        }
+        const root = asRecord(res.data);
+        const body = asRecord(root?.data) ?? root ?? {};
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        const summary = asRecord(body.career_summary) ?? {};
+        const filters = asRecord(body.filters) ?? {};
+        /**
+         * Map an arbitrary {label: value} breakdown without assuming the upstream
+         * key set: the endpoint has grown keys before and a hardcoded list would
+         * silently drop new ones.
+         */
+        const numericBlock = (value) => {
+            const rec = asRecord(value);
+            if (!rec)
+                return null;
+            const out = {};
+            for (const [k, v] of Object.entries(rec))
+                out[k] = num(v);
+            return Object.keys(out).length > 0 ? out : null;
+        };
+        return successEnvelope({
+            source: 'player_stats',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            entities: { games: [game], ids: { playerId } },
+            data: {
+                title: `${pickString(body.player_name) ?? playerId} career statistics`,
+                playerId: pickString(body.player_id) ?? playerId,
+                playerName: pickString(body.player_name) ?? null,
+                filters: {
+                    surface: pickString(filters.surface) ?? null,
+                    level: pickString(filters.level) ?? null,
+                    yearFrom: num(filters.year_from),
+                    yearTo: num(filters.year_to),
+                },
+                careerSummary: {
+                    matchesPlayed: num(summary.matches_played),
+                    matchesWon: num(summary.matches_won),
+                    matchesLost: num(summary.matches_lost),
+                    winPercentage: num(summary.win_percentage),
+                    titles: num(summary.titles_count),
+                    grandSlamTitles: num(summary.grand_slam_titles),
+                    mastersTitles: num(summary.masters_titles),
+                    finalsReached: num(summary.finals_reached),
+                },
+                bySurface: numericBlock(body.by_surface ?? body.surface_breakdown),
+                byLevel: numericBlock(body.by_level ?? body.level_breakdown),
+            },
+        });
+    },
+};
+export const playerTools = [playerProfile, playerForm, playerMatches, playerStats];

package/dist/tools/rankings.js

@@ -225,4 +225,150 @@ Parallel-safe: yes. Upstream cost: 1.`,
         });
     },
 };
-export const rankingsTools = [rankingsMovers];
+export const playerRankingsHistory = {
+    name: 'player_rankings_history',
+    description: `Tennis player ranking trajectory: every published ranking date for one player, plus career-high and weeks at No.1.
+
+When to use:
+- "Show Alcaraz's ranking over time"; career-high rank and when it was reached; how a player climbed; plotting a rank chart.
+
+Prefer over: standings (latest snapshot only); rankings_movers (week-over-week delta for a whole tour); player_profile (has career-high but no per-date series).
+
+Do not use when: the current top-N table → standings with game tennis.
+
+Tennis-only. Rows arrive oldest-first (chronological), which is the order a chart
+wants; the newest entries are the tail. Use 'since' or 'limit' to bound the
+series — the full career can be hundreds of rows.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'playerId'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            playerId: stringSchema('Tennis player id, e.g. "atp_207989" or "wta_214544".', 'atp_207989'),
+            since: stringSchema('Only rows on or after this date (YYYY-MM-DD).', '2026-01-01'),
+            limit: limitSchema({ default: 20, max: 500, description: 'Max history rows (default 20, max 500).' }),
+        },
+    },
+    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: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `player_rankings_history is tennis-only (game '${game}' has no ranking-history endpoint)`,
+                game,
+                source: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use standings for the latest snapshot of this game', 'Retry with game tennis'],
+            });
+        }
+        const playerId = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        if (!playerId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'playerId is required',
+                game,
+                source: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Find an id with search_entities or resolve_entity'],
+            });
+        }
+        const sinceRaw = typeof args.since === 'string' ? args.since.trim() : '';
+        if (sinceRaw && !/^\d{4}-\d{2}-\d{2}$/.test(sinceRaw)) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `since must be YYYY-MM-DD (got '${args.since}')`,
+                game,
+                source: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const limit = clampInt(args.limit, 20, 1, 500);
+        const res = await fetchJson(ctx, `/tennis/rankings/history/${encodeURIComponent(playerId)}`, {
+            query: { limit },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Ranking history failed for '${playerId}' (HTTP ${res.status})`,
+                game,
+                source: 'player_rankings_history',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+                recover: ['Check the player id with search_entities'],
+            });
+        }
+        const root = asRecord(res.data) ?? {};
+        const body = asRecord(root.data) ?? root;
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        let history = (Array.isArray(body.history) ? body.history : []).map((row) => {
+            const r = asRecord(row) ?? {};
+            return {
+                date: pickString(r.date) ?? null,
+                rank: num(r.rank),
+                points: num(r.points),
+            };
+        });
+        if (sinceRaw)
+            history = history.filter((h) => h.date !== null && h.date >= sinceRaw);
+        // Best rank actually present in the returned window, so a caller can label a
+        // chart without recomputing. Null when the window is empty.
+        const best = history.reduce((acc, h) => {
+            if (h.rank === null)
+                return acc;
+            if (!acc || acc.rank === null || h.rank < acc.rank)
+                return { date: h.date, rank: h.rank };
+            return acc;
+        }, null);
+        return successEnvelope({
+            pagination: {
+                limit,
+                offset: 0,
+                total: history.length,
+                hasMore: false,
+                nextCursor: null,
+                prevCursor: null,
+            },
+            source: 'player_rankings_history',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            data: {
+                title: `${pickString(body.player_name) ?? playerId} ranking history`,
+                playerId: pickString(body.player_id) ?? playerId,
+                playerName: pickString(body.player_name) ?? null,
+                tour: pickString(body.tour) ?? null,
+                careerHighRank: num(body.career_high_rank),
+                careerHighDate: pickString(body.career_high_date) ?? null,
+                weeksAtNo1: num(body.total_weeks_at_no_1),
+                since: sinceRaw || null,
+                bestRankInWindow: best,
+                history,
+            },
+        });
+    },
+};
+export const rankingsTools = [rankingsMovers, playerRankingsHistory];