mcp-data-explorer

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

Tools

Related MCP server: csv-analyzer-mcp

Instalação

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:

npx @modelcontextprotocol/inspector node build/index.js

Conectar a um cliente MCP:

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

Testes

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