cito-mcp 0.2.3 → 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.3` · **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.3';
+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/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.3';
+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,22 +97,55 @@ 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);
@@ -148,7 +182,8 @@ 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,

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

@@ -37,36 +37,94 @@ function pushCandidates(out, game, type, rows, q, limit) {
     if (out.length > limit * 3)
         out.length = limit * 3;
 }
-/** UFC dedicated search (list /fighters ignores `q`). */
+/** 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 = [];
-    const res = await fetchJson(ctx, '/ufc/search', { query: { q } });
-    if (!res.ok) {
-        return { candidates, calls: 1, ok: false, status: res.status };
-    }
-    const data = asRecord(res.data) ?? {};
-    // withMeta nests under data; extractRows may return fighters only — read buckets explicitly
-    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);
-    if (type === 'any' || type === 'fighter' || type === 'player') {
-        pushCandidates(candidates, 'ufc', 'fighter', fighters, q, limit);
+    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);
     }
-    if (type === 'any' || type === 'event' || type === 'tournament') {
-        pushCandidates(candidates, 'ufc', 'event', events, 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);
+        }
     }
-    if (type === 'any' || type === 'match') {
-        pushCandidates(candidates, 'ufc', 'match', bouts, 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);
     }
-    candidates.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
-    return { candidates: candidates.slice(0, limit), calls: 1, ok: true };
+    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 = [];

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.3",
+  "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": {