cito-mcp 0.4.2 → 0.4.4

package/README.md

@@ -28,7 +28,6 @@ v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among t
 | Pre-match briefing (with surface) | `match_preview` |
 | Event / fight-night card | `event_card` |
 | Rivalry record | `head_to_head` |
-| Tennis betting odds | `tennis_odds` |
 | Tennis tournament catalog | `tournaments` |
 | One day of tennis | `tennis_schedule` |
 | Tennis player match log | `player_matches` |
@@ -213,9 +212,27 @@ When a key is `null` the image does not exist for that entity; when the whole
 never partially shaped — if any image exists, all four keys are present.
 
 Tennis is the exception on purpose: the feed supplies a single `portrait_url`
-(Wikimedia) and no square crop, so that one URL fills both `headshotUrl` and
-`imageUrl`, and `proxiedImageUrl` stays `null` because only `ufc.com` URLs have
-a proxy. A card with the real photo slightly cropped beats a faceless card.
+(Wikimedia Commons) and no square crop, so that one URL fills both `headshotUrl`
+and `imageUrl`, and `proxiedImageUrl` stays `null` because only `ufc.com` URLs have
+a proxy.
+
+**Tennis images carry their licence and credit** — and a UI is expected to render
+them:
+
+```jsonc
+"images": {
+  "headshotUrl": "https://commons.wikimedia.org/wiki/Special:FilePath/Hoang_WMQ18_%2833%29_%2842647295495%29.jpg?width=400",
+  "license":     "CC BY-SA 2.0",
+  "attribution": "si.robi",
+  "sourceUrl":   "https://commons.wikimedia.org/wiki/File:Hoang_WMQ18_(33)_(42647295495).jpg"
+}
+```
+
+Commons portraits are mostly CC BY / CC BY-SA, which for commercial display
+generally requires naming the author and stating the licence. `attribution` is
+`null` for public-domain and CC0 images, which need no credit — that is a fact,
+not missing data. Anything without a defensible licence has its URL removed
+upstream, so a non-null `headshotUrl` always has a `license` beside it.
 
 ### Games
 

package/dist/tools/index.js

@@ -9,7 +9,6 @@ import { rankingsTools } from './rankings.js';
 import { leaderboardTools } from './leaderboard.js';
 import { insightTools } from './insight.js';
 import { cs2Tools } from './cs2.js';
-import { oddsTools } from './odds.js';
 import { tournamentTools } from './tournaments.js';
 import { scheduleTools } from './schedule.js';
 /** Curated outcome-tool catalog. Order matches preferred cold-start ladder. */
@@ -25,7 +24,13 @@ export const allTools = [
     ...leaderboardTools,
     // Tennis depth added after the coverage audit: odds, tournament discovery and
     // the daily schedule were reachable only through call_api.
-    ...oddsTools,
+    //
+    // oddsTools REMOVED 2026-09-13. Tennis odds were withdrawn from the API
+    // (/tennis/odds/* is unmounted), so the tool would only ever call a 404.
+    // Betting data concentrates the legal risk and is the subject of every
+    // significant dispute researched — Swish Analytics v OddsJam is a data vendor
+    // suing rivals over scraped odds. See docs/tennis-risk-register.md.
+    // To restore: re-add `...oddsTools,` here and remount odds_router in the API.
     ...tournamentTools,
     ...scheduleTools,
     ...insightTools,

package/dist/tools/match.js

@@ -4,7 +4,10 @@
 import { extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { normalizeMatch, normalizeUfcMethod, presentSides, tennisSetCompleted } from './normalize.js';
-import { summarizeTennisOdds } from './odds.js';
+// summarizeTennisOdds was used here for the tennis odds section. Tennis odds were
+// withdrawn 2026-09-13 (see docs/tennis-risk-register.md), so this module no
+// longer imports it. The shaper still exists and is still exported from
+// ./odds.js for the day the surface is restored.
 import { boolSchema, gameSchema, isPrimaryGame, parseGame, stringSchema, } from './types.js';
 async function getSection(ctx, path, query) {
     return fetchJson(ctx, path, { query });
@@ -552,15 +555,127 @@ export function summarizeUfcOdds(data) {
         fullBookPath: '/ufc/bouts/{boutId}/odds',
     };
 }
+/**
+ * Per-period ("ALL / 1ST / 2ND / 3RD") statistics.
+ *
+ * The REST route gained `set_stats`: the same serving/returning figures split by
+ * set. Every field is nullable and a null is a STATEMENT, not a zero -- 0 aces is
+ * a claim, "we do not know" is not. `missing` names the nulls per side and `gaps`
+ * says why each one is absent, so a caller can tell these three apart:
+ *   PERIOD_NO_STATS          no stats exist for that period at all
+ *   INCOMPLETE_PERIOD_STATS  the period exists but a field is unknown
+ *   SOURCE_UNAVAILABLE / SOURCE_NOT_MAPPED
+ *                            a source was consulted and did not deliver
+ * Collapsing any of that into zero, or dropping `gaps`, would delete the very
+ * information that makes the block trustworthy.
+ */
+export function summarizeTennisSetStats(block) {
+    const b = asRecord(block);
+    if (!b)
+        return null;
+    const arr = (v) => (Array.isArray(v) ? v : []);
+    const strings = (v) => arr(v).map(String);
+    /**
+     * An object carrying nothing at all is not a block: the API sends
+     * `set_stats: null` when it has no rows, so `{}` can only be a caller's stub,
+     * and `setStats: null` says "no information" more honestly than a block of
+     * empty arrays. A block with ONLY gaps is kept, because the gaps are the
+     * information.
+     */
+    if (!arr(b.periods).length && !arr(b.gaps).length && !arr(b.sources).length
+        && typeof b.note !== 'string') {
+        return null;
+    }
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    const str = (v) => (typeof v === 'string' ? v : null);
+    const line = (side) => {
+        const s = asRecord(side) ?? {};
+        return {
+            aces: num(s.aces),
+            doubleFaults: num(s.double_faults),
+            firstServePct: num(s.first_serve_pct),
+            firstServeWonPct: num(s.first_serve_win_pct),
+            secondServeWonPct: num(s.second_serve_win_pct),
+            breakPointsSaved: num(s.break_points_saved),
+            breakPointsFaced: num(s.break_points_faced),
+            breakPointsConverted: num(s.break_points_converted),
+            breakPointOpportunities: num(s.break_point_opportunities),
+            totalPointsWon: num(s.total_points_won),
+            servicePointsPlayed: num(s.serve_points),
+            servicePointsWon: num(s.service_points_won),
+            gamesWon: num(s.games_won),
+        };
+    };
+    return {
+        periods: arr(b.periods).map((p) => {
+            const pr = asRecord(p) ?? {};
+            const missing = asRecord(pr.missing) ?? {};
+            return {
+                period: str(pr.period) ?? 'ALL',
+                setNumber: num(pr.set_number) ?? 0,
+                status: str(pr.status) ?? 'partial',
+                sources: strings(pr.sources),
+                winner: line(pr.winner),
+                loser: line(pr.loser),
+                missing: { winner: strings(missing.winner), loser: strings(missing.loser) },
+            };
+        }),
+        sources: arr(b.sources).map((s) => {
+            const sr = asRecord(s) ?? {};
+            return {
+                source: str(sr.source) ?? 'unknown',
+                status: str(sr.status) ?? 'unknown',
+                fields: strings(sr.fields),
+                detail: str(sr.detail),
+            };
+        }),
+        gaps: arr(b.gaps).map((g) => {
+            const gr = asRecord(g) ?? {};
+            return {
+                code: str(gr.code) ?? 'UNKNOWN',
+                period: str(gr.period),
+                setNumber: num(gr.set_number),
+                side: str(gr.side),
+                fields: strings(gr.fields),
+                source: str(gr.source),
+                status: str(gr.status),
+                message: str(gr.message) ?? '',
+            };
+        }),
+        note: str(b.note),
+    };
+}
+/**
+ * One line per stated absence, for the envelope's meta.warnings. The gaps also
+ * ride inside the section; this is what makes them visible to a client that only
+ * reads the envelope.
+ */
+export function tennisSetStatsWarnings(block) {
+    const shaped = summarizeTennisSetStats(block);
+    if (!shaped)
+        return [];
+    const gaps = shaped.gaps ?? [];
+    const out = [];
+    for (const gap of gaps) {
+        const where = [gap.period, gap.side].filter(Boolean).join(' ');
+        out.push(`set_stats ${gap.code}${where ? ` (${where})` : ''}: ${gap.message}`);
+    }
+    // One warning per distinct code is enough for a client that only needs to know
+    // the block is not fully populated; the section carries the detail.
+    const note = shaped.note;
+    if (gaps.length && typeof note === 'string')
+        out.unshift(`set_stats: ${note}`);
+    return out.slice(0, 6);
+}
 /**
  * Tennis per-match stats projection.
  *
  * `/tennis/matches/{id}/stats` does NOT return a row per player the way every
  * other game's player-stats route does. It returns
- * `{ stats: { winner: {...}, loser: {...} }, sets: [...], score }` — two objects
- * keyed by OUTCOME. `match_details sections:["playerStats"]` had no tennis arm
- * at all, so it answered `playerStats: null` while `match_summary` was filling
- * `playerPerformances` from the same route.
+ * `{ stats: { winner: {...}, loser: {...} }, sets: [...], score, set_stats }` —
+ * two objects keyed by OUTCOME. `match_details sections:["playerStats"]` had no
+ * tennis arm at all, so it answered `playerStats: null` while `match_summary`
+ * was filling `playerPerformances` from the same route.
  *
  * The sides stay keyed by outcome rather than being mislabelled as player1 /
  * player2, because the payload carries no names and the ordering is not
@@ -595,6 +710,9 @@ export function summarizeTennisMatchStats(data) {
                 completed: tennisSetCompleted(sr),
             };
         }),
+        // ALL / 1ST / 2ND / 3RD ... Null when the API has no per-period rows for
+        // this match, which is a different statement from an ingested empty period.
+        setStats: summarizeTennisSetStats(payload.set_stats),
         rawPath: '/tennis/matches/{matchId}/stats',
     };
 }
@@ -632,7 +750,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
                     type: 'string',
                     enum: ['base', 'playerStats', 'gamesOrMaps', 'timeline', 'liveState', 'media', 'advanced', 'odds'],
                 },
-                description: 'Explicit section list; defaults to base+playerStats+gamesOrMaps+media. "odds" is opt-in: UFC returns moneyline summarised per fighter with bookmaker count, best and median American price and implied probability plus a count of every other market (closing lines for a finished fight come back with currentlyOffered=false rather than being omitted); tennis returns the same bookmaker/market/outcome projection that tennis_odds serves, including oddsAvailable=false when no book is quoting. Odds exist for UFC and tennis only.',
+                description: 'Explicit section list; defaults to base+playerStats+gamesOrMaps+media. "odds" is opt-in: UFC returns moneyline summarised per fighter with bookmaker count, best and median American price and implied probability plus a count of every other market (closing lines for a finished fight come back with currentlyOffered=false rather than being omitted). Tennis odds were withdrawn alongside the /tennis/odds/* routes, so for any other game the section reports NOT_IMPLEMENTED. Odds exist for UFC only.',
             },
             includeTimeline: boolSchema('Include timeline section (heavy).', false),
             includeLiveState: boolSchema('Include live state/snapshots.', false),
@@ -835,17 +953,15 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
             if (game === 'ufc') {
                 loadWith('odds', `/ufc/bouts/${encodeURIComponent(matchId)}/odds`, summarizeUfcOdds);
             }
-            else if (game === 'tennis') {
-                // The gate that produced "Odds not curated for tennis; UFC only today"
-                // was written before /tennis/odds/{id} existed. It does: the same match
-                // returned FanDuel 1.105 / Matchbook 1.13 from tennis_odds while this
-                // section denied odds existed. Both surfaces now share one projection.
-                loadWith('odds', `/tennis/odds/${encodeURIComponent(matchId)}`, summarizeTennisOdds);
-            }
             else {
+                // Tennis odds were REMOVED 2026-09-13 alongside the /tennis/odds/* routes.
+                // Betting data concentrates the legal risk and is the subject of every
+                // significant dispute researched (see docs/tennis-risk-register.md), so
+                // it is no longer offered. Requesting the section is now an explicit
+                // NOT_IMPLEMENTED rather than a call to a route that returns 404.
                 partial.push(partialFromRejection('odds', {
                     code: 'NOT_IMPLEMENTED',
-                    message: `Odds are not curated for ${game}. Available: UFC (/ufc/bouts/{id}/odds) and tennis (/tennis/odds/{id}).`,
+                    message: `Odds are not curated for ${game}. Currently available: UFC (/ufc/bouts/{id}/odds). Tennis odds were withdrawn.`,
                 }));
             }
         }
@@ -872,6 +988,15 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
             }
         }
         await Promise.all(tasks);
+        // Per-period coverage gaps ride in meta.warnings as well as inside the
+        // playerStats section, so a client that only reads the envelope still learns
+        // that the ALL / 1ST / 2ND / 3RD block is not fully populated and why.
+        const warnings = [];
+        if (game === 'tennis') {
+            const ps = asRecord(sections.playerStats);
+            if (ps)
+                warnings.push(...tennisSetStatsWarnings(ps.setStats));
+        }
         return successEnvelope({
             source: 'match_details',
             game,
@@ -879,6 +1004,7 @@ Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "in
             tookMs: Date.now() - started,
             upstreamCalls,
             rateLimit,
+            warnings: warnings.length ? warnings : undefined,
             partial: partial.length ? partial : undefined,
             entities: { games: [game], ids: { matchId, ...(gameId ? { gameId } : {}) } },
             data: {

package/dist/tools/meta.js

@@ -186,16 +186,6 @@ const TOOL_CATALOG = [
         preferOver: ['raw rankings history via call_api'],
         doNotUse: 'Latest snapshot → standings; week-over-week delta → rankings_movers',
     },
-    {
-        name: 'tennis_odds',
-        outcome: 'Tennis betting odds: upcoming matches with prices, plus pre-match and in-play for one match; upcoming rows carry a joinKey and playerIds because the feed leaves match_id null',
-        parallelSafe: true,
-        games: ['tennis'],
-        jobs: ['preview', 'match_page', 'odds'],
-        exampleArgs: { game: 'tennis', scope: 'upcoming', limit: 20 },
-        preferOver: ['raw odds via call_api', 'match_preview (no prices)'],
-        doNotUse: 'The result → match_details; rankings → standings',
-    },
     {
         name: 'tournaments',
         outcome: 'Tennis tournament catalog: filter by year, tour, level, surface or country; a level name that names a tour also fixes it',

package/dist/tools/player.js

@@ -54,16 +54,29 @@ function identityFrom(game, raw, idHint, slugHint) {
          */
         images: {
             // Tennis supplies exactly one likeness, `portrait_url` (a Wikimedia
-            // portrait), and no separate square headshot crop. Before this, the shaper
-            // read only headshotUrl/bodyImageUrl/imageUrl/photoUrl — none of which the
-            // tennis route emits — so every tennis profile shipped four explicit nulls
-            // while a perfectly good photo sat one key away, and builders concluded
-            // tennis had no images at all. The portrait fills the headshot slot too:
-            // a card with the real photo slightly cropped beats a faceless card.
+            // Commons portrait), and no separate square headshot crop. Before this,
+            // the shaper read only headshotUrl/bodyImageUrl/imageUrl/photoUrl — none of
+            // which the tennis route emits — so every tennis profile shipped four
+            // explicit nulls while a perfectly good photo sat one key away.
             headshotUrl: pickString(r.headshotUrl, r.headshot, r.portrait_url) ?? null,
             bodyImageUrl: pickString(r.bodyImageUrl, r.fullBodyImageUrl) ?? null,
             imageUrl: pickString(r.imageUrl, r.image, r.photoUrl, r.portrait_url) ?? null,
             proxiedImageUrl: pickString(r.proxiedImageUrl, r.proxiedHeadshotUrl) ?? null,
+            /**
+             * The licence and the credit, carried with the URL.
+             *
+             * Commons portraits are mostly CC BY / CC BY-SA, which for commercial
+             * display generally obliges you to name the author and state the licence.
+             * Handing back a bare URL and letting a builder render it silently is what
+             * gets a product a takedown letter, so the fields a UI must show travel in
+             * the same object as the image. `attribution` is null for public-domain
+             * and CC0 images, which need no credit — that is a fact, not missing data.
+             * Anything without a defensible licence has its URL removed upstream, so a
+             * non-null headshotUrl here always has a licence beside it.
+             */
+            license: pickString(r.portrait_license) ?? null,
+            attribution: pickString(r.portrait_attribution) ?? null,
+            sourceUrl: pickString(r.portrait_source_url) ?? null,
         },
     };
 }

package/dist/tools/resolve.js

@@ -892,15 +892,25 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
         const upstreamTotal = total;
         let droppedBelowFloor = [];
         /**
-         * The first row the upstream returned is exempt from the floor.
+         * The upstream's own top ENTITY row 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.
+         * instead.
+         *
+         * This used to be the global items[0], which was wrong: search_entities
+         * merges several sources CONCURRENTLY (for tennis, /players/search and
+         * /competitions), so whichever promise settled first decided which row got
+         * protected. The live gate caught it as a flaky "first result is Jannik
+         * Sinner" — a competition could land at index 0 and the alias protection
+         * would guard the wrong thing. Only entity rows (player/team/fighter) are
+         * alias-matched at all; tournaments are matched by name and have no
+         * nicknames, so taking the first entity row is both deterministic and the
+         * row the rule was written for.
          */
-        const protectedRow = q && items.length > 0 ? items[0] : null;
+        const ENTITY_TYPES = new Set(['player', 'team', 'fighter']);
+        const protectedRow = q ? items.find((it) => ENTITY_TYPES.has(it.type)) ?? null : 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

package/package.json

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