cito-mcp 0.2.2 → 0.2.4

package/README.md

@@ -2,7 +2,7 @@
 
 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.2.2` · **Node:** `>=20` · **Install:** `npx cito-mcp`
+**Version:** `0.2.4` · **Node:** `>=20` · **Install:** `npx cito-mcp`
 
 Primary games: **lol · cs2 · dota2 · cod · ufc**. Fortnite and long-tail REST stay available via `call_api`.
 
@@ -164,6 +164,16 @@ All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (
 | `cod` | medium | Org slugs; CDL standings; UUID match ids |
 | `ufc` | medium | Fighter slugs; `boutId`; live + rankings |
 
+### UFC projection notes (0.2.4)
+
+Hardened agent-facing UFC shapes (offline-tested):
+
+- **`normalizeMatch`** reads `fighters[]` (`corner` + `fighterName` / `profile.name`), live `red`/`blue`, and `boutId` / `dataId` / bare `id`. Never keeps label `? vs ?` when fighter names exist (including blue-first arrays).
+- **`live_matches`** uses `extractLiveRows`: prefer `liveBouts` (empty array = honest empty board); never promote supervisor `events[]` shells into match rows.
+- **`upcoming_schedule`** expands event → bout rows with fighter labels; applies client-side **`hours` / `from` / `to`** (API has no `hours`); event shells without bouts use the **event name**, not `? vs ?`.
+- **`event_card`** bouts share the same `normalizeMatch` path.
+- **`standings`** maps division champions to rank **`C`** (`rankText: "C"`, interim **`IC`**); contender `#1` stays numeric `1` — no dual numeric `#1`.
+
 Fortnite: **`call_api` only** until promoted into the primary enum.
 
 ### `call_api` allowlist
@@ -398,7 +408,7 @@ src/
 
 ## Publish notes
 
-Package: **`cito-mcp@0.2.2`**
+Package: **`cito-mcp@0.2.4`**
 
 | Item | Value |
 | --- | --- |
@@ -433,7 +443,7 @@ claude mcp add cito -e CITO_API_KEY=cito_… -- npx cito-mcp
 
 ### Semver expectations
 
-- **0.2.0** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
+- **0.2.4** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
 - Further 0.2.x patches may refine envelopes and composite quality without renaming the 15 tools.
 - Promoting Fortnite (or other titles) into the primary `game` enum would be a minor feature bump with catalog/docs updates.
 
@@ -441,7 +451,16 @@ claude mcp add cito -e CITO_API_KEY=cito_… -- npx cito-mcp
 
 ## Changelog (summary)
 
-### 0.2.0
+### 0.2.4
+
+- **UFC projection hardening** (offline-tested):
+  - `normalizeMatch`: `fighters[]` corners + profile, live red/blue, `boutId`/`dataId`; never keep `? vs ?` when names exist
+  - `extractRows` / `extractLiveRows`: prefer `liveBouts` (including empty); never fake match rows from supervisor `events[]`
+  - `upcoming_schedule`: client-side `hours`/`from`/`to`; bout expansion with fighter labels; event shells labeled by event name
+  - `event_card` bouts share the same normalize path
+  - `standings`: champion rank `C` / interim `IC`; no dual numeric `#1` for champ + contender
+
+### 0.2.4
 
 - **Breaking:** replaced OpenAPI mass-generated tools with **15 curated outcome tools**
 - Stable JSON envelope + MCP server instructions

package/dist/client.js

@@ -172,6 +172,42 @@ export function asRecord(value) {
     }
     return null;
 }
+/**
+ * Peel Cito `{ success, data: T }` (and one nested `data`) so tools see the entity,
+ * not the envelope. Arrays and primitives pass through. Critical for UFC bouts/fighters
+ * where fighters[] / name live under data, not the top-level response.
+ */
+export function unwrapPayload(value) {
+    let cur = value;
+    for (let depth = 0; depth < 3; depth += 1) {
+        const rec = asRecord(cur);
+        if (!rec)
+            return cur;
+        // Classic withMeta: { success: true, data: { ...entity } }
+        if ('data' in rec && rec.data != null && typeof rec.data === 'object' && !Array.isArray(rec.data)) {
+            const inner = rec.data;
+            // Prefer entity-shaped inner objects over list wrappers
+            const looksLikeEntity = 'id' in inner ||
+                'slug' in inner ||
+                'name' in inner ||
+                'title' in inner ||
+                'fighters' in inner ||
+                'boutId' in inner ||
+                'matchId' in inner ||
+                'team1' in inner ||
+                'red' in inner ||
+                'blue' in inner ||
+                'record' in inner ||
+                'nickname' in inner;
+            if (looksLikeEntity || rec.success === true) {
+                cur = rec.data;
+                continue;
+            }
+        }
+        break;
+    }
+    return cur;
+}
 export function pickString(...values) {
     for (const v of values) {
         if (typeof v === 'string' && v.length > 0)

package/dist/index.js

@@ -18,7 +18,7 @@ import { errorEnvelope, toMcpResult } from './envelope.js';
 import { SERVER_INSTRUCTIONS } from './instructions.js';
 import { allTools, getTool } from './tools/index.js';
 import { runTool } from './tools/types.js';
-const PACKAGE_VERSION = '0.2.2';
+const PACKAGE_VERSION = '0.2.4';
 const API_KEY = process.env.CITO_API_KEY;
 if (!API_KEY) {
     console.error('[cito-mcp] CITO_API_KEY is required.\n' +

package/dist/tools/insight.js

@@ -1,7 +1,7 @@
 /**
  * match_preview — pre-match briefing composite
  */
-import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
+import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { normalizeMatch } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
@@ -18,11 +18,15 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
         calls += 1;
         rateLimit = res.headers;
         if (res.ok) {
-            const data = asRecord(res.data) ?? {};
+            const data = asRecord(unwrapPayload(res.data)) ?? {};
             entity = {
-                id: pickString(data.id, side),
+                id: pickString(data.id, data.slug, side),
                 slug: pickString(data.slug, side),
-                name: pickString(data.name, side),
+                // Prefer real display name; never leave entity.name as the slug when name exists
+                name: pickString(data.name, data.displayName, data.nickname, side) ?? side,
+                nickname: pickString(data.nickname) ?? null,
+                division: pickString(data.division) ?? null,
+                recordText: pickString(data.recordText, asRecord(data.record)?.text) ?? null,
                 game,
             };
         }
@@ -33,11 +37,33 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
                 httpStatus: res.status,
             }));
         }
+        // Fight-by-fight form (not aggregate stats alone)
+        const fights = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(side)}/fights`, {
+            query: { limit: recentLimit },
+        });
+        calls += 1;
+        rateLimit = { ...rateLimit, ...fights.headers };
+        if (fights.ok) {
+            recentForm = extractRows(unwrapPayload(fights.data) ?? fights.data)
+                .slice(0, recentLimit)
+                .map((row) => {
+                // history rows nest bout
+                const r = asRecord(row) ?? {};
+                const bout = asRecord(r.bout) ?? r;
+                return normalizeMatch('ufc', { ...bout, ...(r.fighterName ? {} : {}) }, 'completed');
+            });
+        }
         const stats = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(side)}/stats`);
         calls += 1;
         rateLimit = { ...rateLimit, ...stats.headers };
-        if (stats.ok)
-            recentForm = [stats.data];
+        if (stats.ok && recentForm.length === 0) {
+            recentForm = []; // keep empty rather than stuffing aggregate as "matches"
+            keyPlayers = [];
+        }
+        if (stats.ok) {
+            // stash aggregate on entity for talking points
+            entity = { ...entity, stats: unwrapPayload(stats.data) };
+        }
         return { entity, roster, recentForm, keyPlayers, calls, partial, rateLimit };
     }
     if (game === 'lol') {
@@ -285,14 +311,19 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
             upstreamCalls += 1;
             rateLimit = res.headers;
             if (res.ok) {
-                const m = normalizeMatch(game, res.data, 'upcoming');
+                const entity = unwrapPayload(res.data);
+                // Do not force "upcoming" — completed bouts (e.g. UFC 300) should keep completed.
+                const m = normalizeMatch(game, entity);
                 context = {
-                    matchId: m.matchId,
+                    matchId: m.matchId !== 'unknown' ? m.matchId : matchId,
                     startTime: m.startTime,
                     event: m.event,
+                    eventName: m.event?.name ?? null,
                     league: m.league,
                     status: m.status,
+                    label: m.label,
                 };
+                // Prefer stable slugs for follow-up fighter fetches
                 if (!teamA)
                     teamA = m.team1?.slug || m.team1?.id || m.team1?.name || '';
                 if (!teamB)
@@ -366,6 +397,27 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                     if (res.ok)
                         rows = extractRows(res.data);
                 }
+                else if (game === 'ufc') {
+                    // Fighter fight history is the H2H source of truth (not global /bouts page 1).
+                    const hist = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(teamA)}/fights`, {
+                        query: { limit: 50 },
+                    });
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...hist.headers };
+                    if (hist.ok) {
+                        rows = extractRows(unwrapPayload(hist.data) ?? hist.data).map((row) => {
+                            const r = asRecord(row) ?? {};
+                            return asRecord(r.bout) ?? row;
+                        });
+                    }
+                    else {
+                        partial.push(partialFromRejection('h2h', {
+                            code: mapHttpToCode(hist.status),
+                            message: `fighter fights HTTP ${hist.status}`,
+                            httpStatus: hist.status,
+                        }));
+                    }
+                }
                 h2h = composeH2H(game, teamA, teamB, rows, 10);
             }
             catch (e) {

package/dist/tools/live.js

@@ -16,17 +16,39 @@ const LIVE_PATHS = {
  * Extract live match/bout rows. UFC /ufc/live returns
  * { liveBouts, events, ... } — events are supervisor shells without fighters.
  * Prefer liveBouts (and nested tracking on events) over plain events[].
+ * Exported for offline UFC projection tests.
  */
-function extractLiveRows(data, game) {
+export function extractLiveRows(data, game) {
     const root = asRecord(data);
     const payload = asRecord(root?.data) ?? root;
     if (!payload)
         return extractRows(data);
     if (game === 'ufc') {
-        const liveBouts = Array.isArray(payload.liveBouts) ? payload.liveBouts : [];
-        if (liveBouts.length)
-            return liveBouts;
-        // Some shapes nest tracking under events[].tracking
+        // Prefer liveBouts when the key is present (including empty [] — honest empty board).
+        if (Array.isArray(payload.liveBouts)) {
+            const liveBouts = payload.liveBouts;
+            if (liveBouts.length)
+                return liveBouts;
+            // Empty liveBouts: still check nested tracking, but never bare events[]
+            const eventsWithEmptyLive = Array.isArray(payload.events)
+                ? payload.events
+                : [];
+            const nested = [];
+            for (const ev of eventsWithEmptyLive) {
+                const er = asRecord(ev);
+                const tracking = Array.isArray(er?.tracking) ? er.tracking : [];
+                for (const t of tracking) {
+                    const tr = asRecord(t) ?? {};
+                    nested.push({
+                        ...tr,
+                        eventSlug: pickString(tr.eventSlug, er?.eventSlug, er?.slug),
+                        eventName: pickString(er?.name, er?.eventName, er?.eventSlug),
+                    });
+                }
+            }
+            return nested; // [] when only supervisor shells
+        }
+        // liveBouts key missing — try nested tracking under events
         const events = Array.isArray(payload.events) ? payload.events : [];
         const fromTracking = [];
         for (const ev of events) {
@@ -192,7 +214,8 @@ Filter support (unsupported params are ignored with meta.warnings — do not ass
 - lol: hours, team (slug), league (slug)
 - cs2: team, from, to (ISO); hours not applied upstream
 - cod: team, tournamentId
-- dota2 / ufc: limit/cursor primarily; team may be client-filtered where data allows
+- dota2: limit/cursor primarily; team may be client-filtered where data allows
+- ufc: hours / from / to applied client-side after bout expansion (API has no hours); event shells labeled by event name; bouts use fighters[] corners
 
 Parallel-safe: yes. Upstream cost: 1–2.
 Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,

package/dist/tools/match.js

@@ -1,7 +1,7 @@
 /**
  * match_summary + match_details
  */
-import { extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
+import { extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { normalizeMatch } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, parseGame, stringSchema, } from './types.js';
@@ -9,8 +9,14 @@ async function getSection(ctx, path, query) {
     return fetchJson(ctx, path, { query });
 }
 function matchCore(game, matchId, raw) {
-    const m = normalizeMatch(game, raw);
-    const r = asRecord(raw) ?? {};
+    const entity = unwrapPayload(raw);
+    const m = normalizeMatch(game, entity);
+    const r = asRecord(entity) ?? {};
+    const s1 = m.team1?.score ?? null;
+    const s2 = m.team2?.score ?? null;
+    const scoreline = m.team1 || m.team2
+        ? `${m.team1?.name ?? '?'} ${s1 ?? '-'} : ${s2 ?? '-'} ${m.team2?.name ?? '?'}`
+        : null;
     return {
         matchId: m.matchId !== 'unknown' ? m.matchId : matchId,
         game,
@@ -18,14 +24,19 @@ function matchCore(game, matchId, raw) {
         startTime: m.startTime,
         endTime: pickString(r.endTime, r.endedAt, r.finishedAt) ?? null,
         bestOf: r.bestOf ?? r.bo ?? null,
+        label: m.label,
+        scoreline,
         score: {
-            team1: m.team1?.score ?? null,
-            team2: m.team2?.score ?? null,
+            team1: s1,
+            team2: s2,
         },
         team1: m.team1,
         team2: m.team2,
         event: m.event,
         league: m.league,
+        method: pickString(r.method, r.resultMethod) ?? null,
+        winner: pickString(r.winnerFighterSlug, r.winnerSlug, r.winner) ?? null,
+        weightClass: pickString(r.weightClass, r.division) ?? null,
         rawStatus: pickString(r.status, r.state) ?? null,
     };
 }

package/dist/tools/meta.js

@@ -4,7 +4,7 @@
 import { extractRows, fetchJson, gameNotIncludedHint, present } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
 import { boolSchema, gameSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
-const CATALOG_VERSION = '0.2.2';
+const CATALOG_VERSION = '0.2.4';
 const TOOL_CATALOG = [
     {
         name: 'list_capabilities',

package/dist/tools/normalize.js

@@ -1,7 +1,7 @@
 /**
  * Cross-game row normalization for live/schedule boards and entity cards.
  */
-import { asRecord, pickString } from '../client.js';
+import { asRecord, pickString, unwrapPayload } from '../client.js';
 function sideFrom(name, id, slug, score) {
     if (!name && !id && !slug)
         return null;
@@ -39,8 +39,9 @@ function scoreNum(v) {
     return null;
 }
 export function normalizeMatch(game, row, forcedStatus) {
-    const r = asRecord(row) ?? {};
-    const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.fightMetricId) ?? 'unknown';
+    // Always peel { success, data } so UFC bout fighters[] / status are visible.
+    const r = asRecord(unwrapPayload(row)) ?? asRecord(row) ?? {};
+    const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.fightMetricId, r.ufcFightId) ?? 'unknown';
     let team1 = nestedSide(r.team1) ??
         sideFrom(pickString(r.team1Name, r.team_a_name, r.redName, r.fighter1Name, r.homeName), pickString(r.team1Id, r.team1_id, r.redId, r.fighter1Id), pickString(r.team1Slug, r.redSlug, r.fighter1Slug), scoreNum(r.team1Score ?? r.score1 ?? r.team1Maps ?? r.redScore));
     let team2 = nestedSide(r.team2) ??
@@ -96,27 +97,73 @@ export function normalizeMatch(game, row, forcedStatus) {
         team1 = team1 ?? nestedSide(r.teams[0]);
         team2 = team2 ?? nestedSide(r.teams[1]);
     }
-    const startTime = pickString(r.startTime, r.scheduledAt, r.startsAt, r.date, r.startDate, r.beginAt) ?? null;
-    const statusRaw = pickString(r.status, r.state, r.matchStatus)?.toLowerCase() ?? '';
+    const startTime = pickString(r.startTime, r.scheduledAt, r.startsAt, r.date, r.startDate, r.beginAt, asRecord(r.event)?.startsAt, asRecord(r.event)?.startTime, asRecord(r.event)?.date) ?? null;
+    const statusRaw = pickString(r.status, r.state, r.matchStatus, r.boutStatus)?.toLowerCase() ?? '';
     let status = forcedStatus ?? 'unknown';
     if (!forcedStatus) {
-        if (/live|running|in_?progress|ongoing|started/.test(statusRaw))
+        const hasResult = Boolean(pickString(r.winnerFighterSlug, r.winnerSlug, r.winner, r.method, r.result)) ||
+            r.resultRound != null ||
+            r.isComplete === true ||
+            r.completed === true;
+        if (/live|running|in_?progress|ongoing|started|watching/.test(statusRaw))
             status = 'live';
-        else if (/upcoming|scheduled|not_started|pending|soon/.test(statusRaw))
-            status = 'upcoming';
-        else if (/complete|finished|ended|final|closed|done/.test(statusRaw))
+        else if (/complete|finished|ended|final|closed|done|official|result/.test(statusRaw) || hasResult) {
             status = 'completed';
-        else if (forcedStatus)
-            status = forcedStatus;
+        }
+        else if (/upcoming|scheduled|not_started|pending|soon|booked|confirmed|announced/.test(statusRaw) ||
+            (game === 'ufc' && !hasResult && (startTime || statusRaw === '' || statusRaw === 'unknown'))) {
+            // UFC bouts often omit status or use sparse values; default upcoming when no result yet.
+            if (hasResult)
+                status = 'completed';
+            else if (startTime) {
+                const t = Date.parse(startTime);
+                status = Number.isFinite(t) && t < Date.now() - 3 * 3600_000 ? 'completed' : 'upcoming';
+            }
+            else {
+                status = 'upcoming';
+            }
+        }
+        else if (hasResult)
+            status = 'completed';
+    }
+    // Winner → score 1-0 for UFC card display when numeric scores absent
+    if (game === 'ufc' && team1 && team2 && team1.score == null && team2.score == null) {
+        const winner = pickString(r.winnerFighterSlug, r.winnerSlug, r.winner)?.toLowerCase();
+        if (winner) {
+            const t1hit = [team1.slug, team1.id, team1.name].some((x) => x && (String(x).toLowerCase() === winner || String(x).toLowerCase().includes(winner) || winner.includes(String(x).toLowerCase())));
+            const t2hit = [team2.slug, team2.id, team2.name].some((x) => x && (String(x).toLowerCase() === winner || String(x).toLowerCase().includes(winner) || winner.includes(String(x).toLowerCase())));
+            if (t1hit && !t2hit) {
+                team1 = { ...team1, score: 1 };
+                team2 = { ...team2, score: 0 };
+            }
+            else if (t2hit && !t1hit) {
+                team1 = { ...team1, score: 0 };
+                team2 = { ...team2, score: 1 };
+            }
+        }
     }
-    const eventName = pickString(asRecord(r.event)?.name, r.eventName, r.event, asRecord(r.tournament)?.name, r.tournamentName);
-    const eventId = pickString(asRecord(r.event)?.id, r.eventId, asRecord(r.tournament)?.id, r.tournamentId);
-    const eventSlug = pickString(asRecord(r.event)?.slug, r.eventSlug, asRecord(r.tournament)?.slug);
+    const ev = asRecord(r.event);
+    const eventName = pickString(ev?.name, ev?.title, r.eventName, typeof r.event === 'string' ? r.event : undefined, asRecord(r.tournament)?.name, asRecord(r.tournament)?.title, r.tournamentName);
+    const eventId = pickString(ev?.id, r.eventId, asRecord(r.tournament)?.id, r.tournamentId);
+    const eventSlug = pickString(ev?.slug, r.eventSlug, asRecord(r.tournament)?.slug);
     const leagueName = pickString(asRecord(r.league)?.name, r.leagueName, r.league, r.leagueSlug);
     const leagueId = pickString(asRecord(r.league)?.id, r.leagueId);
     const leagueSlug = pickString(asRecord(r.league)?.slug, r.leagueSlug);
-    const label = pickString(r.label, r.title, r.name) ??
-        `${team1?.name ?? '?'} vs ${team2?.name ?? '?'}`;
+    // Prefer explicit title/label when present, but never keep the placeholder
+    // "? vs ?" once fighter/team names were resolved (UFC fighters[] / red-blue).
+    const vsLabel = `${team1?.name ?? '?'} vs ${team2?.name ?? '?'}`;
+    const explicit = pickString(r.label, r.title, r.name);
+    const explicitIsPlaceholder = explicit != null && /^\?\s*vs\s*\?$/i.test(explicit.trim());
+    let label;
+    if (explicit && !explicitIsPlaceholder) {
+        label = explicit;
+    }
+    else if (team1?.name || team2?.name) {
+        label = vsLabel;
+    }
+    else {
+        label = explicit ?? vsLabel;
+    }
     return {
         game,
         matchId,
@@ -135,7 +182,9 @@ export function entityRef(row, type, game) {
         pickString(r.slug) ??
         'unknown';
     const slug = pickString(r.slug, r.orgSlug, r.teamSlug);
-    const name = pickString(r.name, r.nickname, r.displayName, r.tag, r.code, r.title, slug, id) ?? id;
+    // Events often use `title` not `name` (UFC)
+    const name = pickString(r.name, r.title, r.nickname, r.displayName, r.tag, r.code, slug, id) ?? id;
+    const nickname = pickString(r.nickname, asRecord(r.profile)?.nickname);
     return {
         game,
         type,
@@ -143,34 +192,61 @@ export function entityRef(row, type, game) {
         ...(slug ? { slug } : {}),
         name,
         meta: {
+            ...(nickname && nickname !== name ? { nickname } : {}),
             ...(r.region ? { region: r.region } : {}),
             ...(r.role ? { role: r.role } : {}),
             ...(r.nationality ? { nationality: r.nationality } : {}),
             ...(r.entity_type ? { entity_type: r.entity_type } : {}),
+            ...(r.division ? { division: r.division } : {}),
+            ...(r.p4pRank != null ? { p4pRank: r.p4pRank } : {}),
+            ...(r.isChampion != null ? { isChampion: r.isChampion } : {}),
         },
     };
 }
-/** Simple fuzzy score: exact > startsWith > includes (case-insensitive). */
-export function rankScore(query, name, id, slug) {
-    const q = query.trim().toLowerCase();
+/**
+ * Fuzzy score for entity resolution: exact > startsWith > includes > token overlap.
+ * Extra args (nickname, alt names) are scored as additional candidates.
+ * Multi-token person names ("jon jones") get a strong boost when every token hits.
+ */
+export function rankScore(query, name, id, slug, ...extra) {
+    const q = query.trim().toLowerCase().replace(/\s+/g, ' ');
     if (!q)
         return 0;
-    const candidates = [name, id, slug].filter(Boolean).map((s) => String(s).toLowerCase());
+    const candidates = [name, id, slug, ...extra]
+        .filter(Boolean)
+        .map((s) => String(s).toLowerCase().replace(/[_-]+/g, ' ').replace(/\s+/g, ' ').trim());
     let best = 0;
+    const qt = q.split(/\s+/).filter(Boolean);
     for (const c of candidates) {
+        if (!c)
+            continue;
         if (c === q)
             best = Math.max(best, 100);
         else if (c.startsWith(q))
-            best = Math.max(best, 80 - Math.min(20, c.length - q.length));
+            best = Math.max(best, 85 - Math.min(15, c.length - q.length));
+        else if (q.startsWith(c) && c.length >= 3)
+            best = Math.max(best, 70);
         else if (c.includes(q))
-            best = Math.max(best, 50 - Math.min(20, c.indexOf(q)));
+            best = Math.max(best, 55 - Math.min(20, c.indexOf(q)));
         else {
-            // token overlap
-            const qt = q.split(/\s+/);
-            const ct = c.split(/[\s_-]+/);
-            const hits = qt.filter((t) => ct.some((x) => x.includes(t) || t.includes(x))).length;
-            if (hits)
-                best = Math.max(best, 20 + hits * 10);
+            const ct = c.split(/[\s]+/).filter(Boolean);
+            // all query tokens present as whole tokens (order-independent)
+            const allTokens = qt.length > 0 &&
+                qt.every((t) => ct.some((x) => x === t || x.startsWith(t) || t.startsWith(x)));
+            if (allTokens && qt.length >= 2) {
+                best = Math.max(best, 92); // "jon jones" vs "Jon Jones"
+            }
+            else {
+                const hits = qt.filter((t) => ct.some((x) => x.includes(t) || t.includes(x))).length;
+                if (hits === qt.length && qt.length > 0)
+                    best = Math.max(best, 75);
+                else if (hits)
+                    best = Math.max(best, 20 + hits * 12);
+            }
+            // last-name only: query last token equals candidate last token
+            if (qt.length >= 2 && ct.length >= 1 && ct[ct.length - 1] === qt[qt.length - 1]) {
+                best = Math.max(best, 60);
+            }
         }
     }
     return best;

package/dist/tools/player.js

@@ -1,7 +1,7 @@
 /**
  * player_profile
  */
-import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
+import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { normalizeMatch } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
@@ -165,12 +165,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     httpStatus: res.status,
                 });
             }
-            playerRaw = res.data;
-            // some APIs wrap in data
-            const obj = asRecord(res.data);
-            if (obj?.data && typeof obj.data === 'object' && !Array.isArray(obj.data)) {
-                playerRaw = obj.data;
-            }
+            playerRaw = unwrapPayload(res.data);
         }
         const player = identityFrom(game, playerRaw, playerId || undefined, slug || undefined);
         let currentTeam = player.team;
@@ -306,13 +301,15 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             })());
         }
         if (game === 'ufc') {
+            const fighterKey = slug || idOrSlug;
             tasks.push((async () => {
-                const res = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(slug || idOrSlug)}/stats`);
+                const res = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/stats`);
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
-                    form = { summary: 'UFC fighter stats', trend: null, window: null, metrics: res.data };
-                    seasonStats = res.data;
+                    const metrics = unwrapPayload(res.data);
+                    form = { summary: 'UFC fighter stats', trend: null, window: null, metrics };
+                    seasonStats = metrics;
                 }
                 else {
                     partial.push(partialFromRejection('form', {
@@ -322,6 +319,53 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     }));
                 }
             })());
+            tasks.push((async () => {
+                // Fight-by-fight history — /fights and /history are aliases on the API
+                const res = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/fights`, {
+                    query: { limit: recentLimit },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    recentMatches = extractRows(res.data)
+                        .slice(0, recentLimit)
+                        .map((row) => {
+                        const r = asRecord(row) ?? {};
+                        const bout = asRecord(r.bout) ?? row;
+                        const m = normalizeMatch('ufc', bout, 'completed');
+                        return {
+                            ...m,
+                            result: pickString(r.result, r.outcome, asRecord(bout)?.result) ?? null,
+                            opponent: pickString(r.opponentName, asRecord(r.opponent)?.name) ?? null,
+                            method: pickString(asRecord(bout)?.method, r.method) ?? null,
+                        };
+                    });
+                }
+                else {
+                    // fallback history path
+                    const hist = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/history`, {
+                        query: { limit: recentLimit },
+                    });
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...hist.headers };
+                    if (hist.ok) {
+                        recentMatches = extractRows(hist.data)
+                            .slice(0, recentLimit)
+                            .map((row) => {
+                            const r = asRecord(row) ?? {};
+                            const bout = asRecord(r.bout) ?? row;
+                            return normalizeMatch('ufc', bout, 'completed');
+                        });
+                    }
+                    else {
+                        partial.push(partialFromRejection('recentMatches', {
+                            code: mapHttpToCode(res.status),
+                            message: `fighter fights HTTP ${res.status}`,
+                            httpStatus: res.status,
+                        }));
+                    }
+                }
+            })());
         }
         await Promise.all(tasks);
         if (view === 'summary' && recentMatches.length > recentLimit) {

package/dist/tools/resolve.js

@@ -8,31 +8,124 @@ import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_
 function pushCandidates(out, game, type, rows, q, limit) {
     for (const row of rows) {
         const ref = entityRef(row, type, game);
-        const score = rankScore(q, ref.name, ref.id, ref.slug);
-        if (q && score <= 0 && type !== 'any') {
-            // still include search API hits even if local rank is weak
-        }
         const r = asRecord(row) ?? {};
+        const nickname = pickString(r.nickname, asRecord(r.profile)?.nickname, ref.meta?.nickname);
+        const score = rankScore(q, ref.name, ref.id, ref.slug, nickname);
+        // Prefer positive fuzzy hits; keep weak API hits at floor 1 so real search results are not wiped.
+        if (q && score <= 0) {
+            // still allow through at floor so dedicated search endpoints aren't empty on odd nicknames
+        }
         const secondary = {};
         for (const key of ['lolPlayerId', 'codPlayerId', 'matchId', 'boutId', 'tournamentId', 'eventId']) {
             const v = pickString(r[key]);
             if (v)
                 secondary[key] = v;
         }
+        if (nickname)
+            secondary.nickname = nickname;
         out.push({
             game,
             type: pickString(r.entity_type, r.type, type) ?? type,
             id: ref.id,
             slug: ref.slug,
             name: ref.name,
-            score: q ? (score || 10) : 10,
+            score: q ? (score > 0 ? score : 1) : 10,
             ...(Object.keys(secondary).length ? { secondaryIds: secondary } : {}),
         });
     }
-    out.sort((a, b) => b.score - a.score);
+    out.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
     if (out.length > limit * 3)
         out.length = limit * 3;
 }
+/** Drop noise tokens so "UFC Fight Night Medic" can match "UFC Fight Night: Medic vs Rodriguez". */
+function ufcSearchQueries(q) {
+    const raw = q.trim();
+    if (!raw)
+        return [];
+    const queries = [raw];
+    const stop = new Set(['ufc', 'fight', 'night', 'event', 'card', 'vs', 'the', 'and', 'mma']);
+    const tokens = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length >= 3 && !stop.has(t));
+    if (tokens.length) {
+        // distinctive tokens alone (e.g. "medic", "rodriguez")
+        for (const t of tokens.slice(0, 4))
+            queries.push(t);
+        // pair of last two distinctive tokens
+        if (tokens.length >= 2)
+            queries.push(tokens.slice(-2).join(' '));
+    }
+    // slug-ish form
+    const slugish = raw.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    if (slugish && slugish !== raw.toLowerCase())
+        queries.push(slugish);
+    return [...new Set(queries.map((s) => s.trim()).filter(Boolean))];
+}
+/** UFC dedicated search (list /fighters ignores `q`). Multi-query for event fuzzy match. */
+async function ufcSearch(ctx, q, type, limit) {
+    const candidates = [];
+    let calls = 0;
+    let lastStatus = 200;
+    let anyOk = false;
+    const wantFighters = type === 'any' || type === 'fighter' || type === 'player';
+    const wantEvents = type === 'any' || type === 'event' || type === 'tournament';
+    const wantMatches = type === 'any' || type === 'match';
+    for (const query of ufcSearchQueries(q)) {
+        const res = await fetchJson(ctx, '/ufc/search', { query: { q: query } });
+        calls += 1;
+        lastStatus = res.status;
+        if (!res.ok)
+            continue;
+        anyOk = true;
+        const data = asRecord(res.data) ?? {};
+        const payload = asRecord(data.data) ?? data;
+        const fighters = Array.isArray(payload.fighters)
+            ? payload.fighters
+            : extractRows(payload.fighters);
+        const events = Array.isArray(payload.events)
+            ? payload.events
+            : extractRows(payload.events);
+        const bouts = Array.isArray(payload.bouts)
+            ? payload.bouts
+            : extractRows(payload.bouts);
+        // Always score against the *original* user query for ranking quality
+        if (wantFighters)
+            pushCandidates(candidates, 'ufc', 'fighter', fighters, q, limit);
+        if (wantEvents)
+            pushCandidates(candidates, 'ufc', 'event', events, q, limit);
+        if (wantMatches)
+            pushCandidates(candidates, 'ufc', 'match', bouts, q, limit);
+    }
+    // Event soft-miss fallback: scan upcoming + recent event lists client-side
+    if (wantEvents && !candidates.some((c) => c.type === 'event' && c.score >= 40)) {
+        for (const path of ['/ufc/events/upcoming', '/ufc/events/recent', '/ufc/events']) {
+            const res = await fetchJson(ctx, path, { query: { limit: 40, page: 1 } });
+            calls += 1;
+            if (!res.ok)
+                continue;
+            anyOk = true;
+            pushCandidates(candidates, 'ufc', 'event', extractRows(res.data), q, limit);
+        }
+    }
+    // Dedupe by type+id
+    const seen = new Set();
+    const deduped = [];
+    for (const c of candidates.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))) {
+        const key = `${c.type}:${c.id}:${c.slug ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(c);
+    }
+    return {
+        candidates: deduped.slice(0, limit),
+        calls,
+        ok: anyOk || deduped.length > 0,
+        status: anyOk ? 200 : lastStatus,
+    };
+}
 async function searchGame(ctx, game, q, type, limit) {
     const candidates = [];
     let calls = 0;
@@ -164,24 +257,45 @@ async function searchGame(ctx, game, q, type, limit) {
             await Promise.all(tasks);
         }
         else if (game === 'ufc') {
-            const tasks = [];
-            if (type === 'any' || type === 'fighter' || type === 'player') {
-                tasks.push((async () => {
-                    const res = await fetchJson(ctx, '/ufc/fighters', { query: { q, limit, page: 1 } });
-                    calls += 1;
-                    if (res.ok)
-                        pushCandidates(candidates, game, 'fighter', extractRows(res.data), q, limit);
-                })());
+            // /ufc/fighters ignores q (returns p4p/champ list). Always use /ufc/search when querying.
+            if (q) {
+                const ufc = await ufcSearch(ctx, q, type, limit);
+                calls += ufc.calls;
+                if (ufc.ok) {
+                    candidates.push(...ufc.candidates);
+                }
+                else {
+                    return {
+                        candidates,
+                        calls,
+                        error: partialFromRejection(`game:${game}`, {
+                            code: mapHttpToCode(ufc.status ?? 0),
+                            message: `ufc search HTTP ${ufc.status ?? 0}`,
+                            httpStatus: ufc.status,
+                        }),
+                    };
+                }
             }
-            if (type === 'any' || type === 'event' || type === 'tournament') {
-                tasks.push((async () => {
-                    const res = await fetchJson(ctx, '/ufc/events', { query: { q, limit, page: 1 } });
-                    calls += 1;
-                    if (res.ok)
-                        pushCandidates(candidates, game, 'event', extractRows(res.data), q, limit);
-                })());
+            else {
+                const tasks = [];
+                if (type === 'any' || type === 'fighter' || type === 'player') {
+                    tasks.push((async () => {
+                        const res = await fetchJson(ctx, '/ufc/fighters', { query: { limit, page: 1 } });
+                        calls += 1;
+                        if (res.ok)
+                            pushCandidates(candidates, game, 'fighter', extractRows(res.data), q, limit);
+                    })());
+                }
+                if (type === 'any' || type === 'event' || type === 'tournament') {
+                    tasks.push((async () => {
+                        const res = await fetchJson(ctx, '/ufc/events', { query: { limit, page: 1 } });
+                        calls += 1;
+                        if (res.ok)
+                            pushCandidates(candidates, game, 'event', extractRows(res.data), q, limit);
+                    })());
+                }
+                await Promise.all(tasks);
             }
-            await Promise.all(tasks);
         }
     }
     catch (e) {
@@ -312,14 +426,17 @@ When to use:
 - Typeahead / pickers
 - "List teams matching…"
 - Exploring entities without committing to one ID
+- UFC fighter lookup by name/nickname (uses /ufc/search + client re-rank)
 
 Prefer over resolve_entity when the user wants a list.
 Prefer resolve_entity when chaining one name into a profile tool.
 
 Do not use when: fetching a known entity profile — use team_profile or player_profile.
 
+UFC: with q set, results are ranked (exact name > multi-token match > nickname). "Jon Jones" should return jon-jones first — never the generic P4P list.
+
 Parallel-safe: yes. Upstream cost: 1–3.
-Example: { "game": "cs2", "q": "vitality", "type": "team", "limit": 20 }`,
+Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -466,11 +583,69 @@ Example: { "game": "cs2", "q": "vitality", "type": "team", "limit": 20 }`,
                 }
             }
             else if (game === 'ufc') {
-                if (type === 'fighter' || type === 'player' || type === 'any') {
-                    await listPath('/ufc/fighters', 'fighter', q ? { q } : {});
+                if (q) {
+                    // Dedicated search ranks name/slug/nickname; /fighters ignores q.
+                    const res = await fetchJson(ctx, '/ufc/search', { query: { q } });
+                    upstreamCalls += 1;
+                    if (!res.ok) {
+                        throw Object.assign(new Error(`HTTP ${res.status}`), {
+                            status: res.status,
+                            data: res.data,
+                            headers: res.headers,
+                        });
+                    }
+                    const data = asRecord(res.data) ?? {};
+                    const payload = asRecord(data.data) ?? data;
+                    const scored = [];
+                    if (type === 'fighter' || type === 'player' || type === 'any') {
+                        const fighters = Array.isArray(payload.fighters)
+                            ? payload.fighters
+                            : extractRows(payload.fighters);
+                        for (const row of fighters) {
+                            const ref = entityRef(row, 'fighter', game);
+                            const r = asRecord(row) ?? {};
+                            const nick = pickString(r.nickname);
+                            const score = rankScore(q, ref.name, ref.id, ref.slug, nick);
+                            if (score > 0)
+                                scored.push({ ref, score });
+                        }
+                    }
+                    if (type === 'event' || type === 'tournament' || type === 'any') {
+                        const events = Array.isArray(payload.events)
+                            ? payload.events
+                            : extractRows(payload.events);
+                        for (const row of events) {
+                            const ref = entityRef(row, 'event', game);
+                            const score = rankScore(q, ref.name, ref.id, ref.slug);
+                            if (score > 0)
+                                scored.push({ ref, score });
+                        }
+                    }
+                    if (type === 'match' || type === 'any') {
+                        const bouts = Array.isArray(payload.bouts)
+                            ? payload.bouts
+                            : extractRows(payload.bouts);
+                        for (const row of bouts) {
+                            const ref = entityRef(row, 'match', game);
+                            const score = rankScore(q, ref.name, ref.id, ref.slug);
+                            if (score > 0)
+                                scored.push({ ref, score });
+                        }
+                    }
+                    scored.sort((a, b) => b.score - a.score || a.ref.name.localeCompare(b.ref.name));
+                    items = scored.map((s) => ({
+                        ...s.ref,
+                        meta: { ...s.ref.meta, score: s.score },
+                    }));
+                    total = items.length;
                 }
-                if (type === 'event' || type === 'tournament' || type === 'any') {
-                    await listPath('/ufc/events', 'event', q ? { q } : {});
+                else {
+                    if (type === 'fighter' || type === 'player' || type === 'any') {
+                        await listPath('/ufc/fighters', 'fighter');
+                    }
+                    if (type === 'event' || type === 'tournament' || type === 'any') {
+                        await listPath('/ufc/events', 'event');
+                    }
                 }
             }
         }
@@ -487,7 +662,7 @@ Example: { "game": "cs2", "q": "vitality", "type": "team", "limit": 20 }`,
                 rateLimit: e.headers,
             });
         }
-        // de-dupe by game+type+id
+        // de-dupe by game+type+id; when q present re-sort by score if available
         const seen = new Set();
         items = items.filter((it) => {
             const key = `${it.game}:${it.type}:${it.id}`;
@@ -495,8 +670,17 @@ Example: { "game": "cs2", "q": "vitality", "type": "team", "limit": 20 }`,
                 return false;
             seen.add(key);
             return true;
-        }).slice(0, limit);
-        const hasMore = items.length >= limit;
+        });
+        if (q) {
+            items.sort((a, b) => {
+                const sa = typeof a.meta?.score === 'number' ? a.meta.score : rankScore(q, a.name, a.id, a.slug, a.meta?.nickname);
+                const sb = typeof b.meta?.score === 'number' ? b.meta.score : rankScore(q, b.name, b.id, b.slug, b.meta?.nickname);
+                return sb - sa || a.name.localeCompare(b.name);
+            });
+        }
+        // pagination over ranked result set
+        const pageItems = items.slice(offset, offset + limit);
+        const hasMore = offset + pageItems.length < items.length || (!q && items.length >= limit);
         return successEnvelope({
             source: 'search_entities',
             game,
@@ -506,12 +690,12 @@ Example: { "game": "cs2", "q": "vitality", "type": "team", "limit": 20 }`,
             pagination: {
                 limit,
                 offset,
-                total,
+                total: total ?? (q ? items.length : null),
                 hasMore,
                 nextCursor: hasMore ? encodeCursor({ offset: offset + limit }) : null,
                 prevCursor: offset > 0 ? encodeCursor({ offset: Math.max(0, offset - limit) }) : null,
             },
-            data: { items },
+            data: { items: pageItems },
         });
     },
 };

package/dist/tools/standings.js

@@ -4,21 +4,24 @@
 import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
 import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
-function normalizeStandingRow(row, index) {
+/** Exported for offline UFC rank mapping tests. */
+export function normalizeStandingRow(row, index) {
     const r = asRecord(row) ?? {};
     const entity = asRecord(r.team) ?? asRecord(r.fighter) ?? asRecord(r.org) ?? r;
     const name = pickString(asRecord(entity)?.name, r.teamName, r.name, r.orgName, r.fighterName, asRecord(entity)?.slug) ?? `row-${index + 1}`;
-    // UFC official lists: champion has rank=null + rankText="C"; contenders 1..15.
-    // Never fall back to index+1 for null ranks — that produced two "#1" rows (champ + #1).
+    // UFC official lists: champion has rank=null + rankText="C" (interim "IC"); contenders 1..15.
+    // Never fall back to index+1 for explicit null ranks — that produced two "#1" rows (champ + #1).
     const championStatus = pickString(r.championStatus, asRecord(entity)?.championStatus);
     const rankText = pickString(r.rankText);
+    const isInterim = championStatus === 'interim' || rankText === 'IC' || r.isInterimChampion === true;
     const isChampion = championStatus === 'champion' ||
         rankText === 'C' ||
         r.isChampion === true ||
-        r.isTitleHolder === true;
+        r.isTitleHolder === true ||
+        isInterim;
     let rank;
     if (isChampion) {
-        rank = 'C';
+        rank = isInterim || rankText === 'IC' ? 'IC' : 'C';
     }
     else if (typeof r.rank === 'number') {
         rank = r.rank;
@@ -29,16 +32,35 @@ function normalizeStandingRow(row, index) {
     else if (rankText && /^\d+$/.test(rankText)) {
         rank = Number(rankText);
     }
-    else if (r.rank === null && rankText) {
+    else if (r.rank === null) {
+        // Explicit null (UFC champ without flags, or unranked) — never invent index+1
+        rank = rankText ?? null;
+    }
+    else if (rankText) {
         rank = rankText;
     }
+    else if (r.rank === undefined && r.position === undefined) {
+        rank = index + 1; // last resort only when rank fields are absent entirely
+    }
     else {
-        rank = index + 1;
+        rank = null;
     }
+    const resolvedChampionStatus = isInterim
+        ? 'interim'
+        : isChampion
+            ? 'champion'
+            : championStatus === 'interim'
+                ? 'interim'
+                : 'none';
     return {
         rank,
-        rankText: rankText ?? (typeof rank === 'number' || typeof rank === 'string' ? String(rank) : null),
-        championStatus: isChampion ? 'champion' : championStatus === 'interim' ? 'interim' : 'none',
+        rankText: rankText ??
+            (rank === 'C' || rank === 'IC'
+                ? String(rank)
+                : typeof rank === 'number' || typeof rank === 'string'
+                    ? String(rank)
+                    : null),
+        championStatus: resolvedChampionStatus,
         teamOrFighter: {
             id: pickString(asRecord(entity)?.id, r.teamId, r.fighterId, r.orgId, r.id),
             slug: pickString(asRecord(entity)?.slug, r.orgSlug, r.teamSlug, r.slug, r.fighterSlug),
@@ -56,6 +78,7 @@ function normalizeStandingRow(row, index) {
             ...(r.normalizedDivision ? { normalizedDivision: r.normalizedDivision } : {}),
             ...(r.region ? { region: r.region } : {}),
             ...(isChampion ? { isChampion: true } : {}),
+            ...(isInterim ? { isInterim: true } : {}),
         },
     };
 }

package/dist/tools/team.js

@@ -627,26 +627,48 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
             rows = extractRows(res.data);
         }
         else if (game === 'ufc') {
-            // try fighter stats + bouts list
-            const [aRes, bRes, boutsRes] = await Promise.all([
+            // Use fighter fight history (not global /bouts page 1, which rarely contains both fighters).
+            const [aRes, bRes, histA, histB] = await Promise.all([
                 fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(sideA)}`),
                 fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(sideB)}`),
-                fetchJson(ctx, '/ufc/bouts', { query: { limit: 50, page: 1 } }),
+                fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(sideA)}/fights`, { query: { limit: 50 } }),
+                fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(sideB)}/fights`, { query: { limit: 50 } }),
             ]);
-            upstreamCalls += 3;
-            rateLimit = { ...aRes.headers, ...bRes.headers, ...boutsRes.headers };
+            upstreamCalls += 4;
+            rateLimit = { ...aRes.headers, ...bRes.headers, ...histA.headers, ...histB.headers };
             if (!aRes.ok || !bRes.ok) {
                 return errorEnvelope({
                     code: 'NOT_FOUND',
-                    message: 'One or both fighters not found',
+                    message: 'One or both fighters not found — pass fighter slugs from resolve_entity',
                     game,
                     source: 'head_to_head',
                     requestId,
                     tookMs: Date.now() - started,
                     upstreamCalls,
+                    recover: [
+                        'resolve_entity { game: "ufc", type: "fighter", q } for each name',
+                        'Retry head_to_head with returned slugs as sideA/sideB',
+                    ],
                 });
             }
-            rows = boutsRes.ok ? extractRows(boutsRes.data) : [];
+            const toBouts = (payload) => extractRows(payload).map((row) => {
+                const r = asRecord(row) ?? {};
+                return asRecord(r.bout) ?? row;
+            });
+            const fromA = histA.ok ? toBouts(histA.data) : [];
+            const fromB = histB.ok ? toBouts(histB.data) : [];
+            // Union by bout id
+            const byId = new Map();
+            for (const bout of [...fromA, ...fromB]) {
+                const m = normalizeMatch('ufc', bout);
+                const key = m.matchId !== 'unknown' ? m.matchId : JSON.stringify(bout).slice(0, 80);
+                if (!byId.has(key))
+                    byId.set(key, bout);
+            }
+            rows = [...byId.values()];
+            if (rows.length === 0) {
+                warnings.push('No fight history rows returned for either fighter; H2H may be empty');
+            }
         }
         const meetings = rows
             .map((row) => normalizeMatch(game, row))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Standalone MCP server for the Cito esports API — 15 curated outcome tools for agents (live, schedule, profiles, standings, previews, event cards).",
   "type": "module",
   "bin": {