# mcp-analytics

A camada de **calculo** do [Finance Brain](../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`.

```bash
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

```bash
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:

```python
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.