{
  "markdown": "# Querido Diário MCP Server\n\n<!-- mcp-name: io.github.lucaspmgomess/querido-diario-mcp-server -->\n\n**Consulte diários oficiais municipais brasileiros diretamente pelo Claude, Cursor, Codex e outros clientes compatíveis com MCP.**\n\n[![PyPI](https://img.shields.io/pypi/v/querido-diario-mcp-server.svg)](https://pypi.org/project/querido-diario-mcp-server/)\n[![Python](https://img.shields.io/pypi/pyversions/querido-diario-mcp-server.svg)](https://pypi.org/project/querido-diario-mcp-server/)\n[![CI](https://github.com/lucaspmgomess/querido-diario-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaspmgomess/querido-diario-mcp-server/actions/workflows/ci.yml)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-published-brightgreen)](https://registry.modelcontextprotocol.io/?q=io.github.lucaspmgomess%2Fquerido-diario-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\n**Sem chave de API · Executa localmente · Somente leitura · Sem telemetria · Código aberto**\n\n> 🌎 **English version:** [README.en.md](./README.en.md)\n\nO **Querido Diário MCP Server** conecta agentes de IA à API pública do [Querido Diário](https://queridodiario.org.br), permitindo consultar diários oficiais municipais brasileiros por meio de ferramentas estruturadas do Model Context Protocol (MCP).\n\n> **Exemplo de uso:**  \n> \"Encontre todas as menções a inteligência artificial nos diários oficiais de Porto Alegre em 2026.\"\n\nO agente pode identificar o município correto, resolver seu código IBGE, consultar o índice de diários oficiais e devolver resultados estruturados sem que o usuário precise conhecer a API.\n\n---\n\n## Por que este projeto existe?\n\nO [Querido Diário](https://queridodiario.org.br), mantido pela [Open Knowledge Brasil](https://ok.org.br/), torna diários oficiais municipais brasileiros pesquisáveis por meio de uma plataforma de dados abertos e de uma API pública.\n\nEste projeto adiciona uma **interface nativa de MCP** sobre essa API, permitindo que clientes e agentes de IA utilizem os dados diretamente como ferramentas.\n\nSem o MCP, um fluxo típico exigiria:\n\n1. descobrir o município correto;\n2. obter o código IBGE correspondente;\n3. conhecer a API do Querido Diário;\n4. montar os parâmetros de busca;\n5. interpretar manualmente a resposta.\n\nCom este servidor, um agente compatível com MCP pode executar esse fluxo de forma estruturada.\n\nO servidor roda localmente como um subprocesso e realiza apenas requisições HTTPS de leitura para a API pública do Querido Diário.\n\n---\n\n## O que dá para fazer?\n\n### Licitações, compras públicas e contratos\n\nPesquise empresas, processos licitatórios, contratos, termos de contratação e referências a compras governamentais.\n\n> \"Encontre menções à ACME Ltda nos diários oficiais de Porto Alegre entre janeiro e julho de 2026.\"\n\n### Pessoas e organizações\n\nAcompanhe menções a pessoas, empresas, associações, órgãos públicos e outras organizações.\n\n> \"Pesquise João da Silva nos diários oficiais de Torres, RS.\"\n\n### Leis, decretos e atos administrativos\n\nPesquise legislação municipal, decretos, nomeações, exonerações, atos administrativos e mudanças regulatórias.\n\n> \"Encontre publicações relacionadas à regulamentação de inteligência artificial.\"\n\n### Jornalismo de dados e pesquisa cívica\n\nUse o Querido Diário como fonte estruturada em fluxos de pesquisa assistidos por IA.\n\n> \"Busque contratos públicos relacionados a reconhecimento facial nos diários oficiais de Porto Alegre.\"\n\n### Agentes e automações\n\nCombine a busca em diários oficiais com outros servidores MCP para criar fluxos maiores de investigação, classificação, acompanhamento e análise de informações públicas.\n\n---\n\n## Início rápido\n\nRequisitos:\n\n- Python 3.12+\n- [`uv`](https://docs.astral.sh/uv/), que fornece o comando `uvx`\n\nNão é necessário clonar o repositório.\n\n```bash\nuvx querido-diario-mcp-server\n```\n\nEsse comando inicia o servidor MCP via `stdio`.\n\nO servidor não possui interface interativa no terminal por design: ele foi feito para ser iniciado por um cliente MCP.\n\n---\n\n## Conectando ao seu cliente de IA\n\nTodos os clientes abaixo usam o mesmo comando:\n\n```bash\nuvx querido-diario-mcp-server\n```\n\n### Claude Desktop / Claude Code\n\nAdicione ao `claude_desktop_config.json` no Claude Desktop ou ao `.mcp.json` do projeto no Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"querido-diario\": {\n      \"command\": \"uvx\",\n      \"args\": [\"querido-diario-mcp-server\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdicione ao `.cursor/mcp.json` do projeto ou às configurações globais de MCP do Cursor:\n\n```json\n{\n  \"mcpServers\": {\n    \"querido-diario\": {\n      \"command\": \"uvx\",\n      \"args\": [\"querido-diario-mcp-server\"]\n    }\n  }\n}\n```\n\n### Codex CLI\n\nAdicione ao arquivo `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.querido-diario]\ncommand = \"uvx\"\nargs = [\"querido-diario-mcp-server\"]\n```\n\n### Outros clientes MCP\n\nQualquer cliente compatível com servidores MCP locais via `stdio` pode utilizar:\n\n- comando: `uvx`\n- argumento: `querido-diario-mcp-server`\n\nConsulte a documentação do seu cliente para o formato exato da configuração.\n\n---\n\n## Ferramentas disponíveis\n\nO servidor expõe propositalmente uma superfície pequena e somente leitura.\n\n| Ferramenta | Finalidade |\n|---|---|\n| `search_cities` | Busca municípios brasileiros por nome parcial e resolve o código IBGE de 7 dígitos. Permite filtro opcional por estado. |\n| `get_city` | Consulta os detalhes de um município usando seu código IBGE exato de 7 dígitos. |\n| `search_gazettes` | Realiza busca textual em diários oficiais indexados, com filtros por município, período, paginação e ordenação. |\n\n### Sintaxe de busca\n\nA ferramenta `search_gazettes` utiliza a sintaxe **simple query string** do OpenSearch usada pela API do Querido Diário.\n\nExemplos:\n\n| Consulta | Significado |\n|---|---|\n| `inteligência artificial` | Encontra qualquer um dos termos |\n| `+inteligência +artificial` | Exige os dois termos |\n| `-cancelado` | Exclui um termo |\n| `\"João da Silva\"` | Busca uma expressão exata |\n\n---\n\n## Exemplo completo\n\nO usuário pergunta:\n\n```text\nEncontre menções à ACME Ltda nos diários oficiais de Porto Alegre\nentre janeiro e julho de 2026.\n```\n\nO cliente MCP pode executar:\n\n```text\n1. search_cities(city_name=\"Porto Alegre\")\n   → territory_id: \"4314902\"\n\n2. search_gazettes(\n       query='\"ACME Ltda\"',\n       territory_ids=[\"4314902\"],\n       published_since=\"2026-01-01\",\n       published_until=\"2026-07-31\",\n   )\n```\n\nO agente recebe os resultados de forma estruturada e pode então resumir, comparar, classificar ou combinar essas informações com outras ferramentas.\n\nOutros exemplos de prompts:\n\n```text\nQual é o registro do município de Torres, RS, no Querido Diário?\n```\n\n```text\nPesquise referências a compras públicas de inteligência artificial\nnos diários oficiais de Porto Alegre.\n```\n\n```text\nEncontre publicações mencionando uma determinada empresa durante 2025.\n```\n\n```text\nConsulte o município correspondente ao código IBGE 3550308.\n```\n\n---\n\n## Demonstração\n\nAinda não há um vídeo, GIF ou captura de tela desta seção — de propósito, para não sugerir um comportamento que não foi validado de fato. Assim que houver uma demonstração real do servidor rodando dentro do Claude ou do Cursor, ela será adicionada aqui.\n\n---\n\n## Como funciona\n\n```text\nCliente de IA\n   │\n   │ MCP / stdio\n   ▼\nquerido-diario-mcp-server\n   │\n   │ requisições HTTPS tipadas\n   ▼\nAPI pública do Querido Diário\n```\n\nEstrutura do projeto:\n\n```text\nsrc/querido_diario_mcp_server/\n    __init__.py   # versão do pacote + ponto de entrada\n    config.py     # configuração por variáveis de ambiente\n    errors.py     # hierarquia de erros da integração\n    models.py     # modelos Pydantic tipados\n    client.py     # cliente HTTP assíncrono da API\n    server.py     # camada MCP e definição das ferramentas\n```\n\nA implementação separa propositalmente a integração HTTP da camada MCP:\n\n- `client.py` não depende do MCP;\n- `server.py` concentra validação, ferramentas e comportamento de protocolo;\n- um único `httpx.AsyncClient` é criado no ciclo de vida do servidor e reutilizado;\n- erros da API são convertidos em mensagens MCP curtas e compreensíveis para o agente.\n\n---\n\n## Local-first e somente leitura\n\nO projeto foi desenhado para ser conservador em relação ao que um agente pode fazer.\n\n- Executa somente requisições `GET`.\n- Não possui operações de escrita.\n- Não exige conta.\n- Não exige chave de API.\n- Não coleta telemetria.\n- Não utiliza backend proprietário.\n- Não utiliza proxy hospedado.\n- O agente não pode fornecer uma URL arbitrária para o servidor buscar.\n- URLs de diários retornadas pela API não são abertas automaticamente.\n- Código IBGE, datas, paginação e ordenação são validados.\n- Respostas de erro HTML da API não são repassadas integralmente ao agente.\n\nIsso reduz a superfície de risco e evita transformar o servidor MCP em um mecanismo genérico de requisições externas ou SSRF.\n\n### Fora de escopo nesta fase\n\nA versão atual não implementa:\n\n- busca arbitrária de URLs;\n- download automático de PDF ou texto integral;\n- OCR;\n- operações de escrita;\n- banco de dados local;\n- crawling;\n- jobs em segundo plano;\n- sumarização por LLM embutida;\n- interface web.\n\nO objetivo é manter uma camada MCP pequena, previsível e segura sobre a API pública existente.\n\n---\n\n## Configuração\n\n| Variável | Padrão | Finalidade |\n|---|---|---|\n| `QD_API_BASE_URL` | `https://api.queridodiario.org.br` | URL base da API do Querido Diário. Pode ser sobrescrita para ambientes locais ou de staging. |\n\nPara uso normal, nenhuma configuração adicional é necessária.\n\n---\n\n## Instalação e distribuição\n\nO pacote está publicado em:\n\n- [PyPI](https://pypi.org/project/querido-diario-mcp-server/)\n- [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.lucaspmgomess%2Fquerido-diario-mcp-server)\n\nNome no PyPI:\n\n```text\nquerido-diario-mcp-server\n```\n\nNome no MCP Registry:\n\n```text\nio.github.lucaspmgomess/querido-diario-mcp-server\n```\n\n---\n\n## Desenvolvimento\n\nClone o repositório apenas se quiser contribuir ou trabalhar na implementação:\n\n```bash\ngit clone https://github.com/lucaspmgomess/querido-diario-mcp-server.git\ncd querido-diario-mcp-server\nuv sync\n```\n\nExecute os mesmos checks usados pelo CI:\n\n```bash\nuv run ruff check .\nuv run ruff format --check .\nuv run pyright\nuv run pytest --cov\n```\n\nPara executar o servidor a partir do checkout local:\n\n```bash\nuv run querido-diario-mcp-server\n```\n\nPara inspecionar as ferramentas MCP interativamente:\n\n```bash\nuv run mcp dev src/querido_diario_mcp_server/server.py:mcp\n```\n\n---\n\n## Estratégia de testes\n\n### Testes do cliente HTTP\n\nO `client.py` é testado com `httpx.MockTransport`, portanto a suíte automatizada não depende de internet nem de uma instância ativa do Querido Diário.\n\nA cobertura inclui:\n\n- requisições bem-sucedidas;\n- busca de municípios;\n- serialização de parâmetros;\n- múltiplos `territory_ids`;\n- períodos;\n- paginação;\n- ordenação;\n- resultados vazios;\n- erros 400/404/422;\n- erros 5xx;\n- respostas malformadas;\n- timeouts;\n- falhas de conexão.\n\n### Testes de integração MCP\n\nOs testes de integração executam o servidor MCP real por meio do cliente in-process do SDK.\n\nEles verificam:\n\n- descoberta das ferramentas;\n- schemas de entrada;\n- saída estruturada e tipada;\n- falhas de validação;\n- falhas da integração upstream;\n- conversão de erros em mensagens MCP limpas, sem traceback Python bruto.\n\n### Smoke tests manuais\n\nHá dois scripts de verificação manual contra produção:\n\n```bash\nuv run python scripts/smoke_test_api.py\nuv run python scripts/smoke_test_mcp.py\n```\n\nEles podem ser usados para validar a API real e o caminho completo MCP → cliente HTTP → API.\n\n---\n\n## Relação com o Querido Diário\n\nEste é um **projeto comunitário e não oficial**.\n\nO [Querido Diário](https://queridodiario.org.br) é mantido pela [Open Knowledge Brasil](https://ok.org.br/) e sua comunidade.\n\nEste repositório:\n\n- não é um projeto oficial da Open Knowledge Brasil, salvo eventual adoção expressa pela organização;\n- não é afiliado, endossado ou mantido pela Open Knowledge Brasil;\n- não copia nem distribui a implementação do Querido Diário;\n- apenas consulta a API pública do projeto.\n\nRepositórios upstream relevantes:\n\n- [okfn-brasil/querido-diario](https://github.com/okfn-brasil/querido-diario) — coleta/scrapers\n- [okfn-brasil/querido-diario-api](https://github.com/okfn-brasil/querido-diario-api) — API pública\n- [okfn-brasil/querido-diario-deployment](https://github.com/okfn-brasil/querido-diario-deployment) — configuração de deployment\n\nA API de produção utilizada por padrão é:\n\n```text\nhttps://api.queridodiario.org.br\n```\n\nNotas adicionais sobre o histórico dos endpoints estão em:\n\n[`docs/upstream-api-history.md`](./docs/upstream-api-history.md)\n\n---\n\n## Por que código aberto?\n\nExistem integrações hospedadas que expõem dados do Querido Diário para clientes MCP.\n\nEste projeto segue uma abordagem diferente:\n\n- a implementação do servidor é pública;\n- o servidor roda na máquina do próprio usuário;\n- não há middleware hospedado;\n- não há conta;\n- não há chave de API;\n- não há telemetria;\n- a API pública do Querido Diário é acessada diretamente.\n\nAssim, todo o caminho entre o agente e a fonte de dados pode ser inspecionado.\n\n---\n\n## Feedback e uso real\n\nSe você utilizar este projeto em pesquisa, civic tech, jornalismo de dados, análise de compras públicas ou em algum fluxo com agentes de IA, seu feedback é especialmente útil.\n\nExemplos de feedback que ajudam:\n\n- uma busca difícil de expressar;\n- um caso de município que não funcionou como esperado;\n- dificuldade de configuração em algum cliente MCP;\n- um filtro que faria diferença no uso real;\n- comportamento inesperado da API upstream;\n- um exemplo de como você está utilizando o servidor.\n\nAbra uma [issue](https://github.com/lucaspmgomess/querido-diario-mcp-server/issues) descrevendo o caso de uso ou problema encontrado.\n\nO objetivo é evoluir o projeto com base em uso real, mantendo o servidor pequeno, seguro e somente leitura.\n\n---\n\n## Contribuindo\n\nIssues e pull requests são bem-vindos.\n\nAntes de abrir uma PR, execute:\n\n```bash\nuv run ruff check .\nuv run ruff format --check .\nuv run pyright\nuv run pytest --cov\n```\n\nMantenha novas ferramentas e comportamentos alinhados ao objetivo do projeto: oferecer a agentes compatíveis com MCP acesso seguro e estruturado à API pública do Querido Diário.\n\n---\n\n## Licença\n\n[MIT](./LICENSE)\n",
  "bytes": 14431,
  "sha": "ebcafceac5d4d944cab87cfe3df83a371dca6d69d08f1cf353cd20fa8aeca009",
  "repo_slug": "lucaspmgomess/querido-diario-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lucaspmgomess_querido_diario_m_bc61403f/readme"
}