<h1 align="center">
    <img alt="MCP PJe-TRF1 1º e 2º Graus" src="https://raw.githubusercontent.com/fxbarros/MCP-PJe-TRF1/main/docs/assets/banner.svg?sanitize=true">
    <br>
    <small>Expedientes, prazos e autos do PJe da Justiça Federal da 1ª Região em linguagem natural — 1º e 2º graus num único servidor, sem nunca escrever no tribunal</small>
</h1>

<p align="center">
    <img alt="Python" src="https://img.shields.io/badge/python-3.10+-3776AB?logo=python&logoColor=white">
    <img alt="Ferramentas" src="https://img.shields.io/badge/ferramentas-24-brightgreen">
    <img alt="Graus" src="https://img.shields.io/badge/graus-1g%20%2B%202g-blueviolet">
    <img alt="MCP" src="https://img.shields.io/badge/MCP-Claude%20Desktop-d97757">
    <img alt="Login" src="https://img.shields.io/badge/login-CPF%20%2B%20senha%20%2B%20TOTP%20autom%C3%A1tico-black">
    <img alt="Somente leitura" src="https://img.shields.io/badge/PJe-somente%20leitura-8b0000">
</p>

Servidor [MCP](https://modelcontextprotocol.io) que permite ao Claude Desktop consultar o **Processo Judicial Eletrônico** da Justiça Federal da 1ª Região (PJe-TRF1) — **1º e 2º graus** — em linguagem natural. Derivado do [MCP PJe-TJMA](https://github.com/fxbarros/MCP-PJe-TJMA) (que por sua vez deriva do [MCP PJe-TJPI](https://github.com/fxbarros/MCP-PJe-TJPI)), com as duas instâncias do TRF1 atendidas pelo mesmo servidor.

## 🏛️ As duas instâncias

| Grau | URL | client_id (SSO PDPJ) |
|---|---|---|
| **1g** (varas federais/JEFs) | `https://pje1g.trf1.jus.br/pje` | `pje-trf1-1g` |
| **2g** (turmas do TRF1) | `https://pje2g.trf1.jus.br/pje` | `pje-trf1-2g` |

Toda ferramenta aceita o parâmetro `grau` (`"1"` padrão, `"2"` para o 2º grau — aceita também "segundo", "apelação", "turma", "trf"...). O singleton mantém **uma** sessão de Chromium por vez, chaveada por `(persona, grau)`: trocar de grau fecha a sessão anterior e loga na outra instância.

> O login é no **SSO nacional do PDPJ** (`sso.cloud.pje.jus.br`) — as mesmas credenciais CPF + senha + TOTP valem para os dois graus (e para outros tribunais). Se você já usa o MCP PJe-TJMA ou PJe-TJPI neste Mac, as credenciais do Keychain são reaproveitadas automaticamente.

## ✨ Funcionalidades

- 🔐 **Login 100% automatizado**: CPF + senha + 2FA (TOTP)
- ⚖️ **1º e 2º graus** no mesmo servidor, com pastas de download separadas por grau (o mesmo nº CNJ existe nos dois graus)
- 📋 **Expedientes pendentes** e ⏰ **alertas de prazos urgentes** (3 dias)
- 🔍 **6 formas de busca**: nº CNJ, nome da parte, nome do advogado, CPF, CNPJ e OAB
- 📄 **Listagem, leitura e download de documentos** (HTML e PDF), incluindo autos completos com **download em background** (imune ao timeout do protocolo MCP)
- 🗂️ **Histórico completo de expedientes** de um processo (inclusive fechados/vencidos)
- 📝 **Fluxo de produção**: modelos de petição, salvamento de petições e relatórios na pasta do processo
- 🛡️ **Tratamento automático** do aviso da Resolução CNJ 121/2010 (processos de terceiros)

## 🛠️ As 24 ferramentas

**Painel e prazos**

| Ferramenta | O que faz |
|---|---|
| `expedientes_pendentes` | intimações/despachos pendentes de ciência ou resposta |
| `verificar_prazos_urgentes` | expedientes com data limite em ≤ 3 dias |
| `pendencias_processo` | pendências (expedientes + prazos) de UM processo |
| `expedientes_do_processo` | histórico COMPLETO de expedientes (inclui fechados/vencidos) |

**Consulta e busca**

| Ferramenta | O que faz |
|---|---|
| `consultar_processo` | dados básicos do processo por nº CNJ |
| `ultimas_movimentacoes` | N últimas movimentações |
| `relatorio_processo` | relatório completo: dados, movimentações e documentos |
| `buscar_por_nome_parte` / `buscar_por_nome_advogado` | busca por nome |
| `buscar_por_cpf` / `buscar_por_cnpj` / `buscar_por_oab` | busca por identificador |

**Documentos e autos**

| Ferramenta | O que faz |
|---|---|
| `listar_documentos` | todos os documentos do processo |
| `ler_documento` | texto integral de um documento (HTML ou PDF) |
| `ultima_decisao` | teor da última decisão/sentença/despacho/ato ordinatório |
| `ultimo_despacho` | teor do último despacho (só despacho) |
| `baixar_documento` | baixa UM documento e salva na pasta do processo |
| `baixar_processo` | baixa os autos COMPLETOS (em background por padrão) |
| `status_download` | acompanha um download em andamento |
| `preparar_processo` | baixa o processo e decide a estratégia de análise |

**Produção de peças (grava só no SEU disco, nunca no PJe)**

| Ferramenta | O que faz |
|---|---|
| `listar_modelos_peticao` / `ler_modelo_peticao` | modelos em `Modelos TRF1/` no iCloud |
| `salvar_peticao_processo` | salva petição (.docx) na pasta do processo |
| `salvar_relatorio_processo` | salva relatório de análise na pasta do processo |

Parâmetros comuns: `grau` (`"1"`/`"2"`) e `persona` (`"advogado"` padrão ou `"procurador"`).

## 🔬 Diferenças do TRF1 em relação aos MCPs TJMA/TJPI

Descobertas na validação ao vivo (18/07/2026) que motivaram adaptações no parser:

- **Sigla de classe em CamelCase** (`MSCiv`, `ApCiv`), não maiúsculas puras (`MS`, `AP`) — regexes de cabeçalho aceitam `[A-Za-z]`;
- **IDs de documento com 10 dígitos** (TJMA usa 8) — limites de dígitos ampliados para `{6,12}`;
- **Download nativo sem S3**: o botão Download (`a#navbar:downloadProcesso`, com `confirm()`) dispara `POST /pje/seam/resource/rest/download-autosdigitais/download` e o servidor responde **o próprio PDF** na mesma requisição. O cliente intercepta esse POST via `context.route`, reescreve `cronologia`/`idTipoDocumento` no form e captura os bytes de uma geração só. Suporte a `downloadParticionado` (junta as partes com pypdf);
- O modal de download do TRF1 **não tem** as opções "incluir expediente/movimentos" do TJMA — os parâmetros são aceitos e ignorados.

## 📂 Onde os arquivos são salvos

```
~/Library/Mobile Documents/com~apple~CloudDocs/
├── Processos TRF1 1 Grau/{cnj}/    # autos, documentos e peças do 1º grau
├── Processos TRF1 2 Grau/{cnj}/    # idem, 2º grau (mesmo CNJ ≠ mesma pasta!)
└── Modelos TRF1/                   # modelos .docx/.md de petição/relatório
```

## 🧰 Requisitos

- macOS (credenciais no Keychain; em Linux/Windows funciona com `keyring` equivalente)
- Python 3.10+
- Claude Desktop instalado
- Conta ativa no PDPJ com 2FA configurado via app autenticador

## 📦 Instalação

### 1) Ambiente virtual + dependências

```bash
cd mcp-pje-trf1
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium
```

### 2) Credenciais

Se você **já usa o MCP PJe-TJMA ou PJe-TJPI** neste Mac, pule esta etapa — o servidor reaproveita as credenciais PDPJ dos services `mcp-pje-tjma`/`mcp-pje-tjpi` do Keychain (fallback automático).

Senão:

```bash
python3 setup_credenciais.py
```

O script pergunta CPF, senha PDPJ e seed TOTP e grava tudo no Keychain (service `mcp-pje-trf1`) — nunca em arquivo.

### 3) Registre o MCP no Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (ajuste os caminhos):

```json
{
  "mcpServers": {
    "pje-trf1": {
      "command": "/Users/SEU_USUARIO/mcp-pje-trf1/venv/bin/python",
      "args": ["/Users/SEU_USUARIO/mcp-pje-trf1/src/server.py"]
    }
  }
}
```

### 4) Reinicie o Claude Desktop

`Cmd+Q` e abra de novo — as ferramentas devem aparecer.

## 💬 Exemplos de uso

```
Tenho expedientes pendentes na Justiça Federal?

Quais meus prazos urgentes no TRF1?

Consulte o processo 0000000-00.0000.4.01.4000

Consulte a apelação 0000000-00.0000.4.01.4000 no 2º grau

Busca processos pela minha OAB no TRF1

Liste os documentos do processo e lê a última decisão

Baixa os autos completos e prepara o processo para análise
```

## 🏗️ Estrutura do projeto

```
mcp-pje-trf1/
├── README.md
├── requirements.txt
├── setup_credenciais.py     # setup inicial (opcional se já usa MCP TJMA/TJPI)
├── teste_login_graus.py     # smoke test ao vivo: login + painel nos 2 graus
└── src/
    ├── server.py            # servidor MCP (24 tools, param grau em todas)
    ├── pje_client.py        # cliente Playwright (URL_BASES por grau)
    ├── cliente_singleton.py # 1 sessão viva, chaveada por (persona, grau)
    ├── pje_downloader.py    # downloads (pastas por grau, jobs em background)
    ├── minutas.py           # salvar petições/relatórios (.docx/.md/.txt)
    └── modelos.py           # leitura de modelos em Modelos TRF1/
```

## ✅ Estado da validação (18/07/2026)

| Fluxo | 1º grau | 2º grau |
|---|---|---|
| Login SSO + troca de perfil | ✅ ao vivo | ✅ ao vivo |
| Painel de expedientes | ✅ ao vivo (0 pendentes) | ✅ ao vivo (0 pendentes) |
| Formulário de consulta (CNJ/nome/doc/OAB) | ✅ ao vivo | ✅ ao vivo |
| Busca por OAB | ✅ ao vivo (8 processos) | ✅ ao vivo (0 resultados) |
| Autos: partes, timeline, docs, leitura REST | ✅ ao vivo | ⏳ pendente (sem processo no 2g ainda) |
| Download nativo dos autos completos | ✅ ao vivo (335 págs., 14,7 MB) | ⏳ pendente |

O código do 2º grau é o mesmo do 1º (só muda o host); a pendência é apenas de confirmação empírica quando houver processo lá.

## 🔒 Segurança

- **Credenciais** ficam no Keychain do macOS, nunca em arquivo
- **Seed TOTP** tratada como secret — não commitar nunca
- **Nenhuma ação de escrita no PJe**: este MCP só **lê** informação do tribunal — nunca protocola, peticiona ou altera nada (as ferramentas de "salvar" gravam apenas no seu disco local)
- **Resolução CNJ 121/2010**: consulta a processo de terceiro é registrada pelo próprio PJe e o retorno inclui o aviso

## ⚠️ Avisos importantes

**Validade das credenciais** — a senha do PDPJ expira periodicamente; ao trocar no site, rode `setup_credenciais.py` de novo (ou atualize o service que estiver em uso no Keychain).

**Fragilidade de scraping** — o projeto depende do HTML/JavaScript atual do PJe-TRF1. Se o tribunal mudar o layout: rode com `PJE_HEADLESS=0` para ver onde trava, pegue os novos seletores no DevTools e atualize o `pje_client.py`.

**Uso responsável** — respeite o termo de uso do PJe; nada de scraping massivo; consultas a processos de terceiros ficam registradas — use com responsabilidade profissional.

## 📝 Licença e créditos

Uso pessoal e profissional, sem garantias — use por sua conta e risco, respeitando as regras do tribunal e do seu cliente. Construído por [Fábio Ximenes Barros](https://github.com/fxbarros) com ajuda do [Claude](https://www.anthropic.com/claude), usando [Playwright](https://playwright.dev), [PyOTP](https://pyauth.github.io/pyotp/), [Scrapling](https://github.com/D4Vinci/Scrapling) e [pdfplumber](https://github.com/jsvine/pdfplumber).

<p align="center"><sub>Arte do banner: original — marca dos projetos MCP do autor.</sub></p>