{"id":50384298,"url":"https://github.com/alvisooculus/optionsahoy-mcp","last_synced_at":"2026-05-30T14:00:45.102Z","repository":{"id":360389528,"uuid":"1249880417","full_name":"AlvisoOculus/optionsahoy-mcp","owner":"AlvisoOculus","description":"Multi-year equity-compensation optimization MCP server + REST API. Six tools (ISO/AMT, NSO, RSU, QSBS, concentration, protective puts). Full federal + 50-state + DC tax code.","archived":false,"fork":false,"pushed_at":"2026-05-26T07:14:42.000Z","size":133,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T08:34:00.111Z","etag":null,"topics":["ai-agents","anthropic","claude","cloudflare-pages-functions","equity-compensation","finance","mcp","mcp-server","model-context-protocol","openapi","optimization","tax-optimization"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlvisoOculus.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-05-26T05:44:50.000Z","updated_at":"2026-05-26T07:14:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AlvisoOculus/optionsahoy-mcp","commit_stats":null,"previous_names":["alvisooculus/optionsahoy-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AlvisoOculus/optionsahoy-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlvisoOculus%2Foptionsahoy-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlvisoOculus%2Foptionsahoy-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlvisoOculus%2Foptionsahoy-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlvisoOculus%2Foptionsahoy-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlvisoOculus","download_url":"https://codeload.github.com/AlvisoOculus/optionsahoy-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlvisoOculus%2Foptionsahoy-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33694714,"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-05-30T02:00:06.278Z","response_time":92,"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":["ai-agents","anthropic","claude","cloudflare-pages-functions","equity-compensation","finance","mcp","mcp-server","model-context-protocol","openapi","optimization","tax-optimization"],"created_at":"2026-05-30T14:00:42.278Z","updated_at":"2026-05-30T14:00:45.095Z","avatar_url":"https://github.com/AlvisoOculus.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OptionsAhoy MCP Server\n\n\u003e Equity comp tax (ISO/NSO/RSU/QSBS), concentration, and hedging optimizer. Six deterministic tools with federal + 50-state + DC tax code, multi-year horizons.\n\n**Live MCP endpoint:** `https://optionsahoy.com/mcp` (no auth, no install)\n**Live REST API:** `https://optionsahoy.com/api/v1`\n**OpenAPI 3.1 spec:** [`/openapi.json`](https://optionsahoy.com/openapi.json)\n**Discovery manifests:** [`/.well-known/mcp.json`](https://optionsahoy.com/.well-known/mcp.json) · [`/.well-known/openapi.json`](https://optionsahoy.com/.well-known/openapi.json)\n**Agent integration docs:** [optionsahoy.com/for-agents](https://optionsahoy.com/for-agents)\n\nBuilt by [AlphaLatitude Inc.](https://alphalatitude.com) — a pre-revenue beta-stage equity-compensation optimization product.\n\n---\n\n## What this is\n\nAn optimization engine for equity-compensation tax planning, exposed as both a Model Context Protocol (MCP) server and a plain REST API. Six tools:\n\n| Tool name | What it computes |\n|---|---|\n| `amt_iso_optimize` | Multi-year Incentive Stock Option (ISO) exercise schedule that minimizes federal and state Alternative Minimum Tax (AMT), with credit recovery across years |\n| `nso_calculate` | Non-qualified Stock Option (NSO) exercise tax + sell-vs-hold-for-LTCG comparison |\n| `rsu_sell_vs_hold` | RSU sell-at-vest vs hold-for-long-term-capital-gains decision |\n| `concentration_analyze` | Single-stock concentration risk + sell-down vs hold vs hedge optimization |\n| `protective_put_price` | Protective put / zero-cost collar pricing via Black-Scholes against implied volatility from a daily-refreshed option-chain snapshot |\n| `qsbs_check` | Section 1202 Qualified Small Business Stock (QSBS) qualification (eight statutory tests, OBBBA 2026 tiered exclusion) |\n\nEach tool returns the globally-optimal schedule across the candidate space — not heuristics, not samples. Coverage spans the full federal tax code (ordinary brackets, long-term capital gains, AMT with credit recovery, FICA, NIIT) plus all 50 states and DC (state ordinary brackets, LTCG treatment, state AMT for CA, NY, MN). Same engine as the in-browser calculators at [optionsahoy.com/tools](https://optionsahoy.com/tools); the API response is byte-identical to clicking through the tool.\n\n### MCP resources (topical briefings)\n\nSix markdown resources under `resources/list` give an LLM enough grounding to discuss the topic before picking a tool. Each maps 1:1 with a cornerstone article on [optionsahoy.com/learn](https://optionsahoy.com/learn) and the matching calculator.\n\n| Resource URI | Topic | Pair with |\n|---|---|---|\n| `https://optionsahoy.com/learn/amt-crossover` | ISO/AMT crossover and four expensive mistakes | `amt_iso_optimize` |\n| `https://optionsahoy.com/learn/nso-sell-vs-hold` | NSO sell-at-exercise vs hold-for-LTCG | `nso_calculate` |\n| `https://optionsahoy.com/learn/rsu-withholding-gap` | RSU 22% withholding gap and five April surprises | `rsu_sell_vs_hold` |\n| `https://optionsahoy.com/learn/single-stock-concentration-risk` | Concentration risk and diversification trade-off | `concentration_analyze` |\n| `https://optionsahoy.com/learn/zero-cost-collars` | Protective puts and zero-cost collars | `protective_put_price` |\n| `https://optionsahoy.com/learn/qsbs` | QSBS qualification and five ways to lose the exclusion | `qsbs_check` |\n\n### MCP prompts (workflow scaffolds)\n\nSix prompts under `prompts/list` scaffold typical user questions and route to the right tool. In Claude Desktop they appear as named slash-commands; in any MCP client, `prompts/get { name, arguments }` returns a fully-templated user message.\n\n| Prompt name | Routes to |\n|---|---|\n| `optimize-iso-exercise` | `amt_iso_optimize` |\n| `analyze-nso-decision` | `nso_calculate` |\n| `analyze-rsu-vest` | `rsu_sell_vs_hold` |\n| `analyze-concentration` | `concentration_analyze` |\n| `price-protective-put` | `protective_put_price` |\n| `check-qsbs-eligibility` | `qsbs_check` |\n\n## Why use an optimizer\n\nA benchmark of five frontier large language models on the same multi-year ISO exercise problem found that every one of 15 trials overshot the achievable after-tax outcome by 2x to 20x. Multi-year scheduling has a search space larger than an LLM can reason through in-context. Full write-up: [HackerNoon — But can it do taxes though?](https://hackernoon.com/but-can-it-do-taxes-though-why-you-shouldnt-trust-chatbots-with-tax-optimization-math)\n\n## Use from Claude / ChatGPT / Perplexity / any MCP client\n\nAdd the server as a remote HTTP MCP connection:\n\n```\nhttps://optionsahoy.com/mcp\n```\n\nOr via the [`add-mcp`](https://github.com/neon-solutions/add-mcp) CLI:\n\n```bash\nnpx add-mcp https://optionsahoy.com/mcp\n```\n\n## Use the REST API directly\n\n```bash\n# List endpoints\ncurl https://optionsahoy.com/api/v1\n\n# Run an optimization\ncurl -X POST https://optionsahoy.com/api/v1/amt-iso \\\n  -H \"content-type: application/json\" \\\n  -d @input.json\n```\n\nRequest body shapes are documented in [`public/openapi.json`](public/openapi.json).\n\n## Repository layout\n\n```\nfunctions/         Cloudflare Pages Functions (MCP server + REST API endpoints)\n  mcp.ts           HTTP MCP server\n  api/v1/*.ts      Six REST endpoints + GET /api/v1 discovery\n  _lib/*.ts        Shared helpers, calc-input parsers, MCP tool descriptors\nlib/               Optimizer + tax-code logic\n  calc/            Per-tool optimizer functions (computeAmtIso, etc.)\n  tax/             Federal + 50-state + DC bracket data, AMT, FICA, NIIT\n  markets/         Sector statistics\n  options/         Black-Scholes, risk-free rates\n  data/            Type definitions for option-chain data\npublic/            Static assets: OpenAPI spec, llms.txt, discovery manifests\ntests/             Vitest suites (873+ tests including byte-identity assertions)\n```\n\n## Run tests\n\n```bash\nnpm install\nnpm test         # 870+ tests, ~3s on a laptop\nnpm run typecheck\n```\n\n## Registry listings\n\n- [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=optionsahoy) — `io.github.AlvisoOculus/optionsahoy-mcp` v1.0.0, status active\n- [Smithery](https://smithery.ai/server/@alphalatitudeops/optionsahoy)\n- [add-mcp curated registry](https://github.com/neon-solutions/add-mcp)\n- [PulseMCP](https://www.pulsemcp.com) (cascades from Official Registry)\n\n## Use from Google Cloud (Gemini agents)\n\nGoogle Cloud Agent Registry lets each GCP project register external MCP servers for use by Gemini agents. Registration is per-project (no central submission). Two paths:\n\n```bash\n# Path A: let the Agent Registry introspect our MCP endpoint\ngcloud alpha agent-registry mcp-servers register \\\n  --uri=https://optionsahoy.com/mcp \\\n  --display-name=\"OptionsAhoy\" \\\n  --location=us-central1 \\\n  --import-tools\n\n# Path B: pass our published toolspec.json directly (faster, no introspection)\ngcloud alpha agent-registry mcp-servers register \\\n  --uri=https://optionsahoy.com/mcp \\\n  --display-name=\"OptionsAhoy\" \\\n  --location=us-central1 \\\n  --tool-spec=\u003c(curl -sSL https://optionsahoy.com/toolspec.json)\n```\n\nThe toolspec.json mirrors the MCP `tools/list` response with `readOnlyHint` and `idempotentHint` annotations on all six tools (all are pure deterministic calculators with no side effects). To regenerate after a tool-shape change:\n\n```bash\ncurl -sS -X POST https://optionsahoy.com/mcp \\\n  -H 'content-type: application/json' \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}' \\\n  | jq -c '{tools: [.result.tools[] | . + {annotations: {readOnlyHint:true, idempotentHint:true, destructiveHint:false, openWorldHint:false}}]}' \\\n  \u003e public/toolspec.json\n```\n\n## Troubleshooting\n\n**Connection refused / 404 from the MCP endpoint**\n`https://optionsahoy.com/mcp` requires `POST` with `content-type: application/json` and a JSON-RPC body. A `GET` returns a JSON server description; any other verb returns 405. Verify with:\n```bash\ncurl -X POST https://optionsahoy.com/mcp -H 'content-type: application/json' \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":1,\"params\":{}}'\n```\n\n**Tool calls fail with `Error: ...` text in the response**\nThe MCP server returns `isError: true` with a human-readable message when input validation fails. Most common: a required field missing, or a number passed as a string. Check the input against the `inputSchema` returned by `tools/list`, or against [`/openapi.json`](https://optionsahoy.com/openapi.json).\n\n**Tool not appearing in Claude.ai or Claude Desktop**\n- Confirm the connector URL is exactly `https://optionsahoy.com/mcp` (no trailing slash, no `/v1`).\n- In Claude Desktop, restart the app after editing `claude_desktop_config.json`.\n- In Claude.ai, the connector toggle is per-chat: enable it in the attachments menu.\n- Check the live `tools/list` response (six tools expected): `curl -X POST https://optionsahoy.com/mcp -H 'content-type: application/json' -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'`\n\n**CORS errors from a browser-based client**\nThe server returns `access-control-allow-origin: *` on all responses including preflight, and accepts the standard MCP headers (`content-type`, `mcp-session-id`, `mcp-protocol-version`). If a browser still blocks, the client is likely sending a non-allowed header — verify the request headers against the `access-control-allow-headers` response.\n\n**Resource / prompt not found**\nResource URIs and prompt names are case-sensitive. Pull the canonical list with `resources/list` and `prompts/list` rather than hand-typing.\n\n**Stale tax-year math**\nThe tax engine ships with 2026 inflation-adjusted brackets, OBBBA 2026 QSBS rules, and current state-conformity tables. If results look off for a multi-year horizon, verify the input `grantDate`, `acquisitionDate`, or `saleDate` falls in the year you expect — the engine resolves brackets per tax year.\n\n**Reporting a calculation bug or unexpected output**\nEmail andrew@alphalatitude.com with: the exact JSON-RPC request body, the response, the expected value, and (if known) the IRS publication or state statute the expected value derives from.\n\n## License\n\nMIT. See [LICENSE](LICENSE). The deployed service at https://optionsahoy.com/mcp and https://optionsahoy.com/api/v1 is free during beta under [terms](https://optionsahoy.com/terms).\n\n## Contact\n\nFor partnerships, early API access, MCP integration support: andrew@alphalatitude.com\n\n## Deployment topology\n\nTwo pieces serve the live endpoint:\n\n1. **Cloudflare Pages project** (GitHub-connected to this repo) auto-deploys\n   `functions/` + `public/` on every push to main → `optionsahoy-mcp.pages.dev`.\n2. **Cloudflare Worker** in [`worker-proxy/`](worker-proxy/) forwards\n   `optionsahoy.com/mcp*` + `/api/v1/*` to that Pages deployment, so the\n   public URL stays stable. One-time `wrangler deploy` — see\n   [`worker-proxy/README.md`](worker-proxy/README.md).\n\n## Call stats (D1)\n\nEvery inbound MCP and REST call writes one row to a D1 table via\n`ctx.waitUntil` (fire-and-forget — never blocks the response). View\naggregates at `https://optionsahoy-mcp.pages.dev/admin/mcp-stats?token=\u003cADMIN_TOKEN\u003e`.\n\n**One-time setup (Andrew):**\n\n```bash\n# 1. Create the database. Outputs a database_id.\ncd /Users/andrewk/Projects/optionsahoy-mcp\nnpx wrangler d1 create optionsahoy-mcp-stats\n\n# 2. Apply the schema.\nnpx wrangler d1 execute optionsahoy-mcp-stats --remote \\\n  --file=db/migrations/0001_init.sql\n\n# 3. Generate a token.\nopenssl rand -hex 32\n```\n\nThen in the Cloudflare dashboard for the `optionsahoy-mcp` Pages project:\n\n- **Settings → Functions → D1 database bindings** — add variable name\n  `MCP_STATS`, point at the database created in step 1.\n- **Settings → Environment variables → Production** — add `ADMIN_TOKEN`\n  with the value from step 3 (mark as encrypted).\n\nAfter the next deploy, `/admin/mcp-stats?token=...\u0026days=30` renders the\ndashboard. Without the bindings, `logCall` silently no-ops and the admin\npage returns 503 (the rest of the server is unaffected).\n\nWhat's logged: `ts, endpoint, tool, is_error, error_msg (truncated 500),\nclient_name, ua (truncated 200), country`. Tool arguments are **never**\nlogged (PII + table-size).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falvisooculus%2Foptionsahoy-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falvisooculus%2Foptionsahoy-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falvisooculus%2Foptionsahoy-mcp/lists"}