cito-mcp 0.2.3 → 0.2.5

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 = [];
@@ -86,7 +144,9 @@ async function searchGame(ctx, game, q, type, limit) {
                     }),
                 };
             }
-            const data = asRecord(res.data) ?? {};
+            // Unwrap the { success, data, meta } envelope before reading buckets.
+            const envelope = asRecord(res.data) ?? {};
+            const data = asRecord(envelope.data) ?? envelope;
             const buckets = [
                 ['team', data.teams],
                 ['player', data.players],
@@ -101,7 +161,15 @@ async function searchGame(ctx, game, q, type, limit) {
                 pushCandidates(candidates, game, t, rows, q, limit);
             }
             if (candidates.length === 0) {
-                pushCandidates(candidates, game, type === 'any' ? 'unknown' : type, extractRows(res.data), q, limit);
+                const fallbackType = type === 'any' ? 'unknown' : type;
+                let rows = extractRows(data);
+                // extractRows prefers the `matches` bucket; never mislabel those rows as a non-match type.
+                if (fallbackType !== 'match' && fallbackType !== 'unknown') {
+                    const matchRows = extractRows(data.matches);
+                    if (matchRows.length && rows[0] === matchRows[0])
+                        rows = [];
+                }
+                pushCandidates(candidates, game, fallbackType, rows, q, limit);
             }
         }
         else if (game === 'dota2') {
@@ -118,7 +186,9 @@ async function searchGame(ctx, game, q, type, limit) {
                     }),
                 };
             }
-            const data = asRecord(res.data) ?? {};
+            // Unwrap the { success, data, meta } envelope before reading buckets.
+            const envelope = asRecord(res.data) ?? {};
+            const data = asRecord(envelope.data) ?? envelope;
             for (const [t, key] of [
                 ['team', 'teams'],
                 ['player', 'players'],
@@ -130,7 +200,15 @@ async function searchGame(ctx, game, q, type, limit) {
                 pushCandidates(candidates, game, t, extractRows(data[key] ?? data), q, limit);
             }
             if (candidates.length === 0) {
-                pushCandidates(candidates, game, type === 'any' ? 'unknown' : type, extractRows(res.data), q, limit);
+                const fallbackType = type === 'any' ? 'unknown' : type;
+                let rows = extractRows(data);
+                // extractRows prefers the `matches` bucket; never mislabel those rows as a non-match type.
+                if (fallbackType !== 'match' && fallbackType !== 'unknown') {
+                    const matchRows = extractRows(data.matches);
+                    if (matchRows.length && rows[0] === matchRows[0])
+                        rows = [];
+                }
+                pushCandidates(candidates, game, fallbackType, rows, q, limit);
             }
         }
         else if (game === 'cod') {
@@ -255,20 +333,20 @@ async function searchGame(ctx, game, q, type, limit) {
 }
 export const resolveEntity = {
     name: 'resolve_entity',
-    description: `Natural-language / fuzzy query → best typed entity ID(s) + game (player, team, event, tournament, match, fighter).
-
-When to use:
-- User named an entity without an ID ("T1", "s1mple", "IEM Cologne", "Islam Makhachev")
-- Need a canonical id/slug before profile or match tools
-
-Prefer over search_entities when you want one best match (or small ranked set) to chain.
-Prefer search_entities when browsing many results with pagination.
-
-Do not use when: you already have a stable id/slug from a prior tool.
-
-Empty/ambiguous results still return ok:true with best=null or needsDisambiguation=true — pick from candidates or refine q/game/type. Does not emit AMBIGUOUS_ENTITY as a hard error.
-
-Parallel-safe: yes. Upstream cost: 1–5.
+    description: `Natural-language / fuzzy query → best typed entity ID(s) + game (player, team, event, tournament, match, fighter).
+
+When to use:
+- User named an entity without an ID ("T1", "s1mple", "IEM Cologne", "Islam Makhachev")
+- Need a canonical id/slug before profile or match tools
+
+Prefer over search_entities when you want one best match (or small ranked set) to chain.
+Prefer search_entities when browsing many results with pagination.
+
+Do not use when: you already have a stable id/slug from a prior tool.
+
+Empty/ambiguous results still return ok:true with best=null or needsDisambiguation=true — pick from candidates or refine q/game/type. Does not emit AMBIGUOUS_ENTITY as a hard error.
+
+Parallel-safe: yes. Upstream cost: 1–5.
 Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -362,22 +440,22 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
 };
 export const searchEntities = {
     name: 'search_entities',
-    description: `Browse/search teams, players, tournaments, events, fighters with type filter and pagination.
-
-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.
+    description: `Browse/search teams, players, tournaments, events, fighters with type filter and pagination.
+
+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": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -462,7 +540,9 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                     const res = await fetchJson(ctx, '/cs2/search', { query: { q, limit } });
                     upstreamCalls += 1;
                     if (res.ok) {
-                        const data = asRecord(res.data) ?? {};
+                        // Unwrap the { success, data, meta } envelope before reading buckets.
+                        const envelope = asRecord(res.data) ?? {};
+                        const data = asRecord(envelope.data) ?? envelope;
                         if (type === 'any' || type === 'team') {
                             items.push(...extractRows(data.teams).map((r) => entityRef(r, 'team', game)));
                         }
@@ -477,8 +557,15 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                 else {
                     if (type === 'team' || type === 'any')
                         await listPath('/cs2/teams', 'team');
-                    if (type === 'player' || type === 'any')
-                        await listPath('/cs2/players', 'player');
+                    if (type === 'player' || type === 'any') {
+                        if (q) {
+                            // /cs2/players list filters ignore q/search — use the dedicated search endpoint.
+                            await listPath('/cs2/players/search', 'player');
+                        }
+                        else {
+                            await listPath('/cs2/players', 'player');
+                        }
+                    }
                     if (type === 'event' || type === 'tournament' || type === 'any')
                         await listPath('/cs2/events', 'event');
                 }

package/dist/tools/standings.js

@@ -321,6 +321,32 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             rows = nested.map((row, i) => normalizeStandingRow(row, i)).slice(0, limit);
         }
         const obj = asRecord(res.data);
+        const upstreamMeta = asRecord(obj?.meta) ?? {};
+        const dataQuality = asRecord(upstreamMeta.dataQuality) ?? {};
+        const warnings = [];
+        const pushWarning = (value) => {
+            if (typeof value !== 'string')
+                return;
+            const trimmed = value.trim();
+            if (trimmed && !warnings.includes(trimmed))
+                warnings.push(trimmed);
+        };
+        pushWarning(upstreamMeta.warning);
+        pushWarning(dataQuality.warning);
+        if (Array.isArray(upstreamMeta.warnings)) {
+            for (const w of upstreamMeta.warnings)
+                pushWarning(w);
+        }
+        const dataFreshness = pickString(upstreamMeta.dataFreshness, upstreamMeta.freshnessStatus, dataQuality.dataFreshness);
+        const status = pickString(upstreamMeta.status, dataQuality.status);
+        if (status === 'fallback') {
+            pushWarning('Standings served from last-known-good rankings (fallback).');
+        }
+        if (dataFreshness === 'cached' || upstreamMeta.stale === true) {
+            pushWarning(typeof upstreamMeta.dataAgeHours === 'number'
+                ? `Rankings dataFreshness=cached (ageHours=${upstreamMeta.dataAgeHours}).`
+                : 'Rankings dataFreshness=cached or stale.');
+        }
         return successEnvelope({
             source: 'standings',
             game,
@@ -328,13 +354,20 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             tookMs: Date.now() - started,
             upstreamCalls: 1,
             rateLimit: res.headers,
+            warnings: warnings.length ? warnings : undefined,
             data: {
                 scope: effectiveScope,
                 title,
                 season: season ?? null,
                 stage: stage ?? null,
                 rows,
-                updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated) ?? null,
+                updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
+                    null,
+                ...(dataFreshness ? { dataFreshness } : {}),
+                ...(status ? { status } : {}),
+                ...(upstreamMeta.warning || dataQuality.warning
+                    ? { warning: pickString(upstreamMeta.warning, dataQuality.warning) }
+                    : {}),
             },
         });
     },

package/dist/tools/team.js

@@ -21,18 +21,18 @@ function teamIdentity(game, raw, idHint, slugHint) {
 }
 export const teamProfile = {
     name: 'team_profile',
-    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
-
-When to use:
-- Team page / "who is on this roster?"
-- Builder team screen sample
-
-Prefer over: separate roster + matches + detail via call_api.
-
-Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
-Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
-
-Parallel-safe: yes. Upstream cost: 2–4.
+    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
+
+When to use:
+- Team page / "who is on this roster?"
+- Builder team screen sample
+
+Prefer over: separate roster + matches + detail via call_api.
+
+Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
+Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
+
+Parallel-safe: yes. Upstream cost: 2–4.
 Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -123,7 +123,12 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
             teamRaw = res.data;
         }
         else if (game === 'cs2') {
-            const res = await fetchJson(ctx, '/cs2/teams', { query: { search: idOrSlug, limit: 5 } });
+            // A cs2-team-<n> / hltv-team-<n> id resolves 1:1 — fetch it directly instead of
+            // name-searching, which could silently fall back to rows[0] of an unrelated search.
+            const directId = /^(cs2|hltv)-team-\d+$/i.test(idOrSlug);
+            const res = directId
+                ? await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(idOrSlug)}`)
+                : await fetchJson(ctx, '/cs2/teams', { query: { search: idOrSlug, limit: 5 } });
             upstreamCalls += 1;
             rateLimit = res.headers;
             if (!res.ok) {
@@ -143,7 +148,10 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
                     ],
                 });
             }
-            {
+            if (directId) {
+                teamRaw = res.data;
+            }
+            else {
                 const rows = extractRows(res.data);
                 teamRaw =
                     rows.find((row) => {
@@ -285,20 +293,20 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
         if (game === 'cs2') {
             const tid = team.id !== 'unknown' ? team.id : idOrSlug;
             tasks.push((async () => {
-                const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(tid)}/roster-history`);
+                const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(tid)}/roster`);
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     roster = {
                         items: extractRows(res.data).slice(0, 20),
                         asOf: new Date().toISOString(),
-                        quality: 'history',
+                        quality: 'current',
                     };
                 }
                 else {
                     partial.push(partialFromRejection('roster', {
                         code: mapHttpToCode(res.status),
-                        message: `roster-history HTTP ${res.status}`,
+                        message: `roster HTTP ${res.status}`,
                         httpStatus: res.status,
                     }));
                 }
@@ -478,19 +486,19 @@ function winnerSide(match, a) {
 }
 export const headToHead = {
     name: 'head_to_head',
-    description: `Composed head-to-head record between two teams (or two UFC fighters). No first-class REST H2H exists — this tool filters match history server-side.
-
-When to use:
-- Rivalry / series record questions
-- Supporting context for previews
-
-Prefer over: agent-side double match-list filtering.
-
-Do not use when: single-side form only → team_profile or player_profile.
-
-Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
-
-Parallel-safe: yes. Upstream cost: 2–4.
+    description: `Composed head-to-head record between two teams (or two UFC fighters). No first-class REST H2H exists — this tool filters match history server-side.
+
+When to use:
+- Rivalry / series record questions
+- Supporting context for previews
+
+Prefer over: agent-side double match-list filtering.
+
+Do not use when: single-side form only → team_profile or player_profile.
+
+Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
+
+Parallel-safe: yes. Upstream cost: 2–4.
 Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
     inputSchema: {
         type: 'object',
@@ -547,24 +555,80 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
         let upstreamCalls = 0;
         let rateLimit = {};
         let rows = [];
+        // Names used for client-side side matching; replaced with resolved team names
+        // when the id-based REST H2H succeeds (short inputs like "navi" never substring-match "Natus Vincere").
+        let matchA = sideA;
+        let matchB = sideB;
         if (game === 'cs2') {
-            const res = await fetchJson(ctx, '/cs2/matches', { query: { team: sideA, limit: 50 } });
-            upstreamCalls += 1;
-            rateLimit = res.headers;
-            if (!res.ok) {
-                return errorEnvelope({
-                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
-                    message: `H2H match fetch failed (HTTP ${res.status})`,
-                    game,
-                    source: 'head_to_head',
-                    requestId,
-                    tookMs: Date.now() - started,
-                    upstreamCalls,
-                    httpStatus: res.status,
-                    rateLimit: res.headers,
+            // Prefer the purpose-built id-based H2H endpoint; /cs2/matches?team= name-substring
+            // filtering misses short names ("navi" vs stored "Natus Vincere").
+            const resolveCs2Side = async (side) => {
+                const res = await fetchJson(ctx, '/cs2/teams', { query: { search: side, limit: 5 } });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (!res.ok)
+                    return null;
+                const found = extractRows(res.data);
+                const hit = found.find((row) => {
+                    const r = asRecord(row) ?? {};
+                    return [r.id, r.slug, r.name].map((x) => String(x ?? '').toLowerCase()).includes(side.toLowerCase());
+                }) ?? found[0];
+                const r = asRecord(hit);
+                const id = pickString(r?.id, r?.teamId);
+                return id ? { id, name: pickString(r?.name) ?? side } : null;
+            };
+            const [cs2SideA, cs2SideB] = await Promise.all([resolveCs2Side(sideA), resolveCs2Side(sideB)]);
+            let restH2hOk = false;
+            if (cs2SideA && cs2SideB) {
+                const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(cs2SideA.id)}/vs/${encodeURIComponent(cs2SideB.id)}`, {
+                    query: { limit: 50 },
                 });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    // Rows are side-A-perspective summaries (summarizeMatchForTeam); reshape into
+                    // flat match rows so the shared normalize/score pipeline applies unchanged.
+                    rows = extractRows(res.data).map((row) => {
+                        const r = asRecord(row) ?? {};
+                        return {
+                            matchId: r.match_id,
+                            status: r.status,
+                            startsAt: r.starts_at,
+                            eventName: r.event_name,
+                            bestOf: r.best_of,
+                            team1Name: cs2SideA.name,
+                            team1Score: r.team_score,
+                            team2Name: pickString(r.opponent_name) ?? cs2SideB.name,
+                            team2Score: r.opponent_score,
+                        };
+                    });
+                    matchA = cs2SideA.name;
+                    matchB = cs2SideB.name;
+                    restH2hOk = true;
+                }
+                else {
+                    warnings.push(`REST H2H HTTP ${res.status}; fell back to match-history name filtering`);
+                }
+            }
+            if (!restH2hOk) {
+                const res = await fetchJson(ctx, '/cs2/matches', { query: { team: sideA, limit: 50 } });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (!res.ok) {
+                    return errorEnvelope({
+                        code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                        message: `H2H match fetch failed (HTTP ${res.status})`,
+                        game,
+                        source: 'head_to_head',
+                        requestId,
+                        tookMs: Date.now() - started,
+                        upstreamCalls,
+                        httpStatus: res.status,
+                        rateLimit: res.headers,
+                    });
+                }
+                rows = extractRows(res.data);
             }
-            rows = extractRows(res.data);
         }
         else if (game === 'cod') {
             const res = await fetchJson(ctx, '/cod/matches', { query: { team: sideA, limit: 50 } });
@@ -627,30 +691,52 @@ 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))
-            .filter((m) => sidesMatch(m, sideA, sideB))
+            .filter((m) => sidesMatch(m, matchA, matchB))
             .filter((m) => {
             if (!fromIso && !toIso)
                 return true;
@@ -670,7 +756,7 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
         let winsB = 0;
         let draws = 0;
         for (const m of meetings) {
-            const w = winnerSide(m, sideA);
+            const w = winnerSide(m, matchA);
             if (w === 'A')
                 winsA += 1;
             else if (w === 'B')

package/dist/version.js

@@ -0,0 +1,29 @@
+import { createRequire } from 'node:module';
+/**
+ * Single source of truth for the server version.
+ *
+ * This used to be hardcoded in three places — package.json, PACKAGE_VERSION in
+ * index.ts, and CATALOG_VERSION in tools/meta.ts — which had already drifted:
+ * a test asserted 0.2.4 while the package shipped 0.2.5. Agents read the version
+ * out of list_capabilities, so a stale value there is a support problem, not a
+ * cosmetic one. Read it from the manifest instead, so `npm version` is the only
+ * edit a release needs.
+ *
+ * createRequire rather than a JSON import: import assertions are still awkward
+ * across the Node versions this package supports (>=20), and this resolves the
+ * same from src/ under tsx and from dist/ once built, because package.json is
+ * always published alongside dist.
+ */
+const require = createRequire(import.meta.url);
+function readVersion() {
+    try {
+        const pkg = require('../package.json');
+        return typeof pkg.version === 'string' && pkg.version ? pkg.version : '0.0.0';
+    }
+    catch {
+        // Never let a packaging quirk crash the server on boot; a wrong-but-present
+        // version is far better than a failed start.
+        return '0.0.0';
+    }
+}
+export const PACKAGE_VERSION = readVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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": {