<h1 align="center">
    <img alt="MCP DOE-PI" src="https://raw.githubusercontent.com/fxbarros/MCP-DOE-PI/main/docs/assets/banner.svg?sanitize=true&v=2">
    <br>
    <small>Edições, busca no conteúdo e leitura integral dos atos do Diário Oficial do Estado do Piauí em linguagem natural — sem baixar PDF</small>
</h1>

<p align="center">
    <img alt="Python" src="https://img.shields.io/badge/python-3.12+-3776AB?logo=python&logoColor=white">
    <img alt="Ferramentas" src="https://img.shields.io/badge/ferramentas-4-brightgreen">
    <img alt="MCP" src="https://img.shields.io/badge/MCP-Claude%20Desktop-d97757">
    <img alt="Fonte" src="https://img.shields.io/badge/fonte-DOE--PI%20oficial-004a8f">
    <img alt="Sem autenticação" src="https://img.shields.io/badge/acesso-sem%20login%20%C2%B7%20sem%20Cloudflare-black">
    <img alt="Somente leitura" src="https://img.shields.io/badge/DOE-somente%20leitura-8b0000">
</p>

Servidor [MCP](https://modelcontextprotocol.io) que permite ao Claude Desktop consultar o **Diário Oficial do Estado do Piauí** ([diario.pi.gov.br/doe](https://www.diario.pi.gov.br/doe)) em linguagem natural: lista edições, busca por conteúdo nos atos publicados e lê o texto integral de qualquer ato **sem baixar PDF**.

## ⚙️ Como funciona

O portal do DOE-PI é um front DataTables/jQuery sobre três APIs internas que respondem a `POST` form-urlencoded, **sem autenticação e sem Cloudflare**:

| Endpoint | Função |
|---|---|
| `Api/listardiarios.json` | lista edições (`filter_numero`, `filter_data` em `yyyy-mm-dd`) |
| `Api/buscaavancada.json` | busca por palavras-chave no conteúdo (`filter_texto`) |
| `Api/visualizarnota.json` | texto integral do ato em HTML (`uuid`) |

> `GET` nesses endpoints retorna 500 — o método precisa ser `POST`.

## 🛠️ As 4 ferramentas

| Ferramenta | O que faz |
|---|---|
| **`listar_edicoes`** | edições com link do PDF; filtros por data (`yyyy-mm-dd`) e número |
| **`buscar_conteudo`** | palavras-chave no texto dos atos; retorna o `uuid_ato` de cada resultado (filtro de ano aplicado localmente) |
| **`ler_ato`** | texto integral do ato pelo `uuid`, direto da base do portal — **sem baixar PDF** |
| **`baixar_edicao`** | baixa o PDF diagramado para `~/Downloads` (para citação formal ou juntada) |

## 📋 Limitações conhecidas

- O acervo do portal começa na edição **240/2022 (14/12/2022)**.
- A busca normaliza acentos e aceita casamento parcial de palavras — confira o campo `palavras_encontradas` de cada resultado.
- A busca devolve tudo de uma vez (sem paginação); termos muito comuns demoram alguns segundos.

## 🧰 Requisitos

- macOS (ou Linux) com [uv](https://docs.astral.sh/uv/) instalado
- Claude Desktop instalado
- Python 3.12+ (o `uv` cuida do ambiente automaticamente)

## 📦 Instalação

### 1) Clonar

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

### 2) Registrar o MCP no Claude Desktop

No `claude_desktop_config.json` (menu **Configurações → Desenvolvedor → Editar config**), adicione:

```json
"doe-pi": {
  "command": "/Users/SEU_USUARIO/.local/bin/uv",
  "args": ["--directory", "/caminho/para/MCP-DOE-PI", "run", "doe-pi-mcp"]
}
```

### 3) Reiniciar o Claude Desktop

As quatro ferramentas passam a aparecer no ícone de conector do DOE-PI.

## 💬 Exemplos de uso

- *"Liste as edições do DOE-PI de 15/07/2026."*
- *"Busque 'desapropriação de utilidade pública' no Diário Oficial do Estado em 2025."*
- *"Leia o inteiro teor daquele decreto de crédito suplementar."*
- *"Baixe o PDF da edição 134 para eu juntar no processo."*

## 🏗️ Estrutura do projeto

```
MCP-DOE-PI/
├── README.md
├── pyproject.toml
├── docs/assets/banner.svg      # marca dos projetos MCP do autor
├── src/doe_pi_mcp/
│   ├── server.py               # servidor MCP (4 tools)
│   └── doe_client.py           # cliente HTTP + conversor HTML→texto (lxml)
└── tests/
    └── test_limpar_html.py     # testes offline do conversor de notas
```

## 🔬 Notas de implementação

- O HTML das notas é convertido em texto com **lxml** (não regex); tabelas — comuns em decretos orçamentários — são renderizadas linha a linha com células separadas por ` | `, preservando a relação código/valor.
- O transporte httpx faz **retry automático de conexão** (3 tentativas) contra instabilidades do portal.
- A busca (`buscaavancada.json`) não pagina nem filtra por data no servidor: o cliente puxa o acervo inteiro e faz o recorte de `ano`/`limite` localmente.

## 🔒 Segurança e responsabilidade

- **Somente leitura**: este MCP apenas **consulta** o Diário Oficial — nunca publica, altera ou remove nada.
- **Sem credenciais**: o portal é público; nada de login, token ou secret.
- **Não inventa resultados**: se o portal cair ou ficar lento, as ferramentas retornam um erro explícito instruindo o modelo a avisar o usuário, em vez de alucinar atos.
- **Uso responsável**: nada de scraping massivo; respeite o termo de uso do portal.
- **Contingência anti-bot**: hoje o portal não tem Cloudflare nem exige TLS de navegador. Se isso mudar (como ocorreu com o SCON/STJ), o caminho de migração é o `StealthySession`/`FetcherSession(impersonate="chrome")` do [Scrapling](https://github.com/D4Vinci/Scrapling), mantendo o mesmo cliente de parsing.

## 📝 Licença e créditos

Uso pessoal e profissional, sem garantias — use por sua conta e risco, respeitando as regras do portal. Construído por [Fábio Ximenes Barros](https://github.com/fxbarros) com ajuda do [Claude](https://www.anthropic.com/claude), usando [httpx](https://www.python-httpx.org) e [lxml](https://lxml.de).

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