StockFlow

StockFlow MCP

Um servidor FastMCP tipado para metadados de ações, histórico de preços, indicadores técnicos, demonstrações financeiras, calendários e cadeias de opções através do yfinance. Ele suporta transporte stdio local e HTTP Streamable em contêiner.

Ferramentas

• get_stock_data_v2(symbol, include_financials=False, include_analysis=False, include_calendar=False)
• get_historical_data_v2(symbol, period, interval='1d', prepost=False)
• get_options_chain_v2(symbol, expiration_date=None, include_greeks=False)

Downloads históricos usam explicitamente preços não ajustados, com reparo habilitado, retenção de fuso horário, timeout e um índice plano de símbolo único. As linhas mantêm os timestamps e omitem a coluna de fechamento ajustado separada. A volatilidade é anualizada para cada intervalo solicitado, usa 252/5 para barras de cinco dias e escala períodos intradiários para sessões estendidas. O RSI usa a semente canônica de média simples de Wilder seguida de suavização recursiva, com comportamento definido para ganho/perda zero. Quando solicitado, os Gregos de opções são estimativas teóricas europeias de Black-Scholes por ação (theta por dia; vega/rho por ponto percentual); os metadados da taxa livre de risco identificam o fallback configurado.

uv sync --locked
uv run python stockflow.py

O servidor usa stdio. O Yahoo Finance é uma fonte não oficial para uso pessoal e pode estar atrasado, incompleto, com limite de taxa, campos ausentes ou alterações estruturais. Dividendos e exercício antecipado estilo americano não são modelados nos Gregos. Os resultados não são aconselhamento de investimento nem dados em tempo real garantidos.

Docker / HTTP Streamable

O contêiner roda como um usuário sem privilégios, instala as dependências de produção bloqueadas e serve MCP em http://127.0.0.1:8000/mcp. Inicie com:

docker compose up --build -d
Invoke-RestMethod http://127.0.0.1:8000/health

Conecte um cliente MCP compatível com HTTP Streamable a http://127.0.0.1:8000/mcp. Para evitar colisão de portas ao executar vários servidores, defina MCP_HOST_PORT antes de iniciar o Compose, por exemplo $env:MCP_HOST_PORT=8003. Pare e remova o contêiner com docker compose down.

O mapeamento do Compose intencionalmente vincula-se a localhost. O endpoint não possui autenticação nem TLS e não deve ser exposto a uma rede não confiável sem um proxy reverso e controle de acesso configurados adequadamente.

Vincular apenas ao loopback não torna o endpoint privado: um navegador ainda pode alcançá-lo por meio de rebinding de DNS, então o servidor valida os cabeçalhos Host e Origin antes que uma solicitação alcance uma sessão MCP. Solicitações com Host estrangeiro são respondidas com 421 Misdirected Request e aquelas com Origin estrangeiro com 403 Forbidden, enquanto tráfego de loopback de mesma origem e clientes não navegadores que não enviam Origin não são afetados.

Variável	Padrão	Finalidade
MCP_TRANSPORT	stdio	stdio, http ou streamable-http.
MCP_HOST	127.0.0.1	Interface à qual o servidor HTTP vincula.
MCP_PORT	8000	Porta dentro do contêiner.
MCP_PATH	/mcp	Caminho do endpoint HTTP Streamable.
MCP_HOST_PORT	8000	Porta do host que o Compose publica em 127.0.0.1.
MCP_HOST_ORIGIN_PROTECTION	true	true, auto ou false. Desative apenas atrás de um proxy que execute a mesma validação.
MCP_ALLOWED_HOSTS	não definido	Nomes de host extras separados por vírgula permitidos em Host.
MCP_ALLOWED_ORIGINS	não definido	Origens de navegador extras separadas por vírgula permitidas em Origin.

Coloque o nome do host do proxy reverso em MCP_ALLOWED_HOSTS ao colocar o contêiner na frente, caso contrário, a proteção rejeita o Host com proxy. Executar uv run python stockflow.py permanece o padrão compatível com stdio fora do Docker.

Execute a validação com uv lock --check, uv run ruff check ., uv run mypy ., uv run pytest, uv build e uv run python scripts/verify_wheel.py. O CI também compila o contêiner e realiza verificações de saúde e descoberta de ferramentas MCP via HTTP Streamable. A cobertura de ramos de domínio/provedor é limitada a 90%. Defina YFINANCE_LIVE=1 para aceitar testes de fumaça de forma viva.