{
  "markdown": "# optionality-mcp\n\n[MCP](https://modelcontextprotocol.io/) server and React drill UI for an AI-judged options trading practice game. Built on [FastMCP](https://github.com/jlowin/fastmcp).\n\nOptionality is an instance of a [Tollbooth-DPYC](https://tollbooth-dpyc.com)™ service: engagement is monetized with convenient Don't Pester Your Customer™ (DPYC™) Bitcoin commerce. Patrons pre-fund a balance over Lightning and play without per-request payment ceremonies. All prices are dynamic and set by the operator — the Welcome page shows live quotes. Patrons can also enter Tollbooth-DPYC coupons to take advantage of discounts when they are offered.\n\n## How a Round Works\n\n1. **The Dealer deals.** A *dealer* LLM composes a complete options scenario: ticker, spot, IV regime and skew, macro backdrop, catalyst, key levels, and constraints — optionally including a max-loss budget the structure must fit.\n2. **You pitch.** Free text, the way you'd pitch a senior PM. Multi-leg structures, single legs, or a deliberate stand-aside — declining to trade is a legitimate, gradeable answer.\n3. **The Judge grades.** A *judge* LLM parses your pitch into structured legs, scores it across six dimensions, and proposes an alternative structure you can overlay on the risk chart.\n\n**Six judging dimensions:** Strategy Selection, Strikes & Tenor, Risk/Reward, Macro Integration, Tail Risk, and Communication — each 0–20, rolled into a 0–100 score with letter grades A+ through F.\n\n## Core Pedagogy — Red Herrings\n\nEach scenario embeds 1–2 facts that are factually TRUE but immaterial, woven inline into the narrative and never flagged. Citing them as trade drivers penalizes the trainee; recognizing them as noise and setting them aside earns points. The drill is signal-from-noise on a tape where everything you read is true.\n\nA **Facts Ledger** accompanies every evaluation: which scenario facts you integrated, which you missed, which red herrings you caught, and which you followed.\n\n## Scenario Modes & Difficulty\n\n**Three historicity modes:**\n\n- **Historical Fiction** — real, identifiable market moments (SVB week, the gilt crisis), grounded in the actual macro and IV regime of the day\n- **Fiction** — invented regimes: counterfactual shocks, de-peg cascades, gamma squeezes\n- **Live Events** — web-search-grounded scenarios anchored to this week's actual tape, with cited sources\n\n**Four difficulty personas:** Apprentice, Journeyman, Adept, Sovereign. Leaderboard points are difficulty-weighted, so rankings can't be padded on easy mode. A **Mulligan** mode replays an already-judged scenario fresh.\n\n## Options Math — One Source of Truth\n\nThe server builds the full option chain from the dealer's scaffold — three expirations, a strike ladder around spot, a three-anchor IV smile honoring put-bid skew — and prices it with Black–Scholes. The same math runs client-side, so the trainee, the charts, and the judge all see identical numbers.\n\n- **Option chain modal** in broker convention: calls left, strikes and smile center, puts right; tap a mid to buy or sell; running net-premium readout\n- **Risk profile chart** with expiration P/L, breakeven markers, and a DTE slider that replays theta bleed across the holding period\n- **Judge-alternative overlay** to compare your payoff curve against the structure the judge would have run\n\n## Socratic Clue Desk\n\nMid-scenario, ask anything. Educational questions get direct, formula-backed answers; tactical questions get redirected to the dimension worth more thought — the responsibility stays with the trainee. The desk never reveals the scenario's hidden facts or red herrings. Clues carry a scoring penalty.\n\n## Journal, Leaderboard & Peer Learning\n\n- **Journal** — every round persisted: open drafts, submitted pitches, full evaluations with leg tables and charts\n- **Leaderboard** — six sort orders (weighted average, weighted best, raw average, raw best, streak, played), filterable by mode and difficulty\n- **Streaks** — consecutive scores of 70+, current and all-time\n- **Shared entries** — opt in to share an evaluated round so others can study the pitch, the grade, and the ledger\n- **Profile** — display name, avatar, bio\n- **Usage** — transparency tab showing per-model token consumption, per-tool spend, and the patron's account statement\n\n## Repo Layout\n\n```\noptionality-mcp/\n├── server.py    # FastMCP SSE server (Python) → Horizon\n├── tools/       # dealer, judge, journal, leaderboard, profile, options chain\n├── prompts.py   # dealer / judge / clue-desk personas\n└── frontend/    # React 18 + Vite + TS UI → Cloudflare Pages\n```\n\nHeavy LLM tools (deal, judge, clue desk) use a claim-check async pattern: the call returns a claim immediately and the client polls a free fetch tool, so slow generations survive client timeouts.\n\n## DPYC Ecosystem\n\n`optionality-mcp` is one Operator in the DPYC federation — independent MCP servers that share a Nostr identity model, Bitcoin Lightning payments, and the `tollbooth-dpyc` SDK. Peer repos:\n\n| Repo | Role |\n|---|---|\n| [tollbooth-dpyc](https://github.com/lonniev/tollbooth-dpyc) | Python SDK — vault, auth, pricing, Lightning, Nostr identity |\n| [dpyc-community](https://github.com/lonniev/dpyc-community) | Governance registry: membership, advisories, threat model |\n| [dpyc-oracle](https://github.com/lonniev/dpyc-oracle) | Community concierge (free onboarding + member lookup) |\n| [tollbooth-authority](https://github.com/lonniev/tollbooth-authority) | Certification backbone (Schnorr-signed certificates) |\n| [tollbooth-sample](https://github.com/lonniev/tollbooth-sample) | Sample Operator (canonical template) |\n| [tollbooth-pricing-studio](https://github.com/lonniev/tollbooth-pricing-studio) | iOS pricing-model editor / operator console |\n| [cypher-mcp](https://github.com/lonniev/cypher-mcp) | Monetized graph answers: named Cypher templates over Neo4j/AuraDB |\n| [schwab-mcp](https://github.com/lonniev/schwab-mcp) | Charles Schwab brokerage data |\n| [thebrain-mcp](https://github.com/lonniev/thebrain-mcp) | TheBrain personal knowledge graph |\n| [excalibur-mcp](https://github.com/lonniev/excalibur-mcp) | X/Twitter posting |\n| [taxsort-mcp](https://github.com/lonniev/taxsort-mcp) | Tax classification + Cloudflare Pages UI |\n| [optionality-mcp](https://github.com/lonniev/optionality-mcp) | Options analytics (brokerage-data Operator) |\n| [tollbooth-oauth2-collector](https://github.com/lonniev/tollbooth-oauth2-collector) | OAuth2 callback handler (advocate service) |\n| [tollbooth-shortlinks](https://github.com/lonniev/tollbooth-shortlinks) | URL shortener utility |\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).\n",
  "bytes": 6806,
  "sha": "dde4ee1e7b611a4151155ff77041739adc56f1ea91a8356613f6844bfbfe0e3b",
  "repo_slug": "lonniev/optionality-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lonniev_optionality_mcp_275d8b6f/readme"
}