MCP 服务器

MCP-DOE-PI

Allows querying the Diário Oficial do Estado do Piauí (DOE-PI) in natural language: list editions, search content, and read full texts without downloading PDFs.

README

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

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"><sub>Arte do banner: original — marca dos projetos MCP do autor.</sub></p>