cito-mcp 0.3.20 → 0.4.0

package/README.md

@@ -12,7 +12,7 @@ Primary games & sports: **lol · cs2 · dota2 · cod · ufc · tennis**. Long-ta
 
 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.3 ships 18 hand-authored tools** that answer *jobs* instead of mirroring REST:
+**Ships 42 curated outcome tools** that answer *jobs* instead of mirroring REST:
 
 | Job | Tool |
 | --- | --- |
@@ -28,6 +28,12 @@ v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among t
 | Pre-match briefing (with surface) | `match_preview` |
 | Event / fight-night card | `event_card` |
 | Rivalry record | `head_to_head` |
+| Tennis betting odds | `tennis_odds` |
+| Tennis tournament catalog | `tournaments` |
+| One day of tennis | `tennis_schedule` |
+| Tennis player match log | `player_matches` |
+| Tennis career statistics | `player_stats` |
+| Tennis ranking trajectory | `player_rankings_history` |
 | Fighter / team photos | `event_card` · `player_profile` |
 | Which raw REST route exists? | `list_routes` |
 | Name → ID | `resolve_entity` / `search_entities` |

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

@@ -6,8 +6,13 @@ 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 (17 tools). Order matches preferred cold-start ladder. */
+import { cs2Tools } from './cs2.js';
+import { oddsTools } from './odds.js';
+import { tournamentTools } from './tournaments.js';
+import { scheduleTools } from './schedule.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,
@@ -17,7 +22,14 @@ export const allTools = [
     ...teamTools,
     ...standingsTools,
     ...rankingsTools,
+    ...leaderboardTools,
+    // Tennis depth added after the coverage audit: odds, tournament discovery and
+    // the daily schedule were reachable only through call_api.
+    ...oddsTools,
+    ...tournamentTools,
+    ...scheduleTools,
     ...insightTools,
+    ...cs2Tools,
     // Escape-hatch pair last: discover routes, then call one.
     ...metaTools.filter((t) => t.name === 'list_routes' || t.name === 'call_api'),
 ];