Senado Br — Brazilian Federal Senate Open Data

Senado Brasil MCP 服务

🇧🇷 用葡萄牙语阅读

这是一个公开托管的 MCP 服务，可让 AI 助手实时、结构化地访问巴西参议院开放数据——无需安装、无需账户、无需 API 密钥。将 MCP 客户端指向托管端点，即可开始询问参议员、法案、投票、支出等信息。该服务运行于 Cloudflare Workers，使用 Streamable HTTP。

它提供 69 个工具、4 个提示词和 5 个资源，涵盖两个领域：

• 立法——参议员；法案及其审议进程；投票；委员会；全体会议、结果和总统否决；党团投票指引；演讲和速记记录；党团和领导层；联邦立法；以及通过 e-Cidadania 门户开展的公民参与。
• 行政——CEAPS 议会津贴支出；住房津贴；公务员和薪资；加班；实习生；采购合同和招标；外包人员；小额现金基金；以及预算执行情况。

数据来自三个官方来源——立法开放数据 API、行政开放数据 API和 e-Cidadania 门户。所有工具响应均为葡萄牙语（pt-BR）。发行历史请参阅 CHANGELOG.md。

查看实际效果

将客户端指向端点，然后用自然语言提问——英语或葡萄牙语均可：

• “圣保罗的参议员在最近一次全体投票中是如何投票的？” → senado_search_votacoes
• “显示 PEC 45/2019（一项宪法修正案提案）的立法进展。” → senado_buscar_materias + senado_obter_materia
• “2024 年 CEAPS 议会津贴支出了多少？请按支出类型细分。” → senado_ceaps

答案直接来自参议院官方开放数据 API，提供带来源信息的准确数字，而非根据训练数据猜测的数字。

与其他方案的比较

其他巴西 MCP 服务也涉及参议院——mcp-brasil 和 mcp-dados-br 都是多来源聚合器，参议院只是其中一个数据来源。它们的区别在于覆盖范围和运行方式。以下数据根据各项目的源代码统计，统计日期为 2026-10-11：

	参议院工具	覆盖范围	运行位置
senado-br-mcp（本项目）	69	立法、行政（CEAPS、工作人员、合同、预算）和 e-Cidadania，每条回答均附有来源信息	托管服务，无需安装或密钥；也可通过 npx 运行
mcp-brasil 0.14.0	26	立法（参议员、法案、全体会议投票、委员会、日程）——另覆盖数十种其他政府数据源	本地或可自托管（Python）
mcp-dados-br 0.6.0	3	现任参议员、法案列表、投票统计——另覆盖 IBGE、BCB、INMET、众议院	本地（Python）

如果问题涉及参议院、众议院、选举法院（TSE）或透明度门户等多个来源，请选择聚合器。 如果需要查询支出（CEAPS）、工作人员、合同、预算、演讲、委员会投票、否决案或 e-Cidadania，请选择本服务——其他方案不覆盖这些领域。各领域完整对比表、并排示例和重新测量方法（葡萄牙语）：docs/comparativo-alternativas.md。

使用方式（托管服务——无需设置）

这是一个远程、托管、开放访问的服务。要使用它，只需将任意 MCP 客户端指向 Streamable HTTP 端点——无需安装、账户、API 密钥或配置：

https://senado.sidneybissoli.com/mcp

OpenAI / ChatGPT 应用界面

为了提交 OpenAI Apps SDK 并接受审核，Worker 还提供了一个精简的 MCP 界面：

https://senado.sidneybissoli.com/mcp/openai-app-v2

此端点有意保留 /mcp 上完整的公开 MCP 服务，同时将工具发现限制为 27 个高信号、以意图为导向的工具，供 ChatGPT 应用使用。/mcp/openai-app 仍作为旧版别名提供，但新的 ChatGPT 应用配置应使用 /mcp/openai-app-v2，以便客户端获取当前的工具架构。这些工具仍调用相同的处理程序，并返回相同的来源信息封装；只有公开的工具范围更精简。任何 ChatGPT 应用上架页面都应将其介绍为独立的开放数据研究应用，而非官方的 Senate、OpenAI 或 ChatGPT 连接器。

对于 ChatGPT Apps，这 27 个工具还提供了共享的 MCP Apps UI 模板：ui://senado-br-mcp/openai-app-dashboard-v2.html。这个独立组件会将返回的 structuredContent 呈现为简洁的仪表板，显示指标、主要记录和来源信息，无需增加其他模型可见的数据工具。

应用审核所需的公开法律页面：

• 隐私政策：https://senado.sidneybissoli.com/privacy
• 使用条款：https://senado.sidneybissoli.com/terms

ChatGPT（Deep Research）

ChatGPT Deep Research（以及公司知识库，以及通过 Responses API 实现的研究工作流）只使用恰好公开 search 和 fetch 的 MCP 服务；除了 senado_* 工具外，此服务还提供完整的 /mcp 接口（而非精选的应用配置）。将连接器指向托管端点即可，无需密钥：

https://senado.sidneybissoli.com/mcp

search 会根据在任参议员以及参议院和国民议会的现行委员会对查询进行排序，并返回 { id, title, url }（sen:<código> / com:<código>）；fetch 会以可读 Markdown 的形式返回文档——参议员的简介和任期，或委员会的摘要和理事会信息——并附上规范的公开页面（参议员在 www25.senado.leg.br 的个人资料页，或 legis.senado.leg.br 上的委员会页面），ChatGPT 会引用该页面。两者都与其他工具一样，在 structuredContent 和 _meta 中包含相同的来源信息块（文本通道遵循合约的 JSON 格式）。在 ChatGPT 的开发者模式（Settings → Security and login → Developer mode）中，任何工具都可以调用——处理数据时仍应使用 senado_* 工具。

安装（任意客户端）

对于通过命令启动 MCP 服务的客户端，以及一键安装的情况，请使用 mcp-remote 桥接程序。无需构建、无需配置、无需密钥：

npx -y mcp-remote https://senado.sidneybissoli.com/mcp

• **一键安装（LobeHub）：**打开服务页面，然后点击 Install。
• 原生远程 URL（Claude Desktop/Code 和其他 Streamable-HTTP 客户端）：请参阅连接 MCP 客户端。

架构以下的所有内容（先决条件、设置、部署）都仅适用于选择自托管自己的实例——使用此公共服务不需要这些内容。

本地运行（npx · stdio）

不想让查询经由第三方主机（例如出于新闻编辑部政策要求）？同一服务 也可以作为本地 stdio 进程运行，直接与官方政府 API 通信——提供相同的 69 个工具、相同的来源信息封装，且不经过 Cloudflare。这是 npm/stdio 渠道，发布为 senado-br-mcp。

将基于命令的客户端（Claude Desktop/Code 等）指向此软件包即可——npm 会获取并运行它， 无需克隆或构建：

{
  "mcpServers": {
    "senado-br": {
      "command": "npx",
      "args": ["-y", "senado-br-mcp"]
    }
  }
}

若要直接运行或对其进行开发，请改用源代码检出：

git clone https://github.com/SidneyBissoli/senado-br-mcp-cloudflare
cd senado-br-mcp-cloudflare
npm install
npm run build
node dist/cli.js   # serves MCP over stdio (Ctrl+C to stop)

与托管服务保持一致：立法和行政工具完全相同（使用相同的上游 API、限流/缓存/来源信息）——本地的 L1 Cloudflare 缓存不起作用，但 L0 内存缓存仍然有效，因此结果相同。唯一的区别是 e-Cidadania 列表/语料库工具：没有 D1 时，它们会回退到对约 5 个 REST 精选项目进行实时抓取，并通过 meta.fonte / possivelDesatualizacao 标记；详情工具（obter_*）完全相同。日志写入 stderr——stdout 只承载 JSON-RPC 协议流。

Agent Skill（可选）

此仓库附带一项 Claude Agent Skill，位于 .claude/skills/senado-br/，用于指导 Claude 何时调用此服务，以及如何善用其 69 个工具——包括按主题分类的工具地图、常见问题→工具操作指南、来源信息合约，以及注意事项（日期、codigoMateria 桥接、e-Cidadania 的开放集合列表、分页）。 它会指向服务自身的 senado://catalogo / senado://guia 资源，而不会重复其中内容。

在此仓库中工作时，Claude Code 会自动发现此技能。若要在其他地方使用，请将 .claude/skills/senado-br/ 复制到 ~/.claude/skills/，或将该文件夹压缩后上传到 claude.ai （Settings → Features）。此技能假定已连接 senado-br MCP 服务（托管版本或通过 npx 运行）。

架构

• 运行时： Cloudflare Workers（ESM）
• 传输： 通过 agents/mcp 中的 createMcpHandler 实现 Streamable HTTP（MCP 规范 2025-03-26）
• 协议： 基于 JSON-RPC 的 MCP — /mcp 提供完整的公开服务；/mcp/openai-app-v2 提供精选的 27 个工具配置文件，以及一个供 OpenAI 应用审核/提交使用的共享 MCP Apps 小组件（/mcp/openai-app 仍作为旧版别名保留）
• SDK： @modelcontextprotocol/server 2.x（每个请求都会创建 McpServer 实例；未安装 v1 @modelcontextprotocol/sdk — agents 仍将其列为对等依赖，通过 legacy-peer-deps 满足）
• 验证： 使用 Zod schema 验证所有工具输入
• 缓存： 2 层（L0 内存 + L1 Cache API），使用 SHA-256 生成键
• e-Cidadania 存储： 由 Cron Trigger 刷新的 D1 数据库（每 2 小时一次）— 列表工具从 D1 读取，若失败则回退到实时抓取，并带有过期标记；详情工具保持实时读取，并采用写穿缓存（参见 e-Cidadania）
• 速率限制： 令牌桶 — 全局（8 req/s）+ 每客户端（2 req/s）
• 上游限流： 最多 6 个并发请求，每次调用的预算为 10s；遇到 429/5xx/网络错误时，使用指数退避和 Retry-After 重试（portfolio 共享抓取模块 @sbissoli/mcp-upstream）；每个响应的来源信息都会包含测得的 retrieval 诊断信息（调用次数、尝试次数、异常）
• 身份验证： 可选的 Bearer token（设置 API_KEY 密钥；未设置时开放访问）。采用恒定时间比较。
• 可观测性： 结构化 JSON 日志 + /metrics 中的内存计数器；在 Cloudflare Analytics Engine 中记录每种工具调用的遥测数据（选择情况、错误率、缓存与实时数据对比），不含 PII
• 存活状态： 运行在 Cloudflare 自有的全球网络上，并使用自定义域名 — 不依赖可能宕机的第三方主机。公开的 /health 和 /status（版本 + 上次部署 ID/时间戳）可用于验证运行时间和当前构建；上方的 status 徽章会请求实时端点
• 测试： 使用 Vitest 对解析器、辅助函数、缓存、限流和身份验证进行单元测试

自行托管（可选）

使用该服务不需要自行托管 — 服务已托管在 https://senado.sidneybissoli.com/mcp （开放访问）。仅当你想运行自己的私有实例时，才需要遵循本节。

先决条件

• Node.js 22+（engines.node）
• Wrangler CLI v4+
• Cloudflare 账户

设置

1. 安装依赖项

npm install

2. 创建 KV 命名空间

# Create the KV namespace
wrangler kv namespace create CACHE_KV

# Note the ID from the output, e.g.:
# { binding = "CACHE_KV", id = "abc123..." }

3. 配置 wrangler.toml

替换占位符 KV 命名空间 ID：

[[kv_namespaces]]
binding = "CACHE_KV"
id = "YOUR_KV_NAMESPACE_ID_HERE"

也可以设置 ALLOWED_ORIGIN 来限制 CORS：

[vars]
ALLOWED_ORIGIN = "https://your-app.example.com"

e-Cidadania 流程需要一个 D1 数据库和一个 Cron Trigger（二者已在 wrangler.toml 中声明 — 替换数据库 ID）：

[[d1_databases]]
binding = "ECIDADANIA_DB"
database_name = "senado-ecidadania"
database_id = "YOUR_D1_DATABASE_ID_HERE"

[triggers]
crons = ["0 */2 * * *"]

创建数据库（将返回的 ID 粘贴到上方）并应用 schema：

npx wrangler d1 create senado-ecidadania
npx wrangler d1 migrations apply senado-ecidadania --remote

D1 为空时，列表工具会回退到实时抓取，因此首次运行 Cron 前服务也能正常工作。

4.（可选）启用身份验证

wrangler secret put API_KEY
# Clients must then send: Authorization: Bearer <key>
# When API_KEY is not set, the server is open access.

5. 本地开发

npm run dev
# Dev server runs locally on port 8787 (local only).
# The public MCP endpoint is https://senado.sidneybissoli.com/mcp

6. 测试和类型检查

npm test             # run all tests once
npm run test:watch   # watch mode
npm run typecheck    # tsc --noEmit

7. 部署

npm run deploy
# Serves at https://senado.sidneybissoli.com (custom domain) and
# https://senado-br-mcp.sidneybissoli.workers.dev (workers.dev fallback)

端点

路径	方法	说明
/	GET	落地页（pt-BR）— 识别发出请求的 User-Agent 背后的客户端：服务内容、负载状态、联系方式（始终公开）
/mcp	POST, GET, DELETE, OPTIONS	MCP Streamable HTTP 端点（由 createMcpHandler 管理）
/health	GET	健康检查 — 返回 ok（始终公开）
/status	GET	JSON：status、version 和最近部署的元数据（deploy.id/tag/timestamp）— 存活状态和当前构建，无需 MCP 握手（始终公开）
/metrics	GET	JSON 计数器：请求数、工具调用数、缓存命中/未命中数、上游调用/重试/错误数、身份验证失败数（始终公开）
/.well-known/mcp/server-card.json	GET	供目录扫描器（Smithery）使用的 MCP 服务卡片：serverInfo、authentication、工具/资源/提示词 — 由 @sbissoli/mcp-surface/card 根据实时 full 配置生成（始终公开）

可从注册表检查的服务面指纹

每个版本都会在其 MCP Registry 条目中发布 /mcp 提供的服务面的 sha256（full 配置中的 initialize、工具、资源、提示词），以及哪些方法可在无凭据的情况下调用。服务面发生变化却未提升 版本号时，构建会失败；注册表中的指纹可让客户端在自身一侧检查同一信息。规范形式和流程： @sbissoli/mcp-surface 的 SPEC.md。 你也可以自行检查（Node 18+，无依赖）：

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjs
node verify.mjs io.github.SidneyBissoli/senado-br-mcp-cloudflare

MCP 请求示例

所有请求都以 JSON-RPC 2.0 格式发送到 POST /mcp。

列出可用工具

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

调用工具 — 列出 SP 的参议员

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "senado_listar_senadores",
    "arguments": {
      "uf": "SP",
      "emExercicio": true
    }
  }
}

调用工具 — 按关键词搜索法案

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "senado_buscar_materias",
    "arguments": {
      "palavraChave": "inteligência artificial",
      "tramitando": true
    }
  }
}

调用工具 — 获取近期全体会议投票

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "senado_search_votacoes",
    "arguments": {
      "dias": 7
    }
  }
}

调用工具 — 最受欢迎的公民提案

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "senado_ecidadania_listar_ideias",
    "arguments": {
      "ordenarPor": "apoios",
      "ordem": "desc",
      "status": "aberta"
    }
  }
}

上游 API 端点

该服务使用 Senado API 中两类上游端点：

旧版端点（.json 后缀，PascalCase 响应）

由组 A、E、F、H、I、J、K、L、M、N 使用。.json 后缀由 upstream.ts 自动添加。上游未将其中任何端点标记为弃用。

上游路径	使用方
/senador/lista/atual	senado_listar_senadores
/senador/lista/legislatura/{legislatura}	senado_listar_senadores（参数 legislatura）
/senador/{codigo}（+ /mandatos）	senado_obter_senador（通过额外调用获取传记 + 任期）
/senador/{codigo}/licencas、/comissoes、/cargos、/historicoAcademico、/filiacoes、/profissao	senado_senador_historico（tipo 枚举）
/senador/afastados	senado_senadores_afastados
/senador/{codigo}/apartes	senado_discursos_senador（tipo=apartes）
/comissao/lista/colegiados	senado_listar_comissoes（+ 将简称解析为代码）
/comissao/{codigo}	senado_obter_comissao（secao=resumo；数字代码，不是简称）
/composicao/comissao/{codigo}（+ ?ativas=S）	senado_obter_comissao（secao=membros）
/comissao/agenda/{data}	senado_agenda_comissoes
/comissao/agenda/{dataInicio}/{dataFim}	senado_reunioes_comissao
/comissao/reuniao/{codigoReuniao}	senado_reuniao_comissao
/comissao/cpi/{sigla}/requerimentos	senado_requerimentos_cpi（即使 CPI 正在活动，上游也经常返回空结果——空结果会附带 aviso）
/materia/distribuicao/autoria、/distribuicao/relatoria/{sigla}	senado_distribuicao_materias
/plenario/agenda/dia/{data}、/agenda/mes/{data}、/agenda/cn/...	senado_agenda_plenario
/plenario/resultado/{data}、/resultado/cn/{data}、/resultado/mes/{data}	senado_resultado_plenario
/plenario/resultado/veto/{codigo}（+ /materia/、/dispositivo/）	senado_resultado_veto
/plenario/votacao/orientacaoBancada/{data}（+ 时间段）	senado_orientacao_bancada
/plenario/encontro/{codigo}（+ /pauta、/resultado、/resumo）	senado_encontro_plenario
/plenario/tiposSessao、/lista/tiposComparecimento、/lista/legislaturas	senado_tabelas_plenario
/materia/vetos/{ano}、/vetos/aposrcn、/vetos/antesrcn、/vetos/encerrados	senado_vetos
/taquigrafia/notas/{sessao|reuniao}/{id}	senado_notas_taquigraficas
/taquigrafia/videos/{sessao|reuniao}/{id}	senado_videos_taquigrafia
/senador/{codigo}/discursos	senado_discursos_senador
/plenario/lista/discursos/{dataInicio}/{dataFim}	senado_discursos_plenario
/discurso/texto-integral/{codigo}	senado_discurso_texto（纯文本，直接获取）
/senador/lista/tiposUsoPalavra	senado_tabelas_referencia（tabela=tipos-uso-palavra）
/composicao/lista/blocos	senado_listar_blocos
/composicao/bloco/{codigo}	senado_obter_bloco
/composicao/lideranca	senado_liderancas
/composicao/mesaSF	senado_mesa（casa=senado）
/composicao/mesaCN	senado_mesa（casa=congresso）
/orcamento/lista	senado_orcamento_parlamentar（tipo=emendas）
/orcamento/oficios	senado_orcamento_parlamentar（tipo=oficios）
/legislacao/lista	senado_buscar_legislacao
/legislacao/{codigo}	senado_obter_legislacao
/legislacao/tiposNorma	senado_tabelas_referencia（tabela=tipos-norma）
/votacaoComissao/comissao/{sigla}	senado_votacao_comissao（por=comissao）
/votacaoComissao/parlamentar/{codigo}	senado_votacao_comissao（por=senador）
/votacaoComissao/materia/{sigla}/{numero}/{ano}	senado_votacao_comissao（por=materia）
/autor/lista/atual	senado_autores_atuais

v3 端点（扁平 JSON 数组/对象，camelCase）

供 B、C、D 组使用。日期必须采用 ISO 格式（YYYY-MM-DD）——工具接受 YYYYMMDD 并进行转换。codigoMateria 查询参数用于将旧版 matéria 代码映射到 v3 流程。

上游路径	使用方
/votacao	senado_obter_votacao、senado_search_votacoes、senado_votos_materia、senado_votacoes_senador
/processo	senado_search_processos、senado_buscar_materias
/processo/{id}	senado_obter_processo、senado_obter_materia（secao=detalhe/tramitacao）
/processo/documento	senado_obter_materia（secao=textos）
/processo/emenda	senado_processo_detalhe（secao=emendas）
/processo/relatoria	senado_processo_detalhe（secao=relatorias）、senado_obter_materia（报告人）
/processo/prazo	senado_processo_detalhe（secao=prazos）
/processo/{siglas,assuntos,classes,destinos,entes,tipos-*}	senado_tabelas_processo（12 张参考表）

行政 API（adm.senado.gov.br/adm-dadosabertos，扁平 snake_case JSON）

供 O、P、Q、R 组通过 admFetch 使用（无 .json 后缀；HTTP 404 视为空集合）。基础 URL 可通过 SENADO_ADM_BASE_URL 配置。

上游路径	使用方
/api/v1/senadores/despesas_ceaps/{ano}	senado_ceaps（约 10 MB/年，在 Worker 中缓存并聚合）
/api/v1/senadores/{auxilio-moradia,escritorios,aposentados}	senado_senadores_admin（tipo 枚举）
/api/v1/servidores/servidores/{ativos,efetivos,comissionados,inativos}	senado_servidores
/api/v1/servidores/remuneracoes/{ano}/{mes}	senado_remuneracoes_servidores（约 5.5 MB/月）
/api/v1/servidores/horas-extras/{ano}/{mes}	senado_horas_extras
/api/v1/servidores/quantitativos/*、/previsao-aposentadoria、/api/v1/senadores/quantitativos/senadores	senado_pessoal_tabelas（数量统计）
/api/v1/servidores/{estagiarios,pensionistas,lotacoes,cargos}	senado_pessoal_tabelas（姓名列表）
/api/v1/contratacoes/contratos（加上 /{id}/aditivos）	senado_contratos、senado_contratacao_detalhe
/api/v1/contratacoes/{tipo}/{id}/{itens,pagamentos,garantias}	senado_contratacao_detalhe
/api/v1/contratacoes/licitacoes	senado_licitacoes
/api/v1/contratacoes/terceirizados	senado_terceirizados
/api/v1/contratacoes/empresas	senado_empresas_contratadas（约 13 MB，需要筛选条件）
/api/v1/contratacoes/{atas_registro_preco,notas_empenho,menores_aprendizes}	senado_contratacoes_lista
/api/v1/supridos/{ano}（加上 atosConcessao、empenhos、movimentacoes、transacoes）	senado_suprimento_fundos
senado.gov.br/bi-arqs/Arquimedes/Financeiro/{Despesa,Receitas}SenadoDadosAbertos.json	senado_execucao_orcamentaria（每日 JSON 数据源，规范化巴西小数格式字符串）

e-Cidadania（由 D1 支持，按 Cron 刷新）

e-Cidadania 列表数据保存在 D1 数据库（ecidadania_current/_history/_scrape_runs，按 entidade 区分；另有用于 audiência 评论级数据的 ecidadania_comentarios，以及用于可恢复详情回填的 ecidadania_detalhe_cursor——在架构 v2 中添加），读取时从数据库获取，而不是每次调用都重新抓取。三种频率会向其中写入数据：

• 每日运行、在 Worker 外执行的 GitHub Action负责三个线上实体（consultas、eventos、ideias；见下文）的完整语料——即事实来源。每日运行（而不是每周），因为首次出现时间序列 MIN(scraped_at) 是唯一可衡量的提交节奏信号，每漏掉一天都会永久缩短该序列（ROADMAP Etapa 2，decisão D3）；
• 针对 consultas_votos 档案的每周摄取 Action（.github/workflows/verify-consultas-votos.yml——历史文件名）：Senado 会定期重新发布 Arquimedes CSV（已于 2026-07-20 确认），因此每周运行都会在与其他语料相同的异常保护机制下重新摄取当前版本（见下文）；
• Worker 内的 Cron Trigger（0 */2 * * *，src/scraper/pipeline.ts → refreshEcidadania）只对每个线上实体约 5 条 REST 重点数据（restcolecaomaismateria/ideia/audiencia——votos/comentários/apoios）执行定向指标拼接，并记录为 ok-metrica，因此不会再次破坏语料基线，也不会触及长尾数据。在 v2 中，eventos 拼接会保留语料中的规范评论计数（每日抓取是 comentarios 的事实来源，因此拼接不会再与质量下降的 REST 计数来回冲突）。

两个写入方都通过规范的 buildXResumo 构建器和共享的 contentHash 生成数据载荷，因此写入的行逐字节一致。每次写入都会：

• 对 ecidadania_current 执行 upsert（每个条目一行——工具读取的数据）；
• 仅当条目的 content_hash 发生变化时，才向 ecidadania_history 追加数据（可用于时间序列）；
• 在 ecidadania_scrape_runs 中记录每次运行。

异常保护机制（src/scraper/anomaly.ts，classifyRun）可确保失败或异常的语料运行（零行，或少于上次成功运行行数的 ECIDADANIA_CORPUS_MIN_PCT%）绝不会覆盖上次的有效状态。

列表／分析工具（listar_*、consultas_analise、sugerir_tema_enquete、consultas_votos）通过 resolveList（src/scraper/store.ts）从 D1 读取：优先使用 D1。由于现在每个实体都是完整语料，语料过期时仍会从 D1 提供数据并标记为 possivelDesatualizacao: true，而不会退回到约 5 条线上重点数据（原有的覆盖范围缺陷）；只有在 D1 为空时（冷启动，首次每周运行之前）才会进行实时抓取。过期时间依据 ECIDADANIA_CORPUS_STALE_MAX_MIN（约 10 天）判断。每个列表响应都包含附加的 meta（fonte、lastScrapedAt、possivelDesatualizacao），让调用方始终能看到数据的实际时效，避免在不知情的情况下获得过期数据。

详情工具（obter_*）仍会实时抓取（通过针对 CSS 类的正则表达式抓取 HTML）以保证数据新鲜度，并通过即发即弃方式将更丰富的数据载荷写入 ecidadania_detalhe（按 content_hash 去重），从而累积详情历史，且不会增加响应延迟。

完整语料摄取（在 Worker 外执行）

三个线上 e-Cidadania 语料由每日运行的 Action（.github/workflows/ingest-ecidadania.yml）负责；每个语料都有自己的 scripts/ingest-ecidadania/index-*.ts 编排器，生成批量 out-*.sql 文件，供应用步骤批量加载：

• consultas — 进行中的征询（详见下文）。在 v2 中，每项抓取到的议题还会从其详情页（visualizacaomateria）补充autoria/relator；这些字段不可变，因此只抓取尚未补充的行。
• eventos — 来自 principalaudiencia?p=N HTML 列表的听证会/事件；状态直接取自列表区块（不经过 /processo 中转）。在 v2 中，每个事件都会从其详情页补充（规范的 data/hora + comissaoNomeCompleto/local/descricao/pauta/convidados/videoUrl），并从其 AJAX 评论片段补充（规范的评论数 + 每条评论对应一条 ecidadania_comentarios 记录，与存储的哈希进行比对，并写入 out-eventos-comentarios-*.sql）。
• ideias — 来自 pesquisaideia?situacao=N&p=M 的立法提案（约 113.7k 条），按 situacao 分组抓取（列表中没有内嵌状态），并分批输出，每批约 10k 条语句。在 v2 中，列表抓取会保留不可变的详情字段，并通过单独且可恢复的回填任务（index-ideias-detalhe.ts，通过 ingest:ecidadania:ideias-detalhe 运行）每次运行补充一块数据——由于约 113.7k 次详情抓取无法在一次 Action 中完成，因此会将游标保存在 ecidadania_detalhe_cursor 中，并在处理到末尾时从头继续。

第四个实体 consultas_votos 是独立的历史投票档案，数据来自约 33 MB 的 Arquimedes CSV（Proposições-com-votos.csv），按每项议题聚合为一条记录，并包含 votosPorUf 明细。CSV 中的“dados atualizados até”时间戳会作为溯源字段 data_vintage；该字段不纳入行哈希（consultaVotoCore），因此投票数据未变化时，重新摄取不会导致 _history 产生变化。STATUS ATUAL 的值统一为“Descontinuado”，因此这是归档，而非对进行中征询的迁移。该数据由 senado_ecidadania_consultas_votos 提供服务，溯源信息指向 CSV（ECIDADANIA_ARQUIMEDES）。它不纳入每日任务，由独立的每周摄取 Action 负责（.github/workflows/verify-consultas-votos.yml——文件名保留了历史上的 verify- 前缀）：该档案最初被视为冻结的单一版本（ROADMAP Etapa 2，决策 D1），每周运行仅用于验证；但在 2026-07-20，Senado 重新发布了 CSV，形成新的版本（新增 43 项议题，648 项已更新），因此定时任务现在会根据标准异常防护重新摄取当前版本（CSV 为空/被截断以及灾难性下限检查仍会失败且不会写入；通过 force 触发任务可覆盖下限检查）。脚本的验证模式（INGEST_CONSULTAS_VOTOS_VERIFY=1 / --verify）仍可按需用于完整性检查。

consultas 任务是参考实现：

consultas 覆盖所有进行中的征询——当前处于 tramitação 的每一项议题（约 7.7k 项），而不仅是约 5 项重点议题。首次运行时已确认：pesquisamateria 列表仅包含正在 tramitação 的议题，因此该数据源不会收录已结束/历史征询（摄取前的历史数据回填不在范围内）。三项已确定的设计决策：

1. 解耦的数据摄取。 开放集合由一个Worker 外部的 TypeScript 任务（scripts/ingest-ecidadania/，由每日 GitHub Action 运行 — .github/workflows/ingest-ecidadania.yml）获取：该任务会对 HTML 列表（pesquisamateria?p=1..N，这是获取开放咨询完整数据的唯一来源）进行分页，取得 ID 和投票数，并批量加载到 D1；Worker 只负责读取。易出问题且耗时较长的抓取不在请求/Cron 路径中执行。
2. 状态取自 /processo，而不是 HTML。 咨询从提出开始，持续至审议流程结束，因此 status 取决于议案：aberta ⟺ codigoMateria 属于 /processo 中 tramitando=S 的集合，该集合由可靠的 JSON 得出（绝不通过抓取网页获取）。每项咨询都会以 aberta 状态录入（列表只会返回正在审议的议案）；每次完整运行时，任务都会根据议案是否属于 /processo 集合，重新推导所有已存储行的状态（而不是根据列表中是否缺失来判断，因为列表缺失可能只是暂时的），因此议案结束审议流程后，对应咨询会变为 encerrada。encerrada/todas 集合会随时间增长；首次摄取前已结束的咨询不会被收录（不在范围内）。列表/分析工具默认使用 status: aberta。
3. 两种协调一致的运行频率（共用一套写入约定）。 该任务复用 src/scraper/ 中的 contentHash、ConsultaResumo 构建器和 classifyRun，因此写入的数据行与 Cron 的完全一致。每日任务负责处理长尾数据；每 2 小时运行的 Cron 则通过定向指标合并，保持约 5 条热门/开放重点数据最新（记录为 ok-metrica，绕过语料库的 classifyRun 基线）。语料库的新鲜度（possivelDesatualizacao）根据最近一次 status='ok' 的运行计算，并采用较大的时间窗口（ECIDADANIA_CORPUS_STALE_MAX_MIN）；语料库数据过期时，会从 D1 提供带有过期标记的咨询数据，而不会退回到实时重点数据。

写入防护：如果抓取不完整（任意页面抓取失败）或 /processo 状态全集不完整，则只写入一条 erro 运行记录；即使抓取完整，如果数据量低于灾难性下限（ECIDADANIA_CORPUS_MIN_PCT，默认为上一次成功语料库的 80%），也会拒绝写入，以防页面数据不完整；如属合理的大幅缩减，可通过 --force / INGEST_FORCE=1 覆盖。可通过 Action 每日运行，也可手动运行：

CLOUDFLARE_API_TOKEN=… npm run ingest:ecidadania                 # writes scripts/ingest-ecidadania/out.sql
npx wrangler d1 execute senado-ecidadania --remote --file=scripts/ingest-ecidadania/out.sql

缓存

分层架构

层级	存储	范围	TTL 范围	用途
L0	内存中的 Map	每个隔离实例	30-300s	速度极快，消除同一 Worker 隔离实例内的重复请求
L1	Cloudflare Cache API（caches.default）	每个 colo（PoP）	60-600s	在同一边缘位置的请求之间共享
L2	KV（可选）	全局	可变	为罕见、低写入频率的数据预留

缓存类别

类别	L0 TTL	L1 TTL	用途
STATIC	300s	600s	立法类型、静态参考数据
SEMI_STATIC	120s	300s	政党列表、UF 列表、委员会详情
DYNAMIC	30s	60s	议程、近期投票、会议列表
ON_DEMAND	30s	120s	特定议案/参议员/投票查询

POST 缓存方案

MCP 对所有 tools/call 请求都使用 POST。Cache API 原生不支持缓存 POST 响应，因为它要求使用 GET 请求。解决方案如下：

1. 哈希参数 — 使用 SHA-256 对工具名称和排序后的参数进行哈希
2. 合成 GET 键 — 构建合成 URL https://senado-br-mcp.internal/__cache/{tool}/{hash}
3. Cache API 匹配/写入 — 将合成 GET URL 用于 caches.default.match() 和 caches.default.put()，从而对源自 POST 的数据执行标准 Cache API 操作

此缓存发生在工具层级（每个工具的回调内部），而不是 MCP 传输层级。

来源

每个工具都会附加一个来源信息封套，以便将结果追溯到其官方来源——来源信息是答案的一等组成部分，而非可选附加内容（目标受众是记者和政治学研究人员，对他们而言，没有来源的数字毫无用处）。该封套实现了整个产品组合通用的来源信息契约（@sbissoli/mcp-provenance）：服务会为每个响应构建并验证完整的规范模型，然后输出其 concise 投影——一个顺序固定的区块，未知字段明确标记为 null；合并多个上游读取结果的响应还会列出各个部分及其各自的提取时间（field_sources），此时区块的 retrieved_at 取其中最早的时间。该区块位于 structuredContent.provenance 中（客户端可解析；请注意，公布的各工具输出架构较为宽松，因此契约会在服务端构建时由软件包进行验证），并在文本内容中以精简的来源脚注形式呈现，供只渲染文本的客户端使用——数据 JSON 本身不会与封套重复，以降低每个响应的令牌成本。

覆盖范围包括全部四个上游来源，每个来源都有自己的 source/citation/license（位于 src/utils/provenance.ts）：

• Senado Federal — Dados Abertos（Legislativo） — legis.senado.leg.br/dadosabertos
• Senado Federal — Dados Abertos（Administrativo） — adm.senado.gov.br/adm-dadosabertos
• Senado Federal — Execução Orçamentária e Financeira — 位于 senado.gov.br 的 Arquimedes/Financeiro 源
• Senado Federal — Portal e-Cidadania — www12.senado.leg.br/ecidadania

concise 区块的字段（自 3.18.5 起采用契约 v1.3；每个响应对应一个工具和一个来源；键的顺序固定；前七项始终存在，若来源未提供相应值，则为 null；可选项不适用时不会出现，而非留空）：

字段	含义
source	官方来源名称（例如 Senado Federal — Dados Abertos (Legislativo)）
source_url	查询的规范端点／项目 URL（例如 …/processo/{id}）
data_vintage	数据的版本／所属期间（例如 2024-03-15、2019）——在 v3.5.0 之前名为 reference_period
retrieved_at	上游提取时间的 ISO-8601 表示——该值会在缓存中保留，因此反映的是数据实际获取的时间，而非构建时间或命中缓存的时间；对于合并响应，取各部分中最早的时间
retrieval	对请求来源过程的测量诊断信息（尝试次数、结果）；如果本次调用未获取任何数据（纯缓存、本地数据），则为 null——自 3.11.0（v1.1）起提供
citation	可直接使用的引用字符串（人类可读）
license	来源条款（Dados Abertos do Senado Federal）
field_sources	可选。 字段级子来源，每个来源都有自己的提取时间——仅出现在合并读取的响应中（v1.2，自 3.17.0 起提供；见下文）
derived / derivation_note	可选。 当服务端计算值而非直接复制时，设为 true，并附上固定的 pt-BR 说明，注明计算内容（自 3.19.0 起适用于整类情况）：estatisticas 模式（分布、汇总、排名）；分组求和、计数和平均值——CEAPS valorTotal 及其按参议员／类型／月份／供应商划分的模式、预算执行汇总（包括 por-ano 和默认模式）、工资 resumo、加班 valorTotal、relatoria 分布、按党派／UF 统计的在任参议员数量、e-Cidadania 历史全国总量；工资总额（bruto，七个组成部分之和）；分配到某个组织子树的公务员（subordinadasA）；当来源未发布计数时，根据唱名投票计算的投票结果（全体会议公开唱名投票、无总数的委员会投票）；e-Cidadania 百分比、共识／极化排名和估算的创意创建日期；本届立法机构的任期。若所有数字均为来源原始数据，则不出现此字段（原始列表、预算的 detalhe、已发布的投票结果）。引用的各项数值仍来自参议院
revision	该数值是否仍可能被来源修改：对于所有参议院来源，status 均为 current（提取时生效的版本；不声称任何版本为 final）；对于行政和预算来源，note 会说明参议院之后可能更正已发布的数据

参议院来源均不随数据发布通知，因此不会出现 notices（它也是 v1.3 的一部分）。文本页脚仅在例外情况下增加一行——此处为 estatisticas 模式中的计算值说明。

该区块背后的规范模型还包含 dataset.id（项目／系列标识符，例如 codigoMateria=137808）和 api_version；每次构建时都会验证这些字段，并用于生成 attribution（如下），但它们不属于 concise 投影。

除 provenance 信封外，structuredContent 还包含一个顶层 attribution 列表，其中列出响应背后的不同来源 URL。其命名与 modelcontextprotocol#711 中的提议一致（该提议将 attribution 定义为响应级别的来源引用列表），因此如果该 RFC 获得通过，服务端也能保持向前兼容；更丰富的 provenance 对象仍是此服务端自己的扩展。 _meta 中的旁路镜像。 同一份 provenance 和 attribution 也会通过命名空间键（com.sidneybissoli.senado/provenance 和 com.sidneybissoli.senado/attribution）镜像到结果的 _meta 中。MCP 规范将 _meta 保留给关于结果本身、且不应影响模型的元数据；#711 中仍在孵化的信任/归属工作（已拆分到实验性扩展轨道，尚未纳入核心规范）正是针对这一点。将数据镜像到此处，审计和 UI 使用方无需读取面向模型的数据通道即可获取来源信息，且不消耗模型 Token；与此同时，structuredContent 仍会保留这些信息，以便模型引用来源。该镜像不会被 ChatGPT 应用配置文件的精简器移除（它只会剥离 structuredContent.meta）。

字段级粒度。 大多数工具只读取单一来源，因此一个信封就够了。少数会在一个响应中合并多次读取的工具会填充 field_sources——一个由 { fields, source_url, dataset_id, data_vintage, retrieved_at, served_from_cache } 组成的列表，用于将特定输出字段归属到其真实来源；而该数据块的 retrieved_at 取其中最早的时间。对于通过服务缓存读取的内容，served_from_cache 为 true/false；对于不适用此概念的内容（捆绑的组织架构快照、D1 中的 e-Cidadania 语料库），则为 null。会合并数据的工具（自 3.18.2 起）：senado_obter_materia 的 secao=detalhe（/processo/{id} + 来自 /processo 的 ementa + 来自 /processo/relatoria 的 relator）、senado_obter_senador 和 Deep Research 获取参议员信息的 fetch（传记 + 来自 /senador/{codigo}/mandatos 的 mandatos/emExercicio）、跨越年份的时间窗口内调用 senado_reunioes_comissao（每年读取一次）、带有 subordinadasA 的 senado_servidores（工资数据 + 组织架构快照）、senado_suprimento_fundos 中针对 atos-concessao 的统计数据（行为记录 + 来自 supridos 登记表的受益人姓名）、senado_ecidadania_obter_evento（实时详情 + 来自语料库的 comentarios）以及 senado_ecidadania_sugerir_tema_enquete（consultas 和 ideias 语料库）。只有最终成为答案字段的读取才算子来源：仅用于解析或核验标识符的读取（委员会缩写 → 其代码、senado_contratacao_detalhe 中的上级机构核验）不会纳入，否则缓存的查找表会导致整个答案被标记为与其一样陈旧。attribution 始终会列出所有不同的底层 source_url。

缓存层（cachedFetchWithMeta）会保留获取时间戳并与值一同存储，从而确保 retrieved_at 的准确性；即使命中缓存，它仍会反映真实的上游提取时间。只有两个例外会报告准确的实时戳：e-Cidadania 列表工具（从 D1 读取）使用语料库的 lastScrapedAt——即存储数据的真实时间；如果语料库为空或已过期，列表回退到门户网站时，则使用实时抓取时间（自 3.18.3 起；此前，过期语料库的时间会错误地泄露到实时答案中）——而 e-Cidadania 详情工具会实时抓取，并使用获取时间和第 3 级规范条目 URL。唯一会回退到构建时默认值的路径，是代码中的静态参考目录（senado_tabelas_referencia tipos-materia），它没有上游提取时间。

覆盖范围是全面的：所有 69 个工具都带有此信封——67 个 senado_* 工具通过 resultWithProvenance( 实现（可用 grep -c 'resultWithProvenance(' src/tools/*.ts 验证），两个 Deep Research 工具则通过 provenanceExtras 实现（位于同一数据块中的 structuredContent/_meta，因为它们的文本通道采用契约规定的 JSON 格式）。下方清单中的 ⊕ 标记表示最初的试点工具（投票、法案、流程）；如今此信封已扩展到所有工具，这些标记仅供历史参考。

可引用数据集（e-Cidadania 参与数据）

除实时服务外，本项目还发布 e-Cidadania 参与层的冻结、带版本且可引用的数据集（公共咨询、立法提案、互动活动及其评论、按州划分的历史投票）——这是 R 包 congressbr 从未涵盖的部分。每个值都带有按字段记录的来源信息（{ value, sourceEndpoint, sourceField, retrievedAt, license, schemaVersion }）；数据许可（Dados Abertos do Senado Federal）与代码许可（MIT）分开。

• 如何引用——CITATION.cff（数据集；请引用所用快照的版本 DOI，跨版本引用该数据集时请引用概念 DOI）。
• 每个版本包含的内容——CHANGELOG-dataset.md（累积、仅追加；将每个版本与其 schemaVersion 绑定）。
• 变量词典与字段来源信息——docs/dataset-dictionary.md（由 src/dataset/schema.ts 生成，它是唯一可信来源）。
• 数据许可——LICENSE-DATA.md。
• 发布流程（冻结 → 校验和 → GitHub Release → Zenodo DOI）——docs/release-runbook.md；相关机制位于 src/dataset/、scripts/build-dataset/ 和 .github/workflows/release-dataset.yml。

清单 — schema v2（schemaVersion 2.0.0）

每个版本都会为每种实体提供一个 NDJSON 资源（每行一个 HarmonizedRecord：身份信息 + 每个字段的溯源封装），以及一个 datapackage.json 清单和一份字典副本。共五个资源：

资源（*.ndjson）	粒度	关键变量	来源
consultas	1 项公众咨询（议题）	materia、ementa、votosSim/votosNao/totalVotos、percentual*、autoriaⁿ、relatorⁿ、status、url、firstSeenAt	pesquisamateria 列表 + 详情页（visualizacaomateria）ⁿ + /processo?tramitando=S（用于状态）
ideias	1 项立法提案（约 11.37 万项）	titulo、apoios、status、dataPublicacaoⁿ（支持截止日期——门户发布的唯一日期；创建日期约为截止日期前 120 天，见字典）、autorUfⁿ、descricaoⁿ、plConvertidoⁿ、url、firstSeenAt	pesquisaideia 列表 + 通过可续传回填获取的详情页（visualizacaoideia）ⁿ
eventos	1 场互动活动（听证会）	titulo、dataᶜ、horaᶜ、comissao、comissaoNomeCompletoⁿ、localⁿ、descricaoⁿ、pautaⁿ、convidadosⁿ、videoUrlⁿ、comentariosᶜ、status、url、firstSeenAt	principalaudiencia 列表 + 详情页（visualizacaoaudiencia）ⁿ + AJAX 评论片段ᶜ
eventos_comentariosⁿ	1 条评论（评论级别）	eventoId、comentarioId、uf、texto、data、hora、momentoVideoUrl、convidadoAssociado	AJAX 片段 ajaxcolecaocomentarioaudiencia?audienciaId=
consultas_votos	1 项议题（历史档案）	materia、ementa、autoria、votosSim/votosNao/totalVotos、votosPorUf、status、url、referencePeriod	Arquimedes CSV Proposições-com-votos.csv（每周重新摄取）

ⁿ = v2 中新增/重新开放 · ᶜ = v2 中更正为规范来源。 v2（2.0.0）的变化——摄取方式从仅列表改为列表 + 详情页（活动还包括 AJAX 评论）：

• 修正并丰富活动数据。 data/hora 现在取自详情页（规范来源——estudo A3 发现列表中的 hora 有 57% 不一致），并新增六个详情字段（comissaoNomeCompleto、local、descricao、pauta、convidados、videoUrl）。comentarios 现在采用规范 AJAX 计数（列表计数在 82% 的活动中为虚假的 0，仅捕获约 6.7% 的参与情况）。
• 新增评论级资源 eventos_comentarios——每条听证会评论一行，记录了其他任何人都未以版本化形式发布的参与信号。
• 重新开放仅详情页字段：ideias（dataPublicacao、autorUf、descricao、plConvertido）和 consultas（autoria、relator）——这些字段之前按设计始终为 null。
• 依据数据来源采取隐私措施。 公民内容（听证会评论、提案作者）仅保留 UF，不保留姓名，并在解析时丢弃姓名；公职人员（咨询提案人/报告人、活动嘉宾）保留姓名（因其职务而公开）。字段逐项的依据（已批准目标）见 docs/schema-v2-inventario.md。

冻结的 NDJSON 不会提交到代码库（按需从主权 D1 语料库构建）；带标签的 dataset-v* 版本会附带压缩包、SHA256SUMS 和 release.json，并将其存档到 Zenodo。

工具清单

H 组 — 参考数据/元数据（1 个工具）

工具	描述
senado_tabelas_referencia	通过 tabela 枚举获取参考表：types-materia、partidos、ufs、legislatura-atual、tipos-norma、tipos-uso-palavra

A 组 — 参议员（5 个工具）

工具	描述
senado_listar_senadores	列出在任参议员或按届次查询，并可使用 nome（不区分重音符号的部分匹配）、uf 和 partido 筛选
senado_obter_senador	参议员的履历详情：简介、任期、党派、联系方式
senado_votacoes_senador ⊕	参议员对每项议案的投票情况（通过 v3 /votacao）
senado_senador_historico	通过 tipo 枚举查询任职经历：licencas、comissoes、cargos、historico-academico、filiacoes、profissoes
senado_senadores_afastados	当前离任（不在任）的参议员

B 组 — 法案／事项（2 个工具，后端为 v3）

工具	描述
senado_buscar_materias ⊕	按类型、编号、年份、关键词、作者或审议进度搜索事项（通过 v3 /processo）
senado_obter_materia ⊕	通过 secao 枚举获取事项数据：detalhe（状态／报告人）、tramitacao（审议历史）或 textos（文件）

C 组 — 流程（5 个工具）

工具	描述
senado_search_processos ⊕	搜索立法流程（补充事项搜索）
senado_obter_processo ⊕	特定立法流程的完整详情
senado_processo_detalhe	通过 secao 枚举查询流程的相关信息：emendas、relatorias 或 prazos
senado_autores_atuais	正在审议流程的议员作者，按产出排序
senado_tabelas_processo	12 个参考表（缩写、议题、类别、类型-*），通过 tabela 枚举查询

D 组 — 投票（3 个工具）

工具	描述
senado_obter_votacao ⊕	投票详情及唱名表决记录。接受 codigoVotacao（全会会议的 codigoSessao）。
senado_votos_materia ⊕	某项事项的投票情况（通过 v3 /votacao?codigoMateria），可选包含唱名表决记录
senado_search_votacoes ⊕	灵活搜索／列出全会投票，可按 dias、时间段、流程、事项或参议员筛选

E 组 — 委员会（7 个工具）

工具	描述
senado_listar_comissoes	列出活跃委员会（合议机构），可按类型筛选
senado_obter_comissao	通过 secao 枚举获取委员会数据：resumo（主席团／总数）或 membros（成员组成）。内部会将缩写解析为代码。
senado_reunioes_comissao	某委员会在指定时间段内的会议（支持跨年度区间）
senado_agenda_comissoes	指定日期所有委员会的会议日程
senado_reuniao_comissao	会议完整详情：各部分、议题、受邀者、结果、议程／会议记录链接
senado_requerimentos_cpi	活跃 CPI 提交的申请，支持分页（上游数据通常为空，即使 CPI 处于活跃状态；返回空结果时会提供 aviso）
senado_distribuicao_materias	委员会中按参议员统计的工作量：作者身份或报告人身份

F 组 — 全会（7 个工具）

工具	描述
senado_agenda_plenario	全会议程 — 按日、月或国会查询（范围为 dia／mes／cn）
senado_resultado_plenario	会议结果：审议事项、意见、结果（SF／CN／月）
senado_orientacao_bancada	各党派领导层针对每次投票的投票指示及票数统计
senado_vetos	按年份或审议状态查询总统否决案
senado_resultado_veto	否决案唱名投票结果（按否决案、被否决法案或条款查询）
senado_encontro_plenario	立法会议详情、议程事项、结果或摘要
senado_tabelas_plenario	会议类型、出席类型、届次列表

Group G — e-Cidadania（9 个工具）

工具	描述
senado_ecidadania_listar_consultas	公众咨询（全部开放的咨询——正在审议的事项），支持是/否投票；可用 status 筛选（默认值为 aberta）
senado_ecidadania_obter_consulta	咨询详情：投票、作者、报告员、评论
senado_ecidadania_consultas_analise	通过 modo（共识／两极化）分析全部开放的咨询；status 默认值为 aberta
senado_ecidadania_listar_ideias	公民立法提案；通过 ordenarPor: apoios 按支持度排名
senado_ecidadania_obter_ideia	提案详情：文本、支持数、提出日期、时间线（元数据、建议、CDH 决定、结案）以及转化成的议案
senado_ecidadania_listar_eventos	互动活动（听证会、质询会、直播）；通过 ordenarPor 按评论数排名
senado_ecidadania_obter_evento	活动详情：议程、嘉宾、视频链接
senado_ecidadania_sugerir_tema_enquete	根据可配置的条件为月度投票调查推荐主题
senado_ecidadania_consultas_votos	咨询投票的历史记录，按州拆分（Arquimedes CSV）；按 total/sim/nao 排名，可用 uf/materia 筛选

Group I — 演讲（3 个工具）

工具	描述
senado_discursos_senador	通过 tipo 枚举获取参议员的发言：演讲（本人发言）或插话（干预发言）
senado_discursos_plenario	指定日期范围内的全部全体会议演讲
senado_discurso_texto	指定发言／演讲的全文

Group J — 党团与领导层（4 个工具）

工具	描述
senado_listar_blocos	参议院议会党团及其成员党派
senado_obter_bloco	特定议会党团的详情
senado_liderancas	参议院／众议院／国会的领导人（党团领袖、副领袖）及其所领导的党团／党派，可筛选
senado_mesa	通过 casa 枚举获取主席团成员：参议院（SF 主席团）或国会（CN 主席团）

Group K — 预算（1 个工具）

工具	描述
senado_orcamento_parlamentar	通过 tipo 枚举获取预算议员修正案：修正案（按作者分组）或公函（资金去向指示；可按修正案的 ano 筛选，支持分页，incluirEmendas 为可选参数）

Group L — 联邦法律（2 个工具）

工具	描述
senado_buscar_legislacao	按类型、编号、年份或日期搜索联邦法律规范（至少需要提供一项）
senado_obter_legislacao	特定联邦法律规范的详情

Group M — 委员会投票（1 个工具）

工具	描述
senado_votacao_comissao	通过 por 枚举查询委员会投票：委员会、参议员或议案；可选时间范围

Group N — 速记记录（2 个工具）

工具	描述
senado_notas_taquigraficas	全体会议或委员会会议的官方记录——摘要模式（含摘录）、全文模式（按块分页），并支持按发言者筛选
senado_videos_taquigrafia	按会议获取视频／音频资料，并提供发言者信息和媒体链接

Group O — 参议员／行政事务（2 个工具）

工具	描述
senado_ceaps	按年份查询 CEAPS 议会额度支出——可按参议员、支出类型、月份或供应商汇总，也可查看明细；estatisticas=true 返回全集分布统计（最小值／最大值／平均值／中位数／百分位数）和前列／末位排名；也可通过 agruparPor（参议员／类型／月份／供应商）按总支出进行分组排名，并使用 topN；可按参议员／月份／类型／供应商筛选
senado_senadores_admin	通过 tipo 枚举获取参议员行政数据：住房补贴、支持办公室或退休人员

Group P — 公务员／人事管理（4 个工具）

工具	描述
senado_servidores	按状态（在职／正式任用／委任／离职）查询公务员，可按姓名、单位、职位筛选
senado_remuneracoes_servidores	月度薪资——按薪资类型汇总，或查看个人构成及计算后的税前总额；estatisticas=true 返回整份薪资数据的统计（最小值／最大值／平均值／中位数／百分位数）和前列／末位排名，并支持 campo、consolidarPorServidor、agruparPor 和 topN
senado_horas_extras	按月份查询加班费及总额；estatisticas=true 返回全集分布统计（最小值／最大值／平均值／中位数／百分位数）和前列／末位排名；也可通过 agruparPor（姓名／月份）按总金额进行公务员排名，并使用 topN
senado_pessoal_tabelas	通过 tabela 枚举获取人事表：数量统计（人员、职位与职能、退休预测、参议员）和名单（实习生、遗属养老金领取者、任职单位、职位）

Group Q — 合同采购（6 个工具）

工具	描述
senado_contratos	在 Worker 中针对完整数据集筛选合同（不区分重音符号）：供应商、CNPJ、年份、编号、标的、劳务
senado_contratacao_detalhe	查询合同／框架协议／支出承诺的项目、付款、担保、修订或启用信息
senado_licitacoes	按编号或标的文本查询招标
senado_terceirizados	按姓名、公司或单位查询外包人员
senado_empresas_contratadas	查询与参议院签约的公司（需要按名称／CNPJ 筛选）
senado_contratacoes_lista	价格登记框架协议、支出承诺单、青年学徒

Group R — 资金备用金（1 个工具）

工具	描述
senado_suprimento_fundos	按年份查询小额现金预支：收款人、拨款行为、支出承诺、资金变动、银行卡交易；estatisticas=true（tipo 为 transacoes／empenhos／atos-concessao）返回全集分布统计（最小值／最大值／平均值／中位数／百分位数）和前列／末位排名；也可通过 agruparPor（例如供应商）按总金额排名，并设置上下文 campo 和 topN

Group S — 参议院预算（1 个工具）

工具	描述
senado_execucao_orcamentaria	查询自 2013 年以来的预算执行情况（拨款、承诺、核销／结算、支付）以及自 2012 年以来的自有收入（预算与实收）——可按年份、行动、支出组、来源或收入来源汇总；estatisticas=true 返回全集分布统计（最小值／最大值／平均值／中位数／百分位数）和前列／末位排名；也可通过 agruparPor 按 campo 总额进行分组排名，并设置 campo（默认已支付／实收）和 topN

组 T — 组织架构（1 个工具）

读取参议院组织架构树的打包快照（由 npm run ingest:estrutura 从机构门户爬取至 serviço 级别），因为开放数据 API 只公布至 Secretaria 级别的单位，且从不将末级单位关联到其上级。门户仅列出名称、没有独立页面的单位（CONLEG/CONORF núcleos），会根据页面中的缩进列表作为合成节点纳入快照。公务员名册记录了 lotações 的国会机构（CMO、CPCMS、CMMC）来自经过整理的补充数据（src/estrutura/complemento-cn.ts，公开来源：congressonacional.leg.br），置于单独的 国民议会 根节点（CN）下，绝不会放在参议院树中，因此 subordinadasA: "DGER" 不会包含它们，而 subordinadasA: "CN" 会将它们计入。senado_servidores 会将登记在情境伪单位“Servidores Afastados/em Trânsito - SF”下的公务员单独报告为 afastadosOuEmTransito。

工具	描述
senado_estrutura_organizacional	解析 unidade（如 DGER 这样的缩写或名称）对应的组织架构图（organograma）：返回其 caminho（上级单位）和所有下属单位（subordinadas[]——secretarias、coordenações、serviços、núcleos，并附带 nivel）。可搭配 senado_servidores 的 subordinadasA 筛选器使用，以统计／列出某个完整司局下的所有公务员（公务员隶属于末级 serviço，因此按上级缩写筛选 lotacao 会返回 0 条）。

组 U — 深度研究（2 个工具）

OpenAI Deep Research 合约：仅有的两个不带 senado_ 前缀的工具，因为名称由合约固定。它们通过与其他工具相同的 shim 注册（只读注解、共享输出封装——开放数据以及必需的 provenance + attribution、按工具遥测），且仅通过 /mcp 提供——经过整理的 ChatGPT 应用配置文件不包含它们。索引（在任参议员 + 活跃委员会，约 300 份文档）会在首次使用时通过 senado_listar_* 工具读取的相同两个列表端点构建，并保留 24 h。

工具	描述
search	根据查询（自然语言或关键词，支持 pt/en，不区分重音符号）为在任参议员和活跃委员会排序；最多返回 10 个 { id, title, url }——sen:<código> 附公开个人资料 URL，com:<código> 附公开委员会页面。两个列表的来源信息位于 structuredContent/_meta。
fetch	将 search 返回的 id 对应文档作为 { id, title, text, url, metadata } 返回：参议员的简介和任期（与 senado_obter_senador 相同的读取结果），或委员会的摘要和领导班子（与 senado_obter_comissao 相同的读取结果），以 Markdown 格式提供，并附该次读取的来源信息。未知 id → 错误。

总计：69 个工具

提示词（4 个）

可复用的 pt-BR 工作流模板（MCP prompts 能力），定义于 src/prompts.ts：

提示词	参数	用途说明
senado_gastos_senador	senador、ano	解析参议员，并汇总／详细列出 CEAPS 支出。
senado_tramitacao_materia	sigla、numero、ano	获取议题的当前状态 + 流转历史。
senado_votos_senador	senador、periodo?	列出该参议员在指定期间的唱名表决结果。
senado_panorama_ecidadania	—	汇总查询结果（共识／极化）、创意和热门活动。

资源（5）

静态上下文文档/表格（MCP resources 能力），定义于 src/resources.ts：

URI	类型	内容
senado://guia	markdown	概览，以及根据目标选择工具的指南。
senado://catalogo	markdown	按领域分组的 69 个工具。
senado://glossario	markdown	参议院缩略语和术语（PEC、CEAPS、CCJ、RCN…）。
senado://tabelas/tipos-materia	json	提案类型（缩略语/名称/描述）。
senado://tabelas/ufs	json	27 个联邦单位。

项目结构

src/
├── index.ts              # Worker entrypoint (fetch handler + scheduled/Cron handler)
├── server.ts             # McpServer factory (creates per-request instance)
├── auth.ts               # Optional Bearer token auth (constant-time compare)
├── metrics.ts            # In-memory counters served at /metrics
├── types.ts              # Env, cache categories, safeguard constants
├── cache/
│   ├── l0-memory.ts      # In-memory Map cache with TTL + LRU eviction
│   ├── l1-cache-api.ts   # Cloudflare Cache API wrapper (synthetic GET keys)
│   └── manager.ts        # Cache orchestrator (L0 → L1 → upstream)
├── throttle/
│   ├── token-bucket.ts   # Token bucket rate limiter (global + per-client)
│   └── upstream.ts       # Upstream fetch with concurrency limit, retry, timeout
├── scraper/
│   ├── ecidadania.ts     # Isolated e-Cidadania scraper (REST lists + regex HTML detail; buildConsultaResumo)
│   ├── pipeline.ts       # 2h Cron: targeted highlight metric splice (consultas/eventos/ideias); corpora owned by the off-Worker jobs
│   ├── anomaly.ts        # Run classification (anomalous run never overwrites current)
│   └── store.ts          # D1 reads (resolveList + per-entity staleness, lastGoodRunAt) + detail write-through
├── instrument.ts         # Per-tool call telemetry (in-memory + Analytics Engine)
├── utils/
│   ├── logger.ts         # Structured JSON logging
│   └── validation.ts     # toolResult, toolError, errorFrom, buildParams, ensureArray helpers
└── tools/
    ├── referencia.ts        # Group H — 1 reference/metadata tool
    ├── senadores.ts         # Group A — 5 senator tools
    ├── materias.ts          # Group B — 2 bill/matter tools (v3 backend)
    ├── processos.ts         # Group C — 5 process tools
    ├── votacoes.ts          # Group D — 3 vote tools
    ├── comissoes.ts         # Group E — 7 committee tools
    ├── plenario.ts          # Group F — 7 plenary tools
    ├── ecidadania.ts        # Group G — 8 e-Cidadania tools (read from D1; see scraper/)
    ├── discursos.ts         # Group I — 3 speech tools
    ├── composicao.ts        # Group J — 4 bloc/leadership tools
    ├── orcamento.ts         # Group K — 1 budget tool
    ├── legislacao.ts        # Group L — 2 federal law tools
    ├── votacao-comissao.ts  # Group M — 1 committee voting tool
    ├── taquigrafia.ts       # Group N — 2 stenographic record tools
    ├── senadores-admin.ts   # Group O — 2 admin senator tools (CEAPS, housing)
    ├── servidores.ts        # Group P — 4 personnel tools
    ├── contratacoes.ts      # Group Q — 6 procurement tools
    ├── supridos.ts          # Group R — 1 petty-cash tool
    ├── orcamento-senado.ts  # Group S — 1 budget execution tool
    └── estrutura.ts         # Group T — 1 org-structure tool (reads src/data/ snapshot via src/estrutura/)
scripts/
└── ingest-ecidadania/    # Off-Worker full-corpus consultas ingestion (run via `npm run ingest:ecidadania`)
    ├── index.ts          # Orchestrator: crawl → status (/processo) → normalize → guards → out.sql
    ├── listing.ts        # Pure listing parser (parseConsultaListingPage, findLastPage)
    ├── status.ts         # tramitando=S set from /processo → aberta/encerrada (deriveStatus)
    ├── restatus.ts       # Linger fix: re-status stored rows by /processo membership (close zombies)
    ├── http.ts           # Polite fetch (retry/backoff) for the unattended crawl
    ├── d1.ts             # D1 pre-reads (existing meta, payloads, last good rows) via wrangler
    ├── verify.ts         # consultas_votos on-demand integrity-check verdict (verifyAcervoIntegrity)
    └── sql.ts            # out.sql generation (mirrors SQL.upsert/SQL.history; reuses SyncRecord)
.github/workflows/        # ingest-ecidadania.yml (daily D1 corpus load), verify-consultas-votos.yml
                          # (weekly frozen-acervo integrity check), publish-mcp.yml (registry),
                          # usage-report.yml (monthly Analytics report), deprecate-registry.yml
                          # (all pinned to current Node 24 action majors — see each YAML for exact versions)
migrations/               # D1 schema (0001 tables, 0002 indexes, 0003 comment level + detail cursor) for the e-Cidadania pipeline
tests/                    # Vitest unit tests mirroring src/ (parsers, cache, throttle, auth, scraper,
                          # pipeline/anomaly/store, listing/sql/highlights, plus e-Cidadania contract tests)

环境变量

变量	必需	默认值	描述
SENADO_BASE_URL	否	https://legis.senado.leg.br/dadosabertos	立法 API 基础 URL
SENADO_ADM_BASE_URL	否	https://adm.senado.gov.br/adm-dadosabertos	行政 API 基础 URL
ALLOWED_ORIGIN	否	*	CORS 允许的源
API_KEY	否（机密）	—	设置后，除 /health、/metrics 和 CORS 预检请求外，所有请求都必须携带 Authorization: Bearer <key>
CACHE_KV	是（绑定）	—	L2 缓存的 KV 命名空间
ECIDADANIA_DB	是（绑定）	—	e-Cidadania 流水线的 D1 数据库（列表持久化 + 历史记录）
ECIDADANIA_CORPUS_STALE_MAX_MIN	否	14400	Worker 外部完整语料库（所有 e-Cidadania 实体）的过期时间窗口（分钟，约 10 天）；提供时会标记为过期，绝不会折叠为摘要内容
ECIDADANIA_CORPUS_MIN_PCT	否	80	Worker 外语料库任务的灾难性下限：低于上次有效语料库此百分比的完整爬取/解析结果将被拒绝
CLOUDFLARE_API_TOKEN	否（机密）	—	用于语料库导入/完整性检查任务的 GitHub Actions 机密（D1 编辑权限范围）；Worker 不使用此令牌
CLOUDFLARE_ACCOUNT_ID	否（Actions 变量）	—	GitHub Actions 仓库变量，使 wrangler 跳过 /memberships 账户自动发现（D1 权限范围的令牌无法读取该信息）；导入任务中必须与 CLOUDFLARE_API_TOKEN 一同设置
SENADO_ANALYTICS	否（绑定）	—	用于逐工具调用遥测的 Analytics Engine 数据集

连接 MCP 客户端

这是一个远程服务（Streamable HTTP，无需安装，开放访问）——将任意 MCP 客户端指向 https://senado.sidneybissoli.com/mcp。除了 69 个工具，它还提供提示词（现成的 pt-BR 工作流：senado_gastos_senador、senado_tramitacao_materia、senado_votos_senador、 senado_panorama_ecidadania）和资源（senado://guia、senado://catalogo、 senado://glossario、senado://tabelas/tipos-materia、senado://tabelas/ufs）。

一键安装（LobeHub）

从 LobeHub 市场安装——打开 服务页面，然后点击安装 （会自动填入远程端点，无需配置）。

Claude Desktop / Claude Code

将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "senado-br": {
      "url": "https://senado.sidneybissoli.com/mcp"
    }
  }
}

对于基于命令的客户端（或任何不原生支持远程连接的客户端），请使用 mcp-remote 桥接工具：

{
  "mcpServers": {
    "senado-br": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://senado.sidneybissoli.com/mcp"]
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector https://senado.sidneybissoli.com/mcp

许可证

MIT

致谢

图标：“Amanhecer no Congresso Nacional”——巴西国民议会的照片，依据知识共享许可使用。（如果您是作者，请提交 issue，以便我们补充完整署名/许可链接。）