cito-mcp 0.3.21 → 0.4.1

package/dist/tools/resolve.js

@@ -5,6 +5,13 @@ import { clampInt, decodeCursor, encodeCursor, extractRows, fetchJson, gameNotIn
 import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT, errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { editionYear, entityRef, rankScore } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
+/**
+ * Minimum relevance a search result must reach to be returned when a query was
+ * given. rankScore returns 0 for "no part of the query appears anywhere in this
+ * row", so 1 means "must have matched something". See the floor note in
+ * searchEntities for the live evidence.
+ */
+export const RELEVANCE_FLOOR = 1;
 /**
  * Ranking order whose tiebreak never depends on the order upstream happened to
  * return rows in.
@@ -840,33 +847,86 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             seen.add(key);
             return true;
         });
+        /**
+         * Relevance floor.
+         *
+         * The upstream player/tournament search is a substring match with no floor
+         * of its own: `q=Sinner` returns ten rows, of which only "Jannik Sinner" and
+         * "Martin Sinner" have anything to do with the query. The tool scored them
+         * all and then SORTED rather than filtered, so "A Winner", "J Skinner",
+         * "E Skinner", "C Sinkler", "Dr Sinnett", "H C Skinner", "Mrs Skinner" and
+         * "J J Sinnott" came back as equals — an agent asking for one player got
+         * eight strangers to ignore, and a caller paging the results paid for them.
+         *
+         * rankScore already separates them cleanly (Jannik 100, Martin 48, every
+         * other row 0), so the floor is simply "must have matched something at all".
+         * It is applied only when a query was given: with no q this tool is a browse
+         * list, and a floor there would delete the catalogue.
+         */
+        const scoreOf = (it) => typeof it.meta?.score === 'number'
+            ? it.meta.score
+            : rankScore(q, it.name, it.id, it.slug, it.meta?.nickname);
+        const upstreamTotal = total;
+        let droppedBelowFloor = [];
+        if (q) {
+            // Publish the score on every row, not just the ones the scored branch
+            // produced, so the floor is visible rather than mysterious.
+            items = items.map((it) => ({ ...it, meta: { ...(it.meta ?? {}), score: scoreOf(it) } }));
+            droppedBelowFloor = items
+                .filter((it) => it.meta?.score < RELEVANCE_FLOOR)
+                .map((it) => ({ id: it.id, name: it.name, score: it.meta?.score }));
+            if (droppedBelowFloor.length) {
+                items = items.filter((it) => it.meta?.score >= RELEVANCE_FLOOR);
+            }
+        }
         if (q && !preserveUpstreamOrder) {
-            items.sort((a, b) => {
-                const sa = typeof a.meta?.score === 'number' ? a.meta.score : rankScore(q, a.name, a.id, a.slug, a.meta?.nickname);
-                const sb = typeof b.meta?.score === 'number' ? b.meta.score : rankScore(q, b.name, b.id, b.slug, b.meta?.nickname);
-                return sb - sa || a.name.localeCompare(b.name);
-            });
+            items.sort((a, b) => scoreOf(b) - scoreOf(a) || a.name.localeCompare(b.name));
         }
         // pagination over ranked result set
         const pageItems = upstreamPaged ? items.slice(0, limit) : items.slice(offset, offset + limit);
         const hasMore = upstreamPaged
             ? (total != null ? offset + pageItems.length < total : pageItems.length >= limit)
             : offset + pageItems.length < items.length;
+        const floorWarnings = [];
+        if (droppedBelowFloor.length) {
+            const sample = droppedBelowFloor
+                .slice(0, 5)
+                .map((d) => `${d.name} (${d.id})`)
+                .join(', ');
+            floorWarnings.push(`Dropped ${droppedBelowFloor.length} result(s) that do not match "${q}" at all — the upstream search is a ` +
+                `substring match with no relevance floor, so it pads every page: ${sample}. ` +
+                `If one of these is what you wanted, query it by name or id directly.`);
+        }
         return successEnvelope({
             source: 'search_entities',
             game,
             requestId,
             tookMs: Date.now() - started,
             upstreamCalls,
+            warnings: floorWarnings.length ? floorWarnings : undefined,
             pagination: {
                 limit,
                 offset,
-                total: total ?? (q ? items.length : null),
+                total: q ? items.length : (total ?? null),
                 hasMore,
                 nextCursor: hasMore ? encodeCursor({ offset: offset + limit }) : null,
                 prevCursor: offset > 0 ? encodeCursor({ offset: Math.max(0, offset - limit) }) : null,
             },
-            data: { items: pageItems },
+            data: {
+                items: pageItems,
+                ...(q
+                    ? {
+                        relevance: {
+                            query: q,
+                            floor: RELEVANCE_FLOOR,
+                            matched: items.length,
+                            droppedBelowFloor: droppedBelowFloor.length,
+                            dropped: droppedBelowFloor.slice(0, 25),
+                            upstreamTotal: upstreamTotal ?? null,
+                        },
+                    }
+                    : {}),
+            },
         });
     },
 };

package/dist/tools/schedule.js

@@ -0,0 +1,323 @@
+/**
+ * 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,
+        /**
+         * Historical days report every match at T00:00:00 with
+         * `start_time_known: false` — the date is real, the clock is a placeholder.
+         * Emitting the midnight without this flag invites a caller to render "12:00
+         * AM" for a semi-final that finished at 3pm. Null when the route does not
+         * state it (the completed half does not).
+         */
+        startTimeKnown: typeof r.start_time_known === 'boolean' ? r.start_time_known : 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,
+    };
+}
+/** A row is "played" when the feed says so, in either spelling it uses. */
+function isPlayed(row) {
+    const r = asRecord(row) ?? {};
+    const s = (pickString(r.status, r.outcome) ?? '').toLowerCase();
+    return /complete|finished|ended|final|closed|done|official|retire|walkover|default/.test(s);
+}
+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.
+
+'limit' bounds EACH half (the completed route ignores ?limit= upstream, so the
+bound is applied here); scheduledCount/completedCount report how many rows the
+day held and *Returned how many came back. The two halves overlap: the day's
+list includes matches already played, so the same matchId can appear in both —
+see the overlap block before de-duplicating or counting.
+
+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, applied here (default 20, max 50). scheduledCount/completedCount still report the full day.' }),
+        },
+    },
+    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';
+        /**
+         * Ask for the whole day, then bound locally.
+         *
+         * /tennis/schedule honours ?limit= but /tennis/matches/completed ignores it,
+         * so passing `limit` upstream made `scheduledCount` mean "rows this call
+         * asked for" on one half and "rows the day held" on the other. Both halves
+         * are now fetched at the API's own page ceiling and sliced here, which makes
+         * scheduledCount/completedCount a fact about the day and *Returned a fact
+         * about the response.
+         */
+        const upstreamPage = 200;
+        const settled = await Promise.allSettled([
+            wantScheduled
+                ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit: upstreamPage } })
+                : Promise.resolve(null),
+            wantCompleted
+                ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit: upstreamPage } })
+                : Promise.resolve(null),
+        ]);
+        const rejected = [];
+        const rows = (value) => {
+            const root = asRecord(value);
+            const body = asRecord(root?.data) ?? root ?? {};
+            const items = Array.isArray(body.items) ? body.items : [];
+            return { items, total: typeof body.total === 'number' ? body.total : null };
+        };
+        let scheduled = [];
+        let completed = [];
+        let scheduledTotal = null;
+        let completedTotal = null;
+        const [schedRes, compRes] = settled;
+        if (schedRes.status === 'fulfilled' && schedRes.value) {
+            const v = schedRes.value;
+            if (v.ok) {
+                const parsed = rows(v.data);
+                scheduled = parsed.items;
+                scheduledTotal = parsed.total;
+            }
+            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) {
+                const parsed = rows(v.data);
+                completed = parsed.items;
+                completedTotal = parsed.total;
+            }
+            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'],
+            });
+        }
+        /**
+         * /tennis/matches/completed IGNORES ?limit= — verified: `limit=3` returned
+         * all 13 rows of the day with page_size still 50. /tennis/schedule does
+         * honour it, but both halves are bounded here so one call site cannot drift
+         * from the other and `completedCount` stops being a number the caller asked
+         * to be smaller.
+         */
+        const scheduledWindow = scheduled.slice(0, limit);
+        const completedWindow = completed.slice(0, limit);
+        /**
+         * /tennis/schedule is the DAY's list, not an "upcoming" list: it carries
+         * matches that have already finished, with status COMPLETED. So the two
+         * halves of this response legitimately overlap, and the old key name
+         * ("scheduled") plus a status of COMPLETED inside it read as a
+         * contradiction. The overlap is now counted and the statuses summarised, so
+         * a caller can join or de-duplicate deliberately instead of discovering it.
+         */
+        const completedBySchedule = scheduled.filter(isPlayed);
+        const completedIds = new Set(completed
+            .map((row) => pickString(asRecord(row)?.id, asRecord(row)?.match_id))
+            .filter((id) => Boolean(id)));
+        const overlapIds = [
+            ...new Set(completedBySchedule
+                .map((row) => pickString(asRecord(row)?.id, asRecord(row)?.match_id))
+                .filter((id) => typeof id === 'string' && completedIds.has(id))),
+        ];
+        const statusCounts = {};
+        for (const row of scheduled) {
+            const key = (pickString(asRecord(row)?.status, asRecord(row)?.outcome) ?? 'UNKNOWN').toUpperCase();
+            statusCounts[key] = (statusCounts[key] ?? 0) + 1;
+        }
+        const anyUnknownClock = scheduled.some((row) => asRecord(row)?.start_time_known === false);
+        const data = {
+            title: `Tennis — ${date}`,
+            date,
+            include: includeRaw,
+            // Everything the day's list returned, then the bounded window. Both are
+            // present so `scheduledCount` never silently means two different things.
+            scheduled: scheduledWindow.map(normalizeScheduled),
+            scheduledCount: scheduledTotal ?? scheduled.length,
+            scheduledReturned: scheduledWindow.length,
+            completed: completedWindow.map(normalizeScheduled),
+            completedCount: completedTotal ?? completed.length,
+            completedReturned: completedWindow.length,
+            statusBreakdown: statusCounts,
+            overlap: {
+                count: overlapIds.length,
+                matchIds: overlapIds.slice(0, 50),
+                note: overlapIds.length
+                    ? 'These matches appear in BOTH halves: /tennis/schedule is the day\'s full list (played matches included) and /tennis/matches/completed is the played subset. Join on matchId and de-duplicate.'
+                    : 'The two halves returned no shared matchId on this date.',
+            },
+            timezoneNote: 'The API groups by UTC date. For a local "today", pass the date explicitly rather than relying on the default.',
+            ...(anyUnknownClock
+                ? {
+                    startTimeNote: 'Rows with startTimeKnown:false carry a date-only startsAt (T00:00:00) — the clock is a placeholder, not a midnight start. The completed half does not report the flag at all.',
+                }
+                : {}),
+        };
+        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/standings.js

@@ -407,8 +407,24 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 rows,
                 total: allRows.length,
                 hasMore: allRows.length > rows.length,
-                updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
-                    null,
+                ...(game === 'tennis'
+                    ? {
+                        /**
+                         * Tennis rankings are a dated weekly SNAPSHOT, and the route names
+                         * the date in `ranking_date`. updatedAt was read only from
+                         * updatedAt/lastUpdated/meta.syncedAt/meta.fetchedAt, none of which
+                         * the tennis route emits, so every tennis table claimed
+                         * updatedAt:null while the very date a caller needs sat in the
+                         * payload — and a consumer showing a stale-looking table had no
+                         * way to find out it was a week old.
+                         */
+                        rankingDate: pickString(obj?.ranking_date) ?? null,
+                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt, obj?.ranking_date) ?? null,
+                    }
+                    : {
+                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
+                            null,
+                    }),
                 ...(dataFreshness ? { dataFreshness } : {}),
                 ...(status ? { status } : {}),
                 ...(upstreamMeta.warning || dataQuality.warning