Optionality MCP Server

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

1. 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.
2. 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.
3. 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:

License

Apache 2.0 — see LICENSE and NOTICE.