@claudinho/mcp 0.4.1 → 0.4.3

package/README.md

@@ -1,8 +1,8 @@
 # @claudinho/mcp ⚽
 
-**An MCP server for the 2026 men's football tournament.** Ask your agent about
-live scores, fixtures, group standings, and prediction-market odds — in Claude
-Code, Cursor, Codex, and any other MCP client.
+**An MCP server for the 2026 men's football tournament.** Ask your agent about live
+scores, fixtures, group standings, and the prediction-market read — in Claude Code,
+Cursor, Codex, Claude Desktop, Windsurf, Zed, VS Code, or any MCP client (stdio).
 
 > ⚠️ **Not affiliated with, endorsed by, or connected to FIFA or Anthropic.**
 > Claudinho is an independent, open-source fan project. Factual match data with
@@ -15,29 +15,18 @@ Code, Cursor, Codex, and any other MCP client.
 claude mcp add claudinho -- npx -y @claudinho/mcp
 ```
 
-**Cursor** — add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
-```json
-{ "mcpServers": { "claudinho": { "command": "npx", "args": ["-y", "@claudinho/mcp"] } } }
-```
-
-**Codex CLI** — add to `~/.codex/config.toml`:
-```toml
-[mcp_servers.claudinho]
-command = "npx"
-args = ["-y", "@claudinho/mcp"]
+**Codex CLI**
+```bash
+codex mcp add claudinho -- npx -y @claudinho/mcp
 ```
-(or `codex mcp add claudinho -- npx -y @claudinho/mcp`)
 
-**Claude Desktop** — edit `claude_desktop_config.json` (Settings → Developer →
-Edit Config), then restart Claude Desktop:
+**Cursor / Claude Desktop / Windsurf / Zed / VS Code** — standard stdio config:
 ```json
 { "mcpServers": { "claudinho": { "command": "npx", "args": ["-y", "@claudinho/mcp"] } } }
 ```
-Config location: macOS `~/Library/Application Support/Claude/claude_desktop_config.json`,
-Windows `%APPDATA%\Claude\claude_desktop_config.json`.
-
-Transport is stdio, so the same package works in Windsurf, Zed, VS Code, and
-any other MCP client with no changes.
+Cursor: `.cursor/mcp.json` (or `~/.cursor/mcp.json`). Claude Desktop: Settings →
+Developer → Edit Config, then restart. Codex config file: `~/.codex/config.toml`
+(`[mcp_servers.claudinho]`, `command = "npx"`, `args = ["-y", "@claudinho/mcp"]`).
 
 ## Tools
 
@@ -47,67 +36,41 @@ any other MCP client with no changes.
 | `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_next_fixture` | a team's next match (3-letter code, e.g. `MEX`) |
-| `get_market_signal` | read-only prediction-market odds for a match, a team's next fixture, or a date — informational only |
-| `get_share_snippet` | a copy-pasteable match-card snippet for a match, a team's next fixture, a date, or live — plain text, ready to paste |
-
-All tools are **read-only** (annotated `readOnlyHint`) and accept optional
-`tz` (IANA timezone), `lang` (`en`/`es`/`pt`/`fr`), and `flavor`
-(`off`/`subtle`/`full`) arguments. Each response includes both human-readable
-text and structured JSON.
-
-`get_today` and `get_match` also include reliable prediction-market context when a
-market is available. Match→market event slugs are derived automatically, so no
-mapping is needed. Market data is **read-only and informational only — not betting
-advice** (market-implied percentages with attribution, never links or trade
-calls), sourced from Polymarket public data and shown only when a market maps
-cleanly to the result. Disable it with `CLAUDINHO_MARKETS=off`; set
-`CLAUDINHO_MARKETS_SOURCE=fake` (in the server `env`) for a network-free synthetic
-preview.
-
-`get_share_snippet` returns a polished, **copy-pasteable** match card (the same
-artifact as the CLI's `claudinho share`) for a match, a team's next fixture, a
-date, or live matches — plain text, no links, with the non-affiliation disclaimer
-baked in. Hand the returned `snippet` to the user as-is. `style` picks `social`
-(default) or `compact`; market lines (when reliable) stay **informational only**.
-
-## Resources & prompts
-
-- Resources: `standings://{group}` (e.g. `standings://A`), `fixtures://{date}` (UTC date, e.g. `fixtures://2026-06-11`)
-- Prompts: `tournament_today`, `my_team`
+| `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 |
 
-## Commentary flair
+All tools are **read-only** (`readOnlyHint`) and accept optional `tz`, `lang`
+(`en`/`es`/`pt`/`fr`), and `flavor` (`off`/`subtle`/`full`). Every response carries
+human-readable text **and** structured JSON.
 
-By default the server adds a light, localized football-commentary voice: each
-match line in the text ends with a short genre-style exclamation (`— ¡GOOOOL!`),
-and the server instructions nudge the model to narrate scores with matching
-energy. The phrases are generic — no real commentator is quoted or impersonated —
-and they never touch the structured JSON, so the facts stay clean.
+Resources: `standings://{group}`, `fixtures://{date}`. Prompts: `tournament_today`,
+and `my_team` (give it a 3-letter team code; combines next fixture, standings, and
+the prediction-market read).
 
-Control it with `CLAUDINHO_FLAVOR` (`off` | `subtle` | `full`, default `full`),
-or per call via the `flavor` tool argument. In Claude Code, add it to the `env`
-block of your server entry:
+## Market signals
 
-```json
-{ "mcpServers": { "claudinho": {
-  "command": "npx", "args": ["-y", "@claudinho/mcp"],
-  "env": { "CLAUDINHO_FLAVOR": "subtle" }
-} } }
-```
+Market signals are pre-match and in-play reads — finished matches never show one.
+`get_today` / `get_match` include a short market line when a reliable market exists
+(slugs are auto-derived per fixture; matching fails closed). **Read-only and
+informational only — not betting advice:** market-implied percentages with Polymarket
+attribution, never links or trade calls. Disable with `CLAUDINHO_MARKETS=off`; set
+`CLAUDINHO_MARKETS_SOURCE=fake` in the server `env` for a network-free, clearly
+labeled synthetic preview.
 
-## Other competitions
+## Commentary flair
 
-By default the server follows the 2026 World Cup. Set the `CLAUDINHO_COMPETITION`
-env var (e.g. `fifa.friendly`) to point the live tools at another
-competition — useful for testing before the tournament. In Claude Code, add it
-to the `env` block of your MCP server entry.
+Match lines in the text end with a short, localized, genre-style exclamation
+(`— ¡GOOOOL!`) — generic energy, no real commentator quoted or impersonated, never
+in the structured JSON. Control with `CLAUDINHO_FLAVOR` (`off`|`subtle`|`full`,
+default `full`) in the server `env`, or per call via the `flavor` argument.
 
 ## How it works
 
-The fixture list ships bundled in the package; only live state hits the network —
-live scores from **ESPN's** public scoreboard (a swappable provider, attributed
-in the `source` field and text) and market odds from Polymarket. The server writes
-nothing to stdout except the MCP protocol; diagnostics go to stderr.
+All 104 fixtures ship bundled in the package; only live state hits the network —
+live scores from **ESPN's** public scoreboard (swappable provider, attributed in
+output), market signals from Polymarket. Stdout carries only the MCP protocol;
+diagnostics go to stderr.
 
 ## License
 

package/dist/index.js

@@ -2614,6 +2614,7 @@ function nextFixtureForTeam(code, opts = {}) {
     (m) => new Date(m.kickoff).getTime() >= from.getTime()
   );
 }
+var LIVE_WINDOW_MS = 140 * 6e4;
 function groups(fixtures = SCHEDULE) {
   const set = /* @__PURE__ */ new Set();
   for (const m of fixtures) if (m.group) set.add(m.group);
@@ -2871,6 +2872,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 EXTRA_TIME_SLACK_MS = 60 * 6e4;
+async function marketFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Date()) {
+  const nowMs = now.getTime();
+  const candidate = fixturesByTeam(code).find((m) => {
+    const k = Date.parse(m.kickoff);
+    return nowMs >= k && nowMs <= k + LIVE_WINDOW_MS + EXTRA_TIME_SLACK_MS;
+  });
+  if (candidate) {
+    const r = await getMatchById(adapter, candidate.id);
+    const m = r.match ?? candidate;
+    if (!isFinished(m.status)) return { ...r, match: m };
+  }
+  const next = nextFixtureForTeam(code, { from: now });
+  return { match: next, degraded: false };
+}
+async function getMatchById(adapter, id) {
+  const base = allFixtures().find((m) => m.id === id);
+  if (!base) return { match: void 0, degraded: false };
+  const day = base.kickoff.slice(0, 10);
+  try {
+    const live = adapter.fetchWindow ? await adapter.fetchWindow(shiftUtcDate(day, -1), shiftUtcDate(day, 1)) : await adapter.fetchByDate(day);
+    const hit = live.find((m) => m.id === id);
+    return { match: hit ?? base, degraded: false, source: hit ? adapter.name : void 0 };
+  } catch {
+    return { match: base, degraded: true };
+  }
+}
 async function getLiveMatches(adapter) {
   try {
     return { matches: await adapter.fetchLive(), degraded: false, source: adapter.name };
@@ -2879,6 +2907,12 @@ async function getLiveMatches(adapter) {
   }
 }
 var DEFAULT_MAX_AGE_MS = 15 * 6e4;
+function marketRelevant(match, now = /* @__PURE__ */ new Date()) {
+  if (isLive(match.status)) return true;
+  if (isFinished(match.status)) return false;
+  const k = Date.parse(match.kickoff);
+  return !Number.isFinite(k) || now.getTime() <= k + LIVE_WINDOW_MS;
+}
 function normalizeOutcomes(outcomes) {
   const sum = outcomes.reduce(
     (s, o) => s + (Number.isFinite(o.probability) && o.probability > 0 ? o.probability : 0),
@@ -3454,13 +3488,19 @@ function resolveMarketProvider(args) {
 function marketDisplayable(sig) {
   return !sig.ambiguous && sig.favorite != null && hasSaneDistribution(sig.outcomes);
 }
-function marketHeader(m) {
-  return `${m.home.flag} ${m.home.name} vs ${m.away.name} ${m.away.flag}`;
+function marketHeader(m, args) {
+  const when = formatDate(m.kickoff, { tz: args.tz, locale: args.lang });
+  return `${m.home.flag} ${m.home.name} vs ${m.away.name} ${m.away.flag} (${when})`;
 }
-function marketText(m, sig) {
-  return `${marketHeader(m)}
+function marketText(m, sig, args) {
+  return `${marketHeader(m, args)}
 ${marketBlock(sig, m).join("\n")}`;
 }
+function noSignalText(m, args, now) {
+  if (marketRelevant(m, now)) return `No reliable market signal for ${marketHeader(m, args)}.`;
+  const verb = isFinished(m.status) ? "has finished" : "appears to have finished";
+  return `${marketHeader(m, args)} ${verb} \u2014 market signals are pre-match and in-play reads.`;
+}
 function marketData(sig) {
   return {
     matchId: sig.matchId,
@@ -3521,10 +3561,12 @@ async function cachedMarketSignals(args, matches) {
 }
 async function reliableMarketData(args, matches) {
   if (!marketsEnabled()) return void 0;
-  const signals = await cachedMarketSignals(args, matches);
-  const now = /* @__PURE__ */ new Date();
+  const now = args.now ?? /* @__PURE__ */ new Date();
+  const relevant = matches.filter((m) => marketRelevant(m, now));
+  if (relevant.length === 0) return void 0;
+  const signals = await cachedMarketSignals(args, relevant);
   const out = {};
-  for (const m of matches) {
+  for (const m of relevant) {
     const s = signals.get(m.id);
     if (s && isReliableMarketSignal(s, { now })) out[m.id] = marketData(s);
   }
@@ -3577,27 +3619,16 @@ ${matchList(matches, "No matches in play right now.", opts)}`;
   };
 }
 async function toolGetMatch(args) {
-  let match = allFixtures().find((m) => m.id === args.id);
-  let degraded = false;
-  let liveSource;
-  if (match) {
-    try {
-      const adapter = resolveAdapter(args);
-      const live = await adapter.fetchByDate(match.kickoff.slice(0, 10));
-      match = live.find((m) => m.id === args.id) ?? match;
-      liveSource = adapter.name;
-    } catch {
-      degraded = true;
-    }
-  }
+  const { match, degraded, source: liveSource } = await getMatchById(resolveAdapter(args), args.id);
   if (!match) {
     return { text: withDisclaimer(`No match found with id ${args.id}.`), data: { match: null } };
   }
   const opts = fmtOpts(args);
+  const now = args.now ?? /* @__PURE__ */ new Date();
   let marketSignal;
-  if (marketsEnabled()) {
+  if (marketsEnabled() && marketRelevant(match, now)) {
     const s = (await cachedMarketSignals(args, [match])).get(match.id);
-    if (s && isReliableMarketSignal(s, { now: /* @__PURE__ */ new Date() })) marketSignal = s;
+    if (s && isReliableMarketSignal(s, { now })) marketSignal = s;
   }
   const base = matchLine(match, opts);
   const text = marketSignal ? `${base}
@@ -3656,11 +3687,13 @@ ${matchLine(fixture, opts)}`),
 }
 async function toolGetMarketSignal(args) {
   const provider = resolveMarketProvider(args);
+  const now = args.now ?? /* @__PURE__ */ new Date();
   if (args.matchId) {
-    const match = allFixtures().find((m) => m.id === args.matchId);
-    const sig = match ? await getMarketSignal(provider, match) : void 0;
+    const { match } = await getMatchById(resolveAdapter(args), args.matchId);
+    const relevant = match ? marketRelevant(match, now) : false;
+    const sig = match && relevant ? await getMarketSignal(provider, match) : void 0;
     const shown2 = match && sig && marketDisplayable(sig) ? sig : void 0;
-    const text2 = !match ? `No match found with id ${args.matchId}.` : shown2 ? marketText(match, shown2) : `No reliable market signal for ${marketHeader(match)}.`;
+    const text2 = !match ? `No match found with id ${args.matchId}.` : shown2 ? marketText(match, shown2, args) : noSignalText(match, args, now);
     return {
       text: withDisclaimer(text2),
       data: {
@@ -3672,10 +3705,11 @@ async function toolGetMarketSignal(args) {
   }
   if (args.team) {
     const code = args.team.toUpperCase();
-    const fixture = nextFixtureForTeam(code);
-    const sig = fixture ? await getMarketSignal(provider, fixture) : void 0;
+    const { match: fixture } = await marketFixtureForTeam(resolveAdapter(args), code, now);
+    const relevant = fixture ? marketRelevant(fixture, now) : false;
+    const sig = fixture && relevant ? await getMarketSignal(provider, fixture) : void 0;
     const shown2 = fixture && sig && marketDisplayable(sig) ? sig : void 0;
-    const text2 = !fixture ? `No upcoming fixture found for ${code}.` : shown2 ? marketText(fixture, shown2) : `No reliable market signal for ${code}'s next fixture.`;
+    const text2 = !fixture ? `No upcoming fixture found for ${code}.` : shown2 ? marketText(fixture, shown2, args) : noSignalText(fixture, args, now);
     return {
       text: withDisclaimer(text2),
       data: {
@@ -3686,15 +3720,15 @@ async function toolGetMarketSignal(args) {
       }
     };
   }
-  const date = args.date ?? localDate((/* @__PURE__ */ new Date()).toISOString(), args.tz);
+  const date = args.date ?? localDate(now.toISOString(), args.tz);
   const { matches } = await getMatchesForDate(resolveAdapter(args), date);
-  const todays = fixturesByDate(date, matches, args.tz);
+  const todays = fixturesByDate(date, matches, args.tz).filter((m) => marketRelevant(m, now));
   const { signals } = await getMarketSignals(provider, todays, MARKETS_TOOL_OPTS);
   const shown = todays.map((m) => ({ match: m, signal: signals.get(m.id) })).filter(
     (r) => !!r.signal && marketDisplayable(r.signal)
   );
   const text = shown.length ? `Market signals on ${date}:
-${shown.map(({ match, signal }) => marketText(match, signal)).join("\n\n")}` : `No reliable market signals on ${date}.`;
+${shown.map(({ match, signal }) => marketText(match, signal, args)).join("\n\n")}` : `No reliable market signals on ${date}.`;
   return {
     text: withDisclaimer(text),
     data: {
@@ -3706,10 +3740,12 @@ ${shown.map(({ match, signal }) => marketText(match, signal)).join("\n\n")}` : `
 }
 async function reliableSignalMap(args, matches) {
   if (!marketsEnabled()) return /* @__PURE__ */ new Map();
-  const signals = await cachedMarketSignals(args, matches);
-  const now = /* @__PURE__ */ new Date();
+  const now = args.now ?? /* @__PURE__ */ new Date();
+  const relevant = matches.filter((m) => marketRelevant(m, now));
+  if (relevant.length === 0) return /* @__PURE__ */ new Map();
+  const signals = await cachedMarketSignals(args, relevant);
   const out = /* @__PURE__ */ new Map();
-  for (const m of matches) {
+  for (const m of relevant) {
     const s = signals.get(m.id);
     if (s && isReliableMarketSignal(s, { now }) && marketDisplayable(s)) out.set(m.id, s);
   }
@@ -3771,17 +3807,7 @@ async function toolGetShareSnippet(args) {
     );
   }
   if (args.matchId) {
-    let match = allFixtures().find((m) => m.id === args.matchId);
-    let source2;
-    if (match) {
-      try {
-        const adapter = resolveAdapter(args);
-        const live = await adapter.fetchByDate(match.kickoff.slice(0, 10));
-        match = live.find((m) => m.id === args.matchId) ?? match;
-        source2 = adapter.name;
-      } catch {
-      }
-    }
+    const { match, source: source2 } = await getMatchById(resolveAdapter(args), args.matchId);
     const matches = match ? [match] : [];
     return shareResult(
       "match",
@@ -3845,12 +3871,12 @@ async function toolGetShareSnippet(args) {
 
 // src/server.ts
 var SERVER_NAME = "claudinho";
-var SERVER_VERSION = "0.4.1";
+var SERVER_VERSION = "0.4.3";
 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), and get_standings for group tables.
-Use get_market_signal for read-only prediction-market odds (a match, a team's 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_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}`;
 var dateArg = z.string().refine(isValidDate, "must be a real calendar date in YYYY-MM-DD form");
@@ -3926,7 +3952,7 @@ function buildServer() {
     "get_next_fixture",
     {
       title: "Next fixture for a team",
-      description: "A team's next scheduled match. Use a 3-letter code, e.g. MEX, BRA, USA.",
+      description: "A team's next scheduled match. Use a 3-letter code, e.g. MEX, BRA, USA. Instant and offline \u2014 answered from the bundled schedule, no network.",
       inputSchema: { team: teamArg.describe("3-letter team code, e.g. MEX"), ...commonArgs },
       // Read-only and served entirely from the bundled static schedule.
       annotations: { readOnlyHint: true, openWorldHint: false }
@@ -3937,10 +3963,12 @@ function buildServer() {
     "get_market_signal",
     {
       title: "Prediction-market signal",
-      description: "Read-only prediction-market odds for a match (by id), a team's next fixture, or a date (default: today). Returns market-implied percentages with attribution. Informational only \u2014 relay the numbers factually; do not add betting, trading, or 'value' advice, and do not invent links.",
+      description: "Read-only prediction-market signals for a match (by id), a team's current-or-next fixture, or a date (default: today). Returns market-implied percentages with attribution. Shown only before and during a match \u2014 finished matches have no market read. Informational only \u2014 relay the numbers factually; do not add betting, trading, or 'value' advice, and do not invent links.",
       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"),
+        team: teamArg.optional().describe(
+          "3-letter team code, e.g. MEX \u2014 resolves to the team's in-play match when one is live, else their next fixture"
+        ),
         date: dateArg.optional().describe("Date as YYYY-MM-DD (default: today) for all that day's signals"),
         ...commonArgs
       },
@@ -4032,7 +4060,7 @@ function buildServer() {
           role: "user",
           content: {
             type: "text",
-            text: `Using get_next_fixture, get_standings, and get_market_signal, tell me about ${team}'s next match in the 2026 tournament, their current group standing, and what prediction markets currently say about that match. Treat the market percentages as informational context only \u2014 relay them factually, never as betting or trading advice.`
+            text: `Using get_next_fixture, get_standings, and get_market_signal, tell me about ${team}'s next match in the 2026 tournament, their current group standing, and what prediction markets currently say about that match. Always state each fixture's date so a market read is never mistaken for a different match. Treat the market percentages as informational context only \u2014 relay them factually, never as betting or trading advice.`
           }
         }
       ]

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@claudinho/mcp",
-  "version": "0.4.1",
-  "description": "Claudinho MCP server — ask your agent about the 2026 men's football tournament: live scores, fixtures, standings, prediction-market odds. Not affiliated with FIFA or Anthropic.",
+  "version": "0.4.3",
+  "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",
   "license": "MIT",
   "author": "Arturo Garrido",
@@ -30,12 +31,18 @@
   ],
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
+    "claude-code",
+    "cursor",
+    "world-cup",
+    "world-cup-2026",
     "football",
     "soccer",
-    "world-cup",
-    "2026",
     "live-scores",
+    "fixtures",
+    "standings",
+    "2026",
     "vibinglavidaloca"
   ],
   "dependencies": {
@@ -47,7 +54,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.0",
-    "@claudinho/core": "0.4.1"
+    "@claudinho/core": "0.4.3"
   },
   "scripts": {
     "build": "tsup",