cito-mcp 0.3.20 → 0.4.0

package/dist/tools/schedule.js

@@ -0,0 +1,234 @@
+/**
+ * tennis_schedule — one day of tennis, scheduled and completed (TENNIS-26).
+ *
+ * WHY THIS EXISTS
+ * /tennis/schedule and /tennis/matches/completed are the two routes that require
+ * ?date=. They were the exact pair producing "route is broken" support tickets
+ * from callers who omitted it, which is why the REST layer now returns a hint
+ * with a working example URL. But neither route had a tool either — so an agent
+ * driving the MCP had no way to ask "what tennis is on today?" at all.
+ *
+ * This tool owns the required date, defaults it to today, validates the format
+ * before spending an upstream call, and on a bad date returns the same
+ * paste-able example the REST hint does.
+ */
+import { asRecord, clampInt, fetchJson, pickString, } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
+import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
+/** ISO date, no time component, already validated by the caller. */
+function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+function normalizeScheduled(row) {
+    const r = asRecord(row) ?? {};
+    const p1 = asRecord(r.player1) ?? asRecord(r.home) ?? {};
+    const p2 = asRecord(r.player2) ?? asRecord(r.away) ?? {};
+    return {
+        matchId: pickString(r.id, r.match_id) ?? null,
+        tournamentId: pickString(r.tournament_id) ?? null,
+        tournamentName: pickString(r.tournament_name, r.tournament) ?? null,
+        tour: pickString(r.tour) ?? null,
+        level: pickString(r.level, r.tier) ?? null,
+        surface: pickString(r.surface) ?? null,
+        round: pickString(r.round) ?? null,
+        roundName: pickString(r.round_name) ?? null,
+        startsAt: pickString(r.starts_at, r.commence_time, r.match_date) ?? null,
+        status: pickString(r.status, r.outcome) ?? null,
+        player1: { id: pickString(p1.id, p1.player_id) ?? null, name: pickString(p1.name) ?? null },
+        player2: { id: pickString(p2.id, p2.player_id) ?? null, name: pickString(p2.name) ?? null },
+        score: pickString(r.score, r.score_raw) ?? null,
+    };
+}
+export const tennisSchedule = {
+    name: 'tennis_schedule',
+    description: `One day of tennis: the day's schedule and/or the matches completed that day, across ATP and WTA.
+
+When to use:
+- "What tennis is on today?"; a specific day's fixtures; results completed on a given date; building a daily digest.
+
+Prefer over: call_api for /tennis/schedule and /tennis/matches/completed (both require ?date=, which this tool supplies and validates); live_matches (in-progress only, right now); upcoming_schedule (a forward window, not a specific day).
+
+Do not use when: matches currently in play → live_matches; a named player's history → player_matches.
+
+Tennis-only. 'date' defaults to today (UTC) and MUST be YYYY-MM-DD. Choose with
+'include': both (default), scheduled, or completed. Both halves are fetched in
+parallel, so either can fail on its own without losing the other.
+
+Parallel-safe: yes. Upstream cost: 1 or 2.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            date: stringSchema('Day to fetch, YYYY-MM-DD. Defaults to today (UTC).', '2026-09-12'),
+            include: stringSchema('both (default) | scheduled | completed.', 'both'),
+            limit: limitSchema({ default: 20, max: 50, description: 'Rows per half (default 20, 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: 'tennis_schedule',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `tennis_schedule is tennis-only (game '${game}' has its own schedule tool)`,
+                game,
+                source: 'tennis_schedule',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use upcoming_schedule for this game', 'Retry with game tennis'],
+            });
+        }
+        const rawDate = typeof args.date === 'string' ? args.date.trim() : '';
+        const date = rawDate || todayIso();
+        // Validate before spending an upstream call, and echo the same paste-able
+        // example the REST layer returns so the two surfaces teach identically.
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `date must be YYYY-MM-DD (got '${rawDate}')`,
+                game,
+                source: 'tennis_schedule',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [`Try date=${todayIso()}`, 'This route requires a date; omit it to default to today'],
+            });
+        }
+        const includeRaw = typeof args.include === 'string' ? args.include.trim().toLowerCase() : 'both';
+        if (!['both', 'scheduled', 'completed'].includes(includeRaw)) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `include must be both, scheduled, or completed (got '${args.include}')`,
+                game,
+                source: 'tennis_schedule',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const limit = clampInt(args.limit, 20, 1, 50);
+        const wantScheduled = includeRaw === 'both' || includeRaw === 'scheduled';
+        const wantCompleted = includeRaw === 'both' || includeRaw === 'completed';
+        const settled = await Promise.allSettled([
+            wantScheduled
+                ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit } })
+                : Promise.resolve(null),
+            wantCompleted
+                ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit } })
+                : Promise.resolve(null),
+        ]);
+        const rejected = [];
+        const rows = (value) => {
+            const root = asRecord(value);
+            const body = asRecord(root?.data) ?? root ?? {};
+            return Array.isArray(body.items) ? body.items : [];
+        };
+        let scheduled = [];
+        let completed = [];
+        const [schedRes, compRes] = settled;
+        if (schedRes.status === 'fulfilled' && schedRes.value) {
+            const v = schedRes.value;
+            if (v.ok)
+                scheduled = rows(v.data);
+            else
+                rejected.push({
+                    section: 'schedule',
+                    code: mapHttpToCode(v.status),
+                    message: `schedule HTTP ${v.status}`,
+                    httpStatus: v.status,
+                });
+        }
+        else if (schedRes.status === 'rejected') {
+            rejected.push({
+                section: 'schedule',
+                code: 'UPSTREAM',
+                message: String(schedRes.reason).slice(0, 200),
+            });
+        }
+        if (compRes.status === 'fulfilled' && compRes.value) {
+            const v = compRes.value;
+            if (v.ok)
+                completed = rows(v.data);
+            else
+                rejected.push({
+                    section: 'completed',
+                    code: mapHttpToCode(v.status),
+                    message: `completed HTTP ${v.status}`,
+                    httpStatus: v.status,
+                });
+        }
+        else if (compRes.status === 'rejected') {
+            rejected.push({
+                section: 'completed',
+                code: 'UPSTREAM',
+                message: String(compRes.reason).slice(0, 200),
+            });
+        }
+        // Both halves failed -> a real error, not a partial.
+        if (rejected.length > 0 && scheduled.length === 0 && completed.length === 0) {
+            const first = rejected[0];
+            return errorEnvelope({
+                code: first.code,
+                message: `Tennis schedule failed for ${date}: ${rejected.map((r) => r.message).join('; ')}`,
+                game,
+                source: 'tennis_schedule',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: rejected.length,
+                recover: ['Check the date is a real calendar day', 'Retry, or widen include to both'],
+            });
+        }
+        const data = {
+            title: `Tennis — ${date}`,
+            date,
+            include: includeRaw,
+            scheduled: scheduled.map(normalizeScheduled),
+            scheduledCount: scheduled.length,
+            completed: completed.map(normalizeScheduled),
+            completedCount: completed.length,
+            timezoneNote: 'The API groups by UTC date. For a local "today", pass the date explicitly rather than relying on the default.',
+        };
+        const upstreamCalls = (wantScheduled ? 1 : 0) + (wantCompleted ? 1 : 0);
+        // A half that failed is reported alongside the half that worked rather than
+        // being silently dropped: an empty scheduled[] means two different things.
+        if (rejected.length > 0) {
+            return successEnvelope({
+                source: 'tennis_schedule',
+                game,
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                data,
+                partial: rejected.map((r) => partialFromRejection(r.section, {
+                    code: r.code,
+                    message: r.message,
+                    ...(r.httpStatus !== undefined ? { httpStatus: r.httpStatus } : {}),
+                })),
+                warnings: [
+                    `${rejected.length} of ${upstreamCalls} schedule section(s) failed; the rest of the day is still returned.`,
+                ],
+            });
+        }
+        return successEnvelope({
+            source: 'tennis_schedule',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            data,
+        });
+    },
+};
+export const scheduleTools = [tennisSchedule];

package/dist/tools/team.js

@@ -1022,4 +1022,186 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
         });
     },
 };
-export const teamTools = [teamProfile, headToHead];
+/**
+ * h2h_matrix (TENNIS-24, cycle 60).
+ *
+ * Tennis-only: multi-player head-to-head comparison grid from the first-class
+ * GET /tennis/h2h/matrix route (2-16 player ids, comma-separated). Upstream
+ * shape (verified 2026-09-09): { players: [{ id, name, ioc, wins }], matrix:
+ * { [rowId]: { [colId]: "W-L" | "-" } } }. Cell "7-6" at [A][B] means A won 7
+ * and B won 6 of their meetings; "-" marks the self diagonal. Unknown ids get
+ * honest 0-0 cells and no players entry (no 404); fewer than 2 or more than 16
+ * ids 422, which surfaces as VALIDATION here.
+ *
+ * Names are resolved to atp_/wta_ ids via /tennis/players/search first (same
+ * id-shaped shortcut as the head_to_head tennis branch); duplicates collapse
+ * to one grid row.
+ */
+export const h2hMatrix = {
+    name: 'h2h_matrix',
+    description: `Multi-player tennis head-to-head grid: every pair's series record in one comparison matrix.
+
+When to use:
+- Draw/field analysis: how each contender fares against every other (e.g. Alcaraz vs Zverev vs Sinner round-robin records)
+- Group-stage or semifinal-field comparisons
+
+Prefer over: N head_to_head calls for an N-player field; raw matrix via call_api.
+
+Do not use when: a two-player rivalry deep-dive with tiebreak/decider splits → head_to_head; season stat leaders → leaderboard_*; rankings → standings.
+
+Tennis-only. players takes 2-16 ids or names (names resolve via player search). Each matrix cell is "W-L" from the row player's perspective, "-" on the diagonal.
+
+Parallel-safe: yes. Upstream cost: 1 + one search per unresolved name.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'players'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            players: {
+                type: 'array',
+                items: { type: 'string' },
+                minItems: 2,
+                maxItems: 16,
+                description: '2-16 tennis player ids (atp_207989) or names ("Carlos Alcaraz"); duplicates collapse.',
+            },
+        },
+    },
+    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: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `h2h_matrix is tennis-only (game '${game}' has no H2H matrix)`,
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use head_to_head for a two-side rivalry record in this game',
+                    'Retry h2h_matrix with game tennis and 2-16 player ids or names',
+                ],
+            });
+        }
+        const rawPlayers = Array.isArray(args.players) ? args.players : [];
+        const cleaned = rawPlayers
+            .filter((p) => typeof p === 'string' && p.trim().length > 0)
+            .map((p) => p.trim());
+        if (cleaned.length < 2 || cleaned.length > 16) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `players must contain between 2 and 16 names or ids (got ${cleaned.length})`,
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Pass 2-16 player ids (atp_207989) or names ("Carlos Alcaraz")'],
+            });
+        }
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        const resolveTennisSide = async (side) => {
+            if (/^(atp|wta)_\d+$/i.test(side))
+                return { id: side, name: side };
+            const res = await fetchJson(ctx, '/tennis/players/search', { query: { q: side, limit: 3 } });
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...res.headers };
+            if (!res.ok)
+                return null;
+            const envelope = asRecord(res.data) ?? {};
+            const data = asRecord(envelope.data) ?? envelope;
+            const first = asRecord(extractRows(data.items ?? data)[0]);
+            const id = pickString(first?.id, first?.player_id);
+            return id ? { id, name: pickString(first?.full_name, first?.name) ?? side } : null;
+        };
+        const resolved = await Promise.all(cleaned.map((side) => resolveTennisSide(side)));
+        const missing = cleaned.filter((_, i) => !resolved[i]);
+        if (missing.length > 0) {
+            return errorEnvelope({
+                code: 'NOT_FOUND',
+                message: `Tennis player(s) not found: ${missing.join(', ')} — pass names or ids like atp_104745`,
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                rateLimit,
+                recover: [
+                    'resolve_entity { game: "tennis", type: "player", q } for each missing name',
+                    'Retry h2h_matrix with returned ids',
+                ],
+            });
+        }
+        // Dedupe resolved ids preserving order: REST dict keys would collapse
+        // anyway, but players_info would list the duplicate twice.
+        const ids = [...new Set(resolved.map((r) => r.id))];
+        if (ids.length < 2) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'players resolve to fewer than 2 distinct players — pass at least 2 different players',
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                rateLimit,
+            });
+        }
+        const res = await fetchJson(ctx, '/tennis/h2h/matrix', {
+            query: { player_ids: ids.join(',') },
+        });
+        upstreamCalls += 1;
+        rateLimit = { ...rateLimit, ...res.headers };
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Tennis H2H matrix fetch failed (HTTP ${res.status})`,
+                game,
+                source: 'h2h_matrix',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                httpStatus: res.status,
+                rateLimit,
+            });
+        }
+        const envelope = asRecord(res.data) ?? {};
+        const payload = asRecord(envelope.data) ?? envelope;
+        const players = extractRows(payload.players ?? []).map((row) => {
+            const r = asRecord(row) ?? {};
+            return {
+                id: pickString(r.id, r.player_id) ?? null,
+                name: pickString(r.full_name, r.name) ?? null,
+                ioc: pickString(r.ioc) ?? null,
+            };
+        });
+        const matrix = asRecord(payload.matrix) ?? {};
+        return successEnvelope({
+            source: 'h2h_matrix',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            data: {
+                players,
+                matrix,
+                notes: ['Cells are "W-L" from the row player vs the column player; "-" is the self diagonal'],
+            },
+        });
+    },
+};
+export const teamTools = [teamProfile, headToHead, h2hMatrix];

package/dist/tools/tournaments.js

@@ -0,0 +1,253 @@
+/**
+ * tournaments — tennis tournament discovery (TENNIS-25).
+ *
+ * WHY THIS EXISTS
+ * event_card already renders a tournament Profile/Draw, but only once you know a
+ * tournament id. There was no way to ASK for tournaments — so "list the 2026
+ * WTA 1000 events" or "what ATP 250s are on clay" was impossible without
+ * call_api, even though /tennis/tournaments supports exactly those filters
+ * (year, tour, level, surface, country) and the level filter was recently made
+ * to accept names like "WTA 1000" rather than only raw tier codes.
+ *
+ * This tool is the discovery half; event_card stays the detail half.
+ */
+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 SURFACES = ['Hard', 'Clay', 'Grass', 'Carpet'];
+/** Human level names the API accepts on ?level=, plus the raw tier codes. */
+const LEVEL_NAMES = [
+    'Grand Slam',
+    'Masters 1000',
+    'ATP Tour',
+    'ATP 500',
+    'ATP 250',
+    'WTA 1000',
+    'WTA 500',
+    'WTA 250',
+    'WTA 125',
+    'Challenger',
+    'ITF World Tennis Tour',
+    'Davis Cup',
+    'Billie Jean King Cup',
+    'Tour Finals',
+    'WTA Finals',
+    'Olympics',
+];
+function normalizeTournament(row) {
+    const r = asRecord(row) ?? {};
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        id: pickString(r.id) ?? null,
+        name: pickString(r.name) ?? null,
+        tour: pickString(r.tour) ?? null,
+        year: num(r.year),
+        // `tier` is the human level the API derives from the tier code; `level` is
+        // the raw code. Both are surfaced because callers filter on the name but
+        // cross-reference by the code.
+        level: pickString(r.tier) ?? pickString(r.level) ?? null,
+        levelCode: pickString(r.tier_code, r.level) ?? null,
+        category: pickString(r.category) ?? null,
+        surface: pickString(r.surface) ?? null,
+        drawSize: num(r.draw_size),
+        city: pickString(r.city) ?? null,
+        country: pickString(r.country_code) ?? null,
+        firstEditionYear: num(r.first_edition_year),
+        mostRecentEditionYear: num(r.most_recent_edition_year),
+    };
+}
+export const tournaments = {
+    name: 'tournaments',
+    description: `Tennis tournament catalog: find tournaments by year, tour, level, surface, or country.
+
+When to use:
+- "Which ATP 500s are on clay in 2026?"; "list the WTA 1000 events"; "what Grand Slams are in 2026?"; finding a tournament id before calling event_card.
+
+Prefer over: event_card when you do NOT already have a tournament id (event_card needs one); call_api for /tennis/tournaments.
+
+Do not use when: the draw bracket or a specific edition → event_card with the id this returns; the season calendar by month → event_card.
+
+Tennis-only. Levels accept names (Grand Slam, WTA 1000, ATP 500, Challenger,
+ITF World Tennis Tour, Davis Cup, ...) or raw tier codes (G, M, A, C, D).
+Note the source does not separate ATP 500 from ATP 250 — both are ATP Tour.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            year: {
+                type: 'integer',
+                minimum: 1877,
+                maximum: 2100,
+                description: 'Edition year, e.g. 2026. Omit for all years.',
+            },
+            tour: stringSchema('ATP or WTA.', 'WTA'),
+            level: stringSchema(`Filter by level. Names: ${LEVEL_NAMES.slice(0, 6).join(', ')}, ... or codes G|M|A|C|D.`, 'WTA 1000'),
+            surface: stringSchema('Hard, Clay, Grass, or Carpet.', 'Clay'),
+            countryCode: stringSchema('3-letter IOC country code, e.g. FRA.', 'FRA'),
+            q: stringSchema('Case-insensitive name search, e.g. "open".', 'open'),
+            limit: limitSchema({ default: 20, max: 50 }),
+            page: { type: 'integer', minimum: 1, default: 1, description: 'Page number (1-indexed).' },
+        },
+    },
+    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: 'tournaments',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `tournaments is tennis-only (game '${game}' has no tournament catalog on this endpoint)`,
+                game,
+                source: 'tournaments',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use event_card for this game', 'Retry with game tennis'],
+            });
+        }
+        const year = typeof args.year === 'number' && Number.isFinite(args.year) ? Math.trunc(args.year) : null;
+        if (year !== null && (year < 1877 || year > 2100)) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `year must be between 1877 and 2100 (got ${year})`,
+                game,
+                source: 'tournaments',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const tourRaw = typeof args.tour === 'string' ? args.tour.trim().toUpperCase() : '';
+        if (tourRaw && tourRaw !== 'ATP' && tourRaw !== 'WTA') {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `tour must be ATP or WTA (got '${args.tour}')`,
+                game,
+                source: 'tournaments',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const surfaceRaw = typeof args.surface === 'string' ? args.surface.trim() : '';
+        const surface = surfaceRaw
+            ? SURFACES.find((s) => s.toLowerCase() === surfaceRaw.toLowerCase())
+            : undefined;
+        if (surfaceRaw && !surface) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `surface must be one of ${SURFACES.join(', ')} (got '${args.surface}')`,
+                game,
+                source: 'tournaments',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const levelRaw = typeof args.level === 'string' ? args.level.trim() : '';
+        if (levelRaw) {
+            const known = LEVEL_NAMES.some((l) => l.toLowerCase() === levelRaw.toLowerCase()) ||
+                /^[A-Za-z]$/.test(levelRaw);
+            if (!known) {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: `Unknown level '${levelRaw}'. Use a name or a tier code.`,
+                    game,
+                    source: 'tournaments',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    recover: [`Valid names include: ${LEVEL_NAMES.slice(0, 8).join(', ')}`, 'Or a code: G, M, A, C, D'],
+                });
+            }
+        }
+        const limit = clampInt(args.limit, 20, 1, 50);
+        const page = clampInt(args.page, 1, 1, 10000);
+        const countryCode = typeof args.countryCode === 'string' && args.countryCode.trim()
+            ? args.countryCode.trim().toUpperCase()
+            : '';
+        const q = typeof args.q === 'string' && args.q.trim() ? args.q.trim() : '';
+        const res = await fetchJson(ctx, '/tennis/tournaments', {
+            query: {
+                limit,
+                page,
+                ...(year !== null ? { year } : {}),
+                ...(tourRaw ? { tour: tourRaw } : {}),
+                ...(levelRaw ? { level: levelRaw } : {}),
+                ...(surface ? { surface } : {}),
+                ...(countryCode ? { country_code: countryCode } : {}),
+                ...(q ? { q } : {}),
+            },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Tournament catalog failed (HTTP ${res.status})`,
+                game,
+                source: 'tournaments',
+                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(normalizeTournament);
+        const total = typeof body.total === 'number' ? body.total : items.length;
+        const pageSize = typeof body.page_size === 'number' ? body.page_size : limit;
+        const filters = [
+            year !== null ? String(year) : null,
+            tourRaw || null,
+            levelRaw || null,
+            surface || null,
+            countryCode || null,
+            q ? `"${q}"` : null,
+        ].filter(Boolean);
+        return successEnvelope({
+            pagination: {
+                limit: pageSize,
+                offset: (page - 1) * pageSize,
+                total,
+                hasMore: body.has_next === true,
+                nextCursor: null,
+                prevCursor: null,
+            },
+            source: 'tournaments',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            data: {
+                title: filters.length > 0
+                    ? `Tennis tournaments — ${filters.join(' ')}`
+                    : 'Tennis tournaments',
+                filters: {
+                    year,
+                    tour: tourRaw || null,
+                    level: levelRaw || null,
+                    surface: surface ?? null,
+                    countryCode: countryCode || null,
+                    q: q || null,
+                },
+                items,
+                total,
+                page,
+                totalPages: typeof body.total_pages === 'number' ? body.total_pages : null,
+            },
+        });
+    },
+};
+export const tournamentTools = [tournaments];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cito-mcp",
-  "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).",
+  "version": "0.4.0",
+  "description": "Standalone MCP server for the Cito esports and sports API — 42 curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
   "type": "module",
   "bin": {
     "cito-mcp": "dist/index.js"