cito-mcp 0.2.3 → 0.2.5

package/README.md

@@ -2,7 +2,7 @@
 
 Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports API](https://api.citoapi.com) — **curated outcome tools** for agents building esports apps, dashboards, bots, and research flows.
 
-**Version:** `0.2.3` · **Node:** `>=20` · **Install:** `npx cito-mcp`
+**Version:** `0.2.4` · **Node:** `>=20` · **Install:** `npx cito-mcp`
 
 Primary games: **lol · cs2 · dota2 · cod · ufc**. Fortnite and long-tail REST stay available via `call_api`.
 
@@ -164,6 +164,17 @@ All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (
 | `cod` | medium | Org slugs; CDL standings; UUID match ids |
 | `ufc` | medium | Fighter slugs; `boutId`; live + rankings |
 
+### UFC projection notes (0.2.4)
+
+Hardened agent-facing UFC shapes (offline-tested):
+
+- **`normalizeMatch`** reads `fighters[]` (`corner` + `fighterName` / `profile.name`), live `red`/`blue`, and `boutId` / `dataId` / bare `id`. Never keeps label `? vs ?` when fighter names exist (including blue-first arrays).
+- **`live_matches`** uses `extractLiveRows`: prefer `liveBouts` (empty array = honest empty board); never promote supervisor `events[]` shells into match rows.
+- **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`.
+
 Fortnite: **`call_api` only** until promoted into the primary enum.
 
 ### `call_api` allowlist
@@ -398,7 +409,7 @@ src/
 
 ## Publish notes
 
-Package: **`cito-mcp@0.2.2`**
+Package: **`cito-mcp@0.2.4`**
 
 | Item | Value |
 | --- | --- |
@@ -433,7 +444,7 @@ claude mcp add cito -e CITO_API_KEY=cito_… -- npx cito-mcp
 
 ### Semver expectations
 
-- **0.2.0** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
+- **0.2.4** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
 - Further 0.2.x patches may refine envelopes and composite quality without renaming the 15 tools.
 - Promoting Fortnite (or other titles) into the primary `game` enum would be a minor feature bump with catalog/docs updates.
 
@@ -441,7 +452,16 @@ claude mcp add cito -e CITO_API_KEY=cito_… -- npx cito-mcp
 
 ## Changelog (summary)
 
-### 0.2.0
+### 0.2.4
+
+- **UFC projection hardening** (offline-tested):
+  - `normalizeMatch`: `fighters[]` corners + profile, live red/blue, `boutId`/`dataId`; never keep `? vs ?` when names exist
+  - `extractRows` / `extractLiveRows`: prefer `liveBouts` (including empty); never fake match rows from supervisor `events[]`
+  - `upcoming_schedule`: client-side `hours`/`from`/`to`; bout expansion with fighter labels; event shells labeled by event name
+  - `event_card` bouts share the same normalize path
+  - `standings`: champion rank `C` / interim `IC`; no dual numeric `#1` for champ + contender
+
+### 0.2.4
 
 - **Breaking:** replaced OpenAPI mass-generated tools with **15 curated outcome tools**
 - Stable JSON envelope + MCP server instructions

package/dist/client.js

@@ -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,
     };
 }
@@ -172,6 +186,42 @@ export function asRecord(value) {
     }
     return null;
 }
+/**
+ * Peel Cito `{ success, data: T }` (and one nested `data`) so tools see the entity,
+ * not the envelope. Arrays and primitives pass through. Critical for UFC bouts/fighters
+ * where fighters[] / name live under data, not the top-level response.
+ */
+export function unwrapPayload(value) {
+    let cur = value;
+    for (let depth = 0; depth < 3; depth += 1) {
+        const rec = asRecord(cur);
+        if (!rec)
+            return cur;
+        // Classic withMeta: { success: true, data: { ...entity } }
+        if ('data' in rec && rec.data != null && typeof rec.data === 'object' && !Array.isArray(rec.data)) {
+            const inner = rec.data;
+            // Prefer entity-shaped inner objects over list wrappers
+            const looksLikeEntity = 'id' in inner ||
+                'slug' in inner ||
+                'name' in inner ||
+                'title' in inner ||
+                'fighters' in inner ||
+                'boutId' in inner ||
+                'matchId' in inner ||
+                'team1' in inner ||
+                'red' in inner ||
+                'blue' in inner ||
+                'record' in inner ||
+                'nickname' in inner;
+            if (looksLikeEntity || rec.success === true) {
+                cur = rec.data;
+                continue;
+            }
+        }
+        break;
+    }
+    return cur;
+}
 export function pickString(...values) {
     for (const v of values) {
         if (typeof v === 'string' && v.length > 0)

package/dist/index.js

@@ -18,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.3';
+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/insight.js

@@ -1,7 +1,7 @@
 /**
  * match_preview — pre-match briefing composite
  */
-import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
+import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { normalizeMatch } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
@@ -18,11 +18,15 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
         calls += 1;
         rateLimit = res.headers;
         if (res.ok) {
-            const data = asRecord(res.data) ?? {};
+            const data = asRecord(unwrapPayload(res.data)) ?? {};
             entity = {
-                id: pickString(data.id, side),
+                id: pickString(data.id, data.slug, side),
                 slug: pickString(data.slug, side),
-                name: pickString(data.name, side),
+                // Prefer real display name; never leave entity.name as the slug when name exists
+                name: pickString(data.name, data.displayName, data.nickname, side) ?? side,
+                nickname: pickString(data.nickname) ?? null,
+                division: pickString(data.division) ?? null,
+                recordText: pickString(data.recordText, asRecord(data.record)?.text) ?? null,
                 game,
             };
         }
@@ -33,11 +37,33 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
                 httpStatus: res.status,
             }));
         }
+        // Fight-by-fight form (not aggregate stats alone)
+        const fights = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(side)}/fights`, {
+            query: { limit: recentLimit },
+        });
+        calls += 1;
+        rateLimit = { ...rateLimit, ...fights.headers };
+        if (fights.ok) {
+            recentForm = extractRows(unwrapPayload(fights.data) ?? fights.data)
+                .slice(0, recentLimit)
+                .map((row) => {
+                // history rows nest bout
+                const r = asRecord(row) ?? {};
+                const bout = asRecord(r.bout) ?? r;
+                return normalizeMatch('ufc', { ...bout, ...(r.fighterName ? {} : {}) }, 'completed');
+            });
+        }
         const stats = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(side)}/stats`);
         calls += 1;
         rateLimit = { ...rateLimit, ...stats.headers };
-        if (stats.ok)
-            recentForm = [stats.data];
+        if (stats.ok && recentForm.length === 0) {
+            recentForm = []; // keep empty rather than stuffing aggregate as "matches"
+            keyPlayers = [];
+        }
+        if (stats.ok) {
+            // stash aggregate on entity for talking points
+            entity = { ...entity, stats: unwrapPayload(stats.data) };
+        }
         return { entity, roster, recentForm, keyPlayers, calls, partial, rateLimit };
     }
     if (game === 'lol') {
@@ -285,14 +311,19 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
             upstreamCalls += 1;
             rateLimit = res.headers;
             if (res.ok) {
-                const m = normalizeMatch(game, res.data, 'upcoming');
+                const entity = unwrapPayload(res.data);
+                // Do not force "upcoming" — completed bouts (e.g. UFC 300) should keep completed.
+                const m = normalizeMatch(game, entity);
                 context = {
-                    matchId: m.matchId,
+                    matchId: m.matchId !== 'unknown' ? m.matchId : matchId,
                     startTime: m.startTime,
                     event: m.event,
+                    eventName: m.event?.name ?? null,
                     league: m.league,
                     status: m.status,
+                    label: m.label,
                 };
+                // Prefer stable slugs for follow-up fighter fetches
                 if (!teamA)
                     teamA = m.team1?.slug || m.team1?.id || m.team1?.name || '';
                 if (!teamB)
@@ -366,6 +397,27 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                     if (res.ok)
                         rows = extractRows(res.data);
                 }
+                else if (game === 'ufc') {
+                    // Fighter fight history is the H2H source of truth (not global /bouts page 1).
+                    const hist = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(teamA)}/fights`, {
+                        query: { limit: 50 },
+                    });
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...hist.headers };
+                    if (hist.ok) {
+                        rows = extractRows(unwrapPayload(hist.data) ?? hist.data).map((row) => {
+                            const r = asRecord(row) ?? {};
+                            return asRecord(r.bout) ?? row;
+                        });
+                    }
+                    else {
+                        partial.push(partialFromRejection('h2h', {
+                            code: mapHttpToCode(hist.status),
+                            message: `fighter fights HTTP ${hist.status}`,
+                            httpStatus: hist.status,
+                        }));
+                    }
+                }
                 h2h = composeH2H(game, teamA, teamB, rows, 10);
             }
             catch (e) {

package/dist/tools/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 } : {}),
             },
         });
     },