quiniela-mcp 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# World Cup 2026 — Quiniela + Prediction Markets
+
+Two **completely separate** games in one dark, Polymarket-styled app:
+
+1. **Quiniela** — free score-prediction pool with stage-weighted scoring, Jokers,
+   perfect-round and champion bonuses, a live leaderboard, and a dynamic knockout bracket.
+2. **Prediction Markets** — a peer-to-peer binary (YES/NO) exchange played with admin-granted
+   **credits**, settled at the end of the tournament.
+
+- **Backend** — FastAPI + SQLite + JWT auth (`backend/`)
+- **Frontend** — React + Vite SPA, dark themed (`frontend/`)
+
+## Quick start
+
+### Backend
+```bash
+cd backend
+python -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+uvicorn app.main:app --reload
+```
+API + Swagger docs at http://localhost:8000/docs. A seed admin (`admin` / `admin123`),
+sample teams and matches across every stage are created on first startup.
+
+### Frontend
+```bash
+cd frontend
+npm install
+cp .env.example .env
+npm run dev
+```
+App at http://localhost:5173 (it proxies `/api` to the backend).
+
+## How scoring works
+See `backend/app/scoring.py` and `backend/app/bonuses.py`.
+
+**Per match** — accuracy scaled by a **stage multiplier** (group ×1 … final ×5):
+
+| Result | Base points |
+|---|---|
+| Exact scoreline | 3 |
+| Correct outcome (win/draw/loss) | 1 |
+| Wrong | 0 |
+
+`match_points = round(base × stage_multiplier)`, then **×2 if you played your Joker** on it.
+
+**Bonuses**
+- 🃏 **Joker** — one per group (and one per knockout round); doubles that match's points.
+- 🎯 **Perfect round** — get every game in a group (or a full knockout round) correct → **+5**.
+- 🏆 **Champion** — correctly pick the tournament winner → **+10** (locks at first kickoff,
+  or whenever the admin locks it).
+
+All constants live in `scoring.py` and are easy to tune.
+
+## Data
+Seeded from the real 2026 World Cup final draw (5 Dec 2025): 48 teams across
+Groups A–L with country flags (via flagcdn.com) and all 72 group-stage fixtures.
+Results are blank until entered.
+
+## Pages
+
+**Quiniela**
+- **Predict** — picks grouped by group → matchday, each with a live **countdown** + lock; one
+  **Joker** per round; a **champion** picker. Once a match locks, reveal **everyone's** picks.
+- **Groups** — live standings tables: P / W / D / L / GF / GA / GD / Pts.
+- **Bracket** — knockout slots that **populate dynamically**; admins assign teams as they
+  qualify (no preselection); predictable once both teams are set.
+- **Leaderboard** — **live**, with a points breakdown (match / 🎯 / 🏆 / total).
+- **Profile** — your stats.
+
+**Prediction Markets** (credits, separate)
+- **Markets** — per-match YES/NO markets as Polymarket-style cards with implied-probability bars.
+- **Market detail** — order book: **make** an offer (pick a side + price + shares) or **take**
+  the other side of any offer (partial fills). Admins resolve YES/NO.
+- **Wallet** — balance, locked, granted, and net.
+
+**Shared / admin**
+- **Rules** — the full rules of each game, side by side.
+- **Admin** — enter results, sync from the live feed, lock champion picks, set the winner.
+- **Dashboard** (admin) — grant credits and view the settlement table (granted vs balance vs net).
+
+## Auto-syncing results
+The Admin "Sync now" button calls `POST /admin/sync-results`, which pulls finished scores from a
+free no-key feed (`RESULTS_API_URL`, default [worldcup26.ir](https://worldcup26.ir/get/games)),
+matches them to our fixtures by group + team names, and recomputes points. You can always enter
+or override results by hand.
+
+## Typical flow
+1. Register / log in (a seeded `admin` / `admin123` account can enter results).
+2. Players enter scores, place a Joker per round, and pick a champion (before kickoff).
+3. Results arrive via the Admin **Sync** button (or manual entry / `POST /matches/{id}/result`).
+4. Points + bonuses recompute automatically — watch the live Leaderboard, Groups, and Profile.

package/mcp-server-node/README.md

@@ -0,0 +1,75 @@
+# Quiniela MCP server (Node / npm)
+
+An MCP server that lets agents play the World Cup 2026 quiniela + prediction
+markets. Node 18+ only — no Python, no build step. Defaults to the public
+deployment, so it works with zero config.
+
+## Use it (other people — the easy way)
+
+Add this to your MCP client config (Claude Desktop, Claude Code, Cursor, …):
+
+```json
+{
+  "mcpServers": {
+    "quiniela": {
+      "command": "npx",
+      "args": ["-y", "quiniela-mcp"]
+    }
+  }
+}
+```
+
+`npx` downloads and runs it on demand — nothing to install. (Works once the
+package is published to npm; see *Publishing* below.)
+
+**No npm publish?** Point `npx` straight at the GitHub repo instead:
+
+```json
+{
+  "mcpServers": {
+    "quiniela": {
+      "command": "npx",
+      "args": ["-y", "github:davidesquer/quiniela-driven-development"]
+    }
+  }
+}
+```
+
+Then just tell your agent things like *"using the quiniela tools, show the
+leaderboard"*, *"log in as <user>/<pass> and predict 2–1 on match 1, joker it"*,
+or *"place a YES offer at 0.6 for 10 shares on the Over 2.5 market for game X"*.
+
+## Auth
+- Read-only tools (`standings`, `leaderboard`, `markets_overview`, `list_matches`)
+  need no login.
+- Player/admin tools: have the agent call `login(username, password)` first, or
+  add `"env": { "QUINIELA_USERNAME": "...", "QUINIELA_PASSWORD": "..." }` to the
+  config (use a dedicated bot account, not your admin password).
+- Point at a local backend with `"env": { "QUINIELA_API_URL": "http://localhost:8010/api" }`.
+
+## Run from a clone (dev)
+```bash
+npm install          # at the repo root (installs the MCP deps)
+node mcp-server-node/index.js
+```
+The repo's `.mcp.json` already uses this, so Claude Code auto-discovers it.
+
+## Publishing (so anyone can `npx quiniela-mcp`)
+The package lives at the repo root (`package.json`, name `quiniela-mcp`).
+```bash
+npm login
+npm publish        # publishes just mcp-server-node/ (see "files")
+```
+After that, `npx -y quiniela-mcp` works for everyone.
+
+## Tools (29)
+Auth: `login`, `register`, `whoami` · Quiniela: `list_matches`,
+`submit_prediction`, `set_joker`, `my_predictions`, `set_champion`, `standings`,
+`leaderboard`, `profile`, `match_predictions` · Markets: `markets_overview`,
+`list_markets`, `market_detail`, `make_offer`, `take_offer`, `cancel_order`,
+`wallet` · Admin: `admin_set_result`, `admin_assign_knockout`,
+`admin_remove_knockout`, `admin_add_market`, `admin_resolve_market`,
+`admin_grant_credits`, `admin_list_users`, `admin_settlement`,
+`admin_set_tournament_winner`, `admin_sync_results`.
+
+> A Python/uv version of the same server lives in `../mcp-server` if you prefer it.

package/mcp-server-node/index.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// MCP server for the World Cup 2026 quiniela + prediction markets (Node).
+// Exposes the API as tools so agents can play. Uses Node's built-in fetch.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API = (
+  process.env.QUINIELA_API_URL || "https://quiniela-wc26.onrender.com/api"
+).replace(/\/+$/, "");
+let TOKEN = process.env.QUINIELA_TOKEN || null;
+
+async function doLogin(username, password) {
+  const r = await fetch(`${API}/auth/login`, {
+    method: "POST",
+    body: new URLSearchParams({ username, password }),
+  });
+  if (!r.ok) throw new Error(`login failed: ${await r.text()}`);
+  TOKEN = (await r.json()).access_token;
+}
+
+async function ensureAuth() {
+  if (TOKEN) return;
+  const u = process.env.QUINIELA_USERNAME;
+  const p = process.env.QUINIELA_PASSWORD;
+  if (u && p) await doLogin(u, p);
+}
+
+async function req(method, path, { auth = true, json, params } = {}) {
+  if (auth) await ensureAuth();
+  let url = API + path;
+  if (params) url += "?" + new URLSearchParams(params);
+  const headers = {};
+  if (auth && TOKEN) headers["Authorization"] = `Bearer ${TOKEN}`;
+  let body;
+  if (json !== undefined) {
+    headers["Content-Type"] = "application/json";
+    body = JSON.stringify(json);
+  }
+  const r = await fetch(url, { method, headers, body });
+  const text = await r.text();
+  if (!r.ok) throw new Error(`HTTP ${r.status} ${path}: ${text}`);
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function brief(m) {
+  return {
+    id: m.id,
+    stage: m.stage,
+    round_key: m.round_key,
+    kickoff: m.kickoff,
+    status: m.status,
+    home: m.home_team?.name ?? null,
+    away: m.away_team?.name ?? null,
+    score: m.home_score != null ? `${m.home_score}-${m.away_score}` : null,
+  };
+}
+
+// name, description, zod schema, handler returning data (string|object)
+const tools = [
+  // --- auth ---
+  ["login", "Authenticate and store a bearer token.",
+    { username: z.string(), password: z.string() },
+    async ({ username, password }) => {
+      await doLogin(username, password);
+      const me = await req("GET", "/auth/me");
+      return `Logged in as ${me.username} (admin=${me.is_admin}).`;
+    }],
+  ["whoami", "Current authenticated user.", {}, () => req("GET", "/auth/me")],
+  ["register", "Create a new player account.",
+    { username: z.string(), password: z.string() },
+    ({ username, password }) =>
+      req("POST", "/auth/register", { auth: false, json: { username, password } })],
+
+  // --- quiniela ---
+  ["list_matches", "List matches (brief). Optional stage filter (group, round_of_32, round_of_16, quarter, semi, third_place, final).",
+    { stage: z.string().optional() },
+    async ({ stage }) => {
+      const ms = await req("GET", "/matches", { auth: false });
+      return (stage ? ms.filter((m) => m.stage === stage) : ms).map(brief);
+    }],
+  ["submit_prediction", "Submit/update your scoreline prediction for a match (locks at kickoff).",
+    { match_id: z.number(), home_score: z.number(), away_score: z.number() },
+    ({ match_id, home_score, away_score }) =>
+      req("POST", "/predictions", { json: { match_id, pred_home: home_score, pred_away: away_score } })],
+  ["set_joker", "Play your one Joker (x2 points) for this match's group.",
+    { match_id: z.number() },
+    ({ match_id }) => req("POST", `/predictions/${match_id}/joker`)],
+  ["my_predictions", "Your current quiniela predictions.", {}, () => req("GET", "/predictions")],
+  ["set_champion", "Pick the tournament champion (+10; locks at first kickoff).",
+    { team_id: z.number() },
+    ({ team_id }) => req("POST", "/champion", { json: { team_id } })],
+  ["standings", "Group standings tables.", {}, () => req("GET", "/standings", { auth: false })],
+  ["leaderboard", "Quiniela leaderboard with breakdown.", {}, () => req("GET", "/leaderboard", { auth: false })],
+  ["profile", "Your quiniela stats.", {}, () => req("GET", "/profile")],
+  ["match_predictions", "Everyone's picks for a match (only once it has locked).",
+    { match_id: z.number() },
+    ({ match_id }) => req("GET", `/matches/${match_id}/predictions`, { auth: false })],
+
+  // --- markets ---
+  ["markets_overview", "All games that have markets, with summaries.", {},
+    () => req("GET", "/markets/overview", { auth: false })],
+  ["list_markets", "Markets for a match.",
+    { match_id: z.number() },
+    ({ match_id }) => req("GET", "/markets", { auth: false, params: { match_id } })],
+  ["market_detail", "Order book, recent fills, and your position for a market.",
+    { market_id: z.number() },
+    ({ market_id }) => req("GET", `/markets/${market_id}`)],
+  ["make_offer", "Post an offer to back a side (side=YES|NO, price 0..1) for N shares.",
+    { market_id: z.number(), side: z.enum(["YES", "NO"]), price: z.number(), shares: z.number() },
+    ({ market_id, side, price, shares }) =>
+      req("POST", `/markets/${market_id}/orders`, { json: { side, price, shares } })],
+  ["take_offer", "Take the opposite side of an existing offer (partial fills allowed).",
+    { order_id: z.number(), shares: z.number() },
+    ({ order_id, shares }) => req("POST", `/orders/${order_id}/take`, { json: { shares } })],
+  ["cancel_order", "Cancel your own open offer (refunds unmatched escrow).",
+    { order_id: z.number() },
+    ({ order_id }) => req("DELETE", `/orders/${order_id}`)],
+  ["wallet", "Your credits wallet: balance / locked / granted / net.", {}, () => req("GET", "/wallet")],
+
+  // --- admin ---
+  ["admin_set_result", "(admin) Set a match result; recomputes points.",
+    { match_id: z.number(), home_score: z.number(), away_score: z.number() },
+    ({ match_id, home_score, away_score }) =>
+      req("POST", `/matches/${match_id}/result`, { json: { home_score, away_score } })],
+  ["admin_assign_knockout", "(admin) Assign two teams to a knockout slot.",
+    { match_id: z.number(), home_team_id: z.number(), away_team_id: z.number() },
+    ({ match_id, home_team_id, away_team_id }) =>
+      req("POST", `/matches/${match_id}/teams`, { json: { home_team_id, away_team_id } })],
+  ["admin_remove_knockout", "(admin) Clear a knockout matchup (voids/refunds its markets + predictions).",
+    { match_id: z.number() },
+    ({ match_id }) => req("DELETE", `/matches/${match_id}/teams`)],
+  ["admin_add_market", "(admin) Add a custom YES/NO market to a match.",
+    { match_id: z.number(), question: z.string(), category: z.string().optional() },
+    ({ match_id, question, category }) =>
+      req("POST", "/markets", { json: { match_id, question, category: category || "custom" } })],
+  ["admin_resolve_market", "(admin) Resolve a market; pays winners, refunds unmatched.",
+    { market_id: z.number(), outcome_yes: z.boolean() },
+    ({ market_id, outcome_yes }) =>
+      req("POST", `/markets/${market_id}/resolve`, { json: { outcome: outcome_yes } })],
+  ["admin_grant_credits", "(admin) Grant credits to a user (buy-in).",
+    { user_id: z.number(), amount: z.number(), note: z.string().optional() },
+    ({ user_id, amount, note }) =>
+      req("POST", "/admin/credits", { json: { user_id, amount, note: note || null } })],
+  ["admin_list_users", "(admin) List users.", {}, () => req("GET", "/admin/users")],
+  ["admin_settlement", "(admin) Settlement dashboard.", {}, () => req("GET", "/admin/settlement")],
+  ["admin_set_tournament_winner", "(admin) Record the actual champion (+10 bonus).",
+    { team_id: z.number() },
+    ({ team_id }) => req("POST", "/tournament/champion", { json: { team_id } })],
+  ["admin_sync_results", "(admin) Pull finished scores from the live feed.", {},
+    () => req("POST", "/admin/sync-results")],
+];
+
+const server = new McpServer({ name: "quiniela", version: "0.1.0" });
+for (const [name, desc, schema, fn] of tools) {
+  server.tool(name, desc, schema, async (args) => {
+    const data = await fn(args || {});
+    return {
+      content: [
+        { type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) },
+      ],
+    };
+  });
+}
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "quiniela-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the FIFA World Cup 2026 quiniela + prediction markets — lets agents make predictions and trade markets.",
+  "type": "module",
+  "bin": {
+    "quiniela-mcp": "mcp-server-node/index.js"
+  },
+  "files": [
+    "mcp-server-node"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["mcp", "model-context-protocol", "world-cup", "quiniela", "prediction-markets"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidesquer/quiniela-driven-development.git"
+  },
+  "homepage": "https://github.com/davidesquer/quiniela-driven-development/tree/main/mcp-server-node#readme",
+  "bugs": {
+    "url": "https://github.com/davidesquer/quiniela-driven-development/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  }
+}