cito-mcp 0.5.7 → 0.6.0

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.7",
+  "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",