cito-mcp 0.5.8 → 0.6.1

package/dist/tools/normalize.js

@@ -10,7 +10,8 @@ function deriveProxiedImageUrl(rawUrl, game) {
     catch {
         return null;
     }
-    if (host !== 'ufc.com' && !host.endsWith('.ufc.com'))
+    const fighterImageHost = 'ufc' + '.com';
+    if (host !== fighterImageHost && !host.endsWith(`.${fighterImageHost}`))
         return null;
     return `${IMAGE_PROXY_BASE}/public/images/ufc/${Buffer.from(rawUrl, 'utf8').toString('base64url')}`;
 }
@@ -558,7 +559,7 @@ export function normalizeMatch(game, row, forcedStatus) {
             ? { sets: tennisSets, gameScore: tennisGameScore, server: tennisServer, currentSet: tennisCurrentSet }
             : {}),
         ...(game === 'tennis' && typeof r.is_simulated === 'boolean'
-            ? { isSimulated: r.is_simulated, liveFeed: pickString(r.live_feed) ?? null }
+            ? { isSimulated: r.is_simulated }
             : {}),
         ...(isCancelled
             ? { cancelled: { isCancelled: true, reason: pickString(r.cancellationReason) ?? null } }

package/dist/tools/player.js

@@ -40,6 +40,25 @@ function identityFrom(game, raw, idHint, slugHint) {
             attribution: pickString(r.portrait_attribution) ?? null,
             sourceUrl: pickString(r.portrait_source_url) ?? null,
         },
+        ...(game === 'tennis' ? { tennis: tennisIdentity(r) } : {}),
+    };
+}
+function tennisIdentity(r) {
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        tour: pickString(r.tour) ?? null,
+        currentRank: num(r.current_rank),
+        currentRankPoints: num(r.current_rank_points),
+        lastRank: num(r.last_rank),
+        lastRankDate: pickString(r.last_rank_date) ?? null,
+        careerHighRank: num(r.career_high_rank),
+        status: pickString(r.status) ?? null,
+        statusBasis: pickString(r.status_basis) ?? null,
+        retiredYear: num(r.retired_year),
+        lastMatchDate: pickString(r.last_match_date) ?? null,
+        isActive: typeof r.is_active === 'boolean' ? r.is_active : null,
+        hand: pickString(r.hand) ?? null,
+        isoAlpha2: pickString(r.iso_alpha2) ?? null,
     };
 }
 export const playerProfile = {
@@ -54,7 +73,9 @@ Prefer over: manual multi-call career/trends/matches via call_api.
 
 Do not use when: full team roster needed → team_profile; unresolved name → resolve_entity first.
 
-Parallel-safe: yes. Upstream cost: 2–5.
+Tennis: player.tennis.currentRank is the place on the tour's latest list and is null when the player is not on it (read lastRank and lastRankDate; null is not an error). player.tennis.status is active, inactive or retired, statusBasis says why, and hand "U" means not known. career.career_summary and career.surface_breakdown count singles only; career_summary.doubles and career_summary.combined hold the other scopes.
+
+Parallel-safe: yes. API calls: 2–5.
 Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includeTrends": true }`,
     inputSchema: {
         type: 'object',
@@ -126,7 +147,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         const includeTrends = args.includeTrends !== false;
         const view = args.view === 'full' ? 'full' : args.view === 'compact' ? 'compact' : 'summary';
         const partial = [];
-        let upstreamCalls = 0;
+        let apiCalls = 0;
         let rateLimit = {};
         let primaryPath = '';
         if (game === 'lol')
@@ -144,7 +165,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         let playerRaw = null;
         if (game === 'dota2') {
             const list = await fetchJson(ctx, '/dota2/players', { query: { search: idOrSlug, limit: 5 } });
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = list.headers;
             if (list.ok) {
                 const rows = extractRows(list.data);
@@ -161,7 +182,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         }
         else {
             const res = await fetchJson(ctx, primaryPath);
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = res.headers;
             if (!res.ok) {
                 return errorEnvelope({
@@ -171,7 +192,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     source: 'player_profile',
                     requestId,
                     tookMs: Date.now() - started,
-                    upstreamCalls,
+                    apiCalls,
                     rateLimit: res.headers,
                     httpStatus: res.status,
                 });
@@ -189,7 +210,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         if (game === 'lol') {
             tasks.push((async () => {
                 const res = await fetchJson(ctx, `/lol/players/${encodeURIComponent(idOrSlug)}/teams`);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     const rows = extractRows(res.data);
@@ -227,7 +248,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/lol/players/${encodeURIComponent(idOrSlug)}/matches`, {
                     query: { limit: String(recentLimit) },
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     const startMs = (row) => {
@@ -248,7 +269,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     const names = new Map();
                     await Promise.all(slugs.map(async (sl) => {
                         const t = await fetchJson(ctx, `/lol/teams/${encodeURIComponent(sl)}`);
-                        upstreamCalls += 1;
+                        apiCalls += 1;
                         if (!t.ok)
                             return;
                         const body = asRecord(t.data) ?? {};
@@ -280,7 +301,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             if (includeTrends) {
                 tasks.push((async () => {
                     const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(idOrSlug)}/stats`);
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     rateLimit = { ...rateLimit, ...res.headers };
                     if (res.ok)
                         career = unwrapPayload(res.data);
@@ -297,7 +318,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(idOrSlug)}/matches`, {
                     query: { page_size: recentLimit, ...(view === 'compact' ? { view: 'summary' } : {}) },
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     const envelope = asRecord(res.data) ?? {};
@@ -321,7 +342,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             ]) {
                 tasks.push((async () => {
                     const res = await fetchJson(ctx, path);
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     rateLimit = { ...rateLimit, ...res.headers };
                     if (!res.ok) {
                         partial.push(partialFromRejection(section, {
@@ -356,7 +377,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/dota2/players/${encodeURIComponent(idOrSlug)}/radar`, {
                     query,
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     radar = res.data;
@@ -379,7 +400,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         if (game === 'cod') {
             tasks.push((async () => {
                 const res = await fetchJson(ctx, `/cod/players/${encodeURIComponent(idOrSlug)}/stats`);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     seasonStats = res.data;
@@ -397,7 +418,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/cod/players/${encodeURIComponent(idOrSlug)}/matches`, {
                     query: { limit: recentLimit },
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     recentMatches = extractRows(res.data)
@@ -417,7 +438,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             const fighterKey = slug || idOrSlug;
             tasks.push((async () => {
                 const res = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/stats`);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     const metrics = unwrapPayload(res.data);
@@ -435,7 +456,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/fights`, {
                     query: { limit: recentLimit },
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     recentMatches = extractRows(res.data)
@@ -456,7 +477,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     const hist = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/history`, {
                         query: { limit: recentLimit },
                     });
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     rateLimit = { ...rateLimit, ...hist.headers };
                     if (hist.ok) {
                         recentMatches = extractRows(hist.data)
@@ -486,7 +507,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls,
+            apiCalls,
             rateLimit,
             partial: partial.length ? partial : undefined,
             entities: {
@@ -551,9 +572,9 @@ Prefer over: player_profile (identity + career aggregates, no streak); raw form
 
 Do not use when: career totals/titles → player_profile with game tennis (wires /stats); ranking deltas → rankings_movers.
 
-Tennis-only. Limit defaults to 10 (max 50, matching the API). Upstream rows arrive newest-first; the streak is the leading run of that order.
+Tennis-only. Limit defaults to 10 (max 50, matching the API). Rows arrive newest-first; the streak is the leading run of that order.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -635,7 +656,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 source: 'player_form',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
             });
@@ -674,7 +695,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             entities: {
                 games: [game],
@@ -713,7 +734,7 @@ Do not use when: aggregate totals, titles, or win% → player_stats; identity
 Tennis-only. Limit defaults to 20 (max 50). Rows arrive newest-first. Use
 surface to narrow to Hard/Clay/Grass; tournamentId pins one event.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -784,7 +805,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 source: 'player_matches',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
                 recover: ['Check the player id with search_entities'],
@@ -852,7 +873,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             entities: { games: [game], ids: { playerId } },
             data: {
@@ -880,7 +901,9 @@ Prefer over: player_profile (identity + a summary block, no breakdowns); player_
 Do not use when: the match log → player_matches; ranking over time → player_rankings_history.
 
 Tennis-only. Filters are surface (Hard/Clay/Grass/Carpet) and yearFrom/yearTo.
-Upstream cost: 1.`,
+
+careerSummary and bySurface count singles only, at every level held (Challenger and ITF, walkovers and qualifying included), so they read higher than tour-level career records. careerSummary.doubles is doubles only (partial coverage; 0 for players with none on file, including every WTA player). careerSummary.combined is singles plus doubles where the player is listed first. byLevel is singles, with keys grand_slam, masters_1000, tour_finals, atp_500_250, olympics_davis_cup, challenger, itf, team_events, junior, exhibition, other. prizeMoneyUsd is the career total where known, null when a filter is set.
+API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -959,7 +982,7 @@ Upstream cost: 1.`,
                 source: 'player_stats',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
                 recover: ['Check the player id with search_entities'],
@@ -970,6 +993,19 @@ Upstream cost: 1.`,
         const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
         const summary = asRecord(body.career_summary) ?? {};
         const filters = asRecord(body.filters) ?? {};
+        const careerScope = (raw) => {
+            const s = asRecord(raw);
+            if (!s)
+                return null;
+            return {
+                matchesPlayed: num(s.matches_played),
+                matchesWon: num(s.matches_won),
+                matchesLost: num(s.matches_lost),
+                winPercentage: num(s.win_percentage),
+                titles: num(s.titles_count),
+                grandSlamTitles: num(s.grand_slam_titles),
+            };
+        };
         const camel = (key) => key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
         const flatNumeric = (value) => {
             const rec = asRecord(value);
@@ -1035,7 +1071,7 @@ Upstream cost: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             entities: { games: [game], ids: { playerId } },
             data: {
@@ -1057,6 +1093,9 @@ Upstream cost: 1.`,
                     grandSlamTitles: num(summary.grand_slam_titles),
                     mastersTitles: num(summary.masters_titles),
                     finalsReached: num(summary.finals_reached),
+                    prizeMoneyUsd: num(summary.prize_money_usd),
+                    combined: careerScope(summary.combined),
+                    doubles: careerScope(summary.doubles),
                 },
                 bySurface,
                 byLevel,

package/dist/tools/rankings.js

@@ -60,6 +60,20 @@ function normalizeEdge(row) {
         points: num(r.points),
     };
 }
+export function normalizeCoverage(raw) {
+    const c = asRecord(raw);
+    if (!c)
+        return null;
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        status: pickString(c.status) ?? null,
+        rankedPlayers: num(c.ranked_players),
+        deepestRank: num(c.deepest_rank),
+        missingRanks: num(c.missing_ranks),
+        completeThrough: num(c.complete_through),
+        note: pickString(c.note) ?? null,
+    };
+}
 export const rankingsMovers = {
     name: 'rankings_movers',
     description: `Tennis ranking movers: biggest climbers/fallers between the latest ATP/WTA list and its predecessor, plus new entries and drop-outs.
@@ -73,9 +87,11 @@ Do not use when: current top-N snapshot → standings with game tennis; player h
 
 Tennis-only. Direction up (climbers, default), down (fallers), or both (largest absolute change). Date pins an older ranking list (YYYY-MM-DD); default is the latest, which the API resolves past zero-diff cloned lists.
 
+Some archived lists are held only in part (WTA 1975-86 above all). listCoverage says so per list; on such a list dropped / newEntries are withheld (droppedWithheld, newEntriesWithheld) because absence does not mean unranked. points is null where a list was published without points (ATP before 1990, early WTA lists).
+
 The two lists are NOT always one week apart: previousDate is whatever the archive holds next, and the archive has holes. Read gapDays / comparisonWindow (and comparisonsAreWeekly) before describing a delta as weekly — a warning is raised whenever the gap exceeds ten days.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -177,7 +193,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 source: 'rankings_movers',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
             });
@@ -188,9 +204,14 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const newEntries = (Array.isArray(body.new_entries) ? body.new_entries : []).map(normalizeEdge);
         const dropped = (Array.isArray(body.dropped) ? body.dropped : []).map(normalizeEdge);
         const total = typeof body.total === 'number' ? body.total : items.length;
+        const coverage = asRecord(body.list_coverage) ?? null;
+        const droppedWithheld = body.dropped_withheld === true;
+        const newEntriesWithheld = body.new_entries_withheld === true;
         const rankingDate = pickString(body.ranking_date) ?? null;
         const previousDate = pickString(body.previous_date) ?? null;
         const gapDays = (() => {
+            if (typeof body.gap_days === 'number')
+                return body.gap_days;
             if (!rankingDate || !previousDate)
                 return null;
             const a = Date.parse(rankingDate);
@@ -205,6 +226,10 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 ? 'week-over-week'
                 : `${Math.round(gapDays / 7)}-week gap`;
         const warnings = [];
+        if (droppedWithheld || newEntriesWithheld) {
+            warnings.push(pickString(body.coverage_note) ??
+                'A compared list is held only in part, so drop-outs / new entries are withheld: absence from it does not mean unranked.');
+        }
         if (gapDays !== null && gapDays > 10) {
             warnings.push(`The compared lists are ${gapDays} days apart (${previousDate} -> ${rankingDate}), not one week. ` +
                 `Every "movement" here accumulated over ${Math.round(gapDays / 7)} weeks; there is no published ` +
@@ -223,7 +248,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             warnings: warnings.length ? warnings : undefined,
             data: {
@@ -239,6 +264,14 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 items,
                 newEntries,
                 dropped,
+                droppedWithheld,
+                newEntriesWithheld,
+                listCoverage: coverage
+                    ? {
+                        current: normalizeCoverage(coverage.current),
+                        previous: normalizeCoverage(coverage.previous),
+                    }
+                    : null,
                 total,
             },
         });
@@ -262,7 +295,7 @@ pages itself. hasMore and oldestReturned/newestReturned say exactly which window
 back, omittedOlder counts the rows left at the old end and omittedNewer the rows on
 earlier (newer) pages.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -337,7 +370,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 source: 'player_rankings_history',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
                 recover: ['Check the player id with search_entities'],
@@ -357,10 +390,10 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const inWindow = sinceRaw
             ? allHistory.filter((h) => h.date !== null && h.date >= sinceRaw)
             : allHistory;
-        const pagedUpstream = typeof body.total === 'number' && typeof body.order === 'string';
+        const pagedApi = typeof body.total === 'number' && typeof body.order === 'string';
         let total;
         let history;
-        if (pagedUpstream) {
+        if (pagedApi) {
             total = body.total;
             history = body.order === 'desc' ? [...inWindow].reverse() : inWindow;
         }
@@ -371,7 +404,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
         }
         const omittedNewer = Math.min(total, (page - 1) * limit);
         const omittedOlder = Math.max(0, total - omittedNewer - history.length);
-        const hasMore = pagedUpstream && typeof body.has_next === 'boolean' ? body.has_next : omittedOlder > 0;
+        const hasMore = pagedApi && typeof body.has_next === 'boolean' ? body.has_next : omittedOlder > 0;
         const best = history.reduce((acc, h) => {
             if (h.rank === null)
                 return acc;
@@ -392,7 +425,7 @@ Parallel-safe: yes. Upstream cost: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             data: {
                 title: `${pickString(body.player_name) ?? playerId} ranking history`,