# processo-mcp

Servidor MCP para trabalhar com **processos volumosos em PDF** (PJe, SEI,
escaneados) no Claude Desktop/Code. O processo nunca entra inteiro na conversa:
texto extraído página a página (OCR local via Tesseract), índice híbrido
BM25+denso (voyage-4-large) + rerank, índice **visual** para páginas ilegíveis
(voyage-multimodal-3), citação sempre com arquivo + página exata e validação
literal de citações.

## Escopo: uso local em macOS

Projeto desenvolvido e mantido para **uso pessoal, estritamente local, em
macOS** (Apple Silicon). O OCR primário é o **framework Vision** da Apple
(Neural Engine, via `ocrmac`) — mais preciso que o Tesseract em página
fotografada/torta e 100% local.

**Limitações se você for usar fora desse cenário (sinceridade acima de tudo):**

- **Windows/Linux**: o Vision não existe fora do macOS — o OCR cai
  automaticamente no Tesseract (fallback), com qualidade inferior em página
  fotografada. O instalador de Windows (`distribuicao/instalar-windows.ps1`)
  **nunca foi testado em máquina Windows 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.
- **Chave Voyage individual**: texto (e imagem das páginas "visuais") é
  enviado à API da Voyage para embedding. Para material sigiloso, use plano
  com billing ativo (política no-train) — a estimativa de custo sempre pede
  confirmação antes de gastar.
- **Testado em um hardware só**: MacBook Air M2 / 8 GB. Ajustes de lote e
  limiares foram calibrados para esse perfil.

**Instalação:** ver [distribuicao/LEIA-ME.md](distribuicao/LEIA-ME.md).

## Testes

```bash
uv run pytest
```

Suíte 100% offline: roda em pasta temporária (nunca toca `~/Processos`) e não
chama a API da Voyage (índice populado com embeddings sintéticos). Cobre as
armadilhas históricas do projeto — rodapé PJe mascarando página escaneada,
roubo de rótulo na heurística de peças, dígito trocado em citação, chars
invisíveis das atas, órfãos no índice, rebuild sem confirmação.

12 ferramentas: `listar_casos`, `preparar_caso`, `status_caso`, `indexar_caso`
(estimativa de custo + confirmação obrigatória), `buscar`, `obter_pagina`,
`abrir_pagina`, `indice_pecas`, `cronologia`, `validar_citacoes`,
`quadro_controversias`, `resumo_caso`.

Autor: Fábio Ximenes Barros.