@claudinho/mcp 0.2.0 → 0.4.0

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, and group standings — in Claude Code, Cursor, Codex, and
-any other MCP client.
+live scores, fixtures, group standings, and prediction-market odds — in Claude
+Code, Cursor, Codex, and any other MCP client.
 
 > ⚠️ **Not affiliated with, endorsed by, or connected to FIFA or Anthropic.**
 > Claudinho is an independent, open-source fan project. Factual match data with
@@ -48,12 +48,29 @@ any other MCP client with no changes.
 | `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`)
@@ -87,9 +104,10 @@ to the `env` block of your MCP server entry.
 
 ## How it works
 
-The fixture list ships bundled in the package; only live state hits the network
-(via a swappable data provider). The server writes nothing to stdout
-except the MCP protocol; diagnostics go to stderr.
+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.
 
 ## License
 

package/dist/index.js

@@ -315,6 +315,25 @@ function formatKickoff(iso, opts = {}) {
     timeZone: tz
   }).format(new Date(iso));
 }
+function formatDate(iso, opts = {}) {
+  const tz = resolveTz(opts.tz);
+  const locale = safeLocale(opts.locale);
+  return new Intl.DateTimeFormat(locale, {
+    month: "short",
+    day: "numeric",
+    timeZone: tz
+  }).format(new Date(iso));
+}
+function formatTime(iso, opts = {}) {
+  const tz = resolveTz(opts.tz);
+  const locale = safeLocale(opts.locale);
+  return new Intl.DateTimeFormat(locale, {
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+    timeZone: tz
+  }).format(new Date(iso));
+}
 function countdown(iso, from = /* @__PURE__ */ new Date()) {
   const ms = new Date(iso).getTime() - from.getTime();
   if (ms <= 0) return "now";
@@ -335,6 +354,9 @@ function localDate(iso, tz) {
     timeZone: zone
   }).format(new Date(iso));
 }
+function isLive(status) {
+  return status === "LIVE" || status === "HT";
+}
 function isFinished(status) {
   return status === "FT";
 }
@@ -2831,12 +2853,16 @@ function mergeLive(base, live) {
   for (const m of live) byId.set(m.id, m);
   return [...byId.values()];
 }
+function liveSourceLabel(source) {
+  const known = { espn: "ESPN" };
+  return known[source] ?? source.charAt(0).toUpperCase() + source.slice(1);
+}
 async function getMatchesForDate(adapter, dateISO) {
   const base = allFixtures();
   const day = dateISO.slice(0, 10);
   try {
     const live = adapter.fetchWindow ? await adapter.fetchWindow(shiftUtcDate(day, -1), shiftUtcDate(day, 1)) : await adapter.fetchByDate(day);
-    return { matches: mergeLive(base, live), degraded: false };
+    return { matches: mergeLive(base, live), degraded: false, source: adapter.name };
   } catch {
     return { matches: base, degraded: true };
   }
@@ -2847,11 +2873,513 @@ function shiftUtcDate(dateISO, days) {
 }
 async function getLiveMatches(adapter) {
   try {
-    return { matches: await adapter.fetchLive(), degraded: false };
+    return { matches: await adapter.fetchLive(), degraded: false, source: adapter.name };
   } catch {
     return { matches: [], degraded: true };
   }
 }
+var DEFAULT_MAX_AGE_MS = 15 * 6e4;
+function normalizeOutcomes(outcomes) {
+  const sum = outcomes.reduce(
+    (s, o) => s + (Number.isFinite(o.probability) && o.probability > 0 ? o.probability : 0),
+    0
+  );
+  if (sum <= 0) return outcomes.map((o) => ({ ...o, probability: 0 }));
+  return outcomes.map((o) => ({
+    ...o,
+    probability: Number.isFinite(o.probability) && o.probability > 0 ? o.probability / sum : 0
+  }));
+}
+function favoriteStrength(probability) {
+  if (probability >= 0.65) return "clear";
+  if (probability >= 0.52) return "slight";
+  return "close";
+}
+function deriveFavorite(outcomes) {
+  let top;
+  for (const o of outcomes) {
+    if (o.kind === "other") continue;
+    if (!top || o.probability > top.probability) top = o;
+  }
+  if (!top || top.probability <= 0 || top.kind === "other") return void 0;
+  return {
+    kind: top.kind,
+    teamCode: top.teamCode,
+    probability: top.probability,
+    strength: favoriteStrength(top.probability)
+  };
+}
+function mapsCleanly(match, outcomes) {
+  if (outcomes.some((o) => o.kind === "other")) return false;
+  const home = outcomes.find((o) => o.kind === "home");
+  const away = outcomes.find((o) => o.kind === "away");
+  const draw = outcomes.find((o) => o.kind === "draw");
+  if (!home || !away) return false;
+  if (home.teamCode && home.teamCode.toUpperCase() !== match.home.code.toUpperCase()) {
+    return false;
+  }
+  if (away.teamCode && away.teamCode.toUpperCase() !== match.away.code.toUpperCase()) {
+    return false;
+  }
+  if (match.stage === "GROUP" && !draw) return false;
+  return true;
+}
+function hasSaneDistribution(outcomes) {
+  const priced = outcomes.filter((o) => Number.isFinite(o.probability) && o.probability > 0);
+  if (priced.length < 2) return false;
+  const sum = priced.reduce((s, o) => s + o.probability, 0);
+  return sum > 0.97 && sum < 1.03;
+}
+function isStaleSignal(signal, options = {}) {
+  const maxAge = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+  const asOf = Date.parse(signal.asOf);
+  if (!Number.isFinite(asOf)) return true;
+  const now = (options.now ?? /* @__PURE__ */ new Date()).getTime();
+  return now - asOf > maxAge;
+}
+function isReliableMarketSignal(signal, options = {}) {
+  if (options.includeUnreliable) return true;
+  if (signal.ambiguous) return false;
+  if (!signal.favorite) return false;
+  if (!hasSaneDistribution(signal.outcomes)) return false;
+  if (signal.stale || isStaleSignal(signal, options)) return false;
+  if (options.minLiquidity != null) {
+    if (signal.liquidity == null || signal.liquidity < options.minLiquidity) return false;
+  }
+  return true;
+}
+function buildMarketSignal(input) {
+  const outcomes = normalizeOutcomes(input.outcomes);
+  const ambiguous = input.ambiguous === true || !mapsCleanly(input.match, outcomes);
+  const favorite = ambiguous ? void 0 : deriveFavorite(outcomes);
+  const signal = {
+    matchId: input.match.id,
+    source: input.source,
+    sourceMarketId: input.sourceMarketId,
+    asOf: input.asOf,
+    fetchedAt: input.fetchedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    outcomes,
+    favorite,
+    liquidity: input.liquidity,
+    volume24h: input.volume24h,
+    stale: false,
+    ambiguous
+  };
+  signal.stale = isStaleSignal(signal, { now: input.now, maxAgeMs: input.maxAgeMs });
+  return signal;
+}
+function pct(p) {
+  return Math.round(p * 100);
+}
+function marketSourceLabel(source) {
+  if (source === "polymarket") return "Polymarket";
+  if (source === "fake") return "demo data";
+  return source.charAt(0).toUpperCase() + source.slice(1);
+}
+function outcomeLabel(o, match) {
+  if (o.kind === "home") return match.home.name;
+  if (o.kind === "away") return match.away.name;
+  if (o.kind === "draw") return "Draw";
+  return o.label;
+}
+function utcHhmm(iso) {
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return "";
+  return `${new Date(t).toISOString().slice(11, 16)} UTC`;
+}
+function marketFavoriteText(signal, match) {
+  const fav = signal.favorite;
+  if (!fav || fav.strength === "close") return "Prediction markets see this match as close.";
+  if (fav.kind === "draw") return "Prediction markets see a draw as the top outcome.";
+  const name = fav.kind === "home" ? match.home.name : match.away.name;
+  return fav.strength === "clear" ? `Prediction markets favor ${name}.` : `Prediction markets slightly favor ${name}.`;
+}
+function marketProbabilityText(signal, match) {
+  const order = ["home", "draw", "away"];
+  const parts = [];
+  for (const kind of order) {
+    const o = signal.outcomes.find((x) => x.kind === kind);
+    if (o) parts.push(`${outcomeLabel(o, match)} ${pct(o.probability)}%`);
+  }
+  for (const o of signal.outcomes) {
+    if (o.kind === "other") parts.push(`${outcomeLabel(o, match)} ${pct(o.probability)}%`);
+  }
+  return parts.join(" \xB7 ");
+}
+function marketAttributionText(signal) {
+  const time = utcHhmm(signal.asOf);
+  const src = `Source: ${marketSourceLabel(signal.source)}`;
+  return time ? `${src} \xB7 updated ${time}` : src;
+}
+function marketLine(signal, match) {
+  return `Market: ${marketProbabilityText(signal, match)} \xB7 ${marketSourceLabel(
+    signal.source
+  )} \xB7 informational only`;
+}
+function marketBlock(signal, match) {
+  const lines = [];
+  if (signal.stale) lines.push("Market signal is stale; the reading may be out of date.");
+  lines.push(marketFavoriteText(signal, match));
+  lines.push(marketProbabilityText(signal, match));
+  lines.push(`${marketAttributionText(signal)} \xB7 informational only`);
+  return lines;
+}
+var FakeMarketProvider = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  opts;
+  name = "fake";
+  async findSignal(match, options) {
+    const preset = this.opts.signals?.[match.id];
+    if (preset) return preset;
+    if (this.opts.synthesize) return this.synthesize(match, options);
+    return void 0;
+  }
+  async findSignals(matches, options) {
+    const signals = /* @__PURE__ */ new Map();
+    const checked = /* @__PURE__ */ new Set();
+    for (const m of matches) {
+      checked.add(m.id);
+      const s = await this.findSignal(m, options);
+      if (s) signals.set(m.id, s);
+    }
+    return { signals, checked };
+  }
+  synthesize(match, options) {
+    const seed = hash(`${match.home.code}-${match.away.code}`);
+    const home = 0.3 + seed % 33 / 100;
+    const away = 0.18 + (seed >> 3) % 23 / 100;
+    const draw = Math.max(0.05, 1 - home - away);
+    const outcomes = [
+      { kind: "home", teamCode: match.home.code, label: match.home.name, probability: home },
+      { kind: "draw", label: "Draw", probability: draw },
+      { kind: "away", teamCode: match.away.code, label: match.away.name, probability: away }
+    ];
+    const now = this.opts.now ?? options?.now ?? /* @__PURE__ */ new Date();
+    const asOf = new Date(now.getTime() - 6e4).toISOString();
+    return buildMarketSignal({
+      match,
+      source: "fake",
+      sourceMarketId: `fake-${match.id}`,
+      asOf,
+      fetchedAt: now.toISOString(),
+      outcomes,
+      liquidity: 5e4,
+      now,
+      maxAgeMs: options?.maxAgeMs
+    });
+  }
+};
+function hash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = h * 31 + s.charCodeAt(i) >>> 0;
+  return h % 1e5;
+}
+var mapping_2026_default = {
+  version: 1,
+  note: "Optional matchId -> Polymarket EVENT-slug OVERRIDES. By default the slug is DERIVED from each fixture (fifwc-{home}-{away}-{UTC-date}, e.g. fifwc-mex-rsa-2026-06-11), so most matches need NO entry here. Add an entry only for a fixture whose real Polymarket slug differs (e.g. a team abbreviation that isn't the FIFA code, or a tz-shifted date). The event payload carries the three moneyline binary markets; each outcome's probability is its 'Yes' price; validation fails closed. Entry: { eventSlug, eventId? }.",
+  markets: {}
+};
+var DEFAULT_BASE2 = "https://gamma-api.polymarket.com";
+var ALLOWED_HOSTS = /* @__PURE__ */ new Set(["gamma-api.polymarket.com"]);
+var USER_AGENT2 = "claudinho/0.0 (+https://github.com/arturogarrido/claudinho)";
+var DEFAULT_TIMEOUT_MS = 8e3;
+var WC_SERIES_SLUG = "soccer-fifwc";
+var WC_SPORT = "fifwc";
+var KICKOFF_TOLERANCE_MS = 6 * 60 * 6e4;
+var NON_REGULAR_TIME = /extra time|penalt|to advance|to qualif|win the (group|tournament|cup|title)/i;
+var BUNDLED_MAPPING = mapping_2026_default.markets;
+var PolymarketProvider = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  opts;
+  name = "polymarket";
+  async findSignal(match, options) {
+    return (await this.resolveOne(match, options)).signal;
+  }
+  async findSignals(matches, options) {
+    const signals = /* @__PURE__ */ new Map();
+    const checked = /* @__PURE__ */ new Set();
+    const deadline = options?.deadlineMs != null ? Date.now() + options.deadlineMs : Number.POSITIVE_INFINITY;
+    for (const m of matches) {
+      if (Date.now() >= deadline) break;
+      const r = await this.resolveOne(m, options);
+      if (r.checked) checked.add(m.id);
+      if (r.signal) signals.set(m.id, r.signal);
+    }
+    return { signals, checked };
+  }
+  /**
+   * Resolve one match. `checked` distinguishes a DEFINITIVE result (reached the
+   * source and found no usable market, or the fixture is unmappable) from a
+   * provider/network error — so transient failures are retried, not
+   * negative-cached.
+   */
+  async resolveOne(match, options) {
+    const entry = (this.opts.mapping ?? BUNDLED_MAPPING)[match.id];
+    const eventSlug = entry?.eventSlug ?? deriveEventSlug(match);
+    if (!eventSlug) return { checked: true };
+    try {
+      const event = await this.fetchEvent(eventSlug, options?.timeoutMs);
+      const signal = event ? this.toSignal(match, eventSlug, event, options) : void 0;
+      return { signal, checked: true };
+    } catch {
+      return { checked: false };
+    }
+  }
+  async fetchEvent(slug, timeoutMs) {
+    const base = this.opts.baseUrl ?? DEFAULT_BASE2;
+    assertAllowedHost(base);
+    const url = `${base}/events?slug=${encodeURIComponent(slug)}`;
+    const doFetch = this.opts.fetchImpl ?? fetch;
+    const res = await doFetch(url, {
+      signal: AbortSignal.timeout(timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+      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 data = await res.json();
+    const event = Array.isArray(data) ? data[0] : data;
+    return event && typeof event === "object" ? event : void 0;
+  }
+  toSignal(match, eventSlug, event, options) {
+    if (event.active === false || event.closed === true) return void 0;
+    if (event.seriesSlug != null && event.seriesSlug !== WC_SERIES_SLUG && event.sport?.sport !== WC_SPORT) {
+      return void 0;
+    }
+    if (event.slug != null && event.slug !== eventSlug) return void 0;
+    const start = event.startTime ? Date.parse(event.startTime) : Number.NaN;
+    const kick = Date.parse(match.kickoff);
+    if (Number.isFinite(start) && Number.isFinite(kick) && Math.abs(start - kick) > KICKOFF_TOLERANCE_MS) {
+      return void 0;
+    }
+    const moneyline = (event.markets ?? []).filter(
+      (m) => (m.sportsMarketType ?? "moneyline") === "moneyline"
+    );
+    const homeMarket = pickMarket(moneyline, match.home.code, match.home.name);
+    const awayMarket = pickMarket(moneyline, match.away.code, match.away.name);
+    const drawMarket = pickDraw(moneyline);
+    if (!homeMarket || !awayMarket) return void 0;
+    const legIds = [homeMarket, awayMarket, drawMarket].filter((m) => m != null).map((m) => m.id ?? m.slug ?? "");
+    if (new Set(legIds).size !== legIds.length) return void 0;
+    const legs = [
+      ["home", homeMarket, match.home.code, match.home.name],
+      ["draw", drawMarket, void 0, "Draw"],
+      ["away", awayMarket, match.away.code, match.away.name]
+    ];
+    const outcomes = [];
+    let asOf = event.updatedAt;
+    let liquidity;
+    for (const [kind, market, teamCode, label] of legs) {
+      if (!market) continue;
+      if (market.closed === true || market.active === false) return void 0;
+      if (market.description && NON_REGULAR_TIME.test(market.description)) return void 0;
+      const yes = yesPrice(market);
+      if (yes == null) return void 0;
+      outcomes.push({ kind, teamCode, label, probability: yes });
+      if (market.updatedAt && (!asOf || market.updatedAt < asOf)) asOf = market.updatedAt;
+      const liq = numberish(market.liquidityNum ?? market.liquidity);
+      if (liq != null) liquidity = liquidity == null ? liq : Math.min(liquidity, liq);
+    }
+    const rawSum = outcomes.reduce((s, o) => s + o.probability, 0);
+    if (rawSum < 0.9 || rawSum > 1.15) return void 0;
+    const signal = buildMarketSignal({
+      match,
+      source: "polymarket",
+      sourceMarketId: event.id ?? eventSlug,
+      asOf: asOf ?? (/* @__PURE__ */ new Date()).toISOString(),
+      outcomes,
+      liquidity,
+      now: options?.now ?? this.opts.now,
+      maxAgeMs: options?.maxAgeMs ?? this.opts.maxAgeMs
+    });
+    return signal.ambiguous ? void 0 : signal;
+  }
+};
+function deriveEventSlug(match) {
+  const home = match.home.code.toLowerCase();
+  const away = match.away.code.toLowerCase();
+  if (home === away || home === "tbd" || away === "tbd") return void 0;
+  if (!/^[a-z]{3}$/.test(home) || !/^[a-z]{3}$/.test(away)) return void 0;
+  const date = match.kickoff.slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return void 0;
+  return `fifwc-${home}-${away}-${date}`;
+}
+function slugToken(m) {
+  return (m.slug ?? "").toLowerCase().split("-").pop() ?? "";
+}
+function isDrawMarket(m) {
+  return slugToken(m) === "draw" || (m.groupItemTitle ?? "").trim().toLowerCase().startsWith("draw");
+}
+function pickMarket(markets, teamCode, teamName) {
+  const code = teamCode.toLowerCase();
+  const name = teamName.trim().toLowerCase();
+  const teamMarkets = markets.filter((m) => !isDrawMarket(m));
+  const bySlug = teamMarkets.find((m) => slugToken(m) === code);
+  if (bySlug) return bySlug;
+  return teamMarkets.find((m) => (m.groupItemTitle ?? "").trim().toLowerCase() === name);
+}
+function pickDraw(markets) {
+  return markets.find(isDrawMarket);
+}
+function assertAllowedHost(base) {
+  let host;
+  try {
+    host = new URL(base).host;
+  } catch {
+    throw new Error(`Invalid Polymarket base URL: ${base}`);
+  }
+  if (!ALLOWED_HOSTS.has(host)) {
+    throw new Error(`Polymarket host not allow-listed: ${host}`);
+  }
+}
+function yesPrice(market) {
+  const labels = parseJsonArray(market.outcomes);
+  const prices = parseJsonArray(market.outcomePrices).map((p2) => Number(p2));
+  if (labels.length === 0 || labels.length !== prices.length) return void 0;
+  const i = labels.findIndex((l) => l.trim().toLowerCase() === "yes");
+  if (i < 0) return void 0;
+  const p = prices[i];
+  return typeof p === "number" && Number.isFinite(p) && p > 0 && p <= 1 ? p : void 0;
+}
+function parseJsonArray(v) {
+  if (Array.isArray(v)) return v.map((x) => String(x));
+  if (typeof v === "string") {
+    try {
+      const parsed = JSON.parse(v);
+      return Array.isArray(parsed) ? parsed.map((x) => String(x)) : [];
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+function numberish(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : void 0;
+  if (typeof v === "string") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : void 0;
+  }
+  return void 0;
+}
+function resolveMarketSource(explicit) {
+  if (explicit) return explicit;
+  if (typeof process !== "undefined" && process.env?.CLAUDINHO_MARKETS_SOURCE) {
+    return process.env.CLAUDINHO_MARKETS_SOURCE;
+  }
+  return "polymarket";
+}
+function makeMarketProvider(source) {
+  switch (resolveMarketSource(source)) {
+    case "fake":
+      return new FakeMarketProvider({ synthesize: true });
+    case "none":
+    case "off":
+      return new FakeMarketProvider();
+    // no synth → yields no signals, no network
+    default:
+      return new PolymarketProvider();
+  }
+}
+async function getMarketSignal(provider, match, options) {
+  try {
+    return await provider.findSignal(match, options);
+  } catch {
+    return void 0;
+  }
+}
+async function getMarketSignals(provider, matches, options) {
+  try {
+    return await provider.findSignals(matches, options);
+  } catch {
+    return { signals: /* @__PURE__ */ new Map(), checked: /* @__PURE__ */ new Set() };
+  }
+}
+var SHARE_HASHTAG = "#VibingLaVidaLoca";
+var SHARE_DISCLAIMER = "Independent fan project \xB7 not affiliated with FIFA or Anthropic.";
+function mid(m) {
+  return isLive(m.status) || m.status === "FT" ? scoreline(m) : "vs";
+}
+function statusTail(m) {
+  switch (m.status) {
+    case "LIVE":
+      return m.minute ? `${m.minute}'` : "LIVE";
+    case "HT":
+      return "HT";
+    case "FT":
+      return "FT";
+    case "POSTPONED":
+      return "postponed";
+    case "CANCELLED":
+      return "cancelled";
+    default:
+      return "";
+  }
+}
+function compactLine(m, input, single) {
+  const home = `${m.home.flag} ${m.home.code}`;
+  const away = `${m.away.code} ${m.away.flag}`;
+  const opts = { tz: input.tz, locale: input.locale };
+  let tail;
+  if (m.status === "SCHEDULED") {
+    const time = formatTime(m.kickoff, opts);
+    tail = single ? `${formatDate(m.kickoff, opts)} ${time}` : time;
+  } else {
+    tail = statusTail(m);
+  }
+  return `${home} ${mid(m)} ${away}${tail ? ` \xB7 ${tail}` : ""}`;
+}
+function socialCard(m, input) {
+  const lines = [];
+  const head = `${m.home.flag} ${m.home.name} ${mid(m)} ${m.away.name} ${m.away.flag}`;
+  if (m.status === "SCHEDULED") {
+    lines.push(head);
+    const date = formatDate(m.kickoff, { tz: input.tz, locale: input.locale });
+    const time = formatTime(m.kickoff, { tz: input.tz, locale: input.locale });
+    const zone = input.tz ? ` ${input.tz}` : "";
+    lines.push(`${date} \xB7 ${time}${zone}`);
+  } else {
+    const tail = statusTail(m);
+    lines.push(tail ? `${head} \xB7 ${tail}` : head);
+  }
+  const loc = matchLocation(m);
+  if (loc) lines.push(loc);
+  return lines;
+}
+function formatShareSnippet(input, options = {}) {
+  const style = options.style ?? "social";
+  const includeMarkets = options.includeMarkets !== false;
+  const includeHashtag = options.includeHashtag !== false;
+  const includeInstall = options.includeInstallLine !== false;
+  const signals = input.marketSignals ?? /* @__PURE__ */ new Map();
+  const single = input.matches.length === 1;
+  const blocks = [input.title];
+  if (input.matches.length === 0) {
+    if (input.emptyNote) blocks.push(input.emptyNote);
+  } else if (style === "compact") {
+    blocks.push(input.matches.map((m) => compactLine(m, input, single)).join("\n"));
+  } else {
+    for (const m of input.matches) {
+      const card = socialCard(m, input);
+      const sig = includeMarkets ? signals.get(m.id) : void 0;
+      if (sig) {
+        if (single) card.push("", ...marketBlock(sig, m));
+        else card.push(marketLine(sig, m));
+      }
+      blocks.push(card.join("\n"));
+    }
+  }
+  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"));
+  return blocks.join("\n\n");
+}
 
 // src/format.ts
 var STATUS_LABEL = {
@@ -2920,6 +3448,88 @@ var DISCLAIMER = "Claudinho is an independent fan project \u2014 not affiliated
 function resolveAdapter(args) {
   return args.adapter ?? makeAdapter(args.source);
 }
+function resolveMarketProvider(args) {
+  return args.marketProvider ?? makeMarketProvider();
+}
+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 marketText(m, sig) {
+  return `${marketHeader(m)}
+${marketBlock(sig, m).join("\n")}`;
+}
+function marketData(sig) {
+  return {
+    matchId: sig.matchId,
+    source: sig.source,
+    asOf: sig.asOf,
+    fetchedAt: sig.fetchedAt,
+    market: { id: sig.sourceMarketId ?? null, url: null },
+    outcomes: sig.outcomes,
+    favorite: sig.favorite ?? null,
+    liquidity: sig.liquidity ?? null,
+    stale: sig.stale,
+    ambiguous: sig.ambiguous,
+    informationalOnly: true
+  };
+}
+function marketsEnabled() {
+  return (process.env.CLAUDINHO_MARKETS ?? "").toLowerCase() !== "off";
+}
+var marketMem = /* @__PURE__ */ new Map();
+var MEM_POSITIVE_TTL = 10 * 6e4;
+var MEM_NEGATIVE_TTL = 3 * 6e4;
+var DEFAULT_ON_MARKET_OPTS = { deadlineMs: 2e3, timeoutMs: 2500 };
+var MARKETS_TOOL_OPTS = { deadlineMs: 12e3, timeoutMs: 6e3 };
+function memKey(competition, id) {
+  return `polymarket:${competition}:${id}`;
+}
+async function cachedMarketSignals(args, matches) {
+  if (args.marketProvider) return (await getMarketSignals(args.marketProvider, matches)).signals;
+  const source = resolveMarketSource();
+  if (source !== "polymarket") {
+    return (await getMarketSignals(makeMarketProvider(source), matches, DEFAULT_ON_MARKET_OPTS)).signals;
+  }
+  const competition = resolveCompetition();
+  const now = Date.now();
+  const result = /* @__PURE__ */ new Map();
+  const miss = [];
+  for (const m of matches) {
+    const e = marketMem.get(memKey(competition, m.id));
+    const ttl = e?.signal ? MEM_POSITIVE_TTL : MEM_NEGATIVE_TTL;
+    if (e && now - e.at <= ttl) {
+      if (e.signal) result.set(m.id, e.signal);
+    } else {
+      miss.push(m);
+    }
+  }
+  if (miss.length > 0) {
+    const { signals: fetched, checked } = await getMarketSignals(
+      makeMarketProvider("polymarket"),
+      miss,
+      DEFAULT_ON_MARKET_OPTS
+    );
+    for (const id of checked) {
+      marketMem.set(memKey(competition, id), { at: now, signal: fetched.get(id) ?? null });
+    }
+    for (const [id, s] of fetched) result.set(id, s);
+  }
+  return result;
+}
+async function reliableMarketData(args, matches) {
+  if (!marketsEnabled()) return void 0;
+  const signals = await cachedMarketSignals(args, matches);
+  const now = /* @__PURE__ */ new Date();
+  const out = {};
+  for (const m of matches) {
+    const s = signals.get(m.id);
+    if (s && isReliableMarketSignal(s, { now })) out[m.id] = marketData(s);
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
 function fmtOpts(args) {
   return {
     tz: args.tz,
@@ -2927,43 +3537,55 @@ function fmtOpts(args) {
     flavor: asFlavorLevel(args.flavor ?? process.env.CLAUDINHO_FLAVOR)
   };
 }
-function withDisclaimer(text) {
-  return `${text}
+function withDisclaimer(text, source) {
+  const live = source ? `
+Live data: ${liveSourceLabel(source)}` : "";
+  return `${text}${live}
 
 ${DISCLAIMER}`;
 }
 async function toolGetToday(args) {
   const adapter = resolveAdapter(args);
   const date = args.date ?? localDate((/* @__PURE__ */ new Date()).toISOString(), args.tz);
-  const { matches, degraded } = await getMatchesForDate(adapter, date);
+  const { matches, degraded, source } = await getMatchesForDate(adapter, date);
   const todays = fixturesByDate(date, matches, args.tz);
   const opts = fmtOpts(args);
   const text = `Matches on ${date}:
 ${matchList(todays, "No matches scheduled.", opts)}`;
+  const marketSignals = await reliableMarketData(args, todays);
   return {
-    text: withDisclaimer(text),
-    data: { date, degraded, count: todays.length, matches: todays }
+    text: withDisclaimer(text, source),
+    data: {
+      date,
+      degraded,
+      source: source ?? null,
+      count: todays.length,
+      matches: todays,
+      ...marketSignals ? { marketSignals } : {}
+    }
   };
 }
 async function toolGetLive(args = {}) {
   const adapter = resolveAdapter(args);
-  const { matches, degraded } = await getLiveMatches(adapter);
+  const { matches, degraded, source } = await getLiveMatches(adapter);
   const opts = fmtOpts(args);
   const text = `Live now:
 ${matchList(matches, "No matches in play right now.", opts)}`;
   return {
-    text: withDisclaimer(text),
-    data: { degraded, count: matches.length, matches }
+    text: withDisclaimer(text, source),
+    data: { degraded, source: source ?? null, count: matches.length, matches }
   };
 }
 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;
     }
@@ -2972,10 +3594,26 @@ async function toolGetMatch(args) {
     return { text: withDisclaimer(`No match found with id ${args.id}.`), data: { match: null } };
   }
   const opts = fmtOpts(args);
-  return { text: withDisclaimer(matchLine(match, opts)), data: { degraded, match } };
+  let marketSignal;
+  if (marketsEnabled()) {
+    const s = (await cachedMarketSignals(args, [match])).get(match.id);
+    if (s && isReliableMarketSignal(s, { now: /* @__PURE__ */ new Date() })) marketSignal = s;
+  }
+  const base = matchLine(match, opts);
+  const text = marketSignal ? `${base}
+${marketBlock(marketSignal, match).join("\n")}` : base;
+  return {
+    text: withDisclaimer(text, liveSource),
+    data: {
+      degraded,
+      source: liveSource ?? null,
+      match,
+      marketSignal: marketSignal ? marketData(marketSignal) : null
+    }
+  };
 }
 async function toolGetStandings(args) {
-  const { matches, degraded } = await getMatchesForDate(
+  const { matches, degraded, source } = await getMatchesForDate(
     resolveAdapter(args),
     localDate((/* @__PURE__ */ new Date()).toISOString(), args.tz)
   );
@@ -2984,10 +3622,8 @@ async function toolGetStandings(args) {
     const g = args.group.toUpperCase();
     if (!known.includes(g)) {
       return {
-        text: withDisclaimer(
-          `No group "${g}". Groups are ${known.join(", ")}.`
-        ),
-        data: { degraded, tables: null }
+        text: withDisclaimer(`No group "${g}". Groups are ${known.join(", ")}.`, source),
+        data: { degraded, source: source ?? null, tables: null }
       };
     }
   }
@@ -2998,8 +3634,8 @@ async function toolGetStandings(args) {
   }));
   const text = tables.map((t) => standingsTable(t.group, t.standings)).join("\n\n");
   return {
-    text: withDisclaimer(text || `No group found.`),
-    data: { degraded, tables: args.group ? tables[0] ?? null : tables }
+    text: withDisclaimer(text || `No group found.`, source),
+    data: { degraded, source: source ?? null, tables: args.group ? tables[0] ?? null : tables }
   };
 }
 async function toolGetNextFixture(args) {
@@ -3018,14 +3654,204 @@ ${matchLine(fixture, opts)}`),
     data: { team: code, fixture }
   };
 }
+async function toolGetMarketSignal(args) {
+  const provider = resolveMarketProvider(args);
+  if (args.matchId) {
+    const match = allFixtures().find((m) => m.id === args.matchId);
+    const sig = match ? 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)}.`;
+    return {
+      text: withDisclaimer(text2),
+      data: {
+        matchId: args.matchId,
+        informationalOnly: true,
+        signal: shown2 ? marketData(shown2) : null
+      }
+    };
+  }
+  if (args.team) {
+    const code = args.team.toUpperCase();
+    const fixture = nextFixtureForTeam(code);
+    const sig = fixture ? 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.`;
+    return {
+      text: withDisclaimer(text2),
+      data: {
+        team: code,
+        matchId: fixture?.id ?? null,
+        informationalOnly: true,
+        signal: shown2 ? marketData(shown2) : null
+      }
+    };
+  }
+  const date = args.date ?? localDate((/* @__PURE__ */ new Date()).toISOString(), args.tz);
+  const { matches } = await getMatchesForDate(resolveAdapter(args), date);
+  const todays = fixturesByDate(date, matches, args.tz);
+  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}.`;
+  return {
+    text: withDisclaimer(text),
+    data: {
+      date,
+      informationalOnly: true,
+      signals: shown.map(({ signal }) => marketData(signal))
+    }
+  };
+}
+async function reliableSignalMap(args, matches) {
+  if (!marketsEnabled()) return /* @__PURE__ */ new Map();
+  const signals = await cachedMarketSignals(args, matches);
+  const now = /* @__PURE__ */ new Date();
+  const out = /* @__PURE__ */ new Map();
+  for (const m of matches) {
+    const s = signals.get(m.id);
+    if (s && isReliableMarketSignal(s, { now }) && marketDisplayable(s)) out.set(m.id, s);
+  }
+  return out;
+}
+function shareOptions(args) {
+  return {
+    style: args.style === "compact" ? "compact" : "social",
+    includeMarkets: marketsEnabled() && args.includeMarkets !== false,
+    includeHashtag: args.includeHashtag !== false,
+    includeInstallLine: args.includeInstallLine !== false
+  };
+}
+function shareResult(kind, target, team, input, options) {
+  const snippet = formatShareSnippet(input, options);
+  return {
+    // The snippet is self-contained: it carries its own non-affiliation
+    // disclaimer (and, for any market line, the "informational only" caveat +
+    // attribution), so it is deliberately NOT wrapped with withDisclaimer —
+    // that would duplicate the disclaimer inside a paste-ready artifact.
+    text: snippet,
+    data: {
+      kind,
+      target,
+      ...team ? { team } : {},
+      source: input.source ?? null,
+      informationalOnly: true,
+      style: options.style ?? "social",
+      snippet,
+      matches: input.matches,
+      marketSignals: Object.fromEntries(
+        [...input.marketSignals ?? /* @__PURE__ */ new Map()].map(([id, s]) => [
+          id,
+          marketData(s)
+        ])
+      )
+    }
+  };
+}
+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));
+    return shareResult(
+      "live",
+      "live",
+      void 0,
+      {
+        title: "Live match pulse",
+        matches,
+        source: source2,
+        emptyNote: "No matches in play right now.",
+        installLine: "npx @claudinho/cli live",
+        tz: args.tz,
+        locale: args.lang
+      },
+      { ...options, includeMarkets: false }
+    );
+  }
+  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 matches = match ? [match] : [];
+    return shareResult(
+      "match",
+      args.matchId,
+      void 0,
+      {
+        title: "Match pulse",
+        matches,
+        marketSignals: await signalsFor(matches),
+        source: source2,
+        emptyNote: `No match found with id ${args.matchId}.`,
+        installLine: `npx @claudinho/cli match ${args.matchId}`,
+        tz: args.tz,
+        locale: args.lang
+      },
+      options
+    );
+  }
+  if (args.team) {
+    const code = args.team.toUpperCase();
+    const fixture = nextFixtureForTeam(code);
+    const matches = fixture ? [fixture] : [];
+    const teamName = fixture ? fixture.home.code === code ? fixture.home.name : fixture.away.name : code;
+    return shareResult(
+      "next",
+      "next",
+      code,
+      {
+        title: `Next up for ${teamName}`,
+        matches,
+        marketSignals: await signalsFor(matches),
+        emptyNote: `No upcoming fixture found for ${code}.`,
+        installLine: `npx @claudinho/cli next ${code}`,
+        tz: args.tz,
+        locale: args.lang
+      },
+      options
+    );
+  }
+  const date = args.date ?? localDate((/* @__PURE__ */ new Date()).toISOString(), args.tz);
+  const { matches: all, 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(
+    "today",
+    date,
+    void 0,
+    {
+      title: args.date ? `Matches \xB7 ${human}` : `Today's matches \xB7 ${human}`,
+      matches: todays,
+      marketSignals: await signalsFor(todays),
+      source,
+      emptyNote: `No matches scheduled for ${human}.`,
+      installLine: "npx @claudinho/cli today",
+      tz: args.tz,
+      locale: args.lang
+    },
+    options
+  );
+}
 
 // src/server.ts
 var SERVER_NAME = "claudinho";
-var SERVER_VERSION = "0.2.0";
+var SERVER_VERSION = "0.4.0";
 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.${VOICE}
+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_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");
 var groupArg = z.string().regex(/^[A-La-l]$/, "a group letter A\u2013L");
@@ -3107,6 +3933,43 @@ function buildServer() {
     },
     async (args) => toContent(await toolGetNextFixture(args))
   );
+  server.registerTool(
+    "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.",
+      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"),
+        date: dateArg.optional().describe("Date as YYYY-MM-DD (default: today) for all that day's signals"),
+        ...commonArgs
+      },
+      // Read-only; reaches an external prediction-market data provider.
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => toContent(await toolGetMarketSignal(args))
+  );
+  server.registerTool(
+    "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.",
+      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"),
+        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)"),
+        includeHashtag: z.boolean().optional().describe("Include the #VibingLaVidaLoca tag (default true)"),
+        includeInstallLine: z.boolean().optional().describe('Include the "Try it: \u2026" run cue (default true)'),
+        includeMarkets: z.boolean().optional().describe("Include the reliable market line when available (default true)"),
+        ...commonArgs
+      },
+      // Read-only; may reach the live/market data providers (live/today/match).
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => toContent(await toolGetShareSnippet(args))
+  );
   server.registerResource(
     "standings",
     new ResourceTemplate("standings://{group}", { list: void 0 }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@claudinho/mcp",
-  "version": "0.2.0",
-  "description": "Claudinho MCP server — ask your agent about the 2026 football tournament. Live scores, fixtures, standings. Not affiliated with FIFA or Anthropic.",
+  "version": "0.4.0",
+  "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.",
   "type": "module",
   "license": "MIT",
   "author": "Arturo Garrido",
@@ -47,7 +47,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.0",
-    "@claudinho/core": "0.2.0"
+    "@claudinho/core": "0.4.0"
   },
   "scripts": {
     "build": "tsup",