cito-mcp 0.2.1 → 0.2.3

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.1` · **Node:** `>=20` · **Install:** `npx cito-mcp`
+**Version:** `0.2.3` · **Node:** `>=20` · **Install:** `npx cito-mcp`
 
 Primary games: **lol · cs2 · dota2 · cod · ufc**. Fortnite and long-tail REST stay available via `call_api`.
 
@@ -398,7 +398,7 @@ src/
 
 ## Publish notes
 
-Package: **`cito-mcp@0.2.1`**
+Package: **`cito-mcp@0.2.2`**
 
 | Item | Value |
 | --- | --- |

package/dist/client.js

@@ -137,19 +137,22 @@ export function extractRows(data) {
     if (typeof data !== 'object')
         return [];
     const obj = data;
+    // Order matters: UFC /ufc/live nests real bouts under liveBouts while also
+    // shipping supervisor `events` (no fighter names). Prefer bout-like keys first.
     for (const key of [
         'data',
+        'liveBouts',
+        'bouts',
         'matches',
         'items',
         'results',
         'teams',
         'players',
-        'events',
         'fighters',
         'tournaments',
         'leagues',
         'orgs',
-        'bouts',
+        'events',
         'rankings',
         'standings',
         'rows',

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.1';
+const PACKAGE_VERSION = '0.2.3';
 const API_KEY = process.env.CITO_API_KEY;
 if (!API_KEY) {
     console.error('[cito-mcp] CITO_API_KEY is required.\n' +

package/dist/tools/live.js

@@ -12,6 +12,64 @@ const LIVE_PATHS = {
     cod: '/cod/matches/live',
     ufc: '/ufc/live',
 };
+/**
+ * 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.
+ */
+export function extractLiveRows(data, game) {
+    const root = asRecord(data);
+    const payload = asRecord(root?.data) ?? root;
+    if (!payload)
+        return extractRows(data);
+    if (game === 'ufc') {
+        // 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) {
+            const er = asRecord(ev);
+            const tracking = Array.isArray(er?.tracking) ? er.tracking : [];
+            for (const t of tracking) {
+                const tr = asRecord(t) ?? {};
+                fromTracking.push({
+                    ...tr,
+                    eventSlug: pickString(tr.eventSlug, er?.eventSlug, er?.slug),
+                    eventName: pickString(er?.name, er?.eventName, er?.eventSlug),
+                });
+            }
+        }
+        if (fromTracking.length)
+            return fromTracking;
+        // Last resort: empty live board rather than fake ? vs ? event shells
+        return [];
+    }
+    return extractRows(data);
+}
 export const liveMatches = {
     name: 'live_matches',
     description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
@@ -88,12 +146,25 @@ Example: { "game": "all", "limitPerGame": 10 }`,
                 });
                 continue;
             }
-            // Dota may nest matches at top-level and under data
-            let rows = extractRows(res.data);
+            // Prefer real match/bout rows over supervisor event shells (UFC /ufc/live).
+            let rows = extractLiveRows(res.data, game);
             const obj = asRecord(res.data);
             if (rows.length === 0 && Array.isArray(obj?.matches))
                 rows = obj.matches;
-            const normalized = rows.slice(0, limitPerGame).map((row) => normalizeMatch(game, row, 'live'));
+            const normalized = rows
+                .slice(0, limitPerGame)
+                .map((row) => normalizeMatch(game, row, 'live'))
+                // Drop hollow UFC event-supervisor rows mistaken for bouts (no bout id + no sides).
+                .filter((m) => {
+                if (game !== 'ufc')
+                    return true;
+                if (m.matchId && m.matchId !== 'unknown' && (m.team1?.name || m.team2?.name))
+                    return true;
+                if (m.team1?.name && m.team2?.name)
+                    return true;
+                // Keep if at least a real bout id even when fighters pending
+                return Boolean(m.matchId && m.matchId !== 'unknown' && !String(m.matchId).startsWith('event'));
+            });
             const items = labelsOnly
                 ? normalized.map((m) => ({
                     game: m.game,
@@ -143,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 }`,
@@ -265,19 +337,19 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
         }
         else if (game === 'ufc') {
             path = '/ufc/events/upcoming';
-            query = { limit, page: Math.floor(offset / limit) + 1, includeBouts: true };
-            if (args.hours !== undefined)
-                noteIgnored('hours', 'UFC upcoming events list does not accept hours');
+            // Request more events than limit so client-side hours filter still has a card pool.
+            query = {
+                limit: Math.min(50, Math.max(limit * 3, limit)),
+                page: Math.floor(offset / limit) + 1,
+                includeBouts: true,
+            };
+            // hours / from / to applied client-side after expand (below) — do not warn as ignored.
             if (team)
                 noteIgnored('team', 'UFC uses fighter filters via resolve/event_card, not team on schedule');
             if (league)
                 noteIgnored('league', 'UFC has no league filter on upcoming events');
             if (tournamentId)
                 noteIgnored('tournamentId', 'pass event slug via event_card instead');
-            if (from)
-                noteIgnored('from', 'UFC upcoming does not accept from');
-            if (to)
-                noteIgnored('to', 'UFC upcoming does not accept to');
         }
         const res = await fetchJson(ctx, path, { query });
         if (!res.ok) {
@@ -294,29 +366,69 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
             });
         }
         let rows = extractRows(res.data);
-        // UFC events may need bout expansion
+        // UFC events → expand to bout rows (fighters[] shape) so labels are not "? vs ?"
         if (game === 'ufc') {
             const expanded = [];
             for (const event of rows) {
                 const er = asRecord(event) ?? {};
+                const eventName = pickString(er.name, er.title);
+                const eventId = pickString(er.id, er.slug);
+                const eventSlug = pickString(er.slug);
+                const eventStart = pickString(er.startTime, er.date, er.startsAt);
                 const bouts = extractRows(er.bouts ?? er.fights);
                 if (bouts.length) {
                     for (const bout of bouts) {
                         const br = asRecord(bout) ?? {};
                         expanded.push({
                             ...br,
-                            eventName: pickString(er.name, er.title),
-                            eventId: pickString(er.id, er.slug),
-                            eventSlug: pickString(er.slug),
-                            startTime: pickString(br.startTime, er.startTime, er.date),
+                            eventName,
+                            eventId,
+                            eventSlug,
+                            startTime: pickString(br.startTime, br.date, eventStart),
                         });
                     }
                 }
                 else {
-                    expanded.push(event);
+                    // Keep event shell as a schedule card with a real label (not fighter matchup)
+                    expanded.push({
+                        id: eventId ?? eventSlug,
+                        matchId: eventId ?? eventSlug,
+                        name: eventName,
+                        title: eventName,
+                        label: eventName ?? eventSlug ?? 'UFC event',
+                        startTime: eventStart,
+                        eventName,
+                        eventId,
+                        eventSlug,
+                        status: pickString(er.status) ?? 'upcoming',
+                    });
                 }
             }
             rows = expanded;
+            // Client-side hours / from / to window (API list has no hours param)
+            const now = Date.now();
+            const fromMs = from ? Date.parse(from) : now;
+            const toMs = to
+                ? Date.parse(to)
+                : args.hours !== undefined || !from
+                    ? now + hours * 3600_000
+                    : Number.POSITIVE_INFINITY;
+            if (Number.isFinite(fromMs) && Number.isFinite(toMs)) {
+                const before = rows.length;
+                rows = rows.filter((row) => {
+                    const r = asRecord(row) ?? {};
+                    const ts = pickString(r.startTime, r.date, r.startsAt, r.scheduledAt);
+                    if (!ts)
+                        return true; // keep undated rows rather than drop whole card
+                    const t = Date.parse(ts);
+                    if (!Number.isFinite(t))
+                        return true;
+                    return t >= fromMs && t <= toMs;
+                });
+                if (before > 0 && rows.length === 0) {
+                    warnings.push(`hours/from/to window matched 0 of ${before} UFC rows — widen hours or omit time filters`);
+                }
+            }
         }
         // Client-side team filter when API ignored it
         if (team && (game === 'dota2' || game === 'cs2')) {

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.1';
+const CATALOG_VERSION = '0.2.3';
 const TOOL_CATALOG = [
     {
         name: 'list_capabilities',

package/dist/tools/normalize.js

@@ -19,9 +19,10 @@ function nestedSide(raw) {
             return { name: raw };
         return null;
     }
-    const name = pickString(o.name, o.code, o.shortName, o.nickname, o.displayName);
-    const id = pickString(o.id, o.teamId, o.orgId);
-    const slug = pickString(o.slug, o.orgSlug);
+    const profile = asRecord(o.profile);
+    const name = pickString(o.name, o.fighterName, o.code, o.shortName, o.nickname, o.displayName, profile?.name, profile?.nickname);
+    const id = pickString(o.id, o.teamId, o.orgId, o.fighterId, profile?.id);
+    const slug = pickString(o.slug, o.orgSlug, o.fighterSlug, profile?.slug);
     const scoreRaw = o.score ?? o.mapsWon ?? o.gamesWon;
     const score = typeof scoreRaw === 'number'
         ? scoreRaw
@@ -39,17 +40,56 @@ function scoreNum(v) {
 }
 export function normalizeMatch(game, row, forcedStatus) {
     const r = asRecord(row) ?? {};
-    const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id) ?? 'unknown';
+    const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.fightMetricId) ?? '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) ??
         sideFrom(pickString(r.team2Name, r.team_b_name, r.blueName, r.fighter2Name, r.awayName), pickString(r.team2Id, r.team2_id, r.blueId, r.fighter2Id), pickString(r.team2Slug, r.blueSlug, r.fighter2Slug), scoreNum(r.team2Score ?? r.score2 ?? r.team2Maps ?? r.blueScore));
-    // UFC fighters as corners
-    if (game === 'ufc' && (!team1 || !team2)) {
-        const f1 = nestedSide(r.redCorner ?? r.fighter1 ?? r.fighterA);
-        const f2 = nestedSide(r.blueCorner ?? r.fighter2 ?? r.fighterB);
-        team1 = team1 ?? f1;
-        team2 = team2 ?? f2;
+    // UFC / live corners: red/blue objects, corner arrays, or fighters[] with corner field.
+    // Public API serializeBout uses fighters:[{ corner, fighterName, fighterSlug, profile:{name,slug} }].
+    // Live tracking uses red/blue + fighters[] (not team1/team2).
+    if (game === 'ufc' || (!team1 && !team2 && (r.red || r.blue || Array.isArray(r.fighters)))) {
+        const fromCornerObj = (raw) => {
+            const o = asRecord(raw);
+            if (!o) {
+                if (typeof raw === 'string' && raw.trim())
+                    return { name: raw.trim() };
+                return null;
+            }
+            // Nested profile from serializeBoutFighter
+            const profile = asRecord(o.profile);
+            const fighter = asRecord(o.fighter);
+            const name = pickString(o.name, o.fighterName, o.displayName, o.nickname, profile?.name, profile?.nickname, fighter?.name, fighter?.nickname);
+            const id = pickString(o.id, o.fighterId, profile?.id, fighter?.id);
+            const slug = pickString(o.slug, o.fighterSlug, profile?.slug, fighter?.slug);
+            const score = scoreNum(o.score ?? o.points);
+            return sideFrom(name, id, slug, score);
+        };
+        team1 =
+            team1 ??
+                fromCornerObj(r.red) ??
+                fromCornerObj(r.redCorner) ??
+                fromCornerObj(r.fighter1) ??
+                fromCornerObj(r.fighterA);
+        team2 =
+            team2 ??
+                fromCornerObj(r.blue) ??
+                fromCornerObj(r.blueCorner) ??
+                fromCornerObj(r.fighter2) ??
+                fromCornerObj(r.fighterB);
+        const fightersList = Array.isArray(r.fighters) ? r.fighters : [];
+        if (fightersList.length) {
+            const byCorner = (want) => fightersList.find((f) => {
+                const c = pickString(asRecord(f)?.corner, asRecord(f)?.side)?.toLowerCase();
+                return c === want || c === want[0]; // "red" / "r"
+            });
+            const redF = byCorner('red') ?? byCorner('r') ?? fightersList[0];
+            const blueF = byCorner('blue') ??
+                byCorner('b') ??
+                (fightersList.length > 1 ? fightersList[1] : undefined);
+            team1 = team1 ?? fromCornerObj(redF);
+            team2 = team2 ?? fromCornerObj(blueF);
+        }
     }
     // COD sometimes uses teams[]
     if ((!team1 || !team2) && Array.isArray(r.teams)) {
@@ -75,8 +115,21 @@ export function normalizeMatch(game, row, forcedStatus) {
     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,
@@ -96,6 +149,7 @@ export function entityRef(row, type, game) {
         '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;
+    const nickname = pickString(r.nickname, asRecord(r.profile)?.nickname);
     return {
         game,
         type,
@@ -103,34 +157,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/resolve.js

@@ -8,31 +8,66 @@ 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;
 }
+/** UFC dedicated search (list /fighters ignores `q`). */
+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);
+    }
+    if (type === 'any' || type === 'event' || type === 'tournament') {
+        pushCandidates(candidates, 'ufc', 'event', events, q, limit);
+    }
+    if (type === 'any' || type === 'match') {
+        pushCandidates(candidates, 'ufc', 'match', bouts, q, limit);
+    }
+    candidates.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+    return { candidates: candidates.slice(0, limit), calls: 1, ok: true };
+}
 async function searchGame(ctx, game, q, type, limit) {
     const candidates = [];
     let calls = 0;
@@ -164,24 +199,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 +368,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 +525,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 +604,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 +612,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 +632,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,15 +4,66 @@
 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" (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 ||
+        isInterim;
+    let rank;
+    if (isChampion) {
+        rank = isInterim || rankText === 'IC' ? 'IC' : 'C';
+    }
+    else if (typeof r.rank === 'number') {
+        rank = r.rank;
+    }
+    else if (typeof r.position === 'number') {
+        rank = r.position;
+    }
+    else if (rankText && /^\d+$/.test(rankText)) {
+        rank = Number(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 = null;
+    }
+    const resolvedChampionStatus = isInterim
+        ? 'interim'
+        : isChampion
+            ? 'champion'
+            : championStatus === 'interim'
+                ? 'interim'
+                : 'none';
     return {
-        rank: typeof r.rank === 'number' ? r.rank : typeof r.position === 'number' ? r.position : index + 1,
+        rank,
+        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),
+            slug: pickString(asRecord(entity)?.slug, r.orgSlug, r.teamSlug, r.slug, r.fighterSlug),
             name,
         },
         played: r.played ?? r.gamesPlayed ?? r.matches ?? null,
@@ -24,7 +75,10 @@ function normalizeStandingRow(row, index) {
         streak: r.streak ?? null,
         meta: {
             ...(r.division ? { division: r.division } : {}),
+            ...(r.normalizedDivision ? { normalizedDivision: r.normalizedDivision } : {}),
             ...(r.region ? { region: r.region } : {}),
+            ...(isChampion ? { isChampion: true } : {}),
+            ...(isInterim ? { isInterim: true } : {}),
         },
     };
 }

package/package.json

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