cito-mcp 0.4.7 → 0.4.8

package/README.md

@@ -4,7 +4,7 @@ Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports A
 
 **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`.
 
 ---
 

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/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'] },
@@ -724,6 +787,8 @@ const ALLOWLIST_PREFIXES = [
     '/ufc',
     '/fortnite',
     '/tennis',
+    '/raf',
+    '/bkfc',
     '/openapi.json',
 ];
 function pathAllowed(path) {
@@ -747,7 +812,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.
 Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
 
 Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
@@ -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.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).",
-  "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"
+  }
+}