{"id":51699091,"url":"https://github.com/edycutjong/cuporacle-mcp","last_synced_at":"2026-07-16T08:33:47.422Z","repository":{"id":370929684,"uuid":"1297906970","full_name":"edycutjong/cuporacle-mcp","owner":"edycutjong","description":"World Cup MCP server: live fixtures, scores, odds \u0026 knockout bracket as free tools — plus wc_edge, an agent that pays 0.05 USDC via Injective x402 by itself and cites the on-chain receipt. 8 tools · 2 resources · 1 prompt over stdio.","archived":false,"fork":false,"pushed_at":"2026-07-12T11:44:57.000Z","size":12039,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-16T08:33:42.969Z","etag":null,"topics":["agent","cctp","football","injective","mcp","model-context-protocol","soccer","typescript","usdc","world-cup","x402"],"latest_commit_sha":null,"homepage":"https://cuporacle.edycu.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edycutjong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-12T01:53:04.000Z","updated_at":"2026-07-12T11:43:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/edycutjong/cuporacle-mcp","commit_stats":null,"previous_names":["edycutjong/cuporacle-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/edycutjong/cuporacle-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fcuporacle-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fcuporacle-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fcuporacle-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fcuporacle-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edycutjong","download_url":"https://codeload.github.com/edycutjong/cuporacle-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fcuporacle-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35537751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","cctp","football","injective","mcp","model-context-protocol","soccer","typescript","usdc","world-cup","x402"],"created_at":"2026-07-16T08:33:44.063Z","updated_at":"2026-07-16T08:33:47.394Z","avatar_url":"https://github.com/edycutjong.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/readme-hero-animated.svg\" alt=\"CupOracle — the missing World Cup MCP server: an agent asks, the tools fire, x402 pays, and the receipt lands on Injective\" width=\"100%\" /\u003e\n\n# cuporacle-mcp\n\n**Your AI assistant is football-blind during the biggest event on earth** — it can't see tonight's World Cup match, has no odds, and has no way to pay for premium data itself.\u003cbr/\u003e\n**CupOracle is a published MCP server that fixes that:** live FIFA World Cup 2026 fixtures, scores, consensus odds and the knockout bracket as **free** tools — plus **`wc_edge`, an agent that pays 0.05 USDC via Injective x402 _by itself_** (under a spend cap) and cites the on-chain receipt.\u003cbr/\u003e\n**Shipped:** 8 tools · 2 resources · 1 prompt over stdio · 63 vitest · MCP-Inspector-conformant in CI · publish-ready npm package.\n\n[![Pitch Deck](https://img.shields.io/badge/Pitch%20Deck-PDF-E91E8C?logo=adobeacrobatreader\u0026logoColor=white)](PITCH.pdf)\n[![CI](https://github.com/edycutjong/cuporacle-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/edycutjong/cuporacle-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/badge/npm-after%20publish-9e9e9e?logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/cuporacle-mcp)\n[![docs](https://img.shields.io/badge/docs-after%20deploy-9e9e9e)](docs/index.html)\n[![License: MIT](https://img.shields.io/badge/License-MIT-2ea44f)](LICENSE)\n\n\u003c/div\u003e\n\n📊 **[Pitch deck (PDF)](PITCH.pdf)** · [interactive HTML](PITCH.html) — the 10-slide story (arrow keys · press `P` to print).\n\n```bash\n# Claude Code — the 4 free data tools work with just two free API keys\nclaude mcp add cuporacle -- npx -y cuporacle-mcp\n```\n\n`cuporacle-mcp` is a standalone [Model Context Protocol](https://modelcontextprotocol.io)\nserver that runs **side by side with the Injective MCP server**: **8 tools + 2\nresources + 1 prompt** over stdio. Free data tools work out of the box; `wc_edge`\nis a reference implementation of an agent *buying and proving its own alpha*\nkeylessly via Injective's x402.\n\n## 🧑‍⚖️ Notes for judges — reproduce in \u003c 5 min\n\n- **Zero-cost path.** The four free tools (`wc_fixtures`, `wc_live`, `wc_odds`,\n  `wc_bracket`) return **real live World Cup 2026 data** with just the two free\n  API keys — no wallet, no funds.\n- **The x402 buyer path runs with _zero funds_.** `wc_edge(matchId, dry_run: true)`\n  (or `npm run paid-call-smoke`) parses the **recorded 402 quote**, enforces the\n  spend cap, and signs the EIP-3009 authorization **locally** — a deterministic\n  proof of the payment client with **no money moved and no fabricated receipt**.\n- **\u003c 5-minute reproduce:**\n  ```bash\n  npm install\n  npm run smoke      # cold-start over stdio → lists 8 tools/2 resources/1 prompt + a live free call\n  npm test           # 63 vitest (schemas · spend cap · 402-parse · EIP-3009 sign · receipts · degrade)\n  npm run inspector  # official MCP Inspector conformance against the built dist/\n  ```\n- **Honestly gated (not faked):** a *real settled* `wc_edge` payment needs a few\n  cents of USDC on Injective (funding is user-gated) plus the live EdgeLedger\n  upstream. Until then `wc_edge` **degrades to free odds** and never invents an\n  edge or a receipt — full honest state in [`STATUS.md`](STATUS.md).\n\n---\n\n## Why this exists\n\nAgents have no first-class sports capability. Injective's own MCP server covers\nwallets, markets, CCTP and trading — but an agent asked *\"is tonight's match\nworth a bet?\"* has to hallucinate or scrape, and there's no pattern for an agent\n*paying for premium data itself*. CupOracle is that missing layer, built as a\ncomposable server that runs **side by side** with the Injective MCP server.\n\n## Tools\n\n| Tool | Gate | Returns |\n|---|---|---|\n| `wc_fixtures(date?)` | free | fixtures for a day or the next upcoming window |\n| `wc_live(matchId)` | free | live score, minute, status |\n| `wc_odds(matchId)` | free | consensus h2h odds + de-vigged implied probabilities |\n| `wc_bracket()` | free | knockout bracket state (R16 → Final) |\n| `wc_edge(matchId, maxSpend?, dry_run?)` | **pays x402** | CLV-audited edge + conviction ladder + **receipt tx** |\n| `receipt_verify(txHash)` | free | verifies a receipt on Injective EVM (block time, amount, payee) |\n| `wallet_fund_guide(chain?)` | free | CCTP runbook to fund the agent wallet |\n| `wc_spend_ledger()` | free | the agent's own purchase history: entries + receipts + session total vs cap |\n\n**Resources:** `wc://bracket`, `wc://ledger` · **Prompt:** `analyze-match(matchId)`.\n\n## Quickstart\n\n### 1. Get keys\n- [football-data.org](https://www.football-data.org/) free tier → `FOOTBALL_DATA_KEY`\n- [the-odds-api.com](https://the-odds-api.com/) free tier → `ODDS_API_KEY`\n\nThe four **free** data tools work with just these two keys. `wc_edge` additionally\nneeds a payer wallet (see [Funding](#funding-the-agent-wallet)).\n\n### 2. Add to your harness\n\n**Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"cuporacle\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cuporacle-mcp\"],\n      \"env\": {\n        \"FOOTBALL_DATA_KEY\": \"…\",\n        \"ODDS_API_KEY\": \"…\",\n        \"CUPORACLE_PRIVATE_KEY\": \"0x…\",\n        \"CUPORACLE_MAX_SPEND\": \"0.50\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code:**\n```bash\nclaude mcp add cuporacle \\\n  -e FOOTBALL_DATA_KEY=… -e ODDS_API_KEY=… \\\n  -e CUPORACLE_PRIVATE_KEY=0x… -e CUPORACLE_MAX_SPEND=0.50 \\\n  -- npx -y cuporacle-mcp\n```\n\n**Cursor** (`.cursor/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"cuporacle\": { \"command\": \"npx\", \"args\": [\"-y\", \"cuporacle-mcp\"],\n      \"env\": { \"FOOTBALL_DATA_KEY\": \"…\", \"ODDS_API_KEY\": \"…\" } }\n  }\n}\n```\n\n### 3. Ask\n\u003e *\"What's tonight's Semi-Final, and is it worth a bet?\"*\n\nThe assistant lists the fixture (`wc_fixtures`), pulls odds (`wc_odds`), buys a\nvetted edge for ~5¢ (`wc_edge`) **paying via x402 itself**, and cites the\nreceipt. Paste that hash into `receipt_verify` to confirm the payment on Injective.\n\n## Injective technologies used\n\nCupOracle is Injective-native by construction — remove any layer and it's just a\nscraper or a hosted API with a billing page.\n\n| # | Technology | Exact surface | Where |\n|---|---|---|---|\n| 1 | **MCP Server** | Publishes a complete server (stdio): **8 tools + 2 resources + 1 prompt**, Inspector-conformance-checked. Extends the InjectiveLabs/mcp-server pattern and runs beside it. | the whole package |\n| 2 | **x402** | Autonomous **client**: parses the 402 quote (`accepts` / `PAYMENT-REQUIRED`), signs an **EIP-3009** transfer authorization, retries with `PAYMENT-SIGNATURE`, reads the receipt from `PAYMENT-RESPONSE`. Uses [`@injectivelabs/x402`](https://www.npmjs.com/package/@injectivelabs/x402) `./client` + `./eip3009`. | `src/x402/`, `wc_edge` |\n| 3 | **Agent Skills** | Ships the `cuporacle` Skill: tool-selection table, spend policy, fund-if-broke runbook. | `skills/cuporacle/SKILL.md` |\n| 4 | **USDC + CCTP** | Native USDC `0xa00C…235a` (Circle FiatTokenV2_2, EIP-3009). Funding path routes to the Injective MCP server's `cctp_supported_chains` → `cctp_attestation_status` → `cctp_mint`. | `wallet_fund_guide`, Skill |\n| 5 | **Injective EVM** | Mainnet `eip155:1776` (Blockscout + `sentry.evm-rpc.injective.network`), testnet `eip155:1439`. `receipt_verify` reads the tx over the EVM RPC. | `src/networks.ts`, `receipt_verify` |\n\n\u003e **Interop, not wrap.** CupOracle does **not** reimplement chain ops or wrap the\n\u003e Injective MCP tools as its own — both servers run in the same harness and the\n\u003e Skill routes funding to Injective's tools. Honesty over land-grab.\n\n## The autonomous-payment loop (`wc_edge`)\n\n```\nPOST /api/edge  ──▶  402 { accepts: [{ network: eip155:1776, amount: 50000, asset: USDC, payTo }] }\n      │\n      ├─ spend-cap gate  (per-call max · per-session cap · \"ask human above cap\")\n      ├─ sign EIP-3009 authorization  (local viem signTypedData — no broadcast)\n      ├─ retry with PAYMENT-SIGNATURE header\n      ▼\n200 { edge, ladder, pick_hash }  +  PAYMENT-RESPONSE { transaction: 0x… }\n      │\n      ▼   agent cites receipt_tx  ──▶  receipt_verify(0x…)  ──▶  block time + amount on Injective\n```\n\nSpending is **auditable in-conversation** via `wc_spend_ledger` (and `wc://ledger`).\nFailures teach: `INSUFFICIENT_USDC` carries the CCTP runbook; `SPEND_CAP_HIT`\ncarries the cap and how to raise it (ask the human — the agent never raises its own).\n\n## Funding the agent wallet\n\n`wc_edge` needs a few **cents** of USDC on Injective. Generate a throwaway payer\nwallet and fund it via CCTP:\n\n```bash\nnpx cuporacle-mcp init          # prints a fresh wallet address + key\n```\n\nThen call `wallet_fund_guide` (or ask your agent to) for the CCTP steps, executed\nwith the Injective MCP server: `account_balances → cctp_supported_chains → burn on\nBase (domain 6) → cctp_attestation_status → cctp_mint`. Fund only cents; the\ndefault cap is 0.50 USDC.\n\n## Development\n\n```bash\nnpm install\nnpm run smoke      # cold-start over stdio, list 8 tools/2 resources/1 prompt, one live call\nnpm test           # 63 vitest (schemas, spend cap, 402-parse, EIP-3009 sign, receipts, degrade)\nnpm run bench      # cache hit/miss + wc_edge dry_run (parse+sign) p50/p95\nnpm run build      # tsup → dist (publish-ready)\nSMOKE_BIN=dist npm run smoke   # smoke the built artifact\n```\n\n`npm run paid-call-smoke` runs a **real** paid `wc_edge` end-to-end — it is\nfunds-gated behind `CUPORACLE_ALLOW_PAID=1` and a funded key, and otherwise falls\nback to a dry run.\n\n## Configuration\n\n| Env | Default | Meaning |\n|---|---|---|\n| `FOOTBALL_DATA_KEY` | — | football-data.org key (free data tools) |\n| `ODDS_API_KEY` | — | the-odds-api.com key (odds) |\n| `CUPORACLE_PRIVATE_KEY` | — | payer wallet key for `wc_edge` (fund cents only) |\n| `CUPORACLE_MAX_SPEND` | `0.50` | per-session USDC spend cap |\n| `CUPORACLE_NETWORK` | `eip155:1776` | `eip155:1776` mainnet · `eip155:1439` testnet |\n| `EDGELEDGER_URL` | `https://edgeledger.edycu.dev` | upstream edge provider |\n\n## Extend it (add your own sport)\n\nEach tool is `{ name, config, handler }` (`src/tools/`). To add, say, a cricket\nserver: copy a free tool, swap the data client in `src/data/`, register it in\n`src/tools/index.ts`. The x402 client (`src/x402/`) is sport-agnostic — reuse it\nto sell any premium signal. PRs welcome.\n\n## Honest limitations\n\n1. `wc_edge` depends on EdgeLedger's `/api/edge` (a disclosed sibling project).\n   If it's down, `wc_edge` degrades to free odds — it never fabricates an edge.\n2. Free-tier data APIs cap request rates → 60s cache + committed snapshots\n   (always labeled `[snapshot]`).\n3. The payer keystore holds a real (tiny) balance. Spend caps default low; fund\n   only cents. Windows keystore paths are documented, not hardened.\n\n## License\n\nMIT. \"Football data provided by the Football-Data.org API.\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedycutjong%2Fcuporacle-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedycutjong%2Fcuporacle-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedycutjong%2Fcuporacle-mcp/lists"}