senado-br-mcp 3.7.0 → 3.9.0

package/README.md

@@ -6,7 +6,7 @@
 [![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)
-[![smithery badge](https://smithery.ai/badge/sidneybissoli/senado-br-mcp-cloudflare)](https://smithery.ai/servers/sidneybissoli/senado-br-mcp-cloudflare)
+[![LightNow capabilities](https://lightnow.ai/badge/io.github.SidneyBissoli/senado-br-mcp-cloudflare)](https://lightnow.ai/servers/io.github.SidneyBissoli/senado-br-mcp-cloudflare)
 [![senado-br-mcp-cloudflare MCP server](https://glama.ai/mcp/servers/SidneyBissoli/senado-br-mcp-cloudflare/badges/score.svg)](https://glama.ai/mcp/servers/SidneyBissoli/senado-br-mcp-cloudflare)
 [![GitHub stars](https://img.shields.io/github/stars/SidneyBissoli/senado-br-mcp-cloudflare?style=flat&logo=github)](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/SidneyBissoli?logo=githubsponsors&label=Sponsor&color=db61a2)](https://github.com/sponsors/SidneyBissoli)
@@ -148,7 +148,7 @@ Claude Code auto-discovers it when you work in this repo. To use it elsewhere, c
 - **Runtime:** Cloudflare Workers (ESM)
 - **Transport:** Streamable HTTP (MCP spec 2025-03-26) via `createMcpHandler` from `agents/mcp`
 - **Protocol:** MCP over JSON-RPC — `/mcp` handles the full public server; `/mcp/openai-app-v2` exposes a curated 27-tool profile plus a shared MCP Apps widget for OpenAI app review/submission (`/mcp/openai-app` remains as a legacy alias)
-- **SDK:** `@modelcontextprotocol/sdk` 1.26.0+ (per-request McpServer instances)
+- **SDK:** `@modelcontextprotocol/server` 2.x (per-request McpServer instances; the v1 `@modelcontextprotocol/sdk` remains only as a peer of `agents`, dev-time)
 - **Validation:** Zod schemas for all tool inputs
 - **Caching:** 2-layer (L0 memory + L1 Cache API) with SHA-256 keying
 - **e-Cidadania store:** D1 database refreshed by a Cron Trigger (every 2h) — list tools read from D1 with a live-scrape fallback and a staleness flag; detail tools stay live with write-through (see [e-Cidadania](#e-cidadania-d1-backed-cron-refreshed))

package/README.pt-BR.md

@@ -149,7 +149,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 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)
+- **SDK:** `@modelcontextprotocol/server` 2.x (instâncias de McpServer por requisição; o `@modelcontextprotocol/sdk` v1 fica só como peer do `agents`, em tempo de dev)
 - **Validação:** schemas Zod para todas as entradas das ferramentas
 - **Cache:** 2 camadas (L0 memória + L1 Cache API) com chaveamento SHA-256
 - **Store do e-Cidadania:** banco D1 atualizado por um Cron Trigger (a cada 2h) — as ferramentas de listagem leem do D1 com fallback de scraping ao vivo e flag de desatualização; as de detalhe ficam ao vivo com write-through (veja [e-Cidadania](#e-cidadania-em-d1-atualizado-por-cron))

package/dist/app-surface.js

@@ -1,6 +1,11 @@
 export const DEFAULT_MCP_ROUTE = "/mcp";
 export const OPENAI_APP_LEGACY_MCP_ROUTE = "/mcp/openai-app";
 export const OPENAI_APP_MCP_ROUTE = "/mcp/openai-app-v2";
+// Rota privada do dono: mesma superficie COMPLETA da rota publica, outro
+// endereco, e a telemetria a marca como uso proprio (ver src/instrument.ts).
+// Precisa ser reconhecida aqui, senao handlerRouteForPath cai no fallback e
+// o handler e montado numa rota diferente da que a requisicao pediu.
+export const SELF_MCP_ROUTE = "/mcp/uso-proprio";
 export const OPENAI_APP_WIDGET_URI = "ui://senado-br-mcp/openai-app-dashboard-v2.html";
 export const OPENAI_APP_WIDGET_DOMAIN = "https://senado.sidneybissoli.com";
 const OPENAI_APP_MCP_ROUTES = new Set([OPENAI_APP_LEGACY_MCP_ROUTE, OPENAI_APP_MCP_ROUTE]);
@@ -89,7 +94,9 @@ export function mcpRouteForProfile(profile) {
 }
 export function handlerRouteForPath(pathname, profile) {
     const normalized = normalizeMcpRoute(pathname);
-    if (OPENAI_APP_MCP_ROUTES.has(normalized) || normalized === DEFAULT_MCP_ROUTE) {
+    if (OPENAI_APP_MCP_ROUTES.has(normalized) ||
+        normalized === DEFAULT_MCP_ROUTE ||
+        normalized === SELF_MCP_ROUTE) {
         return pathname;
     }
     return mcpRouteForProfile(profile);

package/dist/call-shape.js

@@ -0,0 +1,168 @@
+/**
+ * A FORMA da chamada, nunca o conteúdo dela.
+ *
+ * Por que existe. Em 10/09/2026 o painel do portfólio passou a medir erro por
+ * chamada e apontou cinco ferramentas quebradas, a pior delas
+ * `senado_reuniao_comissao`, com 74 erros em 74 chamadas. Diagnosticar custou
+ * vinte minutos de chamadas manuais porque a telemetria dizia QUE falhou e não
+ * DIZIA por quê — e a primeira hipótese (o agente escolheu a ferramenta errada,
+ * confundindo o singular com o plural `senado_reunioes_comissao`) estava
+ * ERRADA: erro de validação de esquema nem chega aqui, o SDK o responde antes
+ * do callback. As 74 falhas eram códigos bem-formados que não existem.
+ *
+ * Por que não gravar os argumentos. O dado que este servidor serve é público; a
+ * PERGUNTA não é. `senado_ceaps` com o id de um senador, repetido, é alguém
+ * investigando aquele senador, e o registro já guarda país e organização de
+ * rede. Parte dos parâmetros é texto livre (`palavraChave`), onde cabe qualquer
+ * coisa que a pessoa digitou. E ligar isso mudaria o que o serviço coleta sem
+ * mudar o que a página pública diz que ele coleta.
+ *
+ * O meio-termo: NOMES de parâmetro (que são o esquema publicado, não dado de
+ * ninguém) e a CLASSE do erro (vocabulário fechado, derivado da nossa própria
+ * mensagem). Isso separa "chamou sem o parâmetro obrigatório" de "chamou certo
+ * com um valor que não existe" — que é a bifurcação do conserto.
+ */
+/**
+ * Classifica pela mensagem de erro, que é NOSSA. A ordem importa: "não
+ * encontrado" e "vazio" são mais específicos que "erro da fonte", e um 404
+ * casaria com os dois.
+ *
+ * O vocabulário foi ampliado depois de passar o classificador por TODAS as
+ * mensagens de erro do bcb e do senado (a varredura virou a guarda em
+ * `call-shape.test.ts`): 13 de 18 aqui e 12 de 18 lá caíam em `outro`, ou
+ * seja, a telemetria não responderia nada nestes dois servidores. As famílias
+ * que faltavam eram "Informe X ou Y", "só existe para", "desconhecido",
+ * "recusada", "não retornou dados" e "não publica" — nenhuma exótica; a versão
+ * inicial foi escrita a partir das mensagens do senado que eu já tinha lido.
+ */
+export function classifyError(message) {
+    const m = message.toLowerCase();
+    // A fronteira de palavra vai só no INÍCIO. Os padrões são RADICAIS
+    // ("vazi", "obrigatóri", "indisponív") justamente porque a flexão muda o
+    // fim: `\bvazi\b` não casa "vazia", e foi assim que "Resposta upstream
+    // vazia" caiu em `fonte` na primeira versão — a palavra que casava era
+    // "upstream". Ordem também importa: "não encontrado" é mais específico que
+    // "erro da fonte", e a mensagem real do senado tem sinal das duas famílias.
+    // "desconhecido"/"unknown" só é sinal de contrato quando qualifica um VALOR
+    // que o chamador passou ("Índice de preços desconhecido: X. Aceitos: ...",
+    // "Unknown dimension(s) for dataflow X"). "Erro desconhecido ao consultar o
+    // calendário do IBGE" e "Unknown error" são o oposto — são justamente o caso
+    // sem classe — e a primeira versão desta ampliação os classificava como
+    // contrato.
+    const valorDesconhecido = /\b(desconhecid|unknown)/.test(m) && !/\b(erro desconhecid|unknown error)/.test(m);
+    if (valorDesconhecido ||
+        /\b(obrigatóri|obrigatori|exige|requer|required|inválid|invalid|validation error|não aceita|nao aceita|no máximo|no maximo|só existe|so existe|recusad)/.test(m) ||
+        // Inglês, das mensagens do ilo, do uis e do medical. `empty query` fica
+        // AQUI e não em nao_encontrado: consulta vazia é parâmetro que falta. Era o
+        // radical `empty` solto que a classificava errado — ele existia para "empty
+        // response", que é outra coisa, e agora está escrito por extenso lá.
+        // "narrow it/the query" e "maximum N per call" são instruções ao chamador:
+        // a resposta não veio porque a chamada precisa mudar, que é contrato.
+        /\b(empty query|not part of|too broad|too many|maximum|narrow (it|the|your)|has no codelist|has no enumerated)/.test(m)) {
+        return "contrato";
+    }
+    if (/\b(não encontrad|nao encontrad|não existe|nao existe|does ?n[o']t exist|not.?found|inexistent|vazi|empty response|empty result|returned empty|sem registros|não retornou dados|nao retornou dados|não publica|nao publica|404)/.test(m) ||
+        // "Nenhum evento encontrado", "nenhuma reunião", "nenhum registro": a forma
+        // varia com o substantivo de cada servidor, então case pelo padrão.
+        /\bnenhum[ao]?s?\b[\s\S]{0,40}\b(encontrad|resultado|registro|dado)/.test(m)) {
+        return "nao_encontrado";
+    }
+    // "Informe X ou Y" é a mensagem canônica de parâmetro que falta — dez delas
+    // no senado, com e sem qualificador na frente ("Para por=senador, informe
+    // 'codigoSenador'"). Fica DEPOIS de "não encontrado" de propósito: é o sinal
+    // mais fraco dos dois, e um "informe um código válido" fechando uma mensagem
+    // de não encontrado não pode sequestrar a classe. Hoje nenhuma mensagem dos
+    // quatro servidores casa com as duas famílias — a ordem existe para a
+    // mensagem que alguém escrever amanhã.
+    if (/\binforme\b/.test(m))
+        return "contrato";
+    // `\b5\d\d\b` e não `5\d\d`: sem a fronteira final, qualquer número com um 5
+    // seguido de dois dígitos casava — um código de reunião "591234" citado na
+    // mensagem virava "erro 5xx". A intenção sempre foi o status HTTP.
+    // A fonte falhou ou demorou. As quatro últimas vieram da fábrica de erros do
+    // ibge, onde caíam em `outro`: ela nomeia a falha de infraestrutura em vez de
+    // usar as palavras genéricas ("Tempo de resposta excedido", não "timeout";
+    // "Serviço em manutenção"; "Erro de conexão"). `erro interno do servidor` vai
+    // com o complemento, porque "erro interno" sozinho pode ser bug nosso.
+    if (/\b(timeout|tempo esgotado|tempo de resposta excedid|excedeu o tempo|indisponív|indisponiv|manutenç|manutenc|erro de conexão|erro de conexao|erro interno do servidor|internal server error|upstream|\b5\d\d\b|payload|too large|grande demais|limite de tamanho)/.test(m)) {
+        return "fonte";
+    }
+    return "outro";
+}
+/**
+ * Nomes dos parâmetros que a chamada trouxe, em ordem, separados por vírgula.
+ * Só os nomes de PRIMEIRO nível e só quando o argumento é objeto simples — o
+ * conteúdo nunca entra. Cortado em 200 caracteres porque blob do Analytics
+ * Engine tem teto de tamanho e um nome de parâmetro longo não vale a linha.
+ */
+export function paramNames(args) {
+    const a = Array.isArray(args) ? args[0] : args;
+    if (!a || typeof a !== "object" || Array.isArray(a))
+        return "";
+    const nomes = Object.keys(a)
+        .filter((k) => a[k] !== undefined)
+        .sort();
+    return nomes.join(",").slice(0, 200);
+}
+/**
+ * Texto de erro de um resultado de tool, para classificar. Vazio quando não há.
+ *
+ * Lê o CAMPO `error` do envelope, não o payload serializado inteiro. O envelope
+ * padrão é `{ error, retryable, hint }`, e o `hint` de erro não recuperável
+ * termina com "a fonte oficial pode estar indisponível" — texto de formulário,
+ * igual em todos. Classificando o payload inteiro, esse "indisponível"
+ * arrastava TODO erro não recuperável para a classe `fonte`. Visto na produção
+ * do senado em 10/09/2026: a mensagem "Não existe reunião com o código X",
+ * que é `nao_encontrado` por definição, foi gravada como `fonte`.
+ */
+export function errorText(result) {
+    if (!result || typeof result !== "object")
+        return "";
+    const r = result;
+    const estruturado = r.structuredContent?.error;
+    if (typeof estruturado === "string")
+        return estruturado;
+    const t = Array.isArray(r.content) ? r.content[0]?.text : undefined;
+    if (typeof t !== "string")
+        return "";
+    try {
+        const j = JSON.parse(t);
+        if (typeof j.error === "string")
+            return j.error;
+    }
+    catch {
+        // Não é o envelope JSON — vale o texto cru (é o caso de outros servidores).
+    }
+    return t;
+}
+/**
+ * Classifica uma exceção que ESCAPOU do handler, tendo o objeto do erro em mãos
+ * e não só a mensagem.
+ *
+ * Por que existe. Em 22/09/2026 o `ibge_cnae` respondia
+ * `Cannot read properties of undefined (reading 'divisao')` a um código de
+ * classe válido — um `TypeError` nosso, nascido de um `[]` da fonte que
+ * atravessou a camada de rede. Nenhum padrão de `classifyError` casa com essa
+ * frase, então ela caía em `outro`, que já era 13 dos 23 erros da ferramenta na
+ * semana. O comentário de `outro` avisava desde o início: *se esta classe
+ * crescer, é sinal de que falta uma classe*. Faltava esta. O conserto nasceu no
+ * `ibge-br-mcp` 5.1.2 e é o mesmo em toda a frota, porque a classe é a mesma.
+ *
+ * O sinal é o TIPO, não a frase, e é por isso que esta função existe separada
+ * de `classifyError`: `TypeError`, `RangeError`, `ReferenceError` e
+ * `SyntaxError` são erros de programa. A fonte não os produz — nós os
+ * produzimos ao supor a forma do que ela respondeu. Classificá-los por
+ * mensagem seria caçar o texto do motor de JS, que muda entre versões de Node.
+ *
+ * `classifyError` fica INTACTA: ela recebe mensagem e continua sendo o caminho
+ * do erro que NÓS escrevemos.
+ */
+export function classifyThrown(error) {
+    if (error instanceof TypeError ||
+        error instanceof RangeError ||
+        error instanceof ReferenceError ||
+        error instanceof SyntaxError) {
+        return "defeito";
+    }
+    return classifyError(error instanceof Error ? error.message : String(error));
+}

package/dist/instrument.js

@@ -15,10 +15,12 @@
  * there is nothing to await and no need for ctx.waitUntil — a try/catch is the
  * correct and sufficient guard.
  *
- * Privacy: only the tool name, a coarse ok/error status, cache-outcome counts, and
- * aggregable request context (country, AS organization, owner's self-use marker) are
- * recorded. No user query content, tool parameters, IP, or PII ever reach Analytics
- * Engine.
+ * Privacy: only the tool name, a coarse ok/error status, cache-outcome counts,
+ * aggregable request context (country, AS organization, owner's self-use marker),
+ * and — since 2026-09-10 — the SHAPE of the call: the NAMES of the parameters
+ * supplied and a closed-vocabulary error class. No user query content, no
+ * parameter VALUES, no IP and no PII ever reach Analytics Engine. The reasoning
+ * for that line, and why the shape was worth adding, is in src/call-shape.ts.
  *
  * Request context (blobs 4–6): hosted AI-platform connectors egress from the
  * platform's own servers (e.g. Anthropic in the US), so country/AS is the only way
@@ -26,43 +28,75 @@
  * connector is only identifiable via the secret header his MCP clients send
  * (SELF_HEADER, value = the SELF_MARKER Wrangler secret).
  */
+import { classifyError, classifyThrown, errorText, paramNames } from "./call-shape.js";
 import { incr, incrTool } from "./metrics.js";
 import { callCache, cacheClass } from "./observability/call-context.js";
 /** Header the owner's MCP clients send (value = the SELF_MARKER secret). */
 export const SELF_HEADER = "x-mcp-self";
+/**
+ * Rota privada do dono: mesma superficie, mesmo resultado, outro ENDERECO.
+ *
+ * O marcador por header so funciona em cliente que aceita header custom, e o
+ * conector do claude.ai nao aceita — e e por ele que o dono mais usa os
+ * proprios servidores. Medido em 28/08/2026: o header pegava UMA chamada por
+ * produto por semana; todo o resto do uso proprio saia dos servidores da
+ * Anthropic, indistinguivel de terceiro, inflando a adocao.
+ *
+ * O conector nao manda header, mas aponta para qualquer URL. Entao a
+ * separacao vem da ROTA: chamada que chega aqui e uso proprio por construcao.
+ *
+ * O caminho e adivinhavel de proposito (o dono precisa cola-lo em varios
+ * clientes). O risco e um varredor cair aqui e ser contado como dono: sujeira
+ * no balde do uso proprio, nao vazamento — a rota serve o mesmo conteudo
+ * publico. Detectavel olhando pais/AS das chamadas marcadas.
+ */
+export const SELF_ROUTE = "/mcp/uso-proprio";
 /** Extracts country/AS from request.cf and matches the self-use secret header. */
-export function tagRequest(request, selfSecret) {
+export function tagRequest(request, selfSecret, sessao = "") {
     const cf = request.cf;
     return {
-        self: !!selfSecret && request.headers.get(SELF_HEADER) === selfSecret,
+        self: (!!selfSecret && request.headers.get(SELF_HEADER) === selfSecret) ||
+            new URL(request.url).pathname === SELF_ROUTE,
         country: typeof cf?.country === "string" ? cf.country : "",
         asOrg: typeof cf?.asOrganization === "string" ? cf.asOrganization : "",
+        sessao,
     };
 }
 export function instrumentTool(name, cb, analytics, tag) {
     return async (...args) => {
         incr("toolCalls");
         let isError = false;
+        let classe = "";
         // Per-call store the cache layer increments per upstream fetch (see call-context.ts).
         const stats = { fetches: 0, hits: 0 };
         try {
             const result = await callCache.run(stats, () => cb(...args));
             isError =
                 typeof result === "object" && result !== null && result.isError === true;
+            if (isError)
+                classe = classifyError(errorText(result));
             return result;
         }
         catch (e) {
             // A thrown error is also a failed tool call — record it, then rethrow so the
             // SDK still produces the normal error response.
             isError = true;
+            // `classifyThrown` e não `classifyError`: aqui o OBJETO do erro existe,
+            // e o tipo dele separa bug nosso (`TypeError` & cia. -> `defeito`) de
+            // condição da fonte. Pela mensagem, um `TypeError` caía em `outro`.
+            classe = classifyThrown(e);
             throw e;
         }
         finally {
-            recordToolCall(name, isError, stats, analytics, tag);
+            // ATENÇÃO ao que NÃO chega aqui: erro de validação do esquema. O SDK o
+            // responde ANTES do callback, então a chamada não é contada nem como
+            // chamada nem como erro. Medido em 10/09/2026 pelo /metrics: três
+            // chamadas com argumento de forma errada não moveram o contador.
+            recordToolCall(name, isError, stats, analytics, tag, classe, paramNames(args));
         }
     };
 }
-function recordToolCall(name, isError, stats, analytics, tag) {
+function recordToolCall(name, isError, stats, analytics, tag, errorClass = "", params = "", cliente = "") {
     incrTool(name, isError);
     if (!analytics)
         return;
@@ -74,6 +108,11 @@ function recordToolCall(name, isError, stats, analytics, tag) {
             // blob3 = cache class of the call (cached | live | partial | none),
             // blob4 = "self" when the owner's secret header matched, blob5 = country,
             // blob6 = AS organization (request.cf) — same positions in every portfolio MCP.
+            // blob7 = error class (closed vocabulary, "" when the call succeeded),
+            // blob8 = NAMES of the parameters supplied, comma-separated — never values.
+            // blob9 = session id issued at initialize (random, echoed by the client),
+            // blob10 = client software name from initialize (clientInfo.name, normalised;
+            // only on the initialize line) — same positions in every portfolio MCP.
             blobs: [
                 name,
                 isError ? "error" : "ok",
@@ -81,6 +120,10 @@ function recordToolCall(name, isError, stats, analytics, tag) {
                 tag?.self ? "self" : "",
                 tag?.country ?? "",
                 tag?.asOrg ?? "",
+                errorClass,
+                params,
+                tag?.sessao ?? "",
+                cliente,
             ],
             // double1 = error flag (error rate via avg); double2 = upstream fetches in the call;
             // double3 = how many were cache hits (fetch-level cache-hit ratio via sum/sum).
@@ -91,3 +134,177 @@ function recordToolCall(name, isError, stats, analytics, tag) {
         // Swallow: a telemetry failure must never break or slow a tool response.
     }
 }
+/**
+ * Métodos de PROTOCOLO, gravados na camada HTTP.
+ *
+ * `instrumentTool` só vê `tools/call`: ela envolve o callback da tool.
+ * `initialize`, `tools/list`, `notifications/*`, `ping` e o que mais o
+ * cliente mande (`server/discover`, por exemplo) atravessam o transporte sem
+ * tocar tool nenhuma — e são eles que contam o FUNIL DE SESSÃO: quantos
+ * `initialize` viram chamada de ferramenta de verdade, que é o que separa
+ * "acharam o servidor" de "usaram o servidor". Medido em 2026-09-10: só o
+ * sih-br-mcp os gravava, porque lá o Worker é um proxy que lê o corpo
+ * JSON-RPC antes de encaminhar. Aqui o servidor roda dentro do Worker, e o
+ * corpo vem de uma CÓPIA tirada antes de o handler consumir o stream
+ * (src/index.ts). Desde 2026-09-16 a frota inteira grava igual.
+ *
+ * Mesmo esquema de blobs, com o método no lugar do nome da tool — igual ao
+ * sih. O painel separa os dois pelo nome (`metodo_de_protocolo`). Classe de
+ * cache, classe de erro e parâmetros ficam vazios; fetches e hits, zero.
+ *
+ * O que entra, e de onde vem o desfecho:
+ *  - todo método que não é `tools/call` → uma linha, "ok" se o HTTP da
+ *    resposta for < 400, "error" senão. LIMITAÇÃO, a mesma do sih: erro
+ *    JSON-RPC que viaja dentro de um 200 (método desconhecido, -32601) sai
+ *    como "ok" — ler exigiria consumir o corpo que está sendo devolvido;
+ *  - `tools/call` só quando o HTTP é ≥ 400: o transporte recusou antes de
+ *    despachar (Accept errado, sessão inválida, Origin estrangeiro) e a tool
+ *    nunca rodou; sem isto a recusa seria invisível. Com HTTP < 400 a
+ *    `instrumentTool` já gravou a linha, com o desfecho de verdade — não se
+ *    grava de novo;
+ *  - lote JSON-RPC (array) → uma linha por item; item sem `method` (resposta
+ *    do cliente, corpo que não é JSON) → nada.
+ *
+ * Só no Analytics Engine: os contadores do /metrics continuam contando tools.
+ */
+export function protocolNamesFromBody(body, status) {
+    const itens = Array.isArray(body) ? body : [body];
+    const nomes = [];
+    for (const item of itens) {
+        if (!item || typeof item !== "object")
+            continue;
+        const msg = item;
+        if (typeof msg.method !== "string" || msg.method === "")
+            continue;
+        if (msg.method === "tools/call") {
+            if (status < 400)
+                continue; // instrumentTool já gravou esta
+            const params = msg.params;
+            nomes.push(typeof params?.name === "string" && params.name !== "" ? params.name : "tools/call");
+        }
+        else {
+            nomes.push(msg.method);
+        }
+    }
+    return nomes;
+}
+/**
+ * Grava no Analytics Engine os métodos de protocolo de um POST no endpoint
+ * MCP (ver protocolNamesFromBody). Devolve os nomes gravados. Sem binding,
+ * não grava nada.
+ */
+export function recordProtocolMethods(analytics, tag, body, status) {
+    if (!analytics || body === undefined)
+        return [];
+    const cliente = clientNameFromBody(body);
+    const nomes = protocolNamesFromBody(body, status);
+    const isError = status >= 400;
+    for (const name of nomes) {
+        try {
+            analytics.writeDataPoint({
+                indexes: [name],
+                blobs: [
+                    name,
+                    isError ? "error" : "ok",
+                    "",
+                    tag?.self ? "self" : "",
+                    tag?.country ?? "",
+                    tag?.asOrg ?? "",
+                    "",
+                    "",
+                    tag?.sessao ?? "",
+                    name === "initialize" ? cliente : "",
+                ],
+                doubles: [isError ? 1 : 0, 0, 0],
+            });
+        }
+        catch {
+            // Falha de telemetria nunca quebra nem atrasa a resposta.
+        }
+    }
+    return nomes;
+}
+/**
+ * SESSÃO E CLIENTE (blobs 9 e 10, desde 2026-09-17).
+ *
+ * O que faltava para o funil de sessão do painel ser um funil de verdade: a
+ * telemetria tinha `initialize` e `tools/call` como contagens soltas, sem
+ * nada que ligasse duas linhas à mesma sessão — a razão "chamadas por
+ * initialize" mistura quantas sessões usaram com quanto cada uma usou, e
+ * 2,5 tanto pode ser todo mundo chamando 2 ou 3 vezes quanto 10% chamando 25.
+ *
+ * O elo é o do próprio protocolo: o servidor devolve `Mcp-Session-Id` na
+ * resposta ao `initialize` e o cliente é obrigado a repeti-lo em toda
+ * requisição seguinte. O handler continua STATELESS — o transporte do SDK v2
+ * não emite id neste modo e, conferido em 16/09/2026 nos sete servidores e
+ * no código (`validateSession` retorna sem checar quando não há gerador),
+ * também não lê nem valida o que o cliente manda. Então o Worker sorteia o
+ * id no `initialize`, devolve no cabeçalho e, nas demais requisições, só lê
+ * o que o cliente devolveu e grava. Nada é armazenado; o id é aleatório
+ * (UUID v4 do `crypto`) e não identifica pessoa, máquina nem rede — só liga
+ * as linhas de um aperto de mão. Colisão de UUID v4 é da ordem de n²/2¹²⁹:
+ * não é risco prático.
+ *
+ * O cliente é o software que se apresentou no `initialize`
+ * (`params.clientInfo.name`): claude.ai, Claude Code, Inspector, um scanner
+ * com nome próprio. É autodeclarado e descreve o programa, não a pessoa. Vai
+ * normalizado (minúsculas, sem versão, vocabulário de caracteres fechado,
+ * tamanho limitado) para não virar texto livre na telemetria, e SÓ na linha
+ * do `initialize` — as chamadas seguintes chegam ao cliente pela sessão.
+ *
+ * Id que o cliente manda e não parece um id (fora do vocabulário, comprido
+ * demais) é tratado como ausente: continua sem estado, e a telemetria não
+ * carrega o que não sabe ler.
+ */
+export const SESSION_HEADER = "mcp-session-id";
+const SESSION_ID_OK = /^[A-Za-z0-9._~-]{1,64}$/;
+/** O corpo (mensagem ou lote JSON-RPC) contém um `initialize`? */
+export function isInitialize(body) {
+    const itens = Array.isArray(body) ? body : [body];
+    return itens.some((m) => !!m && typeof m === "object" && m.method === "initialize");
+}
+/**
+ * A sessão desta requisição: sorteada no `initialize` (`nova`), lida do
+ * cabeçalho nas demais; "" quando não há sessão legível.
+ */
+export function sessionFromRequest(request, body) {
+    if (isInitialize(body))
+        return { id: crypto.randomUUID(), nova: true };
+    const enviada = request.headers.get(SESSION_HEADER) ?? "";
+    return { id: SESSION_ID_OK.test(enviada) ? enviada : "", nova: false };
+}
+/** Devolve a resposta com o `Mcp-Session-Id` quando a sessão nasceu aqui. */
+export function withSessionHeader(response, sessao) {
+    if (!sessao.nova || !sessao.id)
+        return response;
+    const headers = new Headers(response.headers);
+    headers.set(SESSION_HEADER, sessao.id);
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+/** Nome do cliente normalizado: minúsculas, caracteres fechados, até 40. */
+export function normalizeClientName(x) {
+    if (typeof x !== "string")
+        return "";
+    return x
+        .toLowerCase()
+        .replace(/[^a-z0-9._+/ -]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 40);
+}
+/** `clientInfo.name` do `initialize` (o primeiro, num lote); "" fora dele. */
+export function clientNameFromBody(body) {
+    const itens = Array.isArray(body) ? body : [body];
+    for (const m of itens) {
+        if (!m || typeof m !== "object")
+            continue;
+        const msg = m;
+        if (msg.method === "initialize")
+            return normalizeClientName(msg.params?.clientInfo?.name);
+    }
+    return "";
+}

package/dist/server.js

@@ -33,6 +33,32 @@ import { instructionsForProfile, isToolEnabledForProfile, minimizeToolResultForP
 import { registerOpenAiAppWidget } from "./openai-app-widget.js";
 import { titleForTool } from "./tool-titles.js";
 import { announceServedVersions } from "./discover.js";
+/**
+ * O esquema de entrada RECUSA parâmetro que não existe.
+ *
+ * Todas as tools do senado passam por um funil só (`host.tool` abaixo), que
+ * recebia a shape crua e a entregava ao SDK como objeto ABERTO. Aberto, o zod
+ * descarta a chave desconhecida em silêncio, o parâmetro que o chamador queria
+ * usar fica com o default e a ferramenta responde OUTRA pergunta com cara de
+ * resposta. Medido no irmão ibge-br-mcp em 11/09/2026: `periodo` no singular,
+ * que o esquema não tem, devolveu a população de 2026 para uma pergunta sobre
+ * 2023, com nenhum aviso. Resposta errada é pior que erro — erro o modelo
+ * corrige na chamada seguinte, resposta errada vira número em relatório. Aqui
+ * o campo minado é grande: 67 ferramentas, muitas com pares quase homônimos
+ * (`codigoSenador`/`codigoParlamentar`, `sigla`/`siglaComissao`).
+ *
+ * `.strict()` publica `additionalProperties: false` e faz o SDK responder
+ * `Unrecognized key: "<nome>"`, que NOMEIA a chave.
+ *
+ * `search` e `fetch` ficam ABERTAS de propósito: o contrato é da OpenAI, elas
+ * entram pelo mesmo funil (registerDeepResearchToolsSenado) e fechá-las seria
+ * mexer num contrato que não é nosso.
+ */
+const TOOLS_DE_CONTRATO_ALHEIO = new Set(["search", "fetch"]);
+function esquemaDeEntrada(name, shape) {
+    const objeto = z.object(shape);
+    return TOOLS_DE_CONTRATO_ALHEIO.has(name) ? objeto : objeto.strict();
+}
 export function createServer(env, ctx, options = {}) {
     const toolProfile = options.toolProfile ?? "full";
     const server = new McpServer({
@@ -76,7 +102,7 @@ export function createServer(env, ctx, options = {}) {
         return registerTool(name, {
             title: titleForTool(name),
             description,
-            inputSchema: shape,
+            inputSchema: esquemaDeEntrada(name, shape),
             outputSchema: outputSchema,
             annotations: {
                 title: titleForTool(name),

package/dist/throttle/upstream.js

@@ -18,10 +18,27 @@ let inFlight = 0;
 export class UpstreamError extends Error {
     status;
     retryable;
-    constructor(message, status, retryable) {
+    transport;
+    constructor(message, status, retryable, 
+    /**
+     * True only when the upstream never produced a response: DNS, TCP, TLS,
+     * an aborted request, or the time budget running out. A response that
+     * arrived and was rejected — an HTTP status, a body over the size guard,
+     * an empty body, a body that is not JSON — is NOT transport, even when
+     * its status is 502.
+     *
+     * The distinction exists because "the Senado did not answer" and "the
+     * Senado answered with a different shape" are opposite facts for the
+     * nightly contract tier: the first means drift could not be measured
+     * tonight, the second is the drift it exists to catch. Status alone
+     * cannot carry it — 502 is used for both a real Bad Gateway and a body
+     * that failed to parse.
+     */
+    transport = false) {
         super(message);
         this.status = status;
         this.retryable = retryable;
+        this.transport = transport;
         this.name = "UpstreamError";
     }
 }
@@ -87,7 +104,7 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
         const elapsed = Date.now() - startTime;
         const remaining = UPSTREAM_TIMEOUT_MS - elapsed;
         if (remaining <= 0) {
-            lastError = lastError || new UpstreamError(`[${path}] Timeout: orçamento de ${UPSTREAM_TIMEOUT_MS}ms esgotado antes da tentativa ${attempt + 1}`, 504, true);
+            lastError = lastError || new UpstreamError(`[${path}] Timeout: orçamento de ${UPSTREAM_TIMEOUT_MS}ms esgotado antes da tentativa ${attempt + 1}`, 504, true, true);
             break;
         }
         const controller = new AbortController();
@@ -159,7 +176,8 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
             const isAbort = err.name === "AbortError";
             lastError = new UpstreamError(isAbort
                 ? `[${path}] Timeout na requisição upstream (${UPSTREAM_TIMEOUT_MS / 1000}s)`
-                : `[${path}] Erro de rede: ${err.message || "desconhecido"}`, isAbort ? 504 : 502, true);
+                : `[${path}] Erro de rede: ${err.message || "desconhecido"}`, isAbort ? 504 : 502, true, // Network errors are always retryable
+            true);
             if (isAbort)
                 break; // AbortError means time budget is spent
             if (attempt < MAX_RETRIES) {

package/dist/tools/comissoes.js

@@ -16,6 +16,7 @@ import { cachedFetch, cachedFetchWithMeta } from "../cache/manager.js";
 import { upstreamFetch } from "../throttle/upstream.js";
 import { toolError, errorFrom, ensureArray, safeInt, toBool, normalizeText } from "../utils/validation.js";
 import { digArrayRoot } from "../utils/upstream-parse.js";
+import { escolherReuniao, ehReuniaoInexistente, mensagemCodigoInexistente } from "./resolver-reuniao.js";
 import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { CACHE_SEMI_STATIC, CACHE_DYNAMIC, CACHE_ON_DEMAND, UPSTREAM_TIMEOUT_MS } from "../types.js";
 import { USER_AGENT } from "../version.js";
@@ -306,16 +307,57 @@ export function registerComissoesTools(server, baseUrl) {
         }
     });
     // E6. senado_reuniao_comissao
-    server.tool("senado_reuniao_comissao", "Detalha uma reunião de comissão pelo `codigoReuniao`. Retorna um objeto com `codigo`, `titulo`, `comissao`, `data`, `hora`, `local`, `situacao`, `realizada`, `secreta`, `tipoPresenca` (presencial/semipresencial), `presidente`, links `urlPauta`/`urlResultado`/`urlAta` e `partes` (cada parte com `evento` e `itens` apreciados: `identificacao`, `ementa`, `autoria`, `relatoria`, `resultado`, `codigoMateria`). A API NÃO publica lista de presença da reunião (só presidente e eventuais convidados): reconstrua a presença pelos votos nominais (`senado_votacao_comissao`), por quem falou na transcrição (`senado_notas_taquigraficas` com `tipo=reuniao`) ou pela ata oficial (`urlAta`, quando publicada). Obtenha o `codigoReuniao` em `senado_agenda_comissoes` ou `senado_reunioes_comissao`.", {
-        codigoReuniao: z.number().int().positive().describe("Código da reunião (campo 'codigo' na agenda de comissões)"),
+    server.tool("senado_reuniao_comissao", "Detalha uma reunião de comissão. Aceita DOIS caminhos: o `codigoReuniao` direto, ou `sigla` da comissão mais `data` (YYYYMMDD) — neste segundo caso a ferramenta resolve o código sozinha, e devolve as candidatas quando o dia tem mais de uma reunião. Retorna um objeto com `codigo`, `titulo`, `comissao`, `data`, `hora`, `local`, `situacao`, `realizada`, `secreta`, `tipoPresenca` (presencial/semipresencial), `presidente`, links `urlPauta`/`urlResultado`/`urlAta` e `partes` (cada parte com `evento` e `itens` apreciados: `identificacao`, `ementa`, `autoria`, `relatoria`, `resultado`, `codigoMateria`). A API NÃO publica lista de presença da reunião (só presidente e eventuais convidados): reconstrua a presença pelos votos nominais (`senado_votacao_comissao`), por quem falou na transcrição (`senado_notas_taquigraficas` com `tipo=reuniao`) ou pela ata oficial (`urlAta`, quando publicada). Sem código à mão, prefira `sigla` + `data`; o `codigoReuniao` também sai de `senado_agenda_comissoes` ou `senado_reunioes_comissao`.", {
+        codigoReuniao: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Código da reunião (campo 'codigo' na agenda). Sem ele, informe sigla e data."),
+        sigla: z.string().min(2).optional().describe("Sigla da comissão (ex.: CAE) — alternativa ao código"),
+        data: z
+            .string()
+            .regex(/^\d{8}$/)
+            .optional()
+            .describe("Data da reunião (YYYYMMDD) — usada com `sigla`; sem ela, os últimos 14 dias"),
     }, async (params) => {
         try {
-            const reuniaoPath = `/comissao/reuniao/${params.codigoReuniao}`;
-            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_reuniao_comissao", { codigo: params.codigoReuniao }, CACHE_ON_DEMAND, () => upstreamFetch(reuniaoPath, {}, baseUrl));
+            // Caminho por sigla: resolve o código internamente. Existe porque a
+            // ferramenta falhou em 74 de 74 chamadas com o código como única
+            // entrada — quem pergunta tem uma sigla e uma data, não um inteiro
+            // interno. Ver src/tools/resolver-reuniao.ts.
+            let codigo = params.codigoReuniao;
+            if (codigo === undefined) {
+                const sigla = (params.sigla || "").toUpperCase();
+                if (!sigla) {
+                    return toolError("Informe `codigoReuniao`, ou `sigla` da comissão (com `data`, opcional). " +
+                        "Sem nenhum dos dois não há o que detalhar.", false);
+                }
+                const hoje = new Date();
+                const inicio = new Date(hoje);
+                inicio.setDate(inicio.getDate() - 14);
+                const di = params.data || formatDateYMD(inicio);
+                const df = params.data || formatDateYMD(hoje);
+                const agenda = await cachedFetchWithMeta("senado_reuniao_comissao_resolve", { sigla, di, df }, CACHE_DYNAMIC, () => upstreamFetch(`/comissao/agenda/${di}/${df}`, {}, baseUrl));
+                const candidatas = ensureArray(agenda.value?.AgendaReuniao?.reunioes?.reuniao)
+                    .filter((re) => (re.colegiadoCriador?.sigla || "").toUpperCase() === sigla)
+                    .map((re) => ({
+                    codigo: parseInt(re.codigo || "0"),
+                    descricao: re.descricao || re.titulo || "",
+                    data: re.dataInicio ? String(re.dataInicio).split("T")[0] : "",
+                    hora: re.dataInicio ? String(re.dataInicio).split("T")[1]?.slice(0, 5) || null : null,
+                }));
+                const escolha = escolherReuniao(candidatas, sigla, params.data ? di : `${di}–${df}`);
+                if (escolha.tipo !== "codigo")
+                    return toolError(escolha.mensagem, false);
+                codigo = escolha.codigo;
+            }
+            const reuniaoPath = `/comissao/reuniao/${codigo}`;
+            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_reuniao_comissao", { codigo }, CACHE_ON_DEMAND, () => upstreamFetch(reuniaoPath, {}, baseUrl));
             const re = response?.DetalheReuniao?.reuniao ?? response?.reuniao ?? response;
             const com = re.colegiadoCriador || {};
             const prov = provenanceFor("SENADO_LEGIS", baseUrl, reuniaoPath, {
-                dataset_id: `codigoReuniao=${params.codigoReuniao}`,
+                dataset_id: `codigoReuniao=${codigo}`,
                 reference_period: re.dataInicio ? String(re.dataInicio).split("T")[0] : undefined,
                 retrieved_at: fetchedAt,
             });
@@ -359,6 +401,13 @@ export function registerComissoesTools(server, baseUrl) {
             }, prov);
         }
         catch (e) {
+            // Corpo vazio neste endpoint é "não existe", não erro transitório. O
+            // upstreamFetch marca vazio como 502 retryable, o que vale para a
+            // maioria dos endpoints e mandava o agente repetir uma chamada que
+            // nunca ia funcionar.
+            if (ehReuniaoInexistente(e)) {
+                return toolError(mensagemCodigoInexistente(params.codigoReuniao ?? 0), false);
+            }
             return errorFrom(e, "Reunião de comissão não encontrada");
         }
     });

package/dist/tools/deep-research.js

@@ -38,6 +38,7 @@ 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 { RootNotFoundError } from "../utils/upstream-parse.js";
 import { fetchComissaoColegiado, parseComissaoItem, parseComissaoResumo } from "./comissoes.js";
 import { UFS } from "./referencia.js";
 export { DEEP_RESEARCH_TOOLS };
@@ -188,7 +189,22 @@ function handlers(baseUrl) {
             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);
+            // Desde 24/09/2026 `fetchSenadorDetalhe` LANÇA em código inexistente, em
+            // vez de devolver um registro montado de defaults. Aqui a ausência tem
+            // forma própria — `null`, que a fábrica do mcp-search traduz no
+            // "documento não encontrado" do contrato —, então a exceção vira null.
+            // O `!detalhe.codigo` continua como cinto: outro caminho de ausência que
+            // apareça não pode virar documento vazio.
+            let detalheSenador;
+            try {
+                detalheSenador = await fetchSenadorDetalhe(codigo, baseUrl);
+            }
+            catch (e) {
+                if (e instanceof RootNotFoundError)
+                    return null;
+                throw e;
+            }
+            const { path, fetchedAt, detalhe } = detalheSenador;
             if (!detalhe.codigo)
                 return null;
             const prov = provenanceFor("SENADO_LEGIS", baseUrl, path, {

package/dist/tools/materias.js

@@ -133,6 +133,21 @@ async function resolveProcesso(codigoMateria, baseUrl) {
     }
     return { item, fetchedAt };
 }
+/**
+ * Zero resultado por palavra-chave não é prova de que o tema não existe: a
+ * busca é REMOTA e casa contra as palavras-chave que o próprio Senado indexa,
+ * com tesauro dele. Medido na produção em 16/09/2026: "maconha" e "cannabis"
+ * acham as mesmas 6 matérias (o tesauro cobre), mas "remédio" acha 0 contra 16
+ * de "medicamento" e "carro" acha 5 contra 151 de "veículo". Como o casamento
+ * é da fonte, o conserto local é dizer o que fazer em seguida — não uma tabela
+ * de tradução, que aqui só repetiria o tesauro do Senado.
+ */
+export function dicaBuscaVazia(palavraChave) {
+    return (`Nenhuma matéria indexada com a palavra-chave "${palavraChave}". A busca casa contra as palavras-chave ` +
+        "que o Senado atribui a cada processo, no vocabulário dele: tente o termo técnico ou mais geral " +
+        "(medicamento, não remédio; veículo, não carro), o singular, um sinônimo, " +
+        "ou combine com `ano`/`sigla` em vez da palavra-chave.");
+}
 export function registerMateriasTools(server, baseUrl) {
     // B1. senado_buscar_materias
     server.tool("senado_buscar_materias", "Busca matérias legislativas por tipo (PEC, PL, PLP, MPV), número, ano, palavras-chave, autor, período de apresentação ou situação de tramitação; informe ao menos um critério. Para pedidos como 'matérias recentes sobre X', use `palavraChave`, `ano` ou `dataInicioApresentacao`/`dataFimApresentacao`, `ordenarPor: 'dataApresentacao'`, `ordem: 'desc'` e `limite` baixo (ex: 10); não é necessário chamar detalhes para listar resultados. Retorna `{ count, total, materias[] }`, cada item com `codigo` (codigoMateria), `sigla`, `numero`, `ano`, `ementa`, `autor`, `situacao`, `dataApresentacao`, `url` e `tramitando`. Use `codigo` em `senado_obter_materia` apenas quando o usuário pedir detalhe/tramitação/textos. `limite` padrão 100 (máx. 500); ao truncar inclui `aviso`. Ex.: `{ palavraChave: 'inteligência artificial', ano: 2025, limite: 10 }` ou `{ sigla: 'PEC', numero: 45, ano: 2019 }` (datas em YYYYMMDD ou ISO).", {
@@ -186,6 +201,8 @@ export function registerMateriasTools(server, baseUrl) {
                 count: materias.length,
                 total: todos.length,
                 ...(todos.length > limite ? { aviso: `Exibindo ${limite} de ${todos.length} resultados. Refine a busca ou aumente o limite.` } : {}),
+                // Zero calado é beco sem saída (ver dicaBuscaVazia).
+                ...(todos.length === 0 && params.palavraChave ? { dica: dicaBuscaVazia(params.palavraChave) } : {}),
                 materias,
             }, prov);
         }

package/dist/tools/resolver-reuniao.js

@@ -0,0 +1,64 @@
+/**
+ * Resolve o `codigoReuniao` a partir do que uma PESSOA tem na mão.
+ *
+ * Por quê. Em 10/09/2026 o painel apontou `senado_reuniao_comissao` com **74
+ * erros em 74 chamadas** — nunca funcionou para ninguém. A telemetria de forma
+ * (blob7/blob8) mostrou o motivo: `classe=nao_encontrado`,
+ * `parametros=codigoReuniao`. Ou seja, o agente chama com o parâmetro CERTO e
+ * um valor que não existe. Não é erro de seleção de ferramenta, que era a
+ * primeira hipótese — erro de validação de esquema nem chega à instrumentação,
+ * o SDK o responde antes do callback.
+ *
+ * A causa é de contrato: o único jeito de entrar na ferramenta era um inteiro
+ * interno que ninguém tem sem antes chamar OUTRA ferramenta. Quem pergunta
+ * "o que a CAE decidiu na reunião do dia 1º?" tem uma sigla e uma data.
+ *
+ * Este módulo não substitui `senado_reunioes_comissao`: essa continua sendo a
+ * ferramenta de LISTAR, e a pergunta "quais reuniões houve" é legítima por si.
+ * Aqui a listagem é só o caminho interno para achar UM código.
+ */
+/**
+ * Escolhe UMA reunião da lista. Devolve erro com as candidatas quando há mais
+ * de uma, em vez de devolver a lista no lugar do detalhe: a ferramenta de
+ * detalhe tem uma forma de resposta só, e trocá-la pela forma de lista quando
+ * a busca é ambígua é o tipo de resposta polimórfica que o modelo consome mal.
+ */
+export function escolherReuniao(reunioes, sigla, periodo) {
+    if (reunioes.length === 0) {
+        return {
+            tipo: "nenhuma",
+            mensagem: `Nenhuma reunião da comissão ${sigla} em ${periodo}. Confira a sigla com ` +
+                `senado_listar_comissoes ou amplie o período com senado_reunioes_comissao.`,
+        };
+    }
+    if (reunioes.length === 1)
+        return { tipo: "codigo", codigo: reunioes[0].codigo };
+    const lista = reunioes
+        .slice(0, 10)
+        .map((r) => `${r.codigo} (${r.data}${r.hora ? " " + r.hora : ""}, ${r.descricao})`)
+        .join("; ");
+    return {
+        tipo: "ambigua",
+        mensagem: `${reunioes.length} reuniões da comissão ${sigla} em ${periodo}. Repita informando ` +
+            `codigoReuniao com uma destas: ${lista}${reunioes.length > 10 ? "; …" : ""}`,
+    };
+}
+/**
+ * A resposta vazia do upstream em `/comissao/reuniao/{codigo}` NÃO é erro
+ * transitório: é "não existe reunião com esse código". O `upstreamFetch` marca
+ * corpo vazio como 502 retryable, o que é certo para a maioria dos endpoints e
+ * errado para este — e mandava o agente repetir uma chamada que nunca ia
+ * funcionar, gastando a vez dele. Esta função reconhece o caso.
+ */
+export function ehReuniaoInexistente(e) {
+    const m = e instanceof Error ? e.message : String(e);
+    return /\/comissao\/reuniao\/\d+/.test(m) && /vazia|não é JSON|nao e JSON/i.test(m);
+}
+/** A mensagem que o agente recebe quando o código não existe. */
+export function mensagemCodigoInexistente(codigo) {
+    return (`Não existe reunião com o código ${codigo}. Esse código é interno e não é ` +
+        `dedutível: pegue-o em senado_reunioes_comissao (por sigla e período) ou em ` +
+        `senado_agenda_comissoes (por data) — ou chame esta mesma ferramenta com ` +
+        `sigla e data, que ela resolve o código sozinha. Repetir a chamada com o ` +
+        `mesmo código não vai funcionar.`);
+}

package/dist/tools/senadores.js

@@ -10,8 +10,8 @@ import { z } from "zod";
 import { cachedFetchWithMeta } from "../cache/manager.js";
 import { upstreamFetch } from "../throttle/upstream.js";
 import { errorFrom, ensureArray, normalizeText, safeInt } from "../utils/validation.js";
-import { digArrayRoot } from "../utils/upstream-parse.js";
-import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { digArrayRoot, digObjectRoot } from "../utils/upstream-parse.js";
+import { provenanceFor, resultWithProvenance, toBrasiliaIso } from "../utils/provenance.js";
 import { CACHE_SEMI_STATIC, CACHE_DYNAMIC, CACHE_ON_DEMAND } from "../types.js";
 export function parseSenadorResumo(parlamentar) {
     const id = parlamentar.IdentificacaoParlamentar || parlamentar;
@@ -42,6 +42,37 @@ export function matchesPartido(sigla, filtro) {
     const shorter = Math.min(sp.length, p.length);
     return shorter >= 4 && (sp.startsWith(p) || p.startsWith(sp));
 }
+/**
+ * `emExercicio` derivado do DADO, nunca afirmado. Regra: está em exercício quem
+ * tem um `Exercicio` já iniciado e ainda não encerrado — suplente que assumiu a
+ * vaga tem exercício aberto (`DataFim` ausente); titular licenciado tem todos
+ * fechados.
+ *
+ * MEDIDA em 24/09/2026 contra as duas listas oficiais (`/senador/lista/atual`,
+ * 81 senadores, e `/senador/afastados`, 42): 123 de 123 acertos, sem exceção.
+ *
+ * Devolve `null` — não `false` — quando não há exercício nenhum para ler
+ * (sub-endpoint `/mandatos` indisponível, ou mandato sem `Exercicios`): campo
+ * que não se sabe não pode sair afirmado, e `false` afirmaria "não está em
+ * exercício". As datas do upstream são ISO `AAAA-MM-DD`, então a comparação
+ * lexicográfica é a cronológica; `hoje` vem do chamador (fuso de Brasília)
+ * para a função continuar pura e testável.
+ */
+export function derivarEmExercicio(mandatos, hoje) {
+    let algumExercicio = false;
+    for (const m of mandatos) {
+        for (const e of ensureArray(m?.Exercicios?.Exercicio)) {
+            const inicio = e?.DataInicio;
+            if (!inicio)
+                continue;
+            algumExercicio = true;
+            const fim = e?.DataFim;
+            if (inicio <= hoje && (!fim || fim >= hoje))
+                return true;
+        }
+    }
+    return algumExercicio ? false : null;
+}
 export function parseSenadorDetalhe(dados) {
     const p = dados.Parlamentar || dados;
     const id = p.IdentificacaoParlamentar || {};
@@ -59,7 +90,15 @@ export function parseSenadorDetalhe(dados) {
         uf: id.UfParlamentar || "",
         foto: id.UrlFotoParlamentar || null,
         email: id.EmailParlamentar || null,
-        emExercicio: true,
+        // O detalhe `/senador/{codigo}` NÃO carrega exercício nenhum — medido em
+        // 24/09/2026: traz só IdentificacaoParlamentar, DadosBasicosParlamentar e
+        // OutrasInformacoes. Até 24/09 este campo saía `true` fixo, e o servidor se
+        // contradizia sobre gente real (o código 6358 saía `emExercicio: true` aqui
+        // e `false` em `senado_senadores_afastados`). Quem sabe a verdade é o
+        // sub-endpoint `/mandatos`: `fetchSenadorDetalhe` sobrescreve este valor com
+        // `derivarEmExercicio`. `null` é o default honesto para quem chamar o parser
+        // sozinho, sem os mandatos em mãos.
+        emExercicio: null,
         mandatos: ensureArray(p.Mandatos?.Mandato).map((m) => ({
             legislatura: parseInt(m.PrimeiraLegislaturaDoMandato?.NumeroLegislatura || "0"),
             uf: m.UfParlamentar || "",
@@ -164,20 +203,41 @@ export function matchesNome(s, nome) {
 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;
+    // Ausência com HTTP 200: para um código que não existe o upstream devolve
+    // `{"DetalheParlamentar":{...Metadados}}` — envelope e metadados presentes,
+    // SEM o nó `Parlamentar` (medido em 24/09/2026: 200, 304 bytes). O
+    // `?? response` que havia aqui deixava o parser montar um registro inteiro a
+    // partir de nada (`codigo: 0`, `nome: ""`), e quem perguntava recebia uma
+    // afirmação falsa. `digObjectRoot` é a defesa na BORDA: num detalhe por
+    // identificador único, nó ausente é ausência, nunca "vazio legítimo".
+    const dados = digObjectRoot(response, [
+        ["DetalheParlamentar", "Parlamentar"],
+        ["Parlamentar"],
+    ], "senado_obter_senador", { notFoundMessage: `Senador com código ${codigoSenador} não encontrado.` });
     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 = [];
+    // É também o único endpoint que carrega os `Exercicios`, de onde sai o
+    // `emExercicio` — lista vazia (falha do sub-endpoint) vira `null`, não `false`.
+    let mandatosBrutos = [];
     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);
+        mandatosBrutos = digArrayRoot(mResp, [["MandatoParlamentar", "Parlamentar", "Mandatos", "Mandato"]], "senado_obter_senador:mandatos");
     }
     catch {
         // sub-endpoint unavailable — keep the (empty) mandatos from the detail
     }
-    return { path, fetchedAt, detalhe: { ...detalhe, mandatos } };
+    const hoje = toBrasiliaIso(new Date()).slice(0, 10);
+    return {
+        path,
+        fetchedAt,
+        detalhe: {
+            ...detalhe,
+            emExercicio: derivarEmExercicio(mandatosBrutos, hoje),
+            mandatos: mandatosBrutos.map(parseMandato),
+        },
+    };
 }
 export function registerSenadoresTools(server, baseUrl) {
     // A1. senado_listar_senadores (filtro `nome` substitui a antiga busca por nome)
@@ -215,7 +275,7 @@ export function registerSenadoresTools(server, baseUrl) {
         }
     });
     // A2. senado_obter_senador
-    server.tool("senado_obter_senador", "Obtém o detalhe biográfico de um senador específico. Retorna um objeto com `codigo`, `nome`, `nomeCompleto`, `nomeCivil`, `sexo`, `dataNascimento`, `naturalidade`/`ufNaturalidade`, `partido`, `uf`, `foto`, `email` e a lista `mandatos` (`legislatura`, `uf`, `participacao`, `dataInicio`, `dataFim`). Requer `codigoSenador` — obtenha-o via `senado_listar_senadores` (filtro `nome`). Para filiações, profissões, licenças, comissões ou cargos use `senado_senador_historico` (parâmetro `tipo`).", {
+    server.tool("senado_obter_senador", "Obtém o detalhe biográfico de um senador específico. Retorna um objeto com `codigo`, `nome`, `nomeCompleto`, `nomeCivil`, `sexo`, `dataNascimento`, `naturalidade`/`ufNaturalidade`, `partido`, `uf`, `foto`, `email`, `emExercicio` e a lista `mandatos` (`legislatura`, `uf`, `participacao`, `dataInicio`, `dataFim`). `emExercicio` é derivado dos exercícios do mandato (aberto = em exercício) e vem `null` — nunca afirmado — quando os mandatos não puderam ser lidos. Código inexistente retorna erro (\"Senador com código N não encontrado\"), nunca um registro vazio. Requer `codigoSenador` — obtenha-o via `senado_listar_senadores` (filtro `nome`). Para filiações, profissões, licenças, comissões ou cargos use `senado_senador_historico` (parâmetro `tipo`).", {
         codigoSenador: z.number().int().positive().describe("Código único do senador no sistema do Senado"),
     }, async (params) => {
         try {

package/dist/utils/estatisticas.js

@@ -54,12 +54,9 @@ export function computarEstatisticas(registros, valorDe, opcoes = {}) {
         grupos: g.groups.map(({ group, ...s }) => ({ grupo: group, ...paraPtBR(s) })),
     };
 }
-// ─── Display layer ───────────────────────────────────────────────────────────
-// Shared by all five statistics tools so the wording stays identical across the
-// whole surface: 2-decimal money rounding + the package's labeled percentile list
-// (pt-BR locale), so the model never surfaces internal shorthand ("p99").
-/** 2-decimal money rounding (all statistics fields are monetary — BRL). */
-const r2 = (n) => Math.round(n * 100) / 100;
+function r2(n) {
+    return n === null ? null : Math.round(n * 100) / 100;
+}
 /**
  * Format a number as pt-BR currency deterministically ("R$ 1.234,56") — no
  * `Intl` dependency, so tests are stable and it never depends on the runtime's
@@ -79,6 +76,26 @@ export function rotularPercentis(p, formatarValor = formatarBRL) {
  * self-documenting labeled list (not bare p25..p99 keys).
  */
 export function arredondarEstatisticas(e, formatarValor = formatarBRL) {
+    // SEM REGISTRO NENHUM não existe distribuição, e o bloco não é emitido.
+    //
+    // Defeito medido em produção em 14/09/2026:
+    // `senado_ceaps({ano: 2024, estatisticas: true, nomeSenador: "ZZQX
+    // INEXISTENTE"})` — ano válido, filtro que não casa nada — respondia a
+    // distribuição inteira em zero e, pior, NARRADA por extenso pela lista de
+    // percentis: "mediana — metade dos valores é igual ou inferior a R$ 0,00",
+    // "99% dos valores são iguais ou inferiores a R$ 0,00", com bloco de
+    // proveniência completo. Um modelo que lê isso afirma ao leitor que a
+    // despesa mediana foi R$ 0,00 — afirmação sobre o mundo, saída de uma
+    // consulta vazia, com aparência de dado oficial.
+    //
+    // Trocar a FORMA, e não só zerar os campos, é deliberado: uma fileira de
+    // nulos ainda convida quem lê a tratá-los como dado, e o aviso NEGA a
+    // leitura errada ("não significa que os valores sejam zero"). Mesma decisão
+    // do `formatStats` do motor comum, repetida aqui porque este módulo mantém a
+    // própria camada de exibição.
+    if (e.n === 0) {
+        return { n: 0, aviso: ptBR.noRecordsNotice() };
+    }
     return {
         n: e.n,
         soma: r2(e.soma),

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.7.0";
+export const VERSION = "3.9.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.7.0",
+  "version": "3.9.0",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "license": "MIT",
   "type": "module",
@@ -48,23 +48,24 @@
     "release:zenodo": "tsx scripts/build-dataset/zenodo-publish.ts"
   },
   "dependencies": {
-    "@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",
+    "@sbissoli/mcp-search": "^0.5.0",
+    "@sbissoli/mcp-stats": "^0.3.0",
     "zod": "^4.5.4"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20260830.1",
     "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@sbissoli/mcp-evals": "^0.1.0",
-    "@types/node": "^26.4.0",
-    "agents": "^0.22.0",
+    "@types/node": "^26.5.1",
+    "agents": "^0.23.0",
     "exceljs": "^4.4.0",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
+    "vite": "^8.2.2",
+    "vitest": "^5.0.0",
     "wrangler": "^4.127.1"
   },
   "overrides": {
@@ -73,7 +74,7 @@
     "@hono/node-server": "^1.19.13",
     "express-rate-limit": "^8.5.2",
     "ip-address": "^10.2.0",
-    "qs": "^6.15.3",
+    "qs": "^6.16.0",
     "path-to-regexp": "^8.4.2",
     "lodash": "^4.18.1",
     "js-yaml": "^4.2.0",
@@ -81,6 +82,7 @@
     "ws": "^8.21.0",
     "picomatch": "^4.0.4",
     "postcss": "^8.5.10",
-    "uuid": "^11.1.1"
+    "uuid": "^11.1.1",
+    "sharp": "^0.35.4"
   }
 }