@claudinho/mcp 0.8.17 → 0.8.19

package/README.md

@@ -51,9 +51,11 @@ Then just ask your agent naturally — it picks the right tool and answers with
 | `get_next_fixture` | a team's next match (3-letter code, e.g. `MEX`) — live-resolves a confirmed knockout tie from the feed; group fixtures offline, fails back to the bundled schedule if the feed is down |
 | `get_market_signal` | read-only prediction-market signal for a match, a team's current-or-next fixture (in-play preferred while live), or a date — informational only |
 | `get_share_snippet` | a copy-pasteable plain-text card — for a match, a team's next fixture, a group's standings table (`group`), the knockout bracket (`bracket: true`, optional `knockoutStage`), a date, or live — hand the returned snippet to the user as-is |
+| `get_team` | resolve a nation name or code to its FIFA 3-letter code, flag, and group — fuzzy (`Mexico`, `mex`, `DR Congo`, `Türkiye`); call it first to turn a user's team name into the code the other tools need. Offline (no network) |
 
-All tools are **read-only** (`readOnlyHint`) and accept optional `tz`, `lang`
-(`en`/`es`/`pt`/`fr`), and `flavor` (`off`/`subtle`/`full`). Every response carries
+Most tools are **read-only** (`readOnlyHint`) and accept optional `tz`, `lang`
+(`en`/`es`/`pt`/`fr`), and `flavor` (`off`/`subtle`/`full`); `get_team` is read-only
+**and** offline. Every response carries
 human-readable text **and** structured content, validated against each tool's
 declared `outputSchema`.
 

package/dist/index.js

@@ -504,6 +504,33 @@ function shiftUtcDate(dateISO, days) {
   const [y, m, d] = dateISO.slice(0, 10).split("-").map(Number);
   return new Date(Date.UTC(y ?? 1970, (m ?? 1) - 1, (d ?? 1) + days)).toISOString().slice(0, 10);
 }
+var FEED_TEXT_MAX = 100;
+function sanitizeFeedText(value, max = FEED_TEXT_MAX) {
+  let out = "";
+  let count = 0;
+  for (const ch of String(value)) {
+    const cp = ch.codePointAt(0) ?? 0;
+    const isWhitespaceControl = cp === 9 || cp === 10 || cp === 13;
+    if ((cp <= 31 || cp >= 127 && cp <= 159) && !isWhitespaceControl) continue;
+    if (count >= max) break;
+    out += isWhitespaceControl ? " " : ch;
+    count++;
+  }
+  return out;
+}
+var segmenter = new Intl.Segmenter();
+var WIDE_CLUSTER = new RegExp("^(?:\\p{Regional_Indicator}|\\p{Extended_Pictographic})", "u");
+function displayWidth(s) {
+  let w = 0;
+  for (const { segment } of segmenter.segment(s)) {
+    w += WIDE_CLUSTER.test(segment) ? 2 : 1;
+  }
+  return w;
+}
+function padVisible(s, width) {
+  const w = displayWidth(s);
+  return w >= width ? s : s + " ".repeat(width - w);
+}
 function outcomeFromScore(home, away) {
   if (home > away) return "H";
   if (home < away) return "A";
@@ -2802,6 +2829,60 @@ function groups(fixtures = SCHEDULE) {
   for (const m of fixtures) if (m.group) set.add(m.group);
   return [...set].sort();
 }
+function norm2(s) {
+  return s.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z]/g, "");
+}
+function allTeams(fixtures = allFixtures()) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const m of fixtures) {
+    if (m.stage !== "GROUP") continue;
+    for (const t2 of [m.home, m.away]) {
+      if (!/^[A-Z]{3}$/.test(t2.code) || t2.flag === "\u{1F3F3}\uFE0F") continue;
+      if (!seen.has(t2.code)) seen.set(t2.code, { ...t2, group: m.group ?? void 0 });
+    }
+  }
+  return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+var TEAM_ALIASES = {
+  turkey: "TUR",
+  holland: "NED",
+  korea: "KOR",
+  skorea: "KOR",
+  korearepublic: "KOR",
+  republicofkorea: "KOR",
+  czechrepublic: "CZE",
+  congo: "COD",
+  drcongo: "COD",
+  drc: "COD",
+  democraticrepublicofcongo: "COD",
+  democraticrepublicofthecongo: "COD",
+  cotedivoire: "CIV",
+  caboverde: "CPV",
+  bosnia: "BIH",
+  bosniaandherzegovina: "BIH",
+  us: "USA",
+  america: "USA",
+  unitedstatesofamerica: "USA"
+};
+function lookupTeam(query, fixtures = allFixtures()) {
+  const roster = allTeams(fixtures);
+  const q = norm2(query);
+  if (!q) return { query, team: null, matches: [] };
+  const byCode = roster.find((t2) => norm2(t2.code) === q);
+  if (byCode) return { query, team: byCode, matches: [byCode] };
+  const byName = roster.find((t2) => norm2(t2.name) === q);
+  if (byName) return { query, team: byName, matches: [byName] };
+  const aliasCode = TEAM_ALIASES[q];
+  if (aliasCode) {
+    const t2 = roster.find((r) => r.code === aliasCode);
+    if (t2) return { query, team: t2, matches: [t2] };
+  }
+  if (q.length < 3) return { query, team: null, matches: [] };
+  const prefix = roster.filter((t2) => norm2(t2.name).startsWith(q));
+  const substr = roster.filter((t2) => norm2(t2.name).includes(q) && !prefix.includes(t2));
+  const matches = [...prefix, ...substr];
+  return { query, team: matches.length === 1 ? matches[0] : null, matches };
+}
 function blankRow(team) {
   return {
     team,
@@ -2827,6 +2908,7 @@ var ESPN_SOCCER = "https://site.api.espn.com/apis/site/v2/sports/soccer";
 var DEFAULT_COMPETITION = "fifa.world";
 var DEFAULT_BASE = `${ESPN_SOCCER}/${DEFAULT_COMPETITION}`;
 var USER_AGENT = "claudinho/0.0 (+https://github.com/arturogarrido/claudinho)";
+var MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
 function competitionBase(slug) {
   return `${ESPN_SOCCER}/${slug}`;
 }
@@ -2870,9 +2952,15 @@ function toInt(s) {
   return Number.isFinite(n) ? n : void 0;
 }
 function toTeam(t2) {
-  const name = t2?.displayName ?? t2?.name ?? t2?.location ?? t2?.shortDisplayName ?? "TBD";
-  const code = (t2?.abbreviation ?? name.slice(0, 3)).toUpperCase();
-  return { code, name, flag: nationToFlag(t2?.displayName ?? t2?.abbreviation ?? name) };
+  const name = sanitizeFeedText(
+    t2?.displayName ?? t2?.name ?? t2?.location ?? t2?.shortDisplayName ?? "TBD"
+  );
+  const code = sanitizeFeedText(t2?.abbreviation ?? name.slice(0, 3)).toUpperCase();
+  return {
+    code,
+    name,
+    flag: nationToFlag(sanitizeFeedText(t2?.displayName ?? t2?.abbreviation ?? name))
+  };
 }
 function mapEspnEvent(ev, ctx = {}) {
   const comp = ev.competitions?.[0];
@@ -2903,9 +2991,9 @@ function mapEspnEvent(ev, ctx = {}) {
     stage,
     group,
     kickoff: ev.date,
-    venue: comp?.venue?.fullName ?? "",
-    city: comp?.venue?.address?.city || void 0,
-    country: comp?.venue?.address?.country || void 0,
+    venue: sanitizeFeedText(comp?.venue?.fullName ?? ""),
+    city: sanitizeFeedText(comp?.venue?.address?.city ?? "") || void 0,
+    country: sanitizeFeedText(comp?.venue?.address?.country ?? "") || void 0,
     home,
     away,
     score: hasScore ? { home: hs, away: as } : void 0,
@@ -3029,11 +3117,18 @@ var EspnAdapter = class {
     try {
       const res = await doFetch(url, {
         signal: controller.signal,
+        // ESPN never legitimately redirects; following one would sidestep the
+        // fixed-host guarantee, so treat any redirect as a failure (degraded).
+        redirect: "error",
         headers: { Accept: "application/json", "User-Agent": USER_AGENT }
       });
       if (!res.ok) {
         throw new Error(`ESPN request failed: ${res.status} ${res.statusText}`);
       }
+      const length = Number(res.headers?.get?.("content-length"));
+      if (Number.isFinite(length) && length > MAX_RESPONSE_BYTES) {
+        throw new Error(`ESPN response too large: ${length} bytes`);
+      }
       return await res.json();
     } finally {
       clearTimeout(timer);
@@ -4175,12 +4270,19 @@ var PolymarketProvider = class {
     const doFetch = this.opts.fetchImpl ?? fetch;
     const res = await doFetch(url, {
       signal: AbortSignal.timeout(timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+      // Gamma never legitimately redirects; following one would sidestep the
+      // host allow-list (it only validates the base URL), so reject redirects.
+      redirect: "error",
       headers: { Accept: "application/json", "User-Agent": USER_AGENT2 }
     });
     if (res.status === 404) return void 0;
     if (!res.ok) {
       throw new Error(`Polymarket request failed: ${res.status} ${res.statusText}`);
     }
+    const length = Number(res.headers?.get?.("content-length"));
+    if (Number.isFinite(length) && length > MAX_RESPONSE_BYTES) {
+      throw new Error(`Polymarket response too large: ${length} bytes`);
+    }
     const data = await res.json();
     const event = Array.isArray(data) ? data[0] : data;
     return event && typeof event === "object" ? event : void 0;
@@ -4623,17 +4725,21 @@ function matchList(matches, empty, opts = {}) {
 }
 function standingsTable(group, rows) {
   const header = `Group ${group}`;
-  const cols = "Team                     P  W  D  L   GD  Pts";
-  const lines = rows.map((r) => {
-    const name = `${r.team.flag} ${r.team.name}`.padEnd(24).slice(0, 24);
-    const gd2 = (r.goalDiff > 0 ? `+${r.goalDiff}` : `${r.goalDiff}`).padStart(3);
-    return `${name} ${pad(r.played)} ${pad(r.won)} ${pad(r.drawn)} ${pad(r.lost)} ${gd2}  ${pad(r.points)}`;
-  });
+  const line = (team, p, w, d, l, gd2, pts) => `${padVisible(team, 24)} ${p.padStart(2)} ${w.padStart(2)} ${d.padStart(2)} ${l.padStart(2)} ${gd2.padStart(3)} ${pts.padStart(3)}`;
+  const cols = line("Team", "P", "W", "D", "L", "GD", "Pts");
+  const lines = rows.map(
+    (r) => line(
+      `${r.team.flag} ${r.team.name}`,
+      String(r.played),
+      String(r.won),
+      String(r.drawn),
+      String(r.lost),
+      r.goalDiff > 0 ? `+${r.goalDiff}` : String(r.goalDiff),
+      String(r.points)
+    )
+  );
   return [header, cols, ...lines].join("\n");
 }
-function pad(n) {
-  return `${n}`.padStart(2);
-}
 var DISCLAIMER = "Claudinho is an independent fan project \u2014 not affiliated with or endorsed by FIFA or Anthropic.";
 
 // src/tools.ts
@@ -4874,16 +4980,31 @@ async function toolGetNextFixture(args) {
     const msg = degraded ? `Couldn't reach the data provider \u2014 no upcoming fixture confirmed for ${code}.` : `No upcoming fixture found for ${code}.`;
     return {
       text: withDisclaimer(msg, void 0, args.lang),
-      data: { team: code, fixture: null, degraded }
+      data: { team: code, fixture: null, degraded, source: source ?? null }
     };
   }
   const opts = fmtOpts(args);
   return {
+    // `source` in data mirrors the text's "Live data: …" attribution (parity
+    // with CLI `next --json`); null for a static group fixture (no live source).
     text: withDisclaimer(`Next up for ${code}:
 ${matchLine(fixture, opts)}`, source, args.lang),
-    data: { team: code, fixture, degraded }
+    data: { team: code, fixture, degraded, source: source ?? null }
   };
 }
+function toolGetTeam(args) {
+  const { team, matches } = lookupTeam(args.query ?? "");
+  const data = { query: args.query ?? "", team: team ?? null, matches, count: matches.length };
+  let text;
+  if (team) {
+    text = `${team.code} \u2014 ${team.flag} ${team.name}${team.group ? ` \xB7 Group ${team.group}` : ""}`;
+  } else if (matches.length > 0) {
+    text = `"${args.query}" is ambiguous. Did you mean: ${matches.map((t2) => `${t2.name} (${t2.code})`).join(", ")}?`;
+  } else {
+    text = `No team found for "${args.query}". Use a nation name or 3-letter code (e.g. Mexico, MEX).`;
+  }
+  return { text: withDisclaimer(text), data };
+}
 async function toolGetMarketSignal(args) {
   const provider = resolveMarketProvider(args);
   const now = args.now ?? /* @__PURE__ */ new Date();
@@ -5152,11 +5273,12 @@ async function toolGetShareSnippet(args) {
 
 // src/server.ts
 var SERVER_NAME = "claudinho";
-var SERVER_VERSION = "0.8.17";
+var SERVER_VERSION = "0.8.19";
 var VOICE = asFlavorLevel(process.env.CLAUDINHO_FLAVOR) === "off" ? "" : `
 Voice: when relaying scores, narrate with lively, regionally-appropriate football-commentary energy in the user's language. Each match line may end with a short exclamation ("\u2014 \xA1GOOOOL!") \u2014 use it as a tone cue. Keep every fact exact; never invent details and never impersonate or name a real commentator.`;
 var INSTRUCTIONS = `Claudinho serves live scores, fixtures, and group standings for the 2026 men's football tournament.
-Use get_live during matches, get_today for a day's schedule, get_next_fixture for a specific team (3-letter code, e.g. MEX), get_standings for group tables, and get_bracket for the knockout tree.
+The team-taking tools (get_next_fixture, get_market_signal, get_share_snippet) expect a 3-letter code (e.g. MEX). When the user gives a nation NAME, call get_team FIRST to resolve it \u2014 get_team is fuzzy ("Mexico", "DR Congo", "T\xFCrkiye"), offline, and returns candidates when the name is ambiguous.
+Use get_live during matches, get_today for a day's schedule, get_next_fixture for a specific team, get_standings for group tables, and get_bracket for the knockout tree.
 Use get_market_signal for read-only prediction-market signals (a match, a team's current-or-next fixture, or a date). Market data is informational only \u2014 relay the percentages factually and never frame it as betting or trading advice.
 Use get_share_snippet to produce a ready-to-paste match card (for a match, a team's next fixture, a date, or live matches) \u2014 hand the user the returned snippet text verbatim.${VOICE}
 ${DISCLAIMER}`;
@@ -5166,7 +5288,9 @@ var teamArg = z.string().regex(/^[A-Za-z]{3}$/, "a 3-letter team code, e.g. MEX"
 var flavorArg = z.enum(["off", "subtle", "full"]);
 var commonArgs = {
   tz: z.string().optional().describe("IANA timezone for kickoff times, e.g. America/Mexico_City"),
-  lang: z.string().optional().describe("Locale for formatting: en, es, pt, fr (other locales fall back to en)"),
+  lang: z.string().optional().describe(
+    "Locale for dates, provider attribution, and commentary: en, es, pt, fr (the summary scaffold stays English; other locales fall back to en)"
+  ),
   flavor: flavorArg.optional().describe("Commentary flair: off, subtle, full (default: full)")
 };
 var teamRef = z.object({ code: z.string(), name: z.string(), flag: z.string() }).partial().passthrough();
@@ -5213,7 +5337,12 @@ var bracketOut = {
   standingsDegraded: z.boolean().optional(),
   source: src.optional()
 };
-var nextOut = { team: z.string(), fixture: matchOut.nullable(), degraded: z.boolean() };
+var nextOut = {
+  team: z.string(),
+  fixture: matchOut.nullable(),
+  degraded: z.boolean(),
+  source: src
+};
 var marketOut = {
   matchId: z.string().nullable().optional(),
   team: z.string().optional(),
@@ -5240,6 +5369,13 @@ var shareOut = {
   matches: z.array(matchOut).optional(),
   marketSignals: z.record(anyObj).optional()
 };
+var teamInfo = z.object({ code: z.string(), name: z.string(), flag: z.string(), group: z.string() }).partial().passthrough();
+var teamOut = {
+  query: z.string(),
+  team: teamInfo.nullable(),
+  matches: z.array(teamInfo),
+  count: z.number()
+};
 function toContent(r) {
   return {
     content: [
@@ -5258,7 +5394,7 @@ function buildServer() {
     "get_today",
     {
       title: "Today's matches",
-      description: "All fixtures for a date (default: today), with live score and minute overlaid on any match in play. Use this for a whole day's card; for only in-play matches use get_live, for one team's match use get_next_fixture, for a single match's detail use get_match. Kickoffs render in tz; lang localizes text (en/es/pt/fr); flavor sets commentary tone.",
+      description: "All fixtures for a date (default: today), with live score and minute overlaid on any match in play. Use this for a whole day's card; for only in-play matches use get_live, for one team's match use get_next_fixture, for a single match's detail use get_match. Kickoffs render in tz; lang localizes dates, attribution, and commentary (en/es/pt/fr); flavor sets commentary tone.",
       inputSchema: {
         date: dateArg.optional().describe("Date as YYYY-MM-DD (default: today)"),
         ...commonArgs
@@ -5375,6 +5511,20 @@ function buildServer() {
     },
     async (args) => toContent(await toolGetShareSnippet(args))
   );
+  server.registerTool(
+    "get_team",
+    {
+      title: "Resolve a team",
+      description: `Resolve a nation name or 3-letter code to its FIFA code, flag, and group. Fuzzy and forgiving: accepts "Mexico", "mex", "USA", "DR Congo", "T\xFCrkiye"/"Turkey", "Holland", etc. Use this FIRST to turn a user's team name into the code the other tools need (get_next_fixture, get_standings, get_market_signal, get_share_snippet). Returns the single confident match (team), plus candidates (matches) when the query is ambiguous (e.g. "south" \u2192 South Africa, South Korea). Offline \u2014 reads the bundled roster, never the network.`,
+      inputSchema: {
+        query: z.string().describe('Team name or 3-letter code, e.g. "Mexico", "MEX", "DR Congo"')
+      },
+      // Read-only AND offline — resolves against the bundled roster, no provider call.
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      outputSchema: teamOut
+    },
+    async (args) => toContent(toolGetTeam(args))
+  );
   server.registerResource(
     "standings",
     new ResourceTemplate("standings://{group}", { list: void 0 }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudinho/mcp",
-  "version": "0.8.17",
+  "version": "0.8.19",
   "mcpName": "io.github.arturogarrido/claudinho",
   "description": "MCP server for the 2026 men's football tournament — live scores, fixtures, standings, read-only prediction-market signals, and paste-ready match cards. Works with Claude Code, Cursor, Codex, Windsurf, Zed. Not affiliated with FIFA or Anthropic.",
   "type": "module",
@@ -26,6 +26,7 @@
   },
   "files": [
     "dist",
+    "!dist/*.mcpb",
     "README.md",
     "LICENSE"
   ],
@@ -57,7 +58,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.9",
-    "@claudinho/core": "0.8.17"
+    "@claudinho/core": "0.8.19"
   },
   "scripts": {
     "build": "tsup",