cito-mcp 0.3.21 → 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/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.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.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"