Querido Diário MCP Server

Querido Diário MCP Server

一个本地优先的 Model Context Protocol 服务，为 AI 客户端提供对 Querido Diário 索引的巴西市政官方公报的结构化只读访问。

无需 API 密钥 · 本地运行 · 只读 · 无遥测 · 开源

🇧🇷 葡萄牙语版本

此软件包已发布到 PyPI 和 MCP Registry。

功能

Querido Diário 通过公共 API 提供可搜索的市政官方公报。此服务在该 API 之上提供精简、类型化的 MCP 接口，使 MCP 客户端能够：

• 查找巴西市政地区及其 IBGE 区域 ID；
• 按文本、市政地区和日期范围搜索已索引的官方公报；
• 获取结构化结果，方便 Agent 检查并与其他工具结合使用。

此服务作为本地 stdio 子进程运行，只向 Querido Diário 公共 API 发出只读 HTTPS 请求。

快速开始

需要 Python 3.12+ 和 uv。

无需克隆代码库：

uvx querido-diario-mcp-server

这会通过 stdio 启动 MCP 服务。此服务旨在由 MCP 客户端启动，而非作为交互式终端应用使用。

客户端配置

所有受支持的客户端使用相同的命令：

uvx querido-diario-mcp-server

Claude Desktop / Claude Code

{
  "mcpServers": {
    "querido-diario": {
      "command": "uvx",
      "args": ["querido-diario-mcp-server"]
    }
  }
}

Claude Desktop 请在 claude_desktop_config.json 中使用此配置；Claude Code 请在项目级 .mcp.json 中使用。

Cursor

{
  "mcpServers": {
    "querido-diario": {
      "command": "uvx",
      "args": ["querido-diario-mcp-server"]
    }
  }
}

将其添加到 .cursor/mcp.json 或 Cursor 的全局 MCP 配置中。

Codex CLI

[mcp_servers.querido-diario]
command = "uvx"
args = ["querido-diario-mcp-server"]

其他支持本地 stdio 服务的 MCP 客户端也可以启动相同的命令。

工具

此服务有意仅提供精简的只读工具。

工具	用途
search_cities	按名称搜索巴西市政地区，并查找 7 位数的 IBGE 区域 ID。支持可选的州筛选条件。
get_city	按精确的 7 位数 IBGE 区域 ID 获取一个市政地区。
search_gazettes	对已索引的公报进行全文搜索，并支持市政地区、发布日期、分页和排序筛选条件。

search_gazettes 使用上游搜索 API 支持的简单查询字符串语法。示例包括 +required、-excluded 和 "exact phrase"。

示例

用户可以这样提问：

Find mentions of ACME Ltda in Porto Alegre gazettes
from January through July 2026.

随后，MCP 客户端可以执行：

1. search_cities(city_name="Porto Alegre")
   -> territory_id: "4314902"

2. search_gazettes(
       query='"ACME Ltda"',
       territory_ids=["4314902"],
       published_since="2026-01-01",
       published_until="2026-07-31",
   )

结果将以结构化工具输出的形式返回，供客户端总结、筛选或与其他工具结合使用。

架构

MCP client
   |
   | stdio / MCP
   v
server.py
   |
   | validated tool arguments
   v
client.py
   |
   | typed read-only HTTPS requests
   v
Querido Diário public API

实现将协议边界与 HTTP 集成分开：

src/querido_diario_mcp_server/
    __init__.py   package version and CLI entry point
    config.py     environment-driven configuration
    errors.py     integration error hierarchy
    models.py     typed Pydantic domain models
    client.py     async HTTP client with no MCP dependency
    server.py     MCP lifespan, validation and tool definitions

服务生命周期内会创建一个 httpx.AsyncClient 连接池，并在各次工具调用间重复使用。HTTP 客户端可以脱离 MCP 独立测试，而集成测试则会在进程内运行真实的 MCP 服务。

设计原则

• 默认只读。 此集成只调用一组固定的上游 GET 端点。
• 本地优先。 不依赖托管中间件、专有后端或账户。
• 类型化边界。 API 响应和 MCP 输出使用显式的 Pydantic 模型。
• 精简的工具集。 服务仅提供发现城市和搜索公报所需的操作。
• 明确报告失败。 上游故障会转换为简洁的 MCP 工具错误，而不会返回原始回溯信息或 HTML 响应。
• 不获取任意 URL。 工具调用方无法将服务用作通用 HTTP 工具或 SSRF 原语。
• 不收集遥测数据。 服务不会收集使用数据。

安全

服务绝不会自动访问上游 API 返回的公报 URL，也不接受工具调用方提供的任意目标 URL。使用前会验证辖区 ID、日期、分页和排序选项。

有关漏洞报告和支持的安全范围，请参阅 SECURITY.md。

配置

变量	默认值	用途
QD_API_BASE_URL	https://api.queridodiario.org.br	Querido Diário API 的基础 URL。可在本地或预发布环境中覆盖。

普通用户无需设置任何环境变量。

开发

仅当你想参与贡献或处理实现时，才克隆此仓库：

git clone https://github.com/lucaspmgomess/querido-diario-mcp-server.git
cd querido-diario-mcp-server
uv sync

运行 CI 中执行的相同检查：

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest --cov

从检出的仓库运行服务：

uv run querido-diario-mcp-server

以交互方式检查 MCP 工具：

uv run mcp dev src/querido_diario_mcp_server/server.py:mcp

测试策略

单元测试使用 httpx.MockTransport 模拟 HTTP 边界，因此自动化测试套件不依赖公共 API。

覆盖范围包括：

• 成功搜索城市和公报；
• 查询序列化和重复的辖区 ID；
• 日期范围、分页和排序；
• 空结果集；
• 上游 4xx 和 5xx 故障；
• 格式错误的响应；
• 连接错误和超时；
• MCP 工具发现、架构和结构化输出；
• MCP 边界上的验证错误和上游故障。

提供了手动冒烟测试脚本，用于验证真实的生产 API 以及完整的 MCP 到 API 调用链：

uv run python scripts/smoke_test_api.py
uv run python scripts/smoke_test_mcp.py

项目状态

项目目前处于测试阶段。MCP 工具集有意保持精简，变更也会谨慎控制。发布历史记录在 CHANGELOG.md 中。

以下内容有意不纳入当前范围：

• 获取任意 URL；
• 自动下载 PDF 或全文；
• OCR；
• 写入操作；
• 爬取和后台任务；
• 内置的大模型摘要功能；
• Web 界面。

与 Querido Diário 的关系

这是一个由社区构建的非官方项目。

Querido Diário 由 Open Knowledge Brasil 及其社区维护。本仓库不是 Open Knowledge Brasil 的官方项目，也未得到该组织的认可或维护，仅使用该项目的公共 API。

相关上游仓库：

• okfn-brasil/querido-diario
• okfn-brasil/querido-diario-api
• okfn-brasil/querido-diario-deployment

有关上游端点历史的补充说明记录在 docs/upstream-api-history.md 中。

贡献

欢迎提交问题和拉取请求。有关开发工作流、项目范围和审查清单，请参阅 CONTRIBUTING.md。

许可证

MIT