cito-mcp 0.5.8 → 0.6.0

package/dist/tools/standings.js

@@ -1,3 +1,4 @@
+import { normalizeCoverage } from './rankings.js';
 import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
 import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
@@ -77,26 +78,26 @@ export function normalizeStandingRow(row, index) {
 }
 export const standings = {
     name: 'standings',
-    description: `League/event standings or world/division rankings normalized to ranked rows.
-
-When to use:
-- Table / playoff picture
-- UFC rankings; CS2 world or event standings; CDL standings; LoL league/tournament tables
-
-Prefer over: raw standings via call_api for agent-normalized rows.
-
-Do not use when: single team form → team_profile; live scores → live_matches.
-Dota has no first-class standings (may NOT_IMPLEMENTED or weak worldRanking).
-
-Required scope keys by game:
-- lol: leagueId OR tournamentId
-- cs2: omit for world rankings; eventId for event standings
-- cod: optional season/stage
-- ufc: optional division (scope=division)
-- tennis: optional division (ATP or WTA tour; default ATP)
-- dota2: best-effort worldRanking only
-
-Parallel-safe: yes. Upstream cost: 1–2.
+    description: `League/event standings or world/division rankings normalized to ranked rows.
+
+When to use:
+- Table / playoff picture
+- UFC rankings; CS2 world or event standings; CDL standings; LoL league/tournament tables
+
+Prefer over: raw standings via call_api for agent-normalized rows.
+
+Do not use when: single team form → team_profile; live scores → live_matches.
+Dota has no first-class standings (may NOT_IMPLEMENTED or weak worldRanking).
+
+Required scope keys by game:
+- lol: leagueId OR tournamentId
+- cs2: omit for world rankings; eventId for event standings
+- cod: optional season/stage
+- ufc: optional division (scope=division)
+- tennis: optional division (ATP or WTA tour; default ATP); optional season YYYY = that season's last published list (default: latest). listCoverage says when an archived list is held only in part
+- dota2: best-effort worldRanking only
+
+Parallel-safe: yes. API calls: 1–2.
 Example: { "game": "cod", "season": "2026", "limit": 50 }`,
     inputSchema: {
         type: 'object',
@@ -112,7 +113,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             leagueId: stringSchema('LoL league id for league standings.'),
             tournamentId: stringSchema('LoL/COD tournament id.'),
             eventId: stringSchema('CS2 event id for event standings.'),
-            season: stringSchema('Season key (COD).'),
+            season: stringSchema('Season key (COD). Tennis: a year (YYYY) gives that season\'s last published ranking list.'),
             stage: stringSchema('Stage key (COD / LoL).'),
             division: stringSchema('UFC division key.'),
             limit: limitSchema({ default: 50, max: 100 }),
@@ -145,7 +146,11 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         const leagueId = typeof args.leagueId === 'string' ? args.leagueId : undefined;
         const tournamentId = typeof args.tournamentId === 'string' ? args.tournamentId : undefined;
         const eventId = typeof args.eventId === 'string' ? args.eventId : undefined;
-        const season = typeof args.season === 'string' ? args.season : undefined;
+        const season = typeof args.season === 'string'
+            ? args.season
+            : typeof args.season === 'number' && Number.isFinite(args.season)
+                ? String(Math.trunc(args.season))
+                : undefined;
         const stage = typeof args.stage === 'string' ? args.stage : undefined;
         const division = typeof args.division === 'string' ? args.division : undefined;
         const tennisPage = typeof args.page === 'number' && Number.isFinite(args.page) && args.page >= 1
@@ -241,7 +246,18 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         else if (game === 'tennis') {
             const tour = String(division ?? 'ATP').toUpperCase() === 'WTA' ? 'WTA' : 'ATP';
             path = '/tennis/standings';
-            query = { tour, top_n: Math.min(limit, 100), page: tennisPage };
+            const tennisSeason = season && /^\d{4}$/.test(season.trim()) ? season.trim() : undefined;
+            if (season && !tennisSeason) {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: `season must be a year (YYYY) for tennis (got '${season}')`,
+                    game,
+                    source: 'standings',
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+            query = { tour, top_n: Math.min(limit, 100), page: tennisPage, ...(tennisSeason ? { season: tennisSeason } : {}) };
             effectiveScope = 'world';
             title = `${tour} singles rankings`;
         }
@@ -371,6 +387,9 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         };
         pushWarning(upstreamMeta.warning);
         pushWarning(dataQuality.warning);
+        const tennisCoverage = game === 'tennis' ? asRecord(obj?.list_coverage) : null;
+        if (tennisCoverage && tennisCoverage.status === 'partial')
+            pushWarning(tennisCoverage.note);
         if (Array.isArray(upstreamMeta.warnings)) {
             for (const w of upstreamMeta.warnings)
                 pushWarning(w);
@@ -412,6 +431,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 ...(game === 'tennis'
                     ? {
                         rankingDate: pickString(obj?.ranking_date) ?? null,
+                        listCoverage: tennisCoverage ? normalizeCoverage(tennisCoverage) : null,
                         updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt, obj?.ranking_date) ?? null,
                     }
                     : {

package/dist/tools/team.js

@@ -42,7 +42,7 @@ Prefer over: separate roster + matches + detail via call_api.
 Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
 Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
 
-Parallel-safe: yes. Upstream cost: 2–4.
+Parallel-safe: yes. API calls: 2–4.
 Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -532,7 +532,7 @@ function winnerSide(match, a) {
 }
 export const headToHead = {
     name: 'head_to_head',
-    description: `Composed head-to-head record between two teams, two UFC fighters, or two tennis players. No first-class REST H2H exists — this tool filters match history server-side.
+    description: `Head-to-head record between two teams, two UFC fighters, or two tennis players. Tennis reads the tennis head-to-head route; other games filter match history server-side.
 
 When to use:
 - Rivalry / series record questions
@@ -544,7 +544,9 @@ Do not use when: single-side form only → team_profile or player_profile.
 
 Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
 
-Parallel-safe: yes. Upstream cost: 2–4.
+Tennis: pass entityType "player" with sideA and sideB (ids like atp_207989, or names). This tool has no players param; for three or more players use h2h_matrix, which does. limit pages the meetings list only (max 50); every tally covers all meetings. In the payload current_rank is null when a player is not on the tour's latest list: read last_rank. The tiebreak and level_breakdown keys are in data.h2h.
+
+Parallel-safe: yes. API calls: 2–4.
 Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
     inputSchema: {
         type: 'object',
@@ -558,8 +560,8 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
                 default: 'team',
                 description: 'team (default), fighter (UFC), or player (tennis).',
             },
-            sideA: stringSchema('Id or slug for side A.', 'faze'),
-            sideB: stringSchema('Id or slug for side B.', 'navi'),
+            sideA: stringSchema('Id or slug for side A (tennis: atp_207989 or a player name).', 'faze'),
+            sideB: stringSchema('Id or slug for side B (tennis: atp_206173 or a player name).', 'navi'),
             limit: limitSchema({ default: 20, max: 50, description: 'Max meetings returned.' }),
             from: stringSchema('ISO-8601 lower bound on meeting startTime (client filter).'),
             to: stringSchema('ISO-8601 upper bound on meeting startTime (client filter).'),
@@ -982,7 +984,7 @@ Do not use when: a two-player rivalry deep-dive with tiebreak/decider splits →
 
 Tennis-only. players takes 2-16 ids or names (names resolve via player search). Each matrix cell is "W-L" from the row player's perspective, "-" on the diagonal.
 
-Parallel-safe: yes. Upstream cost: 1 + one search per unresolved name.`,
+Parallel-safe: yes. API calls: 1 + one search per unresolved name.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,

package/dist/tools/tournaments.js

@@ -54,10 +54,10 @@ Tennis-only. Levels accept names (Grand Slam, WTA 1000, ATP 500, Challenger,
 ITF World Tennis Tour, Davis Cup, ...) or raw tier codes (G, M, A, C, D).
 A level name that starts with ATP or WTA also fixes the tour (and conflicts with
 a contradicting tour= argument are rejected), so "WTA 1000" cannot return ATP
-Masters events even though the upstream filter is not tour-aware.
-Note the source does not separate ATP 500 from ATP 250 — both are ATP Tour.
+Masters events.
+The category field reports ATP 500 and ATP 250 both as atp_tour (read tier to tell them apart), and WTA 1000 events as wta_1000.
 
-Parallel-safe: yes. Upstream cost: 1.`,
+Parallel-safe: yes. API calls: 1.`,
     inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -232,10 +232,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 .slice(0, 5)
                 .map((t) => `${t.id} (${t.tour})`)
                 .join(', ');
-            warnings.push(`The upstream level filter returned ${contradictions.length} tournament(s) that contradict level="${levelRaw}": ` +
-                `${sample}. They were dropped. The API's level reverse-map is not tour-aware (WTA 1000 resolves to tier codes ` +
-                `PM and M), which is a server-side defect; this tool sends tour=${levelTourPrefix} as well, so a repeat of this ` +
-                `warning means the upstream filter is widening again.`);
+            warnings.push(`The level filter returned ${contradictions.length} tournament(s) that contradict level="${levelRaw}": ` +
+                `${sample}. They were dropped; this tool also sends tour=${levelTourPrefix}.`);
         }
         return successEnvelope({
             pagination: {

package/dist/tools/types.js

@@ -156,7 +156,7 @@ export async function runTool(def, args, ctx) {
     catch (error) {
         const { errorEnvelope, toMcpResult: toResult } = await import('../envelope.js');
         return toResult(errorEnvelope({
-            code: 'UPSTREAM',
+            code: 'SERVICE_ERROR',
             message: error.message || 'Unhandled tool error',
             game: null,
             source: def.name,

package/dist/tools/webhooks.js

@@ -0,0 +1,377 @@
+import { fetchJson } from '../client.js';
+import { errorEnvelope, mapHttpToCode, successEnvelope } from '../envelope.js';
+import { READ_TOOL_ANNOTATIONS, boolSchema, limitSchema, stringSchema, } from './types.js';
+const WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
+async function callApi(ctx, tool, method, path, opts = {}, shape = (b) => b) {
+    const started = Date.now();
+    const res = await fetchJson(ctx, path, { method, query: opts.query, body: opts.body, raw: true });
+    const body = (res.data && typeof res.data === 'object' ? res.data : {});
+    if (!res.ok) {
+        const nested = body.error && typeof body.error === 'object' ? body.error : null;
+        const message = typeof body.error === 'string' ? body.error : String(nested?.message ?? `Request failed (HTTP ${res.status})`);
+        const recover = [
+            ...(body.fix ? [String(body.fix)] : []),
+            ...(body.upgradeUrl ? [`Tell the user webhooks need Pro or Scale and give them this link: ${body.upgradeUrl}`] : []),
+        ];
+        return errorEnvelope({
+            code: mapHttpToCode(res.status),
+            message,
+            game: null,
+            source: tool,
+            httpStatus: res.status,
+            retryable: res.status === 429 || res.status >= 500,
+            ...(recover.length ? { recover } : {}),
+            ...(body.code || body.upgradeUrl ? { details: { ...(body.code ? { apiCode: body.code } : {}), ...(body.upgradeUrl ? { upgradeUrl: body.upgradeUrl, currentPlan: body.currentPlan, requiredPlan: body.requiredPlan } : {}) } } : {}),
+        });
+    }
+    return successEnvelope({ data: shape(body), game: null, source: tool, tookMs: Date.now() - started, upstreamCalls: 1 });
+}
+function bad(tool, message, recover) {
+    return errorEnvelope({ code: 'VALIDATION', message, game: null, source: tool, retryable: false, recover });
+}
+const idArg = stringSchema('The webhook id, from list_webhooks or create_webhook. Never invent one.');
+const inboxIdArg = stringSchema('The inbox id, from create_webhook_inbox or list_webhook_inboxes.');
+const eventsArg = {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Event names from list_webhook_events. Subscribe to the fewest that do the job. Example: ["cs2.match.completed"].',
+};
+const filtersArg = {
+    type: 'object',
+    description: 'Optional. Only events matching these are sent, for example {"league":"LEC"}. Check each event\'s filters in list_webhook_events: filtering on a field an event does not carry stops every delivery of it.',
+};
+const without = (body, ...keys) => {
+    const out = { ...body };
+    for (const k of keys)
+        delete out[k];
+    return out;
+};
+export const webhookTools = [
+    {
+        name: 'list_webhook_events',
+        description: 'Every webhook event Cito can send, for every game. Each has a description, when it fires, status (active, quiet, not_observed), measured frequency, minimum plan and the filters it supports. Pass event for one event\'s field names and a real example. Only recommend events whose status is "active". API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                game: stringSchema('Filter to one game: lol, cs2, cod, dota2, tennis, ufc, fortnite.', 'cs2'),
+                event: stringSchema('One event name. Adds its fields and a real example.', 'cs2.match.completed'),
+            },
+            additionalProperties: false,
+        },
+        annotations: READ_TOOL_ANNOTATIONS,
+        handler: async (args, ctx) => {
+            const detail = typeof args.event === 'string' && args.event.length > 0;
+            return callApi(ctx, 'list_webhook_events', 'GET', '/webhooks/events', {
+                query: { game: args.game, event: args.event, examples: detail ? undefined : 'false', fields: detail ? undefined : 'false' },
+            }, (b) => ({
+                events: b.events,
+                count: b.count,
+                games: b.games,
+                plans: b.plans,
+                ...(detail ? { envelope: b.envelope, delivery: b.delivery } : {}),
+                measuredAt: b.measured_at,
+            }));
+        },
+    },
+    {
+        name: 'explain_webhook_setup',
+        description: 'How Cito webhooks work and what to do next for this user: their plan, their existing webhooks and inboxes, setup steps, signature verification code, retries and what happens during an outage. Start here when a user asks about webhooks or describes polling for changes. API calls: 3.',
+        inputSchema: {
+            type: 'object',
+            properties: { game: stringSchema('Optional game, to list its active events.', 'tennis') },
+            additionalProperties: false,
+        },
+        annotations: READ_TOOL_ANNOTATIONS,
+        handler: async (args, ctx) => {
+            const catalog = await fetchJson(ctx, '/webhooks/events', { query: { game: args.game, examples: 'false', fields: 'false' }, raw: true });
+            if (!catalog.ok) {
+                return errorEnvelope({ code: mapHttpToCode(catalog.status), message: 'Could not read the webhook catalog.', game: null, source: 'explain_webhook_setup', httpStatus: catalog.status });
+            }
+            const c = catalog.data;
+            const hooks = ctx.apiKey ? await fetchJson(ctx, '/webhooks', { raw: true }) : null;
+            const inboxes = ctx.apiKey ? await fetchJson(ctx, '/webhook-inbox', { raw: true }) : null;
+            const hookBody = (hooks?.data ?? {});
+            const inboxBody = (inboxes?.data ?? {});
+            const planLocked = hooks?.status === 403;
+            return successEnvelope({
+                data: {
+                    account: {
+                        liveDeliveryAvailable: hooks ? hooks.ok : null,
+                        ...(planLocked ? { upgradeUrl: hookBody.upgradeUrl, currentPlan: hookBody.currentPlan, whatYouCanDoNow: 'Create a test inbox and add sample events to see the real payloads. Live delivery needs Pro or Scale.' } : {}),
+                        webhooks: hooks?.ok ? hookBody.webhooks : [],
+                        inboxes: inboxes?.ok ? inboxBody.inboxes : [],
+                    },
+                    whatTheyAre: 'Cito POSTs a signed JSON event to your URL when something happens, so you stop polling and spending calls to find out.',
+                    steps: c.setup,
+                    plans: c.plans,
+                    delivery: c.delivery,
+                    filters: c.filters,
+                    envelope: c.envelope,
+                    activeEvents: c.events.filter((e) => e.status === 'active').map((e) => ({ event: e.event, typicalFrequency: e.typicalFrequency })),
+                    verifySignature: {
+                        node: "const ok = crypto.timingSafeEqual(Buffer.from(req.headers['x-cito-signature']), Buffer.from(crypto.createHmac('sha256', process.env.CITO_WEBHOOK_SECRET).update(rawBody).digest('hex')));",
+                        python: "ok = hmac.compare_digest(headers['X-Cito-Signature'], hmac.new(os.environ['CITO_WEBHOOK_SECRET'].encode(), raw_body, hashlib.sha256).hexdigest())",
+                        note: 'Hash the raw request bytes before parsing JSON.',
+                    },
+                    safety: 'Writes through these tools only touch this account\'s webhooks and test inboxes. The account owner gets an email when a key creates a webhook or changes its URL.',
+                    docs: c.docs,
+                },
+                game: null,
+                source: 'explain_webhook_setup',
+                upstreamCalls: 3,
+            });
+        },
+    },
+    {
+        name: 'list_webhooks',
+        description: 'This account\'s webhooks with their health: failures, last success, last error, and whether sending is paused. Never includes secrets. Needs a plan with webhooks. API calls: 1.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        annotations: READ_TOOL_ANNOTATIONS,
+        handler: async (_args, ctx) => callApi(ctx, 'list_webhooks', 'GET', '/webhooks'),
+    },
+    {
+        name: 'create_webhook',
+        description: 'Create a webhook on this account: Cito starts POSTing the chosen events to the URL. Needs Pro or Scale; a plan error includes the upgrade link to relay. The URL must be public. The account owner is emailed. webhook.secret comes back ONCE: have the user store it in an environment variable such as CITO_WEBHOOK_SECRET, and do not repeat it in chat. Then call test_webhook. API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            required: ['url', 'events'],
+            properties: {
+                url: stringSchema('Public URL that accepts POST and answers 2xx within 10 seconds. A test inbox url works too.', 'https://your-domain.com/webhooks/cito'),
+                events: eventsArg,
+                filters: filtersArg,
+            },
+            additionalProperties: false,
+        },
+        annotations: WRITE,
+        handler: async (args, ctx) => {
+            if (typeof args.url !== 'string' || !Array.isArray(args.events)) {
+                return bad('create_webhook', 'url and events are required.', ['Call list_webhook_events to pick events, then retry with url and events.']);
+            }
+            return callApi(ctx, 'create_webhook', 'POST', '/webhooks', { body: { url: args.url, events: args.events, ...(args.filters ? { filters: args.filters } : {}) } }, (b) => ({
+                ...b,
+                secretHandling: 'Store webhook.secret in an environment variable now. It is never shown again; regenerate_webhook_secret replaces it.',
+            }));
+        },
+    },
+    {
+        name: 'update_webhook',
+        description: 'Change a webhook\'s URL, events, filters or on/off state. Changing the URL emails the account owner. Send only what changes. API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            required: ['id'],
+            properties: {
+                id: idArg,
+                url: stringSchema('New public URL.'),
+                events: eventsArg,
+                filters: { ...filtersArg, description: `${filtersArg.description} Send null to clear them.`, type: ['object', 'null'] },
+                isActive: boolSchema('false pauses the webhook; true turns it back on and clears its failures.'),
+            },
+            additionalProperties: false,
+        },
+        annotations: WRITE,
+        handler: async (args, ctx) => {
+            const body = {};
+            for (const k of ['url', 'events', 'filters', 'isActive'])
+                if (args[k] !== undefined)
+                    body[k] = args[k];
+            if (typeof args.id !== 'string')
+                return bad('update_webhook', 'id is required.', ['Call list_webhooks to find the id.']);
+            if (Object.keys(body).length === 0)
+                return bad('update_webhook', 'Nothing to change.', ['Send at least one of url, events, filters, isActive.']);
+            return callApi(ctx, 'update_webhook', 'PATCH', `/webhooks/${encodeURIComponent(args.id)}`, { body });
+        },
+    },
+    {
+        name: 'delete_webhook',
+        description: 'Permanently delete a webhook on this account. Only call this when the user clearly asked to delete this specific webhook, and pass confirm: true. To stop deliveries without deleting, use update_webhook with isActive false. API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            required: ['id', 'confirm'],
+            properties: { id: idArg, confirm: boolSchema('Must be true. Set it only after the user clearly asked to delete this webhook.') },
+            additionalProperties: false,
+        },
+        annotations: DESTRUCTIVE,
+        handler: async (args, ctx) => {
+            if (args.confirm !== true) {
+                return bad('delete_webhook', 'Not deleted: confirm must be true.', ['Ask the user whether to delete this webhook, naming its URL. Then retry with confirm: true.', 'To stop deliveries without deleting, use update_webhook with isActive false.']);
+            }
+            if (typeof args.id !== 'string')
+                return bad('delete_webhook', 'id is required.', ['Call list_webhooks to find the id.']);
+            return callApi(ctx, 'delete_webhook', 'DELETE', `/webhooks/${encodeURIComponent(args.id)}`);
+        },
+    },
+    {
+        name: 'regenerate_webhook_secret',
+        description: 'Replace a webhook\'s signing secret. The old secret stops verifying immediately, so only do this when the user asks. The new secret comes back once: have them store it, and do not repeat it in chat. API calls: 1.',
+        inputSchema: { type: 'object', required: ['id'], properties: { id: idArg }, additionalProperties: false },
+        annotations: WRITE,
+        handler: async (args, ctx) => {
+            if (typeof args.id !== 'string')
+                return bad('regenerate_webhook_secret', 'id is required.', ['Call list_webhooks to find the id.']);
+            return callApi(ctx, 'regenerate_webhook_secret', 'POST', `/webhooks/${encodeURIComponent(args.id)}/regenerate-secret`, { body: {} });
+        },
+    },
+    {
+        name: 'test_webhook',
+        description: 'Send a test to a webhook now and report what happened: status, statusCode, latencyMs and a plain-English diagnosis to relay. With event, sends a real recent sample of that event, signed and marked as a test (test: true, data.test: true, X-Cito-Test: true); without it, a short ping. API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            required: ['id'],
+            properties: { id: idArg, event: stringSchema('Event to sample, from list_webhook_events.', 'cs2.match.completed') },
+            additionalProperties: false,
+        },
+        annotations: WRITE,
+        handler: async (args, ctx) => {
+            if (typeof args.id !== 'string')
+                return bad('test_webhook', 'id is required.', ['Call list_webhooks to find the id.']);
+            return callApi(ctx, 'test_webhook', 'POST', `/webhooks/${encodeURIComponent(args.id)}/test`, { body: args.event ? { event: args.event } : {} }, (b) => without(b, 'debug'));
+        },
+    },
+    {
+        name: 'webhook_deliveries',
+        description: 'A webhook\'s delivery log, newest first: event, status (delivered, failed, skipped_backoff), HTTP code, error and a diagnosis. Pass deliveryId for one delivery with its payload. skipped_backoff means the event was NOT sent because the webhook was paused; see catch_up_webhook. API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            required: ['id'],
+            properties: {
+                id: idArg,
+                deliveryId: stringSchema('One delivery, with its payload.'),
+                status: stringSchema('delivered, failed, skipped_backoff; comma separated.', 'failed,skipped_backoff'),
+                event: stringSchema('Only this event name.'),
+                matchId: stringSchema('Only this match.'),
+                since: stringSchema('ISO 8601 time.'),
+                until: stringSchema('ISO 8601 time.'),
+                summary: boolSchema('Add 7-day counts by status.'),
+                limit: limitSchema({ default: 20, max: 100 }),
+                cursor: stringSchema('nextCursor from the previous page.'),
+            },
+            additionalProperties: false,
+        },
+        annotations: READ_TOOL_ANNOTATIONS,
+        handler: async (args, ctx) => {
+            if (typeof args.id !== 'string')
+                return bad('webhook_deliveries', 'id is required.', ['Call list_webhooks to find the id.']);
+            const base = `/webhooks/${encodeURIComponent(args.id)}/deliveries`;
+            if (typeof args.deliveryId === 'string') {
+                return callApi(ctx, 'webhook_deliveries', 'GET', `${base}/${encodeURIComponent(args.deliveryId)}`);
+            }
+            return callApi(ctx, 'webhook_deliveries', 'GET', base, {
+                query: { status: args.status, event: args.event, matchId: args.matchId, since: args.since, until: args.until, limit: args.limit ?? 20, cursor: args.cursor, include: args.summary ? 'summary' : undefined },
+            });
+        },
+    },
+    {
+        name: 'replay_webhook',
+        description: 'Re-send stored events to this webhook: one eventId, or a matchId (at most 10 events, optionally one eventType). Each is marked data.replayed true with data.original_event_id, so the receiver can deduplicate. Take the ids from webhook_deliveries. API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            required: ['id'],
+            properties: { id: idArg, eventId: stringSchema('One event to re-send.'), matchId: stringSchema('Re-send this match\'s events.'), eventType: stringSchema('With matchId, only this event name.') },
+            additionalProperties: false,
+        },
+        annotations: WRITE,
+        handler: async (args, ctx) => {
+            if (typeof args.id !== 'string')
+                return bad('replay_webhook', 'id is required.', ['Call list_webhooks to find the id.']);
+            const body = {};
+            for (const k of ['eventId', 'matchId', 'eventType'])
+                if (args[k] !== undefined)
+                    body[k] = args[k];
+            return callApi(ctx, 'replay_webhook', 'POST', `/webhooks/${encodeURIComponent(args.id)}/replay`, { body });
+        },
+    },
+    {
+        name: 'catch_up_webhook',
+        description: 'After an endpoint outage: re-send the match and result events this webhook missed (failed, or skipped during a pause) and never received. Live ticks are left out. Use dryRun first to see how many. Stops at the first failure. API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            required: ['id'],
+            properties: {
+                id: idArg,
+                since: stringSchema('ISO 8601 time. Default 24 hours ago, at most 7 days.'),
+                limit: limitSchema({ default: 50, max: 100 }),
+                dryRun: boolSchema('Only report what is missing.'),
+            },
+            additionalProperties: false,
+        },
+        annotations: WRITE,
+        handler: async (args, ctx) => {
+            if (typeof args.id !== 'string')
+                return bad('catch_up_webhook', 'id is required.', ['Call list_webhooks to find the id.']);
+            const body = {};
+            for (const k of ['since', 'limit', 'dryRun'])
+                if (args[k] !== undefined)
+                    body[k] = args[k];
+            return callApi(ctx, 'catch_up_webhook', 'POST', `/webhooks/${encodeURIComponent(args.id)}/catch-up`, { body });
+        },
+    },
+    {
+        name: 'create_webhook_inbox',
+        description: 'Create a hosted temporary URL that stores webhook requests, so no server or tunnel is needed. Works on every plan and lasts 24 hours. Free and Starter accounts add samples with send_inbox_sample; on Pro or Scale, a webhook can target its url to see real events. signingSecret comes back once. API calls: 1.',
+        inputSchema: { type: 'object', properties: { name: stringSchema('Optional label.') }, additionalProperties: false },
+        annotations: WRITE,
+        handler: async (args, ctx) => callApi(ctx, 'create_webhook_inbox', 'POST', '/webhook-inbox', { body: args.name ? { name: args.name } : {} }),
+    },
+    {
+        name: 'list_webhook_inboxes',
+        description: 'This account\'s live test inboxes, their limits and whether the plan includes live delivery. API calls: 1.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        annotations: READ_TOOL_ANNOTATIONS,
+        handler: async (_args, ctx) => callApi(ctx, 'list_webhook_inboxes', 'GET', '/webhook-inbox'),
+    },
+    {
+        name: 'read_webhook_inbox',
+        description: 'What an inbox received: headers, body and whether the signature was valid. To poll, pass latestRequestId from the previous call as after. API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            required: ['id'],
+            properties: { id: inboxIdArg, after: stringSchema('Only requests newer than this id.'), limit: limitSchema({ default: 10, max: 100 }) },
+            additionalProperties: false,
+        },
+        annotations: READ_TOOL_ANNOTATIONS,
+        handler: async (args, ctx) => {
+            if (typeof args.id !== 'string')
+                return bad('read_webhook_inbox', 'id is required.', ['Call list_webhook_inboxes to find the id.']);
+            return callApi(ctx, 'read_webhook_inbox', 'GET', `/webhook-inbox/${encodeURIComponent(args.id)}/requests`, { query: { after: args.after, limit: args.limit ?? 10 } });
+        },
+    },
+    {
+        name: 'send_inbox_sample',
+        description: 'Put a real sample of an event into a test inbox, signed with the inbox secret and marked as a test. Any plan, any event; below Pro the sample is at least 2 hours old. Up to 30 an hour. API calls: 1.',
+        inputSchema: {
+            type: 'object',
+            required: ['id', 'event'],
+            properties: { id: inboxIdArg, event: stringSchema('Event name from list_webhook_events.', 'cs2.match.completed') },
+            additionalProperties: false,
+        },
+        annotations: WRITE,
+        handler: async (args, ctx) => {
+            if (typeof args.id !== 'string' || typeof args.event !== 'string')
+                return bad('send_inbox_sample', 'id and event are required.', ['Call list_webhook_inboxes and list_webhook_events.']);
+            return callApi(ctx, 'send_inbox_sample', 'POST', `/webhook-inbox/${encodeURIComponent(args.id)}/sample`, { body: { event: args.event } });
+        },
+    },
+    {
+        name: 'clear_webhook_inbox',
+        description: 'Remove everything stored in a test inbox. The inbox and its URL stay. API calls: 1.',
+        inputSchema: { type: 'object', required: ['id'], properties: { id: inboxIdArg }, additionalProperties: false },
+        annotations: DESTRUCTIVE,
+        handler: async (args, ctx) => {
+            if (typeof args.id !== 'string')
+                return bad('clear_webhook_inbox', 'id is required.', ['Call list_webhook_inboxes to find the id.']);
+            return callApi(ctx, 'clear_webhook_inbox', 'DELETE', `/webhook-inbox/${encodeURIComponent(args.id)}/requests`);
+        },
+    },
+    {
+        name: 'delete_webhook_inbox',
+        description: 'Delete a test inbox and what it holds. A webhook still pointing at it starts failing, so update or delete that webhook too. API calls: 1.',
+        inputSchema: { type: 'object', required: ['id'], properties: { id: inboxIdArg }, additionalProperties: false },
+        annotations: DESTRUCTIVE,
+        handler: async (args, ctx) => {
+            if (typeof args.id !== 'string')
+                return bad('delete_webhook_inbox', 'id is required.', ['Call list_webhook_inboxes to find the id.']);
+            return callApi(ctx, 'delete_webhook_inbox', 'DELETE', `/webhook-inbox/${encodeURIComponent(args.id)}`);
+        },
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Standalone MCP server for the Cito esports and sports API — curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
   "type": "module",
   "homepage": "https://cito.gg",