<!-- mcp-name: io.github.DeHor-Labs/mcp-juridico-brasil -->

<p align="center">
  <img src="https://raw.githubusercontent.com/DeHor-Labs/mcp-juridico-brasil/main/assets/banner.svg" width="800" alt="MCP Juridico Brasil">
</p>

<p align="center">
  <strong>Conecte qualquer assistente de IA ao DataJud CNJ e aos 91 tribunais brasileiros - com cálculo de prazos, monitoramento de processos e conformidade com o CPC.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/mcp-juridico-brasil/"><img src="https://img.shields.io/pypi/v/mcp-juridico-brasil?color=003087&label=PyPI" alt="PyPI version"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-1a7a4a?logo=python&logoColor=white" alt="Python 3.10+"></a>
  <a href="https://github.com/DeHor-Labs/mcp-juridico-brasil/actions/workflows/ci.yml"><img src="https://github.com/DeHor-Labs/mcp-juridico-brasil/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/licenca-MIT-4fc3f7?labelColor=001f5b" alt="Licença MIT"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatível-7c3aed" alt="MCP Compatível"></a>
  <img src="https://img.shields.io/github/stars/DeHor-Labs/mcp-juridico-brasil?style=flat&color=003087" alt="Stars">
  <img src="https://img.shields.io/github/issues/DeHor-Labs/mcp-juridico-brasil?color=4fc3f7&labelColor=001f5b" alt="Issues">
</p>

<p align="center">
  <a href="#o-que-é">O que é</a> ·
  <a href="#ferramentas-disponíveis">Ferramentas</a> ·
  <a href="#instalação">Instalação</a> ·
  <a href="#configuração-por-cliente-mcp">Configuração</a> ·
  <a href="#roadmap">Roadmap</a> ·
  <a href="#contribuindo">Contribuindo</a>
</p>

---

## ⚡ Comece em 60 segundos

Sem clonar nada, sem configurar ambiente — direto do PyPI:

```bash
uvx mcp-juridico-brasil
```

Plugando no **Claude Code** em um comando:

```bash
claude mcp add juridico-brasil -- uvx mcp-juridico-brasil
```

Pronto: seu assistente passa a consultar processos nos 91 tribunais (DataJud CNJ), pesquisar legislação no LexML, calcular prazos do CPC em dias úteis, montar minutas e gerar documentos Visual Law auditáveis. Configuração completa por cliente (Claude Desktop, Cursor, `.mcp.json`) logo abaixo.

> 📌 Este repositório é a **vitrine da versão atual (v0.5.0)** publicada por [@ehrodan](https://github.com/ehrodan). Snapshot pronto para instalar e integrar.

---

## O que é

`mcp-juridico-brasil` conecta assistentes de IA, escritórios de advocacia e sistemas de gestão processual ao **DataJud CNJ**, ao **Domicílio Judicial Eletrônico**, ao **LexML Brasil** e a um **corpus jurídico local em SQLite**. A camada processual cobre 91 tribunais; a camada normativa pesquisa metadados, sincroniza textos oficiais, cria embeddings locais por artigo, recupera fundamentos com fonte e SHA-256 e produz escrita estruturada com auditoria de fonte original e Visual Law.

O servidor não é um catálogo genérico de dados públicos. A proposta é transformar consultas judiciais e normativas fragmentadas em **tools seguras, componíveis e prontas para agentes** - com cálculo de prazos em dias úteis, monitoramento em lote, snapshots persistentes e confirmação humana obrigatória para qualquer ação com efeito jurídico.

---

## Ferramentas disponíveis

Tools processuais, normativas e de automação prontas para uso.

### Consulta e monitoramento de processos

| Ferramenta | Descrição | Fonte |
|------------|-----------|-------|
| `buscar_processo_por_numero` | Consulta completa de processo pelo número CNJ (NNNNNNN-DD.AAAA.J.TT.OOOO) | DataJud CNJ |
| `listar_movimentacoes` | Histórico de andamentos processuais com filtro por data | DataJud CNJ |
| `resumir_andamento` | Dados do processo mais instrução de resumo para o modelo de linguagem | DataJud CNJ |
| `monitorar_processo` | Verifica atualizações desde uma data (polling com snapshot em memória) | DataJud CNJ |
| `listar_processos_monitorados` | Lista processos com snapshot salvo na sessão atual | Memória local |
| `executar_monitoramento_em_lote` | Ciclo RPA finito, concorrente e tolerante a falhas para até 50 processos; somente leitura | DataJud CNJ |

### Pesquisa legislativa e jurídica

| Ferramenta | Descrição | Fonte |
|------------|-----------|-------|
| `pesquisar_lexml` | Pesquisa por termos, título, ementa, assunto ou URN, com filtros e paginação | LexML Brasil SRU/CQL |
| `resolver_urn_lexml` | Valida uma URN LEX brasileira e monta o resolvedor persistente oficial | Offline + URL LexML |

> **Vigência:** LexML é usado para descoberta, identificação e ligação. Confirme texto consolidado, alterações, revogações e data de corte na autoridade publicadora competente antes de fundamentar qualquer ato jurídico.

### Corpus inteligente, embeddings e minutas

| Tool | Descrição | Persistência/fonte |
|------|-----------|--------------------|
| `listar_fontes_corpus_juridico` | Catálogo curado das principais leis e códigos | Planalto |
| `sincronizar_corpus_juridico` | RPA finito: baixa HTML oficial, remove texto revogado, separa artigos, calcula SHA-256 e embeddings | SQLite local |
| `consultar_corpus_juridico` | Busca híbrida por embedding local (72%) e cobertura lexical (28%) | SQLite local |
| `estatisticas_corpus_juridico` | Cobertura, datas, hashes, fonte e localização do banco | SQLite local |
| `preparar_minuta_juridica` | Contratos, CT, termos, petições, contestações, notificações, pareceres e políticas de privacidade | Corpus local |
| `listar_tipos_minuta_juridica` | Tipos de minuta e campos recomendados | Offline |
| `construir_argumento_juridico` | Matriz Fato→Prova→Norma→Subsunção→Consequência→Pedido, com bloqueios explícitos | Corpus local |
| `auditar_citacoes_juridicas` | Recusa agregador, LexML isolado e jurisprudência sem inteiro teor oficial | Corpus + allowlist oficial |
| `gerar_documento_visual_law` | HTML acessível, responsivo e imprimível, mais sidecar JSON auditável | `data/visual-law/` |

O embedding padrão é determinístico, auditável e não envia texto para APIs externas. Ele não é um modelo neural. Cada resultado traz o texto do artigo, URL oficial, data da consulta e hash da versão baixada.

Fluxo recomendado:

```text
1. listar_fontes_corpus_juridico
2. sincronizar_corpus_juridico(fontes=["constituicao", "codigo_civil", "cpc", "clt", "lgpd"])
3. consultar_corpus_juridico(pergunta="Quais regras protegem dados pessoais no contrato?")
4. preparar_minuta_juridica(tipo_documento="ct", objetivo="...", dados={...})
5. construir_argumento_juridico(tese="...", fatos=[{"descricao": "...", "prova": "..."}], pedido="...")
6. gerar_documento_visual_law(titulo="...", tese="...", fatos=[...], pedido="...")
```

O RPA aceita somente HTTPS nos hosts allowlisted do Planalto, limita concorrência e tamanho, recusa desafios de segurança e substitui cada lei em transação. Se uma fonte falhar, a última versão local válida é preservada.

Na cópia da Área de Trabalho, os atalhos `SINCRONIZAR-LEIS.cmd` e `INICIAR-MCP.cmd` executam o RPA e o servidor usando o ambiente isolado do próprio projeto.

### Cálculo de prazos processuais

| Ferramenta | Descrição | Referência |
|------------|-----------|------------|
| `calcular_proximo_prazo` | Cálculo de prazo em dias úteis com calendário forense nacional e estadual (art. 219, 220 e 224 CPC) | Offline |

### Referência de tribunais

| Ferramenta | Descrição | Fonte |
|------------|-----------|-------|
| `listar_tribunais` | Lista todas as 91 siglas suportadas (Portaria CNJ 160/2020) | Offline |

### Resource MCP

| Resource | Descrição |
|----------|-----------|
| `processo://{numero}/snapshot` | Último snapshot capturado de um processo monitorado |

---

## Instalação

A forma mais simples, sem instalar nada permanentemente:

```bash
uvx mcp-juridico-brasil
```

> **O que é `uvx`?** É o gerenciador de ferramentas do [uv](https://docs.astral.sh/uv/), que baixa e executa pacotes Python em ambiente isolado, sem poluir seu sistema. Se ainda não tem o uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`

> **Mantendo atualizado:** use `uvx mcp-juridico-brasil@latest` ou `uvx --refresh mcp-juridico-brasil` para forçar a versão mais recente do PyPI.

### Instalação permanente (alternativa)

```bash
# via pip
pip install mcp-juridico-brasil

# via uv (recomendado para projetos Python)
uv add mcp-juridico-brasil
```

### A partir do código-fonte

```bash
git clone https://github.com/DeHor-Labs/mcp-juridico-brasil.git
cd mcp-juridico-brasil
uv sync
```

---

## Configuração por cliente MCP

Cole o trecho abaixo no arquivo de configuração do seu cliente. A variável `DATAJUD_API_KEY` é necessária para consultas ao DataJud CNJ - solicite em [datajud-wiki.cnj.jus.br](https://datajud-wiki.cnj.jus.br/api-publica/acesso/).

### Claude Desktop

Edite `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "juridico-brasil": {
      "command": "uvx",
      "args": ["mcp-juridico-brasil"],
      "env": {
        "DATAJUD_API_KEY": "sua-chave-aqui"
      }
    }
  }
}
```

Reinicie o Claude Desktop. As ferramentas jurídicas aparecem automaticamente.

### Claude Code (CLI)

```bash
claude mcp add juridico-brasil -- uvx mcp-juridico-brasil
```

Para incluir a chave de API:

```bash
DATAJUD_API_KEY=sua-chave-aqui claude mcp add juridico-brasil -- uvx mcp-juridico-brasil
```

### Cursor / `.mcp.json`

Crie ou edite `.cursor/mcp.json` (ou `.mcp.json` na raiz do projeto):

```json
{
  "mcpServers": {
    "juridico-brasil": {
      "command": "uvx",
      "args": ["mcp-juridico-brasil"],
      "env": {
        "DATAJUD_API_KEY": "sua-chave-aqui"
      }
    }
  }
}
```

### VS Code + Continue

Adicione ao `settings.json`:

```json
{
  "continue.mcpServers": {
    "juridico-brasil": {
      "command": "uvx",
      "args": ["mcp-juridico-brasil"],
      "env": {
        "DATAJUD_API_KEY": "sua-chave-aqui"
      }
    }
  }
}
```

---

## Variáveis de ambiente

| Variável | Descrição | Padrão |
|----------|-----------|--------|
| `DATAJUD_API_KEY` | Chave de acesso ao DataJud CNJ (necessária para consultas) | - |
| `JURIDICO_LOG_LEVEL` | Nível de log: `DEBUG`, `INFO`, `WARNING` | `INFO` |
| `JURIDICO_SNAPSHOT_DIR` | Diretório para persistência de snapshots em arquivo (opcional) | memória |
| `JURIDICO_HTTP_TIMEOUT` | Timeout em segundos para chamadas HTTP | `30` |
| `LEXML_BASE_URL` | Endpoint oficial SRU 1.1 | `https://www.lexml.gov.br/busca/SRU` |
| `LEXML_CACHE_TTL` | Cache local de pesquisas LexML, em segundos | `900` |
| `LEXML_RATE_LIMIT` | Máximo de chamadas LexML por segundo | `2` |
| `JURIDICO_CORPUS_DB` | Banco SQLite do corpus local | `data/corpus_juridico.sqlite3` |
| `JURIDICO_EMBEDDING_DIMENSIONS` | Dimensão do embedding local | `384` |
| `JURIDICO_VISUAL_LAW_DIR` | HTMLs Visual Law e auditorias JSON gerados | `data/visual-law` |

---

## Arquitetura

```
Claude / GPT / Cursor / qualquer cliente MCP
              |
              | Model Context Protocol (stdio)
              v
    mcp-juridico-brasil
              |
    +---------+---------+-----------+----------+--------+----------+
    |         |         |           |          |        |          |
 Processos  DJe     Automação   Snapshots   Prazos   LexML     Corpus/RAG
    |         |         |           |          |        |          |
    v         v         v           v          v        v          v
 DataJud  API Comunica DataJud   mem/disco Calendário SRU/CQL  SQLite+hash
   CNJ       CNJ      (lote)                  offline  + URN    embedding
```

**Fontes de dados:**
- [DataJud CNJ](https://datajud-wiki.cnj.jus.br/) - base unificada de dados judiciais (Portaria CNJ 160/2020)
- [LexML Brasil](https://www.lexml.gov.br/) - metadados jurídicos, padrão URN LEX e resolvedor persistente
- [Planalto](https://www.planalto.gov.br/legislacao/) - textos legais oficiais sincronizados no corpus local
- Calendário forense nacional e estadual - processado offline para cálculo de prazos (CPC art. 219/220/224)

Diagramas executáveis e UML ficam em [`docs/arquitetura/`](docs/arquitetura/). A política de escrita, fonte original e Visual Law está em [`docs/POLITICA-ESCRITA-JURIDICA-VISUAL-LAW.md`](docs/POLITICA-ESCRITA-JURIDICA-VISUAL-LAW.md).

---

## Roadmap

- [x] **v0.1.x** - Busca de processo, listagem de movimentações, resumo de andamento e listagem de tribunais
- [x] **v0.2.x** - Snapshot atômico, prazos, DJe com gate duplo, LexML SRU/CQL e monitoramento RPA em lote
- [x] **v0.3.x** - Corpus oficial local, embeddings por artigo, busca híbrida, RPA de leis e minutas ancoradas
- [ ] **v0.4.x** - Fontes oficiais alternativas para contingência LexML e extração estruturada de publicações
- [ ] **v1.0.0** - Suite processual completa com auditoria LGPD, contratos de API estáveis e cobertura ampliada

---

## Privacidade e LGPD

> **Atenção:** o `mcp-juridico-brasil` acessa exclusivamente dados públicos disponibilizados pelo DataJud CNJ (Resolução CNJ 331/2020). Processos em **segredo de justiça** não são retornados pela API e não são acessados por este servidor. Nenhum dado processual é armazenado fora do ambiente local do usuário - exceto quando `JURIDICO_SNAPSHOT_DIR` é configurado explicitamente. O uso das ferramentas é de responsabilidade do profissional habilitado, em conformidade com a LGPD (Lei 13.709/2018), a Resolução CNJ 647/2025 e a OAB Recomendação 001/2024. Estas ferramentas não constituem consultoria jurídica.

---

## Contribuindo

Contribuições são bem-vindas!

```bash
# 1. Clone o repositório ou seu fork
git clone https://github.com/DeHor-Labs/mcp-juridico-brasil.git
cd mcp-juridico-brasil

# 2. Instale as dependências de desenvolvimento
uv sync

# 3. Crie sua branch
git checkout -b feature/meu-recurso

# 4. Implemente, teste e verifique
pytest
ruff check src/
mypy src/

# 5. Abra um Pull Request
```

Veja as [issues abertas](https://github.com/DeHor-Labs/mcp-juridico-brasil/issues) - especialmente as marcadas com `good first issue`.

Cada módulo segue o padrão `client.py` + `schemas.py` + `tools.py`, tornando simples adicionar novos módulos processuais.

---

## Projeto irmão

Este servidor faz par com o **MCP Fiscal Brasil**, que conecta IAs ao sistema fiscal brasileiro (NF-e, SPED, CNPJ, Simples Nacional, Reforma Tributária 2026):

[github.com/DeHor-Labs/mcp-fiscal-brasil](https://github.com/DeHor-Labs/mcp-fiscal-brasil)

---

## Licença

MIT - veja [LICENSE](LICENSE) para detalhes.

---

<p align="center">
  Feito com dedicação para o Judiciário brasileiro
  <br>
  <sub>Conectando inteligência artificial aos 91 tribunais do sistema de justiça nacional</sub>
</p>