senado-br-mcp 3.21.0 → 3.22.0

package/dist/dataset/schema.js

@@ -114,16 +114,16 @@ const consultasSchema = {
             sourceEndpoint: EP_CONSULTAS_DETALHE,
             sourceField: "página de detalhe: <b>Autoria:</b> <span>…</span>",
             operationalization: "Lido da página de detalhe (visualizacaomateria) no crawl enriquecido; null quando o detalhe não expõe. Nome MANTIDO (informação pública por função — ver postura de privacidade).",
-            caveat: "Detail-only (v2): populado pelo crawl de detalhe; null nas linhas ainda não enriquecidas.",
+            caveat: "Detail-only (v2): populado pelo crawl de detalhe; null nas linhas ainda não enriquecidas. Até a 3.21.0 o crawl só preencheu as ~3,4 mil consultas do primeiro lote: as demais ficaram null com a autoria publicada na página e são relidas desde então, até o teto por execução.",
         },
         {
             name: "relator",
             type: "string",
-            description: "Relator(a) da matéria (agente público).",
+            description: "Relator(a) da matéria (agente público). Sempre null: a página da consulta não publica relatoria.",
             sourceEndpoint: EP_CONSULTAS_DETALHE,
-            sourceField: "página de detalhe: <b>Relator(a):</b> <span>…</span>",
-            operationalization: "Lido da página de detalhe (visualizacaomateria); null quando não há relatoria ou o detalhe não a expõe. Nome MANTIDO (público por função).",
-            caveat: "Detail-only (v2): populado pelo crawl de detalhe; null nas linhas ainda não enriquecidas.",
+            sourceField: "página de detalhe: <b>Relator(a):</b> <span>…</span> (rótulo que a página não traz)",
+            operationalization: "O leitor procura o rótulo Relator(a) na página de detalhe (visualizacaomateria), mas a página publica só Autoria e Ementa: 0 de 8.145 consultas e 0 de 40.548 versões do histórico tiveram valor, e 42 páginas reais de anos e situações diferentes (medição de 18/10/2026) não traziam o rótulo. O relator da matéria está na API legislativa (/processo/relatoria), fora deste corpus.",
+            caveat: "Campo mantido por compatibilidade do formato; não use como dado. Vazio não significa matéria sem relator.",
         },
         {
             name: "status",

package/dist/throttle/upstream.js

@@ -16,7 +16,7 @@
  * semântica deste servidor, medida contra a fonte). O pacote CLASSIFICA; este
  * módulo DECIDE. A classe `UpstreamError` local, as mensagens e o `transport`
  * continuam os mesmos: `errorFrom`, `ehReuniaoInexistente`, `classifyError` e o
- * disjuntor do contrato noturno (`scripts/contract/outage.ts`) leem todos eles.
+ * repórter do contrato noturno (`@sbissoli/mcp-live-source`, pelo `cause`) leem todos eles.
  *
  * POLÍTICA (`UPSTREAM_POLICY`) — medida em 27/09/2026 com `curl` e o User-Agent
  * do portfólio: a API legislativa responde em 0,3–1 s (`/senador/lista/atual`
@@ -93,8 +93,17 @@ export class UpstreamError extends Error {
      * quem sabe mais passa explícito (rota inexistente é `defeito`, corpo vazio
      * é `nao_encontrado`).
      */
-    classe) {
-        super(message);
+    classe, 
+    /**
+     * `cause`: o erro do PACOTE (`@sbissoli/mcp-upstream`) que este erro local
+     * traduz. É por ele que o repórter do contrato noturno
+     * (`@sbissoli/mcp-live-source`, via `entregaDaOrigem`) decide se a origem
+     * entregou algo medível — pelo `kind`, nunca pela frase. Sem `cause`, toda
+     * falha traduzida seria "alheia à origem" (medido em 22/10/2026: um 502 nas
+     * três tentativas caía em "other" e zerava o disjuntor).
+     */
+    opcoes = {}) {
+        super(message, opcoes.cause === undefined ? undefined : { cause: opcoes.cause });
         this.status = status;
         this.retryable = retryable;
         this.transport = transport;
@@ -376,7 +385,7 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
     if (!text.trim()) {
         // `nao_encontrado`, como a frase já dava ("vazi"): um corpo vazio é como o
         // `/comissao/reuniao/{codigo}` responde a código inexistente.
-        throw new UpstreamError(`[${path}] Resposta upstream vazia`, 502, true, false, "nao_encontrado");
+        throw new UpstreamError(`[${path}] Resposta upstream vazia`, 502, true, false, "nao_encontrado", { cause: corpoInesperado(url.toString(), response.status, text) });
     }
     if (options.text)
         return text;
@@ -384,7 +393,7 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
         return JSON.parse(text);
     }
     catch {
-        throw new UpstreamError(`[${path}] Resposta upstream não é JSON válido`, 502, false);
+        throw new UpstreamError(`[${path}] Resposta upstream não é JSON válido`, 502, false, false, undefined, { cause: corpoInesperado(url.toString(), response.status, text.slice(0, 2048)) });
     }
 }
 /**
@@ -394,28 +403,40 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
  * `transport` alimenta o disjuntor do contrato noturno.
  */
 export function traduzirErro(err, path) {
+    // O erro do pacote vai em `cause`: é por ele (pelo `kind`) que o repórter do
+    // contrato noturno sabe se a origem entregou algo medível (3.21.2).
+    const cause = { cause: err };
     switch (err.kind) {
         case "timeout":
         case "aborted":
-            return new UpstreamError(`[${path}] Timeout na requisição upstream (${UPSTREAM_TIMEOUT_MS / 1000}s)`, 504, true, true);
+            return new UpstreamError(`[${path}] Timeout na requisição upstream (${UPSTREAM_TIMEOUT_MS / 1000}s)`, 504, true, true, undefined, cause);
         case "network": {
-            const cause = err.cause;
-            const detalhe = cause instanceof Error ? cause.message : typeof cause === "string" ? cause : "";
-            return new UpstreamError(`[${path}] Erro de rede: ${detalhe || "desconhecido"}`, 502, true, true);
+            const raiz = err.cause;
+            const detalhe = raiz instanceof Error ? raiz.message : typeof raiz === "string" ? raiz : "";
+            return new UpstreamError(`[${path}] Erro de rede: ${detalhe || "desconhecido"}`, 502, true, true, undefined, cause);
         }
         case "rate_limited":
-            return new UpstreamError(`[${path}] Upstream retornou 429`, 429, true);
+            return new UpstreamError(`[${path}] Upstream retornou 429`, 429, true, false, undefined, cause);
         case "http_5xx": {
             const status = err.status ?? 502;
             return status === 503
-                ? new UpstreamError(`[${path}] Upstream retornou 503`, 503, true)
-                : new UpstreamError(`[${path}] Upstream retornou HTTP ${status}`, status, true);
+                ? new UpstreamError(`[${path}] Upstream retornou 503`, 503, true, false, undefined, cause)
+                : new UpstreamError(`[${path}] Upstream retornou HTTP ${status}`, status, true, false, undefined, cause);
         }
         case "http_4xx":
         case "not_found":
-            return new UpstreamError(`[${path}] Upstream retornou HTTP ${err.status ?? 404}`, err.status ?? 404, false);
+            return new UpstreamError(`[${path}] Upstream retornou HTTP ${err.status ?? 404}`, err.status ?? 404, false, false, undefined, cause);
         case "malformed_body":
             // Não acontece no modo `response` (o corpo é lido por `upstreamFetch`).
-            return new UpstreamError(`[${path}] Resposta upstream não é JSON válido`, 502, false);
+            return new UpstreamError(`[${path}] Resposta upstream não é JSON válido`, 502, false, false, undefined, cause);
     }
 }
+/**
+ * O corpo chegou, mas não é o esperado (vazio, ou não é JSON). Para o repórter do
+ * contrato noturno isso é `malformed_body` da origem — veredito "ambíguo": ou o
+ * formato mudou, ou a origem serviu a página de erro num pedido bom; repetir decide.
+ * Lido AQUI, depois da ida, porque o modo `response` do pacote não lê o corpo.
+ */
+function corpoInesperado(url, status, body) {
+    return new PkgUpstreamError({ url, kind: "malformed_body", status, retryable: false, transport: false, attempts: 1, body });
+}

package/dist/tools/ecidadania.js

@@ -239,7 +239,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
         }
     });
     // G2. senado_ecidadania_obter_consulta
-    server.tool("senado_ecidadania_obter_consulta", "Obtém o detalhe de uma consulta pública específica do e-Cidadania. Retorna um objeto com `id`, `materia`, `ementa`, `votosSim`/`votosNao`/`totalVotos`, `percentualSim`/`percentualNao`, `status`, `autor`, `relator`, `url`. O portal não publica o período da consulta: `dataAbertura`/`dataEncerramento` (e `comissao`/`linkMateria`) vêm sempre `null` — a consulta abre quando a matéria entra em tramitação e encerra quando sai, refletido em `status`. O campo `comentarios` vem `null`: a página de consulta não possui recurso de comentários. Obtenha o `id` antes via `senado_ecidadania_listar_consultas` ou `senado_ecidadania_consultas_analise`.", { id: z.number().int().positive().describe("ID da consulta pública") }, async (params) => {
+    server.tool("senado_ecidadania_obter_consulta", "Obtém o detalhe de uma consulta pública específica do e-Cidadania. Retorna um objeto com `id`, `materia`, `ementa`, `votosSim`/`votosNao`/`totalVotos`, `percentualSim`/`percentualNao`, `status`, `autor`, `relator`, `url`. O portal não publica o período da consulta: `dataAbertura`/`dataEncerramento` (e `comissao`/`linkMateria`) vêm sempre `null` — a consulta abre quando a matéria entra em tramitação e encerra quando sai, refletido em `status`. O campo `comentarios` vem `null`: a página de consulta não possui recurso de comentários. O campo `relator` vem `null`: a página da consulta publica só autoria e ementa, não a relatoria — o relator da matéria sai de `senado_obter_materia` com o mesmo número (`codigoMateria` = `id`). Obtenha o `id` antes via `senado_ecidadania_listar_consultas` ou `senado_ecidadania_consultas_analise`.", { id: z.number().int().positive().describe("ID da consulta pública") }, async (params) => {
         try {
             const { value: r, fetchedAt } = await cachedFetchWithMeta("ecidadania_consulta", { id: params.id }, CACHE_ON_DEMAND, () => obterConsultaInternal(params.id));
             writeDetalheThrough(db, ctx, "consultas", params.id, r);

package/dist/tools/senadores-admin.js

@@ -123,7 +123,7 @@ export function estatisticasCeaps(filtrado, opts) {
 }
 export function registerSenadoresAdminTools(server, admBaseUrl) {
     // O1. senado_ceaps
-    server.tool("senado_ceaps", "Despesas da Cota para Exercício da Atividade Parlamentar (CEAPS) dos senadores em um ano. Para perguntas de **maior/menor/média/mediana/distribuição/ranking** ('quem gastou mais CEAPS', 'gasto mediano', 'distribuição das despesas') use `estatisticas=true`: computa min/máx/média/mediana/desvio/percentis sobre TODAS as despesas filtradas e devolve `top`/`bottom` (padrão 10) com identificadores — os modos agregados só somam por grupo e não revelam a distribuição nem o extremo individual. Sem `agruparPor` → `distribuicao` das despesas individuais + `top`/`bottom`; com `agruparPor` (`senador`/`tipo`/`mes`/`fornecedor`) → `grupos[]` ranqueados por soma decrescente (`grupos[0]` = maior gastador), cada um com sua mini-distribuição. Sem `estatisticas`: nos modos agregados (`por-senador`/`por-tipo`/`por-mes`/`por-fornecedor`, padrão `por-senador`) traz `agregado[]` ordenado por `total` desc com `chave`, `total` e `despesas` (contagem); em `modo='detalhe'` traz `despesas[]` (mês, data, senador, tipoDespesa, fornecedor, cnpjCpf, valor). Filtre por `mes`, `codSenador`, `nomeSenador`, `tipoDespesa` ou `fornecedor` (busca parcial); `limite` cap 100 com `aviso` ao truncar. Obtenha `codSenador` via `senado_listar_senadores`.", {
+    server.tool("senado_ceaps", "Despesas da Cota para Exercício da Atividade Parlamentar (CEAPS) dos senadores em um ano. A fonte também publica lançamentos NEGATIVOS, sem rótulo próprio (a maioria em passagens aéreas, com jeito de crédito ou estorno): eles entram nas somas e totais como desconto e, nas estatísticas, aparecem como mínimo e no `bottom` — não leia um valor negativo como erro nem como 'a menor despesa'. Para perguntas de **maior/menor/média/mediana/distribuição/ranking** ('quem gastou mais CEAPS', 'gasto mediano', 'distribuição das despesas') use `estatisticas=true`: computa min/máx/média/mediana/desvio/percentis sobre TODAS as despesas filtradas e devolve `top`/`bottom` (padrão 10) com identificadores — os modos agregados só somam por grupo e não revelam a distribuição nem o extremo individual. Sem `agruparPor` → `distribuicao` das despesas individuais + `top`/`bottom`; com `agruparPor` (`senador`/`tipo`/`mes`/`fornecedor`) → `grupos[]` ranqueados por soma decrescente (`grupos[0]` = maior gastador), cada um com sua mini-distribuição. Sem `estatisticas`: nos modos agregados (`por-senador`/`por-tipo`/`por-mes`/`por-fornecedor`, padrão `por-senador`) traz `agregado[]` ordenado por `total` desc com `chave`, `total` e `despesas` (contagem); em `modo='detalhe'` traz `despesas[]` (mês, data, senador, tipoDespesa, fornecedor, cnpjCpf, valor). Filtre por `mes`, `codSenador`, `nomeSenador`, `tipoDespesa` ou `fornecedor` (busca parcial); `limite` cap 100 com `aviso` ao truncar. Obtenha `codSenador` via `senado_listar_senadores`.", {
         ano: z.number().int().min(2008).max(2100).describe("Ano das despesas"),
         modo: z.enum(["por-senador", "por-tipo", "por-mes", "por-fornecedor", "detalhe"]).optional().default("por-senador").describe("Agregação ou detalhe (padrão: por-senador). Ignorado quando estatisticas=true"),
         estatisticas: z.boolean().optional().default(false).describe("Computa estatísticas (min/máx/média/mediana/percentis) + ranking top/bottom sobre todas as despesas filtradas. Use para 'quem gastou mais/menos', 'gasto médio/mediano', 'distribuição', 'ranking'"),

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.21.0";
+export const VERSION = "3.22.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.21.0",
+  "version": "3.22.0",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "keywords": [
     "mcp",
@@ -74,13 +74,14 @@
     "@sbissoli/mcp-provenance": "^0.4.0",
     "@sbissoli/mcp-search": "^0.9.0",
     "@sbissoli/mcp-stats": "^0.3.0",
-    "@sbissoli/mcp-upstream": "^0.4.2",
+    "@sbissoli/mcp-upstream": "^0.5.1",
     "zod": "^4.5.4"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20260830.1",
     "@modelcontextprotocol/client": "^2.0.0",
     "@sbissoli/mcp-evals": "^0.2.1",
+    "@sbissoli/mcp-live-source": "^0.1.1",
     "@sbissoli/mcp-surface": "^0.6.0",
     "@types/node": "^26.5.1",
     "agents": "^0.28.0",