cito-mcp 0.3.17 → 0.3.18

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/package.json

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