senado-br-mcp 3.10.0 → 3.12.0

package/README.md

@@ -8,6 +8,7 @@
 [![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-senado-br-mcp-cloudflare)](https://lobehub.com/mcp/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)
+[![smithery badge](https://smithery.ai/badge/sidneybissoli/senado-br-mcp-cloudflare)](https://smithery.ai/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)
 [![License: MIT](https://img.shields.io/github/license/SidneyBissoli/senado-br-mcp-cloudflare)](LICENSE)
@@ -153,7 +154,7 @@ Claude Code auto-discovers it when you work in this repo. To use it elsewhere, c
 - **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))
 - **Rate limiting:** Token bucket — global (8 req/s) + per-client (2 req/s)
-- **Upstream throttle:** Max 6 concurrent requests, 10s timeout, retry with exponential backoff
+- **Upstream throttle:** Max 6 concurrent requests, 10s budget per trip, retry on 429/5xx/network with exponential backoff and `Retry-After` (portfolio shared fetch `@sbissoli/mcp-upstream`); every response's provenance carries the measured `retrieval` diagnostics (trips, attempts, anomalies)
 - **Auth:** Optional Bearer token (set the `API_KEY` secret; open access when unset). Constant-time comparison.
 - **Observability:** Structured JSON logging + in-memory counters at `/metrics`; per-tool call telemetry (selection, error rate, cache-vs-live) in Cloudflare Analytics Engine, PII-free
 - **Liveness:** Runs on Cloudflare's own global network behind a custom domain — no third-party host that can go dark. Public `/health` and `/status` (version + last-deploy id/timestamp) make uptime and the current build verifiable; the **status** badge above pings the live endpoint

package/dist/call-shape.js

@@ -171,8 +171,70 @@ export function classifyThrown(error) {
         error instanceof SyntaxError) {
         return "defeito";
     }
+    const declarada = classeDeclarada(error);
+    if (declarada)
+        return declarada;
     return classifyError(error instanceof Error ? error.message : String(error));
 }
+const CLASSES = new Set(["contrato", "nao_encontrado", "fonte", "defeito", "outro"]);
+function ehClasse(x) {
+    return typeof x === "string" && CLASSES.has(x);
+}
+/**
+ * A classe com que o erro NASCEU (`UpstreamError.classe`, o erro do
+ * e-Cidadania), ou `undefined` quando ele não declara nenhuma — aí vale a
+ * frase, como sempre.
+ */
+export function classeDeclarada(error) {
+    const c = error?.classe;
+    return ehClasse(c) ? c : undefined;
+}
+/**
+ * Onde um resultado de erro leva a classe decidida pelo TIPO da exceção.
+ *
+ * Por que existe. Medido em 30/09/2026, rodando este classificador sobre as
+ * mensagens de falha da origem: "Erro de rede: ..." (base legislativa), o 429
+ * do nosso próprio balde ("Taxa de requisições excedida") e, no e-Cidadania,
+ * "falha de rede ao acessar" e "retornou HTTP 429/400/403" caíam em `outro`.
+ * O tipo da falha existia no `catch` e só o texto chegava ao `instrumentTool`.
+ *
+ * O mesmo defeito de fundo foi consertado no bcb-br-mcp (#45), no
+ * ilo-mcp-server (#24), no uis-mcp-server (#22), no ibge-br-mcp (#62) e no
+ * medical-terminologies-mcp (#58). O conserto não reescreve frase nem mexe em
+ * regex: a classe viaja AO LADO do texto, nesta chave-símbolo não enumerável,
+ * que o `JSON.stringify` não vê — o que o cliente recebe não muda.
+ * `instrumentTool` a lê antes de cair na frase.
+ */
+export const CLASSE_DO_ERRO = Symbol.for("br.com.sidneybissoli.mcp/classe-do-erro");
+/** A classe anexada a um resultado de erro, ou `undefined` quando não há. */
+export function classeAnexada(result) {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const c = result[CLASSE_DO_ERRO];
+    return ehClasse(c) ? c : undefined;
+}
+/**
+ * Anexa ao resultado, fora do fio, a classe que o erro declara — ou `defeito`,
+ * quando é bug nosso (`TypeError` & cia., como em `classifyThrown`). Devolve o
+ * próprio resultado.
+ *
+ * Medido em 30/09/2026 na varredura da frota: os ~60 `catch` que passam por
+ * `errorFrom` engolem a exceção antes do hook, e um "Cannot read properties of
+ * undefined" saía `outro`. A falha de rede crua da undici também é `TypeError`
+ * ("fetch failed"); toda ida passa por throttle/upstream.ts, que a tipa — a
+ * exclusão é guarda, para uma ida crua futura não virar `defeito`.
+ */
+export function anexarClasse(result, error) {
+    const classe = classeDeclarada(error) ?? (ehBugNosso(error) ? "defeito" : undefined);
+    if (classe !== undefined)
+        Object.defineProperty(result, CLASSE_DO_ERRO, { value: classe, enumerable: false });
+    return result;
+}
+function ehBugNosso(error) {
+    if (error instanceof TypeError)
+        return error.message !== "fetch failed";
+    return error instanceof RangeError || error instanceof ReferenceError || error instanceof SyntaxError;
+}
 /**
  * Classe de um erro JSON-RPC do PROTOCOLO, pelo código antes da mensagem.
  *

package/dist/data/estrutura-organizacional.js

@@ -1,7 +1,7 @@
 export const ESTRUTURA_ORGANIZACIONAL = {
-    "extraidoEm": "2026-09-01T10:56:16.383Z",
+    "extraidoEm": "2026-10-01T12:13:07.708Z",
     "fonteUrl": "https://www12.senado.leg.br/institucional/estrutura/orgaosenado",
-    "total": 823,
+    "total": 821,
     "orgaos": [
         {
             "cod": -2072346465,
@@ -3129,12 +3129,6 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "nome": "Escritório de Apoio Nº 01 do Senador Chico Rodrigues",
             "codSuperior": 10057
         },
-        {
-            "cod": 10156,
-            "sigla": null,
-            "nome": "Escritório de Apoio Nº 01 do Senador Angelo Coronel",
-            "codSuperior": 10046
-        },
         {
             "cod": 10157,
             "sigla": null,
@@ -4631,7 +4625,7 @@ export const ESTRUTURA_ORGANIZACIONAL = {
         },
         {
             "cod": 10749,
-            "sigla": null,
+            "sigla": "CSADVOSF",
             "nome": "Conselho Superior da Advocacia do Senado Federal",
             "codSuperior": 67
         },
@@ -4887,18 +4881,6 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "nome": "Gabinete da Liderança do Avante",
             "codSuperior": 109
         },
-        {
-            "cod": 10847,
-            "sigla": "GSHKLANN",
-            "nome": "Gabinete do Senador Hermes Klann",
-            "codSuperior": 108
-        },
-        {
-            "cod": 10850,
-            "sigla": null,
-            "nome": "Escritório de Apoio Nº 01 do Senador Hermes Klann",
-            "codSuperior": 10847
-        },
         {
             "cod": 10857,
             "sigla": null,
@@ -4940,6 +4922,12 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "sigla": null,
             "nome": "Escritório de Apoio Nº 01 do Senador Sargento Reginauro",
             "codSuperior": 10862
+        },
+        {
+            "cod": 10866,
+            "sigla": "GSRBRAZ",
+            "nome": "Gabinete do Senador Renzo Braz",
+            "codSuperior": 108
         }
     ]
 };

package/dist/instrument.js

@@ -29,9 +29,10 @@
  * (SELF_HEADER, value = the SELF_MARKER Wrangler secret).
  */
 import { resolveDesfecho } from "./envelope.js";
-import { classifyError, classifyThrown, errorText, paramNames } from "./call-shape.js";
+import { classeAnexada, classifyError, classifyThrown, errorText, paramNames } from "./call-shape.js";
 import { incr, incrTool } from "./metrics.js";
 import { callCache, cacheClass } from "./observability/call-context.js";
+import { withUpstreamCall } from "./throttle/upstream.js";
 /** Header the owner's MCP clients send (value = the SELF_MARKER secret). */
 export const SELF_HEADER = "x-mcp-self";
 /**
@@ -71,11 +72,18 @@ export function instrumentTool(name, cb, analytics, tag, gravados) {
         // 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));
+            // Dois contextos por chamada, aninhados: o coletor de REDE do fetch comum
+            // (idas, tentativas, anomalias → `retrieval` da proveniência; ver
+            // src/throttle/upstream.ts) e o acumulador de CACHE (acertos → blob3).
+            // Este é o único lugar em que uma chamada de tool começa — stdio e Worker
+            // passam pelo mesmo funil (`host.tool` em src/server.ts).
+            const result = await withUpstreamCall(() => callCache.run(stats, () => Promise.resolve(cb(...args))));
             isError =
                 typeof result === "object" && result !== null && result.isError === true;
+            // A classe que o handler anexou pelo TIPO do erro vence a frase; a frase
+            // fica para o erro que nasceu sem tipo. Ver CLASSE_DO_ERRO.
             if (isError)
-                classe = classifyError(errorText(result));
+                classe = classeAnexada(result) ?? classifyError(errorText(result));
             return result;
         }
         catch (e) {

package/dist/scraper/ecidadania.js

@@ -9,8 +9,10 @@
  * Everything here is pure parsing + fetch, with no MCP/tool/cache dependency, so it can be
  * driven by the Cron pipeline (step 3) and covered by fixture-based contract tests.
  */
+import { UpstreamError as PkgUpstreamError } from "@sbissoli/mcp-upstream";
 import { UPSTREAM_TIMEOUT_MS } from "../types.js";
 import { USER_AGENT } from "../version.js";
+import { upstreamCall } from "../throttle/upstream.js";
 export const ECIDADANIA_BASE = "https://www12.senado.leg.br/ecidadania";
 /**
  * Error carrying a `retryable` flag, mirroring UpstreamError so the tool layer
@@ -18,8 +20,14 @@ export const ECIDADANIA_BASE = "https://www12.senado.leg.br/ecidadania";
  * (not `upstreamFetch`), so transient conditions are classified here: 5xx / 429 /
  * timeout / network → retryable; 4xx → not.
  */
-function ecidadaniaFetchError(message, retryable) {
-    return Object.assign(new Error(message), { retryable });
+/**
+ * `classe`, quando dada, é a classe de telemetria decidida pelo TIPO da falha
+ * (ver `CLASSE_DO_ERRO` em src/call-shape.ts). Medido em 30/09/2026: pela
+ * frase, "falha de rede ao acessar" e "retornou HTTP 429/400/403" caíam em
+ * `outro`. Sem ela, vale a frase, como sempre.
+ */
+function ecidadaniaFetchError(message, retryable, classe) {
+    return Object.assign(new Error(message), classe ? { retryable, classe } : { retryable });
 }
 const isTransientStatus = (status) => status >= 500 || status === 429;
 /**
@@ -28,78 +36,69 @@ const isTransientStatus = (status) => status >= 500 || status === 429;
  * (`X-Requested-With: XMLHttpRequest`, wider `Accept`).
  */
 export async function fetchPage(path, opts = {}) {
-    const url = `${ECIDADANIA_BASE}${path}`;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), UPSTREAM_TIMEOUT_MS);
-    try {
-        const resp = await fetch(url, {
-            headers: opts.ajax
-                ? { Accept: "text/html,*/*", "User-Agent": USER_AGENT, "X-Requested-With": "XMLHttpRequest" }
-                : { Accept: "text/html", "User-Agent": USER_AGENT },
-            signal: controller.signal,
-        });
-        clearTimeout(timeout);
-        if (!resp.ok) {
-            throw ecidadaniaFetchError(`e-Cidadania retornou HTTP ${resp.status} para ${path}`, isTransientStatus(resp.status));
-        }
-        const text = await resp.text();
-        // AJAX comment fragments are legitimately empty for events with zero comments — allowEmpty
-        // lets the caller treat "" as a valid (empty) result instead of a transient failure.
-        if (!opts.allowEmpty && !text.trim()) {
-            throw ecidadaniaFetchError(`e-Cidadania retornou página vazia para ${path}`, true);
-        }
-        return text;
-    }
-    catch (e) {
-        clearTimeout(timeout);
-        if (e.name === "AbortError") {
-            throw ecidadaniaFetchError(`e-Cidadania: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`, true);
-        }
-        if (e instanceof Error && "retryable" in e)
-            throw e; // already classified above
-        throw ecidadaniaFetchError(`e-Cidadania: falha de rede ao acessar ${path} (${e.message})`, true);
+    const resp = await idaEcidadania(path, opts.ajax
+        ? { Accept: "text/html,*/*", "User-Agent": USER_AGENT, "X-Requested-With": "XMLHttpRequest" }
+        : { Accept: "text/html", "User-Agent": USER_AGENT }, "e-Cidadania");
+    const text = await resp.text();
+    // AJAX comment fragments are legitimately empty for events with zero comments — allowEmpty
+    // lets the caller treat "" as a valid (empty) result instead of a transient failure.
+    if (!opts.allowEmpty && !text.trim()) {
+        throw ecidadaniaFetchError(`e-Cidadania retornou página vazia para ${path}`, true);
     }
+    return text;
 }
 /**
  * Fetch JSON from an e-Cidadania REST endpoint with validation.
  * Ensures the response is valid JSON and an array.
  */
 export async function fetchEcidadaniaJson(endpoint) {
-    const url = `${ECIDADANIA_BASE}${endpoint}`;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), UPSTREAM_TIMEOUT_MS);
+    const resp = await idaEcidadania(endpoint, { Accept: "application/json", "User-Agent": USER_AGENT }, "e-Cidadania REST API");
+    let data;
     try {
-        const resp = await fetch(url, {
-            headers: { Accept: "application/json", "User-Agent": USER_AGENT },
-            signal: controller.signal,
-        });
-        clearTimeout(timeout);
-        if (!resp.ok) {
-            throw ecidadaniaFetchError(`e-Cidadania REST API retornou HTTP ${resp.status} para ${endpoint}`, isTransientStatus(resp.status));
-        }
-        let data;
-        try {
-            data = await resp.json();
-        }
-        catch {
-            throw ecidadaniaFetchError(`e-Cidadania REST API retornou JSON inválido para ${endpoint}`, true);
-        }
-        if (!Array.isArray(data)) {
-            // API returned an object or other non-array — wrap or return empty
-            if (data && typeof data === "object")
-                return [data];
-            return [];
-        }
-        return data;
+        data = await resp.json();
+    }
+    catch {
+        throw ecidadaniaFetchError(`e-Cidadania REST API retornou JSON inválido para ${endpoint}`, true);
+    }
+    if (!Array.isArray(data)) {
+        // API returned an object or other non-array — wrap or return empty
+        if (data && typeof data === "object")
+            return [data];
+        return [];
+    }
+    return data;
+}
+/**
+ * A ida ao portal, pelo fetch comum do portfólio (desde a 3.11.0; antes um
+ * `fetch` cru com timeout de 10 s e sem retry). Mesma política da API do Senado
+ * (`upstreamSenado`: teto 10 s, 5xx/429/rede repetem, timeout não) e mesmo
+ * coletor da chamada de tool — o detalhe raspado ao vivo entra no `retrieval`
+ * do bloco e-Cidadania. No cron (`scheduled`, fora de uma chamada) o coletor é
+ * descartável e a política vale igual. O token bucket NÃO se aplica: é outro
+ * host, e o portal nunca passou por ele. As mensagens e o `retryable` são os
+ * de antes — `ecidadaniaError` (tools) e o pipeline os leem.
+ */
+async function idaEcidadania(path, headers, rotulo) {
+    const url = `${ECIDADANIA_BASE}${path}`;
+    try {
+        return await upstreamCall().response(url, { headers });
     }
     catch (e) {
-        clearTimeout(timeout);
-        if (e.name === "AbortError") {
-            throw ecidadaniaFetchError(`e-Cidadania REST API: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${endpoint}`, true);
+        if (!(e instanceof PkgUpstreamError))
+            throw e;
+        switch (e.kind) {
+            case "timeout":
+            case "aborted":
+                throw ecidadaniaFetchError(`${rotulo}: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`, true, "fonte");
+            case "network": {
+                const causa = e.cause instanceof Error ? e.cause.message : String(e.cause ?? "desconhecido");
+                throw ecidadaniaFetchError(`${rotulo}: falha de rede ao acessar ${path} (${causa})`, true, "fonte");
+            }
+            default: {
+                const status = e.status ?? 502;
+                throw ecidadaniaFetchError(`${rotulo} retornou HTTP ${status} para ${path}`, isTransientStatus(status), status === 404 ? "nao_encontrado" : "fonte");
+            }
         }
-        if (e instanceof Error && "retryable" in e)
-            throw e; // already classified above
-        throw ecidadaniaFetchError(`e-Cidadania REST API: falha de rede ao acessar ${endpoint} (${e.message})`, true);
     }
 }
 /** Parse Brazilian number: 1.234.567 -> 1234567 */

package/dist/server.js

@@ -50,14 +50,14 @@ import { announceServedVersions } from "./discover.js";
  * `.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.
+ * Vale para TODAS, `search` e `fetch` inclusive. Até a 3.11.0 as duas ficavam
+ * abertas por serem contrato da OpenAI; desde o `@sbissoli/mcp-search` 0.9.0
+ * o próprio contrato do portfólio é estrito (`z.strictObject`), e as duas
+ * entram por este funil (registerDeepResearchToolsSenado passa a shape) —
+ * sem o `.strict()` aqui, a estrição do pacote se perderia na passagem.
  */
-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();
+function esquemaDeEntrada(shape) {
+    return z.object(shape).strict();
 }
 export function createServer(env, ctx, options = {}) {
     const toolProfile = options.toolProfile ?? "full";
@@ -102,7 +102,7 @@ export function createServer(env, ctx, options = {}) {
         return registerTool(name, {
             title: titleForTool(name),
             description,
-            inputSchema: esquemaDeEntrada(name, shape),
+            inputSchema: esquemaDeEntrada(shape),
             outputSchema: outputSchema,
             annotations: {
                 title: titleForTool(name),