OptionsAhoy

Planejamento de impostos e exercício/venda/hedge de compensação de ações para funcionários dos EUA: cronogramas de exercício de ISO com AMT, calculadoras de NSO e RSU, ordenação de lotes de RSU, verificações de QSBS, análise de concentração e precificação de hedge. Cálculos fiscais federais, dos 50 estados e de DC. Servidor remoto hospedado (Streamable HTTP), gratuito, sem chave de API.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP OptionsAhoy

_{Verificado de forma independente por terceiros. Glama: pontuação de qualidade de terceiros do diretório MCP (documentação das ferramentas, comportamento, completude). · npm: publicado com proveniência de build, uma atestação SLSA assinada de que este pacote foi construído a partir deste repositório pelo GitHub Actions (verifique com npm audit signatures). · MCPSafe: varredura de segurança independente com consenso de 5 modelos (AIVSS), Grau A com zero achados.}

_{Validado contra fontes confiáveis (verificações que executamos nós mesmos, contra referências que não controlamos e que você pode reproduzir). Cálculo: cada constante fiscal federal de 2026 corresponde ao seu valor no IRS Rev. Proc. 2025-32 / Internal Revenue Code, e 14 casos federais trabalhados (renda ordinária, ganhos de capital de longo prazo e o Imposto Mínimo Alternativo, incluindo o elemento de barganha de opções de ações de incentivo) reproduzem ao centavo contra o PSL Tax-Calculator, mantido de forma independente, um modelo tributário que não escrevemos. O imposto de renda estadual é verificado da mesma forma: 16 casos na Califórnia, Nova York, Nova Jersey, Pensilvânia e Massachusetts reproduzem ao centavo contra o OpenTaxSolver, um motor tributário estadual independente que também não escrevemos. A resposta principal é recalculada ao vivo no seu navegador.}

_{Testado e endurecido. Segurança de entrada: as solicitações são validadas contra o esquema publicado; entradas inválidas retornam um 400 claro com o campo problemático nomeado, nunca uma falha ou um número errado, e a API ao vivo é reverificada por uma suíte de robustez após cada implantação. · Suíte de testes: o motor de cálculo é coberto por mais de mil testes automatizados na lógica tributária federal e dos 50 estados, recuperação de crédito AMT e precificação de opções; um teste com falha bloqueia o lançamento.}

_{Uso ao vivo: chamadas MCP nos últimos 30 dias, servidas diretamente da telemetria do próprio servidor (/api/v1/stats, apenas contagens agregadas, sem PII).}

Matemática tributária determinística para remuneração em ações que qualquer cliente do Model Context Protocol (MCP) pode chamar: cronogramas de exercício de opções de ações de incentivo (ISO) sob o imposto mínimo alternativo (AMT), decisões de opções de ações não qualificadas (NSO) e unidades de ações restritas (RSU), qualificação de ações qualificadas de pequenas empresas (QSBS), concentração em ação única, hedge com opção de venda protetora e metas de financiamento com capital próprio. Código tributário federal relevante, além de todos os 50 estados e DC, faixas de 2026. Construído pela AlphaLatitude Inc., a empresa por trás do OptionsAhoy.

Por que não simplesmente perguntar ao modelo? Avaliamos cinco modelos de linguagem de grande porte (LLMs) de fronteira, 3 execuções cada, 15 tentativas no total, no mesmo problema de exercício de ISO plurianual. Cada tentativa superestimou o resultado após impostos do seu próprio cronograma proposto, em 2x a 20x. O agendamento plurianual tem um espaço de busca maior do que é prático trabalhar no contexto; essas ferramentas retornam a resposta verificável. Benchmark ao vivo, atualizado para os modelos mais recentes: optionsahoy.com/benchmark. Respostas brutas e pontuação: llm-iso-benchmark. Relatório completo: Mas ele consegue fazer impostos?

Instalação em uma linha

O endpoint hospedado é https://optionsahoy.com/mcp (HTTP, sem autenticação, sem conta). Caminhos mais rápidos:

Cliente	Instalação
Qualquer cliente MCP	Adicione `https://optionsahoy.com/mcp` como servidor HTTP remoto, ou `npx add-mcp https://optionsahoy.com/mcp`
Claude Desktop	Baixe `optionsahoy.mcpb` e clique duas vezes
19 clientes via Smithery	`npx @smithery/cli install alphalatitude/optionsahoy --client claude`
stdio local (npm)	`npx -y optionsahoy-mcp`

Matriz de instalação completa (extensão do Gemini CLI, JSON de arquivo de configuração, API REST, Google Cloud Agent Registry): optionsahoy.com/for-agents.

As oito ferramentas

Nome da ferramenta	O que calcula
`amt_iso_optimize`	Cronograma de exercício de ISO plurianual que maximiza o valor final líquido após impostos no horizonte de planejamento, modelando recuperação de crédito AMT, expiração da concessão e a janela de exercício pós-rescisão
`nso_calculate`	Pagamento após impostos no exercício de NSO (federal, estadual, FICA), comparando vender no exercício vs. manter para ganhos de capital de longo prazo
`rsu_sell_vs_hold`	Decisão de vesting de RSU: vender no vesting vs. manter para ganhos de capital de longo prazo, incluindo a lacuna entre a retenção suplementar de 22% e sua faixa marginal
`concentration_analyze`	Risco de concentração em ação única (exposição a queda em cenários de 30/50/70%), comparando venda após impostos, manutenção e estratégias de hedge
`protective_put_price`	Precificação de opção de venda protetora, collar de custo zero e spread de opções de venda via Black-Scholes: custo anualizado do hedge, perda máxima, teto de alta, banda protegida, probabilidade de atingir o piso e qual estrutura ele recomenda
`qsbs_check`	Qualificação QSBS da Seção 1202 nos seis testes legais, com a exclusão escalonada OBBBA 2026 e conformidade por estado
`equity_funding_plan`	Cronograma de venda plurianual e multi-lote para atingir um valor alvo após impostos até um prazo; retorna quatro planos nomeados mais a fronteira completa de risco/riqueza
`rsu_lot_optimize`	Quais lotes de RSU com vesting vender, e em quais datas, para alienar uma fração alvo de ações ao menor imposto calculado: identificação específica de lote, adiamento de longo prazo e distribuição plurianual entre faixas com compensação de perdas no plano, versus uma ordem de venda FIFO

O otimizador de ISO busca todo o seu espaço candidato discretizado e refina ação por ação, igualando um máximo de força bruta ao centavo em um caso publicamente tratável (veja a prova); os planejadores executam buscas determinísticas cientes das faixas e as calculadoras retornam resultados exatos. Cálculo determinístico, não um palpite de modelo de linguagem. A cobertura abrange o código tributário federal relevante (faixas ordinárias, ganhos de capital de longo prazo, AMT com recuperação de crédito, FICA, NIIT), além de todos os 50 estados e DC (faixas ordinárias estaduais, tratamento de LTCG, AMT estadual para CA, CO, CT, MN). Mesmo motor das calculadoras no navegador em optionsahoy.com/tools; a resposta da API carrega os mesmos valores calculados que clicar na ferramenta.

Como é uma chamada (todas as oito ferramentas)

Uma chamada real por ferramenta, capturada de https://optionsahoy.com/mcp e confirmada em docs/examples/, para que cada valor abaixo seja auditável contra a resposta de onde veio. As entradas são deliberadamente explícitas (sem ticker, todas as datas fixadas), então reexecutar scripts/capture-readme-examples.mts reproduz os mesmos números. Cada bloco mostra a pergunta, os argumentos que carregam o cenário e o que retornou.

`amt_iso_optimize`

"Tenho 50.000 ISOs com vesting a um strike de $4 e a ação está a $90. Casado em declaração conjunta, $300.000 de renda, Califórnia. Devo exercer o bloco inteiro agora ou distribuir?"

{"shares": 50000, "strike": 4, "fmv": 90, "horizon": 4, "filingStatus": "married_joint",
 "ordinaryIncome": 300000, "stateCode": "CA", "grantDate": "2023-03-15",
 "expectedGrowth": 0.1, "volatilityDrag": 0.2, "cashReturnRate": 0.05, …}

O cronograma otimizado exercita 1.401 / 1.339 / 1.280 / 45.980 ações ao longo dos quatro anos e termina com um valor final líquido de $1.623.234, contra $1.565.849 para exercer o bloco inteiro hoje. O ponto de cruzamento do AMT está em 699 ações: os primeiros $60.185 do elemento de barganha não custam AMT algum. (bruto; a mesma posição do exemplo trabalhado publicado do site, precificado com o crescimento e arrasto explícitos acima)

`nso_calculate`

"5.000 NSOs a um strike de $8, ação a $75. Vendo no exercício ou mantenho por um ano para ganhos de longo prazo? Solteiro, $250.000 de renda, Califórnia."

{"shares": 5000, "strike": 8, "currentPrice": 75, "expectedSalePrice": 90, "holdYears": 1,
 "holdFunding": "sell-to-cover", "volatility": 0.3, "ordinaryIncome": 250000,
 "filingStatus": "single", "stateCode": "CA", …}

O exercício em si é um elemento de barganha de $335.000 tributado em $159.618, deixando $175.382 se você vender tudo na hora. Manter por um ano com venda para cobrir projeta $193.943 contra $184.209 para vender agora e investir os rendimentos, uma vantagem de $9.734 para manter. (bruto)

`rsu_sell_vs_hold`

"1.000 RSUs com vesting a $200. Vender no vesting ou manter por mais um ano e meio? Casado em declaração conjunta, $300.000 de renda, Nova York."

{"shares": 1000, "currentPrice": 200, "expectedSalePrice": 220, "holdYears": 1.5,
 "volatility": 0.25, "ordinaryIncome": 300000, "filingStatus": "married_joint",
 "stateCode": "NY", "stillEmployed": true, …}

O vesting custa $73.896 em imposto total, dos quais $55.716 são federais contra apenas $44.000 retidos na taxa suplementar fixa: essa lacuna é a conta de abril que as pessoas não veem chegando. Vender no vesting e investir projeta $136.247 ao final dessa manutenção versus $130.817 para manter, então manter perde $5.430 aqui. (bruto)

`concentration_analyze`

"$750.000 dos meus $2,25M estão em uma ação de tecnologia que comprei em 2022 por $150.000. Quão exposto estou e quanto custa vender parte?"

{"positionValue": 750000, "costBasis": 150000, "acquisitionDate": "2022-01-15",
 "sector": "tech_software", "totalAssets": 2250000, "expectedPositionReturn": 0.12,
 "volatility": 0.35, "ordinaryIncome": 350000, "filingStatus": "single", "stateCode": "CA", …}

A posição é 33% do patrimônio líquido, que a ferramenta classifica como "Concentrada", e uma queda de 50% nesse único nome custaria $375.000. Vender ao longo de três anos paga $196.709 em imposto contra $208.368 para vender em um único ano. (bruto)

`protective_put_price`

"Quero proteção contra queda em uma posição de tecnologia de $500.000 por um ano, com um piso cerca de 20% abaixo do preço à vista. Put, collar ou spread de puts?"

{"positionValue": 500000, "sector": "tech_software", "volatility": 0.35,
 "protectionLevel": 0.2, "tenorYears": 1, "spreadRiskLevel": 0.1, "expectedReturn": 0.08}

Uma put simples com strike em $400.000 custa $19.348 por ano, 3,87% da posição. O collar de custo zero compra o mesmo piso por um prêmio líquido de aproximadamente zero ao limitar o teto de alta em $724.518, no qual ele coloca uma chance de 15,7% de atingir, e essa é a estrutura que ele recomenda. (bruto) Esta chamada passa um sigma explícito, então cada perna é precificada nesse único número; passe um ticker em vez disso e cada perna será precificada na volatilidade implícita do seu próprio strike a partir da cadeia de opções ao vivo dessa ação, o que custa mais para um piso tão fora do dinheiro.

`qsbs_check`

"Comprei ações de fundador em março de 2020 e estou vendendo em março de 2026 com um ganho de $5M. É QSBS e quanto é isento de imposto?"

{"acquisitionDate": "2020-03-01", "saleDate": "2026-03-15", "entityType": "us-c-corp",
 "acquisitionMethod": "original-issuance", "assetCategory": "under-50m",
 "industry": "tech-software", "adjustedBasis": 50000, "expectedGain": 5000000, …}

Veredito qualifies: todos os seis testes legais passam com 6,0 anos de manutenção, então 100% do ganho de $5.000.000 é excluível sob o limite de $10.000.000 por emissor, valendo $1.190.000 em imposto federal. A Califórnia não está em conformidade, então o mesmo ganho é totalmente tributável pelo estado. (bruto)

`equity_funding_plan`

"Preciso de $400.000 após impostos até junho de 2029 para uma casa. Tenho 3.500 ações a $120 em dois lotes. O que vendo e quando?"

{"targetAfterTax": 400000, "targetDate": "2029-06-30", "stacks": [{"currentPrice": 120,
 "expectedAnnualGrowth": 0.08, "lots": [{"shares": 2000, "costBasisPerShare": 50,
 "acquisitionDate": "2022-01-15"}, …]}], "ordinaryIncome": 350000, "stateCode": "CA", …}

Vender tudo hoje fica aquém: rende $391.574 contra a meta de $400.000. O plano escalonado recomendado vende 3.314 das 3.500 ações ao longo dos anos até o prazo, chega a $400.075 após impostos com $63.740 de imposto pago e supera uma venda única no ano alvo em $12.976. (bruto)

`rsu_lot_optimize`

"Tenho 3.000 ações de RSU com vesting de três vestings, a ação está a $180 e quero cortar a posição pela metade nos próximos dois anos. Quais lotes saem?"

{"lots": [{"vestDate": "2022-08-15", "shares": 1200, "costBasisPerShare": 95},
 {"vestDate": "2024-02-15", "shares": 1000, "costBasisPerShare": 130}, …],
 "currentPrice": 180, "divestFraction": 0.5, "horizonYears": 2, "ordinaryIncome": 200000, …}

Para alienar 1.500 das 3.000 ações, ele combina o lote mais novo submerso contra ganhos de longo prazo de um mais antigo, então toda a alienação custa $2.935 em imposto e mantém $267.065 após impostos, $29.942 a mais do que vender a mesma fração em ordem FIFO. (bruto)

Cada exemplo acima passa volatilidade e crescimento explicitamente. Em uma chamada real, você pode em vez disso passar ticker: a volatilidade é resolvida do instantâneo de volatilidade implícita publicado no último fechamento do mercado, e o crescimento do instantâneo de CAGR acumulado em cache. Se qualquer um não puder ser resolvido, a chamada retorna um erro nomeando o campo exato em vez de um número adivinhado, e protective_put_price ecoa volatilitySource (explicit, chain, ticker ou sector-default) mais pricingMode (chain-skew ou flat) para que você sempre saiba qual sigma foi precificado e se as pernas foram precificadas em seus próprios strikes.

Essas capturas foram executadas no ano fiscal de 2026. Os valores mudam em um ano fiscal posterior para as três ferramentas cujos cronogramas avançam a partir da data de hoje (amt_iso_optimize, equity_funding_plan, rsu_lot_optimize); todo o resto é fixado pelas datas nos argumentos.

Use em seu framework de agentes (Python)

Se você cria agentes em Python em vez de chamar o endpoint MCP diretamente, o OptionsAhoy oferece pacotes de ferramentas instaláveis para os principais frameworks de agentes. Cada um encapsula as mesmas calculadoras por trás da interface nativa de ferramentas do framework. Todos estão publicados no PyPI e todos são sem chave: sem conta OptionsAhoy, sem chave de API.

Framework	Instalação	Importação	Exemplo
LangChain	`pip install optionsahoy-langchain`	`from langchain_optionsahoy import get_optionsahoy_tools`	`equity_agent.py`
LlamaIndex	`pip install llama-index-tools-optionsahoy`	`from llama_index.tools.optionsahoy import OptionsAhoyToolSpec`	`equity_agent.py`
CrewAI	`pip install crewai-optionsahoy`	`from crewai_optionsahoy import get_optionsahoy_tools`	`equity_crew.py`
Cliente Python simples	`pip install optionsahoy`	`from optionsahoy import OptionsAhoyClient`	`basic_client.py`

Os três adaptadores de framework puxam automaticamente o cliente optionsahoy sem chave. Há também um agente OpenBB Workspace (um aplicativo FastAPI construído sobre o cliente OptionsAhoy) para uso dentro do OpenBB Workspace. Exemplos de código-fonte e executáveis para todos os itens acima estão disponíveis em integrations/python.

Mais formas de construir

Independentemente de como seu agente é construído, há uma peça pronta para uso. Todos são públicos e sem chave.

Bloco de construção	O que é
Ferramentas do Vercel AI SDK	Um pacote TypeScript (`optionsahoy-ai-sdk`) que expõe todas as oito calculadoras como definições `tool()` do Vercel AI SDK, prontas para serem espalhadas em `generateText` / `streamText`.
Kits de instrução	Regras de editor e habilidades para Cursor, Windsurf, Claude Skills e subagentes Claude Code, para que seu agente de codificação chame as ferramentas OptionsAhoy para perguntas sobre remuneração em ações.
Receitas de codificação	Receitas Python de copiar e colar, um arquivo autocontido por pergunta, chamando a API sem chave apenas com `requests`. Também em `integrations/recipes`.
Modelos de construtor	Um fluxo de trabalho n8n importável, além de receitas de construção para Flowise, Langflow e Dify.
Avaliação de uso de ferramenta	Uma avaliação inspect_ai que mede se um agente atinge o ótimo comprovável em um problema ISO de vários anos, com e sem a ferramenta.
Descoberta A2A	Um Agent Card Agent2Agent (A2A) para que outros agentes possam descobrir e delegar perguntas sobre remuneração em ações ao planejador.
Extensão Zed	Uma extensão de servidor de contexto do editor Zed que conecta o agente do editor ao servidor MCP OptionsAhoy.
Aplicativo ACI.dev	A definição do aplicativo OptionsAhoy para a plataforma de ferramentas de agente de código aberto ACI.dev.
Ponte OpenRouter	Uma receita para anexar o servidor MCP OptionsAhoy sem chave a qualquer modelo roteado pelo endpoint compatível com OpenAI do OpenRouter.

Experimente sem instalar

O widget ao vivo em optionsahoy.com/for-agents chama este mesmo endpoint do seu navegador. Sem cliente, sem configuração.

Prefere uma interface de chat? As mesmas calculadoras respondem a perguntas em linguagem simples em poe.com/OptionsAhoy.

Ou assista a uma sessão real:

Sessão real do Claude Code, sem edição. Uma pergunta META de múltiplas camadas (10K ISOs + 6K RSUs adquiridos + 2K RSUs novos + casa de $400K em 2027) dispara 4 ferramentas MCP OptionsAhoy em paralelo: risco de concentração, plano de financiamento de capital, otimização AMT/ISO, precificação de put protetora. O Claude sintetiza as saídas em um único plano que substitui a escolha isolada de cada ferramenta porque o usuário está 86% concentrado em META. 2:13. Clique no pôster para reproduzir em optionsahoy.com.

Endpoints e descoberta

Endpoint MCP ao vivo: https://optionsahoy.com/mcp API REST ao vivo: https://optionsahoy.com/api/v1 Especificação OpenAPI 3.1: /openapi.json Manifestos de descoberta: /.well-known/mcp.json · /.well-known/openapi.json Documentação de integração de agentes: optionsahoy.com/for-agents

Recursos MCP (briefings temáticos)

Oito recursos markdown sob resources/list dão a um LLM fundamentação suficiente para discutir o tópico antes de escolher uma ferramenta. A maioria mapeia 1:1 com um artigo fundamental em optionsahoy.com/learn e a calculadora correspondente; o briefing de financiamento de capital mapeia para sua calculadora, e o briefing de tickers cobertos enumera os símbolos que o atalho opcional ticker resolve.

URI do recurso	Tópico	Combinar com
`https://optionsahoy.com/learn/amt-crossover`	Crossover ISO/AMT e quatro erros caros	`amt_iso_optimize`
`https://optionsahoy.com/learn/nso-sell-vs-hold`	NSO vender no exercício vs. manter para LTCG	`nso_calculate`
`https://optionsahoy.com/learn/rsu-withholding-gap`	Lacuna de retenção de 22% do RSU e cinco surpresas de abril	`rsu_sell_vs_hold`
`https://optionsahoy.com/learn/single-stock-concentration-risk`	Risco de concentração e trade-off de diversificação	`concentration_analyze`
`https://optionsahoy.com/learn/zero-cost-collars`	Puts protetoras, collars de custo zero e spreads de put	`protective_put_price`
`https://optionsahoy.com/learn/qsbs`	Qualificação QSBS e cinco maneiras de perder a exclusão	`qsbs_check`
`https://optionsahoy.com/tools/equity-funding`	Vender capital para financiar uma meta de caixa até um prazo	`equity_funding_plan`
`https://optionsahoy.com/tools/covered-tickers`	Quais símbolos o atalho opcional `ticker` resolve	qualquer ferramenta que aceite `ticker`

Prompts MCP (estruturas de fluxo de trabalho)

Oito prompts sob prompts/list estruturam perguntas típicas de usuários e roteiam para a ferramenta correta. No Claude Desktop, eles aparecem como comandos de barra nomeados; em qualquer cliente MCP, prompts/get { name, arguments } retorna uma mensagem de usuário totalmente modelada.

Nome do prompt	Roteia para
`optimize-iso-exercise`	`amt_iso_optimize`
`analyze-nso-decision`	`nso_calculate`
`analyze-rsu-vest`	`rsu_sell_vs_hold`
`analyze-concentration`	`concentration_analyze`
`price-protective-put`	`protective_put_price`
`check-qsbs-eligibility`	`qsbs_check`
`plan-equity-funding`	`equity_funding_plan`
`plan-equity-portfolio`	várias ferramentas, reconciliadas em um único plano

Uma invocação prompts/get, argumentos como strings:

{"name": "optimize-iso-exercise",
 "arguments": {"shares": "50000", "strike": "4", "fmv": "90", "expectedGrowth": "0.1",
               "volatility": "0.5", "state": "CA", "ordinaryIncome": "300000"}}

Ela retorna uma mensagem de usuário modelada ("Tenho 50000 Incentive Stock Options (ISOs) com um strike de $4 por ação ...") que já diz ao modelo para chamar amt_iso_optimize com esses valores, para perguntar sobre qualquer campo obrigatório ausente em vez de assumi-lo, e para relatar o cronograma otimizado em comparação com as alternativas de pagamento único e divisão uniforme (bruto).

Detalhes de instalação

Extensão Claude Desktop (um clique)

O pacote optionsahoy.mcpb instala com duplo clique (ou arrastar para Claude Desktop → Configurações → Extensões), sem edição de terminal ou arquivo de configuração, usando o runtime Node.js integrado do Claude Desktop.

Para construir o pacote a partir do código-fonte:

npm install && npm run build:mcpb

CLI Smithery (19 clientes, um comando)

npx @smithery/cli install alphalatitude/optionsahoy --client claude

Troque claude por qualquer cliente que o Smithery suporte: claude-code, cursor, vscode, gemini-cli, codex, windsurf, cline, goose, opencode e mais 10. Listagem: smithery.ai/servers/alphalatitude/optionsahoy.

Extensão CLI Gemini

gemini extensions install https://github.com/AlvisoOculus/optionsahoy-mcp

Este repositório também funciona como uma extensão CLI Gemini: gemini-extension.json conecta o endpoint MCP hospedado e GEMINI.md fornece contexto de uso ao modelo.

stdio local (npm)

Para clientes que suportam apenas servidores stdio locais (Claude Desktop sem mcp-remote, algumas integrações de IDE):

npx -y optionsahoy-mcp

Ou adicione a um arquivo de configuração Claude Desktop / Cline / Goose:

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

O servidor local retorna os mesmos valores calculados que o endpoint hospedado em https://optionsahoy.com/mcp. O código-fonte para ambos está em functions/_lib/mcp-tools.ts; o ponto de entrada stdio é src/stdio-server.ts.

Use a API REST diretamente

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

# Run an optimization (the 50,000-ISO example from "What a call looks like")
curl -X POST https://optionsahoy.com/api/v1/amt-iso \
  -H "content-type: application/json" \
  -d '{"shares":50000,"strike":4,"fmv":90,"horizon":4,"filingStatus":"married_joint",
       "ordinaryIncome":300000,"stateCode":"CA","grantDate":"2023-03-15",
       "hasLeftCompany":false,"expectedGrowth":0.1,"volatilityDrag":0.2,
       "carryforwardCredit":0,"cashReturnRate":0.05}'

Isso retorna o mesmo result.schedules.optimized.nfv que a chamada MCP acima (bruto). As formas do corpo da solicitação para os outros sete endpoints estão documentadas em public/openapi.json.

Estrutura do repositório

functions/         Cloudflare Pages Functions (MCP server + REST API endpoints)
  mcp.ts           HTTP MCP server
  api/v1/*.ts      Eight 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/            Option-chain types, and the readers for the live vol and chain feeds
public/            Static assets: OpenAPI spec, llms.txt, discovery manifests
tests/             Vitest suites (an extensive test suite including byte-identity assertions)

Executar testes

npm install
npm test         # an extensive test suite, ~3s on a laptop
npm run typecheck

Listagens de registro

Registro MCP oficial — io.github.AlvisoOculus/optionsahoy-mcp, status ativo
Diretório de plugins ChatGPT — adição com um clique para qualquer usuário do ChatGPT, sem modo de desenvolvedor (publicado em 28/07/2026)
Smithery — alphalatitude/optionsahoy (além da habilidade de plano de capital)
Galeria de extensões CLI Gemini — @AlvisoOculus/optionsahoy-mcp
Registro curado add-mcp
PulseMCP (cascateia do Registro Oficial)
Hub Continue.dev — o YAML do bloco está em .continue/mcpServers/optionsahoy.yaml

Uso do Google Cloud (agentes Gemini)

O Google Cloud Agent Registry permite que cada projeto GCP registre servidores MCP externos para uso por agentes Gemini. O registro é por projeto (sem envio central). Dois caminhos:

# 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)

O toolspec.json espelha a resposta tools/list do MCP com anotações readOnlyHint e idempotentHint em todas as oito ferramentas (todas são calculadoras determinísticas puras, sem efeitos colaterais). Para regenerar após uma mudança na forma da ferramenta:

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

Solução de problemas

Conexão recusada / 404 do endpoint MCP https://optionsahoy.com/mcp requer POST com content-type: application/json e um corpo JSON-RPC. Um GET retorna uma descrição JSON do servidor; qualquer outro verbo retorna 405. Verifique com:

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

Chamadas de ferramenta falham com texto Error: ... na resposta O servidor MCP retorna isError: true com uma mensagem legível por humanos quando a validação de entrada falha. O mais comum: um campo obrigatório ausente ou um número passado como string. Verifique a entrada contra o inputSchema retornado por tools/list, ou contra /openapi.json.

Ferramenta não aparecendo no Claude.ai ou Claude Desktop

Confirme se a URL do conector é exatamente https://optionsahoy.com/mcp (sem barra final, sem /v1).
No Claude Desktop, reinicie o aplicativo após editar claude_desktop_config.json.
No Claude.ai, o alternador do conector é por chat: ative-o no menu de anexos.
Verifique a resposta ao vivo tools/list (oito ferramentas esperadas): curl -X POST https://optionsahoy.com/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Erros CORS de um cliente baseado em navegador O servidor retorna access-control-allow-origin: * em todas as respostas, incluindo preflight, e aceita os cabeçalhos MCP padrão (content-type, mcp-session-id, mcp-protocol-version). Se um navegador ainda bloquear, o cliente provavelmente está enviando um cabeçalho não permitido — verifique os cabeçalhos da solicitação contra a resposta access-control-allow-headers.

Recurso / prompt não encontrado URIs de recursos e nomes de prompts diferenciam maiúsculas de minúsculas. Obtenha a lista canônica com resources/list e prompts/list em vez de digitar manualmente.

Matemática de ano fiscal desatualizada O mecanismo fiscal vem com faixas ajustadas pela inflação de 2026, regras QSBS OBBBA 2026 e tabelas atuais de conformidade estadual. Se os resultados parecerem errados para um horizonte de vários anos, verifique se a entrada grantDate, acquisitionDate ou saleDate cai no ano que você espera — o mecanismo resolve as faixas por ano fiscal.

Relatando um bug de cálculo ou saída inesperada Envie um e-mail para andrew@alphalatitude.com com: o corpo exato da solicitação JSON-RPC, a resposta, o valor esperado e (se conhecido) a publicação do IRS ou estatuto estadual do qual o valor esperado deriva.

Política de Privacidade

Política completa: optionsahoy.com/privacy. Em resumo: nenhuma conta é necessária e nenhuma informação pessoalmente identificável é armazenada — sem nome, e-mail, endereço IP ou login. Entradas e saídas de ferramentas são retidas brevemente (cerca de sete dias) para depuração e melhoria do produto, juntamente com metadados agregados de uso (ferramenta, timestamp, localização aproximada, tipo de cliente) usados para entender o uso e detectar abusos. O servidor stdio local e a extensão do Claude Desktop calculam tudo na sua máquina. Eles fazem exatamente dois tipos de solicitação de rede, ambos apenas quando você passa um ticker sem o número que ele resolveria: o arquivo de volatilidade implícita publicado, que é uma URL fixa sem nenhum ticker, e, para protective_put_price, a cadeia de opções dessa ação, cuja URL contém o símbolo. Nada mais sobre a chamada sai da máquina.

Licença

MIT. Consulte LICENSE. O serviço implantado em https://optionsahoy.com/mcp e https://optionsahoy.com/api/v1 é gratuito durante o beta sob os termos.

Contato

Para parcerias, acesso antecipado à API, suporte de integração MCP: andrew@alphalatitude.com