cito-mcp 0.3.21 → 0.4.1

package/dist/tools/tournaments.js

@@ -0,0 +1,319 @@
+/**
+ * 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).
+A level name that starts with ATP or WTA also fixes the tour (and conflicts with
+a contradicting tour= argument are rejected), so "WTA 1000" cannot return ATP
+Masters events even though the upstream filter is not tour-aware.
+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'],
+                });
+            }
+        }
+        /**
+         * A level name that starts with a tour token constrains the tour, and the
+         * upstream filter does not know that.
+         *
+         * The API's reverse level map is not tour-aware: `_TIER_WTA` carries BOTH
+         * "PM" and "M" as "WTA 1000" (M is the fallback label for a WTA row stored
+         * with the ATP code), so `?level=WTA 1000` resolves to `tier_code IN
+         * ('PM','M')` and returns every ATP Masters 1000 event alongside the WTA
+         * ones. Verified live: asking for "WTA 1000" returned Rome Masters, Madrid
+         * Masters, Monte Carlo, Miami Masters and Indian Wells Masters (all ATP).
+         * The same widening hits "WTA 125" (code C, shared with ATP Challengers) and
+         * "ATP 500"/"ATP 250" (code A, shared with WTA tour-level rows).
+         *
+         * The tool therefore asserts the invariant the label states: it sends the
+         * tour, and it verifies the rows that come back. Rows that contradict the
+         * requested level are dropped and counted rather than passed through as
+         * "close enough" — a filter that returns other-tour events is worse than a
+         * filter that returns nothing, because the caller has no way to notice.
+         */
+        const levelTourPrefix = (() => {
+            const m = /^(ATP|WTA)\b/i.exec(levelRaw);
+            return m ? m[1].toUpperCase() : null;
+        })();
+        if (levelTourPrefix && tourRaw && tourRaw !== levelTourPrefix) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `tour ('${tourRaw}') contradicts level ('${levelRaw}'), which names the ${levelTourPrefix} tour`,
+                game,
+                source: 'tournaments',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    `Drop tour, or set tour=${levelTourPrefix}`,
+                    'A level name that starts with ATP/WTA already determines the tour',
+                ],
+            });
+        }
+        const effectiveTour = tourRaw || levelTourPrefix || '';
+        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 } : {}),
+                ...(effectiveTour ? { tour: effectiveTour } : {}),
+                ...(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 rawItems = (Array.isArray(body.items) ? body.items : []).map(normalizeTournament);
+        // Verify the invariant the level label states. See levelTourPrefix above.
+        const contradictions = levelTourPrefix
+            ? rawItems.filter((t) => t.tour && t.tour.toUpperCase() !== levelTourPrefix)
+            : [];
+        const items = contradictions.length
+            ? rawItems.filter((t) => !t.tour || t.tour.toUpperCase() === levelTourPrefix)
+            : rawItems;
+        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,
+            effectiveTour || null,
+            levelRaw || null,
+            surface || null,
+            countryCode || null,
+            q ? `"${q}"` : null,
+        ].filter(Boolean);
+        const warnings = [];
+        if (contradictions.length) {
+            const sample = contradictions
+                .slice(0, 5)
+                .map((t) => `${t.id} (${t.tour})`)
+                .join(', ');
+            warnings.push(`The upstream level filter returned ${contradictions.length} tournament(s) that contradict level="${levelRaw}": ` +
+                `${sample}. They were dropped. The API's level reverse-map is not tour-aware (WTA 1000 resolves to tier codes ` +
+                `PM and M), which is a server-side defect; this tool sends tour=${levelTourPrefix} as well, so a repeat of this ` +
+                `warning means the upstream filter is widening again.`);
+        }
+        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,
+            warnings: warnings.length ? warnings : undefined,
+            data: {
+                title: filters.length > 0
+                    ? `Tennis tournaments — ${filters.join(' ')}`
+                    : 'Tennis tournaments',
+                filters: {
+                    year,
+                    tour: effectiveTour || null,
+                    level: levelRaw || null,
+                    surface: surface ?? null,
+                    countryCode: countryCode || null,
+                    q: q || null,
+                },
+                levelFilterIntegrity: {
+                    levelNamesTour: levelTourPrefix,
+                    rowsChecked: rawItems.length,
+                    contradictionsDropped: contradictions.length,
+                    ok: contradictions.length === 0,
+                },
+                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.21",
-  "description": "Standalone MCP server for the Cito esports and sports API — 36 curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
+  "version": "0.4.1",
+  "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"