processo-mcp

<h1 align="center"> <img alt="MCP-Processo" src="https://raw.githubusercontent.com/fxbarros/MCP-Processo/main/docs/assets/banner.svg?sanitize=true"> <br> <small>O processo de 2.000 páginas nunca entra inteiro na conversa</small> </h1>

<p align="center"> <img alt="Python" src="https://img.shields.io/badge/python-3.12+-3776AB?logo=python&logoColor=white"> <img alt="Testes" src="https://img.shields.io/badge/testes-77%20%E2%9C%93-brightgreen"> <img alt="Plataforma" src="https://img.shields.io/badge/macOS-Apple%20Silicon-black?logo=apple"> <img alt="MCP" src="https://img.shields.io/badge/MCP-Claude%20Desktop%20%2F%20Code-d97757"> <img alt="Local" src="https://img.shields.io/badge/dados-100%25%20local%20por%20padr%C3%A3o-8b0000"> </p>

<p align="center"> <a href="#%EF%B8%8F-como-funciona"><strong>Como funciona</strong></a> · <a href="#%EF%B8%8F-as-13-ferramentas"><strong>Ferramentas</strong></a> · <a href="#-ocr-em-cascata"><strong>OCR em cascata</strong></a> · <a href="#-custos-nada-%C3%A9-gasto-sem-confirma%C3%A7%C3%A3o"><strong>Custos</strong></a> · <a href="#-instala%C3%A7%C3%A3o"><strong>Instalação</strong></a> · <a href="#-testes"><strong>Testes</strong></a> </p>

MCP-Processo é um servidor MCP que faz RAG local sobre processos judiciais e administrativos volumosos em PDF (PJe, SEI, escaneados) no Claude Desktop/Code.

Jogar um PDF de 2 mil páginas no chat estoura a janela de contexto e gera alucinação. Aqui o processo vira texto página a página + um índice local — e na conversa entram só os trechos relevantes de cada pergunta, sempre com citação de (arquivo, p. N) verificável no original. Um caso de 2.000 páginas custa ao chat o mesmo que um de 20.

Feito por um advogado, para uso forense real: heurística anti-rodapé-PJe, índice de peças pela árvore do processo, cronologia por data de assinatura, validação literal de citações (dígito trocado é rejeitado) e quadro de controvérsias em .docx.

⚔️ Como funciona

~/Processos/meu-caso/  ←  jogue o(s) PDF(s) na pasta
        │
        ▼
"prepara o caso"       →  texto página a página + OCR local (grátis)
        │                 portão de integridade: o que ficou ilegível?
        ▼
"pode indexar"         →  estimativa de custo → SUA confirmação → índice
        │                 híbrido BM25 + denso (voyage-4-large) + rerank
        ▼
"busca X no caso"      →  trechos com página exata:【arquivo — p. N】

• 1 chunk = 1 página — a unidade natural de citação forense.
• Busca por sentido ("quebra da affectio societatis" acha "perda da clientela") e por identificador ("Lei 3.208", nº CNJ completo).
• Índice visual (voyage-multimodal-3): página fotográfica/ilegível continua achável pela aparência.
• Incremental por hash e conteúdo: PDF novo, substituído ou re-OCRizado reindexa só o que mudou — nunca o caso inteiro.

🛠️ As 13 ferramentas

Ferramenta	O que faz
listar_casos	pastas de ~/Processos com status (PDFs, preparo, índice, resumo)
preparar_caso	extração + OCR local; caso grande roda em background
status_caso	progresso, pendências com custo, avisos de integridade
indexar_caso	estimativa → confirmação obrigatória → indexação (background se grande)
buscar	híbrida + rerank, filtro opcional por arquivo, seção de páginas visuais
obter_pagina	texto literal da página (validação de leitura)
abrir_pagina	abre o PDF original na página, no navegador
indice_pecas	árvore de documentos reconstruída do rodapé PJe (ou do nome do arquivo)
cronologia	peças ordenadas pela data de assinatura
validar_citacoes	CONFIRMADA · QUASE · DIVERGENTE · PÁGINA ERRADA · NÃO ENCONTRADA
quadro_controversias	tabela autor × réu em .docx paisagem
resumo_caso	memória do caso entre conversas (com backup automático)
ocr_nuvem	opt-in: Google Document AI para o que o OCR local não leu

🔍 OCR em cascata

Nível	Motor	Onde roda	Custo
1º	Apple Vision (Neural Engine)	100% local	zero
2º	Tesseract (fallback automático)	100% local	zero
—	Portão de integridade — lista o que ficou ilegível ANTES de qualquer gasto	local	zero
3º	Google Document AI (ocr_nuvem)	nuvem ⚠️	~US$ 1,50/1.000 pág.

O 3º nível é sempre manual e seletivo: a ferramenta lista as candidatas e o custo exato sem enviar nada; você audita as duvidosas com abrir_pagina (foto/planta sem texto não vale envio) e autoriza só as páginas que quiser (paginas=[...]). Sem motor de OCR funcional, o preparo aborta antes de destruir a extração anterior.

💰 Custos: nada é gasto sem confirmação

• Extração + OCR local: grátis, ilimitado.
• Indexação (Voyage): centavos por caso (~R$ 1,70 em um processo real de 1.561 páginas). Estimativa exata antes, confirmação sua, sempre.
• OCR em nuvem (opt-in): cobrado por página, prévia exata, requisição que falha não é cobrada.
• Texto (e imagem das páginas visuais) vai à Voyage sob política no-train do plano pago; para material sigiloso, use billing ativo.

📦 Instalação

git clone https://github.com/fxbarros/MCP-Processo && cd MCP-Processo
uv sync

Pré-requisitos: uv, Tesseract com por (brew install tesseract tesseract-lang), chave Voyage AI no Keychain (keyring set voyage-ai api_key). Registro no Claude Desktop (claude_desktop_config.json):

"processos": {
  "command": "uv",
  "args": ["--directory", "/caminho/para/MCP-Processo", "run", "processo-mcp"]
}

Instaladores prontos (Mac e Windows) em distribuicao/LEIA-ME.md. Para o ocr_nuvem (opcional): credencial GCP própria em ~/.config/processo-mcp/ — nunca no repositório.

💬 Uso no dia a dia

você: prepara o caso acp-sol-nascente claude: 1.561 páginas, 69 OCR, 0 ilegíveis. Pendente de indexação: ~1,7M tokens → US$ 0,30 (~R$ 1,67). Autoriza? você: pode indexar você: o que o réu respondeu sobre a impenhorabilidade? claude: 【contestacao.pdf — p. 85】"A arrematação de bem impenhorável..." (...) você: valida essa citação antes de eu usar na réplica claude: CONFIRMADA ✓ (similaridade 1.0)

🍎 Escopo: uso local em macOS

Projeto desenvolvido e mantido para uso pessoal, estritamente local, em macOS (Apple Silicon). Sinceridade acima de tudo:

• Windows/Linux: o Vision não existe fora do macOS — o OCR cai no Tesseract (qualidade inferior em página fotografada). O instalador de Windows nunca foi testado em máquina real.
• Não é um servidor: transporte stdio puro, sem HTTP, sem autenticação, sem multiusuário. Cada pessoa roda a própria cópia na própria máquina.
• Testado em um hardware só: MacBook Air M2 / 8 GB — lotes e limiares calibrados para esse perfil.

✅ Testes

uv run pytest

77 testes, 100% offline: rodam em pasta temporária (nunca tocam ~/Processos) e não chamam nenhuma API. Cobrem as armadilhas aprendidas em caso real — rodapé PJe mascarando página escaneada, roubo de rótulo na heurística de peças, dígito trocado em citação, caracteres invisíveis das atas, órfãos no índice, rebuild sem confirmação, teto de tokens por lote.

---

<p align="center">Autor: <strong>Fábio Ximenes Barros</strong> · arte do banner original, criada para o projeto</p>