Content
<h1 align="center">
<img alt="MCP PJe-TJMA 1º e 2º Graus" src="https://raw.githubusercontent.com/fxbarros/MCP-PJe-TJMA/main/docs/assets/banner.svg?sanitize=true">
<br>
<small>Expedientes, prazos e autos do PJe do TJ-MA 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** do Tribunal de Justiça do Maranhão (PJe-TJMA) — **1º e 2º graus** — em linguagem natural. Derivado do [MCP PJe-TJPI](https://github.com/fxbarros/MCP-PJe-TJPI), com as duas instâncias do TJMA atendidas pelo mesmo servidor.
## 🏛️ As duas instâncias
| Grau | URL | client_id (SSO PDPJ) |
|---|---|---|
| **1g** (varas) | `https://pje.tjma.jus.br/pje` | `pje-tjma-1g` |
| **2g** (câmaras/turmas) | `https://pje2.tjma.jus.br/pje2g` | `pje-tjma-2g` |
Toda ferramenta aceita o parâmetro `grau` (`"1"` padrão, `"2"` para o 2º grau — aceita também "segundo", "apelação", "câmara"...). 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-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 TJMA/` 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"`).
## 📂 Onde os arquivos são salvos
```
~/Library/Mobile Documents/com~apple~CloudDocs/
├── Processos TJMA 1 Grau/{cnj}/ # autos, documentos e peças do 1º grau
├── Processos TJMA 2 Grau/{cnj}/ # idem, 2º grau (mesmo CNJ ≠ mesma pasta!)
└── Modelos TJMA/ # 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-tjma
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-TJPI** neste Mac, pule esta etapa — o servidor reaproveita as credenciais PDPJ do service `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-tjma`) — nunca em arquivo.
### 3) Registre o MCP no Claude Desktop
`~/Library/Application Support/Claude/claude_desktop_config.json` (ajuste os caminhos):
```json
{
"mcpServers": {
"pje-tjma": {
"command": "/Users/SEU_USUARIO/mcp-pje-tjma/venv/bin/python",
"args": ["/Users/SEU_USUARIO/mcp-pje-tjma/src/server.py"]
}
}
}
```
### 4) Reinicie o Claude Desktop
`Cmd+Q` e abra de novo — as ferramentas devem aparecer.
## 💬 Exemplos de uso
```
Tenho expedientes pendentes no TJMA?
Quais meus prazos urgentes no 2º grau do TJMA?
Consulte o processo 0000000-00.0000.8.10.0001
Consulte a apelação 0000000-00.0000.8.10.0001 no 2º grau
Busca processos pela minha OAB no TJMA
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-tjma/
├── README.md
├── requirements.txt
├── setup_credenciais.py # setup inicial (opcional se já usa o MCP TJPI)
└── 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 TJMA/
```
## 🔒 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-TJMA. 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>
