# mcp-data-explorer

![CI](https://github.com/Paul0Anselmi/mcp-data-explorer/actions/workflows/ci.yml/badge.svg)

Servidor MCP que permite a um LLM explorar datasets CSV via estatísticas, sem carregar os dados brutos no contexto.

## Tools

| Tool | Retorna |
|---|---|
| `inspect_dataset` | Linhas, colunas, tipo inferido e % de ausentes |
| `describe_column` | Média, desvio, quartis e outliers (IQR), ou top categorias |
| `query_dataset` | Estatísticas de um subconjunto filtrado, não as linhas |
| `correlate_columns` | Pearson e Spearman com intervalo de confiança, sinalizando divergência |
| `test_normality` | Jarque-Bera com assimetria, curtose e as limitações do teste |

## Instalação

```bash
git clone https://github.com/Paul0Anselmi/mcp-data-explorer.git
cd mcp-data-explorer
npm install && npm run build
```

Node 20+.

## Uso

Testar com o MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

Conectar a um cliente MCP:

```json
{
  "mcpServers": {
    "data-explorer": {
      "command": "node",
      "args": ["/caminho/absoluto/build/index.js"],
      "env": { "MCP_DATA_DIR": "/caminho/para/seus/csvs" }
    }
  }
}
```

## Testes

```bash
npm test
```

Os valores esperados foram calculados com pandas 3.0.2 e scipy 1.17.1 — quantis pelo tipo 7, desvio-padrão com `ddof=1`, assimetria e curtose populacionais. A suíte cobre interpolação de quantis, casos de borda, detecção de outliers, tratamento de empates no Spearman e o limiar de inferência de tipo.

## Segurança

O servidor só lê arquivos dentro do diretório definido em `MCP_DATA_DIR` (padrão: `./data`), recusa extensões diferentes de `.csv` e limita o tamanho a 100 MB.

Isso existe porque o caminho do arquivo é escolhido pelo modelo, não pelo usuário — e o modelo pode ser influenciado pelo conteúdo que está lendo. Sem essa restrição, instalar o servidor equivaleria a dar acesso de leitura ao disco inteiro. Quem instala define o escopo; o modelo não pode ampliá-lo.

## Decisões de implementação

- **Pearson e Spearman sempre juntos** — quando divergem, a relação é monotônica mas não linear, ou há outliers dominando. Devolver apenas um dos dois permite ao modelo concluir errado com confiança
- **Jarque-Bera declarando suas limitações** — teste assintótico, com pouco poder para n < 30 e sensível demais para n muito grande. O retorno avisa em vez de deixar o p-valor decidir sozinho
- **Quantis tipo 7 e variância com n−1** — mesmas definições de R, NumPy e pandas, o que torna os resultados diretamente comparáveis
- **Retorno sempre truncado** — top N categorias e outliers por amostra; devolver tudo reintroduziria o problema que o projeto resolve

## Limitações

A análise é univariada. Normalidade multivariada (Mardia) e diagnóstico de regressão dependem de rotinas que não valem reimplementar em TypeScript — entram junto com a camada opcional em Python.

## Roadmap

Camada opcional em Python/scipy (Shapiro-Wilk, regressão com diagnóstico de resíduos, normalidade multivariada) · streaming para arquivos grandes · amostragem com intervalo de confiança · histograma e bins · testes de hipótese entre grupos · Parquet · transporte HTTP

## Licença

MIT