mcp-analytics

A camada de calculo do Finance Brain: uma biblioteca quantitativa para pairs trading baseado em cointegracao, exposta como servidor MCP. E a camada que decide e dimensiona com estatistica; o LLM (os agentes do Finance Brain) apenas opina e narra. Um backtest que mente e pior que nenhum, entao correcao e disciplina anti-lookahead vem antes de tudo.

Espelha a arquitetura e o envelope de retorno {"ok": ..., "data": ...} do servidor de dados Scout (mcp-market-research): cada ferramenta e uma casca fina e sem estado sobre um nucleo puro e testavel offline. Apenas o carregador de dados, o servidor e o healthcheck tocam a rede.

Por que existe

Da analise critica de TradingAgents e ai-hedge-fund (em finance-brain/ANALISE_REPOS.md), a lacuna que nenhum dos dois preencheu foi validacao out-of-sample seria com custos realistas. Backtests sem custos e sem separacao treino/teste superestimam retorno e enganam. Esta camada existe exatamente para fazer isso direito.

Garantias anti-lookahead (a diretriz suprema)

Toda decisao no instante t usa apenas informacao disponivel ate t. Imposto em codigo e coberto por testes:

• Apenas estatistica movel (rolling). O z-score usa media/desvio em janela movel (model/spread.py), nunca a serie inteira. Alterar spread[t+k] nao pode mudar z[t] para t < t+k.
• Defasagem de execucao D+1. O backtest faz positions = signals.shift(1) antes de aplicar os retornos (backtest/engine.py). Decisao e execucao nunca compartilham o mesmo preco; equity[t] depende apenas de precos e sinais ate t.
• Calibracao so no TREINO. Selecao do par, hedge ratio e limiares sao fixados na fatia de treino; a fatia de teste fica intocada ate a aplicacao (validation/walk_forward.py). Metricas in-sample e out-of-sample sao reportadas separadamente — a diferenca entre elas e o indice de overfitting.
• Hedge ratio movel causal. O beta rolling opcional usa apenas a janela passada.

Custos desde o dia 1

Nunca opcionais. commission_bps + slippage_bps sao cobrados em cada perna de toda abertura e fechamento (quatro incidencias por round-trip), e um carrego diario de aluguel do short (borrow_rate_annual / 252) e debitado sobre a perna vendida enquanto a posicao esta aberta. Ligar os custos sempre reduz o retorno final — ha um teste que afirma exatamente isso.

Avisos honestos

O relatorio de performance sinaliza Sharpe > 3 ou win rate > 90% como provavel sinal de overfitting ou vazamento de lookahead. Resultado bom demais tem de ser barulhento, nao comemorado.

Modulos (os 9 da especificacao)

Modulo	Arquivo	Responsabilidade
1	data/loader.py	Baixa (yfinance, ajustado), alinha (intersecao de datas), cacheia em parquet
2a	selection/correlation.py	Pre-filtro barato por correlacao (de retornos, nao de niveis)
2b	selection/cointegration.py	Engle-Granger + correcao de multiplos testes (Bonferroni)
3	model/hedge_ratio.py	Beta OLS estatico (+ beta rolling causal opcional)
4	model/spread.py	Spread e z-score rolling
5	signals/rules.py	Sinais com estado: entrada/saida/stop
6	backtest/engine.py	P&L dia a dia com defasagem D+1, custos e contabilidade de duas pernas
7	validation/walk_forward.py	Split temporal e walk-forward (in-sample vs out-of-sample)
8	risk/sizing.py	Half-life, sizing por alvo de volatilidade, limites de risco
9	metrics/performance.py	Sharpe, Sortino, drawdown, CAGR, vs-benchmark, avisos

Ferramentas MCP

Ferramenta	O que faz
test_cointegration(ticker_a, ticker_b, start, end)	Engle-Granger: p-valor, hedge ratio, cointegrado?
find_pairs(tickers, start, end, min_corr=0.8, alpha=0.05, bonferroni=True)	Pre-filtro por correlacao + cointegracao com Bonferroni; pares ranqueados
analyze_spread(ticker_a, ticker_b, start, end, window=60)	Hedge ratio, half-life, z-score atual, estatisticas do spread
run_pairs_backtest(ticker_a, ticker_b, start, end, split_date, ...)	Backtest com custos e D+1; in-sample vs out-of-sample, resumo de equity/trades, avisos, benchmark buy-and-hold (SPY)
walk_forward(ticker_a, ticker_b, start, end, train_window, test_window, step, ...)	Tabela de performance treino vs teste por janela
performance_metrics(returns, periods_per_year=252)	Metricas completas para uma serie de retornos arbitraria
estimate_half_life(ticker_a, ticker_b, start, end, window=60)	Half-life da reversao (Ornstein-Uhlenbeck / AR(1))
position_size(capital, n_active_pairs, vol_target=0.10, realized_vol=None)	Capital por par com alvo de volatilidade
risk_limits(capital, pair_vol, vol_target=0.10, correlation=None, ...)	Limites de posicao por volatilidade/correlacao

Series longas voltam como resumo (estatisticas + head/tail) para manter o payload enxuto; a biblioteca guarda a serie completa internamente.

Instalar e rodar

Pre-requisitos: Python 3.11+ e uv.

uv venv .venv
uv pip install -e ".[dev]" --python .venv/bin/python

# Suite de testes offline (a definicao de pronto: 44 testes, inclui anti-lookahead)
.venv/bin/python -m pytest -q

# Smoke test ao vivo (precisa de rede para o yfinance)
.venv/bin/python -m analytics.healthcheck                 # padrao: KO vs PEP
.venv/bin/python -m analytics.healthcheck KO PEP 2021-01-01 2024-01-01

Scripts de console (apos instalar): mcp-analytics (o servidor) e analytics-healthcheck.

Registrar como MCP no Claude Code

claude mcp add analytics -- /caminho/para/mcp-analytics/.venv/bin/python -m analytics.server.app

Exemplo de uso (biblioteca, em Python)

O nucleo e composto de funcoes puras sobre pandas, testaveis sem rede:

from analytics.selection.cointegration import test_cointegration
from analytics.data.loader import load_prices

prices = load_prices(["KO", "PEP"], "2021-01-01", "2024-01-01")
result = test_cointegration(prices["KO"], prices["PEP"])
# {"pvalue": 0.27, "hedge_ratio": 0.26, "is_cointegrated": False}

Arquitetura

src/analytics/
  data/         # Modulo 1: carregamento e alinhamento de precos ajustados
  selection/    # Modulos 2a/2b: correlacao e cointegracao (Bonferroni)
  model/        # Modulos 3/4: hedge ratio e spread/z-score
  signals/      # Modulo 5: regras de entrada/saida/stop
  backtest/     # Modulo 6: engine com custos e defasagem D+1
  validation/   # Modulo 7: split temporal e walk-forward
  risk/         # Modulo 8: half-life, sizing, limites
  metrics/      # Modulo 9: metricas de performance e avisos
  server/app.py # servidor MCP (FastMCP) expondo as ferramentas
  healthcheck.py
tests/          # testes unitarios por modulo, incluindo os anti-lookahead obrigatorios

Licenca

MIT.

---

Documento e ferramenta de pesquisa para paper trading. Nao constitui recomendacao de investimento.