cito-mcp 0.5.8 → 0.6.0

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/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,7 +73,7 @@ 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)
@@ -81,7 +81,7 @@ export function successEnvelope(args) {
     if (args.tookMs !== undefined)
         meta.tookMs = args.tookMs;
     if (args.upstreamCalls !== undefined)
-        meta.upstreamCalls = args.upstreamCalls;
+        meta.apiCalls = args.upstreamCalls;
     if (args.rateLimit)
         meta.rateLimit = args.rateLimit;
     if (args.warnings?.length)
@@ -103,10 +103,10 @@ 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)
@@ -114,7 +114,7 @@ export function errorEnvelope(args) {
     if (args.tookMs !== undefined)
         meta.tookMs = args.tookMs;
     if (args.upstreamCalls !== undefined)
-        meta.upstreamCalls = args.upstreamCalls;
+        meta.apiCalls = args.upstreamCalls;
     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/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/scrub.js

@@ -59,17 +59,53 @@ 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',
+    'esportsMatchId',
+    'esportsGameId',
+    'esports_match_id',
+    'riotId',
+    'riot_id',
+    'steamId',
+    'steam_id',
+    'oddsKey',
+    'odds_key',
+    'provider',
+    'providers',
 ]);
-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 PROVIDER_PREFIX_KEY = /^_?(hltv|open_?dota|polymarket|fight_?odds|ufc_?stats)/i;
+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) ||
+        PROVIDER_PREFIX_KEY.test(key) ||
+        (STATUS_KEYS.has(key) && STATUS_PARENTS.has(parentKey)));
 }
 function scrub(node, parentKey, inError) {
     if (typeof node === 'string') {
@@ -98,7 +134,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;

package/dist/tools/combat.js

@@ -192,7 +192,7 @@ returns an empty list with data.note instead of failing.
 Prefer over: call_api /{league}/events.
 Do not use when: you already have the event slug and want its bouts (combat_card).
 
-Parallel-safe: yes. Upstream cost: 1.
+Parallel-safe: yes. API calls: 1.
 Example: { "league": "bkfc", "when": "upcoming", "limit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -264,7 +264,7 @@ MMA archives are closed: event defaults to "last" (the most recent card; for mma
 Prefer over: combat_events + call_api per bout.
 Do not use when: you need one bout's period/round breakdown (combat_bout).
 
-Parallel-safe: yes. Upstream cost: 2–3.
+Parallel-safe: yes. API calls: 2–3.
 Example: { "league": "raf", "event": "last" }`,
     inputSchema: {
         type: 'object',
@@ -364,7 +364,7 @@ note while the result still returns.
 Get boutId from combat_card or combat_athlete (e.g. "raf13--belal-muhammad--colby-covington", "bellator-5600").
 MMA archive bout ids are "<promotion>-<fightId>"; a bare fight id resolves in any MMA archive league.
 
-Parallel-safe: yes. Upstream cost: 1–2.
+Parallel-safe: yes. API calls: 1–2.
 Example: { "league": "bkfc", "boutId": "bkfc-fight-night-bethlehem--gregoris-cisneros--ryan-petersen" }`,
     inputSchema: {
         type: 'object',
@@ -439,7 +439,7 @@ Keep the records apart: archive fights never belong in a UFC answer.
 
 Prefer over: call_api profile + history + stats separately.
 
-Parallel-safe: yes. Upstream cost: 2–4.
+Parallel-safe: yes. API calls: 2–4.
 Example: { "league": "raf", "athlete": "Kyle Snyder", "historyLimit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -516,7 +516,7 @@ Accepts slugs or names for both sides (names resolve through the league's search
 the ones on that promotion's cards (league "mma": every archived promotion); UFC meetings are a UFC question
 (head_to_head).
 
-Parallel-safe: yes. Upstream cost: 1–3.
+Parallel-safe: yes. API calls: 1–3.
 Example: { "league": "bkfc", "athleteA": "ryan-petersen", "athleteB": "gregoris-cisneros" }`,
     inputSchema: {
         type: 'object',
@@ -573,7 +573,7 @@ The MMA archives (bellator, pride, strikeforce, wec, dream, elitexc, affliction,
 non-retryable NOT_IMPLEMENTED.
 Never answer with UFC rankings instead.
 
-Parallel-safe: yes. Upstream cost: 1.
+Parallel-safe: yes. API calls: 1.
 Example: { "league": "bkfc", "division": "heavyweight" }`,
     inputSchema: {
         type: 'object',

package/dist/tools/index.js

@@ -12,6 +12,7 @@ import { cs2Tools } from './cs2.js';
 import { tournamentTools } from './tournaments.js';
 import { scheduleTools } from './schedule.js';
 import { combatTools } from './combat.js';
+import { webhookTools } from './webhooks.js';
 export const allTools = [
     ...metaTools.filter((t) => t.name === 'list_capabilities' || t.name === 'api_health'),
     ...resolveTools,
@@ -27,6 +28,7 @@ export const allTools = [
     ...insightTools,
     ...cs2Tools,
     ...combatTools,
+    ...webhookTools,
     ...metaTools.filter((t) => t.name === 'list_routes' || t.name === 'call_api'),
 ];
 export function getTool(name) {

package/dist/tools/insight.js

@@ -26,6 +26,9 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
                 hand: pickString(data.hand) ?? null,
                 age: typeof data.age === 'number' ? data.age : null,
                 currentRank: typeof data.current_rank === 'number' ? data.current_rank : null,
+                lastRank: typeof data.last_rank === 'number' ? data.last_rank : null,
+                lastRankDate: pickString(data.last_rank_date) ?? null,
+                status: pickString(data.status) ?? null,
                 careerHighRank: typeof data.career_high_rank === 'number' ? data.career_high_rank : null,
                 careerRecord: career.matches_won != null && career.matches_lost != null
                     ? `${career.matches_won}-${career.matches_lost}`
@@ -272,7 +275,7 @@ Prefer match_summary when match is completed; match_details for live in-game.
 
 Do not use when: user wants final score/recap of a finished match.
 
-Parallel-safe: yes. Upstream cost: 4–8.
+Parallel-safe: yes. API calls: 4–8.
 Tennis H2H accepts an optional surface filter (Hard, Clay, Grass).
 Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "recentLimit": 5 }`,
     inputSchema: {
@@ -520,7 +523,7 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
             }
             catch (e) {
                 partial.push(partialFromRejection('h2h', {
-                    code: 'UPSTREAM',
+                    code: 'SERVICE_ERROR',
                     message: e.message,
                 }));
             }
@@ -718,7 +721,7 @@ Bouts come back in card order — main event first, then prelims, then early pre
 Each bout carries weightClass, titleBout, card placement, and (once fought) result
 { method, round, time, referee, winnerSlug }. Each corner carries images
 { headshotUrl, bodyImageUrl, imageUrl, proxiedImageUrl }, record, nickname, rank,
-championStatus, country and flag when upstream supplies them. Use proxiedImageUrl in
+championStatus, country and flag when available. Use proxiedImageUrl in
 browsers — the image host sends no CORS header. You do not need call_api per fighter for faces.
 
 Prefer over: agent-side resolve + call_api /ufc/events + bout expansion; N+1 match_summary for the card list only; per-fighter call_api just to fetch headshots.
@@ -730,14 +733,14 @@ Do not use when: you only need live scores (live_matches); single finished match
 Tennis: pass a tournament id/slug to get the draw bracket — every main round from
 the first to the Final (status completed / in_progress / not_started), then
 qualifying (Q1..Q3). Each result carries winnerId/loserId/outcome (retirements
-included), startTime (null with startTimeUnavailableReason when the source has no
+included), startTime (null with startTimeUnavailableReason when no start time is
 clock), nextMatchId (the bracket edge) and bracketPosition; scheduled and live
 matches sit in rounds[].pending. draw carries drawSize (real field size, byes
 excluded, e.g. 56), byes, matchesExpected (main draw) and complete (true only
 when every main round to the Final is played). This is the primary tennis path
 here; there is no separate draw tool.
 
-Parallel-safe: yes. Upstream cost: 1–4.
+Parallel-safe: yes. API calls: 1–4.
 Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "includeStandings": false }`,
     inputSchema: {
         type: 'object',
@@ -751,7 +754,7 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
             includeMatches: boolSchema('Include the bout/match list, or the tennis draw bracket (default true).', true),
             includeStandings: boolSchema('Include standings/rankings snippet when API supports event/tournament/division scope (default false). ' +
                 'For UFC this also joins divisional rank and movement onto each bout corner as team.rank / team.rankMovement — ' +
-                'bout rows themselves carry no rank. Costs one extra upstream call.', false),
+                'bout rows themselves carry no rank. Costs one extra API call.', false),
             limit: limitSchema({
                 default: 20,
                 max: 50,
@@ -1290,7 +1293,7 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                                 ? { startTimeUnavailableReason: pickString(mr.start_time_unavailable_reason) }
                                 : {}),
                             nextMatchId: pickString(mr.next_match_id) ?? null,
-                            ...(pickString(mr.next_match_source) ? { nextMatchSource: pickString(mr.next_match_source) } : {}),
+                            ...(pickString(mr.next_match_source) ? { nextMatchBasis: pickString(mr.next_match_source)?.replace(/^source_/, '') } : {}),
                             bracketPosition: num(mr.bracket_position),
                             nextSlot: asRecord(mr.next_slot)
                                 ? {
@@ -1298,7 +1301,7 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                                     position: num(asRecord(mr.next_slot)?.position),
                                 }
                                 : null,
-                            ...(pickString(mr.source_round) ? { sourceRound: pickString(mr.source_round) } : {}),
+                            ...(pickString(mr.source_round) ? { rawRound: pickString(mr.source_round) } : {}),
                         }, 'tennis');
                     };
                     const pendingMatch = (pr) => {
@@ -1315,7 +1318,7 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                             startTimeKnown: pr.start_time_known === true,
                             liveScore: pickString(pr.live_score) ?? null,
                             winnerId: null,
-                            ...(pickString(pr.source_winner_id) ? { sourceWinnerId: pickString(pr.source_winner_id) } : {}),
+                            ...(pickString(pr.source_winner_id) ? { reportedWinnerId: pickString(pr.source_winner_id) } : {}),
                             nextMatchId: pickString(pr.next_match_id) ?? null,
                             bracketPosition: num(pr.bracket_position),
                         };
@@ -1397,7 +1400,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                     }
                     drawSummary = {
                         drawSize,
-                        drawSizeSource: pickString(dd.draw_size_source) ?? null,
                         drawSizeVerified: typeof dd.draw_size_verified === 'boolean' ? dd.draw_size_verified : null,
                         drawSizeDerived: num(dd.draw_size_derived),
                         bracketSize: num(dd.bracket_size),

package/dist/tools/leaderboard.js

@@ -53,7 +53,7 @@ Do not use when: ranking position → standings with game tennis; week-over-week
 
 Tennis-only. Season defaults to 2026; tour (ATP|WTA) is optional — omit it for the combined board. Rows carry aces + matches played, ordered most aces first.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -205,7 +205,7 @@ Do not use when: ranking position → standings with game tennis; week-over-week
 
 Tennis-only. Season defaults to 2026; tour (ATP|WTA) is optional — omit it for the combined board. ${spec.minAttemptsNote}
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
         inputSchema: {
             type: 'object',
             additionalProperties: false,

package/dist/tools/live.js

@@ -110,9 +110,9 @@ export function humanUfcEmptyNote(emptyReason, health) {
         supervisor_warming: 'Card open / pre-gate; no bout live yet',
         between_bouts: 'Between bouts; next may be armed',
         armed_only: 'Next bout armed; not started',
-        worker_stale: 'Live feed is behind; scores may lag',
-        worker_down_inferred: 'Live feed unavailable right now',
-        event_degraded: 'Sources empty clock / event degraded; not inventing stats',
+        worker_stale: 'Live data is behind; scores may lag',
+        worker_down_inferred: 'Live data unavailable right now',
+        event_degraded: 'Live clock unavailable; not inventing stats',
     };
     const msg = human[reason] || `No live|watching bouts (${reason})`;
     return `UFC: ${msg} (${workerPart}${lagPart}; emptyReason=${reason})`;
@@ -165,9 +165,10 @@ Prefer over: sequential per-game call_api live probes.
 Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
 
 CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
+Tennis: ITF and junior rows have no serve statistics (stats_unavailable_code), so a missing stat there is expected. For push updates point the user at wss://api.citoapi.com/api/v1/tennis/live/ws.
 UFC empty board: section.note + emptyReason + health (workerAlive/lag) + optional supervisor/nextCard (non-live); never fake match items from events[].
 
-Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
+Parallel-safe: yes. API calls: 1–5 (allSettled).
 Example: { "game": "all", "limitPerGame": 10 }`,
     inputSchema: {
         type: 'object',
@@ -359,12 +360,12 @@ Do not use when: only in-progress matches needed → live_matches.
 
 Filter support (unsupported params are ignored with meta.warnings — do not assume filtering worked):
 - lol: hours, team (slug), league (slug)
-- cs2: team, from, to (ISO); hours not applied upstream
+- cs2: team, from, to (ISO); hours is not applied
 - cod: team, tournamentId
 - dota2: limit/cursor primarily; team may be client-filtered where data allows
 - ufc: hours / from / to applied client-side after bout expansion (API has no hours); event shells labeled by event name; bouts use fighters[] corners
 
-Parallel-safe: yes. Upstream cost: 1–2.
+Parallel-safe: yes. API calls: 1–2.
 Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
     inputSchema: {
         type: 'object',
@@ -465,7 +466,7 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 ...(to ? { to } : {}),
             };
             if (args.hours !== undefined)
-                noteIgnored('hours', 'CS2 uses from/to or unfiltered upcoming; hours is not applied upstream');
+                noteIgnored('hours', 'CS2 uses from/to or unfiltered upcoming; hours is not applied');
             if (league)
                 noteIgnored('league', 'CS2 schedule does not accept league here — filter client-side or use event tools');
             if (tournamentId)