cito-mcp 0.4.1 → 0.4.2

package/README.md

@@ -525,6 +525,19 @@ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 
 ## Changelog (summary)
 
+### 0.4.2
+
+Second tennis correctness pass, from the 2026-09-12 re-sweep. Five defects, each reproduced from a raw payload and re-verified after the fix. Two were upstream (fixed on the API and verified with the 40/40 invariant gate); three were MCP-side.
+
+- **`tennis_odds` called a nonexistent match "no coverage".** `/tennis/odds/{id}` answers **HTTP 200 with `coverage.odds=false` for every id it does not know** — verified for `s365_2026_0000000` and for the literal `total-garbage-id`. So a typo and a genuine no-book gap were indistinguishable and both came back `ok:true`. `scope=match`/`live` now verify the id against `/tennis/matches/{id}` (which does 404) when no odds are quoted: unknown id → `NOT_FOUND` with recovery steps, real match → an honest coverage gap with `matchExists: true`.
+- **Tennis `standings` published a fake total and could not be paged.** `/tennis/standings?top_n=5` set `rank_max=top_n`, so the count (which carried the rank bounds) equalled the page size: `total:5`, `hasMore:false` for a list of **150** ranked players. The API now counts the population without the rank window and returns `ranked_players`/`total_pages`/`has_next`, `/standings` takes a `page` argument, and the tool reports `total`/`rankedPlayers`/`totalPages`/`hasMore` — page 2 of the ATP list now starts at rank 6. The same `allRows.length` mistake in the `pagination` block was fixed too, so the two counts cannot disagree.
+- **`event_card` published the requested id as the event name.** With a bad id it answered `ok:true` and `event.name = "atp_2026_999999"` over a 404 that `partial[]` reported correctly. Names now come from the payload or are `null`, with `event.resolved` recording whether the detail fetch succeeded.
+- **`leaderboard_*` reported the page size as the population.** Every board returned `"total": len(items)` after applying `.limit(limit)`, so `limit=2` answered `total:2` — for boards whose own docs record thousands of qualifiers. Upstream now carries `count(*) OVER ()` (Postgres evaluates it after `GROUP BY`/`HAVING`, so it is exactly the qualifying population, at no extra round trip): aces **2488**, break-conversion **1089** (matching the figure in its own docstring), 1st-serve-won 1141, bp-saved 1186, return-games 987, tiebreak 364, deciders 334, comebacks 611, finals 66. Each tool also reports `returned` and the board's `minimumAttempts`.
+- **`resolve_entity { q: "Nole" }` answered "M Canoles".** The upstream name search puts Novak Djokovic first for `Nole` — it knows a nickname nothing in the payload carries, so `rankScore` scores it 0 — and the tool floored every unmatched row to 1 and then *sorted*, letting a substring collision win. `pushCandidates` now lets the upstream's own first row stand as the alias answer (labelled `meta.matchedBy: "upstream-first"`) when our scorer is silent, and `search_entities` exempts exactly that one row from its relevance floor. Padding is still dropped: `Sinner` still returns only Sinner.
+- **`/tennis/tournaments/calendar` silently ignored `?month=`.** FastAPI drops unknown query parameters, so `?month=9` and `?month=3` returned the identical 621-event season list and a caller asking "what is on in September" got the whole year. The route now takes `month` and filters on the event's start month (2026-09 → 12 events).
+- **`standings` and `leaderboards` were never cached**, so every call re-ran its grouped scan and paid db1's ~90ms RTT per query: 474–922ms on *every* request while every cached route answered in <20ms. That held eleven tools permanently over the 400ms latency budget. Both prefixes now have TTLs (1800s / 600s); repeat calls measure **4–5ms**.
+- **`bestOf`** now reads `best_of`, the only spelling the tennis route emits.
+
 ### 0.4.1
 
 Tennis correctness pass, driven by the 2026-09-12 sweep (`reports/tennis-mcp-sweep-2026-09-12.md`). Every item was reproduced against live ids and re-verified after the fix.

package/dist/tools/insight.js

@@ -882,10 +882,22 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 });
             }
         }
+        /**
+         * Seeded with the key but explicitly NOT resolved.
+         *
+         * `name: q || eventKey` used to put the raw requested id in the name slot,
+         * and the tennis branch then kept it whenever its detail fetch failed
+         * (`pickString(d.name) ?? event.name`). event_card { eventIdOrSlug:
+         * "atp_2026_999999" } therefore answered ok:true with
+         * event.name = "atp_2026_999999" — an id presented as a tournament name,
+         * over a 404 that the partial[] block reported correctly. A name is
+         * something the API supplied or it is null; an identifier is not a name.
+         */
         let event = {
             id: eventKey,
             slug: eventKey,
-            name: q || eventKey,
+            name: q || null,
+            resolved: false,
             game,
         };
         let bouts = [];
@@ -1308,7 +1320,11 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                     ...event,
                     id: pickString(d.id) ?? eventKey,
                     slug: pickString(d.id) ?? eventKey,
-                    name: pickString(d.name) ?? event.name,
+                    // Never fall back to event.name here: that is the requested key, and
+                    // this branch only runs when the detail fetch SUCCEEDED, so the name
+                    // comes from the payload or it is honestly absent.
+                    name: pickString(d.name, d.id) ?? null,
+                    resolved: true,
                     tour: pickString(d.tour) ?? null,
                     level: pickString(d.level) ?? null,
                     tier: pickString(d.tier) ?? null,
@@ -1446,7 +1462,7 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                     message: `dota tournament HTTP ${detail.status}`,
                     httpStatus: detail.status,
                 }));
-                event = { id: eventKey, slug: eventKey, name: q || eventKey, game };
+                event = { id: eventKey, slug: eventKey, name: q || null, resolved: false, game };
             }
             if (includeBouts) {
                 const matchesRes = await fetchJson(ctx, '/dota2/matches/upcoming', { query: { limit } });
@@ -1481,6 +1497,18 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 }));
             }
         }
+        /**
+         * Last line of defence against an identifier posing as a name.
+         *
+         * Every game branch seeds `event.name` from `q`/`eventKey` so a partially
+         * resolved card still has something in the slot. Any branch that failed and
+         * left that seed in place would publish "atp_2026_999999" as a tournament
+         * name, and nothing downstream can tell an id from a name. It is nulled
+         * here; `resolved` records that the detail fetch never succeeded.
+         */
+        if (event.resolved !== true && typeof event.name === 'string' && event.name === eventKey) {
+            event = { ...event, name: null, nameResolved: false };
+        }
         return successEnvelope({
             source: 'event_card',
             game,

package/dist/tools/leaderboard.js

@@ -156,13 +156,23 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const root = asRecord(res.data);
         const body = asRecord(root?.data) ?? root ?? {};
         const items = (Array.isArray(body.items) ? body.items : []).map(normalizeAceRow);
+        /**
+         * `total` is the QUALIFYING POPULATION, not the page.
+         *
+         * The API used to return len(items) AFTER applying .limit(limit), so limit=2
+         * answered total:2 for a board with thousands of eligible players and the
+         * caller had no way to tell a page from the whole board. It now carries
+         * count(*) OVER (), the count of players passing the board's own threshold.
+         * `returned` and `hasMore` are stated separately so the two can never be
+         * confused again, and the threshold is surfaced so the number is explicable.
+         */
         const total = typeof body.total === 'number' ? body.total : items.length;
         return successEnvelope({
             pagination: {
                 limit,
                 offset: 0,
                 total,
-                hasMore: false,
+                hasMore: items.length < total,
                 nextCursor: null,
                 prevCursor: null,
             },
@@ -179,6 +189,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 stat: pickString(body.stat) ?? 'aces',
                 items,
                 total,
+                returned: items.length,
+                ...(typeof body.minimum_attempts === 'number' ? { minimumAttempts: body.minimum_attempts } : {}),
             },
         });
     },
@@ -306,13 +318,15 @@ Parallel-safe: yes. Upstream cost: 1.`,
             const root = asRecord(res.data);
             const body = asRecord(root?.data) ?? root ?? {};
             const items = (Array.isArray(body.items) ? body.items : []).map(normalizeRow);
+            // Same contract as leaderboard_aces: total is the qualifying population,
+            // not the page. See the note there.
             const total = typeof body.total === 'number' ? body.total : items.length;
             return successEnvelope({
                 pagination: {
                     limit,
                     offset: 0,
                     total,
-                    hasMore: false,
+                    hasMore: items.length < total,
                     nextCursor: null,
                     prevCursor: null,
                 },
@@ -329,6 +343,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
                     stat: pickString(body.stat) ?? spec.stat,
                     items,
                     total,
+                    returned: items.length,
+                    ...(typeof body.minimum_attempts === 'number' ? { minimumAttempts: body.minimum_attempts } : {}),
                 },
             });
         },

package/dist/tools/odds.js

@@ -125,6 +125,10 @@ Do not use when: the match result → match_details; rankings → standings.
 Tennis-only. Odds are decimal. Coverage is partial upstream: a match with no
 priced bookmaker returns coverage.odds=false and an empty bookmakers[] rather
 than invented numbers, and this tool surfaces that distinction explicitly.
+A match id that does not exist is a NOT_FOUND error, not a coverage gap: the
+odds route answers 200/odds:false for every unknown id, so scope=match and
+scope=live verify the match against /tennis/matches/{id} before reporting a gap,
+and set matchExists.
 
 Parallel-safe: yes. Upstream cost: 1.`,
     inputSchema: {
@@ -259,6 +263,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
             ? `/tennis/odds/${encodeURIComponent(matchId)}`
             : `/tennis/odds/${encodeURIComponent(matchId)}/live`;
         const res = await fetchJson(ctx, path, {});
+        let upstreamCalls = 1;
+        let rateLimit = res.headers;
         if (!res.ok) {
             return errorEnvelope({
                 code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
@@ -274,13 +280,62 @@ Parallel-safe: yes. Upstream cost: 1.`,
             });
         }
         const summary = summarizeTennisOdds(res.data);
+        /**
+         * A match id that does not exist and a real match nobody is quoting look
+         * identical on the wire.
+         *
+         * /tennis/odds/{id} answers HTTP 200 with `coverage: { odds: false }` for
+         * EVERY id it does not know — verified for `s365_2026_0000000` (a plausible
+         * typo) and for the literal string `total-garbage-id`, both of which came
+         * back 200/odds:false. So the status code cannot tell them apart, and this
+         * tool used to report a typo as "upstream coverage gap, not an error" with
+         * ok:true — leaving the caller to conclude a real match has no prices.
+         *
+         * /tennis/matches/{id} DOES 404 for those same ids (verified: 404 NOT_FOUND
+         * for both, 200 for a real one), so that is the discriminator. It costs one
+         * extra call, and only on the no-odds path, where the answer is otherwise
+         * useless. player_stats already gets this right (404 -> NOT_FOUND); this
+         * makes odds agree with it.
+         */
+        let matchExists = null;
+        if (summary.oddsAvailable !== true) {
+            const probe = await fetchJson(ctx, `/tennis/matches/${encodeURIComponent(matchId)}`);
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...probe.headers };
+            matchExists = probe.ok;
+            if (!matchExists) {
+                // Live ids live at /matches/live/{id} until the match archives.
+                const liveProbe = await fetchJson(ctx, `/tennis/matches/live/${encodeURIComponent(matchId)}`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...liveProbe.headers };
+                matchExists = liveProbe.ok;
+            }
+            if (!matchExists) {
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: `No tennis match with id '${matchId}' — the odds feed has no event for it because the id itself does not exist`,
+                    game,
+                    source: 'tennis_odds',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit,
+                    httpStatus: 200,
+                    recover: [
+                        'Check the id with live_matches or tennis_schedule / match_summary',
+                        'Ids come from live_matches (s365_*) or the archive (s365_{year}_{gid})',
+                        `For the pre-match odds list instead, call tennis_odds { game: "tennis", scope: "upcoming" }`,
+                    ],
+                });
+            }
+        }
         return successEnvelope({
             source: 'tennis_odds',
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
-            rateLimit: res.headers,
+            upstreamCalls,
+            rateLimit,
             data: {
                 title: `Tennis ${scopeRaw} odds — ${matchId}`,
                 scope: scopeRaw,
@@ -288,6 +343,9 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 // returns. See summarizeTennisOdds.
                 ...summary,
                 matchId: summary.matchId ?? matchId,
+                // true when the no-odds path verified the match exists; null when odds
+                // existed so no verification was needed.
+                matchExists,
             },
         });
     },

package/dist/tools/resolve.js

@@ -44,7 +44,11 @@ const ORG_ALIASES = {
     skt1: 't1',
 };
 function pushCandidates(out, game, type, rows, q, limit) {
+    // Position within the upstream's own result list. That ordering is a real
+    // signal we otherwise throw away.
+    let index = -1;
     for (const row of rows) {
+        index += 1;
         const ref = entityRef(row, type, game);
         const r = asRecord(row) ?? {};
         const nickname = pickString(r.nickname, asRecord(r.profile)?.nickname, ref.meta?.nickname);
@@ -56,9 +60,26 @@ function pushCandidates(out, game, type, rows, q, limit) {
         if (score > 0 && Number.isFinite(currentRank) && currentRank > 0) {
             score += currentRank <= 100 ? 8 : currentRank <= 1000 ? 4 : 2;
         }
-        // Prefer positive fuzzy hits; keep weak API hits at floor 1 so real search results are not wiped.
-        if (q && score <= 0) {
-            // still allow through at floor so dedicated search endpoints aren't empty on odd nicknames
+        /**
+         * The upstream's FIRST row is allowed to match on something we cannot see.
+         *
+         * /tennis/players/search is a dedicated name search and it knows nicknames
+         * and aliases that the payload does not carry: `q=Nole` returns Novak
+         * Djokovic first, and nothing in the string "Novak Djokovic" resembles
+         * "nole", so rankScore scores it 0. The old code floored every unmatched row
+         * to 1 and then sorted, which let a mere substring collision win —
+         * `resolve_entity { q: "Nole" }` answered **M Canoles** (a WTA player whose
+         * name contains "noles") and search_entities dropped Djokovic entirely.
+         *
+         * So when our own scorer finds no name match at all but the dedicated search
+         * put the row first, the row is kept as the alias answer and labelled. Only
+         * the first row, and only when our scorer is silent, so this can never
+         * outrank a query that genuinely matches a name.
+         */
+        let matchedBy;
+        if (q && score <= 0 && index === 0) {
+            score = 95;
+            matchedBy = 'upstream-first';
         }
         const secondary = {};
         for (const key of ['lolPlayerId', 'codPlayerId', 'matchId', 'boutId', 'tournamentId', 'eventId']) {
@@ -68,6 +89,8 @@ function pushCandidates(out, game, type, rows, q, limit) {
         }
         if (nickname)
             secondary.nickname = nickname;
+        if (matchedBy)
+            secondary.matchedBy = matchedBy;
         out.push({
             game,
             type: pickString(r.entity_type, r.type, type) ?? type,
@@ -868,19 +891,49 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             : rankScore(q, it.name, it.id, it.slug, it.meta?.nickname);
         const upstreamTotal = total;
         let droppedBelowFloor = [];
+        /**
+         * The first row the upstream returned is exempt from the floor.
+         *
+         * The upstream's dedicated search knows aliases the payload does not carry:
+         * `q=Nole` returns Novak Djokovic first, and rankScore cannot see why, so a
+         * pure floor would delete the correct answer and keep substring collisions
+         * instead. Exactly one row is protected, and only when a query was given, so
+         * the floor still removes all the padding it was added for.
+         */
+        const protectedRow = q && items.length > 0 ? items[0] : null;
+        const protectedKey = protectedRow ? `${protectedRow.game}:${protectedRow.type}:${protectedRow.id}` : null;
         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) } }));
+            items = items.map((it) => {
+                const key = `${it.game}:${it.type}:${it.id}`;
+                const isProtected = protectedKey !== null && key === protectedKey;
+                const raw = scoreOf(it);
+                return {
+                    ...it,
+                    meta: {
+                        ...(it.meta ?? {}),
+                        score: raw,
+                        ...(isProtected && raw < RELEVANCE_FLOOR ? { matchedBy: 'upstream-first' } : {}),
+                    },
+                };
+            });
+            const keep = (it) => it.meta?.score >= RELEVANCE_FLOOR || it.meta?.matchedBy === 'upstream-first';
             droppedBelowFloor = items
-                .filter((it) => it.meta?.score < RELEVANCE_FLOOR)
+                .filter((it) => !keep(it))
                 .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 (droppedBelowFloor.length)
+                items = items.filter(keep);
         }
+        // An explicit (possibly rank-0) alias match beats a higher-scoring substring
+        // collision: the upstream's own top hit is the answer to a query we cannot
+        // score. This is what makes "Nole" resolve to Djokovic instead of M Canoles.
         if (q && !preserveUpstreamOrder) {
-            items.sort((a, b) => scoreOf(b) - scoreOf(a) || a.name.localeCompare(b.name));
+            items.sort((a, b) => {
+                const am = a.meta?.matchedBy === 'upstream-first' ? 1 : 0;
+                const bm = b.meta?.matchedBy === 'upstream-first' ? 1 : 0;
+                return bm - am || 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);

package/dist/tools/standings.js

@@ -126,6 +126,11 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             stage: stringSchema('Stage key (COD / LoL).'),
             division: stringSchema('UFC division key.'),
             limit: limitSchema({ default: 50, max: 100 }),
+            page: {
+                type: 'integer',
+                minimum: 1,
+                description: 'Tennis only: page over the full published ranking list. With limit=5 the ATP list is 30 pages (150 ranked players); the response reports total/rankedPlayers/totalPages/hasMore.',
+            },
             cursor: stringSchema('Opaque cursor from pagination.nextCursor. UFC world scope spans every division; page with it rather than raising limit.'),
         },
     },
@@ -155,6 +160,10 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         const season = typeof args.season === 'string' ? args.season : undefined;
         const stage = typeof args.stage === 'string' ? args.stage : undefined;
         const division = typeof args.division === 'string' ? args.division : undefined;
+        // Tennis rankings are pageable now that the API reports the real list size.
+        const tennisPage = typeof args.page === 'number' && Number.isFinite(args.page) && args.page >= 1
+            ? Math.trunc(args.page)
+            : 1;
         let path = '';
         let query = {};
         let title = `${game} standings`;
@@ -247,7 +256,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             // rank_movement/previous_rank on every row. Pass tour via division.
             const tour = String(division ?? 'ATP').toUpperCase() === 'WTA' ? 'WTA' : 'ATP';
             path = '/tennis/standings';
-            query = { tour, top_n: Math.min(limit, 100) };
+            query = { tour, top_n: Math.min(limit, 100), page: tennisPage };
             effectiveScope = 'world';
             title = `${tour} singles rankings`;
         }
@@ -355,16 +364,36 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 return rest;
             });
         }
+        const obj = asRecord(res.data);
+        const upstreamMeta = asRecord(obj?.meta) ?? {};
+        /**
+         * `total` is the size of the published table, NOT the size of this page.
+         *
+         * This read `total: allRows.length` — the rows that happened to arrive — so
+         * a tennis table of 150 ranked players reported total:5, hasMore:false and
+         * looked complete and unpaginated. The API now returns the real figure
+         * (total/ranked_players/total_pages/has_next); this prefers it and only
+         * falls back to the received count when the route does not state one.
+         *
+         * These are read BEFORE the pagination block, because that block had the
+         * identical bug: it published total: allRows.length too, so fixing only the
+         * data block left pagination.total disagreeing with data.total on the same
+         * response. Two counts, one response, only one of them true.
+         */
+        const upstreamTotal = typeof obj?.total === 'number' ? obj.total : null;
+        const rankedPlayers = typeof obj?.ranked_players === 'number' ? obj.ranked_players : null;
+        const totalPages = typeof obj?.total_pages === 'number' ? obj.total_pages : null;
+        const upstreamHasNext = typeof obj?.has_next === 'boolean' ? obj.has_next : null;
+        const effectiveTotal = upstreamTotal ?? allRows.length;
+        const effectiveHasMore = upstreamHasNext ?? offset + rows.length < effectiveTotal;
         const standingsPagination = {
             limit,
             offset,
-            total: allRows.length,
-            hasMore: offset + rows.length < allRows.length,
-            nextCursor: offset + rows.length < allRows.length ? String(offset + rows.length) : null,
+            total: effectiveTotal,
+            hasMore: effectiveHasMore,
+            nextCursor: effectiveHasMore ? String(offset + rows.length) : null,
             prevCursor: offset > 0 ? String(Math.max(0, offset - limit)) : null,
         };
-        const obj = asRecord(res.data);
-        const upstreamMeta = asRecord(obj?.meta) ?? {};
         const dataQuality = asRecord(upstreamMeta.dataQuality) ?? {};
         const warnings = [];
         const pushWarning = (value) => {
@@ -405,8 +434,16 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 season: season ?? null,
                 stage: stage ?? null,
                 rows,
-                total: allRows.length,
-                hasMore: allRows.length > rows.length,
+                total: effectiveTotal,
+                hasMore: effectiveHasMore,
+                ...(game === 'tennis'
+                    ? {
+                        // How deep the published list is, independent of this page.
+                        rankedPlayers: rankedPlayers ?? effectiveTotal,
+                        totalPages,
+                        page: tennisPage,
+                    }
+                    : {}),
                 ...(game === 'tennis'
                     ? {
                         /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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": {