cito-mcp 0.2.4 → 0.2.6

package/dist/tools/player.js

@@ -29,6 +29,24 @@ function identityFrom(game, raw, idHint, slugHint) {
             : null,
         role: pickString(r.role, r.position) ?? null,
         nationality: pickString(r.nationality, r.country) ?? null,
+        /**
+         * Always present, keys always present, null when the upstream has no photo.
+         *
+         * REST has carried headshot/body/proxied images on /ufc/fighters/{slug} all
+         * along; this shaper silently dropped them, so every agent concluded the
+         * product had no images and either shipped faceless UIs or N+1'd call_api
+         * per fighter to dig them out. Emitting explicit nulls is the point: silence
+         * reads as "not supported", null reads as "not available for this one".
+         *
+         * proxiedImageUrl is the one builders should prefer — it is served from our
+         * own domain, so it works from a browser without hotlink/CORS trouble.
+         */
+        images: {
+            headshotUrl: pickString(r.headshotUrl, r.headshot) ?? null,
+            bodyImageUrl: pickString(r.bodyImageUrl, r.fullBodyImageUrl) ?? null,
+            imageUrl: pickString(r.imageUrl, r.image, r.photoUrl) ?? null,
+            proxiedImageUrl: pickString(r.proxiedImageUrl, r.proxiedHeadshotUrl) ?? null,
+        },
     };
 }
 export const playerProfile = {
@@ -332,7 +350,14 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                         .map((row) => {
                         const r = asRecord(row) ?? {};
                         const bout = asRecord(r.bout) ?? row;
-                        const m = normalizeMatch('ufc', bout, 'completed');
+                        // Never force 'completed'. A fighter's history endpoint also
+                        // returns bouts that are booked but not yet fought, and forcing
+                        // the status told agents that a future main event had already
+                        // happened (Hernandez vs Rodrigues, ufc-12928: status
+                        // 'confirmed', no method, no winner, event still scheduled,
+                        // reported as completed with result null). Let normalizeMatch
+                        // derive it from the result and the start time instead.
+                        const m = normalizeMatch('ufc', bout);
                         return {
                             ...m,
                             result: pickString(r.result, r.outcome, asRecord(bout)?.result) ?? null,
@@ -354,7 +379,8 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                             .map((row) => {
                             const r = asRecord(row) ?? {};
                             const bout = asRecord(r.bout) ?? row;
-                            return normalizeMatch('ufc', bout, 'completed');
+                            // Same as above: derive, never assert. See the note there.
+                            return normalizeMatch('ufc', bout);
                         });
                     }
                     else {

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/tools/types.js

@@ -64,9 +64,82 @@ export function stringSchema(description, example) {
         schema.examples = [example];
     return schema;
 }
+/** Levenshtein distance, capped for short arg names. */
+function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    let prev = Array.from({ length: n + 1 }, (_, j) => j);
+    for (let i = 1; i <= m; i++) {
+        const cur = [i];
+        for (let j = 1; j <= n; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[n];
+}
+/** Closest known parameter to a mistyped one, if it is plausibly a typo. */
+function suggestParam(unknown, known) {
+    const u = unknown.toLowerCase();
+    let best = null;
+    for (const k of known) {
+        const d = editDistance(u, k.toLowerCase());
+        if (!best || d < best.d)
+            best = { name: k, d };
+    }
+    if (!best)
+        return null;
+    // Accept near-misses, plus prefix relationships like query -> q.
+    const threshold = Math.max(2, Math.floor(Math.max(u.length, best.name.length) / 3));
+    if (best.d <= threshold)
+        return best.name;
+    const prefixHit = known.find((k) => u.startsWith(k.toLowerCase()) || k.toLowerCase().startsWith(u));
+    return prefixHit ?? null;
+}
+/**
+ * Args the tool does not declare, when its schema says additionalProperties:false.
+ *
+ * Every tool already declared that, but nothing enforced it: the MCP SDK does
+ * not validate arguments against inputSchema, so a plausible-but-wrong name was
+ * dropped on the floor and the tool ran with a default. search_entities
+ * { game:"ufc", query:"Jon Jones" } — `q` is the real parameter — returned
+ * ok:true with an unrelated roster. Silently wrong beats loudly wrong for a
+ * human skimming output, but for an agent it is far worse: it has no way to
+ * tell a real answer from a discarded question.
+ */
+export function unknownArgKeys(def, args) {
+    const schema = def.inputSchema ?? {};
+    if (schema.additionalProperties !== false)
+        return [];
+    const props = schema.properties;
+    if (!props || typeof props !== 'object')
+        return [];
+    const known = Object.keys(props);
+    return Object.keys(args ?? {}).filter((k) => !known.includes(k));
+}
 /** Normalize MCP handler return to MCP content result. */
 export async function runTool(def, args, ctx) {
     try {
+        const unknown = unknownArgKeys(def, args ?? {});
+        if (unknown.length > 0) {
+            const known = Object.keys((def.inputSchema.properties ?? {}));
+            const pairs = unknown.map((k) => ({ k, s: suggestParam(k, known) }));
+            const hints = pairs.map(({ k, s }) => s ? `"${k}" — did you mean "${s}"?` : `"${k}" is not accepted`);
+            const { errorEnvelope, toMcpResult: toResult } = await import('../envelope.js');
+            return toResult(errorEnvelope({
+                code: 'VALIDATION',
+                message: `${def.name}: unknown argument${unknown.length > 1 ? 's' : ''} ` +
+                    // Avoid "?." when the last hint is a did-you-mean question.
+                    `${hints.join('; ')}${hints[hints.length - 1].endsWith('?') ? '' : '.'} ` +
+                    `Accepted: ${known.join(', ')}.`,
+                game: typeof args?.game === 'string' ? args.game : null,
+                source: def.name,
+                recover: [
+                    ...pairs.map(({ k, s }) => s ? `Rename "${k}" to "${s}" and retry` : `Remove "${k}" and retry`),
+                    `Accepted arguments: ${known.join(', ')}`,
+                ],
+            }));
+        }
         const result = await def.handler(args ?? {}, ctx);
         if (result && typeof result === 'object' && 'content' in result) {
             return result;

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.6",
   "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": {
@@ -17,7 +17,8 @@
     "build": "tsc -p tsconfig.json",
     "test": "tsx --test src/**/*.test.ts src/*.test.ts",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm test && npm run smoke",
+    "smoke": "node scripts/smoke.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0"