🦅 DataClaw MCP Server

AI-First CSV Analysis Tool — um servidor MCP para agentes de IA e workflows com LLM. Feito para datasets grandes (10k–1M linhas) com precisão cirúrgica.

🚦 Status: v3.2 — em validação com dados reais. O servidor passou da bateria sintética para datasets públicos de verdade (Olist e-commerce, ~1,5 milhão de linhas em 9 arquivos). Essa rodada encontrou 4 defeitos que os testes sintéticos não pegavam — todos já corrigidos e descritos abaixo, com transparência total. O time de testes segue validando com novas bases nas próximas semanas. Deploy em produção previsto para as próximas semanas, condicionado aos itens de segurança listados no fim deste documento.

🧠 O que é o DataClaw?

DataClaw é um servidor Model Context Protocol (MCP) que dá a agentes de IA a capacidade de analisar, consultar e auditar arquivos CSV sem escrever uma linha de código.

A ideia central: o CSV nunca entra no contexto do LLM. O pandas calcula tudo localmente e o agente recebe apenas um JSON de ~10 KB com os números já prontos e rótulos inequívocos. Um arquivo de 1 milhão de linhas e o de 5 mil produzem exatamente a mesma estrutura de resposta — muda só o conteúdo.

Objetivo principal: servir como servidor MCP para agentes de IA, especificamente para uso no OpenClaw.

Related MCP server: CSV Analytics MCP Server

🔒 Princípio de confiabilidade

Nenhuma transformação é silenciosa. Tudo que o servidor faz com os dados volta no JSON, com contagem:

Estatísticas de coluna são calculadas sobre o arquivo inteiro, nunca sobre amostra. Se algum dia houver amostragem, o campo stats_scope diz explicitamente.

O servidor não decide o que é duplicata

Duas linhas idênticas podem ser erro de digitação ou venda legítima (duas unidades do mesmo item no mesmo pedido). O dado sozinho não desempata — então o DataClaw não remove nada por padrão. Ele conta, classifica a confiança e recomenda:

"deduplication": {
  "exact_duplicate_rows": 11033,
  "rows_removed_total": 11033,
  "duplicate_confidence": "baixa",
  "confidence_reason": "arquivo transacional (tem data e valor): linhas idênticas
                        costumam ser itens repetidos legítimos, não erro de digitação",
  "duplicate_pct": 9.79,
  "recommended_action": "NÃO remover automaticamente; confirme a regra de negócio antes"
}

Para analisar sem as duplicatas, é uma escolha explícita: analyze_csv(arquivo, deduplicate=True). Os dois totais (total_WITH_duplicates e total_WITHOUT_duplicates) vêm sempre no JSON.

🛠️ Tools expostas

Todas as tools de leitura aceitam deduplicate: bool = False. Em clean_csv o padrão é True — limpar é o objetivo dela —, mas ela avisa (WARNING_DEDUP) quando a confiança na remoção é baixa.

🚀 Instalação e uso

pip install -r requirements.txt
python server.py            # sobe via stdio

Registro em um cliente MCP:

{
  "mcpServers": {
    "dataclaw": {
      "command": "python",
      "args": ["/caminho/absoluto/para/dataclaw-mcp/server.py"]
    }
  }
}

🧪 Testes

python tests/test_dataclaw.py                    # 129 checks contra gabarito sintético
python tests/test_mcp_protocol.py                # smoke test do protocolo MCP via stdio
python tests/test_dados_reais.py <arquivo|pasta> # valida QUALQUER CSV contra o pandas

test_dataclaw.py cobre precisão contra gabarito, conservação, invariância (5k/50k/150k linhas, metades, ordem embaralhada, latin-1, locale en-US, TAB), determinismo e robustez (arquivo vazio, prosa, só cabeçalho, linha malformada, quebra de linha dentro de aspas, coluna inexistente, filtro sem match).

test_dados_reais.py é a ferramenta de validação com dados novos. Aponte para um CSV ou uma pasta e ele confere o servidor contra o pandas puro, sem gabarito pré-calculado — serve para qualquer base que o time de testes trouxer:

python tests/test_dados_reais.py ~/dados/vendas_2026.csv
python tests/test_dados_reais.py ~/dados/           # a pasta inteira

Ele valida contagem de registros (via csv.reader, respeitando aspas e quebra de linha), soma/média/mediana/máx/mín contra o pandas, as duas leis de conservação, coerência entre o total reportado e a base declarada, fechamento do ranking completo, denúncia de métrica inválida, determinismo e a invariância metade + metade.

📋 Rodada de validação com dados reais — o que foi encontrado e corrigido

Dataset: Olist Brazilian E-Commerce (9 arquivos, ~1,5 milhão de linhas, 123 MB), mais uma planilha de vendas achatada de 112.650 linhas montada por join — o formato que um usuário de negócio realmente manda para o agente.

Resultado depois das correções: 129/129 na suíte sintética, 109/109 na validação com os 9 arquivos reais, 37/37 na bateria específica dos defeitos acima, e o smoke test MCP verde. O que já estava correto continuou correto: contagem de registros exata em todos os arquivos (incluindo os 99.224 registros de reviews espalhados em 104.720 linhas físicas por quebra de linha dentro de aspas), soma/média/mediana idênticas ao pandas, determinismo, filtro insensível a caixa e acento, e 1.000.163 linhas processadas sem erro.

⚠️ Mudança de contrato na v3.2

Quem já consumia o JSON precisa saber:

A invariante de conservação agora é rows_parsed == rows_after_dedup + duplicate_rows_found.

⚠️ Limitações atuais

• Variantes de texto só são unificadas quando diferem em caixa, acento, espaço ou pontuação. S. Paulo e SP não são unificados a São Paulo — casamento fuzzy traz risco de fundir categorias distintas. Eles aparecem separados no ranking.

• analyze_csv cobre até 3 dimensões categóricas por rodada. O campo columns_detected.categorical_dimensions_analyzed diz quais foram — use query_csv para as demais.

• Colunas com mais de 1000 valores distintos não passam pela unificação de variantes.

• A tendência mensal mostra os últimos 12 meses; monthly_trend_scope informa o total.

• Transporte apenas stdio; file_path aceita qualquer caminho do disco local.

🔐 Antes do deploy em produção

O deploy hospedado multiusuário depende destes itens, ainda pendentes:

• Transporte HTTP no lugar de stdio

• Autenticação por token

• Sandbox de arquivos — hoje o servidor lê qualquer caminho da máquina

• Limite de tamanho de arquivo e timeout por requisição

Até lá, use apenas localmente ou em ambiente confiável.

🗺️ Próximos passos

1. ✅ Fase 1 — arquitetura JSON e suíte sintética

2. ✅ Fase 2 — validação com dados reais (Olist) e correção dos 4 defeitos

3. 🔄 Fase 3 — validação ampliada pelo time de testes com novas bases reais ← estamos aqui

4. ⏳ Fase 4 — hardening de segurança (HTTP + auth + sandbox)

5. ⏳ Fase 5 — deploy e publicação para os agentes do OpenClaw