cito-mcp 0.3.20 → 0.4.0

package/dist/tools/meta.js

@@ -116,6 +116,16 @@ const TOOL_CATALOG = [
         preferOver: ['agent-side double match-list filtering'],
         doNotUse: 'Single-side form only → team_profile or player_profile',
     },
+    {
+        name: 'h2h_matrix',
+        outcome: 'Tennis multi-player H2H grid: every pair series record in one matrix',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['h2h', 'preview'],
+        exampleArgs: { game: 'tennis', players: ['atp_207989', 'atp_100644'] },
+        preferOver: ['N head_to_head calls for an N-player field', 'raw matrix via call_api'],
+        doNotUse: 'Two-player deep-dive with tiebreak splits → head_to_head; season leaders → leaderboard_*',
+    },
     {
         name: 'standings',
         outcome: 'League/event standings or world/division rankings',
@@ -146,6 +156,156 @@ const TOOL_CATALOG = [
         preferOver: ['raw form via call_api'],
         doNotUse: 'Career totals/titles → player_profile; ranking deltas → rankings_movers',
     },
+    {
+        name: 'player_matches',
+        outcome: 'Tennis player match log: every archived match with opponent, round and score',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['player_form', 'match_page'],
+        exampleArgs: { game: 'tennis', playerId: 'atp_210097', limit: 20 },
+        preferOver: ['raw match log via call_api', 'player_form (summary window, not the log)'],
+        doNotUse: 'Aggregates/titles → player_stats; one box score → match_details',
+    },
+    {
+        name: 'player_stats',
+        outcome: 'Tennis career statistics: W/L, win%, titles, Grand Slam and Masters titles, breakdowns',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['player_form'],
+        exampleArgs: { game: 'tennis', playerId: 'atp_207989', surface: 'Clay' },
+        preferOver: ['raw player stats via call_api'],
+        doNotUse: 'Match rows → player_matches; ranking over time → player_rankings_history',
+    },
+    {
+        name: 'player_rankings_history',
+        outcome: 'Tennis ranking trajectory per published date, plus career-high and weeks at No.1',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings', 'player_form'],
+        exampleArgs: { game: 'tennis', playerId: 'atp_207989', since: '2026-01-01', limit: 20 },
+        preferOver: ['raw rankings history via call_api'],
+        doNotUse: 'Latest snapshot → standings; week-over-week delta → rankings_movers',
+    },
+    {
+        name: 'tennis_odds',
+        outcome: 'Tennis betting odds: upcoming matches with prices, plus pre-match and in-play for one match',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['preview', 'match_page', 'odds'],
+        exampleArgs: { game: 'tennis', scope: 'upcoming', limit: 20 },
+        preferOver: ['raw odds via call_api', 'match_preview (no prices)'],
+        doNotUse: 'The result → match_details; rankings → standings',
+    },
+    {
+        name: 'tournaments',
+        outcome: 'Tennis tournament catalog: filter by year, tour, level, surface or country',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['preview', 'standings'],
+        exampleArgs: { game: 'tennis', year: 2026, tour: 'WTA', level: 'WTA 1000', limit: 20 },
+        preferOver: ['raw tournament list via call_api'],
+        doNotUse: 'A specific draw/edition → event_card with the id this returns',
+    },
+    {
+        name: 'tennis_schedule',
+        outcome: "One day of tennis: that day's schedule and/or completed matches",
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['schedule', 'match_page'],
+        exampleArgs: { game: 'tennis', date: '2026-09-12', include: 'both', limit: 20 },
+        preferOver: ['raw schedule/completed via call_api (both require ?date=)'],
+        doNotUse: 'In-play right now → live_matches; a forward window → upcoming_schedule',
+    },
+    {
+        name: 'leaderboard_aces',
+        outcome: 'Tennis season aces leaderboard: most aces served, ordered first',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_break_points_saved',
+        outcome: 'Tennis season break-points-saved pct leaderboard, min 50 faced',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_first_serve_won',
+        outcome: 'Tennis season first-serve-won pct leaderboard, min 300 in',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_tiebreak_win_pct',
+        outcome: 'Tennis season tiebreak-win-pct leaderboard, min 10 tiebreaks',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_break_conversion',
+        outcome: 'Tennis season break-conversion pct leaderboard, min 50 opportunities',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_return_games_won',
+        outcome: 'Tennis season return-games-won pct leaderboard, min 100 played',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_deciding_set_record',
+        outcome: 'Tennis season deciding-set-record pct leaderboard, min 10 deciders',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_comeback_wins',
+        outcome: 'Tennis season comeback-wins pct leaderboard, min 20 first sets',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
+    {
+        name: 'leaderboard_finals_record',
+        outcome: 'Tennis season finals-record pct leaderboard, min 3 finals',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', season: 2026, limit: 10 },
+        preferOver: ['raw leaderboard via call_api'],
+        doNotUse: 'Ranking position → standings; week-over-week movement → rankings_movers',
+    },
     {
         name: 'match_preview',
         outcome: 'Pre-match briefing: sides, rosters/form, H2H stub',
@@ -172,6 +332,86 @@ const TOOL_CATALOG = [
         ],
         doNotUse: 'Live-only strip → live_matches; single match recap → match_summary',
     },
+    {
+        name: 'cs2_live_scoreboard',
+        outcome: 'Live real-time in-game scoreboard for an active CS2 match',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['live_board', 'match_page'],
+        exampleArgs: { matchId: 'cs2-match-2397733' },
+        preferOver: ['polling call_api for live scoreboard'],
+        doNotUse: 'For completed matches without live state',
+    },
+    {
+        name: 'cs2_round_economy',
+        outcome: 'Round-by-round tactical economy and buy types for a CS2 map',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['match_page'],
+        exampleArgs: { mapId: '7716-map-1' },
+        preferOver: ['raw round event parsing'],
+        doNotUse: 'For overall match scorelines → match_summary',
+    },
+    {
+        name: 'cs2_opening_duels',
+        outcome: 'First blood and opening duel statistics by player or leaderboard',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['player_form', 'match_page'],
+        exampleArgs: { playerId: 'chucky', limit: 20 },
+        preferOver: ['manual kill log counting'],
+        doNotUse: 'For general player stats → player_profile',
+    },
+    {
+        name: 'cs2_clutches',
+        outcome: '1vX clutch situation success records (1v1 to 1v5)',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['player_form', 'match_page'],
+        exampleArgs: { playerId: 'xm1nd', limit: 20 },
+        preferOver: ['manual demo parse analysis'],
+        doNotUse: 'For regular player stats → player_profile',
+    },
+    {
+        name: 'cs2_team_map_stats',
+        outcome: 'Team win rates and CT/T side splits across competitive map pool',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['team_page', 'preview'],
+        exampleArgs: { teamId: 'hltv-team-4608', days: 90 },
+        preferOver: ['manual match history scraping'],
+        doNotUse: 'For non-CS2 games',
+    },
+    {
+        name: 'cs2_utility_leaderboard',
+        outcome: 'Sub-second leaderboard of CS2 utility and flashbang efficiency',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['standings', 'player_form'],
+        exampleArgs: { limit: 20 },
+        preferOver: ['unindexed round event aggregation'],
+        doNotUse: 'For standard weapon ratings',
+    },
+    {
+        name: 'cs2_veto_sequence',
+        outcome: 'Map pick/ban sequence and veto history for a CS2 match',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['match_page', 'preview'],
+        exampleArgs: { matchId: '2397603' },
+        preferOver: ['scraping match page text'],
+        doNotUse: 'For map scores → match_summary',
+    },
+    {
+        name: 'cs2_roster_transfers',
+        outcome: 'Recent pro CS2 roster changes, benchings, stand-ins, and transfers',
+        parallelSafe: true,
+        games: ['cs2'],
+        jobs: ['team_page', 'schedule'],
+        exampleArgs: { limit: 20 },
+        preferOver: ['manual news feed scanning'],
+        doNotUse: 'For current active rosters → team_profile',
+    },
     {
         name: 'list_routes',
         outcome: 'Index of raw REST routes from the live OpenAPI spec (method, path, summary)',
@@ -199,7 +439,7 @@ const JOBS = [
     { 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: 'h2h', description: 'Historical rivalry record', recommendedTools: ['head_to_head', 'h2h_matrix'] },
     { 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'] },

package/dist/tools/odds.js

@@ -0,0 +1,251 @@
+/**
+ * tennis_odds — the betting-odds surface for tennis (TENNIS-24).
+ *
+ * WHY THIS EXISTS
+ * The tennis API serves three odds routes, and NONE of them had a tool. Odds are
+ * a headline feature of the paid tiers and one of the most common reasons to buy
+ * a sports API, so a builder had to discover /tennis/odds/* through call_api or
+ * the docs. This closes that gap.
+ *
+ * Coverage is genuinely partial upstream, and the tool says so rather than
+ * returning an empty success: /tennis/odds/{id} answers with
+ * `coverage: { odds: false }` and an empty bookmakers[] for any match the feed
+ * has no prices for (verified against atp_2026_560, which returned exactly
+ * that). An agent that cannot tell "no odds exist for this match" from "the call
+ * failed" will invent a price, so the response distinguishes the two.
+ */
+import { asRecord, clampInt, fetchJson, gameNotIncludedHint, pickString, } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
+import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
+/** A bookmaker row: { key, title, last_update, markets: [{ key, outcomes: [{ name, price }] }] }. */
+function normalizeBookmaker(row) {
+    const r = asRecord(row) ?? {};
+    const markets = (Array.isArray(r.markets) ? r.markets : []).map((mk) => {
+        const m = asRecord(mk) ?? {};
+        const outcomes = (Array.isArray(m.outcomes) ? m.outcomes : []).map((o) => {
+            const oc = asRecord(o) ?? {};
+            return {
+                name: pickString(oc.name) ?? null,
+                // Decimal odds as the feed supplies them; never recomputed or implied.
+                price: typeof oc.price === 'number' && Number.isFinite(oc.price) ? oc.price : null,
+                point: typeof oc.point === 'number' && Number.isFinite(oc.point) ? oc.point : null,
+            };
+        });
+        return {
+            market: pickString(m.key) ?? null,
+            outcomes,
+            // Implied probability from the prices actually returned, so a caller does
+            // not have to redo the arithmetic. Null when any price is missing.
+            impliedProbabilities: (() => {
+                const prices = outcomes.map((o) => o.price).filter((p) => p !== null && p > 1);
+                if (prices.length !== outcomes.length || prices.length === 0)
+                    return null;
+                const inv = prices.map((p) => 1 / p);
+                const sum = inv.reduce((a, b) => a + b, 0);
+                return inv.map((v) => Number((v / sum).toFixed(4)));
+            })(),
+        };
+    });
+    return {
+        key: pickString(r.key) ?? null,
+        title: pickString(r.title) ?? null,
+        lastUpdate: pickString(r.last_update) ?? null,
+        markets,
+    };
+}
+function parseTennis(args, tool) {
+    const gameParse = parseGame(args.game, { allowAll: false, required: true });
+    if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+        return { error: gameParse.error ?? 'game is required', game: null };
+    }
+    const game = gameParse.game;
+    if (game !== 'tennis') {
+        return {
+            error: `${tool} is tennis-only (odds for '${game}' is not served by this endpoint)`,
+            game,
+        };
+    }
+    return { game };
+}
+function requireTennisId(args, tool) {
+    const id = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+    if (!id)
+        return { error: `${tool} requires matchId` };
+    return { matchId: id };
+}
+export const tennisOdds = {
+    name: 'tennis_odds',
+    description: `Tennis betting odds: upcoming matches with prices, plus pre-match and in-play odds for one match.
+
+Modes (pick with 'scope'):
+- upcoming (default): matches with odds available, each with the bookmakers quoting it.
+- match: pre-match odds for one match_id.
+- live: in-play odds for one match_id.
+
+When to use:
+- "What are the odds on X vs Y?"; pre-match prices; in-play prices; which matches have odds today.
+
+Prefer over: call_api for /tennis/odds/*; match_preview (no prices).
+
+Do not use when: the match result → match_details; rankings → standings.
+
+Tennis-only. Odds are decimal. Coverage is partial upstream: a match with no
+priced bookmaker returns coverage.odds=false and an empty bookmakers[] rather
+than invented numbers, and this tool surfaces that distinction explicitly.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            scope: stringSchema('upcoming (default) | match | live.', 'upcoming'),
+            matchId: stringSchema('Match id for scope=match or scope=live, e.g. "s365_2026_4853596".', 's365_2026_4853596'),
+            limit: limitSchema({ default: 20, max: 50, description: 'Rows for scope=upcoming (default 20, max 50).' }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const parsed = parseTennis(args, 'tennis_odds');
+        if (parsed.error) {
+            return errorEnvelope({
+                code: parsed.error.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: parsed.error,
+                game: parsed.game,
+                source: 'tennis_odds',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = parsed.game;
+        const scopeRaw = typeof args.scope === 'string' ? args.scope.trim().toLowerCase() : 'upcoming';
+        if (!['upcoming', 'match', 'live'].includes(scopeRaw)) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `scope must be upcoming, match, or live (got '${args.scope}')`,
+                game,
+                source: 'tennis_odds',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use scope=upcoming for matches with odds', 'Use scope=match or scope=live with a matchId'],
+            });
+        }
+        const matchId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+        if (scopeRaw !== 'upcoming' && !matchId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `matchId is required when scope=${scopeRaw}`,
+                game,
+                source: 'tennis_odds',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [`Pass matchId, or use scope=upcoming with no id`],
+            });
+        }
+        const limit = clampInt(args.limit, 20, 1, 50);
+        if (scopeRaw === 'upcoming') {
+            const res = await fetchJson(ctx, '/tennis/odds/upcoming', { query: { limit } });
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `Upcoming tennis odds failed (HTTP ${res.status})`,
+                    game,
+                    source: 'tennis_odds',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls: 1,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                });
+            }
+            const root = asRecord(res.data) ?? {};
+            const body = asRecord(root.data) ?? root;
+            const items = (Array.isArray(body.items) ? body.items : []).map((row) => {
+                const r = asRecord(row) ?? {};
+                const home = asRecord(r.home) ?? {};
+                const away = asRecord(r.away) ?? {};
+                return {
+                    matchId: pickString(r.match_id, r.id) ?? null,
+                    oddsEventId: pickString(r.odds_event_id) ?? null,
+                    tournament: pickString(r.tournament) ?? null,
+                    commenceTime: pickString(r.commence_time, r.starts_at) ?? null,
+                    player1: { name: pickString(home.name) ?? null, id: pickString(home.player_id, home.id) ?? null },
+                    player2: { name: pickString(away.name) ?? null, id: pickString(away.player_id, away.id) ?? null },
+                    bookmakers: Array.isArray(r.bookmakers) ? r.bookmakers.map((b) => pickString(b) ?? null) : [],
+                    live: r.live === true,
+                };
+            });
+            const total = typeof body.total === 'number' ? body.total : items.length;
+            return successEnvelope({
+                pagination: {
+                    limit,
+                    offset: 0,
+                    total,
+                    hasMore: body.has_next === true,
+                    nextCursor: null,
+                    prevCursor: null,
+                },
+                source: 'tennis_odds',
+                game,
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                rateLimit: res.headers,
+                data: {
+                    title: `Tennis odds — upcoming (${items.length} of ${total})`,
+                    scope: scopeRaw,
+                    oddsFormat: 'decimal',
+                    items,
+                    total,
+                },
+            });
+        }
+        const path = scopeRaw === 'match'
+            ? `/tennis/odds/${encodeURIComponent(matchId)}`
+            : `/tennis/odds/${encodeURIComponent(matchId)}/live`;
+        const res = await fetchJson(ctx, path, {});
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Tennis ${scopeRaw} odds failed for '${matchId}' (HTTP ${res.status})`,
+                game,
+                source: 'tennis_odds',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+                recover: ['Check the match id with live_matches or match_details'],
+            });
+        }
+        const root = asRecord(res.data) ?? {};
+        const body = asRecord(root.data) ?? root;
+        const coverage = asRecord(body.coverage) ?? {};
+        const bookmakers = (Array.isArray(body.bookmakers) ? body.bookmakers : []).map(normalizeBookmaker);
+        const hasOdds = coverage.odds === true || bookmakers.length > 0;
+        return successEnvelope({
+            source: 'tennis_odds',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            data: {
+                title: `Tennis ${scopeRaw} odds — ${matchId}`,
+                scope: scopeRaw,
+                matchId: pickString(body.match_id) ?? matchId,
+                oddsFormat: pickString(body.odds_format) ?? 'decimal',
+                bookmakers,
+                // Explicit, because an empty bookmakers[] is otherwise indistinguishable
+                // from a failed scrape.
+                oddsAvailable: hasOdds,
+                note: hasOdds
+                    ? null
+                    : 'No bookmaker is currently quoting this match. This is an upstream coverage gap, not an error; retry closer to the start time.',
+            },
+        });
+    },
+};
+export const oddsTools = [tennisOdds];