cito-mcp 0.2.6 → 0.3.0

package/dist/install.js

@@ -0,0 +1,348 @@
+/**
+ * `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',
+        },
+        {
+            id: 'grok',
+            label: 'Grok CLI',
+            configPath: join(home, '.grok', 'config.toml'),
+            detectPath: join(home, '.grok'),
+            // Same [mcp_servers.x] / [mcp_servers.x.env] layout as 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, grok.
+                    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/instructions.js

@@ -16,7 +16,7 @@ You are connected to Cito esports data (read-only). Prefer curated outcome tools
 
 ## Game parameter
 
-game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | all
+game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | tennis | all
 
 - Default when the user named one title: that game. Default for "what's live?" / multi-title: omit game or all on tools that accept it.
 - On UNSUPPORTED_GAME / 403 for a title: stop retrying that game; call api_health; report plan gaps.

package/dist/tools/live.js

@@ -11,6 +11,7 @@ const LIVE_PATHS = {
     dota2: '/dota2/matches/live',
     cod: '/cod/matches/live',
     ufc: '/ufc/live',
+    tennis: '/tennis/matches/live',
 };
 /**
  * Extract live match/bout rows. UFC /ufc/live returns
@@ -502,6 +503,22 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
             if (tournamentId)
                 noteIgnored('tournamentId', 'pass event slug via event_card instead');
         }
+        else if (game === 'tennis') {
+            // Tennis has no upcoming-fixtures endpoint; the archive is results-only.
+            return errorEnvelope({
+                code: 'UNSUPPORTED_GAME',
+                message: 'Tennis has no upcoming-fixtures feed. Live matches: live_matches { game: "tennis" }. Recent results: call_api GET /tennis/matches/recent. Season calendar: call_api GET /tennis/tournaments/calendar?year=YYYY.',
+                game,
+                source: 'upcoming_schedule',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use live_matches with game "tennis" for in-progress matches',
+                    'Use call_api GET /tennis/matches/recent for latest results',
+                    'Use call_api GET /tennis/tournaments/calendar?year=YYYY for the season schedule',
+                ],
+            });
+        }
         const res = await fetchJson(ctx, path, { query });
         if (!res.ok) {
             return errorEnvelope({

package/dist/tools/match.js

@@ -99,22 +99,24 @@ function primaryPath(game, matchId) {
             return `/cod/matches/${encodeURIComponent(matchId)}`;
         case 'ufc':
             return `/ufc/bouts/${encodeURIComponent(matchId)}`;
+        case 'tennis':
+            return `/tennis/matches/${encodeURIComponent(matchId)}`;
     }
 }
 export const matchSummary = {
     name: 'match_summary',
-    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
-
-When to use:
-- Match recap / default match UI
-- After user selects a live or completed matchId
-
-Prefer over match_details for chat answers and default UIs.
-Prefer match_details for timelines, full map trees, live state, advanced packages.
-
-Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
-
-Parallel-safe: yes. Upstream cost: 2–5.
+    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
+
+When to use:
+- Match recap / default match UI
+- After user selects a live or completed matchId
+
+Prefer over match_details for chat answers and default UIs.
+Prefer match_details for timelines, full map trees, live state, advanced packages.
+
+Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
+
+Parallel-safe: yes. Upstream cost: 2–5.
 Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includePlayerStats": true }`,
     inputSchema: {
         type: 'object',
@@ -204,6 +206,8 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
                     paths.push(`/cod/matches/${encodeURIComponent(matchId)}/player-stats`);
                 if (game === 'ufc')
                     paths.push(`/ufc/bouts/${encodeURIComponent(matchId)}/stats`);
+                if (game === 'tennis')
+                    paths.push(`/tennis/matches/${encodeURIComponent(matchId)}/stats`);
                 for (const p of paths) {
                     const res = await getSection(ctx, p);
                     upstreamCalls += 1;
@@ -298,22 +302,22 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
 };
 export const matchDetails = {
     name: 'match_details',
-    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
-
-When to use:
-- Analyst deep dive
-- Live in-game window (LoL/CS2/UFC)
-- Full demo list
-
-Prefer over match_summary only when summary is insufficient.
-Prefer match_summary for short answers and default cards.
-
-Do not use when: first-pass live board (use live_matches + match_summary).
-
-Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
-If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
-
-Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
+    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
+
+When to use:
+- Analyst deep dive
+- Live in-game window (LoL/CS2/UFC)
+- Full demo list
+
+Prefer over match_summary only when summary is insufficient.
+Prefer match_summary for short answers and default cards.
+
+Do not use when: first-pass live board (use live_matches + match_summary).
+
+Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
+If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
+
+Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
 Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "includeLiveState": false }`,
     inputSchema: {
         type: 'object',

package/dist/tools/meta.js

@@ -480,6 +480,7 @@ const ALLOWLIST_PREFIXES = [
     '/cod',
     '/ufc',
     '/fortnite',
+    '/tennis',
     // The spec describes the surface call_api is allowed to reach; refusing to
     // serve it left route discovery impossible except by guessing.
     '/openapi.json',
@@ -505,7 +506,7 @@ Prefer curated tools for all standard jobs (live, schedule, profiles, standings,
 
 Do not use when: a curated tool covers the outcome. Avoid parallel storms; same plan rate limits apply.
 
-Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite.
+Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /tennis.
 Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
 
 Parallel-safe: yes but discouraged in bulk. Upstream cost: 1.
@@ -566,7 +567,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
                 source: 'call_api',
                 requestId,
                 tookMs: Date.now() - started,
-                hint: 'Use prefixes /health /lol /cs2 /dota2 /cod /ufc /fortnite',
+                hint: 'Use prefixes /health /lol /cs2 /dota2 /cod /ufc /fortnite /tennis',
             });
         }
         let query = {};
@@ -646,6 +647,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
  * explicitly rather than returning an empty list that reads as a verdict.
  */
 const SPEC_OMITS = {
+    tennis: 'The published OpenAPI spec documents no /tennis paths, but tennis routes exist and work (players, matches, h2h, rankings, tournaments, live). Use the curated tools with game tennis, or call_api with /tennis/* paths.',
     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 = {

package/dist/tools/normalize.js

@@ -154,7 +154,7 @@ function scoreNum(v) {
 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';
+    const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.fightMetricId, r.ufcFightId, r.live_match_id) ?? 'unknown';
     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, game) ??
@@ -171,6 +171,24 @@ export function normalizeMatch(game, row, forcedStatus) {
         if (s != null)
             team2 = { ...team2, score: s };
     }
+    // Tennis: live rows carry player1_name/player2_name; archive rows only carry
+    // winner_id/loser_id (ids, no names). Map both onto sides so labels are never "? vs ?".
+    if (game === 'tennis' && !team1 && !team2) {
+        const p1 = pickString(r.player1_name);
+        const p2 = pickString(r.player2_name);
+        if (p1 || p2) {
+            team1 = sideFrom(p1, pickString(r.player1_id), undefined, undefined);
+            team2 = sideFrom(p2, pickString(r.player2_id), undefined, undefined);
+        }
+        else {
+            const w = pickString(r.winner_id);
+            const l = pickString(r.loser_id);
+            if (w || l) {
+                team1 = sideFrom(w, w, undefined, undefined);
+                team2 = sideFrom(l, l, undefined, undefined);
+            }
+        }
+    }
     // UFC / live corners: red/blue objects, corner arrays, or fighters[] with corner field.
     // Public API serializeBout uses fighters:[{ corner, fighterName, fighterSlug, profile:{name,slug} }].
     // Live tracking uses red/blue + fighters[] (not team1/team2).
@@ -373,12 +391,12 @@ export function sortByCardOrder(rows) {
 }
 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) ??
+    const id = pickString(r.id, r.teamId, r.playerId, r.player_id, r.lolPlayerId, r.codPlayerId, r.matchId, r.boutId, r.eventId, r.tournamentId, r.leagueId) ??
         pickString(r.slug) ??
         'unknown';
     const slug = pickString(r.slug, r.orgSlug, r.teamSlug);
     // Events often use `title` not `name` (UFC)
-    const name = pickString(r.name, r.title, r.nickname, r.displayName, r.tag, r.code, slug, id) ?? id;
+    const name = pickString(r.name, r.full_name, r.player_name, r.title, r.nickname, r.displayName, r.tag, r.code, slug, id) ?? id;
     const nickname = pickString(r.nickname, asRecord(r.profile)?.nickname);
     return {
         game,

package/dist/tools/player.js

@@ -9,7 +9,7 @@ function identityFrom(game, raw, idHint, slugHint) {
     const r = asRecord(raw) ?? {};
     const id = pickString(r.id, r.playerId, r.lolPlayerId, r.codPlayerId, idHint, slugHint) ?? 'unknown';
     const slug = pickString(r.slug, slugHint);
-    const name = pickString(r.name, r.nickname, r.displayName, r.tag, slug, id) ?? id;
+    const name = pickString(r.name, r.full_name, r.nickname, r.displayName, r.tag, slug, id) ?? id;
     const team = asRecord(r.team) ??
         asRecord(r.currentTeam) ??
         (r.teamName || r.orgSlug
@@ -146,6 +146,8 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             primaryPath = `/cod/players/${encodeURIComponent(idOrSlug)}`;
         else if (game === 'ufc')
             primaryPath = `/ufc/fighters/${encodeURIComponent(slug || idOrSlug)}`;
+        else if (game === 'tennis')
+            primaryPath = `/tennis/players/${encodeURIComponent(idOrSlug)}`;
         let playerRaw = null;
         if (game === 'dota2') {
             // Prefer radar as primary signal; try list filter
@@ -218,6 +220,43 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 }
             })());
         }
+        if (game === 'tennis') {
+            if (includeTrends) {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(idOrSlug)}/stats`);
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...res.headers };
+                    if (res.ok)
+                        career = unwrapPayload(res.data);
+                    else {
+                        partial.push(partialFromRejection('career', {
+                            code: mapHttpToCode(res.status),
+                            message: `player stats HTTP ${res.status}`,
+                            httpStatus: res.status,
+                        }));
+                    }
+                })());
+            }
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(idOrSlug)}/matches`, {
+                    query: { page_size: recentLimit },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    const envelope = asRecord(res.data) ?? {};
+                    const data = asRecord(envelope.data) ?? envelope;
+                    recentMatches = extractRows(data.items ?? data).slice(0, recentLimit);
+                }
+                else {
+                    partial.push(partialFromRejection('recentMatches', {
+                        code: mapHttpToCode(res.status),
+                        message: `player matches HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+        }
         if (game === 'cs2' && includeTrends) {
             for (const [section, path] of [
                 ['career', `/cs2/players/${encodeURIComponent(idOrSlug)}/career`],