cito-mcp 0.2.5 → 0.2.7

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.
@@ -36,33 +38,39 @@ Composites multi-fetch server-side, return a **stable JSON envelope**, and isola
 
 ## Install
 
-### One-liner (published package)
+### One command (recommended)
 
 ```bash
-npx cito-mcp
+npx cito-mcp install --key cito_your_key_here
 ```
 
-Requires `CITO_API_KEY` in the environment (see [Environment](#environment)). Most hosts inject env via their MCP config rather than a bare shell.
+Detects the MCP clients installed on your machine — Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI — and writes the config for each. Then restart your editor.
 
-### Claude Code
+It is safe to re-run: existing config is merged, not replaced, your other MCP servers are left alone, a `.cito-bak` backup is written before the first change, and running it again just rotates the key rather than adding a second entry.
 
 ```bash
-claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- npx cito-mcp
+npx cito-mcp install --dry-run                     # show the plan, write nothing
+npx cito-mcp install --key … --client cursor       # one client only
+npx cito-mcp install --help
 ```
 
-Windows — if `npx` fails under Claude:
+Get a key at [citoapi.com/dashboard](https://citoapi.com/dashboard).
+
+### Manual — Claude Code
 
 ```bash
-claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- cmd /c npx cito-mcp
+claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" npx -y cito-mcp
 ```
 
+**Quote the `--`.** PowerShell 5.1 strips a bare `--` before the CLI sees it; because `-e` takes a variable number of values it then swallows `npx -y cito-mcp` as env vars and fails with `unknown option '-y'`. The quoted form works in PowerShell, cmd, bash and zsh alike. `npx cito-mcp install` avoids the problem entirely.
+
 From a local clone (development):
 
 ```bash
 cd mcp
 npm install
 npm run build
-claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- node "%CD%\dist\index.js"
+claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" node "%CD%\dist\index.js"
 ```
 
 ### Cursor
@@ -124,7 +132,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 +140,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 +159,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 |
@@ -429,13 +466,20 @@ Package: **`cito-mcp@0.2.4`**
    - `live_matches`
    - `resolve_entity` (e.g. T1 / s1mple)
    - `match_summary` with a real `matchId` from live/schedule
-4. Confirm `package.json` version and README match the shipped tool list (15).
+4. Confirm `package.json` version and README match the shipped tool list.
 5. `npm publish` from `mcp/` (or your release pipeline) with appropriate npm auth / access.
+   `prepublishOnly` runs build + tests + smoke, so a broken build cannot ship.
 
 ### Install line for docs & marketing
 
 ```bash
-claude mcp add cito -e CITO_API_KEY=cito_… -- npx cito-mcp
+npx cito-mcp install --key cito_…
+```
+
+Manual fallback (note the quoted `--`, required for PowerShell):
+
+```bash
+claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 ```
 
 ```json

package/dist/index.js

@@ -19,6 +19,18 @@ import { SERVER_INSTRUCTIONS } from './instructions.js';
 import { allTools, getTool } from './tools/index.js';
 import { runTool } from './tools/types.js';
 import { PACKAGE_VERSION } from './version.js';
+/**
+ * Subcommands run and exit before any transport exists.
+ *
+ * `install` writes editor config and prints to stdout, which would corrupt the
+ * JSON-RPC channel if it ran alongside the server — hence the early return.
+ * Handled here rather than in a second binary so the documented entry point
+ * stays `npx cito-mcp`.
+ */
+if (process.argv[2] === 'install') {
+    const { runInstall } = await import('./install.js');
+    process.exit(await runInstall(process.argv.slice(3)));
+}
 const API_KEY = process.env.CITO_API_KEY;
 /**
  * Tools that need no API key. These must keep working with the server

package/dist/install.js

@@ -0,0 +1,340 @@
+/**
+ * `npx cito-mcp install` — write the server config for whichever MCP clients
+ * are actually installed.
+ *
+ * Why this exists: the documented one-liner
+ *
+ *   claude mcp add cito -e CITO_API_KEY=… -- npx -y cito-mcp
+ *
+ * is broken in PowerShell 5.1, which strips the bare `--`. Because `-e` is a
+ * variadic option, it then swallows `npx -y cito-mcp` as extra env values and
+ * the CLI dies on "unknown option '-y'". Quoting the separator fixes it, but
+ * expecting every Windows user to know that is not onboarding — it is a trap.
+ * A subcommand has no separator to mangle and works identically everywhere.
+ *
+ * Rules this follows, because it edits files the user did not open:
+ *  - only touch clients that are already installed
+ *  - back up before the first write of a run
+ *  - merge into existing config; never rewrite a file wholesale
+ *  - idempotent: re-running replaces our entry and nothing else
+ *  - --dry-run prints the plan and writes nothing
+ *  - never print the full API key
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { PACKAGE_VERSION } from './version.js';
+const SERVER_NAME = 'cito';
+function envHome(name, fallback) {
+    const v = process.env[name];
+    return v && v.trim() ? v : fallback;
+}
+function clientsFor() {
+    const home = homedir();
+    const os = platform();
+    const appData = envHome('APPDATA', join(home, 'AppData', 'Roaming'));
+    const desktopConfig = os === 'win32'
+        ? join(appData, 'Claude', 'claude_desktop_config.json')
+        : os === 'darwin'
+            ? join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+            : join(home, '.config', 'Claude', 'claude_desktop_config.json');
+    return [
+        {
+            id: 'claude-code',
+            label: 'Claude Code',
+            configPath: join(home, '.claude.json'),
+            detectPath: join(home, '.claude.json'),
+            format: 'json-mcpServers',
+        },
+        {
+            id: 'claude-desktop',
+            label: 'Claude Desktop',
+            configPath: desktopConfig,
+            detectPath: dirname(desktopConfig),
+            format: 'json-mcpServers',
+        },
+        {
+            id: 'cursor',
+            label: 'Cursor',
+            configPath: join(home, '.cursor', 'mcp.json'),
+            detectPath: join(home, '.cursor'),
+            format: 'json-mcpServers',
+        },
+        {
+            id: 'windsurf',
+            label: 'Windsurf',
+            configPath: join(home, '.codeium', 'windsurf', 'mcp_config.json'),
+            detectPath: join(home, '.codeium', 'windsurf'),
+            format: 'json-mcpServers',
+        },
+        {
+            id: 'codex',
+            label: 'Codex CLI',
+            configPath: join(home, '.codex', 'config.toml'),
+            detectPath: join(home, '.codex'),
+            format: 'toml-mcp_servers',
+        },
+    ];
+}
+export function maskKey(key) {
+    if (key.length <= 12)
+        return '****';
+    return `${key.slice(0, 9)}…${key.slice(-4)}`;
+}
+/** The stdio entry every JSON-based client understands. */
+function serverEntry(key, base) {
+    return {
+        type: 'stdio',
+        command: 'npx',
+        args: ['-y', 'cito-mcp'],
+        env: { CITO_API_KEY: key, ...(base ? { CITO_API_BASE: base } : {}) },
+    };
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8').trim();
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Escape a TOML basic string. Only the characters TOML actually requires —
+ * an API key with a quote or backslash would otherwise produce a file the
+ * client cannot parse.
+ */
+function tomlString(v) {
+    return `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function tomlBlock(key, base) {
+    const envLines = [`CITO_API_KEY = ${tomlString(key)}`]
+        .concat(base ? [`CITO_API_BASE = ${tomlString(base)}`] : [])
+        .join('\n');
+    return [
+        `[mcp_servers.${SERVER_NAME}]`,
+        `command = "npx"`,
+        `args = ["-y", "cito-mcp"]`,
+        ``,
+        `[mcp_servers.${SERVER_NAME}.env]`,
+        envLines,
+        ``,
+    ].join('\n');
+}
+/**
+ * Replace an existing [mcp_servers.cito] block (and its .env subtable) or
+ * append a new one. Deliberately conservative: it only recognises the exact
+ * headers it writes, so a hand-edited file is appended to rather than mangled.
+ */
+export function upsertTomlBlock(existing, key, base) {
+    const block = tomlBlock(key, base);
+    const header = new RegExp(`^\\[mcp_servers\\.${SERVER_NAME}(\\.[A-Za-z_]+)?\\]\\s*$`);
+    const anyHeader = /^\[[^\]]+\]\s*$/;
+    const lines = existing.split(/\r?\n/);
+    const kept = [];
+    let skipping = false;
+    for (const line of lines) {
+        if (header.test(line)) {
+            skipping = true;
+            continue;
+        }
+        if (skipping && anyHeader.test(line))
+            skipping = false;
+        if (!skipping)
+            kept.push(line);
+    }
+    const body = kept.join('\n').replace(/\n{3,}$/, '\n\n').replace(/\s*$/, '');
+    return (body ? `${body}\n\n` : '') + block;
+}
+/**
+ * Claude Code owns the schema of ~/.claude.json and stores far more than MCP
+ * config in it, so let its own CLI do the write when it is on PATH. Direct
+ * editing is the fallback, not the default.
+ */
+function tryClaudeCli(key, base, dryRun) {
+    const json = JSON.stringify(serverEntry(key, base));
+    // On Windows `claude` is a .cmd shim, which execFileSync cannot spawn
+    // directly — it needs a shell. Quoting matters there because the JSON
+    // payload contains spaces and double quotes.
+    const isWin = platform() === 'win32';
+    const run = (args) => {
+        if (!isWin) {
+            execFileSync('claude', args, { stdio: 'ignore' });
+            return;
+        }
+        execFileSync('cmd', ['/c', 'claude', ...args], { stdio: 'ignore' });
+    };
+    try {
+        if (dryRun) {
+            run(['--version']);
+            return 'would use `claude mcp add-json` (CLI detected)';
+        }
+        run(['mcp', 'add-json', SERVER_NAME, json, '-s', 'user']);
+        return 'via `claude mcp add-json` (user scope)';
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonClient(c, key, base, dryRun) {
+    const current = readJson(c.configPath);
+    if (current === null && existsSync(c.configPath)) {
+        return {
+            client: c,
+            status: 'failed',
+            note: `${c.configPath} is not valid JSON — left untouched`,
+        };
+    }
+    const config = current ?? {};
+    const servers = (config.mcpServers ?? {});
+    const existed = Object.prototype.hasOwnProperty.call(servers, SERVER_NAME);
+    const next = { ...config, mcpServers: { ...servers, [SERVER_NAME]: serverEntry(key, base) } };
+    if (dryRun) {
+        return {
+            client: c,
+            status: 'planned',
+            note: `${existed ? 'replace' : 'add'} "${SERVER_NAME}" in ${c.configPath}`,
+        };
+    }
+    mkdirSync(dirname(c.configPath), { recursive: true });
+    if (existsSync(c.configPath))
+        copyFileSync(c.configPath, `${c.configPath}.cito-bak`);
+    writeFileSync(c.configPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    return {
+        client: c,
+        status: 'written',
+        note: `${existed ? 'updated' : 'added'} in ${c.configPath}`,
+    };
+}
+function writeTomlClient(c, key, base, dryRun) {
+    const existing = existsSync(c.configPath) ? readFileSync(c.configPath, 'utf8') : '';
+    const existed = new RegExp(`\\[mcp_servers\\.${SERVER_NAME}\\]`).test(existing);
+    if (dryRun) {
+        return {
+            client: c,
+            status: 'planned',
+            note: `${existed ? 'replace' : 'add'} [mcp_servers.${SERVER_NAME}] in ${c.configPath}`,
+        };
+    }
+    mkdirSync(dirname(c.configPath), { recursive: true });
+    if (existsSync(c.configPath))
+        copyFileSync(c.configPath, `${c.configPath}.cito-bak`);
+    writeFileSync(c.configPath, upsertTomlBlock(existing, key, base), 'utf8');
+    return {
+        client: c,
+        status: 'written',
+        note: `${existed ? 'updated' : 'added'} in ${c.configPath}`,
+    };
+}
+function parseArgs(argv) {
+    const out = { key: undefined, base: undefined, only: [], dryRun: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const eat = () => argv[++i];
+        if (a === '--help' || a === '-h')
+            out.help = true;
+        else if (a === '--dry-run' || a === '-n')
+            out.dryRun = true;
+        else if (a === '--key')
+            out.key = eat();
+        else if (a?.startsWith('--key='))
+            out.key = a.slice(6);
+        else if (a === '--base')
+            out.base = eat();
+        else if (a?.startsWith('--base='))
+            out.base = a.slice(7);
+        else if (a === '--client')
+            out.only.push(...(eat() ?? '').split(',').filter(Boolean));
+        else if (a?.startsWith('--client='))
+            out.only.push(...a.slice(9).split(',').filter(Boolean));
+    }
+    return out;
+}
+const HELP = `cito-mcp install — configure the Cito MCP server for your editors
+
+Usage:
+  npx cito-mcp install --key cito_xxx
+  npx cito-mcp install --key cito_xxx --client cursor,claude-code
+  npx cito-mcp install --dry-run
+
+Options:
+  --key <key>       Cito API key. Falls back to $CITO_API_KEY.
+  --client <ids>    Comma-separated: claude-code, claude-desktop, cursor, windsurf, codex.
+                    Default: every client detected on this machine.
+  --base <url>      Override API base (staging / self-hosted).
+  --dry-run, -n     Show what would change; write nothing.
+  --help, -h        This message.
+
+Get a key at https://citoapi.com/dashboard`;
+export async function runInstall(argv) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        console.log(HELP);
+        return 0;
+    }
+    const key = args.key ?? process.env.CITO_API_KEY;
+    if (!key && !args.dryRun) {
+        console.error('No API key. Pass --key cito_xxx or set CITO_API_KEY.\n');
+        console.error('Get one at https://citoapi.com/dashboard');
+        return 1;
+    }
+    const all = clientsFor();
+    const unknown = args.only.filter((id) => !all.some((c) => c.id === id));
+    if (unknown.length) {
+        console.error(`Unknown client(s): ${unknown.join(', ')}`);
+        console.error(`Valid: ${all.map((c) => c.id).join(', ')}`);
+        return 1;
+    }
+    // An explicit --client is a instruction, not a guess: honour it even if we
+    // cannot detect the client (fresh install, portable install, unusual path).
+    const selected = args.only.length
+        ? all.filter((c) => args.only.includes(c.id))
+        : all.filter((c) => existsSync(c.detectPath));
+    if (selected.length === 0) {
+        console.error('No supported MCP clients detected.');
+        console.error(`Looked for: ${all.map((c) => c.label).join(', ')}`);
+        console.error('Use --client <id> to configure one anyway.');
+        return 1;
+    }
+    console.log(`cito-mcp ${PACKAGE_VERSION} installer`);
+    console.log(key ? `key: ${maskKey(key)}` : 'key: (none — dry run)');
+    console.log(args.dryRun ? 'mode: dry run, nothing will be written\n' : '');
+    const effectiveKey = key ?? 'CITO_API_KEY';
+    const results = [];
+    for (const c of selected) {
+        if (c.id === 'claude-code') {
+            const viaCli = tryClaudeCli(effectiveKey, args.base, args.dryRun);
+            if (viaCli) {
+                results.push({ client: c, status: args.dryRun ? 'planned' : 'written', note: viaCli });
+                continue;
+            }
+        }
+        results.push(c.format === 'toml-mcp_servers'
+            ? writeTomlClient(c, effectiveKey, args.base, args.dryRun)
+            : writeJsonClient(c, effectiveKey, args.base, args.dryRun));
+    }
+    for (const r of results) {
+        const mark = r.status === 'failed' ? '✗' : r.status === 'skipped' ? '–' : '✓';
+        console.log(`  ${mark} ${r.client.label.padEnd(16)} ${r.note}`);
+    }
+    const failed = results.filter((r) => r.status === 'failed');
+    console.log('');
+    if (args.dryRun) {
+        console.log('Dry run complete. Re-run without --dry-run to apply.');
+    }
+    else {
+        console.log('Restart your editor to load the server, then ask it:');
+        console.log('  "what UFC events are coming up?"');
+    }
+    if (failed.length) {
+        console.log(`\n${failed.length} client(s) could not be configured (see above).`);
+        return 1;
+    }
+    return 0;
+}

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.7",
   "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"