cito-mcp 0.5.8 → 0.6.1

package/README.md

@@ -43,7 +43,7 @@ Composites multi-fetch server-side, return a **stable JSON envelope**, and isola
 
 ### Honest gaps, in-band
 
-Where the source data is partial, the tool says so instead of shipping a plausible-looking wrong value:
+Where data is partial, the tool says so instead of shipping a plausible-looking wrong value:
 
 | Situation | What the tool returns |
 | --- | --- |
@@ -116,7 +116,7 @@ Windows local clone:
   "mcpServers": {
     "cito": {
       "command": "node",
-      "args": ["C:/Users/Owner/Projects/cito-api-scraper-windows/mcp/dist/index.js"],
+      "args": ["/absolute/path/to/cito-mcp/dist/index.js"],
       "env": {
         "CITO_API_KEY": "cito_your_key_here"
       }
@@ -137,7 +137,7 @@ The server **exits immediately** if `CITO_API_KEY` is missing. The key is sent o
 
 | Variable | Required | Default | Description |
 | --- | --- | --- | --- |
-| `CITO_API_KEY` | **yes** | — | Cito API key → `x-api-key` on every upstream call |
+| `CITO_API_KEY` | **yes** | — | Cito API key → `x-api-key` on every API call |
 | `CITO_API_BASE` | no | `https://api.citoapi.com/api/v1` | Override base URL (staging / self-hosted) |
 
 ---
@@ -160,7 +160,7 @@ Mnemonic: **resolve → live/schedule → summary → deep**.
 
 ## Tool catalog (16)
 
-All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (the server name already brands the surface).
+All tools are **read-only** except the webhook tools (`create_webhook`, `update_webhook`, `delete_webhook`, `regenerate_webhook_secret`, `test_webhook`, `replay_webhook`, `catch_up_webhook`, and the inbox tools), which only touch your own webhooks and test inboxes. Names are `snake_case` with **no** `cito_` prefix (the server name already brands the surface).
 
 | Tool | Outcome | When to use | When not to use | Key inputs |
 | --- | --- | --- | --- | --- |
@@ -183,7 +183,7 @@ All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (
 
 ### Images
 
-Fighter and team sides carry an `images` object wherever upstream supplies one —
+Fighter and team sides carry an `images` object wherever one exists —
 on `event_card` bout corners and on `player_profile`. No extra call, no N+1.
 
 ```jsonc
@@ -206,11 +206,11 @@ hotlink-block, so raw URLs render as broken images in a web UI. The proxied URL
 is served by the API and is safe to put in an `<img src>`.
 
 When a key is `null` the image does not exist for that entity; when the whole
-`images` object is absent, upstream sent nothing for that side. The object is
+`images` object is absent, there is no image for that side. The object is
 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 Commons) and no square crop, so that one URL fills both `headshotUrl`
+Tennis is the exception on purpose: there is a single `portrait_url`
+and no square crop, so that one URL fills both `headshotUrl`
 and `imageUrl`, and `proxiedImageUrl` stays `null` because only fighter image URLs have
 a proxy.
 
@@ -229,8 +229,8 @@ them:
 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.
+not missing data. Anything without a defensible licence has its URL removed,
+so a non-null `headshotUrl` always has a `license` beside it.
 
 ### Games
 
@@ -285,11 +285,11 @@ Every tool returns one JSON object:
   "data": {},
   "meta": {
     "game": "cs2",
-    "source": "match_summary",
+    "tool": "match_summary",
     "fetchedAt": "2026-07-27T12:00:00.000Z",
     "requestId": "mcp_…",
     "tookMs": 120,
-    "upstreamCalls": 3,
+    "apiCalls": 3,
     "rateLimit": { "tier": "pro", "remaining": 54 }
   },
   "pagination": { "limit": 20, "hasMore": false, "nextCursor": null },
@@ -304,11 +304,11 @@ Every tool returns one JSON object:
 | `ok: true` with `partial[]` | Use successful sections; **do not** treat as total failure |
 | List tools | `data.items` + `pagination` (`limit`, `hasMore`, `nextCursor`, …) |
 
-**Error codes:** `VALIDATION` · `NOT_FOUND` · `UNSUPPORTED_GAME` · `UNAUTHORIZED` · `RATE_LIMIT` · `UPSTREAM` · `PATH_NOT_ALLOWED` · `NOT_IMPLEMENTED`
+**Error codes:** `VALIDATION` · `NOT_FOUND` · `UNSUPPORTED_GAME` · `UNAUTHORIZED` · `RATE_LIMIT` · `SERVICE_ERROR` · `PATH_NOT_ALLOWED` · `NOT_IMPLEMENTED`
 
 **Ambiguity:** `resolve_entity` returns `ok: true` with `data.needsDisambiguation` + `data.candidates` — pick a candidate; do not wait for a hard error.
 
-Retry only when `error.retryable` is true (typically `RATE_LIMIT`, `UPSTREAM`).
+Retry only when `error.retryable` is true (typically `RATE_LIMIT`, `SERVICE_ERROR`).
 
 **Pagination:** default limit 20, max 50 (some tools clamp differently). Honor `pagination.hasMore` and pass `pagination.nextCursor` only — never invent cursors or reuse them after changing filters.
 
@@ -417,7 +417,7 @@ Use these as agent playbooks when scaffolding apps. Prefer one composite per scr
 | URI | Purpose |
 | --- | --- |
 | `cito://capabilities` | Static tool / game / workflow summary |
-| `cito://llms.txt` | Live product agent context (may 404 upstream) |
+| `cito://llms.txt` | Live product agent context |
 | `cito://openapi.json` | Live public OpenAPI for **typed clients** — not for tool generation |
 
 ---
@@ -560,9 +560,9 @@ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 
 ### 0.5.6
 
-- **Tennis `event_card` draw is a real bracket** (customer audit 2026-11-03). `draw.complete` is true only when every main round to the Final is played (it said true beside `missingRounds` F/SF/QF); every main round is listed with `status` (`completed` / `in_progress` / `not_started` / `incomplete_archive`), `expected` (byes excluded: a 56 draw's R64 holds 24), `byes`, `walkovers`, and `pending` (scheduled / live matches, never presented as results). `drawSize` is the real field (Paris 56, `drawSizeSource`, `bracketSize`, `byes`); `matchesExpected` counts the main draw and is compared with `mainDrawMatchesReturned` (qualifying is reported apart). Each bout carries `winnerId` / `loserId` / `outcome` (a "6-3 6-7 RET" retirement says who won), `startTime`, `nextMatchId` (the bracket edge) and `bracketPosition`; rounds report `included` / `omitted` when `drawMaxMatches` trims them.
+- **Tennis `event_card` draw is a real bracket** (customer audit 2026-11-03). `draw.complete` is true only when every main round to the Final is played (it said true beside `missingRounds` F/SF/QF); every main round is listed with `status` (`completed` / `in_progress` / `not_started` / `incomplete_archive`), `expected` (byes excluded: a 56 draw's R64 holds 24), `byes`, `walkovers`, and `pending` (scheduled / live matches, never presented as results). `drawSize` is the real field (Paris 56, `bracketSize`, `byes`); `matchesExpected` counts the main draw and is compared with `mainDrawMatchesReturned` (qualifying is reported apart). Each bout carries `winnerId` / `loserId` / `outcome` (a "6-3 6-7 RET" retirement says who won), `startTime`, `nextMatchId` (the bracket edge) and `bracketPosition`; rounds report `included` / `omitted` when `drawMaxMatches` trims them.
 - **Tennis `head_to_head` honours `limit`**: it is sent to `/tennis/h2h`, which pages the meetings while every tally still covers all of them (`meetingsReturned` / `meetingsTotal`; the H2H `level_breakdown` now always sums to `total_matches`).
-- Other tennis audit fixes in the same release: live stats as structured numerator / denominator / pct, `isSimulated` / `liveFeed` on live rows, `setNumber` from `set_number`, and the schedule / rankings / player readers updated for the API changes of 2026-11-03.
+- Other tennis audit fixes in the same release: live stats as structured numerator / denominator / pct, `isSimulated` on live rows, `setNumber` from `set_number`, and the schedule / rankings / player readers updated for the API changes of 2026-11-03.
 
 ### 0.5.5
 
@@ -597,12 +597,12 @@ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 
 ### 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.
+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 fixed on the API; three in the MCP.
 
 - **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.
+- **`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. The total is now exactly the qualifying population: 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 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 search's own first row stand as the alias answer (labelled `meta.matchedBy: "top-hit"`) 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.
@@ -614,7 +614,7 @@ Tennis correctness pass, driven by the 2026-09-12 sweep (`reports/tennis-mcp-swe
 - **`match_summary` tennis scoreline was always `- : -`.** `/tennis/matches/{id}` puts no `sets_won` on its player objects, so the sets-won score was null for every completed match while the same payload held the real score in `score` and `sets[]`. Sets won are now derived (explicit → `winner_sets_won` → `sets[]` → `score` string), `score.detail` carries the game score, and a set's `completed` is inferred when the archive omits `is_completed`. The winner-oriented `winner_games`/`loser_games` pair is deliberately not used as a side score. `bestOf` now reads `best_of`.
 - **`player_stats.bySurface` was always four nulls.** The endpoint publishes one object per surface and the projector coerced each to a number. Real per-surface blocks, `servingStats`, and an explicit `unavailable` map for sections the endpoint does not publish.
 - **`limit` was ignored** by `player_rankings_history` (asked 4, got 342) and by `/tennis/matches/completed`. Both are bounded locally now, with `*Returned` versus `*Count` so the day total is never confused with the page.
-- **`tournaments level="WTA 1000"` returned ATP Masters events.** The API's level reverse-map is not tour-aware (`_TIER_WTA` maps both `PM` and `M` to "WTA 1000"), so the tool now sends and enforces the tour the level name states, and drops + counts contradicting rows. Fixed at the source too — the same widening also leaked `WTA 125`, `Challenger`, `Davis Cup` and `Billie Jean King Cup`.
+- **`tournaments level="WTA 1000"` returned ATP Masters events.** The tool now sends and enforces the tour the level name states, and drops + counts contradicting rows. Fixed at the source too — the same widening also leaked `WTA 125`, `Challenger`, `Davis Cup` and `Billie Jean King Cup`.
 - **`rankings_movers` called an 84-day gap "week-over-week".** `gapDays`/`comparisonWindow`/`comparisonsAreWeekly` now state the real interval, with a warning. `standings` reports the tennis `ranking_date` as `updatedAt` instead of `null`.
 - **`tennis_schedule`** now counts the day's list/completed overlap, summarises statuses, and flags date-only `startsAt` placeholders.
 - **`live_matches` labelled tennis rows by tournament**, not players, because the live route's `name` is the event.

package/dist/client.js

@@ -1,4 +1,4 @@
-import { MAX_RATE_LIMIT_RETRIES, MAX_UPSTREAM_RETRIES, MAX_WAIT_MS, UPSTREAM_BACKOFF_MS, classify429, getClock, jitterMs, newCallBudget, pacerFor, } from './pacing.js';
+import { MAX_RATE_LIMIT_RETRIES, MAX_SERVER_RETRIES, MAX_WAIT_MS, SERVER_BACKOFF_MS, classify429, getClock, jitterMs, newCallBudget, pacerFor, } from './pacing.js';
 import { PACKAGE_VERSION } from './version.js';
 export const DEFAULT_API_BASE = 'https://api.citoapi.com/api/v1';
 export const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024;
@@ -87,7 +87,7 @@ export async function fetchJson(ctx, path, opts) {
     const pacer = pacerFor(ctx.apiKey);
     const clock = getClock();
     let rateLimitRetries = 0;
-    let upstreamRetries = 0;
+    let serverRetries = 0;
     for (;;) {
         const gate = await pacer.acquire(budget);
         if (!gate.ok) {
@@ -117,7 +117,7 @@ export async function fetchJson(ctx, path, opts) {
                 text,
                 url,
                 rateLimit: event,
-                retries: rateLimitRetries + upstreamRetries,
+                retries: rateLimitRetries + serverRetries,
             };
         }
         let response;
@@ -162,9 +162,9 @@ export async function fetchJson(ctx, path, opts) {
             }
         }
         else if (response.status === 502 || response.status === 503) {
-            const wait = UPSTREAM_BACKOFF_MS + jitterMs();
-            if (upstreamRetries < MAX_UPSTREAM_RETRIES && clock.now() + wait < budget.deadline) {
-                upstreamRetries += 1;
+            const wait = SERVER_BACKOFF_MS + jitterMs();
+            if (serverRetries < MAX_SERVER_RETRIES && clock.now() + wait < budget.deadline) {
+                serverRetries += 1;
                 budget.retries += 1;
                 budget.waitedMs += wait;
                 log(`${response.status} on ${path}; retry after ${wait} ms`);
@@ -184,8 +184,8 @@ export async function fetchJson(ctx, path, opts) {
         };
         if (limited)
             result.rateLimit = limited;
-        if (rateLimitRetries + upstreamRetries > 0)
-            result.retries = rateLimitRetries + upstreamRetries;
+        if (rateLimitRetries + serverRetries > 0)
+            result.retries = rateLimitRetries + serverRetries;
         return result;
     }
 }

package/dist/envelope.js

@@ -25,7 +25,7 @@ export const DEFAULT_RECOVER = {
         'Verify CITO_API_KEY is set and valid',
         'Call api_health to confirm tier and included games',
     ],
-    UPSTREAM: [
+    SERVICE_ERROR: [
         'Retry this tool once',
         'If it still fails, narrow params (limit, date range) or use a smaller tool',
     ],
@@ -64,8 +64,8 @@ export function mapHttpToCode(status, hints) {
     if (status === 400 || status === 422)
         return 'VALIDATION';
     if (status >= 500 || status === 0)
-        return 'UPSTREAM';
-    return 'UPSTREAM';
+        return 'SERVICE_ERROR';
+    return 'SERVICE_ERROR';
 }
 export function newRequestId() {
     return `mcp_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
@@ -73,15 +73,15 @@ export function newRequestId() {
 export function successEnvelope(args) {
     const meta = {
         game: args.game,
-        source: args.source,
+        tool: args.source,
         fetchedAt: args.fetchedAt ?? new Date().toISOString(),
     };
     if (args.requestId)
         meta.requestId = args.requestId;
     if (args.tookMs !== undefined)
         meta.tookMs = args.tookMs;
-    if (args.upstreamCalls !== undefined)
-        meta.upstreamCalls = args.upstreamCalls;
+    if (args.apiCalls !== undefined)
+        meta.apiCalls = args.apiCalls;
     if (args.rateLimit)
         meta.rateLimit = args.rateLimit;
     if (args.warnings?.length)
@@ -103,18 +103,18 @@ export function successEnvelope(args) {
 }
 export function errorEnvelope(args) {
     const retryable = args.retryable ??
-        (args.code === 'RATE_LIMIT' || args.code === 'UPSTREAM');
+        (args.code === 'RATE_LIMIT' || args.code === 'SERVICE_ERROR');
     const meta = {
         game: args.game,
-        source: args.source,
+        tool: args.source,
         fetchedAt: args.fetchedAt ?? new Date().toISOString(),
     };
     if (args.requestId)
         meta.requestId = args.requestId;
     if (args.tookMs !== undefined)
         meta.tookMs = args.tookMs;
-    if (args.upstreamCalls !== undefined)
-        meta.upstreamCalls = args.upstreamCalls;
+    if (args.apiCalls !== undefined)
+        meta.apiCalls = args.apiCalls;
     if (args.rateLimit)
         meta.rateLimit = args.rateLimit;
     const error = {
@@ -139,7 +139,7 @@ export function errorEnvelope(args) {
     };
 }
 export function partialFromRejection(section, err) {
-    const code = err.code ?? 'UPSTREAM';
+    const code = err.code ?? 'SERVICE_ERROR';
     return {
         section,
         ok: false,

package/dist/index.js

@@ -21,7 +21,7 @@ const requestAuth = new AsyncLocalStorage();
 function currentApiKey() {
     return requestAuth.getStore()?.apiKey || ENV_API_KEY;
 }
-const OFFLINE_TOOLS = new Set(['list_capabilities']);
+const OFFLINE_TOOLS = new Set(['list_capabilities', 'list_webhook_events', 'explain_webhook_setup']);
 if (!ENV_API_KEY) {
     console.error('[cito-mcp] CITO_API_KEY is not set. Serving tool catalog only; ' +
         'API-backed tools will return MISSING_API_KEY until a key is provided ' +
@@ -95,7 +95,7 @@ function createCitoServer() {
             {
                 uri: 'cito://openapi.json',
                 name: 'Cito OpenAPI (public fetch)',
-                description: 'Live public OpenAPI snapshot for typed clients (not the tool catalog source).',
+                description: 'Live public OpenAPI snapshot for typed clients (separate from the tool catalog).',
                 mimeType: 'application/json',
             },
         ],

package/dist/install.js

@@ -222,21 +222,21 @@ function parseArgs(argv) {
     }
     return out;
 }
-const HELP = `cito-mcp install — configure the Cito MCP server for your editors
-
-Usage:
-  npx cito-mcp install --key cito_xxx
-  npx cito-mcp install --key cito_xxx --client cursor,claude-code
-  npx cito-mcp install --dry-run
-
-Options:
-  --key <key>       Cito API key. Falls back to $CITO_API_KEY.
-  --client <ids>    Comma-separated: claude-code, claude-desktop, cursor, windsurf, codex, grok.
-                    Default: every client detected on this machine.
-  --base <url>      Override API base (staging / self-hosted).
-  --dry-run, -n     Show what would change; write nothing.
-  --help, -h        This message.
-
+const HELP = `cito-mcp install — configure the Cito MCP server for your editors
+
+Usage:
+  npx cito-mcp install --key cito_xxx
+  npx cito-mcp install --key cito_xxx --client cursor,claude-code
+  npx cito-mcp install --dry-run
+
+Options:
+  --key <key>       Cito API key. Falls back to $CITO_API_KEY.
+  --client <ids>    Comma-separated: claude-code, claude-desktop, cursor, windsurf, codex, grok.
+                    Default: every client detected on this machine.
+  --base <url>      Override API base (staging / self-hosted).
+  --dry-run, -n     Show what would change; write nothing.
+  --help, -h        This message.
+
 Get a key at https://citoapi.com/dashboard`;
 export async function runInstall(argv) {
     const args = parseArgs(argv);

package/dist/instructions.js

@@ -1,6 +1,6 @@
 export const SERVER_INSTRUCTIONS = `# Cito MCP — agent operating manual
 
-You are connected to Cito esports data (read-only). Prefer curated outcome tools over raw REST. Production apps must call Cito REST with the user's API key; use this MCP to design, prototype, and resolve IDs — not as a multi-tenant runtime bus.
+You are connected to Cito esports and sports data. Reads are safe. The only writes are the webhook tools, and they only touch this user's own webhooks and test inboxes. Prefer curated outcome tools over raw REST. Production apps must call Cito REST with the user's API key; use this MCP to design, prototype, and resolve IDs — not as a multi-tenant runtime bus.
 
 ## Hard rules
 
@@ -8,7 +8,7 @@ You are connected to Cito esports data (read-only). Prefer curated outcome tools
 2. **Resolve before deep.** Name → ID/slug → summary/page → deep stats. Skip resolve only when the user already provided a Cito ID/slug.
 3. **One screen, one composite.** Prefer a page/summary tool over stitching 4–6 thin GETs.
 4. **Honor the envelope.** Parse ok, data, pagination, partial, error, meta.rateLimit, meta.entities. Partial section failures are not total failures — use successful sections.
-5. **Read-only.** All curated tools are safe to retry except where error.retryable is false for bad args / entitlement.
+5. **Reads are safe to retry** except where error.retryable is false for bad args / entitlement. **Writes** exist only for webhooks: create_webhook, update_webhook, delete_webhook, regenerate_webhook_secret, test_webhook, replay_webhook, catch_up_webhook and the inbox tools. Never call delete_webhook unless the user clearly asked to delete that webhook (it needs confirm: true). Do not retry create_webhook blindly: call list_webhooks first. Never repeat a webhook secret in chat: have the user store it.
 
 ## Game parameter
 
@@ -21,7 +21,8 @@ game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | t
 - RAF (Real American Freestyle wrestling) and BKFC (Bare Knuckle Fighting Championship) are NOT on the game enum: use the combat_* tools with league raf|bkfc (combat_events, combat_card, combat_bout, combat_athlete, combat_h2h, combat_rankings), or call_api /raf/... and /bkfc/.... RAF scores per PERIOD (wrestling points, takedowns); BKFC per ROUND (punches landed/thrown, knockdowns). Never mix either into UFC answers.
 - MMA archives: Bellator, PRIDE, Strikeforce, WEC, DREAM, EliteXC, Affliction, plus /mma for a fighter's whole non-UFC career (recordByPromotion). combat_* tools with league bellator|pride|strikeforce|wec|dream|elitexc|affliction|mma, or call_api /{league}/.... Closed archives (1997-2017) with official per-ROUND stats in UFC's shape ("13 of 18", round 0 = whole fight); no live, rankings or upcoming cards (combat_card "last" = most recent card). Fighters share their UFC slug (ufcFighterSlug). Never mix these into UFC answers. Their stats predate the Free/Starter window: HISTORY_WINDOW_EXCEEDED means Pro, not a bad key.
 - PFL (Professional Fighters League): combat_* with league pfl, or call_api /pfl/.... Every card since 2018, upcoming cards (combat_events when upcoming, combat_card "next") and live fight status (/pfl/live: bout status "live" with live.round / live.clock). Results only (winner, method, round, time): no strike or round stats exist for PFL. league mma includes PFL. Never mix into UFC answers.
-- OKTAGON MMA: combat_* with league oktagon, or call_api /oktagon/.... Every card since Oktagon 1 (2016), upcoming cards and live fight status. Per-ROUND stats on most bouts, LANDED ONLY: significant/total strikes, head/body/leg and takedowns as plain counts (landed.*), plus submission attempts; attempts, accuracy, knockdowns and control time are null because the source does not log them (each bout's statsCoverage says which fields exist). Fighters share their UFC slug when proven. league mma includes OKTAGON. Never mix into UFC answers.
+- OKTAGON MMA: combat_* with league oktagon, or call_api /oktagon/.... Every card since Oktagon 1 (2016), upcoming cards and live fight status. Per-ROUND stats on most bouts, LANDED ONLY: significant/total strikes, head/body/leg and takedowns as plain counts (landed.*), plus submission attempts; attempts, accuracy, knockdowns and control time are null because these aren't recorded for this promotion (each bout's statsCoverage says which fields exist). Fighters share their UFC slug when proven. league mma includes OKTAGON. Never mix into UFC answers.
+- Tennis (ATP, WTA, Challenger, ITF, junior slams): career_summary and surface_breakdown count singles only (career_summary.doubles and .combined hold the other scopes). current_rank is null when a player is not on the tour's latest list, which is normal for former players: read last_rank and last_rank_date. status is active, inactive or retired (status_basis says why); is_active is true exactly when status is active. sets[].tiebreak.winner_points is the match winner's points; tiebreak_points.winner is the tiebreak winner's. Rankings and draws are singles only. /tennis/matches and /tennis/players/{id}/matches return singles by default: pass match_type=doubles for doubles or match_type=all for both. Point-by-point exists from May 2026 (WTA) and June 2026 (ATP) on tour-level matches, and from 2026 on Challenger, WTA 125 and ITF; nothing older. Tennis odds are not offered.
 - UFC includes DWCS and Road to UFC (2022-2026, all 19 cards with official round stats; slugs like road-to-ufc-2-7, "Road to UFC 2.7").
 
 ## Preferred tool order
@@ -50,7 +51,7 @@ Lists use pagination: { limit, offset?, total?, hasMore, nextCursor, prevCursor
 
 ## Errors
 
-ok:false → read error.code (VALIDATION, NOT_FOUND, UNSUPPORTED_GAME, RATE_LIMIT, UNAUTHORIZED, UPSTREAM, PATH_NOT_ALLOWED, NOT_IMPLEMENTED). Follow error.recover[]. Retry only when retryable. RATE_LIMIT means cito-mcp already paced and retried: wait error.retryAfterMs before one more try, call tools one at a time, and never retry when retryable is false (monthly allowance used up: relay the upgrade link).
+ok:false → read error.code (VALIDATION, NOT_FOUND, UNSUPPORTED_GAME, RATE_LIMIT, UNAUTHORIZED, SERVICE_ERROR, PATH_NOT_ALLOWED, NOT_IMPLEMENTED). Follow error.recover[]. Retry only when retryable. RATE_LIMIT means cito-mcp already paced and retried: wait error.retryAfterMs before one more try, call tools one at a time, and never retry when retryable is false (monthly allowance used up: relay the upgrade link).
 
 ok:true with partial[] → use successful sections; do not treat partial as total fail.
 ok:true with meta.warnings[] → filters or depth degraded; do not assume ignored filters applied.
@@ -65,6 +66,11 @@ Player card: resolve_entity {type:player|fighter} → player_profile.
 Fight night / event card: resolve_entity {type:event} → event_card {includeMatches:true} → match_preview for a featured bout.
 Match preview (named sides): resolve_entity each side (optional) → match_preview {teamA, teamB}.
 App scaffold: list_capabilities ∥ api_health ∥ live_matches, then one composite per screen.
+Odds: match_details sections:["odds"] (UFC, CS2) or call_api /lol/matches/{id}/odds. CS2, LoL and UFC prediction-market odds update the moment the price changes (in play and between rounds/games); for an app that must react to every change, point the user at the sport's live WebSocket (wss://api.citoapi.com/api/v1/{cs2|lol|ufc}/live/ws, messages cs2.odds.updated / lol.odds.updated / ufc.odds.updated; odds plan + Live WebSockets), not MCP polling. Per-round / per-game prices: /cs2/matches/{id}/odds/rounds, /lol/matches/{id}/odds/games, /ufc/bouts/{id}/odds/rounds.
+
+## Webhooks
+
+When a user wants to react to changes, or describes polling, recommend webhooks: explain_webhook_setup shows their plan, existing webhooks and next steps. Flow: list_webhook_events → create_webhook → store the secret → test_webhook with event → webhook_deliveries. Only recommend events whose status is "active". Webhooks need Pro or Scale; on a plan error relay error.details.upgradeUrl. Any plan can use create_webhook_inbox and send_inbox_sample to see real payloads with no server. Outage recovery: events during a pause are not queued (status skipped_backoff); catch_up_webhook re-sends the match and result events.
 
 ## Resources
 

package/dist/pacing.js

@@ -3,8 +3,8 @@ export const CONSTRAINED_CONCURRENT_PER_KEY = 2;
 export const CONSTRAINED_WINDOW_MS = 60_000;
 export const MAX_WAIT_MS = 20_000;
 export const MAX_RATE_LIMIT_RETRIES = 2;
-export const MAX_UPSTREAM_RETRIES = 1;
-export const UPSTREAM_BACKOFF_MS = 750;
+export const MAX_SERVER_RETRIES = 1;
+export const SERVER_BACKOFF_MS = 750;
 export const CALL_BUDGET_MS = 45_000;
 const DEFAULT_RETRY_AFTER_MS = 2_000;
 const WINDOW_MS = 60_000;

package/dist/scrub.js

@@ -1,8 +1,8 @@
+import { createHash } from 'node:crypto';
 const INTERNAL_KEYS = new Set([
     'emptyCardHeal',
     'llmValidation',
     'workerHostHint',
-    'scrapeMeta',
     'fetchMeta',
     'cacheKey',
     'failureSteps',
@@ -12,8 +12,6 @@ const INTERNAL_KEYS = new Set([
     'sourceUrl',
     'sourceUrls',
     'sourceIds',
-    'wikiUrl',
-    'wiki_url',
     'jsonLd',
     '_mergeSource',
     '_provenance',
@@ -32,21 +30,17 @@ const INTERNAL_KEYS = new Set([
     'profileImageAttemptedAt',
     'profileImageAttempts',
     'profileImageError',
-    'profileImageSteamAttemptedAt',
     'profileImageWorker',
     'ratingSource',
     'requiredSourceData',
     'rawText',
     'raw_text',
-    'scrapedAt',
-    'scraped_at',
     'sourceSummary',
     'sourceNote',
     'durableStatsTables',
     'lineupSource',
     'mapMediaSource',
     'rosterSource',
-    'upstream',
     'liveCandidateWindowMinutes',
     'rowHash',
     'row_hash',
@@ -59,17 +53,97 @@ const INTERNAL_KEYS = new Set([
     'imageCandidates',
     'image_candidates',
     'source_url',
+    'source',
+    'sources',
+    '_liveSource',
+    'liveSource',
+    'live_feed',
+    'liveFeed',
+    'gameStateSource',
+    'bridge_source',
+    'rank_source',
+    'rankSource',
+    'dataSource',
+    'data_source',
+    'date_source',
+    'meta_source',
 ]);
-const SCRAPE_PARENTS = new Set(['dataAvailability', 'health']);
-const SCRAPE_KEYS = new Set(['strategy', 'samples']);
+const ORIGIN_WORD_KEY = /(^|_)sources?($|_)|[a-z]Sources?($|[A-Z])|^_?sources?[A-Z]/;
+const DENIED_WORDS = new Set([
+    '007d859ffc608f3a',
+    '017055b00735cdaa',
+    '0991545f91164c02',
+    '0a86e4e8778e5bc4',
+    '211022d4dba1354e',
+    '2273bc83a7916501',
+    '343406fa95fefe9a',
+    '3511b94bd7795e3b',
+    '3fbfbeeeaddc4fe5',
+    '417ccb9b693bc11d',
+    '438338424376242e',
+    '53a828d1313e2f24',
+    '56279b500aeff149',
+    '63919bdfdccc4e03',
+    '68ec9e984bd969e2',
+    '735bda6297e559c5',
+    '7a9040b69cc466a0',
+    '7e25e5e9baf788fe',
+    '827ce7e74edb79b2',
+    '82d2e789811fae32',
+    '93b0c3823ffe6d0b',
+    'a85f3c568720d7da',
+    'aab85fb91587ac06',
+    'aaf4b5714130cfbd',
+    'ac4399e79599c5f9',
+    'b71515611a06c04e',
+    'b769513d718b1bdd',
+    'b8e91b77223e5c17',
+    'c833542aacad261c',
+    'cca8e34d07dda457',
+    'd656bca8c6e48174',
+    'dc2bcd7bbfe8773e',
+    'e08ad232764c86ab',
+    'e3bd135d984a0b44',
+    'e924b9eb04be6af2',
+    'f2b71a5a46b415e3',
+    'f578f53f4c52c9c9',
+    'fb25211c8b74e564',
+]);
+const DENIED_MEMO = new Map();
+function wordHash(word) {
+    return createHash('sha256').update(`cito-mcp-key-v1:${word}`).digest('hex').slice(0, 16);
+}
+function hasDeniedWord(key) {
+    let hit = DENIED_MEMO.get(key);
+    if (hit === undefined) {
+        const words = key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[\s_-]+/).filter(Boolean).map((w) => w.toLowerCase());
+        const tries = [...words, ...words.slice(1).map((w, i) => `${words[i]}${w}`)];
+        hit = tries.some((w) => DENIED_WORDS.has(wordHash(w)));
+        if (DENIED_MEMO.size > 20_000)
+            DENIED_MEMO.clear();
+        DENIED_MEMO.set(key, hit);
+    }
+    return hit;
+}
+const PORTRAIT_LICENCE_KEY = /^(portrait|image|photo|picture)_?source_?url$/i;
+const STATUS_PARENTS = new Set(['dataAvailability', 'health']);
+const STATUS_KEYS = new Set(['strategy', 'samples']);
 const MEDIA_PARENT = /image|photo|portrait|picture/i;
 const ERROR_KEYS = new Set(['errors', 'error', 'lastError', 'bodyPreview']);
 const INTERNAL_ERROR_TEXT = /prisma|raw query failed|invocation|ECONNREFUSED|\bat \S+ \(/i;
 export const INTERNAL_ERROR_PLACEHOLDER = 'internal_error';
+const NO_RESULT_REASON_KEY = /^result_?unavailable_?reason$/i;
+const RAW_NO_RESULT_REASON = 'source_published_no_result';
+const NO_RESULT_REASON = 'published_no_result';
 function isInternal(key, parentKey) {
     if (key === 'sourceUrl' && MEDIA_PARENT.test(parentKey))
         return false;
-    return INTERNAL_KEYS.has(key) || (SCRAPE_KEYS.has(key) && SCRAPE_PARENTS.has(parentKey));
+    if (PORTRAIT_LICENCE_KEY.test(key))
+        return false;
+    return (INTERNAL_KEYS.has(key) ||
+        ORIGIN_WORD_KEY.test(key) ||
+        hasDeniedWord(key) ||
+        (STATUS_KEYS.has(key) && STATUS_PARENTS.has(parentKey)));
 }
 function scrub(node, parentKey, inError) {
     if (typeof node === 'string') {
@@ -98,7 +172,9 @@ function scrub(node, parentKey, inError) {
             delete out[key];
             continue;
         }
-        const next = scrub(value, key, inError || ERROR_KEYS.has(key));
+        const next = value === RAW_NO_RESULT_REASON && NO_RESULT_REASON_KEY.test(key)
+            ? NO_RESULT_REASON
+            : scrub(value, key, inError || ERROR_KEYS.has(key));
         if (next !== value) {
             out ??= { ...src };
             out[key] = next;