cito-mcp 0.3.18 → 0.3.20

package/README.md

@@ -2,9 +2,9 @@
 
 Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports API](https://api.citoapi.com) — **curated outcome tools** for agents building esports apps, dashboards, bots, and research flows.
 
-**Version:** `0.2.4` · **Node:** `>=20` · **Install:** `npx cito-mcp`
+**Version:** `0.3.20` · **Node:** `>=20` · **Install:** `npx cito-mcp`
 
-Primary games: **lol · cs2 · dota2 · cod · ufc**. Fortnite and long-tail REST stay available via `call_api`.
+Primary games & sports: **lol · cs2 · dota2 · cod · ufc · tennis**. Long-tail REST stays available via `call_api`.
 
 ---
 
@@ -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 16 hand-authored tools** that answer *jobs* instead of mirroring REST:
+**v0.3 ships 18 hand-authored tools** that answer *jobs* instead of mirroring REST:
 
 | Job | Tool |
 | --- | --- |
@@ -21,9 +21,11 @@ v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among t
 | Build a match card / recap | `match_summary` |
 | Deep timeline / live state | `match_details` |
 | Team page | `team_profile` |
-| Player / fighter form | `player_profile` |
+| Player / fighter profile | `player_profile` |
+| Player form & win streak | `player_form` |
 | Table / rankings | `standings` |
-| Pre-match briefing | `match_preview` |
+| Ranking climbers & droppers | `rankings_movers` |
+| Pre-match briefing (with surface) | `match_preview` |
 | Event / fight-night card | `event_card` |
 | Rivalry record | `head_to_head` |
 | Fighter / team photos | `event_card` · `player_profile` |

package/dist/tools/index.js

@@ -5,8 +5,9 @@ import { matchTools } from './match.js';
 import { playerTools } from './player.js';
 import { teamTools } from './team.js';
 import { standingsTools } from './standings.js';
+import { rankingsTools } from './rankings.js';
 import { insightTools } from './insight.js';
-/** Curated outcome-tool catalog (16 tools). Order matches preferred cold-start ladder. */
+/** Curated outcome-tool catalog (17 tools). Order matches preferred cold-start ladder. */
 export const allTools = [
     ...metaTools.filter((t) => t.name === 'list_capabilities' || t.name === 'api_health'),
     ...resolveTools,
@@ -15,6 +16,7 @@ export const allTools = [
     ...playerTools,
     ...teamTools,
     ...standingsTools,
+    ...rankingsTools,
     ...insightTools,
     // Escape-hatch pair last: discover routes, then call one.
     ...metaTools.filter((t) => t.name === 'list_routes' || t.name === 'call_api'),

package/dist/tools/insight.js

@@ -291,6 +291,7 @@ Prefer match_summary when match is completed; match_details for live in-game.
 Do not use when: user wants final score/recap of a finished match.
 
 Parallel-safe: yes. Upstream cost: 4–8.
+Tennis H2H accepts an optional surface filter (Hard, Clay, Grass).
 Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "recentLimit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -305,6 +306,7 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
             includeH2H: boolSchema('Include composed H2H stub.', true),
             includeRosters: boolSchema('Include roster snippets when available.', true),
             recentLimit: limitSchema({ default: 5, max: 15, description: 'Form window per side (default 5, max 15).' }),
+            surface: stringSchema('Optional tennis H2H surface filter: Hard, Clay, or Grass. Ignored for other games.', 'Clay'),
         },
     },
     handler: async (args, ctx) => {
@@ -329,6 +331,26 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
         const includeH2H = args.includeH2H !== false;
         const includeRosters = args.includeRosters !== false;
         const recentLimit = clampInt(args.recentLimit, 5, 1, 15);
+        // Optional tennis H2H surface filter (TENNIS-04 follow-through: the
+        // /tennis/h2h endpoint accepts surface=Hard|Clay|Grass). Canonicalise
+        // case so 'clay'/'CLAY' still hit; anything else is a validation error
+        // rather than a silently ignored filter.
+        const surfaceRaw = typeof args.surface === 'string' ? args.surface.trim() : '';
+        let surface;
+        if (surfaceRaw) {
+            const canon = surfaceRaw.charAt(0).toUpperCase() + surfaceRaw.slice(1).toLowerCase();
+            if (game === 'tennis' && canon !== 'Hard' && canon !== 'Clay' && canon !== 'Grass') {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: `surface must be one of Hard, Clay, Grass (got '${surfaceRaw}')`,
+                    game,
+                    source: 'match_preview',
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+            surface = canon;
+        }
         if (!matchId && (!teamA || !teamB)) {
             return errorEnvelope({
                 code: 'VALIDATION',
@@ -469,7 +491,10 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                     // Tennis has a first-class H2H endpoint with the full rivalry; use it
                     // rather than composing from a short form window, which reported
                     // Sinner vs Alcaraz as never having met.
-                    const h2hRes = await fetchJson(ctx, '/tennis/h2h', { query: { player1_id: teamA, player2_id: teamB } });
+                    const h2hQuery = { player1_id: teamA, player2_id: teamB };
+                    if (game === 'tennis' && surface)
+                        h2hQuery.surface = surface;
+                    const h2hRes = await fetchJson(ctx, '/tennis/h2h', { query: h2hQuery });
                     upstreamCalls += 1;
                     rateLimit = { ...rateLimit, ...h2hRes.headers };
                     if (h2hRes.ok) {
@@ -594,6 +619,8 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                 talkingPoints.push(`${sideBName} key names: ${names.join(', ')}`);
         }
         const h2hRec = asRecord(h2h);
+        if (game === 'tennis' && surface && includeH2H)
+            talkingPoints.push(`H2H filtered to ${surface} courts`);
         if (h2hRec?.recordNote)
             talkingPoints.push(String(h2hRec.recordNote));
         else if (Array.isArray(h2hRec?.meetings) && h2hRec.meetings.length) {

package/dist/tools/meta.js

@@ -126,6 +126,26 @@ const TOOL_CATALOG = [
         preferOver: ['raw standings via call_api'],
         doNotUse: 'Single team form → team_profile; live scores → live_matches',
     },
+    {
+        name: 'rankings_movers',
+        outcome: 'Tennis ranking movers: climbers/fallers plus new entries and drop-outs',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['standings'],
+        exampleArgs: { game: 'tennis', tour: 'ATP', direction: 'up', limit: 20 },
+        preferOver: ['raw movers via call_api'],
+        doNotUse: 'Latest snapshot without deltas → standings',
+    },
+    {
+        name: 'player_form',
+        outcome: 'Tennis recent form: W/L record, current streak, per-match rows',
+        parallelSafe: true,
+        games: ['tennis'],
+        jobs: ['player_form', 'preview', 'match_page'],
+        exampleArgs: { game: 'tennis', playerId: 'atp_207989', surface: 'Clay', limit: 5 },
+        preferOver: ['raw form via call_api'],
+        doNotUse: 'Career totals/titles → player_profile; ranking deltas → rankings_movers',
+    },
     {
         name: 'match_preview',
         outcome: 'Pre-match briefing: sides, rosters/form, H2H stub',

package/dist/tools/player.js

@@ -575,4 +575,198 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         });
     },
 };
-export const playerTools = [playerProfile];
+/**
+ * player_form (TENNIS-12).
+ *
+ * Tennis-only: recent-match form for one player (GET /tennis/players/{id}/form).
+ * The upstream answers wins/losses/win_pct over the last N completed matches
+ * plus the per-match rows (result, opponent, score, surface) and the player's
+ * current rank + movement. This tool normalizes those rows and derives the
+ * current W/L streak from the leading run, newest first.
+ */
+const SURFACES = ['Hard', 'Clay', 'Grass'];
+function parseFormSurface(args) {
+    const raw = typeof args.surface === 'string' ? args.surface.trim() : '';
+    if (!raw)
+        return {};
+    const canon = raw.charAt(0).toUpperCase() + raw.slice(1).toLowerCase();
+    if (!SURFACES.includes(canon)) {
+        return { error: `surface must be one of Hard, Clay, Grass (got '${args.surface}')` };
+    }
+    return { surface: canon };
+}
+function normalizeFormMatch(row) {
+    const r = asRecord(row) ?? {};
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        matchId: pickString(r.match_id) ?? null,
+        date: pickString(r.date) ?? null,
+        result: pickString(r.result) ?? null,
+        opponentId: pickString(r.opponent_id) ?? null,
+        opponentRank: num(r.opponent_rank),
+        score: pickString(r.score) ?? null,
+        surface: pickString(r.surface) ?? null,
+        tournamentId: pickString(r.tournament_id) ?? null,
+    };
+}
+export const playerForm = {
+    name: 'player_form',
+    description: `Tennis player form: W/L record over the last N completed matches, current win/loss streak, and per-match rows (opponent, score, surface). Optional surface filter (Hard/Clay/Grass).
+
+When to use:
+- "How is X playing lately?"; current streak; surface-specific record (e.g. clay last 5).
+
+Prefer over: player_profile (identity + career aggregates, no streak); raw form via call_api for agent-normalized rows.
+
+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.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'playerId'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            playerId: stringSchema('Tennis player id, e.g. "atp_207989".', 'atp_207989'),
+            surface: stringSchema('Filter to one surface: Hard, Clay, or Grass.', 'Clay'),
+            limit: limitSchema({ default: 10, max: 50, description: 'Recent-match window (default 10, max 50).' }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'player_form',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `player_form is tennis-only (game '${game}' has no recent-form endpoint)`,
+                game,
+                source: 'player_form',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use player_profile for this game (form/trends where available)',
+                    'Retry player_form with game tennis and a tennis playerId',
+                ],
+            });
+        }
+        const playerId = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        if (!playerId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'playerId is required (e.g. "atp_207989")',
+                game,
+                source: 'player_form',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Call resolve_entity with the player name',
+                    'Retry player_form with the returned id',
+                ],
+            });
+        }
+        const surfaceParse = parseFormSurface(args);
+        if (surfaceParse.error) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: surfaceParse.error,
+                game,
+                source: 'player_form',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const limit = clampInt(args.limit, 10, 1, 50);
+        const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(playerId)}/form`, {
+            query: {
+                limit,
+                ...(surfaceParse.surface ? { surface: surfaceParse.surface } : {}),
+            },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Player form failed (HTTP ${res.status})`,
+                game,
+                source: 'player_form',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+            });
+        }
+        const root = asRecord(res.data);
+        const body = asRecord(root?.data) ?? root ?? {};
+        const matches = (Array.isArray(body.matches) ? body.matches : []).map(normalizeFormMatch);
+        // Upstream rows arrive newest-first: the streak is the leading run.
+        let streakCount = 0;
+        let streakResult = null;
+        for (const m of matches) {
+            if (streakResult === null) {
+                if (m.result !== 'W' && m.result !== 'L')
+                    break;
+                streakResult = m.result;
+                streakCount = 1;
+            }
+            else if (m.result === streakResult) {
+                streakCount += 1;
+            }
+            else {
+                break;
+            }
+        }
+        const rank = asRecord(body.ranking) ?? {};
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        return successEnvelope({
+            pagination: {
+                limit,
+                offset: 0,
+                total: matches.length,
+                hasMore: false,
+                nextCursor: null,
+                prevCursor: null,
+            },
+            source: 'player_form',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            entities: {
+                games: [game],
+                ids: { playerId },
+            },
+            data: {
+                title: `${playerId} recent form (last ${matches.length})`,
+                playerId,
+                sampleSize: num(body.sample_size) ?? matches.length,
+                wins: num(body.wins) ?? null,
+                losses: num(body.losses) ?? null,
+                winPct: num(body.win_pct) ?? null,
+                surfaceFilter: pickString(body.surface_filter) ?? null,
+                streak: streakResult ? { result: streakResult, count: streakCount } : null,
+                ranking: {
+                    current: num(rank.current),
+                    movement: num(rank.movement),
+                    asOf: pickString(rank.as_of) ?? null,
+                },
+                matches,
+            },
+        });
+    },
+};
+export const playerTools = [playerProfile, playerForm];

package/dist/tools/rankings.js

@@ -0,0 +1,228 @@
+/**
+ * rankings_movers (TENNIS-07).
+ *
+ * Tennis-only: biggest ranking movers between the latest ranking list and its
+ * predecessor (GET /tennis/rankings/movers). The upstream payload already
+ * carries new_entries[] and dropped[] alongside items[], so one tool covers
+ * both halves of the deferred TENNIS-07 ask — there is no standalone
+ * /rankings/new_entries route (it 404s; verified 2026-09-08).
+ */
+import { asRecord, clampInt, fetchJson, gameNotIncludedHint, pickString, } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
+import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
+const DIRECTIONS = ['up', 'down', 'both'];
+function parseTour(args) {
+    const rawTour = typeof args.tour === 'string' ? args.tour.trim() : '';
+    const rawDivision = typeof args.division === 'string' ? args.division.trim() : '';
+    if (rawTour && rawDivision && rawTour.toUpperCase() !== rawDivision.toUpperCase()) {
+        return { error: `tour ('${rawTour}') and division ('${rawDivision}') disagree; pass one of ATP|WTA` };
+    }
+    const raw = rawTour || rawDivision;
+    if (!raw)
+        return { tour: 'ATP' };
+    const upper = raw.toUpperCase();
+    if (upper !== 'ATP' && upper !== 'WTA') {
+        return { error: `tour must be ATP or WTA (got '${raw}')` };
+    }
+    return { tour: upper };
+}
+function parseDirection(args) {
+    const raw = typeof args.direction === 'string' ? args.direction.trim().toLowerCase() : '';
+    if (!raw)
+        return { direction: 'up' };
+    if (!DIRECTIONS.includes(raw)) {
+        return { error: `direction must be one of up, down, both (got '${args.direction}')` };
+    }
+    return { direction: raw };
+}
+function parseDate(args) {
+    const raw = typeof args.date === 'string' ? args.date.trim() : '';
+    if (!raw)
+        return {};
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+        return { error: `date must be YYYY-MM-DD (got '${args.date}')` };
+    }
+    return { date: raw };
+}
+function normalizeMover(row) {
+    const r = asRecord(row) ?? {};
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        playerId: pickString(r.player_id) ?? null,
+        playerName: pickString(r.player_name) ?? null,
+        country: pickString(r.ioc, r.country_name) ?? null,
+        rank: num(r.rank),
+        previousRank: num(r.previous_rank),
+        movement: num(r.movement),
+        points: num(r.points),
+    };
+}
+function normalizeEdge(row) {
+    const r = asRecord(row) ?? {};
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        playerId: pickString(r.player_id) ?? null,
+        playerName: pickString(r.player_name) ?? null,
+        country: pickString(r.ioc, r.country_name) ?? null,
+        rank: num(r.rank),
+        previousRank: num(r.previous_rank),
+        points: num(r.points),
+    };
+}
+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.
+
+When to use:
+- Who climbed or fell this week; new top-100 entrants; who dropped out.
+
+Prefer over: standings (latest snapshot only, no week-over-week delta); raw movers via call_api for agent-normalized rows.
+
+Do not use when: current top-N snapshot → standings with game tennis; player history → player_profile.
+
+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.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            tour: stringSchema('ATP or WTA tour; default ATP. Synonym: division.', 'WTA'),
+            division: stringSchema('Synonym for tour (ATP or WTA), matching the standings tool spelling.'),
+            direction: stringSchema('up (climbers), down (fallers), or both (largest absolute change).', 'up'),
+            within: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 2000,
+                default: 100,
+                description: 'Only players inside the top N on either list.',
+            },
+            date: stringSchema('Ranking date to compare against its predecessor (YYYY-MM-DD). Default: latest.'),
+            limit: limitSchema({ default: 20, max: 500 }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'rankings_movers',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `rankings_movers is tennis-only (game '${game}' has no ranking-movers endpoint)`,
+                game,
+                source: 'rankings_movers',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use standings for the latest snapshot of this game',
+                    'Retry rankings_movers with game tennis and tour ATP|WTA',
+                ],
+            });
+        }
+        const tourParse = parseTour(args);
+        if (tourParse.error || !tourParse.tour) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: tourParse.error ?? 'tour is required',
+                game,
+                source: 'rankings_movers',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const dirParse = parseDirection(args);
+        if (dirParse.error || !dirParse.direction) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: dirParse.error ?? 'direction is invalid',
+                game,
+                source: 'rankings_movers',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const dateParse = parseDate(args);
+        if (dateParse.error) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: dateParse.error,
+                game,
+                source: 'rankings_movers',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const within = clampInt(args.within, 100, 1, 2000);
+        const limit = clampInt(args.limit, 20, 1, 500);
+        const res = await fetchJson(ctx, '/tennis/rankings/movers', {
+            query: {
+                tour: tourParse.tour,
+                direction: dirParse.direction,
+                within,
+                limit,
+                ...(dateParse.date ? { date: dateParse.date } : {}),
+            },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Rankings movers failed (HTTP ${res.status})`,
+                game,
+                source: 'rankings_movers',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+            });
+        }
+        const root = asRecord(res.data);
+        const body = asRecord(root?.data) ?? root ?? {};
+        const items = (Array.isArray(body.items) ? body.items : []).map(normalizeMover);
+        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;
+        return successEnvelope({
+            pagination: {
+                limit,
+                offset: 0,
+                total,
+                hasMore: false,
+                nextCursor: null,
+                prevCursor: null,
+            },
+            source: 'rankings_movers',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            data: {
+                title: `${tourParse.tour} ranking movers (${dirParse.direction})`,
+                tour: tourParse.tour,
+                direction: dirParse.direction,
+                within,
+                rankingDate: pickString(body.ranking_date) ?? null,
+                previousDate: pickString(body.previous_date) ?? null,
+                items,
+                newEntries,
+                dropped,
+                total,
+            },
+        });
+    },
+};
+export const rankingsTools = [rankingsMovers];

package/dist/tools/standings.js

@@ -103,6 +103,7 @@ Required scope keys by game:
 - cs2: omit for world rankings; eventId for event standings
 - cod: optional season/stage
 - ufc: optional division (scope=division)
+- tennis: optional division (ATP or WTA tour; default ATP)
 - dota2: best-effort worldRanking only
 
 Parallel-safe: yes. Upstream cost: 1–2.
@@ -242,9 +243,10 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             }
         }
         else if (game === 'tennis') {
-            // Tennis "standings" = the latest ATP/WTA singles rankings. Pass tour via division.
+            // Tennis "standings" = the latest ATP/WTA singles rankings, with
+            // rank_movement/previous_rank on every row. Pass tour via division.
             const tour = String(division ?? 'ATP').toUpperCase() === 'WTA' ? 'WTA' : 'ATP';
-            path = '/tennis/rankings/top';
+            path = '/tennis/standings';
             query = { tour, top_n: Math.min(limit, 100) };
             effectiveScope = 'world';
             title = `${tour} singles rankings`;

package/dist/tools/team.js

@@ -1,7 +1,7 @@
 /**
  * team_profile + head_to_head
  */
-import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
+import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { normalizeMatch } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
@@ -24,22 +24,36 @@ function teamIdentity(game, raw, idHint, slugHint) {
         name,
         game,
         region: pickString(nested.region, nested.country) ?? null,
+        // CS2 publishes countryName/countryCode and worldRanking on the team
+        // resource and none of it reached this card: a team page rendered with no
+        // flag and no ladder position while the API had both. Spirit came back as
+        // {id, slug, name, game, region} with world #1 nowhere in sight.
+        country: pickString(nested.countryName, nested.country, nested.countryCode) ?? null,
+        countryCode: pickString(nested.countryCode) ?? null,
+        worldRanking: numberOrNull(nested.worldRanking ?? nested.ranking ?? nested.rank),
     };
 }
+/** A finite number, or null. Ranks arrive as number or numeric string. */
+function numberOrNull(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
 export const teamProfile = {
     name: 'team_profile',
-    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
-
-When to use:
-- Team page / "who is on this roster?"
-- Builder team screen sample
-
-Prefer over: separate roster + matches + detail via call_api.
-
-Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
-Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
-
-Parallel-safe: yes. Upstream cost: 2–4.
+    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
+
+When to use:
+- Team page / "who is on this roster?"
+- Builder team screen sample
+
+Prefer over: separate roster + matches + detail via call_api.
+
+Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
+Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
+
+Parallel-safe: yes. Upstream cost: 2–4.
 Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -374,8 +388,11 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
                 const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(tid)}/trends`);
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
+                // res.data is the whole upstream body, so this nested
+                // {success, data:{...}} inside our own envelope. Every other field
+                // here is normalized; this one leaked the REST wrapper to the agent.
                 if (res.ok)
-                    form = res.data;
+                    form = unwrapPayload(res.data) ?? res.data;
                 else {
                     partial.push(partialFromRejection('form', {
                         code: mapHttpToCode(res.status),
@@ -545,19 +562,19 @@ function winnerSide(match, a) {
 }
 export const headToHead = {
     name: 'head_to_head',
-    description: `Composed head-to-head record between two teams, two UFC fighters, or two tennis players. No first-class REST H2H exists — this tool filters match history server-side.
-
-When to use:
-- Rivalry / series record questions
-- Supporting context for previews
-
-Prefer over: agent-side double match-list filtering.
-
-Do not use when: single-side form only → team_profile or player_profile.
-
-Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
-
-Parallel-safe: yes. Upstream cost: 2–4.
+    description: `Composed head-to-head record between two teams, two UFC fighters, or two tennis players. No first-class REST H2H exists — this tool filters match history server-side.
+
+When to use:
+- Rivalry / series record questions
+- Supporting context for previews
+
+Prefer over: agent-side double match-list filtering.
+
+Do not use when: single-side form only → team_profile or player_profile.
+
+Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
+
+Parallel-safe: yes. Upstream cost: 2–4.
 Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
     inputSchema: {
         type: 'object',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cito-mcp",
-  "version": "0.3.18",
-  "description": "Standalone MCP server for the Cito esports API — 15 curated outcome tools for agents (live, schedule, profiles, standings, previews, event cards).",
+  "version": "0.3.20",
+  "description": "Standalone MCP server for the Cito esports and sports API — 18 curated outcome tools for agents (live, schedule, profiles, standings, previews, event cards, player form, rankings movers).",
   "type": "module",
   "bin": {
     "cito-mcp": "dist/index.js"