cito-mcp 0.4.7 → 0.4.9

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.4.7` · **Node:** `>=20` · **Install:** `npx cito-mcp`
+**Version:** `0.4.9` · **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**, **BKFC bare knuckle** and the **Bellator MMA archive** (2014-2017) through the `combat_*` tools. Long-tail REST stays available via `call_api`.
 
 ---
 
@@ -240,7 +240,17 @@ upstream, so a non-null `headshotUrl` always has a `license` beside it.
 | `cs2` | deep | Prefixed ids; live path **`GET /cs2/live`**; trends / rankings |
 | `dota2` | thin | Numeric ids; radar; weak/no standings & roster endpoints |
 | `cod` | medium | Org slugs; CDL standings; UUID match ids |
-| `ufc` | medium | Fighter slugs; `boutId`; live + rankings |
+| `ufc` | medium | Fighter slugs; `boutId`; live + rankings. Includes Dana White's Contender Series and Road to UFC (2022-2026, all 19 cards with official round stats; event slugs like `road-to-ufc-2-7`, titles "Road to UFC 2.7") |
+
+### Combat leagues (`combat_*`, `league` argument)
+
+RAF, BKFC and Bellator are not on the `game` enum. `combat_events`, `combat_card`, `combat_bout`, `combat_athlete`, `combat_h2h` and `combat_rankings` take `league: "raf" | "bkfc" | "bellator"`, and `call_api` reaches `/raf`, `/bkfc` and `/bellator`. None of them is ever mixed into UFC answers.
+
+| League | Scoring | Notes |
+| --- | --- | --- |
+| `raf` | per PERIOD (wrestling points, takedowns) | Athletes; champions per division |
+| `bkfc` | per ROUND (punches landed/thrown, knockdowns) | Fighters; official rankings + champions |
+| `bellator` | per ROUND, official stats in UFC's shape (`"13 of 18"`, `controlTime "1:42"`, round 0 = whole fight; knockdowns, submission attempts, reversals) | Closed archive: Bellator 131-172 (Nov 2014 - Feb 2017), ~20 cards / ~230 bouts. Bout ids like `bellator-5600`, event slugs like `bellator-142` (or `142`). A fighter we also hold a UFC record for keeps the **same slug** as `/ufc/fighters/{slug}` (`ufcFighterSlug`). No live data, rankings or upcoming cards: `combat_events` `when:"upcoming"` returns `[]` with a note (default is `recent`), `combat_card` `event:"last"` is the most recent card (the default) and `"next"` is a non-retryable `NOT_IMPLEMENTED`, `combat_rankings` is a non-retryable `NOT_IMPLEMENTED`. All of it is older than the Free (30-day) / Starter (90-day) history window, so its stats are Pro: on those plans round stats come back as a `HISTORY_WINDOW_EXCEEDED` partial note while results still return. |
 
 ### UFC projection notes (0.2.4)
 
@@ -259,7 +269,7 @@ Fortnite: **`call_api` only** until promoted into the primary enum.
 
 Path must start with `/` and match one of:
 
-`/health` · `/lol` · `/cs2` · `/dota2` · `/cod` · `/ufc` · `/fortnite`
+`/health` · `/lol` · `/cs2` · `/dota2` · `/cod` · `/ufc` · `/fortnite` · `/tennis` · `/raf` · `/bkfc` · `/bellator` · `/openapi.json`
 
 Absolute URLs and `..` traversal → `PATH_NOT_ALLOWED`. Prefer curated tools for all standard jobs.
 
@@ -540,6 +550,15 @@ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 
 ## Changelog (summary)
 
+### 0.4.9
+
+- **Bellator MMA archive** (`/api/v1/bellator`): `league: "bellator"` on every `combat_*` tool, and `/bellator` on the `call_api` / `list_routes` allowlist. Bellator 131-172 (Nov 2014 - Feb 2017) with official per-round stats in `/ufc`'s shape; fighters with a UFC record share the UFC slug (`combat_athlete` returns `ufcFighterSlug`). Archive gaps are answered honestly: upcoming events are an empty list with a note, `combat_card` defaults to the most recent card and refuses `"next"`, and `combat_rankings` returns a non-retryable `NOT_IMPLEMENTED`. `HISTORY_WINDOW_EXCEEDED` sections are reported as a plan gap (Pro), not as a key problem.
+- Agent guidance (server instructions, `list_capabilities`): Bellator is never mixed into UFC answers; UFC already includes Dana White's Contender Series and **Road to UFC** (2022-2026, all 19 cards with official round stats, slugs like `road-to-ufc-2-7`).
+
+### 0.4.8
+
+- RAF wrestling and BKFC bare knuckle: six league-parameterised `combat_*` tools, and `/raf` + `/bkfc` on the `call_api` allowlist.
+
 ### 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.

package/dist/envelope.js

@@ -38,7 +38,7 @@ export const DEFAULT_RECOVER = {
         'Call api_health to see which games your plan includes',
     ],
     PATH_NOT_ALLOWED: [
-        'Use only allowlisted path prefixes: /health /lol /cs2 /dota2 /cod /ufc /fortnite',
+        'Use only allowlisted path prefixes: /health /lol /cs2 /dota2 /cod /ufc /fortnite /tennis /raf /bkfc /bellator',
         'Prefer a curated tool from list_capabilities when one covers the outcome',
     ],
     NOT_IMPLEMENTED: [

package/dist/instructions.js

@@ -17,6 +17,9 @@ 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.
+- Bellator MMA is not on the enum either: combat_* tools with league bellator, or call_api /bellator/.... A closed 2014-2017 archive (Bellator 131-172) with official per-ROUND stats in UFC's shape ("13 of 18", round 0 = whole fight); no live, rankings or upcoming cards (combat_card "last" = most recent card). A fighter with a UFC record keeps the SAME slug as /ufc/fighters/{slug} (ufcFighterSlug). Never mix Bellator fights into UFC answers. Its stats predate the Free/Starter window: HISTORY_WINDOW_EXCEEDED means Pro, not a bad key.
+- UFC includes DWCS and Road to UFC (2022-2026, all 19 cards with official round stats; slugs like road-to-ufc-2-7, "Road to UFC 2.7").
 
 ## Preferred tool order
 

package/dist/tools/combat.js

@@ -0,0 +1,584 @@
+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', 'bellator'];
+const LEAGUE_NAMES = {
+    raf: 'Real American Freestyle (pro freestyle wrestling)',
+    bkfc: 'Bare Knuckle Fighting Championship',
+    bellator: 'Bellator MMA',
+};
+const ARCHIVES = {
+    bellator: 'Bellator is a closed archive (Bellator 131-172, November 2014 to February 2017)',
+};
+const PEOPLE = { raf: 'athletes', bkfc: 'fighters', bellator: 'fighters' };
+const HISTORY = { raf: 'bouts', bkfc: 'fights', bellator: 'fights' };
+const leagueSchema = {
+    type: 'string',
+    enum: [...COMBAT_LEAGUES],
+    description: 'League: "raf" (Real American Freestyle wrestling), "bkfc" (Bare Knuckle Fighting Championship) or "bellator" ' +
+        '(Bellator MMA archive, 2014-2017). 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, bkfc or bellator (got ${JSON.stringify(value ?? null)})`,
+        game: null,
+        source: d.source,
+        requestId: d.requestId,
+        tookMs: Date.now() - d.started,
+    });
+}
+function isHistoryWindow(res) {
+    return res.status === 403 && asRecord(asRecord(res.data)?.error)?.code === 'HISTORY_WINDOW_EXCEEDED';
+}
+const HISTORY_WINDOW_RECOVER = [
+    'Free reads 30 days and Starter 90 days of in-depth stats; Pro reads the full archive',
+    'Summary sections (combat_card bouts, combat_athlete history) still return the records without stat blocks',
+];
+function httpError(d, league, res, what) {
+    const body = asRecord(res.data);
+    const err = asRecord(body?.error);
+    return errorEnvelope({
+        ...(isHistoryWindow(res) ? { recover: HISTORY_WINDOW_RECOVER } : {}),
+        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 upstreamNotes(res) {
+    const meta = asRecord(asRecord(res.data)?.meta);
+    const out = {};
+    if (typeof meta?.note === 'string')
+        out.note = meta.note;
+    if (meta?.historyWindow)
+        out.historyWindow = meta.historyWindow;
+    return out;
+}
+function sectionFailure(section, res, league) {
+    const body = asRecord(res.data);
+    const err = asRecord(body?.error);
+    const code = mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) });
+    let message = err?.message || `${section} unavailable (HTTP ${res.status})`;
+    if (isHistoryWindow(res)) {
+        message =
+            `${section} is older than this key's history window (HISTORY_WINDOW_EXCEEDED: Free 30 days, Starter 90 days; ` +
+                `Pro reads the full archive)` + (league && ARCHIVES[league] ? `. ${ARCHIVES[league]}, so all of its stats need Pro` : '');
+    }
+    else if (res.status === 403) {
+        message = `${section} needs the Starter plan or above for this league (${err?.message || 'plan restriction'})`;
+    }
+    return partialFromRejection(section, { code, httpStatus: res.status, message });
+}
+function archiveGap(d, league, message, recover, calls = 0) {
+    return errorEnvelope({
+        code: 'NOT_IMPLEMENTED',
+        message,
+        game: league,
+        source: d.source,
+        requestId: d.requestId,
+        tookMs: Date.now() - d.started,
+        upstreamCalls: calls,
+        retryable: false,
+        recover,
+    });
+}
+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, BKFC bare-knuckle or Bellator MMA events: upcoming cards or recent results.
+
+When to use:
+- "When is the next RAF / BKFC card?", "recent BKFC results", "Bellator cards from 2015", 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.
+Bellator is a closed archive (Bellator 131-172, Nov 2014 - Feb 2017): "when" defaults to "recent" (newest card
+first), and "upcoming" returns an empty list with data.note instead of failing.
+
+Prefer over: call_api /raf/events, /bkfc/events or /bellator/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. Default "upcoming" ' +
+                    '("recent" for bellator, an archive). 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 archive = ARCHIVES[league];
+        const when = args.when === 'recent' || args.when === 'upcoming' ? args.when : archive ? 'recent' : 'upcoming';
+        const limit = clampInt(args.limit, 10, 1, 50);
+        if (archive && when === 'upcoming') {
+            return successEnvelope({
+                data: {
+                    league, leagueName: LEAGUE_NAMES[league], when, count: 0, events: [],
+                    note: `${archive}: there are no upcoming cards. Use when "recent" for its cards, newest first.`,
+                },
+                game: league,
+                source: d.source,
+                requestId: d.requestId,
+                tookMs: Date.now() - d.started,
+                upstreamCalls: 0,
+            });
+        }
+        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, ...upstreamNotes(res) },
+            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, BKFC or Bellator event: event identity + bouts in running order with results.
+
+When to use:
+- "RAF 14 card", "BKFC 95 results", "Bellator 142 card", "who won the main event at the last BKFC?"
+- Event pages and results pages
+
+event accepts a slug (e.g. "raf13", "bkfc-95-newark", "bellator-142" or "142") 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, red/blue fighters for Bellator with UFC-format totals and ufcFighterSlug), and once finished the winner
+and result (RAF: score, takedowns, method; BKFC/Bellator: method, round, time).
+Bellator is an archive: event defaults to "last" (its most recent card, Bellator 172), and "next" is a
+non-retryable NOT_IMPLEMENTED (there are no upcoming cards).
+
+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"; "last" for bellator). 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);
+        const archive = ARCHIVES[league];
+        let slug = typeof args.event === 'string' && args.event.trim() ? args.event.trim().toLowerCase() : archive ? 'last' : 'next';
+        let calls = 0;
+        if (archive && slug === 'next') {
+            return archiveGap(d, league, `${archive}: there is no next card.`, [
+                `Use event "last" for the most recent ${league} card, or a slug from combat_events { league: "${league}", when: "recent" }`,
+            ]);
+        }
+        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) {
+                const windowed = !!upstreamNotes(list).historyWindow;
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: windowed
+                        ? `No ${which} ${league.toUpperCase()} event inside this key's history window (meta.historyWindow); pass an event slug instead`
+                        : `No ${which} ${league.toUpperCase()} event`,
+                    game: league,
+                    source: d.source,
+                    requestId: d.requestId,
+                    tookMs: Date.now() - d.started,
+                    upstreamCalls: calls,
+                    ...(windowed ? { retryable: false, details: { historyWindow: upstreamNotes(list).historyWindow } } : {}),
+                });
+            }
+            slug = String(first.slug);
+        }
+        const [ev, bouts] = await Promise.all([
+            fetchJson(ctx, `/${league}/events/${encodeURIComponent(slug)}`, league === 'bellator' ? { query: { includeBouts: 'false' } } : undefined),
+            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, league));
+        }
+        const eventData = asRecord(payload(ev)) ?? {};
+        const { bouts: _ignored, card: _card, ...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, BKFC or Bellator 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.
+Bellator: winner, method, round, time, finish (position / submission), referee, judges' scores, each corner's
+whole-fight totals, and per-ROUND official stats in UFC's format (significantStrikes "13 of 18", totalStrikes,
+takedowns, head/body/leg, distance/clinch/ground, knockdowns, submissionAttempts, reversals, controlTime "1:42").
+The archive is 2014-2017, older than the Free/Starter history window: on those plans rounds come back as a
+HISTORY_WINDOW_EXCEEDED partial note while the result still returns.
+
+Get boutId from combat_card or combat_athlete (e.g. "raf13--belal-muhammad--colby-covington", "bellator-5600").
+
+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 (Bellator: "bellator-5600"). Example: "raf13--belal-muhammad--colby-covington".'),
+            includeBreakdown: boolSchema('Include per-period (RAF) / per-round (BKFC, Bellator) 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, league));
+        }
+        const b = asRecord(data.bout);
+        if (league === 'bkfc' && b && 'rounds' in b && data.rounds)
+            delete b.rounds;
+        if (league === 'bellator' && b && 'roundStats' in b && (data.rounds || !breakdown))
+            delete b.roundStats;
+        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 or Bellator fighter page: profile + recent bouts + career stats.
+
+When to use:
+- "Kyle Snyder's RAF record", "Arlovski BKFC stats", "Tito Ortiz in Bellator", 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.
+Bellator: profile is bio (DOB, height, reach, stance, hometown) + Bellator-only record (2014-2017 archive, not the
+whole career); stats are career totals in UFC's format. A fighter we also hold a UFC record for keeps the SAME slug
+as /ufc/fighters/{slug}: data.ufcFighterSlug is set then (a UFC slug is accepted here too). Keep the two records
+apart: Bellator fights never belong in a UFC answer.
+
+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 (league === 'bellator') {
+            const ufc = asRecord(asRecord(data.profile)?.ufc);
+            data.ufcFighterSlug = typeof ufc?.ufcFighterSlug === 'string' ? ufc.ufcFighterSlug : null;
+        }
+        if (history) {
+            if (history.ok)
+                data.history = extractRows(history.data).slice(0, historyLimit);
+            else
+                partial.push(sectionFailure('history', history, league));
+        }
+        if (stats) {
+            if (stats.ok)
+                data.stats = payload(stats);
+            else
+                partial.push(sectionFailure('stats', stats, league));
+        }
+        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, two BKFC fighters or two Bellator fighters: record and every meeting.
+
+Accepts slugs or names for both sides (names resolve through the league's search). Bellator meetings are only
+the ones on Bellator cards (2014-2017); UFC meetings between the same two are a UFC question (head_to_head).
+
+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").
+Bellator has no rankings (a 2014-2017 archive): league "bellator" returns a non-retryable NOT_IMPLEMENTED.
+Never answer with UFC rankings instead.
+
+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);
+        if (league === 'bellator') {
+            return archiveGap(d, league, `Bellator has no rankings or champions lists: ${ARCHIVES.bellator}, and the API serves its results only.`, [
+                'Do not retry: no Bellator rankings exist on the API',
+                'Title fights: call_api /bellator/bouts with query { "title": "true" }; results: combat_events { league: "bellator", when: "recent" }',
+                'Never substitute UFC rankings for Bellator',
+            ]);
+        }
+        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/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 / Bellator MMA events: upcoming cards or recent results, with date, local time and venue (Bellator: archive, upcoming is empty with a note)',
+        parallelSafe: true,
+        games: ['raf', 'bkfc', 'bellator'],
+        jobs: ['schedule'],
+        exampleArgs: { league: 'bkfc', when: 'upcoming', limit: 5 },
+        preferOver: ['call_api /raf/events, /bkfc/events or /bellator/events'],
+    },
+    {
+        name: 'combat_card',
+        doNotUse: "One bout's period/round breakdown → combat_bout",
+        outcome: 'One RAF/BKFC/Bellator event card in running order with results; event = slug, "next" or "last" (Bellator: "last" = most recent archived card, no "next")',
+        parallelSafe: true,
+        games: ['raf', 'bkfc', 'bellator'],
+        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) / Bellator per-round official stats in UFC format (Pro: the archive is older than the Free/Starter window)',
+        parallelSafe: true,
+        games: ['raf', 'bkfc', 'bellator'],
+        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 or Bellator fighter page: profile + headshot, recent bouts, career stats (Starter); slug or name; Bellator fighters share the UFC slug (ufcFighterSlug)',
+        parallelSafe: true,
+        games: ['raf', 'bkfc', 'bellator'],
+        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, two BKFC fighters or two Bellator fighters',
+        parallelSafe: true,
+        games: ['raf', 'bkfc', 'bellator'],
+        jobs: ['h2h', 'preview'],
+        exampleArgs: { league: 'bkfc', athleteA: 'ryan-petersen', athleteB: 'gregoris-cisneros' },
+    },
+    {
+        name: 'combat_rankings',
+        doNotUse: 'UFC rankings → standings / rankings tools (RAF/BKFC/Bellator never appear in UFC answers); Bellator has no rankings (NOT_IMPLEMENTED)',
+        preferOver: [],
+        outcome: 'RAF champions per division / BKFC official rankings and champions',
+        parallelSafe: true,
+        games: ['raf', 'bkfc', 'bellator'],
+        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'] },
@@ -484,7 +547,14 @@ const GAMES_META = [
     { id: 'cs2', label: 'Counter-Strike 2', depth: 'deep', notes: 'Prefixed ids; live path /cs2/live; trends/rankings' },
     { id: 'dota2', label: 'Dota 2', depth: 'thin', notes: 'Numeric ids; radar; no standings/roster endpoints' },
     { id: 'cod', label: 'Call of Duty (CDL)', depth: 'medium', notes: 'Org slugs; CDL standings; UUID match ids' },
-    { id: 'ufc', label: 'UFC / MMA', depth: 'medium', notes: 'Fighter slugs; boutId; live + rankings' },
+    {
+        id: 'ufc',
+        label: 'UFC / MMA',
+        depth: 'medium',
+        notes: 'Fighter slugs; boutId; live + rankings. Includes Dana White\'s Contender Series and Road to UFC (2022-2026, all 19 cards ' +
+            'with official round stats; event slugs like road-to-ufc-2-7, titles "Road to UFC 2.7"). Bellator is NOT UFC: use the ' +
+            'combat_* tools with league bellator, and never mix its fights into UFC answers.',
+    },
 ];
 export const listCapabilities = {
     name: 'list_capabilities',
@@ -724,6 +794,9 @@ const ALLOWLIST_PREFIXES = [
     '/ufc',
     '/fortnite',
     '/tennis',
+    '/raf',
+    '/bkfc',
+    '/bellator',
     '/openapi.json',
 ];
 function pathAllowed(path) {
@@ -747,7 +820,7 @@ Prefer curated tools for all standard jobs (live, schedule, profiles, standings,
 
 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.
+Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /tennis, /raf, /bkfc, /bellator.
 Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
 
 Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
@@ -808,7 +881,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
                 source: 'call_api',
                 requestId,
                 tookMs: Date.now() - started,
-                hint: 'Use prefixes /health /lol /cs2 /dota2 /cod /ufc /fortnite /tennis',
+                hint: 'Use prefixes /health /lol /cs2 /dota2 /cod /ufc /fortnite /tennis /raf /bkfc /bellator',
             });
         }
         let query = {};
@@ -909,10 +982,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|bellator)$/)) {
             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|bellator`,
                 game: null,
                 source: 'list_routes',
                 requestId,
@@ -935,7 +1008,7 @@ Example: { "game": "ufc", "q": "rankings" }`,
                 httpStatus: res.status,
                 recover: [
                     'Call list_capabilities for curated tools that need no route knowledge',
-                    'call_api accepts /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite',
+                    'call_api accepts /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /tennis, /raf, /bkfc, /bellator',
                 ],
             });
         }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "cito-mcp",
-  "version": "0.4.7",
-  "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).",
+  "version": "0.4.9",
+  "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) — 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.",
+  "//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",
@@ -18,6 +18,7 @@
     "cod",
     "ufc",
     "mma",
+    "bellator",
     "tennis",
     "live-scores",
     "sports-data",