MCP-DOE-PI

<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 que permite ao Claude Desktop consultar o Diário Oficial do Estado do Piauí (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 instalado
• Claude Desktop instalado
• Python 3.12+ (o uv cuida do ambiente automaticamente)

📦 Instalação

1) Clonar

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:

"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, 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 com ajuda do Claude, usando httpx e lxml.

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