CupOracle — the missing World Cup MCP server

One npx install gives any AI agent live World Cup 2026 fixtures, scores and de-vigged consensus odds for free — plus wc_edge, an autonomous Injective x402 buyer that pays for premium data itself under a spend cap and cites the receipt. Published live on npm.

Live: https://cuporacle.edycu.dev/ · npm: https://www.npmjs.com/package/cuporacle-mcp · Pitch deck: https://cuporacle.edycu.dev/pitch/ · Demo: https://youtu.be/FAI3_xZFTx0

INSPIRATION

The 2026 FIFA World Cup is the biggest event on earth, and every AI assistant is football-blind through all of it. Ask Claude "what's on tonight?" and it can't see the fixture, has no odds, and — more fundamentally — has no way to pay for premium data itself. Injective's own MCP server covers wallets, markets, CCTP and trading, but there is no first-class sports capability and no reference pattern for an agent acting as an autonomous x402 buyer. CupOracle is that missing layer: a published, composable MCP server that runs side by side with the Injective MCP server.

WHAT IT DOES

One install (npx -y cuporacle-mcp) makes any Claude / Cursor session a World Cup analyst that can buy and prove its own alpha:

1. Free fixtures — wc_fixtures(date?): real live World Cup 2026 fixtures for a day or the next upcoming window (football-data.org, competition 2000).

2. Free live scores — wc_live(matchId): score, minute, status.

3. Free consensus odds — wc_odds(matchId): h2h odds across ~50 books plus de-vigged implied probabilities.

4. Free knockout bracket — wc_bracket(): R16 → Final state, also exposed as the wc://bracket resource.

5. The showpiece, a paid edge — wc_edge(matchId, maxSpend?, dry_run?): an autonomous Injective x402 buyer. It parses a real HTTP 402 quote accepts / PAYMENT-REQUIRED), enforces a per-call max and per-session spend cap, signs an EIP-3009 USDC transfer authorization locally (viem signTypedData — no key ever leaves the process), retries with PAYMENT-SIGNATURE, and cites the receipt from PAYMENT-RESPONSE. Target network: Injective EVM mainnet eip155:1776, native USDC.

6. Receipt verification — receipt_verify(txHash): reads the tx over the Injective EVM RPC, decodes the USDC Transfer log → block time, amount, payer, payee, Blockscout link.

7. Self-service funding — wallet_fund_guide(chain?): the CCTP runbook that routes to the Injective MCP server's own cctp_* tools (interop, not wrap).

8. Auditable spending — wc_spend_ledger() + the wc://ledger resource: the agent's own purchase history vs. its cap, in-conversation.

Governance is a feature: above the cap the agent stops and asks the human (typed SPEND_CAP_HIT); broke, it teaches itself to fund via CCTP (typed INSUFFICIENT_USDC). And it is honest by construction — if the paid upstream is unavailable or the wallet is unfunded, wc_edge degrades to free odds and never fabricates an edge or a receipt.

HOW WE BUILT IT

- MCP server — TypeScript + @modelcontextprotocol/sdk over stdio: 8 tools, 2 resources, 1 prompt analyze-match), zod schemas on every surface.

- x402 buyer client — @injectivelabs/x402 ./client + ./eip3009) + viem: 402-quote parse → spend-cap gate → local EIP-3009 sign → PAYMENT-SIGNATURE retry → PAYMENT-RESPONSE receipt.

- Injective EVM — mainnet eip155:1776 (Blockscout + sentry.evm-rpc.injective.network), testnet eip155:1439; native USDC 0xa00C59fF5a080D2b954d0c75e46E22a0c371235a (Circle FiatTokenV2_2, EIP-3009).

- Data layer — football-data.org + the-odds-api free tiers, 60s cache, committed snapshots always labeled [snapshot].

- Agent Skills — ships a cuporacle Skill (tool-selection table, spend policy, fund-if-broke runbook) so harnesses use it well.

- Key handling — AES-256-GCM keystore + cuporacle-mcp init wallet scaffold; fund cents only, default cap 0.50 USDC.

- Packaging — tsup → ESM dist/ with typed exports and a shebang'd bin; published live on npm as cuporacle-mcp@1.0.0 (mirrored to GitHub Packages as @edycutjong/cuporacle-mcp).

Quality and security engineering:

- Type safety — strict TypeScript, tsc --noEmit gate in CI.

- Unit / contract tests — 63 vitest across 8 suites: schemas, spend cap, 402-parse against a recorded quote, EIP-3009 sign round-trip, full stubbed handshake, receipts, snapshot fallback, keystore.

- Protocol E2E — no browser surface, so the E2E proof is a cold-start smoke over real stdio (lists 8 tools / 2 resources / 1 prompt + one live free call) plus official MCP Inspector conformance against the built dist/, both on every push.

- Security (DevSecOps) — CodeQL (SAST), Dependabot (npm + Actions, weekly), TruffleHog secret scan (verified-only), npm audit high/critical gate, license compliance (no GPL/AGPL in prod deps).

- CI/CD — 5-stage GitHub Actions pipeline (Quality → Secret Scan + Dependency Audit → Build + dist smoke → MCP Conformance → npm Publish Readiness), Node 20/22/24 matrix on main, semantic-release versioning, token-gated npm publish workflow.

CHALLENGES WE RAN INTO

- Proving a payment client with zero funds — without faking anything. A real settled call needs USDC on Injective. Instead of a fabricated receipt, we built a deterministic dry_run path: parse the recorded 402 quote, enforce the cap, sign the EIP-3009 authorization locally — "Signature produced: TRUE", no money moved, and the tool says so. The only receipt wc_edge will ever cite is one returned by a genuine paid call.

- CI kept failing on release. The semantic-release job tried to npm-publish on every push and died without registry credentials; fixed by moving publish fully into a separate token-gated publish.yml (commit e8f5460), keeping the main pipeline green.

- No browser to E2E. A stdio MCP server can't be Playwright'd, so we replaced the usual browser stages with the two proofs that matter: a real-stdio cold-start smoke of the exact built artifact and official MCP Inspector conformance — both in CI.

- Free-tier rate limits. football-data.org and the-odds-api cap requests hard; solved with a 60s cache plus committed snapshot fallbacks that are always labeled [snapshot], never passed off as live.

WHAT WE LEARNED

Honesty is a feature you can engineer. Typed failure modes SPEND_CAP_HIT teaches governance, INSUFFICIENT_USDC carries the CCTP runbook), labeled snapshots, and a dry-run signature proof turned "we couldn't fund the wallet yet" from a weakness into the most convincing part of the demo — an agent that provably refuses to overspend or invent a receipt. We also learned that publishing a real npm package raises every bar at once: files allowlist, bin shebangs, dist smoke, publish dry-run gates.

WHAT'S NEXT

- Land the first real settled receipt — CCTP a few cents of USDC onto Injective mainnet, run the funds-gated paid-call-smoke, and let receipt_verify prove it on Blockscout.

- More sports, same spine — each tool is a { name, config, handler } module and the x402 client is sport-agnostic; add cricket/NBA servers by swapping the data client.

- Sell, not just buy — flip the reference client into a seller-side surface so CupOracle's own vetted signals are purchasable by other agents via x402.

Everything was built inside the hackathon window — the repo's first commit is the hackathon build:

- Jul 12 — core build session: full MCP server (8 tools · 2 resources · 1 prompt over stdio), 4 free data tools returning real live World Cup 2026 data, the wc_edge x402 buyer (402-parse, spend-cap governance, local EIP-3009 signing), receipt_verify, AES-256-GCM keystore, 63 vitest passing, MCP Inspector conformance, tsup publish-ready build.

- Jul 17 — ship day: public repo github.com/edycutjong/cuporacle-mcp with the 5-stage CI green (CodeQL + Dependabot + TruffleHog); demo video live on YouTube (2:10); landing page + interactive pitch deck redesigned and live at cuporacle.edycu.dev and cuporacle.edycu.dev/pitch/; semantic-release + token-gated publish pipeline fixed.

- Jul 17 — published to npm: cuporacle-mcp@1.0.0 is live npx -y cuporacle-mcp works today), mirrored to GitHub Packages as @edycutjong/cuporacle-mcp, GitHub Release v1.0.0 cut.

No pre-existing code was reused; the only external dependency (LineLock /api/edge, a disclosed sibling project) is behind a documented degrade path.

Bootstrapped, solo-built, not raising. Real shipped surface: cuporacle-mcp@1.0.0 live on npm, public repo with green 5-stage CI, live landing + pitch deck. No revenue yet — the x402 paid call is priced (0.05 USDC) and the buyer client is fully coded and tested, with the first settled mainnet receipt gated only on funding cents of USDC via CCTP.