cito-mcp 0.5.2 → 0.5.3

package/dist/client.js

@@ -1,3 +1,4 @@
+import { MAX_RATE_LIMIT_RETRIES, MAX_UPSTREAM_RETRIES, MAX_WAIT_MS, UPSTREAM_BACKOFF_MS, classify429, getClock, jitterMs, newCallBudget, pacerFor, } from './pacing.js';
 import { PACKAGE_VERSION } from './version.js';
 export const DEFAULT_API_BASE = 'https://api.citoapi.com/api/v1';
 export const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024;
@@ -16,8 +17,10 @@ export function authHeaders(apiKey, extra) {
 export function parseRateLimitHeaders(headers) {
     if (!headers)
         return {};
-    const limitRaw = headers.get('x-ratelimit-limit') ?? headers.get('ratelimit-limit');
-    const remainingRaw = headers.get('x-ratelimit-remaining') ?? headers.get('ratelimit-remaining');
+    const limitRaw = headers.get('x-ratelimit-limit-minute') ?? headers.get('x-ratelimit-limit') ?? headers.get('ratelimit-limit');
+    const remainingRaw = headers.get('x-ratelimit-remaining-minute') ??
+        headers.get('x-ratelimit-remaining') ??
+        headers.get('ratelimit-remaining');
     const resetRaw = headers.get('x-ratelimit-reset') ?? headers.get('ratelimit-reset');
     const tier = headers.get('x-cito-tier') ?? headers.get('x-plan-tier');
     return {
@@ -80,38 +83,111 @@ export async function fetchJson(ctx, path, opts) {
         headers['content-type'] = 'application/json';
         body = JSON.stringify(opts.body);
     }
-    let response;
-    try {
-        response = await fetcher(url, { method, headers, body });
-    }
-    catch (error) {
-        return {
-            ok: false,
-            status: 0,
-            data: { message: error.message },
-            headers: {},
-            text: error.message,
+    const budget = ctx.budget ?? newCallBudget();
+    const pacer = pacerFor(ctx.apiKey);
+    const clock = getClock();
+    let rateLimitRetries = 0;
+    let upstreamRetries = 0;
+    for (;;) {
+        const gate = await pacer.acquire(budget);
+        if (!gate.ok) {
+            const event = {
+                ...(pacer.last429 ?? classify429(null)),
+                message: null,
+                retryAfterMs: gate.waitMs,
+                local: true,
+            };
+            budget.rateLimit = event;
+            const body = {
+                success: false,
+                error: {
+                    code: event.apiCode,
+                    status: 429,
+                    message: `This API key is rate-limited by the Cito API. Retry in ${Math.ceil(gate.waitMs / 1000)} seconds.`,
+                    retry_after_seconds: Math.ceil(gate.waitMs / 1000),
+                    ...(event.upgradeUrl ? { upgrade: event.upgradeUrl } : {}),
+                },
+            };
+            const text = JSON.stringify(body);
+            return {
+                ok: false,
+                status: 429,
+                data: body,
+                headers: {},
+                text,
+                url,
+                rateLimit: event,
+                retries: rateLimitRetries + upstreamRetries,
+            };
+        }
+        let response;
+        let text;
+        try {
+            response = await fetcher(url, { method, headers, body });
+            text = await response.text();
+        }
+        catch (error) {
+            gate.release();
+            return {
+                ok: false,
+                status: 0,
+                data: { message: error.message },
+                headers: {},
+                text: error.message,
+                url,
+            };
+        }
+        gate.release();
+        let data = null;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = text;
+        }
+        const limited = response.status === 429 ? classify429(data, response.headers) : undefined;
+        pacer.observe(response.status, response.headers, limited);
+        if (limited) {
+            budget.rateLimit = limited;
+            const wait = limited.retryAfterMs ?? 2_000;
+            const retryable = limited.kind !== 'monthly' &&
+                rateLimitRetries < MAX_RATE_LIMIT_RETRIES &&
+                wait <= MAX_WAIT_MS &&
+                clock.now() + wait < budget.deadline;
+            if (retryable) {
+                rateLimitRetries += 1;
+                budget.retries += 1;
+                log(`429 ${limited.apiCode} on ${path}; retry ${rateLimitRetries}/${MAX_RATE_LIMIT_RETRIES} after ${wait} ms`);
+                continue;
+            }
+        }
+        else if (response.status === 502 || response.status === 503) {
+            const wait = UPSTREAM_BACKOFF_MS + jitterMs();
+            if (upstreamRetries < MAX_UPSTREAM_RETRIES && clock.now() + wait < budget.deadline) {
+                upstreamRetries += 1;
+                budget.retries += 1;
+                budget.waitedMs += wait;
+                log(`${response.status} on ${path}; retry after ${wait} ms`);
+                await clock.sleep(wait);
+                continue;
+            }
+        }
+        if (!opts?.raw && response.ok && isTennisPath(path))
+            data = flattenTennisEnvelope(data);
+        const result = {
+            ok: response.ok,
+            status: response.status,
+            data,
+            headers: parseRateLimitHeaders(response.headers),
+            text,
             url,
         };
+        if (limited)
+            result.rateLimit = limited;
+        if (rateLimitRetries + upstreamRetries > 0)
+            result.retries = rateLimitRetries + upstreamRetries;
+        return result;
     }
-    const text = await response.text();
-    let data = null;
-    try {
-        data = text ? JSON.parse(text) : null;
-    }
-    catch {
-        data = text;
-    }
-    if (!opts?.raw && response.ok && isTennisPath(path))
-        data = flattenTennisEnvelope(data);
-    return {
-        ok: response.ok,
-        status: response.status,
-        data,
-        headers: parseRateLimitHeaders(response.headers),
-        text,
-        url,
-    };
 }
 export async function parallelGet(ctx, paths) {
     const results = await Promise.all(paths.map(async ({ key, path, query }) => {

package/dist/envelope.js

@@ -194,6 +194,84 @@ export function sealEnvelope(envelope) {
         },
     };
 }
+export function applyRateLimitContext(envelope, event, retries = 0) {
+    if (!event)
+        return envelope;
+    const seconds = event.retryAfterMs != null ? Math.max(1, Math.ceil(event.retryAfterMs / 1000)) : null;
+    const upgrade = event.upgradeUrl;
+    if (envelope.ok) {
+        if (!envelope.partial?.some((p) => p.code === 'RATE_LIMIT'))
+            return envelope;
+        const note = event.kind === 'monthly'
+            ? `Some sections were not fetched: this key has used its monthly requests${upgrade ? ` (upgrade: ${upgrade})` : ''}.`
+            : `Some sections hit the Cito API rate limit after cito-mcp paced and retried them${seconds ? `; retry in ${seconds} s` : ''}${upgrade ? ` (higher limits: ${upgrade})` : ''}.`;
+        return { ...envelope, meta: { ...envelope.meta, warnings: [...(envelope.meta.warnings ?? []), note] } };
+    }
+    if (envelope.error.code !== 'RATE_LIMIT')
+        return envelope;
+    const details = {
+        ...(envelope.error.details ?? {}),
+        apiCode: event.apiCode,
+        retriedByMcp: retries,
+    };
+    if (event.plan)
+        details.plan = event.plan;
+    if (event.limitPerMinute != null)
+        details.limitPerMinute = event.limitPerMinute;
+    if (event.burstPerMinute != null)
+        details.burstPerMinute = event.burstPerMinute;
+    if (upgrade)
+        details.upgrade = upgrade;
+    if (event.kind === 'monthly') {
+        return {
+            ...envelope,
+            error: {
+                ...envelope.error,
+                message: event.message ||
+                    `This API key has used all of its requests for the month, so the Cito API refused this call (MONTHLY_LIMIT_REACHED).${upgrade ? ` Upgrade for more: ${upgrade}` : ''}`,
+                retryable: false,
+                retryAfterMs: event.retryAfterMs,
+                ...(upgrade ? { hint: `Upgrade for more monthly requests: ${upgrade}` } : {}),
+                recover: [
+                    'Do not retry: the monthly allowance is used up, and waiting seconds or minutes will not help',
+                    ...(upgrade ? [`Tell the user they can upgrade for more requests: ${upgrade}`] : []),
+                    'Or wait for the monthly reset named in the message',
+                ],
+                details,
+            },
+        };
+    }
+    const limitText = event.limitPerMinute != null
+        ? ` (${event.plan ? `${event.plan} plan: ` : ''}${event.limitPerMinute} requests per minute on average${event.burstPerMinute ? `, bursts to ${event.burstPerMinute}` : ''})`
+        : '';
+    const what = event.kind === 'concurrency'
+        ? 'The Cito API refused this call because this key had too many requests in flight at once'
+        : `The Cito API rate-limited this key${limitText}`;
+    const waited = retries > 0
+        ? ` cito-mcp already waited and retried ${retries} time${retries === 1 ? '' : 's'}.`
+        : event.local
+            ? ' cito-mcp held the request back because the API had already asked this key to wait.'
+            : '';
+    const message = `${what}.${waited}` +
+        (seconds ? ` Retry in ${seconds} second${seconds === 1 ? '' : 's'}.` : '') +
+        (upgrade && event.kind !== 'concurrency' ? ` For a higher per-minute limit, upgrade: ${upgrade}` : '');
+    return {
+        ...envelope,
+        error: {
+            ...envelope.error,
+            message,
+            retryable: true,
+            retryAfterMs: event.retryAfterMs,
+            ...(upgrade && event.kind !== 'concurrency' ? { hint: `Higher per-minute limits: ${upgrade}` } : {}),
+            recover: [
+                seconds ? `Wait ${seconds} seconds, then retry this tool once` : 'Wait a minute, then retry this tool once',
+                'Call tools one at a time instead of in parallel, and prefer one composite tool over several thin ones',
+                ...(upgrade && event.kind !== 'concurrency' ? [`Tell the user a paid plan raises the limit: ${upgrade}`] : []),
+            ],
+            details,
+        },
+    };
+}
 export const ENVELOPE_OUTPUT_SCHEMA = {
     type: 'object',
     additionalProperties: true,

package/dist/instructions.js

@@ -1,82 +1,82 @@
-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.
-
-## Hard rules
-
-1. **Never invent IDs.** Do not guess matchId, gameId, playerId, team slug, eventId, or boutId. Always obtain IDs from a prior tool result (resolve, live, schedule, search, or list). If the user gives a name ("T1", "s1mple", "UFC 300"), call resolve_entity/search_entities first.
-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.
-
-## Game parameter
-
-game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | tennis | all
-
-- Default when the user named one title: that game. Default for "what's live?" / multi-title: omit game or all on tools that accept it.
-- On UNSUPPORTED_GAME / 403 for a title: stop retrying that game; call api_health; report plan gaps.
-- Fortnite and other titles may appear via call_api/resources; do not assume they are in the curated enum until list_capabilities says so.
-- 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.
-- 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
-
-1. Unsure → list_capabilities (filter by game or job). Optional: api_health for key/tier/included games.
-2. Name without ID → resolve_entity (best match) or search_entities (browse). Reuse returned id/slug.
-3. Live / upcoming → live_matches; upcoming_schedule.
-4. Match UI / recap → match_summary first. match_details only for timelines, full maps, demos, live state.
-5. Team page → team_profile. Player form → player_profile. Tables/ranks → standings.
-6. Pre-match → match_preview. Rivalry → head_to_head. Event / fight-night card → event_card.
-7. Escape hatch → call_api (allowlisted path prefixes; prefer GET). Prefer curated tools.
-
-Mnemonic: resolve → live/schedule → summary → deep.
-
-## Parallel vs sequence
-
-Parallel-safe: independent reads (team_profile A ∥ team_profile B; live_matches ∥ api_health). Cap ~3–5 concurrent agent tools; check meta.rateLimit.remaining.
-
-Serial required: resolve → detail; pagination (cursor from page N only); live board → selected match deep-dive.
-
-Prefer server-side fan-out inside composites (partial[] recovery) over agent N+1.
-
-## Pagination
-
-Lists use pagination: { limit, offset?, total?, hasMore, nextCursor, prevCursor }. Default limit 20, max 50. Loop with cursor: pagination.nextCursor and the same filters. Never invent cursors. Empty list is ok:true with items:[].
-
-## 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.
-
-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.
-resolve_entity ambiguity is soft: ok:true with data.needsDisambiguation and data.candidates — pick a candidate; do not wait for AMBIGUOUS_ENTITY.
-
-## Recipes
-
-Live board: api_health (optional) → live_matches → match_summary for selected matchId.
-UFC empty live (count=0): read section.note / emptyReason / health (workerAlive, lag) / supervisor / nextCard — do not claim "API offline" without workerAlive/lag; never invent matchups from supervisor shells.
-Team page: resolve_entity {type:team} → team_profile.
-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.
-
-## Resources
-
-- cito://llms.txt — product context when available
-- cito://capabilities — catalog summary
-- cito://openapi.json — optional public OpenAPI fetch for typed clients
-
-## What not to do
-
-- Invent match/player/team IDs from memory.
-- Parallel-paginate the same list with different cursors.
-- N+1 match_details for every live row.
-- Retry UNSUPPORTED_GAME or VALIDATION unchanged.
-- Ship production traffic through MCP.
-- Flood odds/timelines when a summary answers the question.
+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.
+
+## Hard rules
+
+1. **Never invent IDs.** Do not guess matchId, gameId, playerId, team slug, eventId, or boutId. Always obtain IDs from a prior tool result (resolve, live, schedule, search, or list). If the user gives a name ("T1", "s1mple", "UFC 300"), call resolve_entity/search_entities first.
+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.
+
+## Game parameter
+
+game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | tennis | all
+
+- Default when the user named one title: that game. Default for "what's live?" / multi-title: omit game or all on tools that accept it.
+- On UNSUPPORTED_GAME / 403 for a title: stop retrying that game; call api_health; report plan gaps.
+- Fortnite and other titles may appear via call_api/resources; do not assume they are in the curated enum until list_capabilities says so.
+- 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.
+- 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
+
+1. Unsure → list_capabilities (filter by game or job). Optional: api_health for key/tier/included games.
+2. Name without ID → resolve_entity (best match) or search_entities (browse). Reuse returned id/slug.
+3. Live / upcoming → live_matches; upcoming_schedule.
+4. Match UI / recap → match_summary first. match_details only for timelines, full maps, demos, live state.
+5. Team page → team_profile. Player form → player_profile. Tables/ranks → standings.
+6. Pre-match → match_preview. Rivalry → head_to_head. Event / fight-night card → event_card.
+7. Escape hatch → call_api (allowlisted path prefixes; prefer GET). Prefer curated tools.
+
+Mnemonic: resolve → live/schedule → summary → deep.
+
+## Parallel vs sequence
+
+Parallel-safe: independent reads (team_profile A ∥ team_profile B; live_matches ∥ api_health). Cap ~3–5 concurrent agent tools; check meta.rateLimit.remaining.
+
+Serial required: resolve → detail; pagination (cursor from page N only); live board → selected match deep-dive.
+
+Prefer server-side fan-out inside composites (partial[] recovery) over agent N+1.
+
+## Pagination
+
+Lists use pagination: { limit, offset?, total?, hasMore, nextCursor, prevCursor }. Default limit 20, max 50. Loop with cursor: pagination.nextCursor and the same filters. Never invent cursors. Empty list is ok:true with items:[].
+
+## 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: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.
+resolve_entity ambiguity is soft: ok:true with data.needsDisambiguation and data.candidates — pick a candidate; do not wait for AMBIGUOUS_ENTITY.
+
+## Recipes
+
+Live board: api_health (optional) → live_matches → match_summary for selected matchId.
+UFC empty live (count=0): read section.note / emptyReason / health (workerAlive, lag) / supervisor / nextCard — do not claim "API offline" without workerAlive/lag; never invent matchups from supervisor shells.
+Team page: resolve_entity {type:team} → team_profile.
+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.
+
+## Resources
+
+- cito://llms.txt — product context when available
+- cito://capabilities — catalog summary
+- cito://openapi.json — optional public OpenAPI fetch for typed clients
+
+## What not to do
+
+- Invent match/player/team IDs from memory.
+- Parallel-paginate the same list with different cursors.
+- N+1 match_details for every live row.
+- Retry UNSUPPORTED_GAME or VALIDATION unchanged.
+- Ship production traffic through MCP.
+- Flood odds/timelines when a summary answers the question.
 `;

package/dist/pacing.js

@@ -0,0 +1,195 @@
+export const MAX_CONCURRENT_PER_KEY = 4;
+export const CONSTRAINED_CONCURRENT_PER_KEY = 2;
+export const CONSTRAINED_WINDOW_MS = 60_000;
+export const MAX_WAIT_MS = 20_000;
+export const MAX_RATE_LIMIT_RETRIES = 2;
+export const MAX_UPSTREAM_RETRIES = 1;
+export const UPSTREAM_BACKOFF_MS = 750;
+export const CALL_BUDGET_MS = 45_000;
+const DEFAULT_RETRY_AFTER_MS = 2_000;
+const WINDOW_MS = 60_000;
+const IDLE_EVICT_MS = 10 * 60_000;
+const MAX_TRACKED_KEYS = 2_000;
+export const UPGRADE_URL = 'https://citoapi.com/dashboard/billing/plans';
+const realClock = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms))),
+};
+let clock = realClock;
+let jitter = () => Math.floor(Math.random() * 250);
+export function getClock() {
+    return clock;
+}
+export function __setClockForTests(fake, jitterMs) {
+    clock = fake ?? realClock;
+    jitter = jitterMs ?? (fake ? () => 0 : () => Math.floor(Math.random() * 250));
+}
+export function jitterMs() {
+    return jitter();
+}
+export function newCallBudget(budgetMs = CALL_BUDGET_MS) {
+    return { deadline: clock.now() + budgetMs, retries: 0, waitedMs: 0 };
+}
+function rec(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function num(value) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN;
+    return Number.isFinite(n) ? n : null;
+}
+export function parseRetryAfter(raw, nowMs = clock.now()) {
+    if (raw == null)
+        return null;
+    const value = String(raw).trim();
+    if (!value)
+        return null;
+    if (/^\d+(\.\d+)?$/.test(value))
+        return Math.round(Number(value) * 1000);
+    const at = Date.parse(value);
+    if (Number.isFinite(at))
+        return Math.max(0, at - nowMs);
+    return null;
+}
+export function classify429(body, headers, nowMs = clock.now()) {
+    const root = rec(body);
+    const err = rec(root?.error);
+    const apiCode = String(err?.code ?? root?.errorCode ?? root?.code ?? 'RATE_LIMIT_EXCEEDED');
+    const kind = apiCode === 'MONTHLY_LIMIT_REACHED'
+        ? 'monthly'
+        : apiCode === 'TOO_MANY_CONCURRENT_REQUESTS'
+            ? 'concurrency'
+            : 'per_minute';
+    const fromHeader = parseRetryAfter(headers?.get('retry-after') ?? null, nowMs);
+    const bodySeconds = num(err?.retry_after_seconds) ?? num(rec(err?.limit)?.retryAfterSeconds) ?? num(root?.retry_after_seconds);
+    const retryAfterMs = fromHeader ?? (bodySeconds != null ? Math.round(bodySeconds * 1000) : null);
+    const upgradeRaw = err?.upgrade;
+    const upgradeUrl = (typeof upgradeRaw === 'string' && upgradeRaw) ||
+        (typeof rec(upgradeRaw)?.url === 'string' && rec(upgradeRaw).url) ||
+        (typeof err?.upgradeUrl === 'string' && err.upgradeUrl) ||
+        (kind === 'concurrency' ? null : UPGRADE_URL);
+    const message = (typeof err?.message === 'string' && err.message) ||
+        (typeof root?.error === 'string' && root.error) ||
+        (typeof root?.message === 'string' && root.message) ||
+        null;
+    return {
+        kind,
+        apiCode,
+        message,
+        retryAfterMs,
+        upgradeUrl,
+        plan: typeof err?.plan === 'string' ? err.plan : null,
+        limitPerMinute: num(err?.limit_per_minute),
+        burstPerMinute: num(err?.burst_per_minute),
+        local: false,
+    };
+}
+export class KeyPacer {
+    inFlight = 0;
+    waiters = [];
+    remaining = null;
+    windowEndsAt = 0;
+    blockedUntil = 0;
+    constrainedUntil = 0;
+    lastUsed = 0;
+    last429 = null;
+    maxConcurrent(now) {
+        return now < this.constrainedUntil ? CONSTRAINED_CONCURRENT_PER_KEY : MAX_CONCURRENT_PER_KEY;
+    }
+    async slot() {
+        for (;;) {
+            if (this.inFlight < this.maxConcurrent(clock.now())) {
+                this.inFlight += 1;
+                return;
+            }
+            await new Promise((resolve) => this.waiters.push(resolve));
+        }
+    }
+    releaseSlot() {
+        this.inFlight = Math.max(0, this.inFlight - 1);
+        const next = this.waiters.shift();
+        if (next)
+            next();
+    }
+    async acquire(budget) {
+        await this.slot();
+        for (;;) {
+            const now = clock.now();
+            this.lastUsed = now;
+            if (this.remaining !== null && now >= this.windowEndsAt)
+                this.remaining = null;
+            let waitMs = 0;
+            let reason = 'blocked';
+            if (this.blockedUntil > now) {
+                waitMs = this.blockedUntil - now;
+            }
+            else if (this.remaining !== null && this.remaining <= 0) {
+                waitMs = this.windowEndsAt - now + 250;
+                reason = 'window';
+            }
+            if (waitMs <= 0)
+                break;
+            if (waitMs > MAX_WAIT_MS + 1_000 || now + waitMs >= budget.deadline) {
+                this.releaseSlot();
+                return { ok: false, waitMs, reason };
+            }
+            await clock.sleep(waitMs);
+            budget.waitedMs += waitMs;
+        }
+        if (this.remaining !== null)
+            this.remaining -= 1;
+        let released = false;
+        return {
+            ok: true,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.releaseSlot();
+            },
+        };
+    }
+    observe(status, headers, limited) {
+        const now = clock.now();
+        const remainingRaw = headers?.get('x-ratelimit-remaining-minute');
+        const remaining = num(remainingRaw);
+        if (remaining !== null) {
+            this.remaining = Math.max(0, remaining - this.inFlight);
+            this.windowEndsAt = (Math.floor(now / WINDOW_MS) + 1) * WINDOW_MS;
+        }
+        if (status === 429 && limited && limited.kind !== 'monthly') {
+            this.last429 = limited;
+            const wait = limited.retryAfterMs ?? DEFAULT_RETRY_AFTER_MS;
+            this.blockedUntil = Math.max(this.blockedUntil, now + wait + jitter());
+            this.constrainedUntil = now + CONSTRAINED_WINDOW_MS;
+        }
+    }
+}
+const pacers = new Map();
+export function pacerFor(apiKey) {
+    let pacer = pacers.get(apiKey);
+    if (!pacer) {
+        if (pacers.size >= MAX_TRACKED_KEYS)
+            evictIdle();
+        pacer = new KeyPacer();
+        pacers.set(apiKey, pacer);
+    }
+    return pacer;
+}
+function evictIdle() {
+    const now = clock.now();
+    for (const [key, p] of pacers) {
+        if (p.inFlight === 0 && now - p.lastUsed > IDLE_EVICT_MS)
+            pacers.delete(key);
+    }
+    if (pacers.size >= MAX_TRACKED_KEYS) {
+        for (const [key, p] of pacers) {
+            if (pacers.size < MAX_TRACKED_KEYS)
+                break;
+            if (p.inFlight === 0)
+                pacers.delete(key);
+        }
+    }
+}
+export function __resetPacersForTests() {
+    pacers.clear();
+}

package/dist/tools/types.js

@@ -1,4 +1,5 @@
-import { ENVELOPE_OUTPUT_SCHEMA, toMcpResult } from '../envelope.js';
+import { ENVELOPE_OUTPUT_SCHEMA, applyRateLimitContext, toMcpResult } from '../envelope.js';
+import { newCallBudget } from '../pacing.js';
 export const READ_TOOL_ANNOTATIONS = {
     readOnlyHint: true,
     destructiveHint: false,
@@ -138,11 +139,19 @@ export async function runTool(def, args, ctx) {
                 ],
             }));
         }
-        const result = await def.handler(args ?? {}, ctx);
+        const budget = ctx.budget ?? newCallBudget();
+        const result = await def.handler(args ?? {}, { ...ctx, budget });
         if (result && typeof result === 'object' && 'content' in result) {
-            return result;
+            const mcp = result;
+            const structured = mcp.structuredContent;
+            if (budget.rateLimit && structured && typeof structured === 'object' && 'ok' in structured) {
+                const enriched = applyRateLimitContext(structured, budget.rateLimit, budget.retries);
+                if (enriched !== structured)
+                    return toMcpResult(enriched);
+            }
+            return mcp;
         }
-        return toMcpResult(result);
+        return toMcpResult(applyRateLimitContext(result, budget.rateLimit, budget.retries));
     }
     catch (error) {
         const { errorEnvelope, toMcpResult: toResult } = await import('../envelope.js');

package/package.json

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