senado-br-mcp 3.5.1 → 3.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 ![Cloudflare Workers](https://img.shields.io/badge/Cloudflare%20Workers-F38020?logo=cloudflare&logoColor=white)
 ![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-1f6feb)
-![Tools](https://img.shields.io/badge/tools-67-2ea44f)
+![Tools](https://img.shields.io/badge/tools-69-2ea44f)
 [![CI](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare/actions/workflows/ci.yml/badge.svg)](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare/actions/workflows/ci.yml)
 [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
 [![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-senado-br-mcp-cloudflare)](https://lobehub.com/mcp/sidneybissoli-senado-br-mcp-cloudflare)
@@ -17,7 +17,7 @@
 
 A **public, hosted** MCP server that gives AI assistants live, structured access to **Brazilian Senate open data** — **no installation, no account, no API key**. Point your MCP client at the hosted endpoint and start asking about senators, bills, votes, expenses, and more. It runs on Cloudflare Workers over Streamable HTTP.
 
-It exposes **67 tools**, **4 prompts**, and **5 resources** across two domains:
+It exposes **69 tools**, **4 prompts**, and **5 resources** across two domains:
 
 - **Legislative** — senators; bills and their tramitation; votes; committees; plenary sessions, results and presidential vetoes; party-bloc voting orientation; speeches and stenographic transcripts; blocs and leadership; federal legislation; and citizen participation via the e-Cidadania portal.
 - **Administrative** — CEAPS parliamentary-quota expenses; housing allowance; civil servants and payroll; overtime; interns; procurement contracts and biddings; outsourced staff; petty-cash funds; and budget execution.
@@ -68,6 +68,16 @@ Public legal URLs for app review:
 - Privacy policy: `https://senado.sidneybissoli.com/privacy`
 - Terms of use: `https://senado.sidneybissoli.com/terms`
 
+### ChatGPT (Deep Research)
+
+ChatGPT deep research (and company knowledge, and research workflows over the Responses API) only uses an MCP server that exposes exactly `search` and `fetch` — this server does, on top of the `senado_*` tools, on the full `/mcp` surface (not on the curated app profile). Point the connector at the hosted endpoint, no key required:
+
+```
+https://senado.sidneybissoli.com/mcp
+```
+
+`search` ranks the query against the senators in office and the active committees of the Senate and the National Congress and returns `{ id, title, url }` (`sen:<código>` / `com:<código>`); `fetch` returns the document as readable Markdown — the senator's biography and mandates, or the committee's summary and board — with the canonical public page (the senator's profile on www25.senado.leg.br or the committee page on legis.senado.leg.br), which is what ChatGPT cites. Both carry the same provenance block as every other tool, in `structuredContent` and `_meta` (the text channel is the contract's JSON). In ChatGPT's developer mode (Settings → Security and login → Developer mode) any tool is callable — the `senado_*` tools remain the ones to use for data.
+
 ### Install (any client)
 
 For clients that launch MCP servers as a command — and for one-command setup — use the
@@ -87,7 +97,7 @@ own instance** — it is **not** required to use this public server.
 
 Prefer not to route queries through a third-party host (e.g. a newsroom policy)? The **same server**
 also runs as a **local stdio process** that talks **directly to the official government APIs** — same
-67 tools, same provenance envelope, no Cloudflare in the loop. This is the npm/stdio channel, published
+69 tools, same provenance envelope, no Cloudflare in the loop. This is the npm/stdio channel, published
 as [`senado-br-mcp`](https://www.npmjs.com/package/senado-br-mcp).
 
 Point a command-based client (Claude Desktop/Code, etc.) at the package — npm fetches and runs it,
@@ -125,7 +135,7 @@ list/corpus tools: without D1 they fall back to a live scrape of the ~5 REST hig
 
 This repo bundles a Claude [Agent Skill](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/overview)
 at [`.claude/skills/senado-br/`](.claude/skills/senado-br/SKILL.md) that teaches Claude **when** to reach for
-this server and **how** to use its 67 tools well — a themed tool map, common question→tool playbooks, the
+this server and **how** to use its 69 tools well — a themed tool map, common question→tool playbooks, the
 provenance contract, and gotchas (dates, the `codigoMateria` bridge, e-Cidadania's open-set listing, pagination).
 It points back to the server's own `senado://catalogo` / `senado://guia` resources rather than duplicating them.
 
@@ -156,7 +166,7 @@ Claude Code auto-discovers it when you work in this repo. To use it elsewhere, c
 
 ### Prerequisites
 
-- Node.js 20+
+- Node.js 22+ (`engines.node`)
 - [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) v4+
 - Cloudflare account
 
@@ -535,7 +545,7 @@ In addition to the `provenance` envelope, `structuredContent` carries a top-leve
 
 `retrieved_at` fidelity is provided by the cache layer (`cachedFetchWithMeta`), which persists the fetch timestamp alongside the value, so it reflects the real upstream extraction even on a cache hit. Two exceptions report an honest live timestamp instead: the e-Cidadania **list** tools (read from D1) use the corpus's `lastScrapedAt` — the true age of the stored data — while e-Cidadania **detail** tools, scraped live, use the fetch time and a level-3 canonical item URL. The only path that falls back to the build-time default is the in-code static reference catalog (`senado_tabelas_referencia` `tipos-materia`), which has no upstream extraction instant.
 
-Coverage is **universal**: all 67 tools carry the envelope (verify with `grep -c 'resultWithProvenance(' src/tools/*.ts`). The **⊕** marks in the inventory below denote the original pilot tools (votes, bills, processes); the envelope now extends to every tool, so the marks are historical.
+Coverage is **universal**: all 69 tools carry the envelope — the 67 `senado_*` tools via `resultWithProvenance(` (verify with `grep -c 'resultWithProvenance(' src/tools/*.ts`) and the two Deep Research tools via `provenanceExtras` (same block, in `structuredContent`/`_meta`, since their text channel is the contract's JSON). The **⊕** marks in the inventory below denote the original pilot tools (votes, bills, processes); the envelope now extends to every tool, so the marks are historical.
 
 ## Citable dataset (e-Cidadania participation)
 
@@ -739,7 +749,16 @@ Reads a bundled snapshot of the Senate's organizational tree (crawled from the i
 |------|-------------|
 | `senado_estrutura_organizacional` | Organizational chart (organograma) resolved for a `unidade` (sigla like `DGER` or name): returns its `caminho` (ancestors) and every subordinate unit (`subordinadas[]` — secretarias, coordenações, serviços, núcleos — with `nivel`). Pairs with `senado_servidores`'s `subordinadasA` filter, which counts/lists all servants under a whole directorate (a servant sits in a leaf serviço, so filtering `lotacao` by the parent sigla returns 0). |
 
-**Total: 67 tools**
+### Group U — Deep Research (2 tools)
+
+The [OpenAI Deep Research contract](#chatgpt-deep-research): the only two tools without the `senado_` prefix, because the names are fixed by the contract. Registered through the same shim as the others (read-only annotations, permissive `outputSchema`, per-tool telemetry) and served on `/mcp` only — the curated ChatGPT app profile does not include them. The index (senators in office + active committees, ~300 documents) is built on first use from the same two list endpoints the `senado_listar_*` tools read, and kept for 24 h.
+
+| Tool | Description |
+|------|-------------|
+| `search` | Ranks the query (natural language or keywords, pt/en, accent-insensitive) against senators in office and active committees; returns up to 10 `{ id, title, url }` — `sen:<código>` with the public profile URL, `com:<código>` with the public committee page. Provenance of both lists in `structuredContent`/`_meta`. |
+| `fetch` | Returns the document for an id from `search` as `{ id, title, text, url, metadata }`: the senator's biography and mandates (same read as `senado_obter_senador`) or the committee's summary and board (same read as `senado_obter_comissao`), as Markdown, with that read's provenance. Unknown id → error. |
+
+**Total: 69 tools**
 
 ### Prompts (4)
 
@@ -759,7 +778,7 @@ Static context documents/tables (MCP `resources` capability), defined in `src/re
 | URI | Type | Content |
 | --- | --- | --- |
 | `senado://guia` | markdown | Visão geral e qual ferramenta usar por objetivo. |
-| `senado://catalogo` | markdown | As 67 ferramentas agrupadas por domínio. |
+| `senado://catalogo` | markdown | As 69 ferramentas agrupadas por domínio. |
 | `senado://glossario` | markdown | Siglas e termos do Senado (PEC, CEAPS, CCJ, RCN…). |
 | `senado://tabelas/tipos-materia` | json | Tipos de proposição (sigla/nome/descrição). |
 | `senado://tabelas/ufs` | json | As 27 unidades federativas. |
@@ -848,7 +867,7 @@ tests/                    # Vitest unit tests mirroring src/ (parsers, cache, th
 ## Connecting MCP Clients
 
 This is a **remote** server (Streamable HTTP, no install, open access) — point any MCP client at
-`https://senado.sidneybissoli.com/mcp`. Besides 67 tools, it exposes **prompts** (ready-made pt-BR
+`https://senado.sidneybissoli.com/mcp`. Besides 69 tools, it exposes **prompts** (ready-made pt-BR
 workflows: `senado_gastos_senador`, `senado_tramitacao_materia`, `senado_votos_senador`,
 `senado_panorama_ecidadania`) and **resources** (`senado://guia`, `senado://catalogo`,
 `senado://glossario`, `senado://tabelas/tipos-materia`, `senado://tabelas/ufs`).

package/README.pt-BR.md

@@ -2,7 +2,7 @@
 
 ![Cloudflare Workers](https://img.shields.io/badge/Cloudflare%20Workers-F38020?logo=cloudflare&logoColor=white)
 ![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-1f6feb)
-![Tools](https://img.shields.io/badge/tools-67-2ea44f)
+![Tools](https://img.shields.io/badge/tools-69-2ea44f)
 [![CI](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare/actions/workflows/ci.yml/badge.svg)](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare/actions/workflows/ci.yml)
 [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
 [![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-senado-br-mcp-cloudflare)](https://lobehub.com/mcp/sidneybissoli-senado-br-mcp-cloudflare)
@@ -16,7 +16,7 @@
 
 Um servidor MCP **público e hospedado** que dá aos assistentes de IA acesso ao vivo e estruturado aos **dados abertos do Senado Federal do Brasil** — **sem instalação, sem conta, sem chave de API**. Aponte o seu cliente MCP para o endpoint hospedado e comece a perguntar sobre senadores, matérias, votações, despesas e muito mais. Roda em Cloudflare Workers via Streamable HTTP.
 
-Expõe **67 ferramentas**, **4 prompts** e **5 recursos** em dois domínios:
+Expõe **69 ferramentas**, **4 prompts** e **5 recursos** em dois domínios:
 
 - **Legislativo** — senadores; matérias e sua tramitação; votações; comissões; sessões plenárias, resultados e vetos presidenciais; orientação de bancada nas votações; discursos e notas taquigráficas; blocos e lideranças; legislação federal; e participação cidadã pelo portal e-Cidadania.
 - **Administrativo** — despesas da cota parlamentar (CEAPS); auxílio-moradia; servidores e remunerações; horas extras; estagiários; contratos e licitações; terceirizados; suprimento de fundos; e execução orçamentária.
@@ -50,7 +50,7 @@ Para submissao e revisao pelo OpenAI Apps SDK, o Worker tambem expoe uma superfi
 https://senado.sidneybissoli.com/mcp/openai-app-v2
 ```
 
-Esse endpoint preserva o servidor MCP publico completo em `/mcp`, mas limita a descoberta a 25
+Esse endpoint preserva o servidor MCP publico completo em `/mcp`, mas limita a descoberta a 27
 ferramentas de alto sinal, organizadas por intencao de usuario, para uso como app do ChatGPT.
 `/mcp/openai-app` continua disponivel como alias legado, mas novas configuracoes do app no ChatGPT
 devem usar `/mcp/openai-app-v2` para forcar a leitura do schema atual das ferramentas. As ferramentas
@@ -58,7 +58,7 @@ continuam chamando os mesmos handlers e retornando o mesmo envelope de provenien
 anunciada fica mais estreita. Qualquer listagem de ChatGPT App deve apresentar isto como um app
 independente de pesquisa em dados abertos, nao como conector oficial do Senado, da OpenAI ou do ChatGPT.
 
-Para ChatGPT Apps, essas 25 ferramentas tambem anunciam um template UI compartilhado do MCP Apps em
+Para ChatGPT Apps, essas 27 ferramentas tambem anunciam um template UI compartilhado do MCP Apps em
 `ui://senado-br-mcp/openai-app-dashboard-v2.html`. O widget e autocontido e renderiza o
 `structuredContent` retornado como painel compacto com metricas, registros principais e fonte/proveniencia,
 sem adicionar outra ferramenta de dados visivel ao modelo.
@@ -68,6 +68,16 @@ URLs publicas legais para revisao do app:
 - Politica de privacidade: `https://senado.sidneybissoli.com/privacy`
 - Termos de uso: `https://senado.sidneybissoli.com/terms`
 
+### ChatGPT (Deep Research)
+
+O deep research do ChatGPT (e o company knowledge, e os workflows de pesquisa da API Responses) só usa um servidor MCP que exponha exatamente `search` e `fetch` — este servidor expõe, além das ferramentas `senado_*`, na superfície completa `/mcp` (não no perfil curado do app). Aponte o conector para o endpoint hospedado, sem chave:
+
+```
+https://senado.sidneybissoli.com/mcp
+```
+
+`search` ranqueia a consulta contra os senadores em exercício e as comissões ativas do Senado e do Congresso Nacional e devolve `{ id, title, url }` (`sen:<código>` / `com:<código>`); `fetch` devolve o documento em Markdown legível — a biografia e os mandatos do senador, ou o resumo e a mesa da comissão — com a página pública canônica (o perfil do senador em www25.senado.leg.br ou a página da comissão em legis.senado.leg.br), que é o que o ChatGPT cita. As duas carregam o mesmo bloco de proveniência das outras ferramentas, em `structuredContent` e `_meta` (o canal de texto é o JSON do contrato). No modo desenvolvedor do ChatGPT (Settings → Security and login → Developer mode) qualquer ferramenta é chamável — as `senado_*` continuam sendo as ferramentas para dados.
+
 ### Instalação (qualquer cliente)
 
 Para clientes que iniciam servidores MCP como um comando — e para uma configuração de um único comando — use a
@@ -87,7 +97,7 @@ própria instância** — **não** é necessário para usar este servidor públi
 
 Prefere não rotear suas consultas por um servidor de terceiros (ex.: política de uma redação)? O **mesmo
 servidor** também roda como um **processo local stdio** que bate **direto nas APIs oficiais do governo** —
-as mesmas 67 ferramentas, o mesmo envelope de proveniência, sem Cloudflare no caminho. É o canal npm/stdio,
+as mesmas 69 ferramentas, o mesmo envelope de proveniência, sem Cloudflare no caminho. É o canal npm/stdio,
 publicado como [`senado-br-mcp`](https://www.npmjs.com/package/senado-br-mcp).
 
 Aponte um cliente baseado em comando (Claude Desktop/Code, etc.) para o pacote — o npm baixa e executa,
@@ -125,7 +135,7 @@ Os logs vão para o **stderr** — o stdout carrega apenas o fluxo do protocolo
 
 Este repositório inclui uma [Agent Skill](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/overview)
 do Claude em [`.claude/skills/senado-br/`](.claude/skills/senado-br/SKILL.md) que ensina o Claude **quando**
-recorrer a este servidor e **como** usar bem as 67 ferramentas — um mapa de ferramentas por tema, playbooks de
+recorrer a este servidor e **como** usar bem as 69 ferramentas — um mapa de ferramentas por tema, playbooks de
 pergunta→ferramenta, o contrato de proveniência e os gotchas (datas, a ponte `codigoMateria`, a listagem
 só-abertas do e-Cidadania, paginação). Ela aponta para os recursos `senado://catalogo` / `senado://guia` do
 próprio servidor em vez de duplicá-los.
@@ -138,7 +148,7 @@ O Claude Code a descobre automaticamente ao trabalhar neste repositório. Para u
 
 - **Runtime:** Cloudflare Workers (ESM)
 - **Transporte:** Streamable HTTP (spec MCP 2025-03-26) via `createMcpHandler` de `agents/mcp`
-- **Protocolo:** MCP sobre JSON-RPC — `/mcp` serve o catalogo publico completo; `/mcp/openai-app-v2` expoe um perfil curado de 25 ferramentas mais um widget MCP Apps compartilhado para revisao/submissao como app OpenAI (`/mcp/openai-app` permanece como alias legado)
+- **Protocolo:** MCP sobre JSON-RPC — `/mcp` serve o catalogo publico completo; `/mcp/openai-app-v2` expoe um perfil curado de 27 ferramentas mais um widget MCP Apps compartilhado para revisao/submissao como app OpenAI (`/mcp/openai-app` permanece como alias legado)
 - **SDK:** `@modelcontextprotocol/sdk` 1.26.0+ (instâncias de McpServer por requisição)
 - **Validação:** schemas Zod para todas as entradas das ferramentas
 - **Cache:** 2 camadas (L0 memória + L1 Cache API) com chaveamento SHA-256
@@ -156,7 +166,7 @@ O Claude Code a descobre automaticamente ao trabalhar neste repositório. Para u
 
 ### Pré-requisitos
 
-- Node.js 20+
+- Node.js 22+ (`engines.node`)
 - [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) v4+
 - Conta Cloudflare
 
@@ -507,6 +517,37 @@ Campos do bloco `concise` (por resposta — uma ferramenta, uma fonte): `source`
 
 A cobertura abrange as quatro fontes upstream: **Dados Abertos Legislativo** (`legis.senado.leg.br`), **Dados Abertos Administrativo** (`adm.senado.gov.br`), **Execução Orçamentária** (feed Arquimedes/Financeiro em `senado.gov.br`) e **Portal e-Cidadania** (`www12.senado.leg.br/ecidadania`). Nas listas do e-Cidadania (lidas do D1) o `retrieved_at` é o `lastScrapedAt` do corpus — a idade real do dado; nos detalhes (raspados ao vivo) é o instante da chamada, com a URL canônica do item. A fidelidade do `retrieved_at` vem da camada de cache (`cachedFetchWithMeta`), que persiste o timestamp junto ao valor.
 
+## Conjunto de dados citável (participação no e-Cidadania)
+
+Além do servidor ao vivo, este projeto publica um **conjunto de dados congelado, versionado e citável** da camada de participação do e-Cidadania (consultas públicas, ideias legislativas, eventos interativos + seus comentários, votos históricos por estado) — a camada que o pacote R `congressbr` nunca cobriu. Cada valor carrega um envelope de procedência por campo (`{ value, sourceEndpoint, sourceField, retrievedAt, license, schemaVersion }`); a licença dos dados (Dados Abertos do Senado Federal) é mantida **separada** da licença do código (MIT).
+
+- **Como citar** — [`CITATION.cff`](CITATION.cff) (conjunto de dados; cite o DOI da versão do snapshot que você usou, e o DOI de conceito para o conjunto através das versões).
+- **O que vai em cada release** — [`CHANGELOG-dataset.md`](CHANGELOG-dataset.md) (cumulativo, só acrescenta; amarra cada release ao seu `schemaVersion`).
+- **Dicionário de variáveis e procedência de campo** — [`docs/dataset-dictionary.md`](docs/dataset-dictionary.md) (gerado de `src/dataset/schema.ts`, a fonte única de verdade).
+- **Licença dos dados** — [`LICENSE-DATA.md`](LICENSE-DATA.md).
+- **Como cortar uma release** (congelar → checksums → GitHub Release → DOI no Zenodo) — [`docs/release-runbook.md`](docs/release-runbook.md); a maquinaria está em `src/dataset/`, `scripts/build-dataset/` e `.github/workflows/release-dataset.yml`.
+
+### Inventário — schema v2 (`schemaVersion` `2.0.0`)
+
+Cada release entrega um recurso NDJSON por entidade (um `HarmonizedRecord` por linha: identidade + um envelope de procedência por campo), mais um manifesto `datapackage.json` e uma cópia do dicionário. Cinco recursos:
+
+| Recurso (`*.ndjson`) | Grão | Variáveis principais | Fonte(s) |
+|---|---|---|---|
+| `consultas` | 1 consulta pública (matéria) | `materia`, `ementa`, `votosSim`/`votosNao`/`totalVotos`, `percentual*`, **`autoria`ⁿ**, **`relator`ⁿ**, `status`, `url`, `firstSeenAt` | listagem `pesquisamateria` + **detalhe** (`visualizacaomateria`)ⁿ + `/processo?tramitando=S` para o status |
+| `ideias` | 1 ideia legislativa (~113,7 mil) | `titulo`, `apoios`, `status`, **`dataPublicacao`ⁿ**, **`autorUf`ⁿ**, **`descricao`ⁿ**, **`plConvertido`ⁿ**, `url`, `firstSeenAt` | listagem `pesquisaideia` + **detalhe** (`visualizacaoideia`) por um backfill retomávelⁿ |
+| `eventos` | 1 evento interativo (audiência) | `titulo`, **`data`ᶜ**, **`hora`ᶜ**, `comissao`, **`comissaoNomeCompleto`ⁿ**, **`local`ⁿ**, **`descricao`ⁿ**, **`pauta`ⁿ**, **`convidados`ⁿ**, **`videoUrl`ⁿ**, **`comentarios`ᶜ**, `status`, `url`, `firstSeenAt` | listagem `principalaudiencia` + **detalhe** (`visualizacaoaudiencia`)ⁿ + **fragmento AJAX de comentários**ᶜ |
+| **`eventos_comentarios`ⁿ** | 1 comentário (nível de comentário) | `eventoId`, `comentarioId`, `uf`, `texto`, `data`, `hora`, `momentoVideoUrl`, `convidadoAssociado` | fragmento AJAX `ajaxcolecaocomentarioaudiencia?audienciaId=` |
+| `consultas_votos` | 1 matéria (acervo histórico) | `materia`, `ementa`, `autoria`, `votosSim`/`votosNao`/`totalVotos`, `votosPorUf`, `status`, `url`, `referencePeriod` | CSV do Arquimedes `Proposições-com-votos.csv` (reingerido semanalmente) |
+
+**ⁿ = novo ou reaberto na v2 · ᶜ = fonte corrigida para a canônica na v2.** O que a v2 (`2.0.0`) mudou — a ingestão saiu de **só listagem** para **listagem + detalhe (+ comentários por AJAX nos eventos)**:
+
+- **Eventos corrigidos e enriquecidos.** `data`/`hora` agora vêm da página de detalhe (a canônica — o [estudo A3](docs/estudo-a3-reconciliacao-eventos.md) achou a listagem divergente em 57% dos casos no `hora`), mais seis campos novos de detalhe (`comissaoNomeCompleto`, `local`, `descricao`, `pauta`, `convidados`, `videoUrl`). `comentarios` passou a ser a **contagem canônica do AJAX** (a contagem da listagem era `0` espúrio em 82% dos eventos, capturando só ~6,7% do engajamento).
+- **Recurso novo em nível de comentário**, `eventos_comentarios` — uma linha por comentário de audiência, o sinal de participação que ninguém mais publica versionado.
+- **Campos que só existem no detalhe foram reabertos** para `ideias` (`dataPublicacao`, `autorUf`, `descricao`, `plConvertido`) e `consultas` (`autoria`, `relator`) — antes sempre `null` por decisão de projeto.
+- **Postura de privacidade pela origem do dado.** Conteúdo de cidadão (comentários de audiência, autores de ideia) guarda **apenas a UF — nunca o nome**, descartado já no parser; agente público (autoria/relatoria de consulta, convidados de evento) guarda o nome (público pela função). O racional campo a campo está em `docs/schema-v2-inventario.md` (alvo aprovado).
+
+O NDJSON congelado **não** é commitado (é construído sob demanda a partir do corpus soberano no D1); uma release marcada `dataset-v*` anexa o tarball + `SHA256SUMS` + `release.json` e os arquiva no Zenodo.
+
 ## Inventário de ferramentas
 
 ### Grupo H — Referência/Metadados (1 ferramenta)
@@ -670,7 +711,24 @@ A cobertura abrange as quatro fontes upstream: **Dados Abertos Legislativo** (`l
 |------|-------------|
 | `senado_execucao_orcamentaria` | Execução orçamentária desde 2013 (dotação, empenhado/liquidado/pago) e receitas próprias desde 2012 (previsto vs. arrecadado) — agregadas por ano, ação, grupo de despesa, fonte ou origem de receita; `estatisticas=true` devolve a distribuição do conjunto (min/máx/média/mediana/percentis) + ranking top/bottom, ou um ranking de grupos por soma do `campo` via `agruparPor`, com `campo` (padrão pago / arrecadada) e `topN` |
 
-**Total: 67 ferramentas**
+### Grupo T — Estrutura Organizacional (1 ferramenta)
+
+Lê um retrato embutido da árvore organizacional do Senado (varrida do portal institucional até o nível de serviço por `npm run ingest:estrutura`), porque a API de dados abertos só publica unidades até Secretaria e nunca liga uma unidade-folha ao pai dela. Unidades que o portal lista apenas por nome, sem página própria (os núcleos da CONLEG/CONORF), são capturadas como nós sintéticos a partir da listagem indentada da página. Órgãos do Congresso onde o cadastro de servidores registra lotações (CMO, CPCMS, CMMC) vêm de um complemento curado (`src/estrutura/complemento-cn.ts`, fonte pública: congressonacional.leg.br) sob uma raiz **Congresso Nacional** (`CN`) separada — nunca sob a árvore do Senado, de modo que `subordinadasA: "DGER"` os exclui e `subordinadasA: "CN"` os conta. Servidores registrados sob as pseudo-unidades situacionais "Servidores Afastados/em Trânsito - SF" são reportados à parte, como `afastadosOuEmTransito`, por `senado_servidores`.
+
+| Ferramenta | Descrição |
+|------|-------------|
+| `senado_estrutura_organizacional` | Organograma resolvido para uma `unidade` (sigla como `DGER` ou nome): devolve o `caminho` (ancestrais) e todas as unidades subordinadas (`subordinadas[]` — secretarias, coordenações, serviços, núcleos — com `nivel`). Faz par com o filtro `subordinadasA` de `senado_servidores`, que conta/lista todos os servidores sob uma diretoria inteira (o servidor fica num serviço-folha, então filtrar `lotacao` pela sigla do pai devolve 0). |
+
+### Grupo U — Deep Research (2 ferramentas)
+
+O [contrato Deep Research da OpenAI](#chatgpt-deep-research): as únicas duas ferramentas sem o prefixo `senado_`, porque os nomes são fixados pelo contrato. Registradas pelo mesmo shim das outras (annotations somente-leitura, `outputSchema` permissivo, telemetria por ferramenta) e servidas só em `/mcp` — o perfil curado do app do ChatGPT não as inclui. O índice (senadores em exercício + comissões ativas, ~300 documentos) é construído no primeiro uso a partir dos mesmos dois endpoints de lista que as ferramentas `senado_listar_*` leem, e mantido por 24 h.
+
+| Ferramenta | Descrição |
+|------|-------------|
+| `search` | Ranqueia a consulta (linguagem natural ou palavras-chave, pt/en, sem distinguir acentos) contra senadores em exercício e comissões ativas; devolve até 10 `{ id, title, url }` — `sen:<código>` com a URL do perfil público, `com:<código>` com a página pública da comissão. Proveniência das duas listas em `structuredContent`/`_meta`. |
+| `fetch` | Devolve o documento de um id vindo de `search` como `{ id, title, text, url, metadata }`: a biografia e os mandatos do senador (a mesma leitura de `senado_obter_senador`) ou o resumo e a mesa da comissão (a mesma leitura de `senado_obter_comissao`), em Markdown, com a proveniência dessa leitura. Id desconhecido → erro. |
+
+**Total: 69 ferramentas**
 
 ### Prompts (4)
 
@@ -690,7 +748,7 @@ Documentos/tabelas de contexto estáticos (capacidade MCP `resources`), definido
 | URI | Tipo | Conteúdo |
 | --- | --- | --- |
 | `senado://guia` | markdown | Visão geral e qual ferramenta usar por objetivo. |
-| `senado://catalogo` | markdown | As 67 ferramentas agrupadas por domínio. |
+| `senado://catalogo` | markdown | As 69 ferramentas agrupadas por domínio. |
 | `senado://glossario` | markdown | Siglas e termos do Senado (PEC, CEAPS, CCJ, RCN…). |
 | `senado://tabelas/tipos-materia` | json | Tipos de proposição (sigla/nome/descrição). |
 | `senado://tabelas/ufs` | json | As 27 unidades federativas. |
@@ -774,7 +832,7 @@ tests/                    # Testes unitários Vitest espelhando src/ (parsers, c
 ## Conectando clientes MCP
 
 Este é um servidor **remoto** (Streamable HTTP, sem instalação, acesso aberto) — aponte qualquer cliente MCP para
-`https://senado.sidneybissoli.com/mcp`. Além das 67 ferramentas, ele expõe **prompts** (workflows prontos em pt-BR:
+`https://senado.sidneybissoli.com/mcp`. Além das 69 ferramentas, ele expõe **prompts** (workflows prontos em pt-BR:
 `senado_gastos_senador`, `senado_tramitacao_materia`, `senado_votos_senador`,
 `senado_panorama_ecidadania`) e **recursos** (`senado://guia`, `senado://catalogo`,
 `senado://glossario`, `senado://tabelas/tipos-materia`, `senado://tabelas/ufs`).

package/dist/cli.js

@@ -14,7 +14,8 @@
  * This file is NOT imported by the Worker entrypoint (`src/index.ts`) and never
  * touches `agents/mcp`. It only depends on `createServer` + the stdio transport.
  */
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { unknownCursorError } from "./pagination.js";
 import { createServer } from "./server.js";
 // No Cloudflare bindings in Node: createServer defaults the base URLs when these
 // are empty, and every binding-dependent path is guarded. CACHE_KV is declared on
@@ -26,8 +27,30 @@ const env = {
 };
 async function main() {
     // No `ctx` → e-Cidadania detail write-through is a no-op (fire-and-forget skipped).
-    const server = createServer(env);
-    await server.connect(new StdioServerTransport());
+    // `serveStdio`, e não `server.connect(transport)` direto: ele serve a
+    // abertura MODERNA e a de 2025 no mesmo processo. Conectar o transporte na
+    // mão atende só o ciclo legado, e o mcpscore conta a prontidão para a spec
+    // 2026-07-28 dentro da nota principal — medido em 30/08/2026: 127/144 com
+    // `connect` direto contra 146/148 nos irmãos que usam `serveStdio`, sem UMA
+    // falha de diferença. Eram 17 pontos de regras que sequer eram avaliadas.
+    //
+    // O transporte é construído aqui, e não deixado a cargo do `serveStdio`, para
+    // que o guarda de cursor possa se pendurar nele. Cursor de paginação inválido
+    // -> -32602, o MESMO guarda que o Worker aplica no POST (src/pagination.ts).
+    // Substitui `onmessage` em vez de somar um ouvinte: só quem está NO lugar do
+    // `onmessage` pode interromper a entrega ao SDK, e é a interrupção que produz
+    // a recusa.
+    const transport = new StdioServerTransport();
+    serveStdio(() => createServer(env), { transport });
+    const entregaAoServidor = transport.onmessage;
+    transport.onmessage = (message) => {
+        const recusa = unknownCursorError(message);
+        if (recusa) {
+            void transport.send(recusa);
+            return;
+        }
+        entregaAoServidor?.(message);
+    };
     // Logs go to stderr (see src/utils/logger.ts); stdout carries only JSON-RPC.
     console.error(JSON.stringify({ level: "info", msg: "stdio_ready", ts: new Date().toISOString() }));
 }

package/dist/data/estrutura-organizacional.js

@@ -1,7 +1,7 @@
 export const ESTRUTURA_ORGANIZACIONAL = {
-    "extraidoEm": "2026-08-01T08:10:35.063Z",
+    "extraidoEm": "2026-09-01T10:56:16.383Z",
     "fonteUrl": "https://www12.senado.leg.br/institucional/estrutura/orgaosenado",
-    "total": 824,
+    "total": 823,
     "orgaos": [
         {
             "cod": -2072346465,
@@ -1947,12 +1947,6 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "nome": "Ouvidoria do Senado Federal",
             "codSuperior": null
         },
-        {
-            "cod": 9426,
-            "sigla": null,
-            "nome": "Assessoria Técnica da Strans",
-            "codSuperior": 8852
-        },
         {
             "cod": 9430,
             "sigla": null,
@@ -2217,12 +2211,6 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "nome": "Serviço de Atendimento Eletrônico",
             "codSuperior": 9600
         },
-        {
-            "cod": 9596,
-            "sigla": null,
-            "nome": "Serviço de Manutenção Eletromecânica",
-            "codSuperior": 10741
-        },
         {
             "cod": 9600,
             "sigla": null,
@@ -2457,12 +2445,6 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "nome": "Serviço de Pesquisa e Análise",
             "codSuperior": 9807
         },
-        {
-            "cod": 9810,
-            "sigla": null,
-            "nome": "Observatório da Mulher Contra a Violência",
-            "codSuperior": 9807
-        },
         {
             "cod": 9868,
             "sigla": "IFI",
@@ -4785,18 +4767,6 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "nome": "Serviço de Suporte aos Sistemas de Saúde",
             "codSuperior": 10620
         },
-        {
-            "cod": 10801,
-            "sigla": "GSBBONET",
-            "nome": "Gabinete do Senador Bruno Bonetti",
-            "codSuperior": 108
-        },
-        {
-            "cod": 10803,
-            "sigla": null,
-            "nome": "Escritório de Apoio Nº 01 do Senador Bruno Bonetti",
-            "codSuperior": 10801
-        },
         {
             "cod": 10806,
             "sigla": "GSRACIOL",
@@ -4946,6 +4916,30 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "sigla": null,
             "nome": "Coordenação do Observatório da Mulher Contra a Violência",
             "codSuperior": 8852
+        },
+        {
+            "cod": 10860,
+            "sigla": "GSLPEREI",
+            "nome": "Gabinete da Senadora Lourdinha Pereira",
+            "codSuperior": 108
+        },
+        {
+            "cod": 10861,
+            "sigla": null,
+            "nome": "Escritório de Apoio Nº 01 da Senadora Lourdinha Pereira",
+            "codSuperior": 10860
+        },
+        {
+            "cod": 10862,
+            "sigla": "GSSREGIN",
+            "nome": "Gabinete do Senador Sargento Reginauro",
+            "codSuperior": 108
+        },
+        {
+            "cod": 10863,
+            "sigla": null,
+            "nome": "Escritório de Apoio Nº 01 do Senador Sargento Reginauro",
+            "codSuperior": 10862
         }
     ]
 };

package/dist/discover.js

@@ -0,0 +1,79 @@
+/**
+ * `server/discover` anuncia TODAS as revisões que o servidor atende, não só as
+ * modernas.
+ *
+ * O ACHADO. O `mcpscore` reprovava `protocol_version_supported_versions_include_negotiated`:
+ * o servidor negocia 2025-11-25 pelo handshake `initialize` — é a revisão que o
+ * próprio auditor negocia, e a que a maioria dos clientes fala hoje — mas o
+ * `server/discover` anunciava só `["2026-07-28"]`. A mensagem do auditor é
+ * explícita sobre as duas saídas: "add it to supportedVersions, or disable the
+ * legacy lifecycle". Desligar o ciclo legado trocaria 1 ponto por uma regressão
+ * de compatibilidade com quase todos os clientes; sobra anunciar a verdade.
+ *
+ * POR QUE O SDK NÃO FAZ ISSO. O `_ondiscover()` do
+ * `@modelcontextprotocol/server` 2.0.0 devolve
+ * `modernProtocolVersions(this._supportedProtocolVersions)`, um filtro que
+ * descarta por desenho toda revisão pré-2026 ("2025-era versions are negotiated
+ * via `initialize`"). Não há opção que o desligue. É uma leitura mais estrita
+ * que a do auditor, que se apoia em Basic §Versioning — onde o exemplo de
+ * `UnsupportedProtocolVersionError` lista revisões legadas em `supported`.
+ *
+ * POR QUE PATCH DE MÉTODO, E NÃO TROCA DE HANDLER. Registrar o nosso próprio
+ * handler de `server/discover` não gruda: a entrada HTTP do SDK chama
+ * `installModernOnlyHandlers` A CADA REQUEST, depois da nossa factory, e ela
+ * reinstala `() => server._ondiscover()` por cima. Como o que ela instala é uma
+ * closure que chama o MÉTODO, trocar o método vale para os dois caminhos — o
+ * handler do construtor e o reinstalado — e sobrevive à reinstalação. Trocar o
+ * handler valeria só no stdio, justamente onde o achado não aparece.
+ *
+ * A GUARDA. Isto mexe em `_ondiscover`, que é interno do SDK. O risco de um
+ * patch assim é virar silêncio: o SDK renomeia o método, o patch não aplica
+ * nada e ninguém percebe. Por isso `announceServedVersions` FALHA ALTO se a
+ * forma esperada não estiver lá — o servidor nem constrói — em vez de seguir
+ * com o anúncio antigo. `tests/discover.test.ts` prende o comportamento, e a
+ * catraca do mcpscore no CI pega a regressão pelo lado de fora.
+ */
+/**
+ * Ordena revisões datadas da mais nova para a mais antiga. São strings
+ * `AAAA-MM-DD`, então a ordem lexicográfica É a cronológica.
+ */
+export function maisNovaPrimeiro(versoes) {
+    return [...new Set(versoes)].sort().reverse();
+}
+/**
+ * Troca o `_ondiscover` da instância por um que anuncia todas as revisões
+ * atendidas. Só a lista muda: capacidades e instruções continuam vindo do
+ * cálculo do próprio SDK.
+ */
+export function announceServedVersions(server) {
+    const low = server.server;
+    if (typeof low._ondiscover !== "function") {
+        throw new Error("SDK mudou: Server._ondiscover sumiu — o anúncio de versões em src/discover.ts " +
+            "deixaria de aplicar em silêncio. Reveja o módulo contra a versão nova do " +
+            "@modelcontextprotocol/server antes de seguir.");
+    }
+    if (!Array.isArray(low._supportedProtocolVersions) ||
+        low._supportedProtocolVersions.some((v) => typeof v !== "string")) {
+        throw new Error("SDK mudou: Server._supportedProtocolVersions não é mais uma lista de strings — " +
+            "src/discover.ts não tem de onde tirar as revisões atendidas.");
+    }
+    const original = low._ondiscover.bind(low);
+    low._ondiscover = () => {
+        const base = original();
+        // LER NA HORA DA CHAMADA, não aqui na aplicação do patch. O
+        // `installDiscoverHandler` do SDK ACRESCENTA as revisões modernas a
+        // `_supportedProtocolVersions` por REATRIBUIÇÃO, já com o servidor
+        // construído: uma referência capturada agora ficaria presa ao array
+        // anterior. Foi o que aconteceu na primeira versão deste módulo — o anúncio
+        // saiu com as cinco revisões legadas e SEM a 2026-07-28, e a regra do
+        // auditor passou assim mesmo, porque ela só confere se a negociada está na
+        // lista. Trocar uma omissão por outra não é corrigir.
+        const agora = low._supportedProtocolVersions;
+        if (!Array.isArray(agora) || agora.some((v) => typeof v !== "string"))
+            return base;
+        // A lista vem do próprio SDK, nunca de literais nossas: anunciar uma
+        // revisão que o servidor não atende seria a mentira simétrica da que este
+        // módulo corrige.
+        return { ...base, supportedVersions: maisNovaPrimeiro(agora) };
+    };
+}

package/dist/discovery.js

@@ -0,0 +1,90 @@
+/**
+ * As três coisas que um rastreador procura antes de decidir se vale a pena
+ * visitar um domínio: `robots.txt`, `sitemap.xml` e a chave do IndexNow.
+ *
+ * POR QUE ESTE ARQUIVO EXISTE. Em 31/08/2026 a landing foi reescrita para ser
+ * indexável — meta description, og:, JSON-LD, texto de verdade nos dois
+ * idiomas. E aí a pergunta certa apareceu: indexável por quem? Medido no mesmo
+ * dia, `sitemap.xml` respondia **404** nos quatro domínios do portfólio, e o
+ * `robots.txt` servido era o bloco de *content signals* que a Cloudflare injeta
+ * — 1.248 bytes que são só COMENTÁRIO, sem uma única diretiva ativa: nenhum
+ * `Sitemap:`, nenhum `Allow`. Não bloqueia nada, e também não convida nada. Os
+ * links de entrada para o domínio são finos, então esperar rastreamento
+ * espontâneo era esperar por algo que podia não acontecer — e, pior, ler o
+ * silêncio como resposta.
+ *
+ * O IndexNow é a peça que não depende de conta em painel de buscador: publica-se
+ * uma chave num arquivo do próprio domínio e avisa-se por HTTP quando uma URL
+ * muda. Bing, Yandex, Seznam e Naver honram o protocolo. A chave é PÚBLICA por
+ * desenho — ela prova posse do domínio justamente por estar servida nele.
+ *
+ * Aqui o sitemap tem DUAS URLs: a raiz e a página de termos. Privacidade fica
+ * de fora por decisão registrada em `tests/landing.test.ts` — páginas de
+ * obrigação não disputam a busca com a landing —, mas os termos descrevem o
+ * serviço e são o que um avaliador de diretório procura.
+ */
+import { SITE_URL } from "./landing.js";
+/**
+ * Chave do IndexNow. É PÚBLICA por desenho: prova posse do domínio por estar
+ * servida em `/<chave>.txt`, então versioná-la não é vazamento.
+ */
+export const INDEXNOW_KEY = "a5286cd351e45bcfa411debef2957eaf";
+/** Quando a superfície mudou pela última vez — vira o `lastmod` do sitemap. */
+const ULTIMA_MUDANCA = "2026-08-31";
+function texto(corpo, tipo = "text/plain; charset=utf-8") {
+    return new Response(corpo, {
+        status: 200,
+        headers: { "Content-Type": tipo, "Cache-Control": "public, max-age=3600" },
+    });
+}
+/**
+ * `robots.txt` PRÓPRIO. Ele diz duas coisas que o injetado não dizia: que o
+ * rastreamento é liberado, e onde está o sitemap. As rotas de máquina ficam
+ * fora do índice — `/mcp` é JSON-RPC e as demais são sondas operacionais.
+ */
+export function robotsTxt() {
+    return [
+        "User-agent: *",
+        "Allow: /",
+        "Disallow: /mcp",
+        "Disallow: /health",
+        "Disallow: /status",
+        "Disallow: /metrics",
+        "Disallow: /.well-known/",
+        "",
+        `Sitemap: ${SITE_URL}/sitemap.xml`,
+        "",
+    ].join("\n");
+}
+export function sitemapXml() {
+    const urls = [
+        { loc: `${SITE_URL}/`, prioridade: "1.0", freq: "weekly" },
+        { loc: `${SITE_URL}/terms`, prioridade: "0.3", freq: "yearly" },
+    ];
+    const corpo = urls
+        .map((u) => `  <url>
+    <loc>${u.loc}</loc>
+    <lastmod>${ULTIMA_MUDANCA}</lastmod>
+    <changefreq>${u.freq}</changefreq>
+    <priority>${u.prioridade}</priority>
+  </url>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${corpo}
+</urlset>
+`;
+}
+/**
+ * Responde as rotas de descoberta, ou `null` se o caminho não for uma delas.
+ * Chamada ANTES da auth: um rastreador não tem credencial.
+ */
+export function discoveryResponseForPath(pathname) {
+    if (pathname === "/robots.txt")
+        return texto(robotsTxt());
+    if (pathname === "/sitemap.xml")
+        return texto(sitemapXml(), "application/xml; charset=utf-8");
+    if (pathname === `/${INDEXNOW_KEY}.txt`)
+        return texto(INDEXNOW_KEY);
+    return null;
+}