cito-mcp 0.3.21 → 0.4.0

package/README.md

@@ -12,7 +12,7 @@ Primary games & sports: **lol · cs2 · dota2 · cod · ufc · tennis**. Long-ta
 
 v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among thin path wrappers, invent IDs, and stitch multi-call UI screens themselves. That catalog was hard to select against and brittle across games.
 
-**v0.3 ships 18 hand-authored tools** that answer *jobs* instead of mirroring REST:
+**Ships 42 curated outcome tools** that answer *jobs* instead of mirroring REST:
 
 | Job | Tool |
 | --- | --- |
@@ -28,6 +28,12 @@ v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among t
 | Pre-match briefing (with surface) | `match_preview` |
 | Event / fight-night card | `event_card` |
 | Rivalry record | `head_to_head` |
+| Tennis betting odds | `tennis_odds` |
+| Tennis tournament catalog | `tournaments` |
+| One day of tennis | `tennis_schedule` |
+| Tennis player match log | `player_matches` |
+| Tennis career statistics | `player_stats` |
+| Tennis ranking trajectory | `player_rankings_history` |
 | Fighter / team photos | `event_card` · `player_profile` |
 | Which raw REST route exists? | `list_routes` |
 | Name → ID | `resolve_entity` / `search_entities` |

package/dist/tools/index.js

@@ -9,6 +9,9 @@ import { rankingsTools } from './rankings.js';
 import { leaderboardTools } from './leaderboard.js';
 import { insightTools } from './insight.js';
 import { cs2Tools } from './cs2.js';
+import { oddsTools } from './odds.js';
+import { tournamentTools } from './tournaments.js';
+import { scheduleTools } from './schedule.js';
 /** Curated outcome-tool catalog. Order matches preferred cold-start ladder. */
 export const allTools = [
     ...metaTools.filter((t) => t.name === 'list_capabilities' || t.name === 'api_health'),
@@ -20,6 +23,11 @@ export const allTools = [
     ...standingsTools,
     ...rankingsTools,
     ...leaderboardTools,
+    // Tennis depth added after the coverage audit: odds, tournament discovery and
+    // the daily schedule were reachable only through call_api.
+    ...oddsTools,
+    ...tournamentTools,
+    ...scheduleTools,
     ...insightTools,
     ...cs2Tools,
     // Escape-hatch pair last: discover routes, then call one.

package/dist/tools/meta.js

@@ -156,6 +156,66 @@ 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',

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];