cito-mcp 0.3.17 → 0.3.19

package/dist/tools/insight.js

@@ -3,7 +3,7 @@
  */
 import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
-import { normalizeMatch, presentSides, sortByCardOrder } from './normalize.js';
+import { chooseNamedEntity, normalizeMatch, presentSides, sortByCardOrder } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
 async function loadSide(ctx, game, side, recentLimit, includeRosters) {
     const partial = [];
@@ -663,9 +663,17 @@ async function resolveEventKey(ctx, game, q) {
             calls += 1;
             rateLimit = res.headers;
             const rows = extractRows(unwrapPayload(res.data) ?? res.data).map((r) => asRecord(r) ?? {});
+            // .find() returned whatever the calendar happened to list first, and the
+            // calendar lists the WTA row before the ATP one for a shared name, while
+            // /tennis/competitions (which resolve_entity reads) lists them the other
+            // way round. Same query, two tools, two ids. One shared rule now settles
+            // both; see chooseNamedEntity.
             hit =
-                rows.find((r) => String(pickString(r.name) ?? '').toLowerCase() === needle) ??
-                    rows.find((r) => String(pickString(r.name) ?? '').toLowerCase().includes(needle));
+                chooseNamedEntity(rows, needle, (r) => ({
+                    id: pickString(r.id, r.tournament_id) ?? '',
+                    name: pickString(r.name) ?? '',
+                    year: r.year,
+                })) ?? undefined;
             if (hit)
                 break;
         }

package/dist/tools/normalize.js

@@ -638,3 +638,51 @@ export function rankScore(query, name, id, slug, ...extra) {
     }
     return best;
 }
+/**
+ * Edition year encoded in a tennis-style entity id ("atp_2026_580" -> 2026).
+ *
+ * `/tennis/competitions` returns no `year` field while the calendar does, so
+ * the id is the only signal available on both, and the two tools that disagreed
+ * about "Australian Open" were each reading a different one of those endpoints.
+ */
+export function editionYear(id, explicit) {
+    const direct = Number(explicit);
+    if (Number.isFinite(direct) && direct > 1800)
+        return direct;
+    const match = /^[a-z]+_(\d{4})_/i.exec(String(id ?? ''));
+    return match ? Number(match[1]) : null;
+}
+/**
+ * Deterministic winner among rows whose names match a query equally well.
+ *
+ * "Australian Open" is two rows in every season, one ATP and one WTA, sharing a
+ * name exactly. resolve_entity read /tennis/competitions, which lists ATP
+ * first; event_card read /tennis/tournaments/calendar, which lists WTA first;
+ * and neither applied a tiebreak, so the same question got atp_2026_580 from
+ * one tool and wta_2026_580 from the other. Neither answer was wrong on its
+ * own. The absence of a rule was the bug.
+ *
+ * Order: an exact name beats a substring, a newer edition beats an older one,
+ * and the id settles whatever is left. That last step is arbitrary, and that is
+ * fine -- it only has to be FIXED, which is the property that was missing.
+ * Callers that need the alternatives still surface them; this only decides
+ * which single row is called "best".
+ */
+export function chooseNamedEntity(rows, needle, read) {
+    const want = needle.trim().toLowerCase();
+    if (!want || !rows.length)
+        return null;
+    const scored = rows.map((row) => ({ row, ref: read(row) }));
+    const exact = scored.filter((s) => s.ref.name.trim().toLowerCase() === want);
+    const pool = exact.length
+        ? exact
+        : scored.filter((s) => s.ref.name.trim().toLowerCase().includes(want));
+    if (!pool.length)
+        return null;
+    pool.sort((a, b) => {
+        const ay = editionYear(a.ref.id, a.ref.year) ?? -1;
+        const by = editionYear(b.ref.id, b.ref.year) ?? -1;
+        return by - ay || a.ref.id.localeCompare(b.ref.id);
+    });
+    return pool[0].row;
+}

package/dist/tools/resolve.js

@@ -3,8 +3,25 @@
  */
 import { clampInt, decodeCursor, encodeCursor, extractRows, fetchJson, gameNotIncludedHint, pickString, asRecord, } from '../client.js';
 import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT, errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
-import { entityRef, rankScore } from './normalize.js';
+import { editionYear, entityRef, rankScore } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
+/**
+ * Ranking order whose tiebreak never depends on the order upstream happened to
+ * return rows in.
+ *
+ * "Australian Open" is two rows with byte-identical names and identical fuzzy
+ * scores, one ATP and one WTA. The old comparator ran out of criteria there and
+ * left the winner to the source ordering, and event_card reads a different
+ * source that orders them the other way round, so the two tools answered the
+ * same question with different ids. Newest edition, then id, matching
+ * chooseNamedEntity so both paths land on the same row.
+ */
+function byRank(a, b) {
+    return (b.score - a.score
+        || a.name.localeCompare(b.name)
+        || ((editionYear(b.id) ?? -1) - (editionYear(a.id) ?? -1))
+        || a.id.localeCompare(b.id));
+}
 /**
  * Query aliases for orgs whose common name is not their slug. Kept deliberately
  * small and one-directional: these map what a person types onto the canonical
@@ -54,7 +71,7 @@ function pushCandidates(out, game, type, rows, q, limit) {
             ...(Object.keys(secondary).length ? { secondaryIds: secondary } : {}),
         });
     }
-    out.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+    out.sort(byRank);
     if (out.length > limit * 3)
         out.length = limit * 3;
 }
@@ -133,7 +150,7 @@ async function ufcSearch(ctx, q, type, limit) {
     // Dedupe by type+id
     const seen = new Set();
     const deduped = [];
-    for (const c of candidates.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))) {
+    for (const c of candidates.sort(byRank)) {
         const key = `${c.type}:${c.id}:${c.slug ?? ''}`;
         if (seen.has(key))
             continue;
@@ -394,25 +411,25 @@ async function searchGame(ctx, game, q, type, limit) {
             }),
         };
     }
-    candidates.sort((a, b) => b.score - a.score);
+    candidates.sort(byRank);
     return { candidates: candidates.slice(0, limit), calls };
 }
 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',
@@ -473,7 +490,7 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
             if (r.error)
                 partial.push(r.error);
         }
-        all.sort((a, b) => b.score - a.score);
+        all.sort(byRank);
         const candidates = all.slice(0, limit);
         const best = candidates[0] ?? null;
         // An exact identity hit is not ambiguous, whatever else scored near it.
@@ -520,22 +537,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',

package/dist/tools/team.js

@@ -1,7 +1,7 @@
 /**
  * team_profile + head_to_head
  */
-import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
+import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { normalizeMatch } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
@@ -24,22 +24,36 @@ function teamIdentity(game, raw, idHint, slugHint) {
         name,
         game,
         region: pickString(nested.region, nested.country) ?? null,
+        // CS2 publishes countryName/countryCode and worldRanking on the team
+        // resource and none of it reached this card: a team page rendered with no
+        // flag and no ladder position while the API had both. Spirit came back as
+        // {id, slug, name, game, region} with world #1 nowhere in sight.
+        country: pickString(nested.countryName, nested.country, nested.countryCode) ?? null,
+        countryCode: pickString(nested.countryCode) ?? null,
+        worldRanking: numberOrNull(nested.worldRanking ?? nested.ranking ?? nested.rank),
     };
 }
+/** A finite number, or null. Ranks arrive as number or numeric string. */
+function numberOrNull(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
 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',
@@ -374,8 +388,11 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
                 const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(tid)}/trends`);
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
+                // res.data is the whole upstream body, so this nested
+                // {success, data:{...}} inside our own envelope. Every other field
+                // here is normalized; this one leaked the REST wrapper to the agent.
                 if (res.ok)
-                    form = res.data;
+                    form = unwrapPayload(res.data) ?? res.data;
                 else {
                     partial.push(partialFromRejection('form', {
                         code: mapHttpToCode(res.status),
@@ -545,19 +562,19 @@ function winnerSide(match, a) {
 }
 export const headToHead = {
     name: 'head_to_head',
-    description: `Composed head-to-head record between two teams, two UFC fighters, or two tennis players. 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, two UFC fighters, or two tennis players. 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',

package/package.json

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