cito-mcp 0.3.19 → 0.3.21

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

@@ -0,0 +1,421 @@
+/**
+ * Dedicated CS2 esports analytics & live scorebot MCP tools.
+ *
+ * Exposes deep CS2 domain data from the 161 backend endpoints:
+ * - Live real-time scoreboards & round state
+ * - Round-by-round tactical economies & buy classifications
+ * - First blood / opening duels per player & map
+ * - 1vX clutch success rates (1v1 through 1v5)
+ * - Team map pool analytics (Mirage, Inferno, Nuke, Dust2, Ancient, Anubis, Vertigo)
+ * - Sub-second utility & flashbang efficiency leaderboard
+ * - Match map pick/ban veto sequence
+ * - Pro roster changes & transfers
+ */
+import { asRecord, clampInt, fetchJson, unwrapPayload, } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
+import { limitSchema, READ_TOOL_ANNOTATIONS, stringSchema, } from './types.js';
+/** Unwraps Cito envelope whether inner entity is an object or array */
+function unwrap(val) {
+    const p = unwrapPayload(val);
+    const r = asRecord(p);
+    if (r && Array.isArray(r.data))
+        return r.data;
+    if (r && Array.isArray(r.items))
+        return r.items;
+    return p;
+}
+/**
+ * 1. cs2_live_scoreboard
+ * Real-time round state, bomb status, and player combat stats for an active match.
+ */
+export const cs2LiveScoreboard = {
+    name: 'cs2_live_scoreboard',
+    description: 'Live real-time in-game scoreboard for an active CS2 match. Returns current round, bomb status, team scores, and individual player stats (K/A/D, ADR, HS%, alive status, HP, armor, weapon, and equipment value).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            matchId: stringSchema('Match ID (e.g. "cs2-match-2397733" or "2397733"). Required.', 'cs2-match-2397733'),
+        },
+        required: ['matchId'],
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+        if (!rawId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'matchId is required',
+                game: 'cs2',
+                source: 'cs2_live_scoreboard',
+                requestId: reqId,
+            });
+        }
+        const cleanId = rawId.replace(/^cs2-match-/, '');
+        const path = `/cs2/live/${encodeURIComponent(cleanId)}/scoreboard`;
+        const res = await fetchJson(ctx, path);
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Live scoreboard fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_live_scoreboard',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_live_scoreboard',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 2. cs2_round_economy
+ * Tactical round-by-round buy classification and equipment values for a map.
+ */
+export const cs2RoundEconomy = {
+    name: 'cs2_round_economy',
+    description: 'Round-by-round tactical economy for a CS2 map. Classifies every round buy type (Full Buy, Force Buy, Semi-Eco, Full Eco), team equipment spend, freeze-time equipment values, and loss bonus counter.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            mapId: stringSchema('Map ID or Game ID (e.g. "7716-map-1" or "cs2-game-123"). Required.', '7716-map-1'),
+        },
+        required: ['mapId'],
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawMapId = typeof args.mapId === 'string' ? args.mapId.trim() : '';
+        if (!rawMapId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'mapId is required',
+                game: 'cs2',
+                source: 'cs2_round_economy',
+                requestId: reqId,
+            });
+        }
+        const path = `/cs2/maps/${encodeURIComponent(rawMapId)}/rounds`;
+        let res = await fetchJson(ctx, path);
+        if (!res.ok && res.status === 404) {
+            res = await fetchJson(ctx, `/cs2/games/${encodeURIComponent(rawMapId)}/rounds`);
+        }
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Round economy fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_round_economy',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_round_economy',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 3. cs2_opening_duels
+ * First blood / opening kill statistics by player or overall leaderboard.
+ */
+export const cs2OpeningDuels = {
+    name: 'cs2_opening_duels',
+    description: 'First blood and opening duel statistics. Pass playerId to view a pro player\'s First Kills (FK), First Deaths (FD), and opening duel conversion %, or omit playerId to view the global CS2 opening duel leaderboard.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            playerId: stringSchema('Optional player ID or slug (e.g. "chucky" or "cs2-player-123"). If omitted, returns global leaderboard.', 'chucky'),
+            limit: limitSchema({ default: 20, max: 100 }),
+        },
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawPlayer = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        const limit = clampInt(args.limit, 20, 1, 100);
+        const path = rawPlayer
+            ? `/cs2/players/${encodeURIComponent(rawPlayer)}/opening-duels`
+            : `/cs2/stats/opening-duels`;
+        const res = await fetchJson(ctx, path, { query: { limit } });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Opening duels fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_opening_duels',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_opening_duels',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 4. cs2_clutches
+ * 1vX clutch situation success records (1v1 through 1v5).
+ */
+export const cs2Clutches = {
+    name: 'cs2_clutches',
+    description: '1vX clutch situation success records. Pass playerId for a specific player\'s clutch breakdown (1v1, 1v2, 1v3, 1v4, 1v5 attempted vs won), or omit to view the global clutch leaderboard.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            playerId: stringSchema('Optional player ID or slug (e.g. "xm1nd" or "cs2-player-456"). If omitted, returns global leaderboard.', 'xm1nd'),
+            limit: limitSchema({ default: 20, max: 100 }),
+        },
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawPlayer = typeof args.playerId === 'string' ? args.playerId.trim() : '';
+        const limit = clampInt(args.limit, 20, 1, 100);
+        const path = rawPlayer
+            ? `/cs2/players/${encodeURIComponent(rawPlayer)}/clutches`
+            : `/cs2/stats/clutches`;
+        const res = await fetchJson(ctx, path, { query: { limit } });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Clutches fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_clutches',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_clutches',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 5. cs2_team_map_stats
+ * Team performance across the competitive map pool.
+ */
+export const cs2TeamMapStats = {
+    name: 'cs2_team_map_stats',
+    description: 'Team win rates, round win rates, and CT/T side win splits across the competitive map pool (Mirage, Inferno, Nuke, Dust2, Ancient, Anubis, Vertigo) over the last 30 or 90 days.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            teamId: stringSchema('Team ID or slug (e.g. "hltv-team-4608", "cs2-team-4608", or "natus-vincere"). Required.', 'hltv-team-4608'),
+            days: {
+                type: 'integer',
+                description: 'Timeframe in days: 30, 90, 180, or 365 (default 90).',
+                default: 90,
+            },
+        },
+        required: ['teamId'],
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawTeam = typeof args.teamId === 'string' ? args.teamId.trim() : '';
+        if (!rawTeam) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'teamId is required',
+                game: 'cs2',
+                source: 'cs2_team_map_stats',
+                requestId: reqId,
+            });
+        }
+        const days = typeof args.days === 'number' ? args.days : 90;
+        const path = `/cs2/teams/${encodeURIComponent(rawTeam)}/map-stats`;
+        const res = await fetchJson(ctx, path, { query: { days } });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Team map stats fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_team_map_stats',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_team_map_stats',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 6. cs2_utility_leaderboard
+ * Sub-second cached leaderboard for flashbang & utility efficiency.
+ */
+export const cs2UtilityLeaderboard = {
+    name: 'cs2_utility_leaderboard',
+    description: 'Sub-second cached leaderboard of CS2 utility and flashbang efficiency. Returns pro player rankings for effective blind duration per flash, enemy blind time, flashes thrown, and grenade ADR.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: limitSchema({ default: 20, max: 100 }),
+        },
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const limit = clampInt(args.limit, 20, 1, 100);
+        const path = `/cs2/stats/utility`;
+        const res = await fetchJson(ctx, path, { query: { limit } });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Utility leaderboard fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_utility_leaderboard',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_utility_leaderboard',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 7. cs2_veto_sequence
+ * Map pick/ban sequence and veto history for a match.
+ */
+export const cs2VetoSequence = {
+    name: 'cs2_veto_sequence',
+    description: 'Map pick/ban veto sequence for a CS2 match. Shows which team banned which map, map picks, and decider map in chronological order.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            matchId: stringSchema('Match ID (e.g. "2397603" or "cs2-match-2397603"). Required.', '2397603'),
+        },
+        required: ['matchId'],
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const rawId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+        if (!rawId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'matchId is required',
+                game: 'cs2',
+                source: 'cs2_veto_sequence',
+                requestId: reqId,
+            });
+        }
+        const cleanId = rawId.replace(/^cs2-match-/, '');
+        const path = `/cs2/matches/${encodeURIComponent(cleanId)}/head-to-head`;
+        const res = await fetchJson(ctx, path);
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Veto sequence fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_veto_sequence',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        const r = asRecord(payload);
+        const veto = r?.veto ?? r?.vetoSequence ?? payload;
+        return successEnvelope({
+            data: veto,
+            game: 'cs2',
+            source: 'cs2_veto_sequence',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/**
+ * 8. cs2_roster_transfers
+ * Recent professional roster changes, benchings, and transfers.
+ */
+export const cs2RosterTransfers = {
+    name: 'cs2_roster_transfers',
+    description: 'Recent professional CS2 roster changes, player benchings, stand-ins, and team transfers.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: limitSchema({ default: 20, max: 100 }),
+        },
+        additionalProperties: false,
+    },
+    annotations: READ_TOOL_ANNOTATIONS,
+    handler: async (args, ctx) => {
+        const reqId = newRequestId();
+        const limit = clampInt(args.limit, 20, 1, 100);
+        const path = `/cs2/transfers/recent`;
+        let res = await fetchJson(ctx, path, { query: { limit } });
+        if (!res.ok && res.status === 404) {
+            res = await fetchJson(ctx, `/cs2/roster-changes/recent`, { query: { limit } });
+        }
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `Roster transfers fetch failed: ${res.status} on ${path}`,
+                game: 'cs2',
+                source: 'cs2_roster_transfers',
+                requestId: reqId,
+                httpStatus: res.status,
+            });
+        }
+        const payload = unwrap(res.data);
+        return successEnvelope({
+            data: payload,
+            game: 'cs2',
+            source: 'cs2_roster_transfers',
+            requestId: reqId,
+            rateLimit: res.headers,
+        });
+    },
+};
+/** All curated CS2 tools */
+export const cs2Tools = [
+    cs2LiveScoreboard,
+    cs2RoundEconomy,
+    cs2OpeningDuels,
+    cs2Clutches,
+    cs2TeamMapStats,
+    cs2UtilityLeaderboard,
+    cs2VetoSequence,
+    cs2RosterTransfers,
+];

package/dist/tools/index.js

@@ -5,8 +5,11 @@ 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 { leaderboardTools } from './leaderboard.js';
 import { insightTools } from './insight.js';
-/** Curated outcome-tool catalog (16 tools). Order matches preferred cold-start ladder. */
+import { cs2Tools } from './cs2.js';
+/** Curated outcome-tool catalog. Order matches preferred cold-start ladder. */
 export const allTools = [
     ...metaTools.filter((t) => t.name === 'list_capabilities' || t.name === 'api_health'),
     ...resolveTools,
@@ -15,7 +18,10 @@ export const allTools = [
     ...playerTools,
     ...teamTools,
     ...standingsTools,
+    ...rankingsTools,
+    ...leaderboardTools,
     ...insightTools,
+    ...cs2Tools,
     // 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) {