cito-mcp 0.4.4 → 0.4.6

package/README.md

@@ -195,15 +195,15 @@ on `event_card` bout corners and on `player_profile`. No extra call, no N+1.
   "record": { "wins": 28, "losses": 1, "draws": 0, "text": "28-1-0 (W-L-D)" },
   "championStatus": "champion",
   "images": {
-    "headshotUrl":     "https://ufc.com/…/MAKHACHEV_ISLAM_BELT_01-18.png",
-    "bodyImageUrl":    "https://ufc.com/…/athlete_bio_full_body/…",
-    "imageUrl":        "https://ufc.com/…/event_fight_card_upper_body/…",
+    "headshotUrl":     "https://…/MAKHACHEV_ISLAM_BELT_01-18.png",
+    "bodyImageUrl":    "https://…/athlete_bio_full_body/…",
+    "imageUrl":        "https://…/event_fight_card_upper_body/…",
     "proxiedImageUrl": "https://api.citoapi.com/api/v1/public/images/ufc/aHR0cHM6…"
   }
 }
 ```
 
-**Use `proxiedImageUrl` in a browser.** `ufc.com` sends no CORS header and can
+**Use `proxiedImageUrl` in a browser.** the image host sends no CORS header and can
 hotlink-block, so raw URLs render as broken images in a web UI. The proxied URL
 is served by the API and is safe to put in an `<img src>`.
 
@@ -213,7 +213,7 @@ never partially shaped — if any image exists, all four keys are present.
 
 Tennis is the exception on purpose: the feed supplies a single `portrait_url`
 (Wikimedia Commons) and no square crop, so that one URL fills both `headshotUrl`
-and `imageUrl`, and `proxiedImageUrl` stays `null` because only `ufc.com` URLs have
+and `imageUrl`, and `proxiedImageUrl` stays `null` because only fighter image URLs have
 a proxy.
 
 **Tennis images carry their licence and credit** — and a UI is expected to render
@@ -535,7 +535,7 @@ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 ### Semver expectations
 
 - **0.2.4** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
-- Further 0.2.x patches may refine envelopes and composite quality without renaming the 15 tools.
+- Further 0.2.x patches may refine envelopes and composite quality without renaming the shipped tools. (This line previously said "15 tools" while the catalog shipped 42 — the count here is intentionally not restated, because a number duplicated in prose drifts the moment the catalog changes.)
 - Promoting Fortnite (or other titles) into the primary `game` enum would be a minor feature bump with catalog/docs updates.
 
 ---
@@ -560,7 +560,7 @@ Second tennis correctness pass, from the 2026-09-12 re-sweep. Five defects, each
 Tennis correctness pass, driven by the 2026-09-12 sweep (`reports/tennis-mcp-sweep-2026-09-12.md`). Every item was reproduced against live ids and re-verified after the fix.
 
 - **`match_summary` tennis scoreline was always `- : -`.** `/tennis/matches/{id}` puts no `sets_won` on its player objects, so the sets-won score was null for every completed match while the same payload held the real score in `score` and `sets[]`. Sets won are now derived (explicit → `winner_sets_won` → `sets[]` → `score` string), `score.detail` carries the game score, and a set's `completed` is inferred when the archive omits `is_completed`. The winner-oriented `winner_games`/`loser_games` pair is deliberately not used as a side score. `bestOf` now reads `best_of`.
-- **`match_details` denied tennis odds existed.** The `odds` section was gated to UFC; the same match returned FanDuel/Matchbook prices from `tennis_odds`. Both surfaces now share one projection (`summarizeTennisOdds`), and `playerStats` (previously always `null` for tennis) is filled from `/tennis/matches/{id}/stats`.
+- **`match_details` denied tennis odds existed.** The `odds` section was gated to UFC; the same match returned bookmaker prices from `tennis_odds`. Both surfaces now share one projection (`summarizeTennisOdds`), and `playerStats` (previously always `null` for tennis) is filled from `/tennis/matches/{id}/stats`.
 - **`player_stats.bySurface` was always four nulls.** The endpoint publishes one object per surface and the projector coerced each to a number. Real per-surface blocks, `servingStats`, and an explicit `unavailable` map for sections the endpoint does not publish.
 - **`limit` was ignored** by `player_rankings_history` (asked 4, got 342) and by `/tennis/matches/completed`. Both are bounded locally now, with `*Returned` versus `*Count` so the day total is never confused with the page.
 - **`tournaments level="WTA 1000"` returned ATP Masters events.** The API's level reverse-map is not tour-aware (`_TIER_WTA` maps both `PM` and `M` to "WTA 1000"), so the tool now sends and enforces the tour the level name states, and drops + counts contradicting rows. Fixed at the source too — the same widening also leaked `WTA 125`, `Challenger`, `Davis Cup` and `Billie Jean King Cup`.

package/dist/client.js

@@ -1,25 +1,9 @@
-/**
- * Authenticated Cito REST client for curated tools.
- * Auth: CITO_API_KEY → x-api-key. Logs never include the key.
- */
 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;
-/** stderr ONLY — stdout is the MCP stdio channel. */
 export function log(message) {
     console.error(`[cito-mcp] ${message}`);
 }
-/**
- * Identify MCP traffic.
- *
- * Without this every MCP request arrives as Node's default agent - "node" -
- * which is the single largest bucket in api_usage_logs (2.78M requests across
- * 182 keys) and indistinguishable from any other script. That made MCP adoption
- * unmeasurable: we could not tell whether an agent-driven user activates faster,
- * consumes more, or converts better than someone hand-rolling curl.
- *
- * Versioned so a bad release can be isolated in the logs.
- */
 export const CITO_MCP_USER_AGENT = `cito-mcp/${PACKAGE_VERSION} (+https://citoapi.com)`;
 export function authHeaders(apiKey, extra) {
     return {
@@ -43,17 +27,11 @@ export function parseRateLimitHeaders(headers) {
         resetAt: resetRaw ?? null,
     };
 }
-/**
- * Build absolute URL under api base.
- * path must start with `/`. Query values skip null/undefined.
- * Arrays become repeated query keys.
- */
 export function buildUrl(baseUrl, path, query) {
     if (!path.startsWith('/')) {
         throw new Error(`path must start with /: ${path}`);
     }
     const base = baseUrl.replace(/\/+$/, '');
-    // LoL-style absolute API paths: if path already includes /api/v1, use origin only
     let originBase = base;
     if (path.startsWith('/api/v1/') && base.endsWith('/api/v1')) {
         originBase = base.slice(0, -'/api/v1'.length) || base;
@@ -78,14 +56,12 @@ export function buildUrl(baseUrl, path, query) {
     const q = qs.toString();
     return `${originBase}${path}${q ? `?${q}` : ''}`;
 }
-/** Pretty-print JSON; truncate oversized bodies with an agent-actionable note. */
 export function present(text, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
     let out = text;
     try {
         out = JSON.stringify(JSON.parse(text), null, 2);
     }
     catch {
-        // Not JSON — return as-is.
     }
     if (out.length > maxBytes) {
         return (`${out.slice(0, maxBytes)}\n\n` +
@@ -126,6 +102,8 @@ export async function fetchJson(ctx, path, opts) {
     catch {
         data = text;
     }
+    if (!opts?.raw && response.ok && isTennisPath(path))
+        data = flattenTennisEnvelope(data);
     return {
         ok: response.ok,
         status: response.status,
@@ -142,7 +120,6 @@ export async function parallelGet(ctx, paths) {
     }));
     return Object.fromEntries(results);
 }
-/** Best-effort row extraction across Cito response shapes. */
 export function extractRows(data) {
     if (data == null)
         return [];
@@ -151,8 +128,6 @@ export function extractRows(data) {
     if (typeof data !== 'object')
         return [];
     const obj = data;
-    // Order matters: UFC /ufc/live nests real bouts under liveBouts while also
-    // shipping supervisor `events` (no fighter names). Prefer bout-like keys first.
     for (const key of [
         'data',
         'liveBouts',
@@ -174,7 +149,6 @@ export function extractRows(data) {
         if (Array.isArray(obj[key]))
             return obj[key];
     }
-    // Nested data.matches / data.items
     if (obj.data && typeof obj.data === 'object' && !Array.isArray(obj.data)) {
         return extractRows(obj.data);
     }
@@ -186,21 +160,51 @@ export function asRecord(value) {
     }
     return null;
 }
-/**
- * Peel Cito `{ success, data: T }` (and one nested `data`) so tools see the entity,
- * not the envelope. Arrays and primitives pass through. Critical for UFC bouts/fighters
- * where fighters[] / name live under data, not the top-level response.
- */
+const TENNIS_LIST_META_KEYS = new Set(['count', 'limit', 'total', 'page', 'totalPages', 'hasNext', 'hasPrev']);
+function isTennisPath(path) {
+    return /^(\/api\/v1)?\/tennis(\/|\?|$)/.test(path);
+}
+function snakeKey(key) {
+    return key.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+export function flattenTennisEnvelope(body) {
+    const env = asRecord(body);
+    if (!env || !('data' in env) || 'items' in env)
+        return body;
+    const meta = asRecord(env.meta);
+    if (!meta)
+        return body;
+    const success = env.success ?? true;
+    if (Array.isArray(env.data)) {
+        const out = { success, items: env.data };
+        for (const [key, value] of Object.entries(meta)) {
+            if (!TENNIS_LIST_META_KEYS.has(key))
+                out[snakeKey(key)] = value;
+        }
+        out.total = typeof meta.total === 'number' ? meta.total : env.data.length;
+        out.page = typeof meta.page === 'number' ? meta.page : 1;
+        out.page_size = typeof meta.limit === 'number' ? meta.limit : env.data.length;
+        if (typeof meta.totalPages === 'number')
+            out.total_pages = meta.totalPages;
+        if (typeof meta.hasNext === 'boolean')
+            out.has_next = meta.hasNext;
+        if (typeof meta.hasPrev === 'boolean')
+            out.has_prev = meta.hasPrev;
+        return out;
+    }
+    const resource = asRecord(env.data);
+    if (resource)
+        return { success, ...resource };
+    return body;
+}
 export function unwrapPayload(value) {
     let cur = value;
     for (let depth = 0; depth < 3; depth += 1) {
         const rec = asRecord(cur);
         if (!rec)
             return cur;
-        // Classic withMeta: { success: true, data: { ...entity } }
         if ('data' in rec && rec.data != null && typeof rec.data === 'object' && !Array.isArray(rec.data)) {
             const inner = rec.data;
-            // Prefer entity-shaped inner objects over list wrappers
             const looksLikeEntity = 'id' in inner ||
                 'slug' in inner ||
                 'name' in inner ||

package/dist/envelope.js

@@ -1,7 +1,4 @@
-/**
- * Canonical JSON envelope for every curated cito-mcp tool response.
- * Agents branch on `ok` / `error.code` / `partial[]` without scraping prose.
- */
+import { scrubInternalFields } from './scrub.js';
 export function isOk(e) {
     return e.ok === true;
 }
@@ -64,8 +61,6 @@ export function mapHttpToCode(status, hints) {
     }
     if (status === 400 && hints?.ambiguous)
         return 'AMBIGUOUS_ENTITY';
-    // 422 is FastAPI's validation status (tennis). It was falling through to
-    // UPSTREAM, which is marked retryable, so an agent retried a bad argument.
     if (status === 400 || status === 422)
         return 'VALIDATION';
     if (status >= 500 || status === 0)
@@ -95,7 +90,7 @@ export function successEnvelope(args) {
         meta.entities = args.entities;
     const out = {
         ok: true,
-        data: args.data,
+        data: scrubInternalFields(args.data),
         meta,
     };
     if (args.pagination)
@@ -135,7 +130,7 @@ export function errorEnvelope(args) {
     if (args.hint)
         error.hint = args.hint;
     if (args.details)
-        error.details = args.details;
+        error.details = scrubInternalFields(args.details);
     return {
         ok: false,
         data: null,
@@ -154,10 +149,6 @@ export function partialFromRejection(section, err) {
         ...(err.httpStatus !== undefined ? { httpStatus: err.httpStatus } : {}),
     };
 }
-/**
- * Enforce MAX_ENVELOPE_CHARS with structural shrink (never mid-slice JSON).
- * Prefers trimming data.items when present.
- */
 export function sealEnvelope(envelope) {
     let text = JSON.stringify(envelope);
     if (text.length <= MAX_ENVELOPE_CHARS)
@@ -203,7 +194,6 @@ export function sealEnvelope(envelope) {
         },
     };
 }
-/** Shared tool output for OpenAI plugin scan. Matches the JSON envelope. */
 export const ENVELOPE_OUTPUT_SCHEMA = {
     type: 'object',
     additionalProperties: true,

package/dist/http.js

@@ -1,10 +1,3 @@
-/**
- * Hosted Streamable HTTP helpers.
- *
- * stdio is unchanged. This is only the public HTTPS surface:
- * pathname matching, per-request API key, CORS, Smithery well-known docs.
- * Never log the key.
- */
 import { allTools } from './tools/index.js';
 import { toolListing } from './tools/types.js';
 import { PACKAGE_VERSION } from './version.js';
@@ -34,10 +27,6 @@ function headerValue(headers, name) {
         return (raw[0] ?? '').trim();
     return typeof raw === 'string' ? raw.trim() : '';
 }
-/**
- * Per-request Cito key. Header first (Smithery x-from), then Bearer, then query.
- * Query is last so nginx access logs are not the intended path.
- */
 export function extractApiKey(req) {
     const fromHeader = headerValue(req.headers, 'x-api-key') || headerValue(req.headers, 'x-cito-api-key');
     if (fromHeader)
@@ -62,7 +51,6 @@ export function corsHeaders() {
 }
 const MCP_ACCEPT = 'application/json, text/event-stream';
 const LEGACY_PROTOCOL = '2025-11-25';
-/** Node reads Accept from rawHeaders; mutating headers.accept alone is not enough. */
 export function setIncomingHeader(req, name, value) {
     req.headers[name.toLowerCase()] = value;
     const raw = req.rawHeaders;
@@ -77,7 +65,6 @@ export function setIncomingHeader(req, name, value) {
     }
     raw.push(name, value);
 }
-/** SDK 406s POSTs that omit MCP Accept. OpenAI's scanner often omits it. */
 export function ensureMcpAccept(headers, req) {
     const raw = headers.accept ?? headers.Accept;
     const value = Array.isArray(raw) ? raw.join(',') : typeof raw === 'string' ? raw : '';
@@ -89,7 +76,6 @@ export function ensureMcpAccept(headers, req) {
     else
         headers.accept = MCP_ACCEPT;
 }
-/** OpenAI Scan Tools sends 2026-07-28; this SDK only speaks 2025-era. */
 export function rewriteMcpProtocolMessage(body) {
     if (!body || typeof body !== 'object')
         return body;
@@ -109,7 +95,6 @@ export function rewriteMcpProtocolMessage(body) {
     }
     return body;
 }
-/** Smithery session config: API key as x-api-key, not OAuth. */
 export function mcpConfigSchema() {
     return {
         $schema: 'https://json-schema.org/draft/2020-12/schema',
@@ -127,7 +112,6 @@ export function mcpConfigSchema() {
         },
     };
 }
-/** Scan fallback if Smithery cannot complete initialize. No OAuth. */
 export function mcpServerCard() {
     return {
         serverInfo: {

package/dist/index.js

@@ -1,13 +1,4 @@
 #!/usr/bin/env node
-/**
- * cito-mcp — curated MCP server for the Cito esports API.
- *
- * 14 outcome tools (not OpenAPI mass-generation). stdio by default;
- * `--http <port>` serves a stateless Streamable HTTP endpoint.
- *
- * Env: CITO_API_KEY (stdio / local). Hosted HTTP reads x-api-key per request.
- * Optional: CITO_API_BASE, CITO_MCP_LISTEN (default 127.0.0.1).
- */
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer as createHttpServer } from 'node:http';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -21,14 +12,6 @@ import { allTools, getTool } from './tools/index.js';
 import { runTool, toolListing } from './tools/types.js';
 import { PACKAGE_VERSION } from './version.js';
 import { MCP_CONFIG_PATH, MCP_PATH, MCP_SERVER_CARD_PATH, corsHeaders, ensureMcpAccept, extractApiKey, rewriteMcpProtocolMessage, setIncomingHeader, mcpConfigSchema, mcpServerCard, requestPathname, } from './http.js';
-/**
- * Subcommands run and exit before any transport exists.
- *
- * `install` writes editor config and prints to stdout, which would corrupt the
- * JSON-RPC channel if it ran alongside the server — hence the early return.
- * Handled here rather than in a second binary so the documented entry point
- * stays `npx cito-mcp`.
- */
 if (process.argv[2] === 'install') {
     const { runInstall } = await import('./install.js');
     process.exit(await runInstall(process.argv.slice(3)));
@@ -38,26 +21,8 @@ const requestAuth = new AsyncLocalStorage();
 function currentApiKey() {
     return requestAuth.getStore()?.apiKey || ENV_API_KEY;
 }
-/**
- * Tools that need no API key. These must keep working with the server
- * unconfigured, so a user can add it and immediately see what it does.
- */
 const OFFLINE_TOOLS = new Set(['list_capabilities']);
-/**
- * Missing key is NOT fatal.
- *
- * This used to process.exit(1) before the transport was even created, so the
- * handshake never completed and the client showed only "server failed to
- * start" — no tool list, no reason, nothing the model could relay. The user's
- * first experience of a mistyped env var was a dead server.
- *
- * Now the server boots, completes initialize, and advertises its full catalog.
- * Tools that need the API return a structured MISSING_API_KEY envelope with
- * recovery steps, which the model can read out; list_capabilities keeps working
- * offline so the server is browsable before it is configured.
- */
 if (!ENV_API_KEY) {
-    // stderr only — stdout is the JSON-RPC channel and must stay clean.
     console.error('[cito-mcp] CITO_API_KEY is not set. Serving tool catalog only; ' +
         'API-backed tools will return MISSING_API_KEY until a key is provided ' +
         '(env CITO_API_KEY, or x-api-key on hosted HTTP). ' +
@@ -65,8 +30,6 @@ if (!ENV_API_KEY) {
 }
 const API_BASE = (process.env.CITO_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
 const ctx = {
-    // Empty string when unconfigured; the dispatcher blocks API-backed tools
-    // before any request is attempted, so this is never sent as a credential.
     apiKey: ENV_API_KEY,
     baseUrl: API_BASE,
 };
@@ -94,8 +57,6 @@ function createCitoServer() {
                 recover: ['Call list_capabilities to see available tools'],
             }));
         }
-        // Fail the CALL, not the process. The model gets an actionable envelope it
-        // can relay verbatim instead of the client reporting a dead server.
         const apiKey = currentApiKey();
         if (!apiKey && !OFFLINE_TOOLS.has(name)) {
             return toMcpResult(errorEnvelope({

package/dist/install.js

@@ -1,25 +1,3 @@
-/**
- * `npx cito-mcp install` — write the server config for whichever MCP clients
- * are actually installed.
- *
- * Why this exists: the documented one-liner
- *
- *   claude mcp add cito -e CITO_API_KEY=… -- npx -y cito-mcp
- *
- * is broken in PowerShell 5.1, which strips the bare `--`. Because `-e` is a
- * variadic option, it then swallows `npx -y cito-mcp` as extra env values and
- * the CLI dies on "unknown option '-y'". Quoting the separator fixes it, but
- * expecting every Windows user to know that is not onboarding — it is a trap.
- * A subcommand has no separator to mangle and works identically everywhere.
- *
- * Rules this follows, because it edits files the user did not open:
- *  - only touch clients that are already installed
- *  - back up before the first write of a run
- *  - merge into existing config; never rewrite a file wholesale
- *  - idempotent: re-running replaces our entry and nothing else
- *  - --dry-run prints the plan and writes nothing
- *  - never print the full API key
- */
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
@@ -80,7 +58,6 @@ function clientsFor() {
             label: 'Grok CLI',
             configPath: join(home, '.grok', 'config.toml'),
             detectPath: join(home, '.grok'),
-            // Same [mcp_servers.x] / [mcp_servers.x.env] layout as Codex.
             format: 'toml-mcp_servers',
         },
     ];
@@ -90,7 +67,6 @@ export function maskKey(key) {
         return '****';
     return `${key.slice(0, 9)}…${key.slice(-4)}`;
 }
-/** The stdio entry every JSON-based client understands. */
 function serverEntry(key, base) {
     return {
         type: 'stdio',
@@ -113,11 +89,6 @@ function readJson(path) {
         return null;
     }
 }
-/**
- * Escape a TOML basic string. Only the characters TOML actually requires —
- * an API key with a quote or backslash would otherwise produce a file the
- * client cannot parse.
- */
 function tomlString(v) {
     return `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
@@ -135,11 +106,6 @@ function tomlBlock(key, base) {
         ``,
     ].join('\n');
 }
-/**
- * Replace an existing [mcp_servers.cito] block (and its .env subtable) or
- * append a new one. Deliberately conservative: it only recognises the exact
- * headers it writes, so a hand-edited file is appended to rather than mangled.
- */
 export function upsertTomlBlock(existing, key, base) {
     const block = tomlBlock(key, base);
     const header = new RegExp(`^\\[mcp_servers\\.${SERVER_NAME}(\\.[A-Za-z_]+)?\\]\\s*$`);
@@ -160,16 +126,8 @@ export function upsertTomlBlock(existing, key, base) {
     const body = kept.join('\n').replace(/\n{3,}$/, '\n\n').replace(/\s*$/, '');
     return (body ? `${body}\n\n` : '') + block;
 }
-/**
- * Claude Code owns the schema of ~/.claude.json and stores far more than MCP
- * config in it, so let its own CLI do the write when it is on PATH. Direct
- * editing is the fallback, not the default.
- */
 function tryClaudeCli(key, base, dryRun) {
     const json = JSON.stringify(serverEntry(key, base));
-    // On Windows `claude` is a .cmd shim, which execFileSync cannot spawn
-    // directly — it needs a shell. Quoting matters there because the JSON
-    // payload contains spaces and double quotes.
     const isWin = platform() === 'win32';
     const run = (args) => {
         if (!isWin) {
@@ -299,8 +257,6 @@ export async function runInstall(argv) {
         console.error(`Valid: ${all.map((c) => c.id).join(', ')}`);
         return 1;
     }
-    // An explicit --client is a instruction, not a guess: honour it even if we
-    // cannot detect the client (fresh install, portable install, unusual path).
     const selected = args.only.length
         ? all.filter((c) => args.only.includes(c.id))
         : all.filter((c) => existsSync(c.detectPath));

package/dist/instructions.js

@@ -1,81 +1,77 @@
-/**
- * MCP server instructions — agent operating manual (embedded at connect).
- * Keep under ~1.5k tokens. Tool names match the curated catalog (no cito_ prefix).
- */
-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.
-
-## 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.
+
+## 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.
 `;