cito-mcp 0.4.8 → 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**, plus **RAF wrestling** and **BKFC bare knuckle** through the `combat_*` tools. 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

@@ -18,6 +18,8 @@ game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | t
 - 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

@@ -1,17 +1,22 @@
 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'];
+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 PEOPLE = { raf: 'athletes', bkfc: 'fighters' };
-const HISTORY = { raf: 'bouts', bkfc: 'fights' };
+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) or "bkfc" (Bare Knuckle Fighting Championship). Example: "bkfc".',
+    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() : '';
@@ -20,17 +25,25 @@ function parseLeague(value) {
 function leagueError(d, value) {
     return errorEnvelope({
         code: 'VALIDATION',
-        message: `league must be raf or bkfc (got ${JSON.stringify(value ?? null)})`,
+        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,
@@ -45,16 +58,41 @@ function payload(res) {
     const body = asRecord(res.data);
     return body && 'data' in body ? body.data : res.data;
 }
-function sectionFailure(section, res) {
+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) });
-    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})`,
+    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) {
@@ -116,15 +154,17 @@ function begin(source) {
 }
 export const combatEvents = {
     name: 'combat_events',
-    description: `RAF wrestling or BKFC bare-knuckle events: upcoming cards or recent results.
+    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", schedule pages
+- "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 or /bkfc/events.
+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.
@@ -139,7 +179,8 @@ Example: { "league": "bkfc", "when": "upcoming", "limit": 5 }`,
                 type: 'string',
                 enum: ['upcoming', 'recent'],
                 default: 'upcoming',
-                description: 'upcoming = scheduled cards, soonest first; recent = completed cards, newest first. Example: "recent".',
+                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).' }),
         },
@@ -149,14 +190,28 @@ Example: { "league": "bkfc", "when": "upcoming", "limit": 5 }`,
         const league = parseLeague(args.league);
         if (!league)
             return leagueError(d, args.league);
-        const when = args.when === 'recent' ? 'recent' : 'upcoming';
+        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 },
+            data: { league, leagueName: LEAGUE_NAMES[league], when, count: events.length, events, ...upstreamNotes(res) },
             game: league,
             source: d.source,
             requestId: d.requestId,
@@ -168,15 +223,18 @@ Example: { "league": "bkfc", "when": "upcoming", "limit": 5 }`,
 };
 export const combatCard = {
     name: 'combat_card',
-    description: `COMPOSITE fight card for one RAF or BKFC event: event identity + bouts in running order with results.
+    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", "who won the main event at the last BKFC?"
+- "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") 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).
+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).
@@ -189,7 +247,7 @@ Example: { "league": "raf", "event": "last" }`,
         required: ['league'],
         properties: {
             league: leagueSchema,
-            event: stringSchema('Event slug, or "next" / "last" (default "next"). Example: "raf13".', 'next'),
+            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).' }),
         },
     },
@@ -199,8 +257,14 @@ Example: { "league": "raf", "event": "last" }`,
         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';
+        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 } });
@@ -209,20 +273,24 @@ Example: { "league": "raf", "event": "last" }`,
                 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: `No ${which} ${league.toUpperCase()} event`,
+                    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)}`),
+            fetchJson(ctx, `/${league}/events/${encodeURIComponent(slug)}`, league === 'bellator' ? { query: { includeBouts: 'false' } } : undefined),
             fetchJson(ctx, `/${league}/events/${encodeURIComponent(slug)}/bouts`),
         ]);
         calls += 2;
@@ -235,10 +303,10 @@ Example: { "league": "raf", "event": "last" }`,
             rows = Array.isArray(p) ? p : extractRows(asRecord(p)?.bouts ?? p);
         }
         else {
-            partial.push(sectionFailure('bouts', bouts));
+            partial.push(sectionFailure('bouts', bouts, league));
         }
         const eventData = asRecord(payload(ev)) ?? {};
-        const { bouts: _ignored, ...event } = eventData;
+        const { bouts: _ignored, card: _card, ...event } = eventData;
         return successEnvelope({
             data: { league, event, boutCount: rows.length, bouts: rows.slice(0, limit) },
             game: league,
@@ -256,13 +324,18 @@ Example: { "league": "raf", "event": "last" }`,
 };
 export const combatBout = {
     name: 'combat_bout',
-    description: `One RAF or BKFC bout in full, with its scoring breakdown.
+    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").
+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" }`,
@@ -272,8 +345,8 @@ Example: { "league": "bkfc", "boutId": "bkfc-fight-night-bethlehem--gregoris-cis
         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),
+            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) => {
@@ -301,11 +374,13 @@ Example: { "league": "bkfc", "boutId": "bkfc-fight-night-bethlehem--gregoris-cis
             if (parts.ok)
                 data[sub] = asRecord(payload(parts))?.[sub] ?? payload(parts);
             else
-                partial.push(sectionFailure(sub, parts));
+                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,
@@ -320,15 +395,19 @@ Example: { "league": "bkfc", "boutId": "bkfc-fight-night-bethlehem--gregoris-cis
 };
 export const combatAthlete = {
     name: 'combat_athlete',
-    description: `COMPOSITE RAF athlete / BKFC fighter page: profile + recent bouts + career stats.
+    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", athlete/fighter profile pages
+- "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.
 
@@ -370,17 +449,21 @@ Example: { "league": "raf", "athlete": "Kyle Snyder", "historyLimit": 5 }`,
             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));
+                partial.push(sectionFailure('history', history, league));
         }
         if (stats) {
             if (stats.ok)
                 data.stats = payload(stats);
             else
-                partial.push(sectionFailure('stats', stats));
+                partial.push(sectionFailure('stats', stats, league));
         }
         return successEnvelope({
             data,
@@ -396,9 +479,10 @@ Example: { "league": "raf", "athlete": "Kyle Snyder", "historyLimit": 5 }`,
 };
 export const combatH2h = {
     name: 'combat_h2h',
-    description: `Head-to-head between two RAF athletes or two BKFC fighters: record and every meeting.
+    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).
+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" }`,
@@ -453,6 +537,8 @@ export const combatRankings = {
 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" }`,
@@ -470,6 +556,13 @@ Example: { "league": "bkfc", "division": "heavyweight" }`,
         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'

package/dist/tools/meta.js

@@ -6,19 +6,19 @@ 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',
+        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'],
+        games: ['raf', 'bkfc', 'bellator'],
         jobs: ['schedule'],
         exampleArgs: { league: 'bkfc', when: 'upcoming', limit: 5 },
-        preferOver: ['call_api /raf/events or /bkfc/events'],
+        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 event card in running order with results; event = slug, "next" or "last"',
+        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'],
+        games: ['raf', 'bkfc', 'bellator'],
         jobs: ['event_card', 'schedule', 'media'],
         exampleArgs: { league: 'raf', event: 'last' },
         preferOver: ['combat_events + call_api per bout'],
@@ -27,9 +27,9 @@ const COMBAT_CATALOG = [
         name: 'combat_bout',
         doNotUse: 'Whole card → combat_card',
         preferOver: [],
-        outcome: 'One bout in full: RAF per-period scores / BKFC per-round punch stats (Starter)',
+        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'],
+        games: ['raf', 'bkfc', 'bellator'],
         jobs: ['match_page'],
         exampleArgs: { league: 'raf', boutId: 'raf13--belal-muhammad--colby-covington' },
     },
@@ -37,9 +37,9 @@ const COMBAT_CATALOG = [
         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',
+        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'],
+        games: ['raf', 'bkfc', 'bellator'],
         jobs: ['player_form', 'media'],
         exampleArgs: { league: 'raf', athlete: 'Kyle Snyder', historyLimit: 5 },
     },
@@ -47,19 +47,19 @@ const COMBAT_CATALOG = [
         name: 'combat_h2h',
         doNotUse: "One athlete's whole history → combat_athlete",
         preferOver: [],
-        outcome: 'Head-to-head between two RAF athletes or two BKFC fighters',
+        outcome: 'Head-to-head between two RAF athletes, two BKFC fighters or two Bellator fighters',
         parallelSafe: true,
-        games: ['raf', 'bkfc'],
+        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 never appear in UFC answers)',
+        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'],
+        games: ['raf', 'bkfc', 'bellator'],
         jobs: ['standings'],
         exampleArgs: { league: 'bkfc', division: 'heavyweight' },
     },
@@ -547,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',
@@ -789,6 +796,7 @@ const ALLOWLIST_PREFIXES = [
     '/tennis',
     '/raf',
     '/bkfc',
+    '/bellator',
     '/openapi.json',
 ];
 function pathAllowed(path) {
@@ -812,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, /raf, /bkfc.
+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.
@@ -873,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 = {};
@@ -974,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|raf|bkfc)$/)) {
+        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|raf|bkfc`,
+                message: `unsupported game "${gameRaw}"; use lol|cs2|dota2|cod|ufc|fortnite|tennis|raf|bkfc|bellator`,
                 game: null,
                 source: 'list_routes',
                 requestId,
@@ -1000,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,51 +1,52 @@
-{
-  "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"
-  }
-}
+{
+  "name": "cito-mcp",
+  "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) \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",
+    "bellator",
+    "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"
+  }
+}