senado-br-mcp 3.6.0 → 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/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/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;
+}

package/dist/landing.js

@@ -7,10 +7,61 @@
 import { htmlPage, CONTACT_EMAIL, PRIVACY_URL, TERMS_URL } from "./legal.js";
 import { VERSION, USER_AGENT } from "./version.js";
 const GITHUB_URL = "https://github.com/SidneyBissoli/senado-br-mcp-cloudflare";
+const NPM_URL = "https://www.npmjs.com/package/senado-br-mcp";
+export const SITE_URL = "https://senado.sidneybissoli.com";
+const PAGE_TITLE = "Dados Abertos Senado BR MCP";
+/**
+ * UMA frase, em português: o que o servidor serve e de qual fonte. Vira a
+ * `meta description` e o parágrafo de abertura — até ~155 caracteres, que é o
+ * que o resultado de busca mostra sem cortar.
+ */
+const RESUMO = "Servidor MCP dos dados abertos do Senado Federal: senadores, matérias, votações, " +
+    "comissões, e-Cidadania e dados administrativos, com fonte citada.";
+/**
+ * Cabeçalho de DESCOBERTA. Esta é a única página do produto que não pertence a
+ * terceiro — não é o npm, não é o GitHub, não é ficha de diretório. Até
+ * 2026-08-31 ela não declarava `description`, og: nem dado estruturado: havia
+ * texto para ler, mas nada para um buscador entender.
+ */
+function seoHead() {
+    const jsonLd = {
+        "@context": "https://schema.org",
+        "@type": "SoftwareApplication",
+        name: PAGE_TITLE,
+        description: RESUMO,
+        url: SITE_URL,
+        applicationCategory: "DeveloperApplication",
+        operatingSystem: "Any",
+        inLanguage: "pt-BR",
+        offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+        license: "https://opensource.org/licenses/MIT",
+        author: { "@type": "Person", name: "Sidney Bissoli" },
+        codeRepository: GITHUB_URL,
+    };
+    return `  <meta name="description" content="${RESUMO}">
+  <link rel="canonical" href="${SITE_URL}/">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="${PAGE_TITLE}">
+  <meta property="og:title" content="${PAGE_TITLE}">
+  <meta property="og:description" content="${RESUMO}">
+  <meta property="og:url" content="${SITE_URL}/">
+  <meta property="og:locale" content="pt_BR">
+  <meta name="twitter:card" content="summary">
+  <script type="application/ld+json">${JSON.stringify(jsonLd)}</script>`;
+}
 export function buildLandingBody() {
     return `
-    <h1>Dados Abertos Senado BR MCP</h1>
+    <h1>${PAGE_TITLE}</h1>
     <p class="muted">Versão ${VERSION} — serviço independente, somente leitura, não afiliado ao Senado Federal.</p>
+    <p class="lead">${RESUMO}</p>
+
+    <h2>Perguntas que ele responde</h2>
+    <ul>
+      <li>“Quais senadores estão em exercício hoje?”</li>
+      <li>“Como cada senador votou na última votação nominal do plenário?”</li>
+      <li>“Quais matérias sobre saúde foram apresentadas neste ano?”</li>
+      <li>“Quem mais gastou com a cota parlamentar (CEAPS) em 2025?”</li>
+    </ul>
     <p>Este é um servidor <a href="https://modelcontextprotocol.io">MCP (Model Context Protocol)</a> que expõe os dados abertos do Senado Federal do Brasil — senadores, matérias, votações, comissões, e-Cidadania e dados administrativos (CEAPS, contratações, servidores, orçamento) — para assistentes de IA como Claude e ChatGPT. Código aberto sob licença MIT em <a href="${GITHUB_URL}">GitHub</a>.</p>
 
     <h2>Identificação nos logs (User-Agent)</h2>
@@ -33,17 +84,25 @@ export function buildLandingBody() {
       <li><a href="/status">/status</a> — versão e metadados do último deploy</li>
       <li><a href="/health">/health</a> — health check</li>
       <li><a href="${PRIVACY_URL}">Política de privacidade</a> · <a href="${TERMS_URL}">Termos de uso</a></li>
-      <li><a href="${GITHUB_URL}">Código-fonte no GitHub</a> · pacote npm <a href="https://www.npmjs.com/package/senado-br-mcp"><code>senado-br-mcp</code></a></li>
+      <li><a href="${GITHUB_URL}">Código-fonte no GitHub</a> · pacote npm <a href="${NPM_URL}"><code>senado-br-mcp</code></a></li>
     </ul>
 
-    <p class="muted">In English: this is an independent, read-only MCP server for Brazilian Federal Senate open data. If you found this domain in your server logs, the requests came from this client; contact <a href="mailto:${CONTACT_EMAIL}">${CONTACT_EMAIL}</a>.</p>
+    <section lang="en">
+      <h2>Also in English</h2>
+      <p>An independent, read-only MCP server for Brazilian Federal Senate open data — senators, bills, votes, committees, the e-Cidadania participation layer and administrative data (expenses, procurement, staff, budget), each answer carrying its source.</p>
+      <ul>
+        <li>“Which senators are currently in office?”</li>
+        <li>“How did each senator vote on the last recorded floor vote?”</li>
+      </ul>
+      <p>If you found this domain in your server logs, the requests came from this client; contact <a href="mailto:${CONTACT_EMAIL}">${CONTACT_EMAIL}</a>.</p>
+    </section>
 `;
 }
 export function landingResponseForPath(pathname) {
     if (pathname !== "/") {
         return null;
     }
-    return new Response(htmlPage("Dados Abertos Senado BR MCP", buildLandingBody(), "pt-BR"), {
+    return new Response(htmlPage(PAGE_TITLE, buildLandingBody(), "pt-BR", seoHead()), {
         status: 200,
         headers: {
             "Content-Type": "text/html; charset=utf-8",

package/dist/legal.js

@@ -5,13 +5,20 @@ export const PRIVACY_URL = `${SITE_ORIGIN}/privacy`;
 export const TERMS_URL = `${SITE_ORIGIN}/terms`;
 const UPDATED_AT = "2026-06-28";
 export const CONTACT_EMAIL = "sbissoli76@gmail.com";
-export function htmlPage(title, body, lang = "en") {
+/**
+ * Shell HTML das páginas públicas. `head` é injetado apenas por quem tem o que
+ * declarar: a LANDING passa aí a `meta description`, o canonical, os og: e o
+ * JSON-LD. Privacidade e Termos não passam nada — são páginas de obrigação,
+ * não superfície de produto, e não disputam a busca com a landing.
+ */
+export function htmlPage(title, body, lang = "en", head = "") {
     return `<!doctype html>
 <html lang="${lang}">
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${title}</title>
+${head}
   <style>
     :root { color-scheme: light dark; }
     body {
@@ -28,6 +35,7 @@ export function htmlPage(title, body, lang = "en") {
     p, li { font-size: 1rem; }
     a { color: LinkText; }
     .muted { color: color-mix(in srgb, CanvasText 72%, Canvas 28%); }
+    .lead { font-size: 1.1rem; }
   </style>
 </head>
 <body>

package/dist/resources.js

@@ -12,7 +12,7 @@ export function buildGuia() {
     return `# Senado BR MCP — guia de uso
 
 Servidor MCP de dados abertos do Senado Federal (API legislativa, API administrativa e portal
-e-Cidadania). 67 ferramentas, respostas em pt-BR. Abaixo, por onde começar conforme o objetivo.
+e-Cidadania). 69 ferramentas, respostas em pt-BR. Abaixo, por onde começar conforme o objetivo.
 
 ## Senadores
 - \`senado_listar_senadores\` — lista/busca por nome, UF ou partido (use o filtro \`nome\` quando só tiver o nome).
@@ -51,9 +51,9 @@ e-Cidadania). 67 ferramentas, respostas em pt-BR. Abaixo, por onde começar conf
 Dica: vários tools usam um parâmetro enum (\`secao\`/\`tipo\`/\`por\`/\`modo\`/\`tabela\`) para cobrir variações —
 leia a descrição do tool para os valores aceitos.`;
 }
-/** Compact grouped catalog of all 67 tools. */
+/** Compact grouped catalog of all 69 tools. */
 export function buildCatalogo() {
-    return `# Catálogo de ferramentas (67)
+    return `# Catálogo de ferramentas (69)
 
 A — Senadores (5): senado_listar_senadores, senado_obter_senador, senado_votacoes_senador, senado_senador_historico, senado_senadores_afastados
 B — Matérias (2): senado_buscar_materias, senado_obter_materia
@@ -74,7 +74,8 @@ P — Servidores (4): senado_servidores, senado_remuneracoes_servidores, senado_
 Q — Contratações (6): senado_contratos, senado_contratacao_detalhe, senado_licitacoes, senado_terceirizados, senado_empresas_contratadas, senado_contratacoes_lista
 R — Suprimento de fundos (1): senado_suprimento_fundos
 S — Orçamento do Senado (1): senado_execucao_orcamentaria
-T — Estrutura organizacional (1): senado_estrutura_organizacional`;
+T — Estrutura organizacional (1): senado_estrutura_organizacional
+U — Deep Research (2, contrato OpenAI, sem prefixo): search, fetch`;
 }
 /** Glossary of common Senate acronyms and terms. */
 export function buildGlossario() {
@@ -117,7 +118,7 @@ export function registerResources(server) {
     }, (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: buildGuia() }] }));
     server.registerResource("catalogo", "senado://catalogo", {
         title: "Catálogo de ferramentas",
-        description: "Lista das 67 ferramentas agrupadas por domínio.",
+        description: "Lista das 69 ferramentas agrupadas por domínio.",
         mimeType: "text/markdown",
     }, (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: buildCatalogo() }] }));
     server.registerResource("glossario", "senado://glossario", {

package/dist/server.js

@@ -24,6 +24,7 @@ import { registerServidoresTools } from "./tools/servidores.js";
 import { registerSupridosTools } from "./tools/supridos.js";
 import { registerOrcamentoSenadoTools } from "./tools/orcamento-senado.js";
 import { registerEstruturaTools } from "./tools/estrutura.js";
+import { registerDeepResearchToolsSenado } from "./tools/deep-research.js";
 import { registerPrompts } from "./prompts.js";
 import { registerResources } from "./resources.js";
 import { instrumentTool } from "./instrument.js";
@@ -129,6 +130,9 @@ export function createServer(env, ctx, options = {}) {
     registerOrcamentoSenadoTools(host);
     // Group T — Estrutura Organizacional (1 tool — árvore de órgãos, snapshot bundlado)
     registerEstruturaTools(host);
+    // Group U — Deep Research (2 tools: `search`/`fetch`, o contrato OpenAI — os únicos
+    // nomes sem o prefixo `senado_`; passam pelo mesmo shim que os outros)
+    registerDeepResearchToolsSenado(host, baseUrl);
     // MCP prompts (4 reusable pt-BR workflow templates) and resources (5 static
     // context docs/tables) — advertised as the `prompts` and `resources` capabilities.
     registerPrompts(server);

package/dist/tool-titles.js

@@ -4,7 +4,7 @@
  * The Anthropic Connectors Directory review requires a `title` annotation on
  * each tool (alongside `readOnlyHint`). The central shim in `server.ts` injects
  * `annotations.title = TOOL_TITLES[name]` for each tool, so this map must stay
- * in sync with the 67 registered tools — the coverage test in
+ * in sync with the 69 registered tools — the coverage test in
  * `tests/tool-titles.test.ts` fails if a registered tool is missing an entry.
  *
  * Titles are short, user-facing display labels (pt-BR), not descriptions.
@@ -97,6 +97,10 @@ export const TOOL_TITLES = {
     senado_execucao_orcamentaria: "Execução orçamentária do Senado",
     // Estrutura organizacional
     senado_estrutura_organizacional: "Estrutura organizacional",
+    // Deep Research (contrato OpenAI — os únicos nomes sem o prefixo `senado_`;
+    // os mesmos títulos padrão pt-BR da fábrica de @sbissoli/mcp-search)
+    search: "Busca para Deep Research",
+    fetch: "Documento para Deep Research",
 };
 /**
  * Fallback title for a tool with no explicit entry — returns the tool name so a

package/dist/tools/comissoes.js

@@ -87,6 +87,21 @@ export function parseComissaoResumo(colegiado, sigla, secao) {
         payload.aviso = OBTER_COMISSAO_FINALIDADE_AVISO;
     return payload;
 }
+/**
+ * Um item de `/comissao/lista/colegiados` na forma que `senado_listar_comissoes`
+ * devolve. Exportado porque o índice do Deep Research (`deep-research.ts`) lê a
+ * mesma lista e precisa da mesma projeção.
+ */
+export function parseComissaoItem(c) {
+    return {
+        codigo: parseInt(c.Codigo || "0"),
+        sigla: c.Sigla || "",
+        nome: c.Nome || "",
+        tipo: c.DescricaoTipoColegiado || null,
+        casa: c.SiglaCasa || null,
+        ativa: true, // this endpoint only returns active committees
+    };
+}
 /** Resolve a committee sigla to its numeric code via the list endpoint. */
 export async function resolveComissaoCodigo(sigla, baseUrl) {
     const response = await cachedFetch("senado_listar_comissoes", {}, CACHE_SEMI_STATIC, () => upstreamFetch("/comissao/lista/colegiados", {}, baseUrl));
@@ -96,6 +111,20 @@ export async function resolveComissaoCodigo(sigla, baseUrl) {
     const match = comissoes.find((c) => (c.Sigla || "").toUpperCase() === upper);
     return match ? parseInt(match.Codigo || "0") : null;
 }
+/**
+ * A leitura da seção `resumo` de `senado_obter_comissao` a partir do código
+ * numérico: o Colegiado cru de `/comissao/{codigo}` (ou `undefined` quando a
+ * fonte não o traz). Exportada porque o `fetch` do Deep Research
+ * (`deep-research.ts`) é este mesmo documento, com o mesmo cache — `path` é o
+ * que entra em `provenanceFor`.
+ */
+export async function fetchComissaoColegiado(codigo, baseUrl) {
+    const path = `/comissao/${codigo}`;
+    const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_obter_comissao", { codigo }, CACHE_SEMI_STATIC, () => upstreamFetch(path, {}, baseUrl));
+    const r = response;
+    const colegiado = ensureArray(r?.ComissoesCongressoNacional?.Colegiados?.Colegiado)[0];
+    return { path, fetchedAt, colegiado };
+}
 export function registerComissoesTools(server, baseUrl) {
     // E1. senado_listar_comissoes
     server.tool("senado_listar_comissoes", "Lista comissões (colegiados) ativas do Senado, com filtros por `tipo` (permanente, temporaria, cpi, mista) e `ativa`. Retorna `{ count, comissoes }`, cada item com `codigo`, `sigla`, `nome`, `tipo`, `casa` e `ativa`. O endpoint só traz comissões ativas, logo `ativa=false` resulta em lista vazia. Use para descobrir a `sigla` exigida por `senado_obter_comissao` e `senado_reunioes_comissao`.", {
@@ -105,14 +134,7 @@ export function registerComissoesTools(server, baseUrl) {
         try {
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_listar_comissoes", {}, CACHE_SEMI_STATIC, () => upstreamFetch("/comissao/lista/colegiados", {}, baseUrl));
             const r = response;
-            let comissoes = ensureArray(r?.ListaColegiados?.Colegiados?.Colegiado).map((c) => ({
-                codigo: parseInt(c.Codigo || "0"),
-                sigla: c.Sigla || "",
-                nome: c.Nome || "",
-                tipo: c.DescricaoTipoColegiado || null,
-                casa: c.SiglaCasa || null,
-                ativa: true, // this endpoint only returns active committees
-            }));
+            let comissoes = ensureArray(r?.ListaColegiados?.Colegiados?.Colegiado).map(parseComissaoItem);
             if (params.tipo === "mista") {
                 // No DescricaoTipoColegiado equals "mista"; the mistas (CMO, CCAI, CMMC, CMCVM,
                 // CMMIR and the CMMPVs) are identifiable by "Mista" in the name.
@@ -175,10 +197,7 @@ export function registerComissoesTools(server, baseUrl) {
                 });
                 return resultWithProvenance({ sigla, secao, count: membros.length, membros }, prov);
             }
-            const resumoPath = `/comissao/${codigo}`;
-            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_obter_comissao", { codigo }, CACHE_SEMI_STATIC, () => upstreamFetch(resumoPath, {}, baseUrl));
-            const r = response;
-            const colegiado = ensureArray(r?.ComissoesCongressoNacional?.Colegiados?.Colegiado)[0];
+            const { path: resumoPath, fetchedAt, colegiado } = await fetchComissaoColegiado(codigo, baseUrl);
             if (!colegiado)
                 return toolError("Dados da comissão não encontrados.");
             const prov = provenanceFor("SENADO_LEGIS", baseUrl, resumoPath, {

package/dist/tools/deep-research.js

@@ -0,0 +1,280 @@
+/**
+ * Group U — Deep Research (2 tools)
+ * search, fetch — o contrato Deep Research da OpenAI sobre o acervo do servidor.
+ * ChatGPT deep research, company knowledge e os workflows de pesquisa da API
+ * Responses exigem EXATAMENTE essas duas tools, com esses nomes — a única
+ * exceção admitida ao prefixo `senado_`.
+ *
+ * Desenho "coletor + shim `host.tool`": a fábrica de `@sbissoli/mcp-search` é
+ * apontada para um coletor que só colhe `description` e `callback`; o registro
+ * de verdade passa pelo shim de `createServer` como o dos outros 20 grupos —
+ * e ganha de graça o filtro de perfil, o título de `tool-titles.ts`, as
+ * annotations somente-leitura, o `outputSchema` permissivo único (o gate de
+ * `tests/output-contract.test.ts` exige um só; o contrato do ChatGPT lê o JSON
+ * do `content`, não exige outputSchema tipado) e o `instrumentTool`. Por isso
+ * a fábrica NÃO recebe `record` (a telemetria é do shim) nem
+ * `extendOutputSchema` (o outputSchema é do shim).
+ *
+ * O acervo: senadores em exercício (`/senador/lista/atual`, id `sen:<codigo>`)
+ * e colegiados ativos (`/comissao/lista/colegiados`, id `com:<codigo>`) —
+ * as duas listas fechadas que a API publica inteiras. Matérias ficam de fora:
+ * não há dump (só busca por query/ano). A `url` é a página PÚBLICA humana,
+ * nunca a API — é o que o ChatGPT cita: perfil do senador em www25 e a página
+ * da comissão em legis.senado.leg.br/comissoes (padrão verificado ao vivo em
+ * 03/09/2026: CAE=38, CCJ=34, CCAI=449 respondem 200; código inexistente 404).
+ *
+ * O índice vive neste módulo com TTL de 24 h (o L0 do cache, `src/cache/`, tem
+ * TTL máximo de 600 s e 500 entradas — não serve para um índice); é construído
+ * no primeiro `search` e chamadas concorrentes compartilham a construção.
+ * `fetch` reusa as leituras reais de `senado_obter_senador` e
+ * `senado_obter_comissao` (`fetchSenadorDetalhe`/`fetchComissaoColegiado`),
+ * com o mesmo cache e a mesma proveniência — que viaja em `structuredContent`
+ * e `_meta` (`provenanceExtras`), sem rodapé no texto.
+ */
+import { DEEP_RESEARCH_TOOLS, contractSchemas, createIndex, registerDeepResearchTools, } from "@sbissoli/mcp-search";
+import { cachedFetchWithMeta } from "../cache/manager.js";
+import { upstreamFetch } from "../throttle/upstream.js";
+import { ensureArray } from "../utils/validation.js";
+import { provenanceExtras, provenanceFor } from "../utils/provenance.js";
+import { CACHE_SEMI_STATIC } from "../types.js";
+import { extractParlamentares, fetchSenadorDetalhe, parseSenadorResumo } from "./senadores.js";
+import { fetchComissaoColegiado, parseComissaoItem, parseComissaoResumo } from "./comissoes.js";
+import { UFS } from "./referencia.js";
+export { DEEP_RESEARCH_TOOLS };
+/** Teto de resultados do `search` (o contrato pede uma lista curta e relevante). */
+export const DEEP_RESEARCH_LIMIT = 10;
+const PREFIXO_SENADOR = "sen:";
+const PREFIXO_COMISSAO = "com:";
+const PATH_SENADORES = "/senador/lista/atual";
+const PATH_COLEGIADOS = "/comissao/lista/colegiados";
+/** Página pública do perfil do senador (confirmada nas fixtures de contrato e ao vivo). */
+export const urlPerfilSenador = (codigo) => `https://www25.senado.leg.br/web/senadores/senador/-/perfil/${codigo}`;
+/** Página pública da comissão (verificada ao vivo em 03/09/2026 — ver cabeçalho). */
+export const urlPaginaComissao = (codigo) => `https://legis.senado.leg.br/comissoes/comissao?codcol=${codigo}`;
+/** O índice muda com posse, licença e criação de colegiado — nada que um dia não absorva. */
+const INDICE_TTL_MS = 24 * 60 * 60 * 1000;
+/** Título de exibição de um senador: nome parlamentar e a bancada. */
+export function tituloSenador(s) {
+    const bancada = [s.partido, s.uf].filter(Boolean).join("/");
+    return bancada ? `${s.nome} (${bancada})` : s.nome;
+}
+/** Título de exibição de uma comissão: sigla e nome. */
+export function tituloComissao(c) {
+    return c.sigla ? `${c.sigla} — ${c.nome}` : c.nome;
+}
+// "senadora do mato grosso do sul" tem de achar quem é de MS: a sigla sozinha
+// não casa com o nome do estado, então o nome entra nas keywords.
+const NOME_UF = new Map(UFS.map((uf) => [uf.sigla, uf.nome]));
+export function entradasSenadores(senadores) {
+    return senadores
+        .filter((s) => s.codigo > 0)
+        .map((s) => ({
+        id: `${PREFIXO_SENADOR}${s.codigo}`,
+        title: tituloSenador(s),
+        url: urlPerfilSenador(s.codigo),
+        keywords: [s.nomeCompleto, s.partido ?? "", s.uf, NOME_UF.get(s.uf) ?? "", "senador", "senadora", "parlamentar"].filter(Boolean),
+        text: `Senador(a) ${s.nomeCompleto} — ${s.partido ?? "sem partido"}/${s.uf} (${NOME_UF.get(s.uf) ?? "UF n/d"}), em exercício no Senado Federal.`,
+    }));
+}
+export function entradasComissoes(comissoes) {
+    return comissoes
+        .filter((c) => c.codigo > 0)
+        .map((c) => ({
+        id: `${PREFIXO_COMISSAO}${c.codigo}`,
+        title: tituloComissao(c),
+        url: urlPaginaComissao(c.codigo),
+        keywords: [c.sigla, c.tipo ?? "", c.casa ?? "", "comissão", "colegiado"].filter(Boolean),
+        text: `${c.nome} — ${c.tipo ?? "colegiado"} (${c.casa === "CN" ? "Congresso Nacional" : "Senado Federal"}).`,
+    }));
+}
+// Por baseUrl: os testes e o stdio podem apontar para outra base, e o índice de
+// uma não pode servir a outra.
+const indices = new Map();
+const carregando = new Map();
+async function construirIndice(baseUrl) {
+    // As mesmas chaves de cache de `senado_listar_senadores`/`senado_listar_comissoes`:
+    // quem já listou pelo tool aquece o índice, e vice-versa.
+    const [sen, com] = await Promise.all([
+        cachedFetchWithMeta("senado_listar_senadores", { path: PATH_SENADORES }, CACHE_SEMI_STATIC, () => upstreamFetch(PATH_SENADORES, {}, baseUrl)),
+        cachedFetchWithMeta("senado_listar_comissoes", {}, CACHE_SEMI_STATIC, () => upstreamFetch(PATH_COLEGIADOS, {}, baseUrl)),
+    ]);
+    const senadores = extractParlamentares(sen.value).map(parseSenadorResumo);
+    const comissoes = ensureArray(com.value?.ListaColegiados?.Colegiados?.Colegiado).map(parseComissaoItem);
+    return {
+        index: createIndex([...entradasSenadores(senadores), ...entradasComissoes(comissoes)]),
+        provenance: [
+            provenanceFor("SENADO_LEGIS", baseUrl, PATH_SENADORES, { dataset_id: "lista/atual", retrieved_at: sen.fetchedAt }),
+            provenanceFor("SENADO_LEGIS", baseUrl, PATH_COLEGIADOS, { retrieved_at: com.fetchedAt }),
+        ],
+        criadoEm: Date.now(),
+    };
+}
+/**
+ * O índice da base, construído no primeiro uso e mantido por `INDICE_TTL_MS`.
+ * Chamadas concorrentes compartilham a construção; falha não fica em cache.
+ */
+export async function obterIndice(baseUrl) {
+    const atual = indices.get(baseUrl);
+    if (atual && Date.now() - atual.criadoEm < INDICE_TTL_MS)
+        return atual;
+    let promessa = carregando.get(baseUrl);
+    if (!promessa) {
+        promessa = construirIndice(baseUrl)
+            .then((indice) => {
+            indices.set(baseUrl, indice);
+            return indice;
+        })
+            .finally(() => carregando.delete(baseUrl));
+        carregando.set(baseUrl, promessa);
+    }
+    return promessa;
+}
+/** Só para testes: esquece os índices construídos. */
+export function limparIndices() {
+    indices.clear();
+    carregando.clear();
+}
+const linha = (rotulo, valor) => valor === null || valor === undefined || valor === "" ? null : `- **${rotulo}:** ${String(valor)}`;
+export function renderizarSenador(d) {
+    const tratamento = d.sexo === "Feminino" ? "Senadora" : "Senador";
+    const cabecalho = [
+        `# ${tratamento} ${d.nome}`,
+        "",
+        linha("Nome completo", d.nomeCompleto),
+        linha("Nome civil", d.nomeCivil),
+        linha("Partido/UF", [d.partido, d.uf].filter(Boolean).join("/")),
+        linha("Nascimento", d.dataNascimento),
+        linha("Naturalidade", [d.naturalidade, d.ufNaturalidade].filter(Boolean).join("/")),
+        linha("E-mail", d.email),
+    ].filter((l) => l !== null);
+    const mandatos = d.mandatos.length
+        ? [
+            "",
+            "## Mandatos",
+            ...d.mandatos.map((m) => `- ${m.legislatura ? `${m.legislatura}ª legislatura` : "legislatura n/d"} — ${m.uf ?? ""} ${m.participacao ?? ""}`.trimEnd() +
+                (m.dataInicio ? ` (${m.dataInicio}${m.dataFim ? ` a ${m.dataFim}` : ""})` : "")),
+        ]
+        : [];
+    return [...cabecalho, ...mandatos, "", `Fonte: Senado Federal — Dados Abertos. Perfil público: ${urlPerfilSenador(d.codigo)}`].join("\n");
+}
+export function renderizarComissao(r) {
+    const presidente = r.presidente;
+    const vice = r.vicePresidente;
+    const pessoa = (p) => (p?.nome ? `${p.nome}${p.bancada ? ` (${p.bancada})` : ""}` : null);
+    return [
+        `# ${tituloComissao({ sigla: String(r.sigla ?? ""), nome: String(r.nome ?? "") })}`,
+        "",
+        linha("Tipo", r.tipo),
+        linha("Finalidade", r.finalidade),
+        linha("Presidência", pessoa(presidente)),
+        linha("Vice-presidência", pessoa(vice)),
+        linha("Membros", r.totalMembros ? `${r.totalMembros} (${r.titulares ?? "?"} titulares, ${r.suplentes ?? "?"} suplentes)` : null),
+        r.aviso ? `\n> ${String(r.aviso)}` : null,
+        "",
+        `Fonte: Senado Federal — Dados Abertos. Página pública: ${urlPaginaComissao(Number(r.codigo))}`,
+    ]
+        .filter((l) => l !== null)
+        .join("\n");
+}
+// ==================== HANDLERS ====================
+function handlers(baseUrl) {
+    async function search(query) {
+        const indice = await obterIndice(baseUrl);
+        const results = indice.index.search(query, { limit: DEEP_RESEARCH_LIMIT }).map(({ id, title, url }) => ({ id, title, url }));
+        return { results, extras: provenanceExtras(indice.provenance) };
+    }
+    async function fetch(id) {
+        if (id.startsWith(PREFIXO_SENADOR)) {
+            const codigo = Number.parseInt(id.slice(PREFIXO_SENADOR.length), 10);
+            if (!Number.isInteger(codigo) || codigo <= 0)
+                return null;
+            const { path, fetchedAt, detalhe } = await fetchSenadorDetalhe(codigo, baseUrl);
+            if (!detalhe.codigo)
+                return null;
+            const prov = provenanceFor("SENADO_LEGIS", baseUrl, path, {
+                dataset_id: `codigoParlamentar=${codigo}`,
+                retrieved_at: fetchedAt,
+            });
+            return {
+                document: {
+                    id,
+                    title: tituloSenador(detalhe),
+                    text: renderizarSenador(detalhe),
+                    url: urlPerfilSenador(codigo),
+                    metadata: {
+                        tipo: "senador",
+                        codigo,
+                        partido: detalhe.partido,
+                        uf: detalhe.uf,
+                        mandatos: detalhe.mandatos.length,
+                    },
+                },
+                extras: provenanceExtras(prov),
+            };
+        }
+        if (id.startsWith(PREFIXO_COMISSAO)) {
+            const codigo = Number.parseInt(id.slice(PREFIXO_COMISSAO.length), 10);
+            if (!Number.isInteger(codigo) || codigo <= 0)
+                return null;
+            const { path, fetchedAt, colegiado } = await fetchComissaoColegiado(codigo, baseUrl);
+            if (!colegiado)
+                return null;
+            const resumo = parseComissaoResumo(colegiado, String(colegiado.SiglaColegiado ?? ""), "resumo");
+            const prov = provenanceFor("SENADO_LEGIS", baseUrl, path, {
+                dataset_id: `comissao=${resumo.sigla}; codigo=${codigo}`,
+                retrieved_at: fetchedAt,
+            });
+            return {
+                document: {
+                    id,
+                    title: tituloComissao({ sigla: String(resumo.sigla ?? ""), nome: String(resumo.nome ?? "") }),
+                    text: renderizarComissao(resumo),
+                    url: urlPaginaComissao(codigo),
+                    metadata: {
+                        tipo: "comissao",
+                        codigo,
+                        sigla: resumo.sigla,
+                        tipoColegiado: resumo.tipo,
+                    },
+                },
+                extras: provenanceExtras(prov),
+            };
+        }
+        return null;
+    }
+    return { search, fetch };
+}
+/**
+ * Aponta a fábrica do pacote para um coletor e devolve o que ela registrou —
+ * só `description` e `callback` interessam: título, annotations, outputSchema,
+ * perfil e telemetria são do shim.
+ */
+export function capturarDeepResearchTools(baseUrl) {
+    const capturados = [];
+    const coletor = {
+        registerTool: (name, config, callback) => {
+            capturados.push({ name, config, callback });
+        },
+    };
+    registerDeepResearchTools(coletor, {
+        ...handlers(baseUrl),
+        corpus: "Brazilian Federal Senate open data (senators in office and active committees of the Senate and the National Congress)",
+        richTools: "the `senado_*` tools",
+        limit: DEEP_RESEARCH_LIMIT,
+    });
+    const porNome = (name) => {
+        const reg = capturados.find((c) => c.name === name);
+        if (!reg)
+            throw new Error(`fábrica do mcp-search não registrou "${name}"`);
+        return reg;
+    };
+    return { search: porNome("search"), fetch: porNome("fetch") };
+}
+export function registerDeepResearchToolsSenado(server, baseUrl) {
+    const { searchInputSchema, fetchInputSchema } = contractSchemas();
+    const capturados = capturarDeepResearchTools(baseUrl);
+    // U1. search
+    server.tool("search", capturados.search.config.description, searchInputSchema.shape, capturados.search.callback);
+    // U2. fetch
+    server.tool("fetch", capturados.fetch.config.description, fetchInputSchema.shape, capturados.fetch.callback);
+}

package/dist/tools/senadores.js

@@ -155,6 +155,30 @@ export function matchesNome(s, nome) {
     const alvo = normalizeText(nome);
     return normalizeText(s.nomeCompleto).includes(alvo) || normalizeText(s.nome).includes(alvo);
 }
+/**
+ * A leitura de `senado_obter_senador`: detalhe biográfico + mandatos (sub-endpoint,
+ * degrada para lista vazia). Exportada porque o `fetch` do Deep Research
+ * (`deep-research.ts`) é este mesmo documento, com a mesma proveniência e o
+ * mesmo cache — `path` é o que entra em `provenanceFor`.
+ */
+export async function fetchSenadorDetalhe(codigoSenador, baseUrl) {
+    const path = `/senador/${codigoSenador}`;
+    const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_obter_senador", { codigo: codigoSenador }, CACHE_ON_DEMAND, () => upstreamFetch(path, {}, baseUrl));
+    const dados = response.DetalheParlamentar || response;
+    const detalhe = parseSenadorDetalhe(dados);
+    // The /senador/{codigo} detail carries no Mandatos; fetch the sub-endpoint.
+    // Degrade to an empty list if it fails, keeping the biographical data.
+    let mandatos = [];
+    try {
+        const mandatosPath = `/senador/${codigoSenador}/mandatos`;
+        const { value: mResp } = await cachedFetchWithMeta("senado_obter_senador_mandatos", { codigo: codigoSenador }, CACHE_ON_DEMAND, () => upstreamFetch(mandatosPath, {}, baseUrl));
+        mandatos = digArrayRoot(mResp, [["MandatoParlamentar", "Parlamentar", "Mandatos", "Mandato"]], "senado_obter_senador:mandatos").map(parseMandato);
+    }
+    catch {
+        // sub-endpoint unavailable — keep the (empty) mandatos from the detail
+    }
+    return { path, fetchedAt, detalhe: { ...detalhe, mandatos } };
+}
 export function registerSenadoresTools(server, baseUrl) {
     // A1. senado_listar_senadores (filtro `nome` substitui a antiga busca por nome)
     server.tool("senado_listar_senadores", "Use para pedidos como 'liste os senadores em exercício', 'senadores atuais', 'lista atual de senadores' ou filtros por UF/partido. Lista senadores em exercício ou de uma legislatura específica, com filtros opcionais por `nome`, `uf` e `partido`. Retorna `{ count, senadores }`, cada item com `codigo`, `nome`, `nomeCompleto`, `partido`, `uf`, `foto` e `emExercicio`, mais proveniência oficial do endpoint `/senador/lista/atual`. Use `emExercicio` (padrão `true`) ou `legislatura` para escolher o conjunto; `nome` faz correspondência parcial ignorando acentos/maiúsculas (use quando você só tem o nome e precisa do `codigo`); `uf`/`partido` filtram localmente. Use o `codigo` em `senado_obter_senador` ou `senado_votacoes_senador`. Para senadores fora de exercício veja `senado_senadores_afastados`.", {
@@ -195,26 +219,12 @@ export function registerSenadoresTools(server, baseUrl) {
         codigoSenador: z.number().int().positive().describe("Código único do senador no sistema do Senado"),
     }, async (params) => {
         try {
-            const path = `/senador/${params.codigoSenador}`;
-            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_obter_senador", { codigo: params.codigoSenador }, CACHE_ON_DEMAND, () => upstreamFetch(path, {}, baseUrl));
-            const dados = response.DetalheParlamentar || response;
-            const detalhe = parseSenadorDetalhe(dados);
-            // The /senador/{codigo} detail carries no Mandatos; fetch the sub-endpoint.
-            // Degrade to an empty list if it fails, keeping the biographical data.
-            let mandatos = [];
-            try {
-                const mandatosPath = `/senador/${params.codigoSenador}/mandatos`;
-                const { value: mResp } = await cachedFetchWithMeta("senado_obter_senador_mandatos", { codigo: params.codigoSenador }, CACHE_ON_DEMAND, () => upstreamFetch(mandatosPath, {}, baseUrl));
-                mandatos = digArrayRoot(mResp, [["MandatoParlamentar", "Parlamentar", "Mandatos", "Mandato"]], "senado_obter_senador:mandatos").map(parseMandato);
-            }
-            catch {
-                // sub-endpoint unavailable — keep the (empty) mandatos from the detail
-            }
+            const { path, fetchedAt, detalhe } = await fetchSenadorDetalhe(params.codigoSenador, baseUrl);
             const prov = provenanceFor("SENADO_LEGIS", baseUrl, path, {
                 dataset_id: `codigoParlamentar=${params.codigoSenador}`,
                 retrieved_at: fetchedAt,
             });
-            return resultWithProvenance({ ...detalhe, mandatos }, prov);
+            return resultWithProvenance(detalhe, prov);
         }
         catch (e) {
             return errorFrom(e, "Senador não encontrado");

package/dist/utils/provenance.js

@@ -202,3 +202,15 @@ export const ATTRIBUTION_META_KEY = provenanceContext.metaKeys.attribution;
  * `data` deve ser um objeto (structuredContent precisa ser objeto).
  */
 export const resultWithProvenance = (data, provenance) => ({ ...provenanceContext.result(data, provenance) });
+/**
+ * Os dois canais não-textuais do envelope (`structuredContent.provenance` +
+ * `attribution`, e o espelho em `_meta`) SEM o bloco de texto — para tools cujo
+ * `content` é ditado por um contrato externo e não pode levar rodapé (`search`/
+ * `fetch` do Deep Research, em `src/tools/deep-research.ts`, cujo texto tem de
+ * ser exatamente o JSON do contrato). Deriva do mesmo `provenanceContext.result`
+ * das outras tools, então o portão de proveniência continua único.
+ */
+export function provenanceExtras(provenance) {
+    const { structuredContent, _meta } = provenanceContext.result({}, provenance);
+    return { structured: structuredContent, meta: _meta };
+}

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Single source of truth for the server version (kept in sync with package.json). */
-export const VERSION = "3.6.0";
+export const VERSION = "3.7.0";
 export const USER_AGENT = `senado-br-mcp/${VERSION} (+https://senado.sidneybissoli.com; sbissoli76@gmail.com)`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "senado-br-mcp",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "license": "MIT",
   "type": "module",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "dev": "wrangler dev",
@@ -35,6 +35,7 @@
     "eval:judge": "tsx scripts/eval/judge.ts",
     "eval:report": "tsx scripts/eval/report.ts",
     "smoke:openai-app": "node scripts/smoke-openai-app.mjs",
+    "smoke:stdio": "node scripts/smoke-stdio.mjs",
     "ingest:ecidadania": "tsx scripts/ingest-ecidadania/index.ts",
     "ingest:ecidadania:eventos": "tsx scripts/ingest-ecidadania/index-eventos.ts",
     "ingest:ecidadania:ideias": "tsx scripts/ingest-ecidadania/index-ideias.ts",
@@ -50,6 +51,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sbissoli/mcp-provenance": "^0.1.0",
+    "@sbissoli/mcp-search": "^0.3.0",
     "@sbissoli/mcp-stats": "^0.2.0",
     "zod": "^4.5.4"
   },