optionality-mcp
MCP server and React drill UI for an AI-judged options trading practice game. Built on FastMCP.
Optionality is an instance of a Tollbooth-DPYC™ 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.
How a Round Works
- 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.
- 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.
- 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.
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.
Core Pedagogy — Red Herrings
Each 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.
A Facts Ledger accompanies every evaluation: which scenario facts you integrated, which you missed, which red herrings you caught, and which you followed.
Scenario Modes & Difficulty
Three historicity modes:
- Historical Fiction — real, identifiable market moments (SVB week, the gilt crisis), grounded in the actual macro and IV regime of the day
- Fiction — invented regimes: counterfactual shocks, de-peg cascades, gamma squeezes
- Live Events — web-search-grounded scenarios anchored to this week's actual tape, with cited sources
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.
Options Math — One Source of Truth
The 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.
- 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
- Risk profile chart with expiration P/L, breakeven markers, and a DTE slider that replays theta bleed across the holding period
- Judge-alternative overlay to compare your payoff curve against the structure the judge would have run
Socratic Clue Desk
Mid-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.
Journal, Leaderboard & Peer Learning
- Journal — every round persisted: open drafts, submitted pitches, full evaluations with leg tables and charts
- Leaderboard — six sort orders (weighted average, weighted best, raw average, raw best, streak, played), filterable by mode and difficulty
- Streaks — consecutive scores of 70+, current and all-time
- Shared entries — opt in to share an evaluated round so others can study the pitch, the grade, and the ledger
- Profile — display name, avatar, bio
- Usage — transparency tab showing per-model token consumption, per-tool spend, and the patron's account statement
Optional Nsec Escrow
A patron on a device without a NIP-07 signer (an iPad, say) can opt in to let Optionality hold a game-scoped nsec and sign Nostr DMs for them. escrow_nsec deposits a freshly generated nsec (it must derive to the patron's npub), encrypted at rest and bound to that npub; send_patron_dm signs and publishes a DM as the patron with it; get_escrow_status says whether one is held; withdraw_nsec returns the nsec once and deletes it, after which the patron keeps the key in their own Nostr client. Self-custody with a NIP-07 signer needs none of this.
Repo Layout
optionality-mcp/
├── server.py # FastMCP server (Python) → Horizon
├── tools/ # dealer, judge, journal, leaderboard, profile, options chain, nsec escrow
├── db/ # Neon persistence (journal, leaderboard, patrons, usage, migrations)
├── llm.py # server-side LLM client (operator's vaulted llm_api_key)
├── prompts.py # dealer / judge / clue-desk personas
├── modal_app.py # detached runner for the LLM drills (Modal)
└── frontend/ # React 19 + Vite + TS UI → Cloudflare Pages
Heavy 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. When the operator has delivered Modal credentials, those jobs run detached on Modal (modal_app.py) instead of on the MCP host.
DPYC Ecosystem
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: