<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-92%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>
    &middot;
    <a href="#%EF%B8%8F-as-13-ferramentas"><strong>Ferramentas</strong></a>
    &middot;
    <a href="#-ocr-em-cascata"><strong>OCR em cascata</strong></a>
    &middot;
    <a href="#-custos-nada-%C3%A9-gasto-sem-confirma%C3%A7%C3%A3o"><strong>Custos</strong></a>
    &middot;
    <a href="#-instala%C3%A7%C3%A3o"><strong>Instalação</strong></a>
    &middot;
    <a href="#-testes"><strong>Testes</strong></a>
</p>

**MCP-Processo** é um servidor [MCP](https://modelcontextprotocol.io) 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

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

Pré-requisitos: [uv](https://docs.astral.sh/uv/), Tesseract com `por` (`brew install tesseract tesseract-lang`), chave [Voyage AI](https://dashboard.voyageai.com) no Keychain (`keyring set voyage-ai api_key`). Registro no Claude Desktop (`claude_desktop_config.json`):

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

Instaladores prontos (Mac e Windows) em [distribuicao/LEIA-ME.md](distribuicao/LEIA-ME.md).

### OCR em nuvem (`ocr_nuvem`) — configuração opcional

Só necessário se você quiser o 3º nível da cascata (Google Document AI) para páginas que o OCR local não leu. **No Windows este recurso pesa mais**: sem o Vision, o Tesseract falha com mais frequência em página fotografada — mais páginas caem na lista de ilegíveis.

No Google Cloud (1 vez): crie um projeto com billing ativo, habilite a [Cloud Document AI API](https://console.cloud.google.com/apis/library/documentai.googleapis.com) e crie um processador em [Document AI → **Galeria de processadores** → Digitalização de texto → **Document OCR**](https://console.cloud.google.com/ai/document-ai/processors) (⚠️ não use a seção "Processadores personalizados" — são outros produtos, 20× mais caros). Anote o ID do processador e a região. Depois crie uma [service account](https://console.cloud.google.com/iam-admin/serviceaccounts) com o papel **Usuário da API Document AI** e baixe a chave JSON.

Na máquina, dois arquivos — **nunca no repositório**:

```bash
mkdir -p ~/.config/processo-mcp
mv ~/Downloads/sua-chave.json ~/.config/processo-mcp/gcp-ocr.json && chmod 600 ~/.config/processo-mcp/gcp-ocr.json
echo '{"processor_id": "SEU_ID", "location": "us"}' > ~/.config/processo-mcp/docai.json
```

No **Windows**, os mesmos nomes em `C:\Users\<voce>\.config\processo-mcp\` (é aí que o código procura; o `chmod` não se aplica). Caminhos alternativos via env `PROCESSO_MCP_GCP_CRED` e `PROCESSO_MCP_DOCAI_CONFIG` no bloco do config. Faltando algo, a própria ferramenta responde com a instrução exata do que falta.

### Windows

O projeto roda em Windows com duas diferenças: o OCR usa **só o Tesseract** (o Apple Vision não existe fora do macOS — qualidade inferior em página fotografada) e o instalador `distribuicao\instalar-windows.ps1` **nunca foi testado em máquina real**. Se preferir não usá-lo (ou se ele falhar), o passo a passo manual:

1. Instale o uv e o Tesseract: `winget install astral-sh.uv UB-Mannheim.TesseractOCR`
2. Se faltar o idioma português, copie [por.traineddata](https://github.com/tesseract-ocr/tessdata_fast/raw/main/por.traineddata) para `C:\Program Files\Tesseract-OCR\tessdata\` (a pasta exige permissão de administrador).
3. Na pasta do projeto, rode `uv sync` e grave a chave Voyage no Gerenciador de Credenciais do Windows:
   ```powershell
   uv run python -c "import keyring; keyring.set_password('voyage-ai','api_key','SUA-CHAVE')"
   ```
   Depois, limpe o comando do histórico do PowerShell (a chave fica visível nele).
4. Registre o mesmo bloco JSON acima em `%APPDATA%\Claude\claude_desktop_config.json`, com o caminho do projeto no formato Windows (ex.: `C:/Users/voce/MCP-Processo`).
5. Os casos ficam em `C:\Users\voce\Processos\` — ou aponte outra pasta via `"env": {"PROCESSO_MCP_PASTA": "D:/outro/caminho"}` no bloco do config.

## 💬 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

```bash
uv run pytest
```

92 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, falso-sucesso de OCR (página que "leu" só o carimbo), texto nativo virado mojibake por fonte CID sem ToUnicode, 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, redação de chave de API em mensagem de erro.

---

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