MCP-DOE-PI

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:

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

Related MCP server: Brazilian PEP MCP Server

🛠️ As 4 ferramentas

📋 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.