senado-br-mcp 3.18.0 → 3.18.2

package/README.md

@@ -35,6 +35,18 @@ Point a client at the endpoint and ask in plain language — English or Portugue
 
 The answers come live from the Senate's official open-data APIs — exact figures with provenance, not numbers guessed from training data.
 
+## Compared with the alternatives
+
+Other Brazilian MCP servers also touch the Senate — [mcp-brasil](https://github.com/Mcp-Brasil/mcp-brasil) and [mcp-dados-br](https://github.com/lucianoon/mcp-dados-br) are multi-source aggregators in which the Senate is one source among many. The difference is coverage and how you run it. Measured in each one's source code on 2026-10-11:
+
+| | Senate tools | Covers | Where it runs |
+| --- | --- | --- | --- |
+| **senado-br-mcp** (this) | 69 | legislative, administrative (CEAPS, staff, contracts, budget) and e-Cidadania, with provenance on every answer | hosted, no install or key; or `npx` |
+| [mcp-brasil](https://github.com/Mcp-Brasil/mcp-brasil) 0.14.0 | 26 | legislative (senators, bills, floor votes, committees, agenda) — plus dozens of other government sources | local or self-hosted (Python) |
+| [mcp-dados-br](https://github.com/lucianoon/mcp-dados-br) 0.6.0 | 3 | sitting senators, bill list, vote tally — plus IBGE, BCB, INMET, Chamber of Deputies | local (Python) |
+
+**Pick an aggregator** when the question crosses the Senate with the Chamber of Deputies, the electoral court (TSE) or the Transparency Portal. **Pick this server** for expenses (CEAPS), staff, contracts, budget, speeches, committee votes, vetoes or e-Cidadania — areas the others don't cover. Full per-area table, side-by-side examples and how to re-measure (in Portuguese): [`docs/comparativo-alternativas.md`](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare/blob/master/docs/comparativo-alternativas.md).
+
 ## Use it (hosted — no setup)
 
 This is a **remote, hosted, open-access** server. To use it, point any MCP client at the Streamable
@@ -552,13 +564,13 @@ Fields of the `concise` block (per response — one tool, one source; keys in th
 | `citation` | Ready-to-use citation string (human-readable) |
 | `license` | Source terms (Dados Abertos do Senado Federal) |
 
-The canonical model behind the block also carries `dataset.id` (item/series identifier, e.g. `codigoMateria=137808`), `api_version` and per-field `field_sources`; those are validated on every build and inform `attribution` (below), but are not part of the `concise` projection.
+The canonical model behind the block also carries `dataset.id` (item/series identifier, e.g. `codigoMateria=137808`) and `api_version`; those are validated on every build and inform `attribution` (below), but are not part of the `concise` projection. Per-field `field_sources` are (contract v1.2, since 3.17.0), on the responses that merge reads.
 
 In addition to the `provenance` envelope, `structuredContent` carries a top-level **`attribution`** list — the distinct source URLs behind the response. This mirrors the naming proposed in [modelcontextprotocol#711](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/711) (where `attribution` is a list of source references at the response level), so the server stays forward-compatible if that RFC lands; the richer `provenance` object remains this server's own extension.
 
 **Out-of-band mirror in `_meta`.** The same `provenance` and `attribution` are also mirrored on the result's `_meta` under namespaced keys (`com.sidneybissoli.senado/provenance` and `com.sidneybissoli.senado/attribution`). The MCP spec keeps `_meta` for metadata *about* a result that should not steer the model, which is where the still-incubating trust/attribution work from #711 (split into an experimental extensions track, not yet in core) points; mirroring there gives audit and UI consumers the provenance without reading the model-facing data channel, at no model-token cost, while `structuredContent` keeps it visible so the model can cite the source. The mirror survives the ChatGPT-app profile minimizer (which only strips `structuredContent.meta`).
 
-**Field-level granularity.** Most tools are single-source, so one envelope suffices. The few that merge slices in one response fill `field_sources` in the canonical model — a list of `{ fields, source_url, data_vintage, retrieved_at, … }` attributing specific output fields to their real origin. Example: `senado_obter_materia` `secao=detalhe` fuses `/processo/{id}` (the top-level source) with the `ementa` from `/processo` and the `relator` from `/processo/relatoria`, each carrying its own `retrieved_at`. In the emitted `concise` block the per-field detail is summarized through `attribution`, which always lists every distinct underlying `source_url`.
+**Field-level granularity.** Most tools are single-source, so one envelope suffices. The few that merge reads in one response fill `field_sources` — a list of `{ fields, source_url, dataset_id, data_vintage, retrieved_at, served_from_cache }` attributing specific output fields to their real origin, and the block's `retrieved_at` is the oldest of them. `served_from_cache` is `true`/`false` for reads through the server cache and `null` where the notion does not apply (the bundled org-chart snapshot, the e-Cidadania corpus in D1). The merging tools (since 3.18.2): `senado_obter_materia` `secao=detalhe` (`/processo/{id}` + `ementa` from `/processo` + `relator` from `/processo/relatoria`), `senado_obter_senador` and the Deep Research `fetch` of a senator (biography + `mandatos`/`emExercicio` from `/senador/{codigo}/mandatos`), `senado_reunioes_comissao` over a window that crosses the year (one read per year), `senado_servidores` with `subordinadasA` (payroll + org-chart snapshot), `senado_suprimento_fundos` statistics on `atos-concessao` (acts + beneficiary names from the supridos registry), `senado_ecidadania_obter_evento` (live detail + `comentarios` from the corpus) and `senado_ecidadania_sugerir_tema_enquete` (consultas and ideias corpora). **Only a read that becomes a field of the answer is a sub-source**: a read that only resolves or checks an identifier (a committee acronym → its code, the parent check in `senado_contratacao_detalhe`) is left out, otherwise a cached lookup table would make the whole answer claim to be as old as it. `attribution` always lists every distinct underlying `source_url`.
 
 `retrieved_at` fidelity is provided by the cache layer (`cachedFetchWithMeta`), which persists the fetch timestamp alongside the value, so it reflects the real upstream extraction even on a cache hit. Two exceptions report an honest live timestamp instead: the e-Cidadania **list** tools (read from D1) use the corpus's `lastScrapedAt` — the true age of the stored data — while e-Cidadania **detail** tools, scraped live, use the fetch time and a level-3 canonical item URL. The only path that falls back to the build-time default is the in-code static reference catalog (`senado_tabelas_referencia` `tipos-materia`), which has no upstream extraction instant.
 

package/dist/tools/comissoes.js

@@ -17,7 +17,7 @@ import { upstreamFetch, UpstreamError } 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 { leituraDoCache, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { CACHE_SEMI_STATIC, CACHE_DYNAMIC, CACHE_ON_DEMAND } from "../types.js";
 export function formatDateYMD(d) {
     return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, "0")}${String(d.getDate()).padStart(2, "0")}`;
@@ -125,6 +125,35 @@ export async function fetchComissaoColegiado(codigo, baseUrl) {
     const colegiado = ensureArray(r?.ComissoesCongressoNacional?.Colegiados?.Colegiado)[0];
     return { path, fetchedAt, colegiado };
 }
+/**
+ * Proveniência de `senado_reunioes_comissao`. A fonte não aceita janela que cruza o ano, então
+ * a tool lê um recorte por ano, cada um numa entrada de cache própria, e junta as reuniões.
+ * Com um recorte só, o bloco é o desse recorte. Com dois, cada um vira sub-fonte das MESMAS
+ * linhas (`reunioes`, `count`) com a sua janela e o seu instante, e o topo é o mais antigo
+ * (adaptador, contrato §3) — até a 3.18.1 o topo era sempre o do 1º recorte e o instante do
+ * 2º era descartado, mesmo quando ele estava em cache havia mais tempo.
+ */
+export function provenanceReunioesComissao(baseUrl, sigla, di, df, partes) {
+    const dataset_id = `comissao=${sigla}`;
+    const [primeira] = partes;
+    const base = baseUrl.replace(/\/$/, "");
+    return provenanceFor("SENADO_LEGIS", baseUrl, `/comissao/agenda/${di}/${df}`, {
+        dataset_id,
+        reference_period: `${di}/${df}`,
+        retrieved_at: primeira.fetchedAt,
+        ...(partes.length > 1
+            ? {
+                field_sources: partes.map((p) => ({
+                    fields: ["reunioes", "count"],
+                    source_url: `${base}/comissao/agenda/${p.dataInicio}/${p.dataFim}`,
+                    dataset_id,
+                    reference_period: `${p.dataInicio}/${p.dataFim}`,
+                    ...leituraDoCache(p),
+                })),
+            }
+            : {}),
+    });
+}
 export function registerComissoesTools(server, baseUrl) {
     // E1. senado_listar_comissoes
     server.tool("senado_listar_comissoes", "Lista comissões (colegiados) ativas do Senado, com filtros por `tipo` (permanente, temporaria, cpi, mista) e `ativa`. Retorna `{ count, comissoes }`, cada item com `codigo`, `sigla`, `nome`, `tipo`, `casa` e `ativa`. O endpoint só traz comissões ativas, logo `ativa=false` resulta em lista vazia. Use para descobrir a `sigla` exigida por `senado_obter_comissao` e `senado_reunioes_comissao`.", {
@@ -229,17 +258,20 @@ export function registerComissoesTools(server, baseUrl) {
             const yearDi = parseInt(di.slice(0, 4));
             const yearDf = parseInt(df.slice(0, 4));
             let todas = [];
-            let fetchedAt;
+            let partes;
             if (yearDi === yearDf) {
                 const res = await cachedFetchWithMeta("senado_reunioes_comissao", { sigla, dataInicio: di, dataFim: df }, CACHE_DYNAMIC, () => upstreamFetch(`/comissao/agenda/${di}/${df}`, {}, baseUrl));
-                fetchedAt = res.fetchedAt;
+                partes = [{ dataInicio: di, dataFim: df, ...res }];
                 todas = ensureArray(res.value?.AgendaReuniao?.reunioes?.reuniao);
             }
             else {
                 // Split: [di..yearDi-12-31] + [yearDf-01-01..df]
                 const r1 = await cachedFetchWithMeta("senado_reunioes_comissao_p1", { sigla, dataInicio: di, dataFim: `${yearDi}1231` }, CACHE_DYNAMIC, () => upstreamFetch(`/comissao/agenda/${di}/${yearDi}1231`, {}, baseUrl));
                 const r2 = await cachedFetchWithMeta("senado_reunioes_comissao_p2", { sigla, dataInicio: `${yearDf}0101`, dataFim: df }, CACHE_DYNAMIC, () => upstreamFetch(`/comissao/agenda/${yearDf}0101/${df}`, {}, baseUrl));
-                fetchedAt = r1.fetchedAt;
+                partes = [
+                    { dataInicio: di, dataFim: `${yearDi}1231`, ...r1 },
+                    { dataInicio: `${yearDf}0101`, dataFim: df, ...r2 },
+                ];
                 todas = [
                     ...ensureArray(r1.value?.AgendaReuniao?.reunioes?.reuniao),
                     ...ensureArray(r2.value?.AgendaReuniao?.reunioes?.reuniao),
@@ -259,11 +291,7 @@ export function registerComissoesTools(server, baseUrl) {
                 tipo: re.tipo?.descricao || null,
                 situacao: re.situacao || null,
             }));
-            const prov = provenanceFor("SENADO_LEGIS", baseUrl, `/comissao/agenda/${di}/${df}`, {
-                dataset_id: `comissao=${sigla}`,
-                reference_period: `${di}/${df}`,
-                retrieved_at: fetchedAt,
-            });
+            const prov = provenanceReunioesComissao(baseUrl, sigla, di, df, partes);
             return resultWithProvenance({ sigla, periodo: { dataInicio: di, dataFim: df }, count: reunioes.length, reunioes }, prov);
         }
         catch (e) {

package/dist/tools/deep-research.js

@@ -37,7 +37,7 @@ import { upstreamFetch } from "../throttle/upstream.js";
 import { ensureArray } from "../utils/validation.js";
 import { provenanceExtras, provenanceFor } from "../utils/provenance.js";
 import { CACHE_SEMI_STATIC } from "../types.js";
-import { extractParlamentares, fetchSenadorDetalhe, parseSenadorResumo } from "./senadores.js";
+import { extractParlamentares, fetchSenadorDetalhe, parseSenadorResumo, provenanceSenadorDetalhe } from "./senadores.js";
 import { RootNotFoundError } from "../utils/upstream-parse.js";
 import { classifyThrown } from "../call-shape.js";
 import { fetchComissaoColegiado, parseComissaoItem, parseComissaoResumo } from "./comissoes.js";
@@ -214,13 +214,10 @@ function handlers(baseUrl) {
                     return null;
                 throw e;
             }
-            const { path, fetchedAt, detalhe } = detalheSenador;
+            const { detalhe } = detalheSenador;
             if (!detalhe.codigo)
                 return null;
-            const prov = provenanceFor("SENADO_LEGIS", baseUrl, path, {
-                dataset_id: `codigoParlamentar=${codigo}`,
-                retrieved_at: fetchedAt,
-            });
+            const prov = provenanceSenadorDetalhe(baseUrl, codigo, detalheSenador);
             return {
                 document: {
                     id,

package/dist/tools/ecidadania.js

@@ -12,7 +12,7 @@
 import { z } from "zod";
 import { cachedFetchWithMeta } from "../cache/manager.js";
 import { errorFrom } from "../utils/validation.js";
-import { provenanceEcidadania, provenanceArquimedesVotos, resultWithProvenance } from "../utils/provenance.js";
+import { leituraDoCache, provenanceEcidadania, provenanceArquimedesVotos, resultWithProvenance, withFieldSources, } from "../utils/provenance.js";
 import { tagUntrustedFields, tagUntrustedList, neutralizeUntrustedText, sanitizeScrapedText } from "../utils/untrusted.js";
 import { CACHE_ON_DEMAND } from "../types.js";
 import { resolveList, writeDetalheThrough } from "../scraper/store.js";
@@ -46,6 +46,68 @@ export const OBTER_CONSULTA_DATAS_AVISO = "O portal e-Cidadania não publica o p
 export function buildConsultaDetalheResult(r) {
     return { ...r, comentarios: null, aviso: OBTER_CONSULTA_DATAS_AVISO };
 }
+/** URL canônica do item raspado (nível 3) quando o scraper a expõe; senão o caminho de fallback. */
+function urlDoItem(item, fallbackPath) {
+    const url = item?.url;
+    return typeof url === "string" && url.startsWith("http") ? url : fallbackPath;
+}
+/**
+ * Sub-fonte lida do corpus em D1 (`resolveList`): o instante é o `lastScrapedAt` da meta, o
+ * mesmo que `provLista` põe no topo das listas; o D1 não é cache, então `served_from_cache`
+ * fica de fora (sai `null`).
+ */
+export function subFonteDoCorpus(pathOrUrl, dataset_id, meta, fields) {
+    const ts = meta?.lastScrapedAt;
+    return {
+        fields,
+        source_url: provenanceEcidadania(pathOrUrl).source_url,
+        dataset_id,
+        ...(typeof ts === "string" && ts ? { retrieved_at: ts } : {}),
+    };
+}
+/**
+ * Proveniência de `senado_ecidadania_obter_evento`. O detalhe é raspado ao vivo (cache próprio),
+ * mas a página estática não lê a contagem de `comentarios` (carregada por AJAX): ela vem do
+ * corpus em D1, lido noutro instante. Até a 3.18.1 o topo era só o do detalhe; agora, quando o
+ * corpus dá a contagem, as duas leituras viram sub-fontes e o topo é o mais antigo (adaptador,
+ * contrato §3). Evento fora do corpus = `comentarios: null`, sem sub-fonte.
+ */
+export function provenanceEventoDetalhe(item, id, leitura, corpusMeta) {
+    const dataset_id = `evento=${id}`;
+    const prov = provenanceEcidadania(urlDoItem(item, `/visualizacaoaudiencia?id=${id}`), {
+        dataset_id,
+        retrieved_at: leitura.fetchedAt,
+    });
+    if (corpusMeta === undefined)
+        return prov;
+    return withFieldSources(prov, [
+        {
+            fields: Object.keys(item).filter((k) => k !== "comentarios"),
+            source_url: prov.source_url,
+            dataset_id,
+            ...leituraDoCache(leitura),
+        },
+        subFonteDoCorpus("/principalaudiencia", "eventos", corpusMeta, ["comentarios"]),
+    ]);
+}
+/**
+ * Proveniência de `senado_ecidadania_sugerir_tema_enquete`: as sugestões cruzam DOIS corpora
+ * do D1 (consultas e ideias), cada um com o seu `lastScrapedAt`. Até a 3.18.1 o topo levava só
+ * o das consultas e o das ideias era descartado; agora cada corpus é sub-fonte das mesmas
+ * contagens e o topo é o mais antigo (adaptador, contrato §3).
+ */
+export function provenanceSugestaoEnquete(consultasMeta, ideiasMeta) {
+    const campos = ["sugestoes", "count", "totalAnalisados", "totalQualificados"];
+    const ts = consultasMeta?.lastScrapedAt;
+    const prov = provenanceEcidadania("/principalmateria", {
+        dataset_id: "consultas+ideias",
+        retrieved_at: typeof ts === "string" && ts ? ts : undefined,
+    });
+    return withFieldSources(prov, [
+        subFonteDoCorpus("/principalmateria", "consultas", consultasMeta, campos),
+        subFonteDoCorpus("/principalideia", "ideias", ideiasMeta, campos),
+    ]);
+}
 // ══════════════════════════════════════════════════════════════════════════
 // Tool registration
 // ══════════════════════════════════════════════════════════════════════════
@@ -74,9 +136,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
     // Detalhes são raspados ao vivo (via cachedFetch): use a URL canônica do próprio item quando
     // o scraper a expõe (nível 3), com o fetchedAt do cache como retrieved_at.
     function provDetalhe(item, fallbackPath, dataset_id, fetchedAt) {
-        const url = item?.url;
-        const alvo = typeof url === "string" && url.startsWith("http") ? url : fallbackPath;
-        return provenanceEcidadania(alvo, { dataset_id, retrieved_at: fetchedAt });
+        return provenanceEcidadania(urlDoItem(item, fallbackPath), { dataset_id, retrieved_at: fetchedAt });
     }
     function ecidadaniaError(e) {
         // Mesmo caminho de toda tool (errorFrom: log cru, classe pelo TIPO da exceção via
@@ -266,22 +326,26 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
     // G9. senado_ecidadania_obter_evento
     server.tool("senado_ecidadania_obter_evento", "Obtém o detalhe completo de um evento interativo do e-Cidadania (audiência, sabatina, live). Retorna um objeto com `id`, `titulo`, `descricao`, `data`, `hora`, `comissao` e `comissaoNomeCompleto`, `local`, `status` (`agendado`/`encerrado`/`cancelado`), `comentarios`, `url`, mais `pauta` (até 15 itens), `convidados` e `videoUrl` (embed do YouTube quando houver, senão `null`) — campos não preenchidos vêm `null` e `id` inexistente retorna erro. Obtenha o `id` antes via `senado_ecidadania_listar_eventos`. Para apenas listar/rankear eventos (sem descrição/pauta/convidados) use `senado_ecidadania_listar_eventos`, não esta.", { id: z.number().int().positive().describe("Identificador do evento (campo `id` de senado_ecidadania_listar_eventos)") }, async (params) => {
         try {
-            const { value: r, fetchedAt } = await cachedFetchWithMeta("ecidadania_evento", { id: params.id }, CACHE_ON_DEMAND, () => obterEventoInternal(params.id));
+            const leitura = await cachedFetchWithMeta("ecidadania_evento", { id: params.id }, CACHE_ON_DEMAND, () => obterEventoInternal(params.id));
+            const r = leitura.value;
             writeDetalheThrough(db, ctx, "eventos", params.id, r);
             // The static detail scrape can't read the AJAX-loaded comentarios count (always 0);
             // the corpus carries the canonical count from the AJAX fragment (estudo A3 — the
             // listing count is spurious, 0 in ~82%). Splice it in, or null when the event is not
             // in the corpus (unknown, not a spurious 0).
             const detalhe = { ...r };
+            let corpusMeta;
             try {
-                const { items } = await resolveList(db, "eventos", corpusStaleMaxMin(), () => listarEventosInternal({ limite: 100 }), undefined, CORPUS_RESOLVE);
+                const { items, meta } = await resolveList(db, "eventos", corpusStaleMaxMin(), () => listarEventosInternal({ limite: 100 }), undefined, CORPUS_RESOLVE);
                 const corpusItem = items.find((e) => e.id === params.id);
                 detalhe.comentarios = corpusItem ? corpusItem.comentarios : null;
+                if (corpusItem)
+                    corpusMeta = meta;
             }
             catch {
                 detalhe.comentarios = null;
             }
-            return resultWithProvenance(tagUntrustedFields("eventos", detalhe), provDetalhe(r, `/visualizacaoaudiencia?id=${params.id}`, `evento=${params.id}`, fetchedAt));
+            return resultWithProvenance(tagUntrustedFields("eventos", detalhe), provenanceEventoDetalhe(r, params.id, leitura, corpusMeta));
         }
         catch (e) {
             return ecidadaniaError(e);
@@ -352,7 +416,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
                 totalQualificados: sugestoes.length,
                 sugestoes: retornadas,
                 meta: { consultas: cRes.meta, ideias: iRes.meta },
-            }, provLista("/principalmateria", "consultas+ideias", cRes.meta));
+            }, provenanceSugestaoEnquete(cRes.meta, iRes.meta));
         }
         catch (e) {
             return ecidadaniaError(e);

package/dist/tools/materias.js

@@ -145,8 +145,15 @@ export function provenanceMateriaDetalhe(baseUrl, a) {
             source_url: `${base}/processo/${a.idProcesso}`,
             dataset_id,
             retrieved_at: a.detalheFetchedAt,
+            served_from_cache: a.doCache?.detalhe,
+        },
+        {
+            fields: ["ementa"],
+            source_url: `${base}/processo`,
+            dataset_id,
+            retrieved_at: a.resumoFetchedAt,
+            served_from_cache: a.doCache?.resumo,
         },
-        { fields: ["ementa"], source_url: `${base}/processo`, dataset_id, retrieved_at: a.resumoFetchedAt },
     ];
     if (a.relatoriaFetchedAt !== undefined) {
         fieldSources.push({
@@ -154,6 +161,7 @@ export function provenanceMateriaDetalhe(baseUrl, a) {
             source_url: `${base}/processo/relatoria`,
             dataset_id,
             retrieved_at: a.relatoriaFetchedAt,
+            served_from_cache: a.doCache?.relatoria,
         });
     }
     return provenanceFor("SENADO_LEGIS", baseUrl, `/processo/${a.idProcesso}`, {
@@ -164,12 +172,12 @@ export function provenanceMateriaDetalhe(baseUrl, a) {
     });
 }
 async function resolveProcesso(codigoMateria, baseUrl) {
-    const { value: response, fetchedAt } = await cachedFetchWithMeta("_processo_por_materia", { codigoMateria }, CACHE_ON_DEMAND, () => upstreamFetch("/processo", { codigoMateria: String(codigoMateria) }, baseUrl));
+    const { value: response, fetchedAt, fromCache } = await cachedFetchWithMeta("_processo_por_materia", { codigoMateria }, CACHE_ON_DEMAND, () => upstreamFetch("/processo", { codigoMateria: String(codigoMateria) }, baseUrl));
     const item = ensureArray(response)[0];
     if (!item || !item.id) {
         throw new Error(`Matéria ${codigoMateria} não encontrada na API de processos`);
     }
-    return { item, fetchedAt };
+    return { item, fetchedAt, fromCache };
 }
 /**
  * Zero resultado por palavra-chave não é prova de que o tema não existe: a
@@ -312,7 +320,7 @@ export function registerMateriasTools(server, baseUrl) {
                 cachedFetchWithMeta("_processo_relatoria", { codigoMateria: params.codigoMateria }, CACHE_ON_DEMAND, () => upstreamFetch("/processo/relatoria", { codigoMateria: String(params.codigoMateria) }, baseUrl)).catch(() => null),
             ]);
             const resumo = resumoRes.item;
-            const { value: detalheRes, fetchedAt } = await cachedFetchWithMeta("senado_obter_materia", { idProcesso: resumo.id }, CACHE_ON_DEMAND, () => upstreamFetch(`/processo/${resumo.id}`, {}, baseUrl));
+            const { value: detalheRes, fetchedAt, fromCache } = await cachedFetchWithMeta("senado_obter_materia", { idProcesso: resumo.id }, CACHE_ON_DEMAND, () => upstreamFetch(`/processo/${resumo.id}`, {}, baseUrl));
             const detalhe = parseProcessoDetalhe(detalheRes);
             const relator = pickRelatorAtual(ensureArray(relatoriasRes?.value));
             const prov = provenanceMateriaDetalhe(baseUrl, {
@@ -322,6 +330,7 @@ export function registerMateriasTools(server, baseUrl) {
                 detalheFetchedAt: fetchedAt,
                 resumoFetchedAt: resumoRes.fetchedAt,
                 relatoriaFetchedAt: relator ? relatoriasRes?.fetchedAt : undefined,
+                doCache: { detalhe: fromCache, resumo: resumoRes.fromCache, relatoria: relatoriasRes?.fromCache },
             });
             return resultWithProvenance({
                 ...detalhe,

package/dist/tools/senadores.js

@@ -11,7 +11,7 @@ import { cachedFetchWithMeta } from "../cache/manager.js";
 import { upstreamFetch } from "../throttle/upstream.js";
 import { errorFrom, ensureArray, normalizeText, safeInt } from "../utils/validation.js";
 import { digArrayRoot, digObjectRoot } from "../utils/upstream-parse.js";
-import { provenanceFor, resultWithProvenance, toBrasiliaIso } from "../utils/provenance.js";
+import { leituraDoCache, 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;
@@ -210,7 +210,7 @@ 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 { value: response, fetchedAt, fromCache } = await cachedFetchWithMeta("senado_obter_senador", { codigo: codigoSenador }, CACHE_ON_DEMAND, () => upstreamFetch(path, {}, baseUrl));
     // 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
@@ -228,10 +228,14 @@ export async function fetchSenadorDetalhe(codigoSenador, baseUrl) {
     // É 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 = [];
+    // Leitura dos mandatos, só quando ela de fato deu os campos `mandatos`/`emExercicio`
+    // (falha = lista vazia e `null`, que não vêm de fonte nenhuma).
+    let mandatosLeitura;
     try {
         const mandatosPath = `/senador/${codigoSenador}/mandatos`;
-        const { value: mResp } = await cachedFetchWithMeta("senado_obter_senador_mandatos", { codigo: codigoSenador }, CACHE_ON_DEMAND, () => upstreamFetch(mandatosPath, {}, baseUrl));
+        const { value: mResp, fetchedAt: mFetchedAt, fromCache: mFromCache } = await cachedFetchWithMeta("senado_obter_senador_mandatos", { codigo: codigoSenador }, CACHE_ON_DEMAND, () => upstreamFetch(mandatosPath, {}, baseUrl));
         mandatosBrutos = digArrayRoot(mResp, [["MandatoParlamentar", "Parlamentar", "Mandatos", "Mandato"]], "senado_obter_senador:mandatos");
+        mandatosLeitura = { fetchedAt: mFetchedAt, fromCache: mFromCache };
     }
     catch {
         // sub-endpoint unavailable — keep the (empty) mandatos from the detail
@@ -240,6 +244,8 @@ export async function fetchSenadorDetalhe(codigoSenador, baseUrl) {
     return {
         path,
         fetchedAt,
+        fromCache,
+        mandatosLeitura,
         detalhe: {
             ...detalhe,
             emExercicio: derivarEmExercicio(mandatosBrutos, hoje),
@@ -247,6 +253,42 @@ export async function fetchSenadorDetalhe(codigoSenador, baseUrl) {
         },
     };
 }
+/** Campos do detalhe que vêm de `/senador/{codigo}/mandatos`, não do detalhe biográfico. */
+const CAMPOS_DOS_MANDATOS = ["mandatos", "emExercicio"];
+/**
+ * Proveniência de `senado_obter_senador` (e do `fetch` `senador:` do Deep Research, que
+ * renderiza o mesmo registro no texto do documento). O registro funde DUAS leituras, cada
+ * uma de uma entrada de cache própria: o detalhe biográfico (`/senador/{codigo}`, topo) e os
+ * mandatos (`/senador/{codigo}/mandatos`), de onde saem `mandatos` e `emExercicio`. Até a
+ * 3.18.1 o instante dos mandatos era descartado e o topo era o do detalhe — com os mandatos
+ * em cache desde antes, o bloco dizia que `emExercicio` fora lido mais recentemente do que
+ * foi. Com as duas como sub-fontes o topo passa a ser o mais antigo (adaptador, contrato §3).
+ * Mandatos que falharam não viram sub-fonte: a resposta leva `[]` e `null`, sem fonte.
+ */
+export function provenanceSenadorDetalhe(baseUrl, codigoSenador, leitura) {
+    const dataset_id = `codigoParlamentar=${codigoSenador}`;
+    const topo = { dataset_id, retrieved_at: leitura.fetchedAt };
+    if (!leitura.mandatosLeitura)
+        return provenanceFor("SENADO_LEGIS", baseUrl, leitura.path, topo);
+    const base = baseUrl.replace(/\/$/, "");
+    return provenanceFor("SENADO_LEGIS", baseUrl, leitura.path, {
+        ...topo,
+        field_sources: [
+            {
+                fields: Object.keys(leitura.detalhe).filter((k) => !CAMPOS_DOS_MANDATOS.includes(k)),
+                source_url: `${base}${leitura.path}`,
+                dataset_id,
+                ...leituraDoCache(leitura),
+            },
+            {
+                fields: CAMPOS_DOS_MANDATOS,
+                source_url: `${base}${leitura.path}/mandatos`,
+                dataset_id,
+                ...leituraDoCache(leitura.mandatosLeitura),
+            },
+        ],
+    });
+}
 export function registerSenadoresTools(server, baseUrl) {
     // A1. senado_listar_senadores (filtro `nome` substitui a antiga busca por nome)
     server.tool("senado_listar_senadores", "Use para pedidos como 'liste os senadores em exercício', 'senadores atuais', 'lista atual de senadores' ou filtros por UF/partido. Lista senadores em exercício ou de uma legislatura específica, com filtros opcionais por `nome`, `uf` e `partido`. Retorna `{ count, senadores }`, cada item com `codigo`, `nome`, `nomeCompleto`, `partido`, `uf`, `foto` e `emExercicio`, mais proveniência oficial do endpoint `/senador/lista/atual`. Use `emExercicio` (padrão `true`) ou `legislatura` para escolher o conjunto; `nome` faz correspondência parcial ignorando acentos/maiúsculas (use quando você só tem o nome e precisa do `codigo`); `uf`/`partido` filtram localmente. Use o `codigo` em `senado_obter_senador` ou `senado_votacoes_senador`. Para senadores fora de exercício veja `senado_senadores_afastados`.", {
@@ -287,12 +329,9 @@ export function registerSenadoresTools(server, baseUrl) {
         codigoSenador: z.number().int().positive().describe("Código único do senador no sistema do Senado"),
     }, async (params) => {
         try {
-            const { path, fetchedAt, detalhe } = await fetchSenadorDetalhe(params.codigoSenador, baseUrl);
-            const prov = provenanceFor("SENADO_LEGIS", baseUrl, path, {
-                dataset_id: `codigoParlamentar=${params.codigoSenador}`,
-                retrieved_at: fetchedAt,
-            });
-            return resultWithProvenance(detalhe, prov);
+            const leitura = await fetchSenadorDetalhe(params.codigoSenador, baseUrl);
+            const prov = provenanceSenadorDetalhe(baseUrl, params.codigoSenador, leitura);
+            return resultWithProvenance(leitura.detalhe, prov);
         }
         catch (e) {
             return errorFrom(e, "Senador não encontrado");

package/dist/tools/servidores.js

@@ -343,14 +343,18 @@ export function particionarPorUnidade(lista, indice, codUnidade) {
  * das duas (derivado pelo adaptador, contrato §3), e a folha entra como sub-fonte própria
  * para que o seu instante não suma do bloco. Antes da 3.17.0 o topo era o da folha, mais
  * novo que o snapshot — com a v1.2 ligada, a lib lançaria e a tool cairia.
+ *
+ * `folhaDoCache` é o `fromCache` da leitura da folha; o snapshot embutido não é cache nem
+ * busca, então a sub-fonte dele não diz (`served_from_cache: null`).
  */
-export function provenanceServidoresSubordinadas(prov, situacao) {
+export function provenanceServidoresSubordinadas(prov, situacao, folhaDoCache) {
     return withFieldSources(prov, [
         {
             fields: ["servidores", "total", "count", "naoClassificados", "afastadosOuEmTransito"],
             source_url: prov.source_url,
             dataset_id: `servidores; situacao=${situacao}`,
             retrieved_at: prov.retrieved_at,
+            served_from_cache: folhaDoCache,
         },
         {
             fields: ["subordinadasA", "total", "naoClassificados"],
@@ -373,7 +377,7 @@ export function registerServidoresTools(server, admBaseUrl) {
     }, async (params) => {
         try {
             const situacao = params.situacao ?? "ativos";
-            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_servidores", { situacao }, CACHE_SEMI_STATIC, () => admFetchLarge(`/servidores/servidores/${situacao}`, {}, admBaseUrl));
+            const { value: response, fetchedAt, fromCache } = await cachedFetchWithMeta("senado_servidores", { situacao }, CACHE_SEMI_STATIC, () => admFetchLarge(`/servidores/servidores/${situacao}`, {}, admBaseUrl));
             let lista = ensureArray(response).map(parseServidor);
             if (params.nome)
                 lista = lista.filter((s) => matchesFiltro(s.nome, params.nome));
@@ -398,7 +402,7 @@ export function registerServidoresTools(server, admBaseUrl) {
                     return toolError(`Unidade '${params.subordinadasA}' não encontrada na estrutura organizacional.${dica}`, "nao_encontrado");
                 }
                 const { sob, naoClassificados, afastadosOuEmTransito } = particionarPorUnidade(lista, indice, alvo.cod);
-                const provComEstrutura = provenanceServidoresSubordinadas(prov, situacao);
+                const provComEstrutura = provenanceServidoresSubordinadas(prov, situacao, fromCache);
                 return resultWithProvenance({
                     situacao,
                     subordinadasA: { sigla: alvo.sigla, nome: alvo.nome },

package/dist/tools/supridos.js

@@ -9,7 +9,7 @@ import { z } from "zod";
 import { cachedFetchWithMeta } from "../cache/manager.js";
 import { admFetch } from "../throttle/adm.js";
 import { errorFrom, ensureArray } from "../utils/validation.js";
-import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { leituraDoCache, provenanceFor, resultWithProvenance, withFieldSources } from "../utils/provenance.js";
 import { computarEstatisticas, arredondarEstatisticas, arredondarEntradas, } from "../utils/estatisticas.js";
 import { CACHE_STATIC } from "../types.js";
 import { matchesFiltro } from "./contratacoes.js";
@@ -172,22 +172,66 @@ export function estatisticasSuprimento(lista, opts) {
 /**
  * Build a `codigo -> nome` map of supridos for a year, from the registry (tipo=supridos, ~1 MB),
  * so `atos-concessao` statistics can identify the beneficiary by NAME instead of the internal code.
- * Cached by year; a fetch failure degrades to an empty map (entries fall back to name = null).
+ * Cached by year; a fetch failure degrades to an empty map (entries fall back to name = null)
+ * and no `leitura` — the names then come from nowhere, so there is no sub-source to declare.
  */
 export async function nomesSupridos(ano, admBaseUrl) {
-    const map = new Map();
+    const nomes = new Map();
     try {
-        const { value } = await cachedFetchWithMeta("senado_suprimento_fundos_nomes", { ano }, CACHE_STATIC, () => admFetch(PATHS["supridos"](ano), {}, admBaseUrl));
+        const { value, fetchedAt, fromCache } = await cachedFetchWithMeta("senado_suprimento_fundos_nomes", { ano }, CACHE_STATIC, () => admFetch(PATHS["supridos"](ano), {}, admBaseUrl));
         for (const s of ensureArray(value)) {
             const cod = s?.codigo != null ? String(s.codigo) : null;
             if (cod && s?.nome)
-                map.set(cod, String(s.nome));
+                nomes.set(cod, String(s.nome));
         }
+        return { nomes, leitura: { fetchedAt, fromCache } };
     }
     catch {
         // best-effort enrichment; the ranking still works without names
+        return { nomes };
     }
-    return map;
+}
+/**
+ * Which fields of the `atos-concessao` statistics carry the suprido's NAME: the groups when
+ * grouping by suprido; nothing when grouping by another (valid) dimension; top/bottom otherwise
+ * (no grouping, or an invalid grouping that falls back to the row distribution).
+ */
+export function camposComNomeDeSuprido(agruparPor) {
+    if (agruparPor === "suprido")
+        return ["grupos"];
+    if (agruparPor != null && CHAVES_POR_TIPO["atos-concessao"][agruparPor])
+        return [];
+    return ["top", "bottom"];
+}
+/**
+ * Proveniência de `senado_suprimento_fundos` com `estatisticas` em atos de concessão: os atos
+ * (`prov`, topo) são cruzados com o cadastro de supridos do ano (`/supridos/{ano}`, outra
+ * entrada de cache) para identificar cada beneficiário pelo NOME. Até a 3.18.1 o instante do
+ * cadastro era descartado. Agora, quando os nomes aparecem na resposta, os atos e o cadastro
+ * viram sub-fontes e o topo é o mais antigo (adaptador, contrato §3). Sem leitura do cadastro
+ * (falhou) ou sem campo com nome (agrupado por outra dimensão), o bloco fica o dos atos.
+ */
+export function provenanceSuprimentoComNomes(prov, atos, ano, admBaseUrl, nomes, agruparPor) {
+    const campos = camposComNomeDeSuprido(agruparPor);
+    if (!nomes.leitura || campos.length === 0)
+        return prov;
+    return withFieldSources(prov, [
+        {
+            fields: agruparPor === "suprido" ? ["total", "totalGrupos", "grupos"] : ["total", "distribuicao", "top", "bottom"],
+            source_url: prov.source_url,
+            dataset_id: prov.dataset.id ?? undefined,
+            reference_period: String(ano),
+            retrieved_at: prov.retrieved_at,
+            served_from_cache: atos.fromCache,
+        },
+        {
+            fields: campos,
+            source_url: `${admBaseUrl.replace(/\/$/, "")}/api/v1${PATHS["supridos"](ano)}`,
+            dataset_id: `suprimento; tipo=supridos; ano=${ano}`,
+            reference_period: String(ano),
+            ...leituraDoCache(nomes.leitura),
+        },
+    ]);
 }
 export function registerSupridosTools(server, admBaseUrl) {
     // R1. senado_suprimento_fundos
@@ -209,7 +253,7 @@ export function registerSupridosTools(server, admBaseUrl) {
         try {
             const tipo = params.tipo ?? "supridos";
             const path = PATHS[tipo](params.ano);
-            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_suprimento_fundos", { ano: params.ano, tipo }, CACHE_STATIC, () => admFetch(path, {}, admBaseUrl));
+            const { value: response, fetchedAt, fromCache } = await cachedFetchWithMeta("senado_suprimento_fundos", { ano: params.ano, tipo }, CACHE_STATIC, () => admFetch(path, {}, admBaseUrl));
             let lista = ensureArray(response);
             if (params.filtro) {
                 const f = params.filtro;
@@ -234,14 +278,14 @@ export function registerSupridosTools(server, admBaseUrl) {
                     }, prov);
                 }
                 // atos-concessao: join the supridos registry so entries carry the beneficiary's NAME.
-                const nomePorCodigo = tipo === "atos-concessao" ? await nomesSupridos(params.ano, admBaseUrl) : undefined;
+                const nomes = tipo === "atos-concessao" ? await nomesSupridos(params.ano, admBaseUrl) : undefined;
                 return resultWithProvenance({
                     ano: params.ano,
                     tipo,
                     modo: "estatisticas",
                     total: lista.length,
-                    ...estatisticasSuprimento(lista, { tipo, campo: params.campo, agruparPor: params.agruparPor, topN: params.topN ?? 10, nomePorCodigo }),
-                }, prov);
+                    ...estatisticasSuprimento(lista, { tipo, campo: params.campo, agruparPor: params.agruparPor, topN: params.topN ?? 10, nomePorCodigo: nomes?.nomes }),
+                }, nomes ? provenanceSuprimentoComNomes(prov, { fromCache }, params.ano, admBaseUrl, nomes, params.agruparPor) : prov);
             }
             return resultWithProvenance({
                 ano: params.ano,

package/dist/utils/provenance.js

@@ -78,6 +78,17 @@ const toCanonicalFieldSource = (fs) => ({
     dataset_id: fs.dataset_id ?? null,
     data_vintage: fs.reference_period ?? null,
     retrieved_at: fs.retrieved_at ?? null,
+    served_from_cache: fs.served_from_cache ?? null,
+});
+/**
+ * Instante e origem de uma leitura de `cachedFetchWithMeta`, nos nomes da sub-fonte:
+ * `{ retrieved_at, served_from_cache }`. Entrada de cache sem envelope (anterior ao
+ * `fetchedAt` persistido) volta com `fromCache: true` e o instante de AGORA — o `true`
+ * continua verdadeiro; o instante é o melhor que a camada sabe.
+ */
+export const leituraDoCache = (m) => ({
+    retrieved_at: m.fetchedAt,
+    served_from_cache: m.fromCache,
 });
 /**
  * `retrieved_at` do topo de uma resposta que funde sub-fontes: o MAIS ANTIGO entre o
@@ -237,6 +248,14 @@ export function provenanceArquimedesVotos(extra) {
  * tools cuja resposta funde campos de mais de um endpoint upstream — o `source_url` de topo
  * cobre o grosso do payload e cada `FieldSource` atribui os campos específicos à sua origem.
  * O envelope é re-validado inteiro no contrato (build).
+ *
+ * REGRA (decisão do dono, 13/10/2026): só entra como sub-fonte a leitura que VIRA CAMPO da
+ * resposta. Leitura só de resolução ou checagem — sigla→código da comissão, o id do processo
+ * antes da tramitação, a confirmação do pai em `senado_contratacao_detalhe` — fica de fora.
+ * Se entrasse, a regra do topo = mais antigo faria a resposta inteira dizer "dados de ontem"
+ * porque a tabela de siglas está em cache desde ontem, com os campos lidos agora (aviso falso
+ * de desatualização). Custo aceito: uma tradução errada por cache velho (código recriado na
+ * fonte) não aparece no bloco — risco baixo, os códigos são estáveis.
  */
 export function withFieldSources(prov, fieldSources) {
     if (fieldSources.length === 0)

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.18.0";
+export const VERSION = "3.18.2";
 export const USER_AGENT = `senado-br-mcp/${VERSION} (+https://senado.sidneybissoli.com; sbissoli76@gmail.com)`;

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "senado-br-mcp",
-  "version": "3.18.0",
+  "version": "3.18.2",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "senado",
+    "senado-federal",
+    "brazilian-senate",
+    "dados-abertos",
+    "open-data",
+    "brasil",
+    "brazil",
+    "legislativo",
+    "votacoes",
+    "materias-legislativas",
+    "ceaps",
+    "cota-parlamentar",
+    "e-cidadania",
+    "transparencia",
+    "cloudflare-workers"
+  ],
   "license": "MIT",
   "type": "module",
   "mcpName": "io.github.SidneyBissoli/senado-br-mcp-cloudflare",
@@ -61,7 +81,7 @@
     "@cloudflare/workers-types": "^5.20260830.1",
     "@modelcontextprotocol/client": "^2.0.0",
     "@sbissoli/mcp-evals": "^0.2.1",
-    "@sbissoli/mcp-surface": "^0.5.0",
+    "@sbissoli/mcp-surface": "^0.6.0",
     "@types/node": "^26.5.1",
     "agents": "^0.26.0",
     "exceljs": "^4.4.0",