cito-mcp 0.2.1 → 0.2.2

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.2` · **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.2';
 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,42 @@ 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[].
+ */
+function extractLiveRows(data, game) {
+    const root = asRecord(data);
+    const payload = asRecord(root?.data) ?? root;
+    if (!payload)
+        return extractRows(data);
+    if (game === 'ufc') {
+        const liveBouts = Array.isArray(payload.liveBouts) ? payload.liveBouts : [];
+        if (liveBouts.length)
+            return liveBouts;
+        // Some shapes nest tracking under events[].tracking
+        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 +124,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,
@@ -265,19 +314,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 +343,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.2';
 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)) {

package/dist/tools/standings.js

@@ -8,11 +8,40 @@ function normalizeStandingRow(row, index) {
     const r = asRecord(row) ?? {};
     const entity = asRecord(r.team) ?? asRecord(r.fighter) ?? asRecord(r.org) ?? r;
     const name = pickString(asRecord(entity)?.name, r.teamName, r.name, r.orgName, r.fighterName, asRecord(entity)?.slug) ?? `row-${index + 1}`;
+    // UFC official lists: champion has rank=null + rankText="C"; contenders 1..15.
+    // Never fall back to index+1 for null ranks — that produced two "#1" rows (champ + #1).
+    const championStatus = pickString(r.championStatus, asRecord(entity)?.championStatus);
+    const rankText = pickString(r.rankText);
+    const isChampion = championStatus === 'champion' ||
+        rankText === 'C' ||
+        r.isChampion === true ||
+        r.isTitleHolder === true;
+    let rank;
+    if (isChampion) {
+        rank = '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 && rankText) {
+        rank = rankText;
+    }
+    else {
+        rank = index + 1;
+    }
     return {
-        rank: typeof r.rank === 'number' ? r.rank : typeof r.position === 'number' ? r.position : index + 1,
+        rank,
+        rankText: rankText ?? (typeof rank === 'number' || typeof rank === 'string' ? String(rank) : null),
+        championStatus: isChampion ? 'champion' : championStatus === 'interim' ? 'interim' : 'none',
         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 +53,9 @@ 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 } : {}),
         },
     };
 }

package/package.json

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