convez.ai
MCP ServerFinanceiroAvançado
AlvisoOculus

OptionsAhoy MCP — Otimizador de Compensação de Ações

AlvisoOculus/optionsahoy-mcp

Otimização fiscal de equity comp com cobertura tributária completa (EUA)

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP e API REST que otimiza planejamento fiscal de compensação em ações (ISO, NSO, RSU, QSBS) com suporte a código tributário federal + 50 estados + DC. Inclui sete ferramentas determinísticas para AMT, concentração, hedging e planos de financiamento multi-ano.

Instalação

$npx convez-ai AlvisoOculus/optionsahoy-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 4 dias
Versão
v1.11.1
Issues abertas
3
Contribuidores
1

Casos de uso

  • Calcular estratégia de exercício de ISO minimizando AMT federal e estadual
  • Analisar decisão venda-no-vesting vs hold para RSUs visando ganhos de capital de longo prazo
  • Avaliar risco de concentração em ação única e cenários de hedge (protective puts)
  • Validar qualificação QSBS e exclusão de ganhos conforme Section 1202
  • Gerar plano de desinvestimento multi-ano com projeção de valor líquido pós-impostos

Veredito

Ferramenta altamente especializada e verificada (Glama, MCPSafe, npm SLSA) para planejamento fiscal preciso de compensação em ações no mercado americano. Essencial para profissionais, advisors e agentes que precisam otimizar decisões de equity com rigor tributário multi-jurisdicional.

README

A tradução para o português deste README ainda está na fila.

OptionsAhoy MCP Server

Glama quality score npm version MCPSafe security grade

Independently verified. Glama: third-party MCP-directory quality score (tool docs, behavior, completeness). · npm: published with build provenance, a signed SLSA attestation that this package was built from this repo by GitHub Actions (verify with npm audit signatures). · MCPSafe: independent 5-model-consensus security scan (AIVSS), Grade A with zero findings.

Equity-compensation optimizer. ISO/AMT, NSO, RSU, QSBS, single-stock concentration, protective puts/collars, and equity-funding plans. Seven deterministic tools across the federal + 50-state + DC tax code.

Live MCP endpoint: https://optionsahoy.com/mcp (no auth, no install) Live REST API: https://optionsahoy.com/api/v1 OpenAPI 3.1 spec: /openapi.json Discovery manifests: /.well-known/mcp.json · /.well-known/openapi.json Agent integration docs: optionsahoy.com/for-agents

Built by AlphaLatitude Inc. — a pre-revenue beta-stage equity-compensation optimization product.

See it in action

Demo: Claude Code installing and using the OptionsAhoy MCP

Real Claude Code session, unedited. One claude mcp add line, a casual question about 1,200 vested Meta restricted stock units (RSU) and a mid-2027 mortgage paydown, and the optimizer returns a month-by-month sell schedule with after-tax net final value across three scenarios. 68 seconds. Click the poster to play.


What this is

An optimization engine for equity-compensation tax planning, exposed as both a Model Context Protocol (MCP) server and a plain REST API. Seven tools:

Tool nameWhat it computes
amt_iso_optimizeMulti-year Incentive Stock Option (ISO) exercise schedule that minimizes federal and state Alternative Minimum Tax (AMT), with credit recovery across years
nso_calculateNon-qualified Stock Option (NSO) exercise tax + sell-vs-hold-for-LTCG comparison
rsu_sell_vs_holdRSU sell-at-vest vs hold-for-long-term-capital-gains decision
concentration_analyzeSingle-stock concentration risk + sell-down vs hold vs hedge optimization
protective_put_priceProtective put / zero-cost collar pricing via Black-Scholes; volatility from a compiled sector-volatility table, or a caller-supplied value
qsbs_checkSection 1202 Qualified Small Business Stock (QSBS) qualification (eight statutory tests, OBBBA 2026 tiered exclusion)
equity_funding_planMulti-year, multi-stack equity-funding plan for hitting a target after-tax amount by a deadline. Returns four named plans (Lock-in-now / Balanced / Hold-for-growth / Recommended) plus the full risk/wealth frontier.

The optimizers return the globally-optimal schedule across the candidate space; the calculators return exact deterministic results. No heuristics, no 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, CO, CT, MN). Same engine as the in-browser calculators at optionsahoy.com/tools; the API response is byte-identical to clicking through the tool.

MCP resources (topical briefings)

Six 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 and the matching calculator.

Resource URITopicPair with
https://optionsahoy.com/learn/amt-crossoverISO/AMT crossover and four expensive mistakesamt_iso_optimize
https://optionsahoy.com/learn/nso-sell-vs-holdNSO sell-at-exercise vs hold-for-LTCGnso_calculate
https://optionsahoy.com/learn/rsu-withholding-gapRSU 22% withholding gap and five April surprisesrsu_sell_vs_hold
https://optionsahoy.com/learn/single-stock-concentration-riskConcentration risk and diversification trade-offconcentration_analyze
https://optionsahoy.com/learn/zero-cost-collarsProtective puts and zero-cost collarsprotective_put_price
https://optionsahoy.com/learn/qsbsQSBS qualification and five ways to lose the exclusionqsbs_check

MCP prompts (workflow scaffolds)

Seven 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.

Prompt nameRoutes to
optimize-iso-exerciseamt_iso_optimize
analyze-nso-decisionnso_calculate
analyze-rsu-vestrsu_sell_vs_hold
analyze-concentrationconcentration_analyze
price-protective-putprotective_put_price
check-qsbs-eligibilityqsbs_check
plan-equity-fundingequity_funding_plan

Why use an optimizer

A 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?

Use from Claude / ChatGPT / Perplexity / any MCP client

Hosted (no install)

Add the server as a remote HTTP MCP connection:

https://optionsahoy.com/mcp

Or via the add-mcp CLI:

npx add-mcp https://optionsahoy.com/mcp

Local stdio (npm)

For clients that only support local stdio servers (Claude Desktop without mcp-remote, some IDE integrations):

npx -y optionsahoy-mcp

Or add to a Claude Desktop / Cline / Goose config file:

{
  "mcpServers": {
    "optionsahoy": {
      "command": "npx",
      "args": ["-y", "optionsahoy-mcp"]
    }
  }
}

The local server returns byte-identical responses to the hosted endpoint at https://optionsahoy.com/mcp. Source for both lives in functions/_lib/mcp-tools.ts; the stdio entry point is src/stdio-server.ts.

Use the REST API directly

# List endpoints
curl https://optionsahoy.com/api/v1

# Run an optimization
curl -X POST https://optionsahoy.com/api/v1/amt-iso \
  -H "content-type: application/json" \
  -d @input.json

Request body shapes are documented in public/openapi.json.

Repository layout

functions/         Cloudflare Pages Functions (MCP server + REST API endpoints)
  mcp.ts           HTTP MCP server
  api/v1/*.ts      Seven tool endpoints + stats + GET /api/v1 discovery
  _lib/*.ts        Shared helpers, calc-input parsers, MCP tool descriptors
lib/               Optimizer + tax-code logic
  calc/            Per-tool optimizer functions (computeAmtIso, etc.)
  tax/             Federal + 50-state + DC bracket data, AMT, FICA, NIIT
  markets/         Sector statistics
  options/         Black-Scholes, risk-free rates
  data/            Type definitions for option-chain data
public/            Static assets: OpenAPI spec, llms.txt, discovery manifests
tests/             Vitest suites (172 tests including byte-identity assertions)

Run tests

npm install
npm test         # 172 tests, ~3s on a laptop
npm run typecheck

Registry listings

Use from Google Cloud (Gemini agents)

Google 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:

# Path A: let the Agent Registry introspect our MCP endpoint
gcloud alpha agent-registry mcp-servers register \
  --uri=https://optionsahoy.com/mcp \
  --display-name="OptionsAhoy" \
  --location=us-central1 \
  --import-tools

# Path B: pass our published toolspec.json directly (faster, no introspection)
gcloud alpha agent-registry mcp-servers register \
  --uri=https://optionsahoy.com/mcp \
  --display-name="OptionsAhoy" \
  --location=us-central1 \
  --tool-spec=<(curl -sSL https://optionsahoy.com/toolspec.json)

The toolspec.json mirrors the MCP tools/list response with readOnlyHint and idempotentHint annotations on all seven tools (all are pure deterministic calculators with no side effects). To regenerate after a tool-shape change:

curl -sS -X POST https://optionsahoy.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  | jq -c '{tools: [.result.tools[] | . + {annotations: {readOnlyHint:true, idempotentHint:true, destructiveHint:false, openWorldHint:false}}]}' \
  > public/toolspec.json

Troubleshooting

Connection refused / 404 from the MCP endpoint 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:

curl -X POST https://optionsahoy.com/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}'

Tool calls fail with Error: ... text in the response The 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.

Tool not appearing in Claude.ai or Claude Desktop

  • Confirm the connector URL is exactly https://optionsahoy.com/mcp (no trailing slash, no /v1).
  • In Claude Desktop, restart the app after editing claude_desktop_config.json.
  • In Claude.ai, the connector toggle is per-chat: enable it in the attachments menu.
  • Check the live tools/list response (seven tools expected): curl -X POST https://optionsahoy.com/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

CORS errors from a browser-based client The 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.

Resource / prompt not found Resource URIs and prompt names are case-sensitive. Pull the canonical list with resources/list and prompts/list rather than hand-typing.

Stale tax-year math The 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.

Reporting a calculation bug or unexpected output Email 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.

License

MIT. See LICENSE. The deployed service at https://optionsahoy.com/mcp and https://optionsahoy.com/api/v1 is free during beta under terms.

Contact

For partnerships, early API access, MCP integration support: andrew@alphalatitude.com

Deployment topology

Two pieces serve the live endpoint:

  1. Cloudflare Pages project (GitHub-connected to this repo) auto-deploys functions/ + public/ on every push to main → optionsahoy-mcp.pages.dev.
  2. Cloudflare Worker in worker-proxy/ forwards optionsahoy.com/mcp* + /api/v1/* to that Pages deployment, so the public URL stays stable. One-time wrangler deploy — see worker-proxy/README.md.

Call stats (D1)

Every inbound MCP and REST call writes one row to a D1 table via ctx.waitUntil (fire-and-forget — never blocks the response). View aggregates at https://optionsahoy-mcp.pages.dev/admin/mcp-stats?token=<ADMIN_TOKEN>.

One-time setup (Andrew):

# 1. Create the database. Outputs a database_id.
cd /Users/andrewk/Projects/optionsahoy-mcp
npx wrangler d1 create optionsahoy-mcp-stats

# 2. Apply the schema.
npx wrangler d1 execute optionsahoy-mcp-stats --remote \
  --file=db/migrations/0001_init.sql

# 3. Generate a token.
openssl rand -hex 32

Then in the Cloudflare dashboard for the optionsahoy-mcp Pages project:

  • Settings → Functions → D1 database bindings — add variable name MCP_STATS, point at the database created in step 1.
  • Settings → Environment variables → Production — add ADMIN_TOKEN with the value from step 3 (mark as encrypted).

After the next deploy, /admin/mcp-stats?token=...&days=30 renders the dashboard. Without the bindings, logCall silently no-ops and the admin page returns 503 (the rest of the server is unaffected).

What's logged: ts, endpoint, tool, is_error, error_msg (truncated 500), client_name, ua (truncated 200), country. Tool arguments are never logged (PII + table-size).

Ver o original no GitHub

Bom para

Relacionados