cuporacle-mcp

# Claude Code — the 4 free data tools work with just two free API keys
claude mcp add cuporacle -- npx -y cuporacle-mcp

Reproducing now (pre-publish): the npx cuporacle-mcp line activates once the package is published — a post-judging gate (see STATUS.md). Until then, run it from source in seconds: git clone https://github.com/edycutjong/cuporacle-mcp && cd cuporacle-mcp && npm install && npm run smoke.

cuporacle-mcp is a standalone Model Context Protocol server that runs side by side with the Injective MCP server: 8 tools + 2 resources + 1 prompt over stdio. Free data tools work out of the box; wc_edge is a reference implementation of an agent buying and proving its own alpha keylessly via Injective's x402.

🧑‍⚖️ Notes for judges — reproduce in < 5 min

• Zero-cost path. The four free tools (wc_fixtures, wc_live, wc_odds, wc_bracket) return real live World Cup 2026 data with just the two free API keys — no wallet, no funds.

• The x402 buyer path runs with zero funds. wc_edge(matchId, dry_run: true) (or npm run paid-call-smoke) parses the recorded 402 quote, enforces the spend cap, and signs the EIP-3009 authorization locally — a deterministic proof of the payment client with no money moved and no fabricated receipt.

• < 5-minute reproduce:

  npm install
  npm run smoke      # cold-start over stdio → lists 8 tools/2 resources/1 prompt + a live free call
  npm test           # 63 vitest (schemas · spend cap · 402-parse · EIP-3009 sign · receipts · degrade)
  npm run inspector  # official MCP Inspector conformance against the built dist/

• Honestly gated (not faked): a real settled wc_edge payment needs a few cents of USDC on Injective (funding is user-gated) plus the live LineLock upstream. Until then wc_edge degrades to free odds and never invents an edge or a receipt — full honest state in STATUS.md.

Related MCP server: ScoutAgent

💡 Why this exists

Agents have no first-class sports capability. Injective's own MCP server covers wallets, markets, CCTP and trading — but an agent asked "is tonight's match worth a bet?" has to hallucinate or scrape, and there's no pattern for an agent paying for premium data itself. CupOracle is that missing layer, built as a composable server that runs side by side with the Injective MCP server.

🧰 Tools

Resources: wc://bracket, wc://ledger · Prompt: analyze-match(matchId).

🚀 Quickstart

1. Get keys

• football-data.org free tier → FOOTBALL_DATA_KEY

• the-odds-api.com free tier → ODDS_API_KEY

The four free data tools work with just these two keys. wc_edge additionally needs a payer wallet (see Funding).

2. Add to your harness

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cuporacle": {
      "command": "npx",
      "args": ["-y", "cuporacle-mcp"],
      "env": {
        "FOOTBALL_DATA_KEY": "…",
        "ODDS_API_KEY": "…",
        "CUPORACLE_PRIVATE_KEY": "0x…",
        "CUPORACLE_MAX_SPEND": "0.50"
      }
    }
  }
}

Claude Code:

claude mcp add cuporacle \
  -e FOOTBALL_DATA_KEY=… -e ODDS_API_KEY=… \
  -e CUPORACLE_PRIVATE_KEY=0x… -e CUPORACLE_MAX_SPEND=0.50 \
  -- npx -y cuporacle-mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "cuporacle": { "command": "npx", "args": ["-y", "cuporacle-mcp"],
      "env": { "FOOTBALL_DATA_KEY": "…", "ODDS_API_KEY": "…" } }
  }
}

3. Ask

"What's tonight's Semi-Final, and is it worth a bet?"

The assistant lists the fixture (wc_fixtures), pulls odds (wc_odds), buys a vetted edge for ~5¢ (wc_edge) paying via x402 itself, and cites the receipt. Paste that hash into receipt_verify to confirm the payment on Injective.

🛠️ Injective technologies used

CupOracle is Injective-native by construction — remove any layer and it's just a scraper or a hosted API with a billing page.

Interop, not wrap. CupOracle does not reimplement chain ops or wrap the Injective MCP tools as its own — both servers run in the same harness and the Skill routes funding to Injective's tools. Honesty over land-grab.

🔄 The autonomous-payment loop (wc_edge)

flowchart TD
    A["POST /api/edge"] --> B["402 Payment Required<br/>accepts: network eip155:1776 · amount 50000 · asset USDC · payTo"]
    B --> C["spend-cap gate<br/>per-call max · per-session cap · ask human above cap"]
    C --> D["sign EIP-3009 authorization<br/>local viem signTypedData — no broadcast"]
    D --> E["retry with PAYMENT-SIGNATURE header"]
    E --> F["200 OK<br/>{ edge, ladder, pick_hash } + PAYMENT-RESPONSE { transaction: 0x… }"]
    F --> G["agent cites receipt_tx"]
    G --> H["receipt_verify(0x…)"]
    H --> I["block time + amount on Injective"]

Spending is auditable in-conversation via wc_spend_ledger (and wc://ledger). Failures teach: INSUFFICIENT_USDC carries the CCTP runbook; SPEND_CAP_HIT carries the cap and how to raise it (ask the human — the agent never raises its own).

💰 Funding the agent wallet

wc_edge needs a few cents of USDC on Injective. Generate a throwaway payer wallet and fund it via CCTP:

npx cuporacle-mcp init          # prints a fresh wallet address + key

Then call wallet_fund_guide (or ask your agent to) for the CCTP steps, executed with the Injective MCP server: account_balances → cctp_supported_chains → burn on Base (domain 6) → cctp_attestation_status → cctp_mint. Fund only cents; the default cap is 0.50 USDC.

🧑‍💻 Development

npm install
npm run smoke  # cold-start over stdio, list 8 tools/2 resources/1 prompt, one live call
npm test       # 63 vitest (schemas, spend cap, 402-parse, EIP-3009 sign, receipts, degrade)
npm run bench  # cache hit/miss + wc_edge dry_run (parse+sign) p50/p95
npm run build  # tsup → dist (publish-ready)
SMOKE_BIN=dist npm run smoke  # smoke the built artifact

npm run paid-call-smoke runs a real paid wc_edge end-to-end — it is funds-gated behind CUPORACLE_ALLOW_PAID=1 and a funded key, and otherwise falls back to a dry run.

🧪 Engineering harness & CI

This is a published npm library, not a web app — so the pipeline swaps the usual browser E2E / Lighthouse stages for the two proofs that actually matter for a stdio MCP server: a cold-start over real stdio (npm run smoke) and official MCP Inspector protocol conformance against the built dist/.

Multi-stage CI: Quality → Security → Build → MCP Conformance → Publish-readiness.

# ── Quality ─────────────────────────────────
npm run typecheck   # tsc --noEmit (strict)
npm test            # vitest — 63 passing
npm run ci          # typecheck + test + build + smoke (local gate)

# ── MCP "E2E" (no browser — this is the end-to-end proof) ──
npm run smoke       # cold-start over stdio → 8 tools / 2 resources / 1 prompt + a live free call
npm run inspector   # official MCP Inspector conformance against dist/
SMOKE_BIN=dist npm run smoke   # smoke the exact built artifact npm ships

# ── Security ────────────────────────────────
make security-scan  # npm audit + license-checker (no GPL/AGPL in prod deps)

No Playwright / Lighthouse — there is no browser surface to drive or audit. The equivalent guarantee is the stdio smoke + Inspector conformance above, both run in CI on every push and PR. Also see make help for the full target list.

⚙️ Configuration

🧩 Extend it (add your own sport)

Each tool is { name, config, handler } (src/tools/). To add, say, a cricket server: copy a free tool, swap the data client in src/data/, register it in src/tools/index.ts. The x402 client (src/x402/) is sport-agnostic — reuse it to sell any premium signal. PRs welcome.

⚠️ Honest limitations

1. wc_edge depends on LineLock's /api/edge (a disclosed sibling project). If it's down, wc_edge degrades to free odds — it never fabricates an edge.

2. Free-tier data APIs cap request rates → 60s cache + committed snapshots (always labeled [snapshot]).

3. The payer keystore holds a real (tiny) balance. Spend caps default low; fund only cents. Windows keystore paths are documented, not hardened.

📄 License

MIT. "Football data provided by the Football-Data.org API."