cito-mcp 0.4.6 → 0.4.8

package/README.md

@@ -2,9 +2,9 @@
 
 Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports API](https://api.citoapi.com) — **curated outcome tools** for agents building esports apps, dashboards, bots, and research flows.
 
-**Version:** `0.3.20` · **Node:** `>=20` · **Install:** `npx cito-mcp`
+**Version:** `0.4.7` · **Node:** `>=20` · **Install:** `npx cito-mcp`
 
-Primary games & sports: **lol · cs2 · dota2 · cod · ufc · tennis**. Long-tail REST stays available via `call_api`.
+Primary games & sports: **lol · cs2 · dota2 · cod · ufc · tennis**, plus **RAF wrestling** and **BKFC bare knuckle** through the `combat_*` tools. Long-tail REST stays available via `call_api`.
 
 ---
 
@@ -50,8 +50,6 @@ Where the source data is partial, the tool says so instead of shipping a plausib
 | The two ranking lists compared by `rankings_movers` are not a week apart | `gapDays` + `comparisonWindow` (`"12-week gap"`), `comparisonsAreWeekly: false`, and a warning naming both dates |
 | A tennis tournament draw is missing matches | `draw.shortRounds` (`["R128 45/64"]`), `draw.missingRounds`, `draw.complete` |
 | A stats section the endpoint does not publish | `player_stats.unavailable` names the section and why, rather than a block of nulls |
-| No bookmaker is quoting a match | `oddsAvailable: false` plus a note that it is a coverage gap, not an error |
-| The odds feed leaves `match_id` null | `joinKey` (`{kind:"oddsEventId", …}`) and `playerIds`, so the row is still joinable |
 | `search_entities` results that do not match at all | dropped, counted under `data.relevance.droppedBelowFloor`, with a warning naming them |
 
 ---
@@ -542,11 +540,14 @@ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 
 ## Changelog (summary)
 
+### 0.4.7
+
+- Removed the unregistered tennis odds module and its README entries; `match_details` `sections:["odds"]` stays UFC-only and answers `NOT_IMPLEMENTED` for other games.
+
 ### 0.4.2
 
 Second tennis correctness pass, from the 2026-09-12 re-sweep. Five defects, each reproduced from a raw payload and re-verified after the fix. Two were upstream (fixed on the API and verified with the 40/40 invariant gate); three were MCP-side.
 
-- **`tennis_odds` called a nonexistent match "no coverage".** `/tennis/odds/{id}` answers **HTTP 200 with `coverage.odds=false` for every id it does not know** — verified for `s365_2026_0000000` and for the literal `total-garbage-id`. So a typo and a genuine no-book gap were indistinguishable and both came back `ok:true`. `scope=match`/`live` now verify the id against `/tennis/matches/{id}` (which does 404) when no odds are quoted: unknown id → `NOT_FOUND` with recovery steps, real match → an honest coverage gap with `matchExists: true`.
 - **Tennis `standings` published a fake total and could not be paged.** `/tennis/standings?top_n=5` set `rank_max=top_n`, so the count (which carried the rank bounds) equalled the page size: `total:5`, `hasMore:false` for a list of **150** ranked players. The API now counts the population without the rank window and returns `ranked_players`/`total_pages`/`has_next`, `/standings` takes a `page` argument, and the tool reports `total`/`rankedPlayers`/`totalPages`/`hasMore` — page 2 of the ATP list now starts at rank 6. The same `allRows.length` mistake in the `pagination` block was fixed too, so the two counts cannot disagree.
 - **`event_card` published the requested id as the event name.** With a bad id it answered `ok:true` and `event.name = "atp_2026_999999"` over a 404 that `partial[]` reported correctly. Names now come from the payload or are `null`, with `event.resolved` recording whether the detail fetch succeeded.
 - **`leaderboard_*` reported the page size as the population.** Every board returned `"total": len(items)` after applying `.limit(limit)`, so `limit=2` answered `total:2` — for boards whose own docs record thousands of qualifiers. Upstream now carries `count(*) OVER ()` (Postgres evaluates it after `GROUP BY`/`HAVING`, so it is exactly the qualifying population, at no extra round trip): aces **2488**, break-conversion **1089** (matching the figure in its own docstring), 1st-serve-won 1141, bp-saved 1186, return-games 987, tiebreak 364, deciders 334, comebacks 611, finals 66. Each tool also reports `returned` and the board's `minimumAttempts`.
@@ -560,12 +561,10 @@ Second tennis correctness pass, from the 2026-09-12 re-sweep. Five defects, each
 Tennis correctness pass, driven by the 2026-09-12 sweep (`reports/tennis-mcp-sweep-2026-09-12.md`). Every item was reproduced against live ids and re-verified after the fix.
 
 - **`match_summary` tennis scoreline was always `- : -`.** `/tennis/matches/{id}` puts no `sets_won` on its player objects, so the sets-won score was null for every completed match while the same payload held the real score in `score` and `sets[]`. Sets won are now derived (explicit → `winner_sets_won` → `sets[]` → `score` string), `score.detail` carries the game score, and a set's `completed` is inferred when the archive omits `is_completed`. The winner-oriented `winner_games`/`loser_games` pair is deliberately not used as a side score. `bestOf` now reads `best_of`.
-- **`match_details` denied tennis odds existed.** The `odds` section was gated to UFC; the same match returned bookmaker prices from `tennis_odds`. Both surfaces now share one projection (`summarizeTennisOdds`), and `playerStats` (previously always `null` for tennis) is filled from `/tennis/matches/{id}/stats`.
 - **`player_stats.bySurface` was always four nulls.** The endpoint publishes one object per surface and the projector coerced each to a number. Real per-surface blocks, `servingStats`, and an explicit `unavailable` map for sections the endpoint does not publish.
 - **`limit` was ignored** by `player_rankings_history` (asked 4, got 342) and by `/tennis/matches/completed`. Both are bounded locally now, with `*Returned` versus `*Count` so the day total is never confused with the page.
 - **`tournaments level="WTA 1000"` returned ATP Masters events.** The API's level reverse-map is not tour-aware (`_TIER_WTA` maps both `PM` and `M` to "WTA 1000"), so the tool now sends and enforces the tour the level name states, and drops + counts contradicting rows. Fixed at the source too — the same widening also leaked `WTA 125`, `Challenger`, `Davis Cup` and `Billie Jean King Cup`.
 - **`rankings_movers` called an 84-day gap "week-over-week".** `gapDays`/`comparisonWindow`/`comparisonsAreWeekly` now state the real interval, with a warning. `standings` reports the tennis `ranking_date` as `updatedAt` instead of `null`.
-- **`tennis_odds upcoming` rows carried `matchId: null`** with no alternative key. `joinKey` and `playerIds` make the row joinable without inventing an id.
 - **`tennis_schedule`** now counts the day's list/completed overlap, summarises statuses, and flags date-only `startsAt` placeholders.
 - **`live_matches` labelled tennis rows by tournament**, not players, because the live route's `name` is the event.
 - **Tennis players had no images** although `/tennis/players/{id}` carries `portrait_url`. Now surfaced (plus `ioc` as the side country on boards).

package/dist/instructions.js

@@ -17,6 +17,7 @@ game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | t
 - Default when the user named one title: that game. Default for "what's live?" / multi-title: omit game or all on tools that accept it.
 - On UNSUPPORTED_GAME / 403 for a title: stop retrying that game; call api_health; report plan gaps.
 - Fortnite and other titles may appear via call_api/resources; do not assume they are in the curated enum until list_capabilities says so.
+- RAF (Real American Freestyle wrestling) and BKFC (Bare Knuckle Fighting Championship) are NOT on the game enum: use the combat_* tools with league raf|bkfc (combat_events, combat_card, combat_bout, combat_athlete, combat_h2h, combat_rankings), or call_api /raf/... and /bkfc/.... RAF scores per PERIOD (wrestling points, takedowns); BKFC per ROUND (punches landed/thrown, knockdowns). Never mix either into UFC answers.
 
 ## Preferred tool order
 

package/dist/tools/combat.js

@@ -0,0 +1,491 @@
+import { asRecord, clampInt, extractRows, fetchJson, gameNotIncludedHint } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
+import { boolSchema, limitSchema, stringSchema } from './types.js';
+export const COMBAT_LEAGUES = ['raf', 'bkfc'];
+const LEAGUE_NAMES = {
+    raf: 'Real American Freestyle (pro freestyle wrestling)',
+    bkfc: 'Bare Knuckle Fighting Championship',
+};
+const PEOPLE = { raf: 'athletes', bkfc: 'fighters' };
+const HISTORY = { raf: 'bouts', bkfc: 'fights' };
+const leagueSchema = {
+    type: 'string',
+    enum: [...COMBAT_LEAGUES],
+    description: 'League: "raf" (Real American Freestyle wrestling) or "bkfc" (Bare Knuckle Fighting Championship). Example: "bkfc".',
+};
+function parseLeague(value) {
+    const v = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return COMBAT_LEAGUES.includes(v) ? v : null;
+}
+function leagueError(d, value) {
+    return errorEnvelope({
+        code: 'VALIDATION',
+        message: `league must be raf or bkfc (got ${JSON.stringify(value ?? null)})`,
+        game: null,
+        source: d.source,
+        requestId: d.requestId,
+        tookMs: Date.now() - d.started,
+    });
+}
+function httpError(d, league, res, what) {
+    const body = asRecord(res.data);
+    const err = asRecord(body?.error);
+    return errorEnvelope({
+        code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+        message: (typeof err?.message === 'string' && err.message) || `${what} failed (HTTP ${res.status})`,
+        game: league,
+        source: d.source,
+        httpStatus: res.status,
+        requestId: d.requestId,
+        tookMs: Date.now() - d.started,
+        rateLimit: res.headers,
+    });
+}
+function payload(res) {
+    const body = asRecord(res.data);
+    return body && 'data' in body ? body.data : res.data;
+}
+function sectionFailure(section, res) {
+    const body = asRecord(res.data);
+    const err = asRecord(body?.error);
+    const code = mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) });
+    return partialFromRejection(section, {
+        code,
+        httpStatus: res.status,
+        message: res.status === 403
+            ? `${section} needs the Starter plan or above for this league (${err?.message || 'plan restriction'})`
+            : err?.message || `${section} unavailable (HTTP ${res.status})`,
+    });
+}
+async function resolvePerson(ctx, league, input) {
+    const raw = input.trim();
+    if (/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(raw)) {
+        const probe = await fetchJson(ctx, `/${league}/${PEOPLE[league]}/${encodeURIComponent(raw)}`);
+        if (probe.ok)
+            return { slug: raw };
+        if (probe.status !== 404)
+            return { error: probe };
+    }
+    const res = await fetchJson(ctx, `/${league}/search`, { query: { q: raw.replace(/-/g, ' '), limit: 10 } });
+    if (!res.ok)
+        return { error: res };
+    const hits = extractRows(res.data)
+        .map((r) => asRecord(r))
+        .filter((r) => !!r && (r.type === 'athlete' || r.type === 'fighter'));
+    if (!hits.length)
+        return { notFound: true };
+    const exact = hits.filter((h) => String(h.name ?? '').toLowerCase() === raw.toLowerCase());
+    if (exact.length === 1)
+        return { slug: String(exact[0].slug) };
+    if (hits.length === 1)
+        return { slug: String(hits[0].slug) };
+    return { candidates: hits.slice(0, 8) };
+}
+async function resolveOrFail(d, ctx, league, input, argName) {
+    const r = await resolvePerson(ctx, league, input);
+    if ('slug' in r)
+        return r;
+    if ('error' in r)
+        return { fail: httpError(d, league, r.error, `${argName} lookup`) };
+    if ('candidates' in r) {
+        return {
+            fail: errorEnvelope({
+                code: 'AMBIGUOUS_ENTITY',
+                message: `"${input}" matches several ${PEOPLE[league]}; pass one slug from details.candidates`,
+                game: league,
+                source: d.source,
+                requestId: d.requestId,
+                tookMs: Date.now() - d.started,
+                details: { candidates: r.candidates },
+            }),
+        };
+    }
+    return {
+        fail: errorEnvelope({
+            code: 'NOT_FOUND',
+            message: `No ${league.toUpperCase()} ${PEOPLE[league].slice(0, -1)} matches "${input}"`,
+            game: league,
+            source: d.source,
+            requestId: d.requestId,
+            tookMs: Date.now() - d.started,
+        }),
+    };
+}
+function begin(source) {
+    return { started: Date.now(), requestId: newRequestId(), source };
+}
+export const combatEvents = {
+    name: 'combat_events',
+    description: `RAF wrestling or BKFC bare-knuckle events: upcoming cards or recent results.
+
+When to use:
+- "When is the next RAF / BKFC card?", "recent BKFC results", schedule pages
+- Getting an event slug for combat_card
+
+Each event carries slug, name, date, local start time + timezone, venue/location, status and bout counts.
+
+Prefer over: call_api /raf/events or /bkfc/events.
+Do not use when: you already have the event slug and want its bouts (combat_card).
+
+Parallel-safe: yes. Upstream cost: 1.
+Example: { "league": "bkfc", "when": "upcoming", "limit": 5 }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['league'],
+        properties: {
+            league: leagueSchema,
+            when: {
+                type: 'string',
+                enum: ['upcoming', 'recent'],
+                default: 'upcoming',
+                description: 'upcoming = scheduled cards, soonest first; recent = completed cards, newest first. Example: "recent".',
+            },
+            limit: limitSchema({ default: 10, max: 50, description: 'Max events (default 10, max 50).' }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const d = begin('combat_events');
+        const league = parseLeague(args.league);
+        if (!league)
+            return leagueError(d, args.league);
+        const when = args.when === 'recent' ? 'recent' : 'upcoming';
+        const limit = clampInt(args.limit, 10, 1, 50);
+        const res = await fetchJson(ctx, `/${league}/events/${when}`, { query: { limit } });
+        if (!res.ok)
+            return httpError(d, league, res, `${league} ${when} events`);
+        const events = extractRows(res.data).slice(0, limit);
+        return successEnvelope({
+            data: { league, leagueName: LEAGUE_NAMES[league], when, count: events.length, events },
+            game: league,
+            source: d.source,
+            requestId: d.requestId,
+            tookMs: Date.now() - d.started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+        });
+    },
+};
+export const combatCard = {
+    name: 'combat_card',
+    description: `COMPOSITE fight card for one RAF or BKFC event: event identity + bouts in running order with results.
+
+When to use:
+- "RAF 14 card", "BKFC 95 results", "who won the main event at the last BKFC?"
+- Event pages and results pages
+
+event accepts a slug (e.g. "raf13", "bkfc-95-newark") or "next" / "last". Bouts come main event first; each carries
+weight class, title stakes, both sides (athletes for RAF, red/blue fighters for BKFC with punch totals), and once
+finished the winner and result (RAF: score, takedowns, method; BKFC: method, round, time).
+
+Prefer over: combat_events + call_api per bout.
+Do not use when: you need one bout's period/round breakdown (combat_bout).
+
+Parallel-safe: yes. Upstream cost: 2–3.
+Example: { "league": "raf", "event": "last" }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['league'],
+        properties: {
+            league: leagueSchema,
+            event: stringSchema('Event slug, or "next" / "last" (default "next"). Example: "raf13".', 'next'),
+            limit: limitSchema({ default: 30, max: 40, description: 'Max bouts on the card (default 30, max 40).' }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const d = begin('combat_card');
+        const league = parseLeague(args.league);
+        if (!league)
+            return leagueError(d, args.league);
+        const limit = clampInt(args.limit, 30, 1, 40);
+        let slug = typeof args.event === 'string' && args.event.trim() ? args.event.trim().toLowerCase() : 'next';
+        let calls = 0;
+        if (slug === 'next' || slug === 'last') {
+            const which = slug === 'next' ? 'upcoming' : 'recent';
+            const list = await fetchJson(ctx, `/${league}/events/${which}`, { query: { limit: 1 } });
+            calls += 1;
+            if (!list.ok)
+                return httpError(d, league, list, `${league} ${which} events`);
+            const first = asRecord(extractRows(list.data)[0]);
+            if (!first?.slug) {
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: `No ${which} ${league.toUpperCase()} event`,
+                    game: league,
+                    source: d.source,
+                    requestId: d.requestId,
+                    tookMs: Date.now() - d.started,
+                    upstreamCalls: calls,
+                });
+            }
+            slug = String(first.slug);
+        }
+        const [ev, bouts] = await Promise.all([
+            fetchJson(ctx, `/${league}/events/${encodeURIComponent(slug)}`),
+            fetchJson(ctx, `/${league}/events/${encodeURIComponent(slug)}/bouts`),
+        ]);
+        calls += 2;
+        if (!ev.ok)
+            return httpError(d, league, ev, `${league} event ${slug}`);
+        const partial = [];
+        let rows = [];
+        if (bouts.ok) {
+            const p = payload(bouts);
+            rows = Array.isArray(p) ? p : extractRows(asRecord(p)?.bouts ?? p);
+        }
+        else {
+            partial.push(sectionFailure('bouts', bouts));
+        }
+        const eventData = asRecord(payload(ev)) ?? {};
+        const { bouts: _ignored, ...event } = eventData;
+        return successEnvelope({
+            data: { league, event, boutCount: rows.length, bouts: rows.slice(0, limit) },
+            game: league,
+            source: d.source,
+            requestId: d.requestId,
+            tookMs: Date.now() - d.started,
+            upstreamCalls: calls,
+            rateLimit: bouts.headers ?? ev.headers,
+            partial,
+            truncated: rows.length > limit
+                ? { applied: true, reason: 'section_item_cap', dropped: { itemsFrom: limit, itemsTo: rows.length }, recover: ['Raise limit (max 40)'] }
+                : null,
+        });
+    },
+};
+export const combatBout = {
+    name: 'combat_bout',
+    description: `One RAF or BKFC bout in full, with its scoring breakdown.
+
+RAF: winner, method (decision / tech fall / pin / injury), final score, takedowns, and per-PERIOD scores.
+BKFC: winner, method, round, time, and per-ROUND punch stats for red and blue (landed/thrown, head/body,
+distance/clinch, knockdowns). BKFC round stats need the Starter plan; on Free they come back as a partial note.
+
+Get boutId from combat_card or combat_athlete (e.g. "raf13--belal-muhammad--colby-covington").
+
+Parallel-safe: yes. Upstream cost: 1–2.
+Example: { "league": "bkfc", "boutId": "bkfc-fight-night-bethlehem--gregoris-cisneros--ryan-petersen" }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['league', 'boutId'],
+        properties: {
+            league: leagueSchema,
+            boutId: stringSchema('Bout id from combat_card / combat_athlete. Example: "raf13--belal-muhammad--colby-covington".'),
+            includeBreakdown: boolSchema('Include per-period (RAF) / per-round (BKFC) breakdown (default true).', true),
+        },
+    },
+    handler: async (args, ctx) => {
+        const d = begin('combat_bout');
+        const league = parseLeague(args.league);
+        if (!league)
+            return leagueError(d, args.league);
+        const boutId = typeof args.boutId === 'string' ? args.boutId.trim() : '';
+        if (!boutId) {
+            return errorEnvelope({ code: 'VALIDATION', message: 'boutId is required', game: league, source: d.source,
+                requestId: d.requestId, tookMs: Date.now() - d.started });
+        }
+        const id = encodeURIComponent(boutId);
+        const breakdown = args.includeBreakdown !== false;
+        const sub = league === 'raf' ? 'periods' : 'rounds';
+        const [bout, parts] = await Promise.all([
+            fetchJson(ctx, `/${league}/bouts/${id}`),
+            breakdown ? fetchJson(ctx, `/${league}/bouts/${id}/${sub}`) : Promise.resolve(null),
+        ]);
+        if (!bout.ok)
+            return httpError(d, league, bout, `${league} bout ${boutId}`);
+        const partial = [];
+        const data = { league, bout: payload(bout) };
+        if (parts) {
+            if (parts.ok)
+                data[sub] = asRecord(payload(parts))?.[sub] ?? payload(parts);
+            else
+                partial.push(sectionFailure(sub, parts));
+        }
+        const b = asRecord(data.bout);
+        if (league === 'bkfc' && b && 'rounds' in b && data.rounds)
+            delete b.rounds;
+        return successEnvelope({
+            data,
+            game: league,
+            source: d.source,
+            requestId: d.requestId,
+            tookMs: Date.now() - d.started,
+            upstreamCalls: parts ? 2 : 1,
+            rateLimit: bout.headers,
+            partial,
+        });
+    },
+};
+export const combatAthlete = {
+    name: 'combat_athlete',
+    description: `COMPOSITE RAF athlete / BKFC fighter page: profile + recent bouts + career stats.
+
+When to use:
+- "Kyle Snyder's RAF record", "Arlovski BKFC stats", athlete/fighter profile pages
+
+athlete accepts a slug ("kyle-snyder") or a name ("Andrei Arlovski"); names are resolved through the league's
+search, and several matches return AMBIGUOUS_ENTITY with candidates. Profile carries record, division, nickname,
+country, official headshot (+ its credit — show it with the image). Career stats need the Starter plan; on Free
+they come back as a partial note while profile and history still return.
+
+Prefer over: call_api profile + history + stats separately.
+
+Parallel-safe: yes. Upstream cost: 2–4.
+Example: { "league": "raf", "athlete": "Kyle Snyder", "historyLimit": 5 }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['league', 'athlete'],
+        properties: {
+            league: leagueSchema,
+            athlete: stringSchema('Athlete/fighter slug or name. Example: "kyle-snyder".'),
+            includeHistory: boolSchema('Include recent bouts (default true).', true),
+            historyLimit: limitSchema({ default: 10, max: 50, description: 'Max bouts of history (default 10, max 50).' }),
+            includeStats: boolSchema('Include career stats (default true; Starter plan).', true),
+        },
+    },
+    handler: async (args, ctx) => {
+        const d = begin('combat_athlete');
+        const league = parseLeague(args.league);
+        if (!league)
+            return leagueError(d, args.league);
+        const input = typeof args.athlete === 'string' ? args.athlete : typeof args.fighter === 'string' ? args.fighter : '';
+        if (!input.trim()) {
+            return errorEnvelope({ code: 'VALIDATION', message: 'athlete is required (slug or name)', game: league,
+                source: d.source, requestId: d.requestId, tookMs: Date.now() - d.started });
+        }
+        const r = await resolveOrFail(d, ctx, league, input, 'athlete');
+        if ('fail' in r)
+            return r.fail;
+        const base = `/${league}/${PEOPLE[league]}/${encodeURIComponent(r.slug)}`;
+        const historyLimit = clampInt(args.historyLimit, 10, 1, 50);
+        const [profile, history, stats] = await Promise.all([
+            fetchJson(ctx, base),
+            args.includeHistory === false ? Promise.resolve(null) : fetchJson(ctx, `${base}/${HISTORY[league]}`, { query: { limit: historyLimit } }),
+            args.includeStats === false ? Promise.resolve(null) : fetchJson(ctx, `${base}/stats`),
+        ]);
+        if (!profile.ok)
+            return httpError(d, league, profile, `${league} ${PEOPLE[league]} ${r.slug}`);
+        const partial = [];
+        const data = { league, slug: r.slug, profile: payload(profile) };
+        if (history) {
+            if (history.ok)
+                data.history = extractRows(history.data).slice(0, historyLimit);
+            else
+                partial.push(sectionFailure('history', history));
+        }
+        if (stats) {
+            if (stats.ok)
+                data.stats = payload(stats);
+            else
+                partial.push(sectionFailure('stats', stats));
+        }
+        return successEnvelope({
+            data,
+            game: league,
+            source: d.source,
+            requestId: d.requestId,
+            tookMs: Date.now() - d.started,
+            upstreamCalls: 1 + (history ? 1 : 0) + (stats ? 1 : 0),
+            rateLimit: profile.headers,
+            partial,
+        });
+    },
+};
+export const combatH2h = {
+    name: 'combat_h2h',
+    description: `Head-to-head between two RAF athletes or two BKFC fighters: record and every meeting.
+
+Accepts slugs or names for both sides (names resolve through the league's search).
+
+Parallel-safe: yes. Upstream cost: 1–3.
+Example: { "league": "bkfc", "athleteA": "ryan-petersen", "athleteB": "gregoris-cisneros" }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['league', 'athleteA', 'athleteB'],
+        properties: {
+            league: leagueSchema,
+            athleteA: stringSchema('First athlete/fighter slug or name. Example: "kyle-snyder".'),
+            athleteB: stringSchema('Second athlete/fighter slug or name. Example: "wyatt-hendrickson".'),
+        },
+    },
+    handler: async (args, ctx) => {
+        const d = begin('combat_h2h');
+        const league = parseLeague(args.league);
+        if (!league)
+            return leagueError(d, args.league);
+        const a = typeof args.athleteA === 'string' ? args.athleteA : '';
+        const b = typeof args.athleteB === 'string' ? args.athleteB : '';
+        if (!a.trim() || !b.trim()) {
+            return errorEnvelope({ code: 'VALIDATION', message: 'athleteA and athleteB are required', game: league,
+                source: d.source, requestId: d.requestId, tookMs: Date.now() - d.started });
+        }
+        const [ra, rb] = await Promise.all([
+            resolveOrFail(d, ctx, league, a, 'athleteA'),
+            resolveOrFail(d, ctx, league, b, 'athleteB'),
+        ]);
+        if ('fail' in ra)
+            return ra.fail;
+        if ('fail' in rb)
+            return rb.fail;
+        const query = league === 'raf' ? { athlete1: ra.slug, athlete2: rb.slug } : { fighter1: ra.slug, fighter2: rb.slug };
+        const res = await fetchJson(ctx, `/${league}/h2h`, { query });
+        if (!res.ok)
+            return httpError(d, league, res, `${league} head-to-head`);
+        return successEnvelope({
+            data: { league, athleteA: ra.slug, athleteB: rb.slug, h2h: payload(res) },
+            game: league,
+            source: d.source,
+            requestId: d.requestId,
+            tookMs: Date.now() - d.started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+        });
+    },
+};
+export const combatRankings = {
+    name: 'combat_rankings',
+    description: `Champions and rankings: RAF title holders per division, BKFC official rankings + champions.
+
+BKFC: omit division for every division's ranked list (champion, interim champion, ranked fighters), or pass one
+(e.g. "heavyweight", "womens-flyweight"). RAF has no ranked lists; it returns every title and its holder, or one
+division's detail when division is given (e.g. "men-heavyweight").
+
+Parallel-safe: yes. Upstream cost: 1.
+Example: { "league": "bkfc", "division": "heavyweight" }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['league'],
+        properties: {
+            league: leagueSchema,
+            division: stringSchema('Optional division key. Example: "heavyweight".'),
+        },
+    },
+    handler: async (args, ctx) => {
+        const d = begin('combat_rankings');
+        const league = parseLeague(args.league);
+        if (!league)
+            return leagueError(d, args.league);
+        const division = typeof args.division === 'string' ? args.division.trim().toLowerCase() : '';
+        const path = league === 'bkfc'
+            ? division ? `/bkfc/rankings/${encodeURIComponent(division)}` : '/bkfc/rankings'
+            : division ? `/raf/divisions/${encodeURIComponent(division)}` : '/raf/champions';
+        const res = await fetchJson(ctx, path);
+        if (!res.ok)
+            return httpError(d, league, res, `${league} rankings`);
+        return successEnvelope({
+            data: { league, division: division || null, rankings: payload(res) },
+            game: league,
+            source: d.source,
+            requestId: d.requestId,
+            tookMs: Date.now() - d.started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+        });
+    },
+};
+export const combatTools = [combatEvents, combatCard, combatBout, combatAthlete, combatH2h, combatRankings];

package/dist/tools/index.js

@@ -11,6 +11,7 @@ import { insightTools } from './insight.js';
 import { cs2Tools } from './cs2.js';
 import { tournamentTools } from './tournaments.js';
 import { scheduleTools } from './schedule.js';
+import { combatTools } from './combat.js';
 export const allTools = [
     ...metaTools.filter((t) => t.name === 'list_capabilities' || t.name === 'api_health'),
     ...resolveTools,
@@ -25,6 +26,7 @@ export const allTools = [
     ...scheduleTools,
     ...insightTools,
     ...cs2Tools,
+    ...combatTools,
     ...metaTools.filter((t) => t.name === 'list_routes' || t.name === 'call_api'),
 ];
 export function getTool(name) {

package/dist/tools/match.js

@@ -809,7 +809,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
             else {
                 partial.push(partialFromRejection('odds', {
                     code: 'NOT_IMPLEMENTED',
-                    message: `Odds are not curated for ${game}. Currently available: UFC (/ufc/bouts/{id}/odds). Tennis odds were withdrawn.`,
+                    message: `Odds are only available for UFC (/ufc/bouts/{id}/odds).`,
                 }));
             }
         }

package/dist/tools/meta.js

@@ -2,6 +2,68 @@ import { extractRows, fetchJson, gameNotIncludedHint, present } from '../client.
 import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
 import { boolSchema, gameSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
 import { PACKAGE_VERSION as CATALOG_VERSION } from '../version.js';
+const COMBAT_CATALOG = [
+    {
+        name: 'combat_events',
+        doNotUse: 'You already have the event slug → combat_card',
+        outcome: 'RAF wrestling / BKFC bare-knuckle events: upcoming cards or recent results, with date, local time and venue',
+        parallelSafe: true,
+        games: ['raf', 'bkfc'],
+        jobs: ['schedule'],
+        exampleArgs: { league: 'bkfc', when: 'upcoming', limit: 5 },
+        preferOver: ['call_api /raf/events or /bkfc/events'],
+    },
+    {
+        name: 'combat_card',
+        doNotUse: "One bout's period/round breakdown → combat_bout",
+        outcome: 'One RAF/BKFC event card in running order with results; event = slug, "next" or "last"',
+        parallelSafe: true,
+        games: ['raf', 'bkfc'],
+        jobs: ['event_card', 'schedule', 'media'],
+        exampleArgs: { league: 'raf', event: 'last' },
+        preferOver: ['combat_events + call_api per bout'],
+    },
+    {
+        name: 'combat_bout',
+        doNotUse: 'Whole card → combat_card',
+        preferOver: [],
+        outcome: 'One bout in full: RAF per-period scores / BKFC per-round punch stats (Starter)',
+        parallelSafe: true,
+        games: ['raf', 'bkfc'],
+        jobs: ['match_page'],
+        exampleArgs: { league: 'raf', boutId: 'raf13--belal-muhammad--colby-covington' },
+    },
+    {
+        name: 'combat_athlete',
+        doNotUse: "Two athletes' meetings → combat_h2h",
+        preferOver: [],
+        outcome: 'RAF athlete / BKFC fighter page: profile + headshot, recent bouts, career stats (Starter); slug or name',
+        parallelSafe: true,
+        games: ['raf', 'bkfc'],
+        jobs: ['player_form', 'media'],
+        exampleArgs: { league: 'raf', athlete: 'Kyle Snyder', historyLimit: 5 },
+    },
+    {
+        name: 'combat_h2h',
+        doNotUse: "One athlete's whole history → combat_athlete",
+        preferOver: [],
+        outcome: 'Head-to-head between two RAF athletes or two BKFC fighters',
+        parallelSafe: true,
+        games: ['raf', 'bkfc'],
+        jobs: ['h2h', 'preview'],
+        exampleArgs: { league: 'bkfc', athleteA: 'ryan-petersen', athleteB: 'gregoris-cisneros' },
+    },
+    {
+        name: 'combat_rankings',
+        doNotUse: 'UFC rankings → standings / rankings tools (RAF/BKFC never appear in UFC answers)',
+        preferOver: [],
+        outcome: 'RAF champions per division / BKFC official rankings and champions',
+        parallelSafe: true,
+        games: ['raf', 'bkfc'],
+        jobs: ['standings'],
+        exampleArgs: { league: 'bkfc', division: 'heavyweight' },
+    },
+];
 const TOOL_CATALOG = [
     {
         name: 'list_capabilities',
@@ -419,6 +481,7 @@ const TOOL_CATALOG = [
         preferOver: [],
         doNotUse: 'Any job covered by a curated tool',
     },
+    ...COMBAT_CATALOG,
 ];
 const JOBS = [
     { id: 'live_board', description: 'Ops/dashboard live strip', recommendedTools: ['live_matches', 'match_summary'] },
@@ -488,18 +551,18 @@ const GAMES_META = [
 ];
 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.
+    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',
@@ -582,18 +645,18 @@ Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
 };
 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.
+    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',
@@ -724,6 +787,8 @@ const ALLOWLIST_PREFIXES = [
     '/ufc',
     '/fortnite',
     '/tennis',
+    '/raf',
+    '/bkfc',
     '/openapi.json',
 ];
 function pathAllowed(path) {
@@ -736,21 +801,21 @@ function pathAllowed(path) {
 }
 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, /tennis.
-Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
-
-Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
+    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, /tennis, /raf, /bkfc.
+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',
@@ -872,20 +937,20 @@ const SPEC_OMITS = {
 };
 export const listRoutes = {
     name: 'list_routes',
-    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
-
-When to use:
-- You need a long-tail path for call_api and do not want to guess
-- Checking whether an endpoint exists before building around it
-- Mapping what raw data backs a curated tool
-
-Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
-
-Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
-
-Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
-
-Parallel-safe: yes. Upstream cost: 1.
+    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
+
+When to use:
+- You need a long-tail path for call_api and do not want to guess
+- Checking whether an endpoint exists before building around it
+- Mapping what raw data backs a curated tool
+
+Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
+
+Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
+
+Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
+
+Parallel-safe: yes. Upstream cost: 1.
 Example: { "game": "ufc", "q": "rankings" }`,
     inputSchema: {
         type: 'object',
@@ -909,10 +974,10 @@ Example: { "game": "ufc", "q": "rankings" }`,
         const started = Date.now();
         const requestId = newRequestId();
         const gameRaw = typeof args.game === 'string' ? args.game.toLowerCase().trim() : '';
-        if (gameRaw && !gameRaw.match(/^(lol|cs2|dota2|cod|ufc|fortnite|tennis)$/)) {
+        if (gameRaw && !gameRaw.match(/^(lol|cs2|dota2|cod|ufc|fortnite|tennis|raf|bkfc)$/)) {
             return errorEnvelope({
                 code: 'UNSUPPORTED_GAME',
-                message: `unsupported game "${gameRaw}"; use lol|cs2|dota2|cod|ufc|fortnite|tennis`,
+                message: `unsupported game "${gameRaw}"; use lol|cs2|dota2|cod|ufc|fortnite|tennis|raf|bkfc`,
                 game: null,
                 source: 'list_routes',
                 requestId,

package/package.json

@@ -1,51 +1,51 @@
-{
-  "name": "cito-mcp",
-  "version": "0.4.6",
-  "description": "Standalone MCP server for the Cito esports and sports API — curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
-  "type": "module",
-  "homepage": "https://cito.gg",
-  "//REPOSITORY": "Intentionally NOT set. cito-api-scraper and cito.gg are PRIVATE repos and must stay that way, so a repository URL pointing at them would render as a broken 404 link on the public npm page and would not satisfy MCP Registry npm ownership validation. Set this only if a PUBLIC repo for this package is ever created (e.g. achillesscriptsvip/cito-mcp with this directory as root) — then use `git+https://github.com/OWNER/REPO.git` and mirror it in the `mcpName`/server.json `name` pair. Do not point it at the private monorepo.",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "esports",
-    "cs2",
-    "counter-strike",
-    "counter-strike-2",
-    "lol",
-    "league-of-legends",
-    "dota2",
-    "cod",
-    "ufc",
-    "mma",
-    "tennis",
-    "live-scores",
-    "sports-data",
-    "esports-api"
-  ],
-  "bin": {
-    "cito-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "tsx --test src/**/*.test.ts src/*.test.ts",
-    "start": "node dist/index.js",
-    "prepublishOnly": "npm run build && npm test && npm run smoke",
-    "smoke": "node scripts/smoke.mjs"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "tsx": "^4.23.1",
-    "typescript": "^5.9.2"
-  }
-}
+{
+  "name": "cito-mcp",
+  "version": "0.4.8",
+  "description": "Standalone MCP server for the Cito esports and sports API \u2014 curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
+  "type": "module",
+  "homepage": "https://cito.gg",
+  "//REPOSITORY": "Intentionally NOT set. cito-api-scraper and cito.gg are PRIVATE repos and must stay that way, so a repository URL pointing at them would render as a broken 404 link on the public npm page and would not satisfy MCP Registry npm ownership validation. Set this only if a PUBLIC repo for this package is ever created (e.g. achillesscriptsvip/cito-mcp with this directory as root) \u2014 then use `git+https://github.com/OWNER/REPO.git` and mirror it in the `mcpName`/server.json `name` pair. Do not point it at the private monorepo.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "esports",
+    "cs2",
+    "counter-strike",
+    "counter-strike-2",
+    "lol",
+    "league-of-legends",
+    "dota2",
+    "cod",
+    "ufc",
+    "mma",
+    "tennis",
+    "live-scores",
+    "sports-data",
+    "esports-api"
+  ],
+  "bin": {
+    "cito-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsx --test src/**/*.test.ts src/*.test.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build && npm test && npm run smoke",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.2"
+  }
+}

package/dist/tools/odds.js

@@ -1,287 +0,0 @@
-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';
-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,
-                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,
-            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,
-    };
-}
-export function summarizeTennisOdds(data) {
-    const root = asRecord(data) ?? {};
-    const payload = asRecord(root.data) ?? root;
-    const coverage = asRecord(payload.coverage) ?? {};
-    const bookmakers = (Array.isArray(payload.bookmakers) ? payload.bookmakers : []).map(normalizeBookmaker);
-    const hasOdds = coverage.odds === true || bookmakers.length > 0;
-    return {
-        matchId: pickString(payload.match_id) ?? null,
-        oddsFormat: pickString(payload.odds_format) ?? 'decimal',
-        commenceTime: pickString(payload.commence_time) ?? null,
-        stale: payload.stale === true,
-        bookmakers,
-        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.',
-        fullBookPath: '/tennis/odds/{matchId}',
-    };
-}
-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.
-A match id that does not exist is a NOT_FOUND error, not a coverage gap: the
-odds route answers 200/odds:false for every unknown id, so scope=match and
-scope=live verify the match against /tennis/matches/{id} before reporting a gap,
-and set matchExists.
-
-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) ?? {};
-                const homeId = pickString(home.player_id, home.id) ?? null;
-                const awayId = pickString(away.player_id, away.id) ?? null;
-                const matchId = pickString(r.match_id, r.id) ?? null;
-                const oddsEventId = pickString(r.odds_event_id) ?? null;
-                return {
-                    matchId,
-                    oddsEventId,
-                    tournament: pickString(r.tournament) ?? null,
-                    commenceTime: pickString(r.commence_time, r.starts_at) ?? null,
-                    player1: { name: pickString(home.name) ?? null, id: homeId },
-                    player2: { name: pickString(away.name) ?? null, id: awayId },
-                    bookmakers: Array.isArray(r.bookmakers) ? r.bookmakers.map((b) => pickString(b) ?? null) : [],
-                    live: r.live === true,
-                    joinKey: matchId
-                        ? { kind: 'matchId', matchId }
-                        : oddsEventId
-                            ? { kind: 'oddsEventId', oddsEventId }
-                            : null,
-                    playerIds: [homeId, awayId].filter((x) => Boolean(x)),
-                };
-            });
-            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, {});
-        let upstreamCalls = 1;
-        let rateLimit = res.headers;
-        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 summary = summarizeTennisOdds(res.data);
-        let matchExists = null;
-        if (summary.oddsAvailable !== true) {
-            const probe = await fetchJson(ctx, `/tennis/matches/${encodeURIComponent(matchId)}`);
-            upstreamCalls += 1;
-            rateLimit = { ...rateLimit, ...probe.headers };
-            matchExists = probe.ok;
-            if (!matchExists) {
-                const liveProbe = await fetchJson(ctx, `/tennis/matches/live/${encodeURIComponent(matchId)}`);
-                upstreamCalls += 1;
-                rateLimit = { ...rateLimit, ...liveProbe.headers };
-                matchExists = liveProbe.ok;
-            }
-            if (!matchExists) {
-                return errorEnvelope({
-                    code: 'NOT_FOUND',
-                    message: `No tennis match with id '${matchId}' — the odds feed has no event for it because the id itself does not exist`,
-                    game,
-                    source: 'tennis_odds',
-                    requestId,
-                    tookMs: Date.now() - started,
-                    upstreamCalls,
-                    rateLimit,
-                    httpStatus: 200,
-                    recover: [
-                        'Check the id with live_matches or tennis_schedule / match_summary',
-                        'Ids come from live_matches (s365_*) or the archive (s365_{year}_{gid})',
-                        `For the pre-match odds list instead, call tennis_odds { game: "tennis", scope: "upcoming" }`,
-                    ],
-                });
-            }
-        }
-        return successEnvelope({
-            source: 'tennis_odds',
-            game,
-            requestId,
-            tookMs: Date.now() - started,
-            upstreamCalls,
-            rateLimit,
-            data: {
-                title: `Tennis ${scopeRaw} odds — ${matchId}`,
-                scope: scopeRaw,
-                ...summary,
-                matchId: summary.matchId ?? matchId,
-                matchExists,
-            },
-        });
-    },
-};
-export const oddsTools = [tennisOdds];