cito-mcp 0.2.5 → 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 |

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/meta.js

@@ -88,10 +88,10 @@ const TOOL_CATALOG = [
     },
     {
         name: 'player_profile',
-        outcome: 'Player/fighter identity + recent form',
+        outcome: 'Player/fighter identity + recent form, including images (headshot, body, CORS-safe proxied)',
         parallelSafe: true,
         games: [...PRIMARY_GAMES],
-        jobs: ['player_form'],
+        jobs: ['player_form', 'media'],
         exampleArgs: { game: 'cs2', playerId: 'cs2-player-1', recentLimit: 10 },
         preferOver: ['manual multi-call career/trends via call_api'],
         doNotUse: 'Full team roster → team_profile; unresolved name → resolve_entity',
@@ -138,14 +138,29 @@ const TOOL_CATALOG = [
     },
     {
         name: 'event_card',
-        outcome: 'Event / fight-night card: identity + bout/match list (+ optional standings)',
+        outcome: 'Event / fight-night card: identity + bout list, card-ordered (main event first), ' +
+            'each corner carrying photos, record, nickname, country and weight class (+ optional standings)',
         parallelSafe: true,
         games: [...PRIMARY_GAMES],
-        jobs: ['event_card', 'schedule', 'app_scaffold'],
+        jobs: ['event_card', 'schedule', 'media', 'app_scaffold'],
         exampleArgs: { game: 'ufc', eventIdOrSlug: 'ufc-300', includeBouts: true },
-        preferOver: ['call_api /ufc/events + bout expansion', 'N+1 match_summary for card list'],
+        preferOver: [
+            'call_api /ufc/events + bout expansion',
+            'N+1 match_summary for card list',
+            'N+1 call_api per fighter for headshots — corners already include images',
+        ],
         doNotUse: 'Live-only strip → live_matches; single match recap → match_summary',
     },
+    {
+        name: 'list_routes',
+        outcome: 'Index of raw REST routes from the live OpenAPI spec (method, path, summary)',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES, 'fortnite'],
+        jobs: ['app_scaffold'],
+        exampleArgs: { game: 'ufc', q: 'rankings' },
+        preferOver: ['guessing a REST path for call_api', 'fetching the full 90KB spec by hand'],
+        doNotUse: 'A curated tool covers the outcome → list_capabilities',
+    },
     {
         name: 'call_api',
         outcome: 'Allowlisted raw REST escape hatch (unshaped data.raw)',
@@ -167,6 +182,13 @@ const JOBS = [
     { id: 'schedule', description: 'Upcoming fixtures/events', recommendedTools: ['upcoming_schedule', 'event_card'] },
     { id: 'preview', description: 'Pre-match briefing', recommendedTools: ['match_preview'] },
     { id: 'event_card', description: 'Event / fight-night card page', recommendedTools: ['event_card', 'resolve_entity', 'match_preview'] },
+    // Agents asked "does this API have photos?" and, finding no job for it,
+    // assumed no. Photos ship on every UFC corner and profile; make that findable.
+    {
+        id: 'media',
+        description: 'Headshots, full-body shots and team logos for visual UIs. UFC fighters carry headshotUrl / bodyImageUrl / imageUrl plus a CORS-safe proxiedImageUrl; use the proxied URL in a browser. Available on event_card corners and player_profile without any extra call.',
+        recommendedTools: ['event_card', 'player_profile', 'resolve_entity'],
+    },
     { id: 'app_scaffold', description: 'Design-time multi-screen prototype', recommendedTools: ['list_capabilities', 'api_health', 'live_matches'] },
 ];
 const RECIPES = [
@@ -450,7 +472,18 @@ Example: { "includeGameProbes": true }`,
         });
     },
 };
-const ALLOWLIST_PREFIXES = ['/health', '/lol', '/cs2', '/dota2', '/cod', '/ufc', '/fortnite'];
+const ALLOWLIST_PREFIXES = [
+    '/health',
+    '/lol',
+    '/cs2',
+    '/dota2',
+    '/cod',
+    '/ufc',
+    '/fortnite',
+    // The spec describes the surface call_api is allowed to reach; refusing to
+    // serve it left route discovery impossible except by guessing.
+    '/openapi.json',
+];
 function pathAllowed(path) {
     if (!path.startsWith('/') || path.startsWith('//'))
         return false;
@@ -604,6 +637,147 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
         });
     },
 };
-export const metaTools = [listCapabilities, apiHealth, callApi];
+/**
+ * Games whose routes the published spec does not describe.
+ *
+ * The spec has 123 paths and zero under /lol, yet every LoL route works —
+ * api_health itself answers partly from /lol/leagues. An agent that treats the
+ * spec as the whole surface concludes LoL is unsupported and stops, so say so
+ * explicitly rather than returning an empty list that reads as a verdict.
+ */
+const SPEC_OMITS = {
+    lol: 'The published OpenAPI spec documents no /lol paths, but LoL routes exist and work. Use the curated LoL tools (live_matches, upcoming_schedule, team_profile, standings, player_profile); for raw access, /lol/* is allowlisted for call_api even though it is undocumented.',
+};
+export const listRoutes = {
+    name: 'list_routes',
+    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
+
+When to use:
+- You need a long-tail path for call_api and do not want to guess
+- Checking whether an endpoint exists before building around it
+- Mapping what raw data backs a curated tool
+
+Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
+
+Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
+
+Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
+
+Parallel-safe: yes. Upstream cost: 1.
+Example: { "game": "ufc", "q": "rankings" }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            game: gameSchema({
+                allowAll: false,
+                description: 'Filter to one game prefix (also accepts fortnite). Omit for all routes.',
+            }),
+            q: stringSchema('Free-text filter over path and summary.', 'rankings'),
+            limit: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 200,
+                default: 60,
+                description: 'Max routes to return (default 60, max 200).',
+            },
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        // Accept fortnite here even though it is not a PRIMARY_GAME: it has 21
+        // documented paths and no curated tools, so it is exactly what call_api
+        // callers come looking for.
+        const gameRaw = typeof args.game === 'string' ? args.game.toLowerCase().trim() : '';
+        if (gameRaw && !gameRaw.match(/^(lol|cs2|dota2|cod|ufc|fortnite)$/)) {
+            return errorEnvelope({
+                code: 'UNSUPPORTED_GAME',
+                message: `unsupported game "${gameRaw}"; use lol|cs2|dota2|cod|ufc|fortnite`,
+                game: null,
+                source: 'list_routes',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const q = typeof args.q === 'string' ? args.q.toLowerCase().trim() : '';
+        const limit = Math.min(Math.max(Number(args.limit) || 60, 1), 200);
+        const res = await fetchJson(ctx, '/openapi.json');
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `openapi.json HTTP ${res.status}`,
+                game: gameRaw || null,
+                source: 'list_routes',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                rateLimit: res.headers,
+                httpStatus: res.status,
+                recover: [
+                    'Call list_capabilities for curated tools that need no route knowledge',
+                    'call_api accepts /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite',
+                ],
+            });
+        }
+        const spec = (res.data ?? {});
+        const paths = (spec.paths ?? {});
+        const rows = [];
+        for (const [path, ops] of Object.entries(paths)) {
+            if (!ops || typeof ops !== 'object')
+                continue;
+            for (const [method, opRaw] of Object.entries(ops)) {
+                if (!/^(get|post|put|patch|delete)$/i.test(method))
+                    continue;
+                const op = (opRaw ?? {});
+                const tags = Array.isArray(op.tags) ? op.tags : [];
+                rows.push({
+                    method: method.toUpperCase(),
+                    path,
+                    summary: typeof op.summary === 'string' ? op.summary : null,
+                    tag: typeof tags[0] === 'string' ? tags[0] : null,
+                });
+            }
+        }
+        let filtered = rows;
+        if (gameRaw)
+            filtered = filtered.filter((r) => r.path.startsWith(`/${gameRaw}`));
+        if (q) {
+            filtered = filtered.filter((r) => r.path.toLowerCase().includes(q) || (r.summary ?? '').toLowerCase().includes(q));
+        }
+        filtered.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+        const notes = [];
+        if (gameRaw && filtered.length === 0 && SPEC_OMITS[gameRaw])
+            notes.push(SPEC_OMITS[gameRaw]);
+        if (!gameRaw)
+            notes.push(SPEC_OMITS.lol);
+        if (filtered.length > limit) {
+            notes.push(`${filtered.length} routes matched; showing ${limit}. Narrow with game or q.`);
+        }
+        return successEnvelope({
+            data: {
+                specVersion: typeof spec.info?.version === 'string'
+                    ? spec.info.version
+                    : null,
+                totalDocumented: rows.length,
+                matched: filtered.length,
+                routes: filtered.slice(0, limit),
+                allowlistedPrefixes: ALLOWLIST_PREFIXES,
+                notes,
+                nextSteps: [
+                    'Prefer a curated tool when one covers the outcome (list_capabilities)',
+                    'call_api { path } for a route with no curated equivalent',
+                ],
+            },
+            game: gameRaw || null,
+            source: 'list_routes',
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+        });
+    },
+};
+export const metaTools = [listCapabilities, apiHealth, listRoutes, callApi];
 // silence unused import in case extractRows needed later
 void extractRows;

package/dist/tools/normalize.js

@@ -1,8 +1,34 @@
 /**
  * Cross-game row normalization for live/schedule boards and entity cards.
  */
-import { asRecord, pickString, unwrapPayload } from '../client.js';
-function sideFrom(name, id, slug, score) {
+import { asRecord, pickString, unwrapPayload, DEFAULT_API_BASE } from '../client.js';
+const IMAGE_PROXY_BASE = (process.env.CITO_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
+/**
+ * Bout rows carry raw ufc.com URLs but no proxied variant (only the fighter
+ * detail endpoint includes one). ufc.com can hotlink-block and sends no CORS
+ * header, so a browser-side card built straight off those URLs shows broken
+ * images. The proxy token is base64url of the source URL — verified to
+ * round-trip and serve HTTP 200 — so derive it rather than making the caller
+ * N+1 the fighter endpoint just to get a loadable image.
+ *
+ * UFC only: /public/images/lol/<token> returns HTTP 400, so other games get
+ * their raw URL and a null proxy rather than a fabricated link.
+ */
+function deriveProxiedImageUrl(rawUrl, game) {
+    if (!rawUrl || game !== 'ufc')
+        return null;
+    let host;
+    try {
+        host = new URL(rawUrl).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+    if (host !== 'ufc.com' && !host.endsWith('.ufc.com'))
+        return null;
+    return `${IMAGE_PROXY_BASE}/public/images/ufc/${Buffer.from(rawUrl, 'utf8').toString('base64url')}`;
+}
+function sideFrom(name, id, slug, score, extra) {
     if (!name && !id && !slug)
         return null;
     return {
@@ -10,9 +36,96 @@ function sideFrom(name, id, slug, score) {
         ...(id ? { id } : {}),
         ...(slug ? { slug } : {}),
         ...(score !== undefined ? { score } : {}),
+        ...(extra ?? {}),
+    };
+}
+function numOrNull(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v !== '' && Number.isFinite(Number(v)))
+        return Number(v);
+    return null;
+}
+/**
+ * Collect image URLs from a corner/team row and its nested profile. Returns
+ * undefined when the upstream carried none, so lean rows stay lean; when any
+ * image exists every key is present (null where absent) — a missing key would
+ * read as "this API has no images" rather than "no image for this one".
+ */
+function imagesFrom(game, ...sources) {
+    const pick = (...keys) => {
+        for (const src of sources) {
+            if (!src)
+                continue;
+            for (const k of keys) {
+                const v = pickString(src[k]);
+                if (v)
+                    return v;
+            }
+        }
+        return null;
+    };
+    const images = {
+        headshotUrl: pick('headshotUrl', 'headshot'),
+        bodyImageUrl: pick('bodyImageUrl', 'fullBodyImageUrl'),
+        imageUrl: pick('imageUrl', 'image', 'photoUrl', 'logoUrl', 'logo'),
+        proxiedImageUrl: pick('proxiedImageUrl', 'proxiedHeadshotUrl'),
+    };
+    if (!images.proxiedImageUrl) {
+        // Prefer the headshot for the proxied variant — it is the crop a card UI wants.
+        images.proxiedImageUrl =
+            deriveProxiedImageUrl(images.headshotUrl, game) ??
+                deriveProxiedImageUrl(images.imageUrl, game);
+    }
+    return Object.values(images).some(Boolean) ? images : undefined;
+}
+function recordFrom(...sources) {
+    for (const src of sources) {
+        if (!src)
+            continue;
+        const rec = asRecord(src.record);
+        const text = pickString(src.recordText, rec?.text);
+        if (!rec && !text)
+            continue;
+        const out = {
+            wins: numOrNull(rec?.wins),
+            losses: numOrNull(rec?.losses),
+            draws: numOrNull(rec?.draws),
+            noContest: numOrNull(rec?.noContest),
+            text: text ?? null,
+        };
+        if (Object.values(out).some((v) => v !== null))
+            return out;
+    }
+    return undefined;
+}
+/** Enrichment shared by UFC corners and (where upstream supplies it) team rows. */
+function sideExtras(o, game) {
+    const profile = asRecord(o.profile) ?? undefined;
+    const fighter = asRecord(o.fighter) ?? undefined;
+    const images = imagesFrom(game, o, profile, fighter);
+    const record = recordFrom(o, profile, fighter);
+    const nickname = pickString(profile?.nickname, fighter?.nickname, o.nickname);
+    const rank = pickString(o.rankText, o.rank, profile?.rankText);
+    const championStatus = pickString(o.championStatus, profile?.championStatus);
+    const division = pickString(profile?.division, o.division, o.weightClass);
+    const country = pickString(o.country, profile?.country);
+    const flag = pickString(o.flag, profile?.flag);
+    const outcome = pickString(o.outcome);
+    return {
+        ...(nickname ? { nickname } : {}),
+        ...(images ? { images } : {}),
+        ...(record ? { record } : {}),
+        ...(rank ? { rank } : {}),
+        // "none" carries no signal for a page; only surface an actual belt state.
+        ...(championStatus && championStatus.toLowerCase() !== 'none' ? { championStatus } : {}),
+        ...(division ? { division } : {}),
+        ...(country ? { country } : {}),
+        ...(flag ? { flag } : {}),
+        ...(outcome ? { outcome } : {}),
     };
 }
-function nestedSide(raw) {
+function nestedSide(raw, game) {
     const o = asRecord(raw);
     if (!o) {
         if (typeof raw === 'string')
@@ -29,7 +142,7 @@ function nestedSide(raw) {
         : typeof scoreRaw === 'string' && scoreRaw !== ''
             ? Number(scoreRaw)
             : null;
-    return sideFrom(name, id, slug, Number.isFinite(score) ? score : null);
+    return sideFrom(name, id, slug, Number.isFinite(score) ? score : null, sideExtras(o, game));
 }
 function scoreNum(v) {
     if (typeof v === 'number' && Number.isFinite(v))
@@ -42,9 +155,9 @@ export function normalizeMatch(game, row, forcedStatus) {
     // Always peel { success, data } so UFC bout fighters[] / status are visible.
     const r = asRecord(unwrapPayload(row)) ?? asRecord(row) ?? {};
     const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.fightMetricId, r.ufcFightId) ?? 'unknown';
-    let team1 = nestedSide(r.team1) ??
+    let team1 = nestedSide(r.team1, game) ??
         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) ??
+    let team2 = nestedSide(r.team2, game) ??
         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));
     // CS2 rows nest team1/team2 objects that lack a score; a nested side must not
     // shadow the flat score fields (team1Score/score1/team1Maps) with score:null.
@@ -76,7 +189,7 @@ export function normalizeMatch(game, row, forcedStatus) {
             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);
+            return sideFrom(name, id, slug, score, sideExtras(o, game));
         };
         team1 =
             team1 ??
@@ -106,8 +219,8 @@ export function normalizeMatch(game, row, forcedStatus) {
     }
     // COD sometimes uses teams[]
     if ((!team1 || !team2) && Array.isArray(r.teams)) {
-        team1 = team1 ?? nestedSide(r.teams[0]);
-        team2 = team2 ?? nestedSide(r.teams[1]);
+        team1 = team1 ?? nestedSide(r.teams[0], game);
+        team2 = team2 ?? nestedSide(r.teams[1], game);
     }
     const startTime = pickString(r.startTime, r.scheduledAt, r.startsAt, r.date, r.startDate, r.beginAt, asRecord(r.event)?.startsAt, asRecord(r.event)?.startTime, asRecord(r.event)?.date) ?? null;
     const statusRaw = pickString(r.status, r.state, r.matchStatus, r.boutStatus)?.toLowerCase() ?? '';
@@ -183,6 +296,22 @@ export function normalizeMatch(game, row, forcedStatus) {
                 (matchId && matchId !== 'unknown' ? `Bout ${matchId}` : null) ??
                 vsLabel;
     }
+    // Bout metadata already present on the upstream row. Passing it through here
+    // is what stops an agent from N+1'ing call_api to rebuild a fight card.
+    const cardSection = pickString(r.cardSection, r.cardSegment, r.segment);
+    const cardPosition = pickString(r.cardPosition);
+    const cardSectionOrder = numOrNull(r.cardSectionOrder);
+    const boutOrder = numOrNull(r.boutOrder);
+    const hasCard = cardSection != null || cardPosition != null || cardSectionOrder != null || boutOrder != null;
+    const method = pickString(r.method);
+    const methodDetails = pickString(r.methodDetails);
+    const resultTime = pickString(r.resultTime);
+    // UFC sends referee as { id, name, firstName, lastName } — not a string.
+    const referee = pickString(r.referee, asRecord(r.referee)?.name);
+    const winnerSlug = pickString(r.winnerFighterSlug, r.winnerSlug, r.winner);
+    const resultRound = numOrNull(r.resultRound);
+    const hasResultDetail = method != null || resultRound != null || winnerSlug != null || resultTime != null;
+    const isCancelled = r.isCancelled === true;
     return {
         game,
         matchId,
@@ -193,8 +322,55 @@ export function normalizeMatch(game, row, forcedStatus) {
         team2,
         event: eventName || eventId || eventSlug ? { id: eventId, slug: eventSlug, name: eventName } : null,
         league: leagueName || leagueId || leagueSlug ? { id: leagueId, slug: leagueSlug, name: leagueName } : null,
+        ...(weightOrClass ? { weightClass: weightOrClass } : {}),
+        ...(r.titleBout != null ? { titleBout: Boolean(r.titleBout) } : {}),
+        ...(hasCard
+            ? {
+                card: {
+                    section: cardSection ?? null,
+                    sectionOrder: cardSectionOrder,
+                    position: cardPosition ?? null,
+                    order: boutOrder,
+                },
+            }
+            : {}),
+        ...(hasResultDetail
+            ? {
+                result: {
+                    method: method ?? null,
+                    methodDetails: methodDetails ?? null,
+                    round: resultRound,
+                    time: resultTime ?? null,
+                    referee: referee ?? null,
+                    winnerSlug: winnerSlug ?? null,
+                },
+            }
+            : {}),
+        ...(isCancelled
+            ? { cancelled: { isCancelled: true, reason: pickString(r.cancellationReason) ?? null } }
+            : {}),
     };
 }
+/**
+ * Sort a fight card the way it is presented: main card before prelims, and the
+ * main event at the top of its section. Rows without placement keep their
+ * upstream order behind those that have it.
+ */
+export function sortByCardOrder(rows) {
+    const rank = (x, i) => ({
+        section: x.card?.sectionOrder ?? Number.MAX_SAFE_INTEGER,
+        order: x.card?.order ?? Number.MAX_SAFE_INTEGER,
+        i,
+    });
+    return rows
+        .map((x, i) => ({ x, k: rank(x, i) }))
+        .sort((a, b) => a.k.section !== b.k.section
+        ? a.k.section - b.k.section
+        : a.k.order !== b.k.order
+            ? a.k.order - b.k.order
+            : a.k.i - b.k.i)
+        .map((e) => e.x);
+}
 export function entityRef(row, type, game) {
     const r = asRecord(row) ?? {};
     const id = pickString(r.id, r.teamId, r.playerId, r.lolPlayerId, r.codPlayerId, r.matchId, r.boutId, r.eventId, r.tournamentId, r.leagueId) ??

package/dist/tools/player.js

@@ -29,6 +29,24 @@ function identityFrom(game, raw, idHint, slugHint) {
             : null,
         role: pickString(r.role, r.position) ?? null,
         nationality: pickString(r.nationality, r.country) ?? null,
+        /**
+         * Always present, keys always present, null when the upstream has no photo.
+         *
+         * REST has carried headshot/body/proxied images on /ufc/fighters/{slug} all
+         * along; this shaper silently dropped them, so every agent concluded the
+         * product had no images and either shipped faceless UIs or N+1'd call_api
+         * per fighter to dig them out. Emitting explicit nulls is the point: silence
+         * reads as "not supported", null reads as "not available for this one".
+         *
+         * proxiedImageUrl is the one builders should prefer — it is served from our
+         * own domain, so it works from a browser without hotlink/CORS trouble.
+         */
+        images: {
+            headshotUrl: pickString(r.headshotUrl, r.headshot) ?? null,
+            bodyImageUrl: pickString(r.bodyImageUrl, r.fullBodyImageUrl) ?? null,
+            imageUrl: pickString(r.imageUrl, r.image, r.photoUrl) ?? null,
+            proxiedImageUrl: pickString(r.proxiedImageUrl, r.proxiedHeadshotUrl) ?? null,
+        },
     };
 }
 export const playerProfile = {
@@ -332,7 +350,14 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                         .map((row) => {
                         const r = asRecord(row) ?? {};
                         const bout = asRecord(r.bout) ?? row;
-                        const m = normalizeMatch('ufc', bout, 'completed');
+                        // Never force 'completed'. A fighter's history endpoint also
+                        // returns bouts that are booked but not yet fought, and forcing
+                        // the status told agents that a future main event had already
+                        // happened (Hernandez vs Rodrigues, ufc-12928: status
+                        // 'confirmed', no method, no winner, event still scheduled,
+                        // reported as completed with result null). Let normalizeMatch
+                        // derive it from the result and the start time instead.
+                        const m = normalizeMatch('ufc', bout);
                         return {
                             ...m,
                             result: pickString(r.result, r.outcome, asRecord(bout)?.result) ?? null,
@@ -354,7 +379,8 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                             .map((row) => {
                             const r = asRecord(row) ?? {};
                             const bout = asRecord(r.bout) ?? row;
-                            return normalizeMatch('ufc', bout, 'completed');
+                            // Same as above: derive, never assert. See the note there.
+                            return normalizeMatch('ufc', bout);
                         });
                     }
                     else {

package/dist/tools/types.js

@@ -64,9 +64,82 @@ export function stringSchema(description, example) {
         schema.examples = [example];
     return schema;
 }
+/** Levenshtein distance, capped for short arg names. */
+function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    let prev = Array.from({ length: n + 1 }, (_, j) => j);
+    for (let i = 1; i <= m; i++) {
+        const cur = [i];
+        for (let j = 1; j <= n; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[n];
+}
+/** Closest known parameter to a mistyped one, if it is plausibly a typo. */
+function suggestParam(unknown, known) {
+    const u = unknown.toLowerCase();
+    let best = null;
+    for (const k of known) {
+        const d = editDistance(u, k.toLowerCase());
+        if (!best || d < best.d)
+            best = { name: k, d };
+    }
+    if (!best)
+        return null;
+    // Accept near-misses, plus prefix relationships like query -> q.
+    const threshold = Math.max(2, Math.floor(Math.max(u.length, best.name.length) / 3));
+    if (best.d <= threshold)
+        return best.name;
+    const prefixHit = known.find((k) => u.startsWith(k.toLowerCase()) || k.toLowerCase().startsWith(u));
+    return prefixHit ?? null;
+}
+/**
+ * Args the tool does not declare, when its schema says additionalProperties:false.
+ *
+ * Every tool already declared that, but nothing enforced it: the MCP SDK does
+ * not validate arguments against inputSchema, so a plausible-but-wrong name was
+ * dropped on the floor and the tool ran with a default. search_entities
+ * { game:"ufc", query:"Jon Jones" } — `q` is the real parameter — returned
+ * ok:true with an unrelated roster. Silently wrong beats loudly wrong for a
+ * human skimming output, but for an agent it is far worse: it has no way to
+ * tell a real answer from a discarded question.
+ */
+export function unknownArgKeys(def, args) {
+    const schema = def.inputSchema ?? {};
+    if (schema.additionalProperties !== false)
+        return [];
+    const props = schema.properties;
+    if (!props || typeof props !== 'object')
+        return [];
+    const known = Object.keys(props);
+    return Object.keys(args ?? {}).filter((k) => !known.includes(k));
+}
 /** Normalize MCP handler return to MCP content result. */
 export async function runTool(def, args, ctx) {
     try {
+        const unknown = unknownArgKeys(def, args ?? {});
+        if (unknown.length > 0) {
+            const known = Object.keys((def.inputSchema.properties ?? {}));
+            const pairs = unknown.map((k) => ({ k, s: suggestParam(k, known) }));
+            const hints = pairs.map(({ k, s }) => s ? `"${k}" — did you mean "${s}"?` : `"${k}" is not accepted`);
+            const { errorEnvelope, toMcpResult: toResult } = await import('../envelope.js');
+            return toResult(errorEnvelope({
+                code: 'VALIDATION',
+                message: `${def.name}: unknown argument${unknown.length > 1 ? 's' : ''} ` +
+                    // Avoid "?." when the last hint is a did-you-mean question.
+                    `${hints.join('; ')}${hints[hints.length - 1].endsWith('?') ? '' : '.'} ` +
+                    `Accepted: ${known.join(', ')}.`,
+                game: typeof args?.game === 'string' ? args.game : null,
+                source: def.name,
+                recover: [
+                    ...pairs.map(({ k, s }) => s ? `Rename "${k}" to "${s}" and retry` : `Remove "${k}" and retry`),
+                    `Accepted arguments: ${known.join(', ')}`,
+                ],
+            }));
+        }
         const result = await def.handler(args ?? {}, ctx);
         if (result && typeof result === 'object' && 'content' in result) {
             return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "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": {
@@ -17,7 +17,8 @@
     "build": "tsc -p tsconfig.json",
     "test": "tsx --test src/**/*.test.ts src/*.test.ts",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm test && npm run smoke",
+    "smoke": "node scripts/smoke.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0"