cito-mcp 0.2.4 → 0.2.5

package/README.md

@@ -170,6 +170,7 @@ Hardened agent-facing UFC shapes (offline-tested):
 
 - **`normalizeMatch`** reads `fighters[]` (`corner` + `fighterName` / `profile.name`), live `red`/`blue`, and `boutId` / `dataId` / bare `id`. Never keeps label `? vs ?` when fighter names exist (including blue-first arrays).
 - **`live_matches`** uses `extractLiveRows`: prefer `liveBouts` (empty array = honest empty board); never promote supervisor `events[]` shells into match rows.
+- **UFC empty board honesty:** when `count === 0`, section includes `note`, `emptyReason`, slim `health` (`workerAlive`, lag), optional non-live `supervisor` strip and `nextCard` (armed only). Also `data.note` + `meta.warnings` for single-game UFC. Do not treat empty as HTTP failure; do not invent `? vs ?` from event shells.
 - **`upcoming_schedule`** expands event → bout rows with fighter labels; applies client-side **`hours` / `from` / `to`** (API has no `hours`); event shells without bouts use the **event name**, not `? vs ?`.
 - **`event_card`** bouts share the same `normalizeMatch` path.
 - **`standings`** maps division champions to rank **`C`** (`rankText: "C"`, interim **`IC`**); contender `#1` stays numeric `1` — no dual numeric `#1`.

package/dist/client.js

@@ -2,16 +2,30 @@
  * 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 {
         'x-api-key': apiKey,
         accept: 'application/json',
+        'user-agent': CITO_MCP_USER_AGENT,
         ...extra,
     };
 }

package/dist/index.js

@@ -18,17 +18,37 @@ import { errorEnvelope, toMcpResult } from './envelope.js';
 import { SERVER_INSTRUCTIONS } from './instructions.js';
 import { allTools, getTool } from './tools/index.js';
 import { runTool } from './tools/types.js';
-const PACKAGE_VERSION = '0.2.4';
+import { PACKAGE_VERSION } from './version.js';
 const API_KEY = process.env.CITO_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 (!API_KEY) {
-    console.error('[cito-mcp] CITO_API_KEY is required.\n' +
-        'Set it to your Cito API key, e.g.:\n' +
-        '  claude mcp add cito -e CITO_API_KEY=cito_... -- npx cito-mcp');
-    process.exit(1);
+    // 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. ' +
+        'Get one at https://citoapi.com/dashboard and set CITO_API_KEY.');
 }
 const API_BASE = (process.env.CITO_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
 const ctx = {
-    apiKey: API_KEY,
+    // Empty string when unconfigured; the dispatcher blocks API-backed tools
+    // before any request is attempted, so this is never sent as a credential.
+    apiKey: API_KEY ?? '',
     baseUrl: API_BASE,
 };
 async function main() {
@@ -59,6 +79,25 @@ async function main() {
                 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.
+        if (!API_KEY && !OFFLINE_TOOLS.has(name)) {
+            return toMcpResult(errorEnvelope({
+                code: 'UNAUTHORIZED',
+                message: 'CITO_API_KEY is not set, so this tool cannot reach the Cito API. ' +
+                    'The server is running and list_capabilities still works.',
+                game: null,
+                source: 'cito-mcp',
+                httpStatus: 401,
+                retryable: false,
+                recover: [
+                    'Create a key at https://citoapi.com/dashboard',
+                    'claude mcp add cito -e CITO_API_KEY=cito_... -- npx cito-mcp',
+                    'Or set CITO_API_KEY in the mcpServers env block of your client config',
+                    'Call list_capabilities to browse available tools without a key',
+                ],
+            }));
+        }
         return runTool(tool, args, ctx);
     });
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({

package/dist/instructions.js

@@ -57,6 +57,7 @@ resolve_entity ambiguity is soft: ok:true with data.needsDisambiguation and data
 ## 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 {includeBouts:true} → match_preview for a featured bout.

package/dist/tools/live.js

@@ -16,6 +16,8 @@ const LIVE_PATHS = {
  * Extract live match/bout rows. UFC /ufc/live returns
  * { liveBouts, events, ... } — events are supervisor shells without fighters.
  * Prefer liveBouts (and nested tracking on events) over plain events[].
+ * Never promote bare events[] to match rows (avoids fake "? vs ?").
+ * Nested tracking with status armed is excluded from live items (use nextCard).
  * Exported for offline UFC projection tests.
  */
 export function extractLiveRows(data, game) {
@@ -24,6 +26,20 @@ export function extractLiveRows(data, game) {
     if (!payload)
         return extractRows(data);
     if (game === 'ufc') {
+        const pushLiveTracking = (tracking, er, out) => {
+            for (const t of tracking) {
+                const tr = asRecord(t) ?? {};
+                const status = String(pickString(tr.status) ?? '').toLowerCase();
+                // Board items = live|watching only; armed is surfaced as nextCard, not items.
+                if (status === 'armed' || status === 'completed' || status === 'stale')
+                    continue;
+                out.push({
+                    ...tr,
+                    eventSlug: pickString(tr.eventSlug, er?.eventSlug, er?.slug),
+                    eventName: pickString(er?.name, er?.eventName, er?.eventSlug),
+                });
+            }
+        };
         // Prefer liveBouts when the key is present (including empty [] — honest empty board).
         if (Array.isArray(payload.liveBouts)) {
             const liveBouts = payload.liveBouts;
@@ -37,16 +53,9 @@ export function extractLiveRows(data, game) {
             for (const ev of eventsWithEmptyLive) {
                 const er = asRecord(ev);
                 const tracking = Array.isArray(er?.tracking) ? er.tracking : [];
-                for (const t of tracking) {
-                    const tr = asRecord(t) ?? {};
-                    nested.push({
-                        ...tr,
-                        eventSlug: pickString(tr.eventSlug, er?.eventSlug, er?.slug),
-                        eventName: pickString(er?.name, er?.eventName, er?.eventSlug),
-                    });
-                }
+                pushLiveTracking(tracking, er, nested);
             }
-            return nested; // [] when only supervisor shells
+            return nested; // [] when only supervisor shells / armed-only
         }
         // liveBouts key missing — try nested tracking under events
         const events = Array.isArray(payload.events) ? payload.events : [];
@@ -54,14 +63,7 @@ export function extractLiveRows(data, game) {
         for (const ev of events) {
             const er = asRecord(ev);
             const tracking = Array.isArray(er?.tracking) ? er.tracking : [];
-            for (const t of tracking) {
-                const tr = asRecord(t) ?? {};
-                fromTracking.push({
-                    ...tr,
-                    eventSlug: pickString(tr.eventSlug, er?.eventSlug, er?.slug),
-                    eventName: pickString(er?.name, er?.eventName, er?.eventSlug),
-                });
-            }
+            pushLiveTracking(tracking, er, fromTracking);
         }
         if (fromTracking.length)
             return fromTracking;
@@ -70,6 +72,103 @@ export function extractLiveRows(data, game) {
     }
     return extractRows(data);
 }
+/** Machine emptyReason codes from API health / meta (or inferred). */
+export function inferUfcEmptyReason(events, health, liveCount) {
+    if (liveCount > 0)
+        return undefined;
+    const fromHealth = pickString(health?.emptyReason);
+    if (fromHealth)
+        return fromHealth;
+    const pulses = events.map((ev) => asRecord(ev) ?? {});
+    if (!pulses.length) {
+        const alive = health?.workerAlive ?? health?.workerStarted;
+        if (alive === false)
+            return 'worker_down_inferred';
+        return 'idle_no_supervisor';
+    }
+    const statuses = pulses.map((p) => String(pickString(p.status, p.eventStatus) ?? '').toLowerCase());
+    const lags = pulses
+        .map((p) => (typeof p.lagSeconds === 'number' ? p.lagSeconds : null))
+        .filter((n) => n != null);
+    const freshest = lags.length ? Math.min(...lags) : null;
+    const workerAlive = health?.workerAlive ?? health?.workerStarted;
+    const hot = statuses.some((s) => ['live', 'warming', 'between_bouts', 'degraded'].includes(s));
+    if (workerAlive === false && (hot || (freshest != null && freshest > 120))) {
+        return 'worker_stale';
+    }
+    if (statuses.some((s) => s === 'degraded'))
+        return 'event_degraded';
+    if (statuses.some((s) => s === 'warming'))
+        return 'supervisor_warming';
+    if (statuses.some((s) => s === 'between_bouts'))
+        return 'between_bouts';
+    if (statuses.every((s) => s === 'completed'))
+        return 'not_fight_night';
+    if (hot)
+        return 'between_bouts';
+    return 'not_fight_night';
+}
+/** Human note for empty UFC live section — never invent matchups. */
+export function humanUfcEmptyNote(emptyReason, health) {
+    const alive = health?.workerAlive ?? health?.workerStarted;
+    const lag = typeof health?.freshestHeartbeatLagSeconds === 'number'
+        ? health.freshestHeartbeatLagSeconds
+        : typeof health?.lagSeconds === 'number'
+            ? health.lagSeconds
+            : null;
+    const lagPart = typeof lag === 'number' ? ` lag=${lag}s` : '';
+    const workerPart = alive === true ? 'workerAlive=true' : alive === false ? 'workerAlive=false' : 'workerAlive=unknown';
+    const reason = emptyReason || 'unknown';
+    const human = {
+        not_fight_night: 'No UFC live card right now',
+        idle_no_supervisor: 'Supervisor has no live event rows',
+        supervisor_warming: 'Card open / pre-gate; no bout live yet',
+        between_bouts: 'Between bouts; next may be armed',
+        armed_only: 'Next bout armed; not started',
+        worker_stale: 'Worker heartbeat stale — check pm2 ufc-live on VPS 169',
+        worker_down_inferred: 'Worker appears down — check pm2 ufc-live on VPS 169',
+        event_degraded: 'Sources empty clock / event degraded; not inventing stats',
+    };
+    const msg = human[reason] || `No live|watching bouts (${reason})`;
+    return `UFC: ${msg} (${workerPart}${lagPart}; emptyReason=${reason})`;
+}
+function slimUfcSupervisorEvents(events, limit = 3) {
+    return events.slice(0, limit).map((ev) => {
+        const er = asRecord(ev) ?? {};
+        return {
+            kind: 'supervisor',
+            eventSlug: pickString(er.eventSlug, er.slug) ?? null,
+            status: pickString(er.status, er.eventStatus) ?? null,
+            currentLiveFmid: er.currentLiveFmid ?? null,
+            nextCandidateFmid: er.nextCandidateFmid ?? null,
+            lagSeconds: typeof er.lagSeconds === 'number' ? er.lagSeconds : null,
+            recommendedPollSeconds: typeof er.recommendedPollSeconds === 'number' ? er.recommendedPollSeconds : null,
+            degradedReason: pickString(er.degradedReason) ?? null,
+            note: 'Non-live supervisor shell — not a matchup',
+        };
+    });
+}
+function slimUfcNextCard(payload) {
+    if (!payload)
+        return undefined;
+    const nextBouts = Array.isArray(payload.nextBouts) ? payload.nextBouts : [];
+    const first = asRecord(payload.nextArmedBout) ??
+        (nextBouts[0] ? asRecord(nextBouts[0]) : null);
+    if (!first)
+        return undefined;
+    return {
+        kind: 'next_armed',
+        status: pickString(first.status) ?? 'armed',
+        boutId: pickString(first.boutId, first.id) ?? null,
+        eventSlug: pickString(first.eventSlug) ?? null,
+        fightMetricId: first.fightMetricId ?? null,
+        // Names only if API already provided them — never invent.
+        red: first.red ?? null,
+        blue: first.blue ?? null,
+        degradedReason: pickString(first.degradedReason) ?? null,
+        note: 'Armed / up-next only — not currently live',
+    };
+}
 export const liveMatches = {
     name: 'live_matches',
     description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
@@ -83,6 +182,7 @@ Prefer over: sequential per-game call_api live probes.
 Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
 
 CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
+UFC empty board: section.note + emptyReason + health (workerAlive/lag) + optional supervisor/nextCard (non-live); never fake match items from events[].
 
 Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
 Example: { "game": "all", "limitPerGame": 10 }`,
@@ -127,6 +227,7 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             return { game, path, res };
         }));
         const sections = [];
+        const warnings = [];
         for (const { game, res } of settled) {
             upstreamCalls += 1;
             rateLimit = { ...rateLimit, ...res.headers };
@@ -148,21 +249,26 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             }
             // Prefer real match/bout rows over supervisor event shells (UFC /ufc/live).
             let rows = extractLiveRows(res.data, game);
-            const obj = asRecord(res.data);
-            if (rows.length === 0 && Array.isArray(obj?.matches))
-                rows = obj.matches;
+            const root = asRecord(res.data);
+            const payload = asRecord(root?.data) ?? root;
+            const meta = asRecord(root?.meta);
+            if (rows.length === 0 && Array.isArray(root?.matches))
+                rows = root.matches;
             const normalized = rows
                 .slice(0, limitPerGame)
                 .map((row) => normalizeMatch(game, row, 'live'))
-                // Drop hollow UFC event-supervisor rows mistaken for bouts (no bout id + no sides).
+                // Drop hollow UFC rows agents cannot use (placeholder labels / no sides).
+                // normalizeMatch already enriches label from eventSlug/weight/bout id when
+                // fighters are pending — keep those; drop pure "? vs ?" only.
                 .filter((m) => {
                 if (game !== 'ufc')
                     return true;
-                if (m.matchId && m.matchId !== 'unknown' && (m.team1?.name || m.team2?.name))
-                    return true;
-                if (m.team1?.name && m.team2?.name)
+                const placeholder = /^\?\s*vs\s*\?$/i.test(m.label.trim());
+                if (placeholder)
+                    return false;
+                if (m.team1?.name || m.team2?.name)
                     return true;
-                // Keep if at least a real bout id even when fighters pending
+                // Identity-only live row (enriched Bout {id} / event name) is ok
                 return Boolean(m.matchId && m.matchId !== 'unknown' && !String(m.matchId).startsWith('event'));
             });
             const items = labelsOnly
@@ -174,6 +280,44 @@ Example: { "game": "all", "limitPerGame": 10 }`,
                     startTime: m.startTime,
                 }))
                 : normalized;
+            if (game === 'ufc') {
+                const health = asRecord(meta?.health) ?? asRecord(payload?.health);
+                const events = Array.isArray(payload?.events) ? payload.events : [];
+                const emptyReason = normalized.length === 0
+                    ? pickString(meta?.emptyReason, health?.emptyReason) ??
+                        inferUfcEmptyReason(events, health, normalized.length)
+                    : undefined;
+                let note;
+                if (normalized.length === 0) {
+                    note = humanUfcEmptyNote(emptyReason, health);
+                    warnings.push(note);
+                }
+                const healthStrip = normalized.length === 0 || health?.workerAlive === false || health?.workerStarted === false
+                    ? {
+                        workerStarted: health?.workerStarted ?? health?.workerAlive ?? null,
+                        workerAlive: health?.workerAlive ?? health?.workerStarted ?? null,
+                        freshestHeartbeatLagSeconds: health?.freshestHeartbeatLagSeconds ?? meta?.lagSeconds ?? null,
+                        emptyReason: emptyReason ?? health?.emptyReason ?? null,
+                        degradedReason: health?.degradedReason ?? null,
+                        ok: health?.ok ?? null,
+                        redis_ready: health?.redis_ready ?? meta?.redis_ready ?? meta?.redis_configured ?? null,
+                    }
+                    : undefined;
+                const supervisor = normalized.length === 0 && events.length ? slimUfcSupervisorEvents(events) : undefined;
+                const nextCard = normalized.length === 0 ? slimUfcNextCard(payload) : undefined;
+                sections.push({
+                    game,
+                    count: normalized.length,
+                    ok: true,
+                    note,
+                    emptyReason,
+                    health: healthStrip,
+                    supervisor,
+                    nextCard,
+                    items,
+                });
+                continue;
+            }
             sections.push({
                 game,
                 count: normalized.length,
@@ -182,6 +326,11 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             });
         }
         const totalLive = sections.reduce((sum, s) => sum + (s.ok ? s.count : 0), 0);
+        // Top-level note when single-game UFC empty so agents don't need deep section walk.
+        const ufcSection = sections.find((s) => s.game === 'ufc');
+        const dataNote = games.length === 1 && games[0] === 'ufc' && ufcSection && ufcSection.count === 0
+            ? ufcSection.note
+            : undefined;
         return successEnvelope({
             source: 'live_matches',
             game: games.length === 1 ? games[0] : null,
@@ -190,10 +339,12 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             upstreamCalls,
             rateLimit,
             partial: partial.length ? partial : undefined,
+            warnings: warnings.length ? warnings : undefined,
             data: {
                 sections,
                 totalLive,
                 asOf: new Date().toISOString(),
+                ...(dataNote ? { note: dataNote } : {}),
             },
         });
     },

package/dist/tools/match.js

@@ -35,8 +35,55 @@ function matchCore(game, matchId, raw) {
         event: m.event,
         league: m.league,
         method: pickString(r.method, r.resultMethod) ?? null,
-        winner: pickString(r.winnerFighterSlug, r.winnerSlug, r.winner) ?? null,
+        winner: (() => {
+            // UFC rows carry an explicit winner slug/fighter ref.
+            const explicit = pickString(r.winnerFighterSlug, r.winnerSlug, r.winner);
+            if (explicit)
+                return explicit;
+            if (game === 'ufc')
+                return null;
+            // CS2 rows expose winnerTeamId instead; map it to a side, else fall back to scores.
+            const sideLabel = (side) => side ? pickString(side.slug, side.id, side.name) ?? null : null;
+            const winnerTeamId = pickString(r.winnerTeamId, r.winner_team_id);
+            if (winnerTeamId) {
+                const t1Ids = [m.team1?.id, m.team1?.slug, pickString(r.team1Id, r.team1_id)].filter(Boolean).map(String);
+                const t2Ids = [m.team2?.id, m.team2?.slug, pickString(r.team2Id, r.team2_id)].filter(Boolean).map(String);
+                if (t1Ids.includes(winnerTeamId))
+                    return sideLabel(m.team1);
+                if (t2Ids.includes(winnerTeamId))
+                    return sideLabel(m.team2);
+            }
+            if (s1 != null && s2 != null && s1 !== s2)
+                return sideLabel(s1 > s2 ? m.team1 : m.team2);
+            return null;
+        })(),
         weightClass: pickString(r.weightClass, r.division) ?? null,
+        referee: (() => {
+            const nested = asRecord(r.referee);
+            if (nested) {
+                const joined = [nested.firstName, nested.lastName].filter(Boolean).join(' ').trim();
+                const name = pickString(nested.name, joined || undefined) ?? null;
+                const id = pickString(nested.id, nested.refereeId) ?? null;
+                if (name || id) {
+                    return {
+                        id,
+                        name,
+                        firstName: pickString(nested.firstName) ?? null,
+                        lastName: pickString(nested.lastName) ?? null,
+                    };
+                }
+            }
+            const name = pickString(r.refereeName) ?? null;
+            const id = pickString(r.refereeId) ?? null;
+            if (!name && !id)
+                return null;
+            return {
+                id,
+                name,
+                firstName: pickString(r.refereeFirstName) ?? null,
+                lastName: pickString(r.refereeLastName) ?? null,
+            };
+        })(),
         rawStatus: pickString(r.status, r.state) ?? null,
     };
 }
@@ -56,18 +103,18 @@ function primaryPath(game, matchId) {
 }
 export const matchSummary = {
     name: 'match_summary',
-    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
-
-When to use:
-- Match recap / default match UI
-- After user selects a live or completed matchId
-
-Prefer over match_details for chat answers and default UIs.
-Prefer match_details for timelines, full map trees, live state, advanced packages.
-
-Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
-
-Parallel-safe: yes. Upstream cost: 2–5.
+    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
+
+When to use:
+- Match recap / default match UI
+- After user selects a live or completed matchId
+
+Prefer over match_details for chat answers and default UIs.
+Prefer match_details for timelines, full map trees, live state, advanced packages.
+
+Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
+
+Parallel-safe: yes. Upstream cost: 2–5.
 Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includePlayerStats": true }`,
     inputSchema: {
         type: 'object',
@@ -251,22 +298,22 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
 };
 export const matchDetails = {
     name: 'match_details',
-    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
-
-When to use:
-- Analyst deep dive
-- Live in-game window (LoL/CS2/UFC)
-- Full demo list
-
-Prefer over match_summary only when summary is insufficient.
-Prefer match_summary for short answers and default cards.
-
-Do not use when: first-pass live board (use live_matches + match_summary).
-
-Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
-If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
-
-Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
+    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
+
+When to use:
+- Analyst deep dive
+- Live in-game window (LoL/CS2/UFC)
+- Full demo list
+
+Prefer over match_summary only when summary is insufficient.
+Prefer match_summary for short answers and default cards.
+
+Do not use when: first-pass live board (use live_matches + match_summary).
+
+Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
+If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
+
+Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
 Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "includeLiveState": false }`,
     inputSchema: {
         type: 'object',

package/dist/tools/meta.js

@@ -4,7 +4,7 @@
 import { extractRows, fetchJson, gameNotIncludedHint, present } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
 import { boolSchema, gameSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
-const CATALOG_VERSION = '0.2.4';
+import { PACKAGE_VERSION as CATALOG_VERSION } from '../version.js';
 const TOOL_CATALOG = [
     {
         name: 'list_capabilities',

package/dist/tools/normalize.js

@@ -46,6 +46,18 @@ export function normalizeMatch(game, row, forcedStatus) {
         sideFrom(pickString(r.team1Name, r.team_a_name, r.redName, r.fighter1Name, r.homeName), pickString(r.team1Id, r.team1_id, r.redId, r.fighter1Id), pickString(r.team1Slug, r.redSlug, r.fighter1Slug), scoreNum(r.team1Score ?? r.score1 ?? r.team1Maps ?? r.redScore));
     let team2 = nestedSide(r.team2) ??
         sideFrom(pickString(r.team2Name, r.team_b_name, r.blueName, r.fighter2Name, r.awayName), pickString(r.team2Id, r.team2_id, r.blueId, r.fighter2Id), pickString(r.team2Slug, r.blueSlug, r.fighter2Slug), scoreNum(r.team2Score ?? r.score2 ?? r.team2Maps ?? r.blueScore));
+    // CS2 rows nest team1/team2 objects that lack a score; a nested side must not
+    // shadow the flat score fields (team1Score/score1/team1Maps) with score:null.
+    if (team1 && team1.score == null) {
+        const s = scoreNum(r.team1Score ?? r.score1 ?? r.team1Maps ?? r.redScore);
+        if (s != null)
+            team1 = { ...team1, score: s };
+    }
+    if (team2 && team2.score == null) {
+        const s = scoreNum(r.team2Score ?? r.score2 ?? r.team2Maps ?? r.blueScore);
+        if (s != null)
+            team2 = { ...team2, score: s };
+    }
     // UFC / live corners: red/blue objects, corner arrays, or fighters[] with corner field.
     // Public API serializeBout uses fighters:[{ corner, fighterName, fighterSlug, profile:{name,slug} }].
     // Live tracking uses red/blue + fighters[] (not team1/team2).
@@ -151,9 +163,12 @@ export function normalizeMatch(game, row, forcedStatus) {
     const leagueSlug = pickString(asRecord(r.league)?.slug, r.leagueSlug);
     // Prefer explicit title/label when present, but never keep the placeholder
     // "? vs ?" once fighter/team names were resolved (UFC fighters[] / red-blue).
+    // When both sides lack names, prefer event / weight / bout id over opaque "? vs ?"
+    // so agent boards (live_matches, upcoming_schedule, event_card) stay legible.
     const vsLabel = `${team1?.name ?? '?'} vs ${team2?.name ?? '?'}`;
     const explicit = pickString(r.label, r.title, r.name);
     const explicitIsPlaceholder = explicit != null && /^\?\s*vs\s*\?$/i.test(explicit.trim());
+    const weightOrClass = pickString(r.weightClass, r.division, r.weight_class, r.boutClass);
     let label;
     if (explicit && !explicitIsPlaceholder) {
         label = explicit;
@@ -162,7 +177,11 @@ export function normalizeMatch(game, row, forcedStatus) {
         label = vsLabel;
     }
     else {
-        label = explicit ?? vsLabel;
+        // Identity fallbacks — never invent fighter names, but avoid bare "? vs ?"
+        label =
+            pickString(eventName, eventSlug, weightOrClass) ??
+                (matchId && matchId !== 'unknown' ? `Bout ${matchId}` : null) ??
+                vsLabel;
     }
     return {
         game,

package/dist/tools/resolve.js

@@ -144,7 +144,9 @@ async function searchGame(ctx, game, q, type, limit) {
                     }),
                 };
             }
-            const data = asRecord(res.data) ?? {};
+            // Unwrap the { success, data, meta } envelope before reading buckets.
+            const envelope = asRecord(res.data) ?? {};
+            const data = asRecord(envelope.data) ?? envelope;
             const buckets = [
                 ['team', data.teams],
                 ['player', data.players],
@@ -159,7 +161,15 @@ async function searchGame(ctx, game, q, type, limit) {
                 pushCandidates(candidates, game, t, rows, q, limit);
             }
             if (candidates.length === 0) {
-                pushCandidates(candidates, game, type === 'any' ? 'unknown' : type, extractRows(res.data), q, limit);
+                const fallbackType = type === 'any' ? 'unknown' : type;
+                let rows = extractRows(data);
+                // extractRows prefers the `matches` bucket; never mislabel those rows as a non-match type.
+                if (fallbackType !== 'match' && fallbackType !== 'unknown') {
+                    const matchRows = extractRows(data.matches);
+                    if (matchRows.length && rows[0] === matchRows[0])
+                        rows = [];
+                }
+                pushCandidates(candidates, game, fallbackType, rows, q, limit);
             }
         }
         else if (game === 'dota2') {
@@ -176,7 +186,9 @@ async function searchGame(ctx, game, q, type, limit) {
                     }),
                 };
             }
-            const data = asRecord(res.data) ?? {};
+            // Unwrap the { success, data, meta } envelope before reading buckets.
+            const envelope = asRecord(res.data) ?? {};
+            const data = asRecord(envelope.data) ?? envelope;
             for (const [t, key] of [
                 ['team', 'teams'],
                 ['player', 'players'],
@@ -188,7 +200,15 @@ async function searchGame(ctx, game, q, type, limit) {
                 pushCandidates(candidates, game, t, extractRows(data[key] ?? data), q, limit);
             }
             if (candidates.length === 0) {
-                pushCandidates(candidates, game, type === 'any' ? 'unknown' : type, extractRows(res.data), q, limit);
+                const fallbackType = type === 'any' ? 'unknown' : type;
+                let rows = extractRows(data);
+                // extractRows prefers the `matches` bucket; never mislabel those rows as a non-match type.
+                if (fallbackType !== 'match' && fallbackType !== 'unknown') {
+                    const matchRows = extractRows(data.matches);
+                    if (matchRows.length && rows[0] === matchRows[0])
+                        rows = [];
+                }
+                pushCandidates(candidates, game, fallbackType, rows, q, limit);
             }
         }
         else if (game === 'cod') {
@@ -313,20 +333,20 @@ async function searchGame(ctx, game, q, type, limit) {
 }
 export const resolveEntity = {
     name: 'resolve_entity',
-    description: `Natural-language / fuzzy query → best typed entity ID(s) + game (player, team, event, tournament, match, fighter).
-
-When to use:
-- User named an entity without an ID ("T1", "s1mple", "IEM Cologne", "Islam Makhachev")
-- Need a canonical id/slug before profile or match tools
-
-Prefer over search_entities when you want one best match (or small ranked set) to chain.
-Prefer search_entities when browsing many results with pagination.
-
-Do not use when: you already have a stable id/slug from a prior tool.
-
-Empty/ambiguous results still return ok:true with best=null or needsDisambiguation=true — pick from candidates or refine q/game/type. Does not emit AMBIGUOUS_ENTITY as a hard error.
-
-Parallel-safe: yes. Upstream cost: 1–5.
+    description: `Natural-language / fuzzy query → best typed entity ID(s) + game (player, team, event, tournament, match, fighter).
+
+When to use:
+- User named an entity without an ID ("T1", "s1mple", "IEM Cologne", "Islam Makhachev")
+- Need a canonical id/slug before profile or match tools
+
+Prefer over search_entities when you want one best match (or small ranked set) to chain.
+Prefer search_entities when browsing many results with pagination.
+
+Do not use when: you already have a stable id/slug from a prior tool.
+
+Empty/ambiguous results still return ok:true with best=null or needsDisambiguation=true — pick from candidates or refine q/game/type. Does not emit AMBIGUOUS_ENTITY as a hard error.
+
+Parallel-safe: yes. Upstream cost: 1–5.
 Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -420,22 +440,22 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
 };
 export const searchEntities = {
     name: 'search_entities',
-    description: `Browse/search teams, players, tournaments, events, fighters with type filter and pagination.
-
-When to use:
-- Typeahead / pickers
-- "List teams matching…"
-- Exploring entities without committing to one ID
-- UFC fighter lookup by name/nickname (uses /ufc/search + client re-rank)
-
-Prefer over resolve_entity when the user wants a list.
-Prefer resolve_entity when chaining one name into a profile tool.
-
-Do not use when: fetching a known entity profile — use team_profile or player_profile.
-
-UFC: with q set, results are ranked (exact name > multi-token match > nickname). "Jon Jones" should return jon-jones first — never the generic P4P list.
-
-Parallel-safe: yes. Upstream cost: 1–3.
+    description: `Browse/search teams, players, tournaments, events, fighters with type filter and pagination.
+
+When to use:
+- Typeahead / pickers
+- "List teams matching…"
+- Exploring entities without committing to one ID
+- UFC fighter lookup by name/nickname (uses /ufc/search + client re-rank)
+
+Prefer over resolve_entity when the user wants a list.
+Prefer resolve_entity when chaining one name into a profile tool.
+
+Do not use when: fetching a known entity profile — use team_profile or player_profile.
+
+UFC: with q set, results are ranked (exact name > multi-token match > nickname). "Jon Jones" should return jon-jones first — never the generic P4P list.
+
+Parallel-safe: yes. Upstream cost: 1–3.
 Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -520,7 +540,9 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                     const res = await fetchJson(ctx, '/cs2/search', { query: { q, limit } });
                     upstreamCalls += 1;
                     if (res.ok) {
-                        const data = asRecord(res.data) ?? {};
+                        // Unwrap the { success, data, meta } envelope before reading buckets.
+                        const envelope = asRecord(res.data) ?? {};
+                        const data = asRecord(envelope.data) ?? envelope;
                         if (type === 'any' || type === 'team') {
                             items.push(...extractRows(data.teams).map((r) => entityRef(r, 'team', game)));
                         }
@@ -535,8 +557,15 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                 else {
                     if (type === 'team' || type === 'any')
                         await listPath('/cs2/teams', 'team');
-                    if (type === 'player' || type === 'any')
-                        await listPath('/cs2/players', 'player');
+                    if (type === 'player' || type === 'any') {
+                        if (q) {
+                            // /cs2/players list filters ignore q/search — use the dedicated search endpoint.
+                            await listPath('/cs2/players/search', 'player');
+                        }
+                        else {
+                            await listPath('/cs2/players', 'player');
+                        }
+                    }
                     if (type === 'event' || type === 'tournament' || type === 'any')
                         await listPath('/cs2/events', 'event');
                 }

package/dist/tools/standings.js

@@ -321,6 +321,32 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             rows = nested.map((row, i) => normalizeStandingRow(row, i)).slice(0, limit);
         }
         const obj = asRecord(res.data);
+        const upstreamMeta = asRecord(obj?.meta) ?? {};
+        const dataQuality = asRecord(upstreamMeta.dataQuality) ?? {};
+        const warnings = [];
+        const pushWarning = (value) => {
+            if (typeof value !== 'string')
+                return;
+            const trimmed = value.trim();
+            if (trimmed && !warnings.includes(trimmed))
+                warnings.push(trimmed);
+        };
+        pushWarning(upstreamMeta.warning);
+        pushWarning(dataQuality.warning);
+        if (Array.isArray(upstreamMeta.warnings)) {
+            for (const w of upstreamMeta.warnings)
+                pushWarning(w);
+        }
+        const dataFreshness = pickString(upstreamMeta.dataFreshness, upstreamMeta.freshnessStatus, dataQuality.dataFreshness);
+        const status = pickString(upstreamMeta.status, dataQuality.status);
+        if (status === 'fallback') {
+            pushWarning('Standings served from last-known-good rankings (fallback).');
+        }
+        if (dataFreshness === 'cached' || upstreamMeta.stale === true) {
+            pushWarning(typeof upstreamMeta.dataAgeHours === 'number'
+                ? `Rankings dataFreshness=cached (ageHours=${upstreamMeta.dataAgeHours}).`
+                : 'Rankings dataFreshness=cached or stale.');
+        }
         return successEnvelope({
             source: 'standings',
             game,
@@ -328,13 +354,20 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             tookMs: Date.now() - started,
             upstreamCalls: 1,
             rateLimit: res.headers,
+            warnings: warnings.length ? warnings : undefined,
             data: {
                 scope: effectiveScope,
                 title,
                 season: season ?? null,
                 stage: stage ?? null,
                 rows,
-                updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated) ?? null,
+                updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
+                    null,
+                ...(dataFreshness ? { dataFreshness } : {}),
+                ...(status ? { status } : {}),
+                ...(upstreamMeta.warning || dataQuality.warning
+                    ? { warning: pickString(upstreamMeta.warning, dataQuality.warning) }
+                    : {}),
             },
         });
     },

package/dist/tools/team.js

@@ -21,18 +21,18 @@ function teamIdentity(game, raw, idHint, slugHint) {
 }
 export const teamProfile = {
     name: 'team_profile',
-    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
-
-When to use:
-- Team page / "who is on this roster?"
-- Builder team screen sample
-
-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.
+    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
+
+When to use:
+- Team page / "who is on this roster?"
+- Builder team screen sample
+
+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.
 Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -123,7 +123,12 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
             teamRaw = res.data;
         }
         else if (game === 'cs2') {
-            const res = await fetchJson(ctx, '/cs2/teams', { query: { search: idOrSlug, limit: 5 } });
+            // A cs2-team-<n> / hltv-team-<n> id resolves 1:1 — fetch it directly instead of
+            // name-searching, which could silently fall back to rows[0] of an unrelated search.
+            const directId = /^(cs2|hltv)-team-\d+$/i.test(idOrSlug);
+            const res = directId
+                ? await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(idOrSlug)}`)
+                : await fetchJson(ctx, '/cs2/teams', { query: { search: idOrSlug, limit: 5 } });
             upstreamCalls += 1;
             rateLimit = res.headers;
             if (!res.ok) {
@@ -143,7 +148,10 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
                     ],
                 });
             }
-            {
+            if (directId) {
+                teamRaw = res.data;
+            }
+            else {
                 const rows = extractRows(res.data);
                 teamRaw =
                     rows.find((row) => {
@@ -285,20 +293,20 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
         if (game === 'cs2') {
             const tid = team.id !== 'unknown' ? team.id : idOrSlug;
             tasks.push((async () => {
-                const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(tid)}/roster-history`);
+                const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(tid)}/roster`);
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     roster = {
                         items: extractRows(res.data).slice(0, 20),
                         asOf: new Date().toISOString(),
-                        quality: 'history',
+                        quality: 'current',
                     };
                 }
                 else {
                     partial.push(partialFromRejection('roster', {
                         code: mapHttpToCode(res.status),
-                        message: `roster-history HTTP ${res.status}`,
+                        message: `roster HTTP ${res.status}`,
                         httpStatus: res.status,
                     }));
                 }
@@ -478,19 +486,19 @@ function winnerSide(match, a) {
 }
 export const headToHead = {
     name: 'head_to_head',
-    description: `Composed head-to-head record between two teams (or two UFC fighters). No first-class REST H2H exists — this tool filters match history server-side.
-
-When to use:
-- Rivalry / series record questions
-- Supporting context for previews
-
-Prefer over: agent-side double match-list filtering.
-
-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.
+    description: `Composed head-to-head record between two teams (or two UFC fighters). No first-class REST H2H exists — this tool filters match history server-side.
+
+When to use:
+- Rivalry / series record questions
+- Supporting context for previews
+
+Prefer over: agent-side double match-list filtering.
+
+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.
 Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
     inputSchema: {
         type: 'object',
@@ -547,24 +555,80 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
         let upstreamCalls = 0;
         let rateLimit = {};
         let rows = [];
+        // Names used for client-side side matching; replaced with resolved team names
+        // when the id-based REST H2H succeeds (short inputs like "navi" never substring-match "Natus Vincere").
+        let matchA = sideA;
+        let matchB = sideB;
         if (game === 'cs2') {
-            const res = await fetchJson(ctx, '/cs2/matches', { query: { team: sideA, limit: 50 } });
-            upstreamCalls += 1;
-            rateLimit = res.headers;
-            if (!res.ok) {
-                return errorEnvelope({
-                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
-                    message: `H2H match fetch failed (HTTP ${res.status})`,
-                    game,
-                    source: 'head_to_head',
-                    requestId,
-                    tookMs: Date.now() - started,
-                    upstreamCalls,
-                    httpStatus: res.status,
-                    rateLimit: res.headers,
+            // Prefer the purpose-built id-based H2H endpoint; /cs2/matches?team= name-substring
+            // filtering misses short names ("navi" vs stored "Natus Vincere").
+            const resolveCs2Side = async (side) => {
+                const res = await fetchJson(ctx, '/cs2/teams', { query: { search: side, limit: 5 } });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (!res.ok)
+                    return null;
+                const found = extractRows(res.data);
+                const hit = found.find((row) => {
+                    const r = asRecord(row) ?? {};
+                    return [r.id, r.slug, r.name].map((x) => String(x ?? '').toLowerCase()).includes(side.toLowerCase());
+                }) ?? found[0];
+                const r = asRecord(hit);
+                const id = pickString(r?.id, r?.teamId);
+                return id ? { id, name: pickString(r?.name) ?? side } : null;
+            };
+            const [cs2SideA, cs2SideB] = await Promise.all([resolveCs2Side(sideA), resolveCs2Side(sideB)]);
+            let restH2hOk = false;
+            if (cs2SideA && cs2SideB) {
+                const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(cs2SideA.id)}/vs/${encodeURIComponent(cs2SideB.id)}`, {
+                    query: { limit: 50 },
                 });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    // Rows are side-A-perspective summaries (summarizeMatchForTeam); reshape into
+                    // flat match rows so the shared normalize/score pipeline applies unchanged.
+                    rows = extractRows(res.data).map((row) => {
+                        const r = asRecord(row) ?? {};
+                        return {
+                            matchId: r.match_id,
+                            status: r.status,
+                            startsAt: r.starts_at,
+                            eventName: r.event_name,
+                            bestOf: r.best_of,
+                            team1Name: cs2SideA.name,
+                            team1Score: r.team_score,
+                            team2Name: pickString(r.opponent_name) ?? cs2SideB.name,
+                            team2Score: r.opponent_score,
+                        };
+                    });
+                    matchA = cs2SideA.name;
+                    matchB = cs2SideB.name;
+                    restH2hOk = true;
+                }
+                else {
+                    warnings.push(`REST H2H HTTP ${res.status}; fell back to match-history name filtering`);
+                }
+            }
+            if (!restH2hOk) {
+                const res = await fetchJson(ctx, '/cs2/matches', { query: { team: sideA, limit: 50 } });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (!res.ok) {
+                    return errorEnvelope({
+                        code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                        message: `H2H match fetch failed (HTTP ${res.status})`,
+                        game,
+                        source: 'head_to_head',
+                        requestId,
+                        tookMs: Date.now() - started,
+                        upstreamCalls,
+                        httpStatus: res.status,
+                        rateLimit: res.headers,
+                    });
+                }
+                rows = extractRows(res.data);
             }
-            rows = extractRows(res.data);
         }
         else if (game === 'cod') {
             const res = await fetchJson(ctx, '/cod/matches', { query: { team: sideA, limit: 50 } });
@@ -672,7 +736,7 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
         }
         const meetings = rows
             .map((row) => normalizeMatch(game, row))
-            .filter((m) => sidesMatch(m, sideA, sideB))
+            .filter((m) => sidesMatch(m, matchA, matchB))
             .filter((m) => {
             if (!fromIso && !toIso)
                 return true;
@@ -692,7 +756,7 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
         let winsB = 0;
         let draws = 0;
         for (const m of meetings) {
-            const w = winnerSide(m, sideA);
+            const w = winnerSide(m, matchA);
             if (w === 'A')
                 winsA += 1;
             else if (w === 'B')

package/dist/version.js

@@ -0,0 +1,29 @@
+import { createRequire } from 'node:module';
+/**
+ * Single source of truth for the server version.
+ *
+ * This used to be hardcoded in three places — package.json, PACKAGE_VERSION in
+ * index.ts, and CATALOG_VERSION in tools/meta.ts — which had already drifted:
+ * a test asserted 0.2.4 while the package shipped 0.2.5. Agents read the version
+ * out of list_capabilities, so a stale value there is a support problem, not a
+ * cosmetic one. Read it from the manifest instead, so `npm version` is the only
+ * edit a release needs.
+ *
+ * createRequire rather than a JSON import: import assertions are still awkward
+ * across the Node versions this package supports (>=20), and this resolves the
+ * same from src/ under tsx and from dist/ once built, because package.json is
+ * always published alongside dist.
+ */
+const require = createRequire(import.meta.url);
+function readVersion() {
+    try {
+        const pkg = require('../package.json');
+        return typeof pkg.version === 'string' && pkg.version ? pkg.version : '0.0.0';
+    }
+    catch {
+        // Never let a packaging quirk crash the server on boot; a wrong-but-present
+        // version is far better than a failed start.
+        return '0.0.0';
+    }
+}
+export const PACKAGE_VERSION = readVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Standalone MCP server for the Cito esports API — 15 curated outcome tools for agents (live, schedule, profiles, standings, previews, event cards).",
   "type": "module",
   "bin": {