@claudinho/mcp 0.4.3 → 0.5.1

package/README.md

@@ -35,10 +35,10 @@ Developer → Edit Config, then restart. Codex config file: `~/.codex/config.tom
 | `get_today` | fixtures for a date (default: today), grouped in the caller's `tz`, live scores overlaid |
 | `get_live` | matches in play right now |
 | `get_match` | a single match by id |
-| `get_standings` | group table(s) — one group `A`–`L`, or all |
+| `get_standings` | live cumulative group table(s) — one group `A`–`L`, or all |
 | `get_next_fixture` | a team's next match (3-letter code, e.g. `MEX`) — fully offline |
 | `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 match card — hand the returned snippet to the user as-is |
+| `get_share_snippet` | a copy-pasteable plain-text card — for a match, a team's next fixture, a group's standings table (`group`), a date, or live — hand the returned snippet to the user as-is |
 
 All tools are **read-only** (`readOnlyHint`) and accept optional `tz`, `lang`
 (`en`/`es`/`pt`/`fr`), and `flavor` (`off`/`subtle`/`full`). Every response carries

package/dist/index.js

@@ -2760,6 +2760,43 @@ function mapEspnEvent(ev, ctx = {}) {
 function toEspnDate(d) {
   return d.replace(/\D/g, "").slice(0, 8);
 }
+function statVal(stats, name) {
+  const v = stats?.find((s) => s.name === name)?.value;
+  return typeof v === "number" && Number.isFinite(v) ? Math.round(v) : 0;
+}
+function entryToRow(e) {
+  return {
+    team: toTeam(e.team),
+    played: statVal(e.stats, "gamesPlayed"),
+    won: statVal(e.stats, "wins"),
+    drawn: statVal(e.stats, "ties"),
+    lost: statVal(e.stats, "losses"),
+    goalsFor: statVal(e.stats, "pointsFor"),
+    goalsAgainst: statVal(e.stats, "pointsAgainst"),
+    goalDiff: statVal(e.stats, "pointDifferential"),
+    points: statVal(e.stats, "points")
+  };
+}
+function parseStandings(data) {
+  const out = [];
+  for (const child of data.children ?? []) {
+    const letter = (child.name ?? child.abbreviation ?? "").match(/Group\s+([A-L])/i)?.[1]?.toUpperCase();
+    if (!letter) continue;
+    const ranked = (child.standings?.entries ?? []).map((e) => ({
+      row: entryToRow(e),
+      rank: statVal(e.stats, "rank")
+    }));
+    ranked.sort((a, b) => {
+      if (a.rank && b.rank && a.rank !== b.rank) return a.rank - b.rank;
+      const r = a.row;
+      const s = b.row;
+      return s.points - r.points || s.goalDiff - r.goalDiff || s.goalsFor - r.goalsFor || r.team.code.localeCompare(s.team.code);
+    });
+    out.push({ group: letter, rows: ranked.map((x) => x.row) });
+  }
+  out.sort((a, b) => a.group.localeCompare(b.group));
+  return out;
+}
 var EspnAdapter = class {
   constructor(opts = {}) {
     this.opts = opts;
@@ -2779,25 +2816,30 @@ var EspnAdapter = class {
     const today = await this.fetchScoreboard();
     return today.filter((m) => m.status === "LIVE" || m.status === "HT");
   }
+  /** Standings endpoint URL (lives under apis/v2, not site/v2; derived from base). */
+  standingsUrl() {
+    const base = this.opts.baseUrl ?? DEFAULT_BASE;
+    return `${base.replace("/apis/site/v2/", "/apis/v2/")}/standings`;
+  }
+  /**
+   * Authoritative, cumulative group tables from the standings endpoint. Throws
+   * on fetch/parse failure (the caller decides the fallback). Group-stage only:
+   * non-group `children` are filtered out by {@link parseStandings}.
+   */
+  async fetchStandings() {
+    return parseStandings(await this.get(this.standingsUrl()));
+  }
   /**
    * Build (and cache) a team-code -> group-letter map from the standings
-   * endpoint. Best-effort: returns {} if standings are unavailable.
+   * endpoint. Best-effort: returns {} if standings are unavailable. Reuses the
+   * same parse as {@link fetchStandings}, so the two never drift.
    */
   async fetchGroupMap(force = false) {
     if (this.groupMap && !force) return this.groupMap;
-    const base = this.opts.baseUrl ?? DEFAULT_BASE;
-    const standingsUrl = `${base.replace("/apis/site/v2/", "/apis/v2/")}/standings`;
     const map = {};
     try {
-      const data = await this.get(standingsUrl);
-      for (const child of data.children ?? []) {
-        const letter = (child.name ?? child.abbreviation ?? "").match(/Group\s+([A-L])/i)?.[1]?.toUpperCase();
-        if (!letter) continue;
-        for (const e of child.standings?.entries ?? []) {
-          const code = e.team?.abbreviation?.toUpperCase();
-          if (code) map[code] = letter;
-        }
-      }
+      const tables = parseStandings(await this.get(this.standingsUrl()));
+      for (const t of tables) for (const r of t.rows) map[r.team.code] = t.group;
     } catch {
     }
     this.groupMap = map;
@@ -2868,6 +2910,22 @@ async function getMatchesForDate(adapter, dateISO) {
     return { matches: base, degraded: true };
   }
 }
+async function getStandings(adapter, group) {
+  const want = group?.toUpperCase();
+  if (adapter.fetchStandings) {
+    try {
+      const all = await adapter.fetchStandings();
+      const tables2 = (want ? all.filter((t) => t.group === want) : all).sort(
+        (a, b) => a.group.localeCompare(b.group)
+      );
+      return { tables: tables2, degraded: false, source: adapter.name };
+    } catch {
+    }
+  }
+  const letters = want ? [want] : groups();
+  const tables = letters.map((g) => ({ group: g, rows: computeStandings(fixturesByGroup(g)) })).filter((t) => t.rows.length > 0);
+  return { tables, degraded: true };
+}
 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);
@@ -3407,11 +3465,53 @@ function formatShareSnippet(input, options = {}) {
       blocks.push(card.join("\n"));
     }
   }
+  if (input.degraded && input.matches.length > 0) {
+    blocks.push("(Live data unavailable \u2014 showing the bundled schedule, not live scores.)");
+  }
+  blocks.push(
+    shareFooter({
+      source: input.source,
+      installLine: input.installLine,
+      includeHashtag,
+      includeInstall
+    })
+  );
+  return blocks.join("\n\n");
+}
+function shareFooter(opts) {
   const footer = [];
-  if (input.source) footer.push(`Live data: ${liveSourceLabel(input.source)}`);
-  footer.push([includeHashtag ? SHARE_HASHTAG : "", SHARE_DISCLAIMER].filter(Boolean).join(" \xB7 "));
-  if (includeInstall && input.installLine) footer.push(`Try it: ${input.installLine}`);
-  blocks.push(footer.join("\n"));
+  if (opts.source) footer.push(`Live data: ${liveSourceLabel(opts.source)}`);
+  footer.push(
+    [opts.includeHashtag ? SHARE_HASHTAG : "", SHARE_DISCLAIMER].filter(Boolean).join(" \xB7 ")
+  );
+  if (opts.includeInstall && opts.installLine) footer.push(`Try it: ${opts.installLine}`);
+  return footer.join("\n");
+}
+function gd(n) {
+  return n > 0 ? `+${n}` : `${n}`;
+}
+function tableRow(r, rank) {
+  return `${rank}. ${r.team.flag} ${r.team.code}  ${r.points} pts \xB7 ${r.won}-${r.drawn}-${r.lost} \xB7 ${gd(r.goalDiff)}`;
+}
+function formatShareTable(input, options = {}) {
+  const includeHashtag = options.includeHashtag !== false;
+  const includeInstall = options.includeInstallLine !== false;
+  const blocks = [];
+  if (input.tables.length === 0) {
+    blocks.push(input.emptyNote ?? "No standings available.");
+  } else {
+    for (const { group, rows } of input.tables) {
+      blocks.push(
+        [`Group ${group} \xB7 standings`, "", ...rows.map((r, i) => tableRow(r, i + 1))].join("\n")
+      );
+    }
+    if (input.degraded) {
+      blocks.push("(Live standings unavailable \u2014 group roster, not live results.)");
+    }
+  }
+  blocks.push(
+    shareFooter({ source: input.source, installLine: input.installLine, includeHashtag, includeInstall })
+  );
   return blocks.join("\n\n");
 }
 
@@ -3468,8 +3568,8 @@ function standingsTable(group, rows) {
   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 gd = (r.goalDiff > 0 ? `+${r.goalDiff}` : `${r.goalDiff}`).padStart(3);
-    return `${name} ${pad(r.played)} ${pad(r.won)} ${pad(r.drawn)} ${pad(r.lost)} ${gd}  ${pad(r.points)}`;
+    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)}`;
   });
   return [header, cols, ...lines].join("\n");
 }
@@ -3592,8 +3692,9 @@ async function toolGetToday(args) {
   const { matches, degraded, source } = await getMatchesForDate(adapter, date);
   const todays = fixturesByDate(date, matches, args.tz);
   const opts = fmtOpts(args);
-  const text = `Matches on ${date}:
+  let text = `Matches on ${date}:
 ${matchList(todays, "No matches scheduled.", opts)}`;
+  if (degraded) text += "\n\n(Live scores unavailable \u2014 showing the bundled schedule.)";
   const marketSignals = await reliableMarketData(args, todays);
   return {
     text: withDisclaimer(text, source),
@@ -3611,7 +3712,7 @@ async function toolGetLive(args = {}) {
   const adapter = resolveAdapter(args);
   const { matches, degraded, source } = await getLiveMatches(adapter);
   const opts = fmtOpts(args);
-  const text = `Live now:
+  const text = degraded ? "Live scores unavailable right now \u2014 could not reach the data provider." : `Live now:
 ${matchList(matches, "No matches in play right now.", opts)}`;
   return {
     text: withDisclaimer(text, source),
@@ -3631,8 +3732,9 @@ async function toolGetMatch(args) {
     if (s && isReliableMarketSignal(s, { now })) marketSignal = s;
   }
   const base = matchLine(match, opts);
-  const text = marketSignal ? `${base}
+  let text = marketSignal ? `${base}
 ${marketBlock(marketSignal, match).join("\n")}` : base;
+  if (degraded) text += "\n\n(Live state unavailable \u2014 showing the scheduled fixture.)";
   return {
     text: withDisclaimer(text, liveSource),
     data: {
@@ -3644,34 +3746,34 @@ ${marketBlock(marketSignal, match).join("\n")}` : base;
   };
 }
 async function toolGetStandings(args) {
-  const { matches, degraded, source } = await getMatchesForDate(
-    resolveAdapter(args),
-    localDate((/* @__PURE__ */ new Date()).toISOString(), args.tz)
-  );
-  const known = groups(matches);
-  if (args.group) {
-    const g = args.group.toUpperCase();
-    if (!known.includes(g)) {
-      return {
-        text: withDisclaimer(`No group "${g}". Groups are ${known.join(", ")}.`, source),
-        data: { degraded, source: source ?? null, tables: null }
-      };
-    }
+  const { tables, degraded, source } = await getStandings(resolveAdapter(args), args.group);
+  const shaped = tables.map((tb) => ({ group: tb.group, standings: tb.rows }));
+  if (shaped.length === 0) {
+    const g = args.group?.toUpperCase();
+    const msg = g ? `No group "${g}". Groups are A\u2013L.` : "No standings available.";
+    return {
+      text: withDisclaimer(degraded ? `${msg} (Live standings unavailable.)` : msg, source),
+      data: { degraded, source: source ?? null, tables: args.group ? null : [] }
+    };
   }
-  const wanted = args.group ? [args.group.toUpperCase()] : known;
-  const tables = wanted.map((g) => ({
-    group: g,
-    standings: computeStandings(fixturesByGroup(g, matches))
-  }));
-  const text = tables.map((t) => standingsTable(t.group, t.standings)).join("\n\n");
+  let text = shaped.map((t) => standingsTable(t.group, t.standings)).join("\n\n");
+  if (degraded) text += "\n\n(Live standings unavailable \u2014 showing the group roster.)";
   return {
-    text: withDisclaimer(text || `No group found.`, source),
-    data: { degraded, source: source ?? null, tables: args.group ? tables[0] ?? null : tables }
+    text: withDisclaimer(text, source),
+    data: { degraded, source: source ?? null, tables: args.group ? shaped[0] ?? null : shaped }
   };
 }
+async function standingsResourceText(group, adapter) {
+  const g = group.toUpperCase();
+  const { tables, degraded, source } = await getStandings(adapter, g);
+  const tb = tables[0];
+  let text = tb ? standingsTable(tb.group, tb.rows) : `No group ${g}.`;
+  if (degraded && tb) text += "\n\n(Live standings unavailable \u2014 showing the group roster.)";
+  return withDisclaimer(text, source);
+}
 async function toolGetNextFixture(args) {
   const code = args.team.toUpperCase();
-  const fixture = nextFixtureForTeam(code);
+  const fixture = nextFixtureForTeam(code, { from: args.now ?? /* @__PURE__ */ new Date() });
   if (!fixture) {
     return {
       text: withDisclaimer(`No upcoming fixture found for ${code}.`),
@@ -3772,6 +3874,7 @@ function shareResult(kind, target, team, input, options) {
       target,
       ...team ? { team } : {},
       source: input.source ?? null,
+      degraded: input.degraded ?? false,
       informationalOnly: true,
       style: options.style ?? "social",
       snippet,
@@ -3789,7 +3892,7 @@ async function toolGetShareSnippet(args) {
   const options = shareOptions(args);
   const signalsFor = (ms) => args.includeMarkets === false ? Promise.resolve(/* @__PURE__ */ new Map()) : reliableSignalMap(args, ms);
   if (args.live) {
-    const { matches, source: source2 } = await getLiveMatches(resolveAdapter(args));
+    const { matches, degraded: degraded2, source: source2 } = await getLiveMatches(resolveAdapter(args));
     return shareResult(
       "live",
       "live",
@@ -3798,7 +3901,9 @@ async function toolGetShareSnippet(args) {
         title: "Live match pulse",
         matches,
         source: source2,
-        emptyNote: "No matches in play right now.",
+        degraded: degraded2,
+        // Feed down ⇒ don't let an empty card read as "nothing is on".
+        emptyNote: degraded2 ? "Live scores unavailable right now \u2014 couldn't reach the data provider." : "No matches in play right now.",
         installLine: "npx @claudinho/cli live",
         tz: args.tz,
         locale: args.lang
@@ -3806,8 +3911,37 @@ async function toolGetShareSnippet(args) {
       { ...options, includeMarkets: false }
     );
   }
+  if (args.group) {
+    const group = args.group.toUpperCase();
+    const { tables, degraded: degraded2, source: source2 } = await getStandings(resolveAdapter(args), group);
+    const snippet = formatShareTable(
+      {
+        tables,
+        // Degraded ⇒ static roster, no live provider: don't attribute one, and
+        // surface the not-live notice (the card gets pasted publicly).
+        source: degraded2 ? void 0 : source2,
+        installLine: `npx @claudinho/cli table ${group}`,
+        emptyNote: `No group ${group}.`,
+        degraded: degraded2
+      },
+      options
+    );
+    return {
+      text: snippet,
+      data: {
+        kind: "table",
+        target: "table",
+        group,
+        source: degraded2 ? null : source2 ?? null,
+        degraded: degraded2,
+        informationalOnly: true,
+        snippet,
+        tables: tables.map((tb) => ({ group: tb.group, standings: tb.rows }))
+      }
+    };
+  }
   if (args.matchId) {
-    const { match, source: source2 } = await getMatchById(resolveAdapter(args), args.matchId);
+    const { match, degraded: degraded2, source: source2 } = await getMatchById(resolveAdapter(args), args.matchId);
     const matches = match ? [match] : [];
     return shareResult(
       "match",
@@ -3818,6 +3952,7 @@ async function toolGetShareSnippet(args) {
         matches,
         marketSignals: await signalsFor(matches),
         source: source2,
+        degraded: degraded2,
         emptyNote: `No match found with id ${args.matchId}.`,
         installLine: `npx @claudinho/cli match ${args.matchId}`,
         tz: args.tz,
@@ -3828,7 +3963,7 @@ async function toolGetShareSnippet(args) {
   }
   if (args.team) {
     const code = args.team.toUpperCase();
-    const fixture = nextFixtureForTeam(code);
+    const fixture = nextFixtureForTeam(code, { from: args.now ?? /* @__PURE__ */ new Date() });
     const matches = fixture ? [fixture] : [];
     const teamName = fixture ? fixture.home.code === code ? fixture.home.name : fixture.away.name : code;
     return shareResult(
@@ -3848,7 +3983,7 @@ async function toolGetShareSnippet(args) {
     );
   }
   const date = args.date ?? localDate((/* @__PURE__ */ new Date()).toISOString(), args.tz);
-  const { matches: all, source } = await getMatchesForDate(resolveAdapter(args), date);
+  const { matches: all, degraded, source } = await getMatchesForDate(resolveAdapter(args), date);
   const todays = fixturesByDate(date, all, args.tz);
   const human = formatDate(`${date}T12:00:00.000Z`, { tz: args.tz, locale: args.lang });
   return shareResult(
@@ -3860,6 +3995,7 @@ async function toolGetShareSnippet(args) {
       matches: todays,
       marketSignals: await signalsFor(todays),
       source,
+      degraded,
       emptyNote: `No matches scheduled for ${human}.`,
       installLine: "npx @claudinho/cli today",
       tz: args.tz,
@@ -3871,7 +4007,7 @@ async function toolGetShareSnippet(args) {
 
 // src/server.ts
 var SERVER_NAME = "claudinho";
-var SERVER_VERSION = "0.4.3";
+var SERVER_VERSION = "0.5.1";
 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.
@@ -3905,7 +4041,7 @@ function buildServer() {
     "get_today",
     {
       title: "Today's matches",
-      description: "Fixtures for a given date (default: today), with live scores overlaid.",
+      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.",
       inputSchema: {
         date: dateArg.optional().describe("Date as YYYY-MM-DD (default: today)"),
         ...commonArgs
@@ -3919,7 +4055,7 @@ function buildServer() {
     "get_live",
     {
       title: "Live matches",
-      description: "Matches currently in play, with score and minute.",
+      description: "Only matches in play right now \u2014 each with current score and minute (empty when nothing is live). Use during matches for in-play state; for a full day's schedule including upcoming and finished, use get_today. tz/lang/flavor affect formatting only.",
       inputSchema: { ...commonArgs },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -3929,7 +4065,7 @@ function buildServer() {
     "get_match",
     {
       title: "Match detail",
-      description: "A single match by its id, with live state if available.",
+      description: "One match by its id, with live score/minute overlaid when it's in play. Get the id from get_today or get_live; to find a team's match without an id, use get_next_fixture. tz/lang/flavor affect formatting.",
       inputSchema: { id: z.string().describe("Match id"), ...commonArgs },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -3939,7 +4075,7 @@ function buildServer() {
     "get_standings",
     {
       title: "Group standings",
-      description: "Group table(s). Pass a group letter A\u2013L, or omit for all groups.",
+      description: "Live cumulative group standings \u2014 pass a group letter A\u2013L, or omit for all 12. Returns ranked rows (team, played, W/D/L, goal difference, points). Use get_today for fixtures/scores and get_next_fixture for one team. Falls back to a roster at zero (flagged degraded) if live standings are unavailable.",
       inputSchema: {
         group: groupArg.optional().describe("Group letter A\u2013L (omit for all)"),
         ...commonArgs
@@ -3981,10 +4117,11 @@ function buildServer() {
     "get_share_snippet",
     {
       title: "Shareable match snippet",
-      description: "A polished, copy-pasteable match card (plain text) for a match (matchId), a team's next fixture (team), a date (default: today), or live matches (live: true). Returns the ready-to-paste snippet plus structured data \u2014 hand the snippet text to the user verbatim. No links; it carries a non-affiliation disclaimer, and any market line stays informational only.",
+      description: `A polished, copy-pasteable card (plain text) for a match (matchId), a team's next fixture (team), a group's standings table (group, e.g. "A"), a date (default: today), or live matches (live: true). Returns the ready-to-paste snippet plus structured data \u2014 hand the snippet text to the user verbatim. No links; it carries a non-affiliation disclaimer, and any market line stays informational only.`,
       inputSchema: {
         matchId: z.string().optional().describe("Match id (most specific)"),
         team: teamArg.optional().describe("3-letter team code for that team's next fixture, e.g. MEX"),
+        group: groupArg.optional().describe("Group letter A\u2013L for a standings card, e.g. A"),
         date: dateArg.optional().describe("Date as YYYY-MM-DD (default: today)"),
         live: z.boolean().optional().describe("Snapshot of matches in play right now"),
         style: z.enum(["social", "compact"]).optional().describe("social (default, full card) or compact (one line per match)"),
@@ -4003,13 +4140,12 @@ function buildServer() {
     new ResourceTemplate("standings://{group}", { list: void 0 }),
     {
       title: "Group standings",
-      description: "Static group table for a group letter A\u2013L.",
+      description: "Live group table for a group letter A\u2013L.",
       mimeType: "text/plain"
     },
     async (uri, variables) => {
-      const group = String(variables.group ?? "").toUpperCase();
-      const rows = computeStandings(fixturesByGroup(group));
-      const text = rows.length ? standingsTable(group, rows) : `No group ${group}.`;
+      const group = String(variables.group ?? "");
+      const text = await standingsResourceText(group, makeAdapter());
       return { contents: [{ uri: uri.href, mimeType: "text/plain", text }] };
     }
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudinho/mcp",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "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",
@@ -54,7 +54,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.0",
-    "@claudinho/core": "0.4.3"
+    "@claudinho/core": "0.5.1"
   },
   "scripts": {
     "build": "tsup",