senado-br-mcp 3.18.4 → 3.18.5

package/README.md

@@ -553,18 +553,24 @@ Coverage spans all four upstream sources, each with its own `source`/`citation`/
 - **Senado Federal — Execução Orçamentária e Financeira** — Arquimedes/Financeiro feed at `senado.gov.br`
 - **Senado Federal — Portal e-Cidadania** — `www12.senado.leg.br/ecidadania`
 
-Fields of the `concise` block (per response — one tool, one source; keys in this fixed order, `null` when the source does not expose the value):
+Fields of the `concise` block (contract v1.3 since 3.18.5; per response — one tool, one source; keys in this fixed order; the first seven are always present, with `null` when the source does not expose the value; the optional ones are **absent**, never empty, when they do not apply):
 
 | Field | Meaning |
 |-------|---------|
 | `source` | Official source name (e.g. *Senado Federal — Dados Abertos (Legislativo)*) |
 | `source_url` | Canonical endpoint/item URL consulted (e.g. `…/processo/{id}`) |
 | `data_vintage` | Vintage/competência of the data (e.g. `2024-03-15`, `2019`) — named `reference_period` before v3.5.0 |
-| `retrieved_at` | ISO-8601 of the **upstream extraction** — carried through the cache, so it reflects when the data was actually fetched, not the build or the cache-hit time |
+| `retrieved_at` | ISO-8601 of the **upstream extraction** — carried through the cache, so it reflects when the data was actually fetched, not the build or the cache-hit time; on merged responses, the oldest of the parts |
+| `retrieval` | Measured diagnostics of the trip to the source (attempts, outcome), or `null` when nothing was fetched in the call (pure cache, local data) — since 3.11.0 (v1.1) |
 | `citation` | Ready-to-use citation string (human-readable) |
 | `license` | Source terms (Dados Abertos do Senado Federal) |
+| `field_sources` | *Optional.* Per-field sub-sources, each with its own extraction instant — only on responses that merge reads (v1.2, since 3.17.0; see below) |
+| `derived` / `derivation_note` | *Optional.* `true` + a fixed note when the server computed the values — the `estatisticas` modes (distribution, aggregates, rankings) of `senado_remuneracoes_servidores`, `senado_horas_extras`, `senado_ceaps`, `senado_execucao_orcamentaria` and `senado_suprimento_fundos`; the individual values they cite remain the Senate's own |
+| `revision` | Whether the figure may still change at the source: `status` is `current` for every Senate source (the version in force at extraction; none is claimed `final`), and `note` says, for the administrative and budget sources, that the Senate may correct published data later |
 
-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.
+No Senate source publishes notices alongside the data, so `notices` (also part of v1.3) does not appear. The text footer gains a line only for exceptions — here, the computed-values line on the `estatisticas` modes.
+
+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.
 
 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.
 

package/dist/tools/materias.js

@@ -134,7 +134,7 @@ export function parseDocumentoProcesso(d) {
  * também entra como sub-fonte: o `retrieved_at` do topo é derivado pelo adaptador como o
  * MAIS ANTIGO das três (contrato §3) e, sem este item, o instante do detalhe sumiria do
  * bloco quando o resumo fosse mais velho. Antes da 3.17.0 o topo era o fetch do detalhe,
- * feito DEPOIS das sub-fontes — com a v1.2 ligada, a lib lançaria e a tool cairia.
+ * feito DEPOIS das sub-fontes — com a regra da v1.2 (que a 1.3 mantém), a lib lançaria e a tool cairia.
  */
 export function provenanceMateriaDetalhe(baseUrl, a) {
     const base = baseUrl.replace(/\/$/, "");

package/dist/tools/orcamento-senado.js

@@ -13,7 +13,7 @@ import { z } from "zod";
 import { cachedFetchWithMeta } from "../cache/manager.js";
 import { upstreamFetch } from "../throttle/upstream.js";
 import { errorFrom, ensureArray, safeInt, parseBRL } from "../utils/validation.js";
-import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { derivadoDeEstatisticas, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { computarEstatisticas, arredondarEstatisticas, arredondarEntradas, } from "../utils/estatisticas.js";
 import { CACHE_STATIC } from "../types.js";
 const FINANCEIRO_BASE = "https://www.senado.gov.br";
@@ -249,7 +249,7 @@ export function registerOrcamentoSenadoTools(server) {
                     ano: params.ano ?? null,
                     totalLinhas: itens.length,
                     ...estatisticasExecucao(itens, { tipo, campo: params.campo, agruparPor: params.agruparPor, topN: params.topN ?? 10 }),
-                }, prov);
+                }, derivadoDeEstatisticas(prov));
             }
             if (tipo === "despesas") {
                 let itens = ensureArray(bruto?.despesas).map(parseDespesa);

package/dist/tools/senadores-admin.js

@@ -12,7 +12,7 @@ import { cachedFetchWithMeta } from "../cache/manager.js";
 import { admFetch, admFetchLarge } from "../throttle/adm.js";
 import { errorFrom, ensureArray, normalizeText, parseBRL } from "../utils/validation.js";
 import { unwrapAdmEnvelope } from "../utils/upstream-parse.js";
-import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { derivadoDeEstatisticas, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { computarEstatisticas, arredondarEstatisticas, arredondarEntradas, } from "../utils/estatisticas.js";
 import { CACHE_SEMI_STATIC, CACHE_STATIC } from "../types.js";
 const norm = normalizeText;
@@ -157,7 +157,7 @@ export function registerSenadoresAdminTools(server, admBaseUrl) {
                     totalDespesas: filtrado.length,
                     valorTotal: totalGeral,
                     ...estatisticasCeaps(filtrado, { agruparPor: params.agruparPor, topN: params.topN ?? 10 }),
-                }, prov);
+                }, derivadoDeEstatisticas(prov));
             }
             const limite = params.limite ?? 100;
             const modo = params.modo ?? "por-senador";

package/dist/tools/servidores.js

@@ -12,7 +12,7 @@ import { cachedFetchWithMeta } from "../cache/manager.js";
 import { admFetch, admFetchLarge } from "../throttle/adm.js";
 import { errorFrom, ensureArray, parseBRL } from "../utils/validation.js";
 import { unwrapAdmEnvelope } from "../utils/upstream-parse.js";
-import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { derivadoDeEstatisticas, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { computarEstatisticas, arredondarEstatisticas, arredondarEntradas, } from "../utils/estatisticas.js";
 import { CACHE_SEMI_STATIC, CACHE_STATIC } from "../types.js";
 import { matchesFiltro, matchesFiltroCampo } from "./contratacoes.js";
@@ -342,7 +342,7 @@ export function particionarPorUnidade(lista, indice, codUnidade) {
  * organograma foi lido agora, o que também é. Com ele, o topo passa a ser o mais antigo
  * 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.
+ * novo que o snapshot — com a regra da v1.2 (que a 1.3 mantém), 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`).
@@ -473,7 +473,7 @@ export function registerServidoresTools(server, admBaseUrl) {
                         agruparPor: params.agruparPor,
                         topN: params.topN ?? 10,
                     }),
-                }, prov);
+                }, derivadoDeEstatisticas(prov));
             }
             if ((params.modo ?? "resumo") === "detalhe") {
                 const limite = params.limite ?? 50;
@@ -539,7 +539,7 @@ export function registerServidoresTools(server, admBaseUrl) {
                     total: itens.length,
                     valorTotal,
                     ...estatisticasHorasExtras(itens, { agruparPor: params.agruparPor, topN: params.topN ?? 10 }),
-                }, prov);
+                }, derivadoDeEstatisticas(prov));
             }
             return resultWithProvenance({
                 ano: params.ano,

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 { leituraDoCache, provenanceFor, resultWithProvenance, withFieldSources } from "../utils/provenance.js";
+import { derivadoDeEstatisticas, 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";
@@ -285,7 +285,7 @@ export function registerSupridosTools(server, admBaseUrl) {
                     modo: "estatisticas",
                     total: lista.length,
                     ...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);
+                }, derivadoDeEstatisticas(nomes ? provenanceSuprimentoComNomes(prov, { fromCache }, params.ano, admBaseUrl, nomes, params.agruparPor) : prov));
             }
             return resultWithProvenance({
                 ano: params.ano,

package/dist/utils/provenance.js

@@ -17,14 +17,16 @@
  *  - v1.1 (release 3.11.0): o concise tem 7 chaves fixas — `source`, `source_url`,
  *    `data_vintage` (ex-`reference_period`), `retrieved_at`, `citation`, `license` e
  *    `retrieval` (diagnóstico medido da ida à origem, ou `null`).
- *  - v1.2 (EMITIDA desde a release 3.17.0): acrescenta ao concise a chave opcional
- *    `field_sources` (sub-fontes por campo), só nas respostas que fundem recortes. Com
- *    ela a lib COBRA que o `retrieved_at` do topo seja o mais antigo entre as sub-fontes
- *    (lança `ProvenanceContractError`, o que derrubaria a tool) — por isso o adaptador
- *    o deriva por construção (`oldestRetrievedAt`), nunca a tool à mão.
- *  - v1.3 (declarada pelo `outputSchema` desde a 3.17.0, ainda NÃO emitida): `notices`,
- *    `derived`/`derivation_note` e `revision`. A `revision` já é informada aqui, por
- *    fonte (`SOURCES`), e a lib a descarta enquanto o servidor emitir 1.2.
+ *  - v1.2 (release 3.17.0): acrescenta ao concise a chave opcional `field_sources`
+ *    (sub-fontes por campo), só nas respostas que fundem recortes. Com ela a lib COBRA
+ *    que o `retrieved_at` do topo seja o mais antigo entre as sub-fontes (lança
+ *    `ProvenanceContractError`, o que derrubaria a tool) — por isso o adaptador o deriva
+ *    por construção (`oldestRetrievedAt`), nunca a tool à mão.
+ *  - v1.3 (EMITIDA desde a release 3.18.5; o `outputSchema` a aceitava desde a 3.17.0):
+ *    o concise leva `revision` SEMPRE (por fonte, em `SOURCES`) e `derived` +
+ *    `derivation_note` nos modos `estatisticas` (`derivadoDeEstatisticas`). `notices`
+ *    não sai: nenhuma fonte do senado publica aviso junto com o dado. Sem cálculo, as
+ *    chaves opcionais ficam AUSENTES, não vazias.
  *  - O rodapé de texto segue a redação fixada do contrato: linha de fonte
  *    ("Fonte: … · url · dados de … · extraído em …"), linha de licença e o aviso ao
  *    leitor de que a referência completa pode ser solicitada na própria conversa.
@@ -57,7 +59,7 @@ export const provenanceContext = createProvenanceContext({
     locale: "pt-BR",
     timezone: { offset: "-03:00", label: "horário de Brasília" },
     defaultMode: "concise",
-    contractVersion: "1.2",
+    contractVersion: "1.3",
 });
 const BRASILIA = provenanceContext.timezone;
 /**
@@ -134,7 +136,7 @@ const extraToCanonical = (extra = {}) => {
  * `current` em todas as fontes do senado, `final` em nenhuma — só com prova da fonte).
  * A `note` só repete o que o servidor JÁ diz nas instructions (`src/app-surface.ts`) sobre
  * os dados administrativos; nas demais fontes não há texto publicado, então `null`.
- * Enquanto o servidor emitir a v1.2 a lib descarta o campo do fio — fica no canônico.
+ * Sai no concise de toda resposta (v1.3).
  */
 const REVISAO_VIGENTE = { status: "current", note: null };
 const REVISAO_ADMINISTRATIVA = {
@@ -268,6 +270,24 @@ export function withFieldSources(prov, fieldSources) {
         field_sources: fieldSources.map(toCanonicalFieldSource),
     });
 }
+/**
+ * Nota fixa dos modos `estatisticas` (mesma redação do ibge-br-mcp, adaptada à fonte):
+ * a distribuição, os agregados e o ranking são cálculo deste servidor; cada valor
+ * individual citado é o que o Senado publica.
+ */
+export const NOTA_DERIVACAO_ESTATISTICAS = "Estatísticas (distribuição, agregados e rankings) computadas pelo servidor a partir dos registros brutos retornados pela fonte; os valores individuais permanecem os originais do Senado Federal.";
+/**
+ * Marca o bloco como derivado (contrato v1.3): `derived: true` + a nota fixa dos modos
+ * `estatisticas`. Aplique por último, sobre o bloco já completo (inclusive o de
+ * `withFieldSources`); o envelope é re-validado inteiro no contrato (build).
+ */
+export function derivadoDeEstatisticas(prov) {
+    return provenanceContext.build({
+        ...prov,
+        derived: true,
+        derivation_note: NOTA_DERIVACAO_ESTATISTICAS,
+    });
+}
 /** Rodapé de texto do contrato: fonte · url · vintage · extração, licença e aviso ao leitor. */
 export const provenanceFooter = (p) => provenanceContext.footer(p);
 /**

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.4";
+export const VERSION = "3.18.5";
 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.18.4",
+  "version": "3.18.5",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "keywords": [
     "mcp",