cito-mcp 0.2.4 → 0.2.6

package/README.md

@@ -12,7 +12,7 @@ Primary games: **lol · cs2 · dota2 · cod · ufc**. Fortnite and long-tail RES
 
 v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among thin path wrappers, invent IDs, and stitch multi-call UI screens themselves. That catalog was hard to select against and brittle across games.
 
-**v0.2 ships 15 hand-authored tools** that answer *jobs* instead of mirroring REST:
+**v0.2 ships 16 hand-authored tools** that answer *jobs* instead of mirroring REST:
 
 | Job | Tool |
 | --- | --- |
@@ -26,6 +26,8 @@ v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among t
 | Pre-match briefing | `match_preview` |
 | Event / fight-night card | `event_card` |
 | Rivalry record | `head_to_head` |
+| Fighter / team photos | `event_card` · `player_profile` |
+| Which raw REST route exists? | `list_routes` |
 | Name → ID | `resolve_entity` / `search_entities` |
 
 Composites multi-fetch server-side, return a **stable JSON envelope**, and isolate partial failures in `partial[]` so one bad secondary section does not fail the whole page.
@@ -124,7 +126,7 @@ The server **exits immediately** if `CITO_API_KEY` is missing. The key is sent o
 4. Match card → `match_summary` (then `match_details` if needed)
 5. Team / player pages → `team_profile` / `player_profile`
 6. Tables / rivalry / preview / event card → `standings` / `head_to_head` / `match_preview` / `event_card`
-7. Escape hatch → `call_api` (allowlisted paths only)
+7. Escape hatch → `list_routes` to find a path, then `call_api` (allowlisted paths only)
 
 **Never invent IDs** — resolve them or take them from live / schedule / search results.
 
@@ -132,7 +134,7 @@ Mnemonic: **resolve → live/schedule → summary → deep**.
 
 ---
 
-## Tool catalog (15)
+## Tool catalog (16)
 
 All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (the server name already brands the surface).
 
@@ -151,9 +153,38 @@ All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (
 | `head_to_head` | Composed H2H (no first-class REST H2H) | Rivalry / series record; preview context | Single-side form only; live scores; standings | `game`, `sideA`, `sideB`, `entityType?`, `limit?`, `from?`, `to?` |
 | `standings` | League/event tables or world/division rankings | Playoff picture; UFC rankings; CDL / CS2 tables | Team form; live scores; match recaps | `game`, `scope?`, `leagueId?`, `tournamentId?`, `eventId?`, `season?`, `stage?`, `division?`, `limit?` |
 | `match_preview` | Pre-match briefing: sides, rosters/form, H2H stub | Upcoming deep link; pick’ems; preview cards | Completed recaps; deep live state | `game`, `matchId` **or** (`teamA` + `teamB`), `eventId?`, `includeH2H?`, `includeRosters?`, `recentLimit?` |
-| `event_card` | Event / fight-night card: identity, bout/match list, optional standings | UFC card, CS2 event hub, tournament overview | Live-only strip; single match recap | `game`, `eventIdOrSlug` **or** `q`, `includeBouts?`, `includeStandings?`, `limit?` |
+| `event_card` | Event / fight-night card: identity + bouts in card order (main event first), each corner with photos, record, nickname, weight class; optional rankings | UFC card, CS2 event hub, tournament overview | Live-only strip; single match recap | `game`, `eventIdOrSlug` **or** `q`, `includeBouts?`, `includeStandings?`, `limit?` |
+| `list_routes` | Index of raw REST routes from the live OpenAPI spec (method, path, summary, tag) | Finding a long-tail path before `call_api`; checking an endpoint exists | A curated tool covers the outcome | `game?`, `q?`, `limit?` |
 | `call_api` | Allowlisted raw REST (`data.raw`) | Fortnite / long-tail paths; payload debugging | Any job covered by a curated tool | `path`, `method?`, `queryJson?`, `bodyJson?` |
 
+### Images
+
+Fighter and team sides carry an `images` object wherever upstream supplies one —
+on `event_card` bout corners and on `player_profile`. No extra call, no N+1.
+
+```jsonc
+"team1": {
+  "name": "Islam Makhachev",
+  "slug": "islam-makhachev",
+  "record": { "wins": 28, "losses": 1, "draws": 0, "text": "28-1-0 (W-L-D)" },
+  "championStatus": "champion",
+  "images": {
+    "headshotUrl":     "https://ufc.com/…/MAKHACHEV_ISLAM_BELT_01-18.png",
+    "bodyImageUrl":    "https://ufc.com/…/athlete_bio_full_body/…",
+    "imageUrl":        "https://ufc.com/…/event_fight_card_upper_body/…",
+    "proxiedImageUrl": "https://api.citoapi.com/api/v1/public/images/ufc/aHR0cHM6…"
+  }
+}
+```
+
+**Use `proxiedImageUrl` in a browser.** `ufc.com` sends no CORS header and can
+hotlink-block, so raw URLs render as broken images in a web UI. The proxied URL
+is served by the API and is safe to put in an `<img src>`.
+
+When a key is `null` the image does not exist for that entity; when the whole
+`images` object is absent, upstream sent nothing for that side. The object is
+never partially shaped — if any image exists, all four keys are present.
+
 ### Games
 
 | Game | Depth | Notes |
@@ -170,6 +201,7 @@ 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.
+- **UFC empty board honesty:** when `count === 0`, section includes `note`, `emptyReason`, slim `health` (`workerAlive`, lag), optional non-live `supervisor` strip and `nextCard` (armed only). Also `data.note` + `meta.warnings` for single-game UFC. Do not treat empty as HTTP failure; do not invent `? vs ?` from event shells.
 - **`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`.

package/dist/client.js

@@ -2,16 +2,30 @@
  * Authenticated Cito REST client for curated tools.
  * Auth: CITO_API_KEY → x-api-key. Logs never include the key.
  */
+import { PACKAGE_VERSION } from './version.js';
 export const DEFAULT_API_BASE = 'https://api.citoapi.com/api/v1';
 export const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024;
 /** stderr ONLY — stdout is the MCP stdio channel. */
 export function log(message) {
     console.error(`[cito-mcp] ${message}`);
 }
+/**
+ * Identify MCP traffic.
+ *
+ * Without this every MCP request arrives as Node's default agent - "node" -
+ * which is the single largest bucket in api_usage_logs (2.78M requests across
+ * 182 keys) and indistinguishable from any other script. That made MCP adoption
+ * unmeasurable: we could not tell whether an agent-driven user activates faster,
+ * consumes more, or converts better than someone hand-rolling curl.
+ *
+ * Versioned so a bad release can be isolated in the logs.
+ */
+export const CITO_MCP_USER_AGENT = `cito-mcp/${PACKAGE_VERSION} (+https://citoapi.com)`;
 export function authHeaders(apiKey, extra) {
     return {
         'x-api-key': apiKey,
         accept: 'application/json',
+        'user-agent': CITO_MCP_USER_AGENT,
         ...extra,
     };
 }

package/dist/index.js

@@ -18,17 +18,37 @@ 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.4';
+import { PACKAGE_VERSION } from './version.js';
 const API_KEY = process.env.CITO_API_KEY;
+/**
+ * Tools that need no API key. These must keep working with the server
+ * unconfigured, so a user can add it and immediately see what it does.
+ */
+const OFFLINE_TOOLS = new Set(['list_capabilities']);
+/**
+ * Missing key is NOT fatal.
+ *
+ * This used to process.exit(1) before the transport was even created, so the
+ * handshake never completed and the client showed only "server failed to
+ * start" — no tool list, no reason, nothing the model could relay. The user's
+ * first experience of a mistyped env var was a dead server.
+ *
+ * Now the server boots, completes initialize, and advertises its full catalog.
+ * Tools that need the API return a structured MISSING_API_KEY envelope with
+ * recovery steps, which the model can read out; list_capabilities keeps working
+ * offline so the server is browsable before it is configured.
+ */
 if (!API_KEY) {
-    console.error('[cito-mcp] CITO_API_KEY is required.\n' +
-        'Set it to your Cito API key, e.g.:\n' +
-        '  claude mcp add cito -e CITO_API_KEY=cito_... -- npx cito-mcp');
-    process.exit(1);
+    // stderr only — stdout is the JSON-RPC channel and must stay clean.
+    console.error('[cito-mcp] CITO_API_KEY is not set. Serving tool catalog only; ' +
+        'API-backed tools will return MISSING_API_KEY until a key is provided. ' +
+        'Get one at https://citoapi.com/dashboard and set CITO_API_KEY.');
 }
 const API_BASE = (process.env.CITO_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
 const ctx = {
-    apiKey: API_KEY,
+    // Empty string when unconfigured; the dispatcher blocks API-backed tools
+    // before any request is attempted, so this is never sent as a credential.
+    apiKey: API_KEY ?? '',
     baseUrl: API_BASE,
 };
 async function main() {
@@ -59,6 +79,25 @@ async function main() {
                 recover: ['Call list_capabilities to see available tools'],
             }));
         }
+        // Fail the CALL, not the process. The model gets an actionable envelope it
+        // can relay verbatim instead of the client reporting a dead server.
+        if (!API_KEY && !OFFLINE_TOOLS.has(name)) {
+            return toMcpResult(errorEnvelope({
+                code: 'UNAUTHORIZED',
+                message: 'CITO_API_KEY is not set, so this tool cannot reach the Cito API. ' +
+                    'The server is running and list_capabilities still works.',
+                game: null,
+                source: 'cito-mcp',
+                httpStatus: 401,
+                retryable: false,
+                recover: [
+                    'Create a key at https://citoapi.com/dashboard',
+                    'claude mcp add cito -e CITO_API_KEY=cito_... -- npx cito-mcp',
+                    'Or set CITO_API_KEY in the mcpServers env block of your client config',
+                    'Call list_capabilities to browse available tools without a key',
+                ],
+            }));
+        }
         return runTool(tool, args, ctx);
     });
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({

package/dist/instructions.js

@@ -57,6 +57,7 @@ resolve_entity ambiguity is soft: ok:true with data.needsDisambiguation and data
 ## Recipes
 
 Live board: api_health (optional) → live_matches → match_summary for selected matchId.
+UFC empty live (count=0): read section.note / emptyReason / health (workerAlive, lag) / supervisor / nextCard — do not claim "API offline" without workerAlive/lag; never invent matchups from supervisor shells.
 Team page: resolve_entity {type:team} → team_profile.
 Player card: resolve_entity {type:player|fighter} → player_profile.
 Fight night / event card: resolve_entity {type:event} → event_card {includeBouts:true} → match_preview for a featured bout.

package/dist/tools/index.js

@@ -6,7 +6,7 @@ import { playerTools } from './player.js';
 import { teamTools } from './team.js';
 import { standingsTools } from './standings.js';
 import { insightTools } from './insight.js';
-/** Curated outcome-tool catalog (15 tools). Order matches preferred cold-start ladder. */
+/** Curated outcome-tool catalog (16 tools). Order matches preferred cold-start ladder. */
 export const allTools = [
     ...metaTools.filter((t) => t.name === 'list_capabilities' || t.name === 'api_health'),
     ...resolveTools,
@@ -16,7 +16,8 @@ export const allTools = [
     ...teamTools,
     ...standingsTools,
     ...insightTools,
-    ...metaTools.filter((t) => t.name === 'call_api'),
+    // Escape-hatch pair last: discover routes, then call one.
+    ...metaTools.filter((t) => t.name === 'list_routes' || t.name === 'call_api'),
 ];
 export function getTool(name) {
     return allTools.find((t) => t.name === name);

package/dist/tools/insight.js

@@ -3,7 +3,7 @@
  */
 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 { normalizeMatch, sortByCardOrder } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
 async function loadSide(ctx, game, side, recentLimit, includeRosters) {
     const partial = [];
@@ -573,7 +573,14 @@ When to use:
 - CS2 event hub with match list
 - Tournament/event overview before match_preview drill-down
 
-Prefer over: agent-side resolve + call_api /ufc/events + bout expansion; N+1 match_summary for the card list only.
+Bouts come back in card order — main event first, then prelims, then early prelims.
+Each bout carries weightClass, titleBout, card placement, and (once fought) result
+{ method, round, time, referee, winnerSlug }. Each corner carries images
+{ headshotUrl, bodyImageUrl, imageUrl, proxiedImageUrl }, record, nickname, rank,
+championStatus, country and flag when upstream supplies them. Use proxiedImageUrl in
+browsers — ufc.com sends no CORS header. You do not need call_api per fighter for faces.
+
+Prefer over: agent-side resolve + call_api /ufc/events + bout expansion; N+1 match_summary for the card list only; per-fighter call_api just to fetch headshots.
 
 Prefer match_preview for one bout/match briefing; match_summary for completed recaps; live_matches for live-only strips; standings alone for pure tables.
 
@@ -585,12 +592,17 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeBouts": true, "inc
         type: 'object',
         additionalProperties: false,
         required: ['game'],
+        // The handler needs an event to look up, so `game` alone always fails.
+        // Say so in the schema rather than letting a client believe game suffices.
+        anyOf: [{ required: ['eventIdOrSlug'] }, { required: ['q'] }],
         properties: {
             game: gameSchema({ allowAll: false, required: true }),
-            eventIdOrSlug: stringSchema('Event or tournament id/slug. Prefer over q when known. Example: "ufc-300".', 'ufc-300'),
+            eventIdOrSlug: stringSchema('Event or tournament id/slug. Prefer over q when known. Required unless q is given. Example: "ufc-300".', 'ufc-300'),
             q: stringSchema('Free-text event name when id/slug unknown. Example: "UFC 300". Resolves within this tool — still prefer resolve_entity when disambiguating many hits.', 'UFC 300'),
             includeBouts: boolSchema('Include bout/match list (default true).', true),
-            includeStandings: boolSchema('Include standings/rankings snippet when API supports event/tournament/division scope (default false).', false),
+            includeStandings: boolSchema('Include standings/rankings snippet when API supports event/tournament/division scope (default false). ' +
+                'For UFC this also joins divisional rank and movement onto each bout corner as team.rank / team.rankMovement — ' +
+                'bout rows themselves carry no rank. Costs one extra upstream call.', false),
             limit: limitSchema({
                 default: 20,
                 max: 50,
@@ -684,12 +696,14 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeBouts": true, "inc
                 if (includeBouts) {
                     const embedded = extractRows(inner.bouts ?? inner.fights ?? data.bouts);
                     if (embedded.length) {
-                        bouts = embedded.slice(0, limit).map((row) => normalizeMatch('ufc', {
+                        // Order the full card before slicing — truncating upstream order
+                        // first can drop the main event and keep an early prelim.
+                        bouts = sortByCardOrder(embedded.map((row) => normalizeMatch('ufc', {
                             ...(asRecord(row) ?? {}),
                             eventName: event.name,
                             eventId: event.id,
                             eventSlug: event.slug,
-                        }, undefined));
+                        }, undefined))).slice(0, limit);
                     }
                 }
             }
@@ -728,14 +742,12 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeBouts": true, "inc
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...boutsRes.headers };
                 if (boutsRes.ok) {
-                    bouts = extractRows(boutsRes.data)
-                        .slice(0, limit)
-                        .map((row) => normalizeMatch('ufc', {
+                    bouts = sortByCardOrder(extractRows(boutsRes.data).map((row) => normalizeMatch('ufc', {
                         ...(asRecord(row) ?? {}),
                         eventName: event.name,
                         eventId: event.id,
                         eventSlug: event.slug,
-                    }, undefined));
+                    }, undefined))).slice(0, limit);
                 }
                 else {
                     partial.push(partialFromRejection('bouts', {
@@ -750,10 +762,69 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeBouts": true, "inc
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...ranks.headers };
                 if (ranks.ok) {
+                    // Bout rows carry rankText: null, so a card built from them alone is
+                    // rank-blind. The rankings payload is one row per fighter keyed by
+                    // slug, so join it onto the corners we already have instead of
+                    // handing back a raw blob the caller has to re-index itself.
+                    const rankRows = extractRows(ranks.data)
+                        .map((row) => asRecord(row))
+                        .filter((r) => Boolean(r));
+                    const bySlug = new Map();
+                    for (const r of rankRows) {
+                        const slug = pickString(r.fighterSlug, asRecord(r.fighter)?.slug);
+                        if (slug)
+                            bySlug.set(slug.toLowerCase(), r);
+                    }
+                    const withRank = (side) => {
+                        if (!side?.slug)
+                            return side;
+                        const hit = bySlug.get(side.slug.toLowerCase());
+                        if (!hit)
+                            return side;
+                        const rankText = pickString(hit.rankText);
+                        const movement = pickString(asRecord(hit.movement)?.label, hit.rankChangeText);
+                        return {
+                            ...side,
+                            ...(side.rank == null && rankText ? { rank: rankText } : {}),
+                            ...(movement ? { rankMovement: movement } : {}),
+                        };
+                    };
+                    bouts = bouts.map((b) => ({ ...b, team1: withRank(b.team1), team2: withRank(b.team2) }));
+                    // Scope the table to divisions actually on this card. The full ladder
+                    // is 176 rows (~42KB) and doubles the response; a card with no
+                    // bantamweight bout has no use for the bantamweight ladder, and that
+                    // context is not free for the agent reading it.
+                    const cardDivisions = new Set(bouts
+                        .flatMap((b) => [b.weightClass, b.team1?.division, b.team2?.division])
+                        .filter((d) => Boolean(d))
+                        // "Welterweight Title" must still match the Welterweight ladder.
+                        .map((d) => d.toLowerCase().replace(/\s+title$/, '').trim()));
+                    const inScope = (r) => {
+                        if (cardDivisions.size === 0)
+                            return true;
+                        const d = pickString(r.division, r.normalizedDivision)?.toLowerCase().trim();
+                        return d ? cardDivisions.has(d) : false;
+                    };
+                    const scoped = rankRows.filter(inScope);
+                    const shown = scoped.length > 0 ? scoped : rankRows;
+                    const shownDivisions = [...new Set(shown.map((r) => pickString(r.division)).filter(Boolean))];
                     standingsSnippet = {
                         scope: 'division',
-                        note: 'UFC global rankings (not event-specific bracket)',
-                        raw: ranks.data,
+                        note: 'UFC global rankings (not an event bracket), joined onto bout corners as team.rank / team.rankMovement. ' +
+                            (scoped.length > 0 && scoped.length < rankRows.length
+                                ? // Count the ladders actually returned, not the card's weight
+                                    // classes — catchweight bouts have no ranking ladder.
+                                    `Rows filtered to the ${shownDivisions.length} ranked division(s) on this card; ${rankRows.length} rows exist across all divisions.`
+                                : 'All divisions shown.'),
+                        divisions: shownDivisions,
+                        rows: shown.map((r) => ({
+                            division: pickString(r.division) ?? null,
+                            rank: pickString(r.rankText) ?? null,
+                            fighterSlug: pickString(r.fighterSlug) ?? null,
+                            fighterName: pickString(r.fighterName) ?? null,
+                            isChampion: r.isChampion === true,
+                            movement: pickString(asRecord(r.movement)?.label) ?? null,
+                        })),
                     };
                 }
                 else {

package/dist/tools/live.js

@@ -16,6 +16,8 @@ const LIVE_PATHS = {
  * Extract live match/bout rows. UFC /ufc/live returns
  * { liveBouts, events, ... } — events are supervisor shells without fighters.
  * Prefer liveBouts (and nested tracking on events) over plain events[].
+ * Never promote bare events[] to match rows (avoids fake "? vs ?").
+ * Nested tracking with status armed is excluded from live items (use nextCard).
  * Exported for offline UFC projection tests.
  */
 export function extractLiveRows(data, game) {
@@ -24,6 +26,20 @@ export function extractLiveRows(data, game) {
     if (!payload)
         return extractRows(data);
     if (game === 'ufc') {
+        const pushLiveTracking = (tracking, er, out) => {
+            for (const t of tracking) {
+                const tr = asRecord(t) ?? {};
+                const status = String(pickString(tr.status) ?? '').toLowerCase();
+                // Board items = live|watching only; armed is surfaced as nextCard, not items.
+                if (status === 'armed' || status === 'completed' || status === 'stale')
+                    continue;
+                out.push({
+                    ...tr,
+                    eventSlug: pickString(tr.eventSlug, er?.eventSlug, er?.slug),
+                    eventName: pickString(er?.name, er?.eventName, er?.eventSlug),
+                });
+            }
+        };
         // Prefer liveBouts when the key is present (including empty [] — honest empty board).
         if (Array.isArray(payload.liveBouts)) {
             const liveBouts = payload.liveBouts;
@@ -37,16 +53,9 @@ export function extractLiveRows(data, game) {
             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),
-                    });
-                }
+                pushLiveTracking(tracking, er, nested);
             }
-            return nested; // [] when only supervisor shells
+            return nested; // [] when only supervisor shells / armed-only
         }
         // liveBouts key missing — try nested tracking under events
         const events = Array.isArray(payload.events) ? payload.events : [];
@@ -54,14 +63,7 @@ export function extractLiveRows(data, game) {
         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),
-                });
-            }
+            pushLiveTracking(tracking, er, fromTracking);
         }
         if (fromTracking.length)
             return fromTracking;
@@ -70,6 +72,103 @@ export function extractLiveRows(data, game) {
     }
     return extractRows(data);
 }
+/** Machine emptyReason codes from API health / meta (or inferred). */
+export function inferUfcEmptyReason(events, health, liveCount) {
+    if (liveCount > 0)
+        return undefined;
+    const fromHealth = pickString(health?.emptyReason);
+    if (fromHealth)
+        return fromHealth;
+    const pulses = events.map((ev) => asRecord(ev) ?? {});
+    if (!pulses.length) {
+        const alive = health?.workerAlive ?? health?.workerStarted;
+        if (alive === false)
+            return 'worker_down_inferred';
+        return 'idle_no_supervisor';
+    }
+    const statuses = pulses.map((p) => String(pickString(p.status, p.eventStatus) ?? '').toLowerCase());
+    const lags = pulses
+        .map((p) => (typeof p.lagSeconds === 'number' ? p.lagSeconds : null))
+        .filter((n) => n != null);
+    const freshest = lags.length ? Math.min(...lags) : null;
+    const workerAlive = health?.workerAlive ?? health?.workerStarted;
+    const hot = statuses.some((s) => ['live', 'warming', 'between_bouts', 'degraded'].includes(s));
+    if (workerAlive === false && (hot || (freshest != null && freshest > 120))) {
+        return 'worker_stale';
+    }
+    if (statuses.some((s) => s === 'degraded'))
+        return 'event_degraded';
+    if (statuses.some((s) => s === 'warming'))
+        return 'supervisor_warming';
+    if (statuses.some((s) => s === 'between_bouts'))
+        return 'between_bouts';
+    if (statuses.every((s) => s === 'completed'))
+        return 'not_fight_night';
+    if (hot)
+        return 'between_bouts';
+    return 'not_fight_night';
+}
+/** Human note for empty UFC live section — never invent matchups. */
+export function humanUfcEmptyNote(emptyReason, health) {
+    const alive = health?.workerAlive ?? health?.workerStarted;
+    const lag = typeof health?.freshestHeartbeatLagSeconds === 'number'
+        ? health.freshestHeartbeatLagSeconds
+        : typeof health?.lagSeconds === 'number'
+            ? health.lagSeconds
+            : null;
+    const lagPart = typeof lag === 'number' ? ` lag=${lag}s` : '';
+    const workerPart = alive === true ? 'workerAlive=true' : alive === false ? 'workerAlive=false' : 'workerAlive=unknown';
+    const reason = emptyReason || 'unknown';
+    const human = {
+        not_fight_night: 'No UFC live card right now',
+        idle_no_supervisor: 'Supervisor has no live event rows',
+        supervisor_warming: 'Card open / pre-gate; no bout live yet',
+        between_bouts: 'Between bouts; next may be armed',
+        armed_only: 'Next bout armed; not started',
+        worker_stale: 'Worker heartbeat stale — check pm2 ufc-live on VPS 169',
+        worker_down_inferred: 'Worker appears down — check pm2 ufc-live on VPS 169',
+        event_degraded: 'Sources empty clock / event degraded; not inventing stats',
+    };
+    const msg = human[reason] || `No live|watching bouts (${reason})`;
+    return `UFC: ${msg} (${workerPart}${lagPart}; emptyReason=${reason})`;
+}
+function slimUfcSupervisorEvents(events, limit = 3) {
+    return events.slice(0, limit).map((ev) => {
+        const er = asRecord(ev) ?? {};
+        return {
+            kind: 'supervisor',
+            eventSlug: pickString(er.eventSlug, er.slug) ?? null,
+            status: pickString(er.status, er.eventStatus) ?? null,
+            currentLiveFmid: er.currentLiveFmid ?? null,
+            nextCandidateFmid: er.nextCandidateFmid ?? null,
+            lagSeconds: typeof er.lagSeconds === 'number' ? er.lagSeconds : null,
+            recommendedPollSeconds: typeof er.recommendedPollSeconds === 'number' ? er.recommendedPollSeconds : null,
+            degradedReason: pickString(er.degradedReason) ?? null,
+            note: 'Non-live supervisor shell — not a matchup',
+        };
+    });
+}
+function slimUfcNextCard(payload) {
+    if (!payload)
+        return undefined;
+    const nextBouts = Array.isArray(payload.nextBouts) ? payload.nextBouts : [];
+    const first = asRecord(payload.nextArmedBout) ??
+        (nextBouts[0] ? asRecord(nextBouts[0]) : null);
+    if (!first)
+        return undefined;
+    return {
+        kind: 'next_armed',
+        status: pickString(first.status) ?? 'armed',
+        boutId: pickString(first.boutId, first.id) ?? null,
+        eventSlug: pickString(first.eventSlug) ?? null,
+        fightMetricId: first.fightMetricId ?? null,
+        // Names only if API already provided them — never invent.
+        red: first.red ?? null,
+        blue: first.blue ?? null,
+        degradedReason: pickString(first.degradedReason) ?? null,
+        note: 'Armed / up-next only — not currently live',
+    };
+}
 export const liveMatches = {
     name: 'live_matches',
     description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
@@ -83,6 +182,7 @@ Prefer over: sequential per-game call_api live probes.
 Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
 
 CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
+UFC empty board: section.note + emptyReason + health (workerAlive/lag) + optional supervisor/nextCard (non-live); never fake match items from events[].
 
 Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
 Example: { "game": "all", "limitPerGame": 10 }`,
@@ -127,6 +227,7 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             return { game, path, res };
         }));
         const sections = [];
+        const warnings = [];
         for (const { game, res } of settled) {
             upstreamCalls += 1;
             rateLimit = { ...rateLimit, ...res.headers };
@@ -148,21 +249,26 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             }
             // 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 root = asRecord(res.data);
+            const payload = asRecord(root?.data) ?? root;
+            const meta = asRecord(root?.meta);
+            if (rows.length === 0 && Array.isArray(root?.matches))
+                rows = root.matches;
             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).
+                // Drop hollow UFC rows agents cannot use (placeholder labels / no sides).
+                // normalizeMatch already enriches label from eventSlug/weight/bout id when
+                // fighters are pending — keep those; drop pure "? vs ?" only.
                 .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)
+                const placeholder = /^\?\s*vs\s*\?$/i.test(m.label.trim());
+                if (placeholder)
+                    return false;
+                if (m.team1?.name || m.team2?.name)
                     return true;
-                // Keep if at least a real bout id even when fighters pending
+                // Identity-only live row (enriched Bout {id} / event name) is ok
                 return Boolean(m.matchId && m.matchId !== 'unknown' && !String(m.matchId).startsWith('event'));
             });
             const items = labelsOnly
@@ -174,6 +280,44 @@ Example: { "game": "all", "limitPerGame": 10 }`,
                     startTime: m.startTime,
                 }))
                 : normalized;
+            if (game === 'ufc') {
+                const health = asRecord(meta?.health) ?? asRecord(payload?.health);
+                const events = Array.isArray(payload?.events) ? payload.events : [];
+                const emptyReason = normalized.length === 0
+                    ? pickString(meta?.emptyReason, health?.emptyReason) ??
+                        inferUfcEmptyReason(events, health, normalized.length)
+                    : undefined;
+                let note;
+                if (normalized.length === 0) {
+                    note = humanUfcEmptyNote(emptyReason, health);
+                    warnings.push(note);
+                }
+                const healthStrip = normalized.length === 0 || health?.workerAlive === false || health?.workerStarted === false
+                    ? {
+                        workerStarted: health?.workerStarted ?? health?.workerAlive ?? null,
+                        workerAlive: health?.workerAlive ?? health?.workerStarted ?? null,
+                        freshestHeartbeatLagSeconds: health?.freshestHeartbeatLagSeconds ?? meta?.lagSeconds ?? null,
+                        emptyReason: emptyReason ?? health?.emptyReason ?? null,
+                        degradedReason: health?.degradedReason ?? null,
+                        ok: health?.ok ?? null,
+                        redis_ready: health?.redis_ready ?? meta?.redis_ready ?? meta?.redis_configured ?? null,
+                    }
+                    : undefined;
+                const supervisor = normalized.length === 0 && events.length ? slimUfcSupervisorEvents(events) : undefined;
+                const nextCard = normalized.length === 0 ? slimUfcNextCard(payload) : undefined;
+                sections.push({
+                    game,
+                    count: normalized.length,
+                    ok: true,
+                    note,
+                    emptyReason,
+                    health: healthStrip,
+                    supervisor,
+                    nextCard,
+                    items,
+                });
+                continue;
+            }
             sections.push({
                 game,
                 count: normalized.length,
@@ -182,6 +326,11 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             });
         }
         const totalLive = sections.reduce((sum, s) => sum + (s.ok ? s.count : 0), 0);
+        // Top-level note when single-game UFC empty so agents don't need deep section walk.
+        const ufcSection = sections.find((s) => s.game === 'ufc');
+        const dataNote = games.length === 1 && games[0] === 'ufc' && ufcSection && ufcSection.count === 0
+            ? ufcSection.note
+            : undefined;
         return successEnvelope({
             source: 'live_matches',
             game: games.length === 1 ? games[0] : null,
@@ -190,10 +339,12 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             upstreamCalls,
             rateLimit,
             partial: partial.length ? partial : undefined,
+            warnings: warnings.length ? warnings : undefined,
             data: {
                 sections,
                 totalLive,
                 asOf: new Date().toISOString(),
+                ...(dataNote ? { note: dataNote } : {}),
             },
         });
     },