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.

Related MCP server: BotSpot

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)

Ferramentas MCP

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.