ibge-br-mcp 3.2.0 → 3.3.0

package/README.md

@@ -36,6 +36,9 @@ The answers come live from the official IBGE APIs — exact figures with the tab
 ## Features
 
 - **22 specialized tools** covering all major IBGE data domains
+- **Provenance block on every response** — source, canonical URL, reference
+  period, real extraction timestamp, ready-to-use citation, and legal regime
+  (see [Data provenance](#data-provenance))
 - **Reference resources & analysis prompts** (MCP catalogs + ready-made templates)
 - **460 automated tests** with 97%+ core coverage
 - **Automatic caching** with configurable TTL for optimal performance
@@ -44,6 +47,31 @@ The answers come live from the official IBGE APIs — exact figures with the tab
 - **Standardized error handling** with helpful suggestions
 - **Full TypeScript support** with strict typing
 
+## Data provenance
+
+Since v3.3.0 every successful tool response carries a **provenance block**
+([portfolio contract v1.0](https://www.npmjs.com/package/@sbissoli/mcp-provenance)),
+so each number is citable, auditable, and reproducible. The block is emitted on
+three channels:
+
+1. `structuredContent.provenance` (parseable, visible to the model) — exactly
+   six keys: `source` (the IBGE API queried), `source_url` (canonical URL that
+   reproduces the query), `data_vintage` (reference period when the source
+   exposes one; `null` otherwise), `retrieved_at` (the REAL upstream extraction
+   instant, preserved across cache hits, Brasília time), `citation`
+   ("Fonte: IBGE — [pesquisa/tabela], [URL], extraído em [data]."), and
+   `license` — plus `attribution`, the canonical list of source URLs.
+2. `_meta` under `br.com.sidneybissoli.ibge/provenance` and `.../attribution`
+   (out-of-band mirror for audit/UI, zero model tokens).
+3. A compact text footer appended to the Markdown, for text-only clients.
+
+The IBGE APIs declare no license of their own; the legal regime is Brazil's
+open-data framework — Lei 12.527/2011 (LAI) and Decreto 8.777/2016
+(unrestricted reuse, free use, obligation limited to crediting the source).
+Statistics-mode responses (`estatisticas=true`) and `ibge_comparar` are marked
+`derived` with an explanatory note in the canonical block, since the
+aggregates are computed server-side from the raw IBGE values.
+
 ## Available Tools
 
 ### Localities & Geography

package/dist/cache.d.ts

@@ -2,8 +2,19 @@
  * Simple in-memory cache with TTL support for IBGE API requests
  */
 import { type RetryOptions } from "./retry.js";
+/**
+ * Metadata of the last `cachedFetch` call for a cache key: the REAL instant the
+ * data was extracted from the upstream (preserved across cache hits — it is the
+ * legally relevant extraction date for the provenance block) and whether that
+ * last call was served from cache.
+ */
+export interface FetchMeta {
+    retrievedAt: Date;
+    servedFromCache: boolean;
+}
 declare class RequestCache {
     private cache;
+    private fetchMeta;
     private defaultTTL;
     constructor(defaultTTLMinutes?: number);
     /**
@@ -26,6 +37,16 @@ declare class RequestCache {
      * Clear all cached data
      */
     clear(): void;
+    /** Records a real upstream fetch for a key (called by `cachedFetch` on a miss). */
+    recordFetch(key: string, retrievedAt: number): void;
+    /**
+     * Records a cache hit for a key, preserving the original fetch instant.
+     * Entries seeded via `set()` directly (tests) have no recorded fetch; the hit
+     * instant is the best available approximation then.
+     */
+    recordHit(key: string): void;
+    /** Fetch metadata of the last `cachedFetch` call for this key, if any. */
+    meta(key: string): FetchMeta | null;
     /**
      * Remove all expired entries
      */
@@ -53,5 +74,13 @@ export declare function cacheKey(base: string, params?: Record<string, string |
  * Fetch with cache support and automatic retry on network failures
  */
 export declare function cachedFetch<T>(url: string, cacheKeyStr: string, ttlMinutes?: number, retryOptions?: RetryOptions): Promise<T>;
+/**
+ * Fetch metadata of the last `cachedFetch` call for a cache key — the REAL
+ * upstream extraction instant (`retrieved_at` of the provenance contract v1.0,
+ * preserved across cache hits) and whether the last call was a cache hit.
+ * Query it right after `cachedFetch` with the same key; the ~40 existing call
+ * sites stay unchanged (parallel-map design, `ibge/docs/03` §3).
+ */
+export declare function lastFetchMeta(cacheKeyStr: string): FetchMeta | null;
 export {};
 //# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAO/D,cAAM,YAAY;IAChB,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,UAAU,CAAS;gBAEf,iBAAiB,GAAE,MAAW;IAI1C;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAY7B;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAQvD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;OAEG;IACH,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;CAO1C;AAGD,eAAO,MAAM,KAAK,cAAuB,CAAC;AAG1C,eAAO,MAAM,SAAS;;;;;CAKZ,CAAC;AAEX;;GAEG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC7D,MAAM,CAUR;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,CAAC,CAAC,CAoBZ"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAO/D;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,IAAI,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,cAAM,YAAY;IAChB,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,SAAS,CAA6E;IAC9F,OAAO,CAAC,UAAU,CAAS;gBAEf,iBAAiB,GAAE,MAAW;IAI1C;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAY7B;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAQvD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKzB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb,mFAAmF;IACnF,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAInD;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQ5B,0EAA0E;IAC1E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAMnC;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;OAEG;IACH,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;CAO1C;AAGD,eAAO,MAAM,KAAK,cAAuB,CAAC;AAG1C,eAAO,MAAM,SAAS;;;;;CAKZ,CAAC;AAEX;;GAEG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC7D,MAAM,CAUR;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAEnE"}

package/dist/cache.js

@@ -4,6 +4,7 @@
 import { fetchWithRetry } from "./retry.js";
 class RequestCache {
     cache = new Map();
+    fetchMeta = new Map();
     defaultTTL;
     constructor(defaultTTLMinutes = 15) {
         this.defaultTTL = defaultTTLMinutes * 60 * 1000;
@@ -42,12 +43,37 @@ class RequestCache {
      */
     delete(key) {
         this.cache.delete(key);
+        this.fetchMeta.delete(key);
     }
     /**
      * Clear all cached data
      */
     clear() {
         this.cache.clear();
+        this.fetchMeta.clear();
+    }
+    /** Records a real upstream fetch for a key (called by `cachedFetch` on a miss). */
+    recordFetch(key, retrievedAt) {
+        this.fetchMeta.set(key, { retrievedAt, servedFromCache: false });
+    }
+    /**
+     * Records a cache hit for a key, preserving the original fetch instant.
+     * Entries seeded via `set()` directly (tests) have no recorded fetch; the hit
+     * instant is the best available approximation then.
+     */
+    recordHit(key) {
+        const existing = this.fetchMeta.get(key);
+        this.fetchMeta.set(key, {
+            retrievedAt: existing?.retrievedAt ?? Date.now(),
+            servedFromCache: true,
+        });
+    }
+    /** Fetch metadata of the last `cachedFetch` call for this key, if any. */
+    meta(key) {
+        const m = this.fetchMeta.get(key);
+        if (!m)
+            return null;
+        return { retrievedAt: new Date(m.retrievedAt), servedFromCache: m.servedFromCache };
     }
     /**
      * Remove all expired entries
@@ -100,6 +126,7 @@ export async function cachedFetch(url, cacheKeyStr, ttlMinutes, retryOptions) {
     // Check cache first
     const cached = cache.get(cacheKeyStr);
     if (cached !== null) {
+        cache.recordHit(cacheKeyStr);
         return cached;
     }
     // Fetch from API with retry support
@@ -110,6 +137,17 @@ export async function cachedFetch(url, cacheKeyStr, ttlMinutes, retryOptions) {
     const data = (await response.json());
     // Store in cache
     cache.set(cacheKeyStr, data, ttlMinutes);
+    cache.recordFetch(cacheKeyStr, Date.now());
     return data;
 }
+/**
+ * Fetch metadata of the last `cachedFetch` call for a cache key — the REAL
+ * upstream extraction instant (`retrieved_at` of the provenance contract v1.0,
+ * preserved across cache hits) and whether the last call was a cache hit.
+ * Query it right after `cachedFetch` with the same key; the ~40 existing call
+ * sites stay unchanged (parallel-map design, `ibge/docs/03` §3).
+ */
+export function lastFetchMeta(cacheKeyStr) {
+    return cache.meta(cacheKeyStr);
+}
 //# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/provenance.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Provenance block (portfolio contract v1.0) — pt-BR adapter over
+ * `@sbissoli/mcp-provenance`. The canonical model, the `concise`/`detailed`
+ * projections, serialization determinism, timezone handling and the footer
+ * wording live in the package; this module binds them to the IBGE server:
+ *
+ *  - one `ProvenanceContext` for the whole server (namespace
+ *    `br.com.sidneybissoli.ibge`, pt-BR footer, Brasília time, `concise` mode);
+ *  - the source registry (`FONTES_IBGE`) — one entry per IBGE API consumed;
+ *  - the normative license block (no explicit license upstream — the legal
+ *    basis is LAI + Decreto 8.777/2016, verbatim verification `ibge/docs/01`,
+ *    2026-08-08). Never use the IBGE logo/brand;
+ *  - `provenienciaIbge(...)`, the per-call builder every tool uses. It pulls
+ *    the REAL extraction instant (`retrieved_at`) and `served_from_cache` from
+ *    the cache layer via `lastFetchMeta` (contract: cache hits keep the
+ *    original fetch instant — it is the legally relevant extraction date).
+ *
+ * Emission happens in `toMcpResult` (`structured.ts`): tools attach the
+ * canonical block to their `StructuredToolResult` and the handler emits the
+ * three channels — `structuredContent.provenance` + `attribution` (parseable,
+ * visible to the model), `_meta` under namespaced keys (out-of-band, zero
+ * model tokens), and the compact text footer appended to the Markdown.
+ *
+ * `derived` semantics (same rule as senado-br-mcp): raw data that is only
+ * filtered/paginated/reserialized → `false`; the D2 statistics modes
+ * (aggregation/rankings computed server-side) → `true` + `derivation_note`.
+ */
+import { z } from "zod";
+import { type CanonicalProvenance, type ConciseBlock } from "@sbissoli/mcp-provenance";
+/** Single provenance context for the server: `_meta` namespace, locale, timezone, mode. */
+export declare const provenanceContext: import("@sbissoli/mcp-provenance").ProvenanceContext;
+/** Canonical envelope v1.0 (post-validation). */
+export type Provenance = CanonicalProvenance;
+/** Namespaced `_meta` keys (stable — audit/UI consumers read by these keys). */
+export declare const PROVENANCE_META_KEY: string;
+export declare const ATTRIBUTION_META_KEY: string;
+/**
+ * Normative license block (shared by every response): the IBGE APIs declare no
+ * license of their own — the legal regime is LAI (Lei 12.527/2011) + Decreto
+ * 8.777/2016 (unrestricted reuse, free use, obligation limited to crediting
+ * the source). Verbatim verification: `ibge/docs/01`, 2026-08-08.
+ */
+export declare const IBGE_LICENSE: {
+    readonly id: null;
+    readonly name: "Dados abertos do Poder Executivo federal (Lei 12.527/2011; Decreto 8.777/2016)";
+    readonly url: null;
+    readonly terms_url: "https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2016/decreto/d8777.htm";
+    readonly verified_at: "2026-08-08";
+};
+/**
+ * Source registry — one entry per IBGE API this server consumes. `name` is
+ * what the concise projection shows as `source`; `endpoint` is the base URL
+ * actually queried. Text only, never the IBGE logo/brand (docs/01).
+ */
+export declare const FONTES_IBGE: {
+    readonly LOCALIDADES: {
+        readonly name: "IBGE — API de Localidades";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v1/localidades";
+    };
+    readonly SIDRA: {
+        readonly name: "IBGE — SIDRA (Banco de Tabelas Estatísticas)";
+        readonly endpoint: "https://apisidra.ibge.gov.br/values";
+    };
+    readonly AGREGADOS: {
+        readonly name: "IBGE — API de Agregados (SIDRA)";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v3/agregados";
+    };
+    readonly NOMES: {
+        readonly name: "IBGE — API de Nomes (Censo Demográfico 2010)";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v2/censos/nomes";
+    };
+    readonly MALHAS: {
+        readonly name: "IBGE — API de Malhas Geográficas";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v3/malhas";
+    };
+    readonly NOTICIAS: {
+        readonly name: "IBGE — API de Notícias";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v3/noticias";
+    };
+    readonly POPULACAO: {
+        readonly name: "IBGE — API de Projeções de População";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v1/projecoes/populacao";
+    };
+    readonly CNAE: {
+        readonly name: "IBGE — API CNAE";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v2/cnae";
+    };
+    readonly CALENDARIO: {
+        readonly name: "IBGE — API de Calendário de Divulgações";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v3/calendario";
+    };
+    readonly PAISES: {
+        readonly name: "IBGE — API de Países";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v1/paises";
+    };
+    readonly PESQUISAS: {
+        readonly name: "IBGE — API de Pesquisas (Cidades@)";
+        readonly endpoint: "https://servicodados.ibge.gov.br/api/v1/pesquisas";
+    };
+};
+export type FonteIbge = keyof typeof FONTES_IBGE;
+export interface ProvenienciaIbgeOptions {
+    /** Which IBGE API answered this response. */
+    fonte: FonteIbge;
+    /** The URL effectively queried (canonical reproduction of the request). */
+    url: string;
+    /**
+     * Cache key of the main `cachedFetch` call — used to pull the REAL upstream
+     * extraction instant and `served_from_cache` from the cache layer. Omit only
+     * for static catalogs maintained in code (contract: builder default).
+     */
+    chaveCache?: string;
+    /** "[pesquisa/tabela]" of the citation, e.g. "SIDRA, Tabela 6579 (Estimativas de população)". */
+    pesquisa: string;
+    /** Dataset identifier within the source (e.g. the SIDRA table code), when there is one. */
+    dataset?: string;
+    /** Reference period exposed by the source (SIDRA period); null/omitted when not exposed. */
+    dataVintage?: string | null;
+    /** D2 statistics modes: the server derived aggregates from the raw records. */
+    derivado?: {
+        nota: string;
+    };
+}
+/**
+ * Builds the canonical provenance block for one tool response. Citation
+ * follows the pattern fixed by the verbatim verification (docs/01):
+ * "Fonte: IBGE — [pesquisa/tabela], [URL], extraído em [data]."
+ */
+export declare function provenienciaIbge(opts: ProvenienciaIbgeOptions): Provenance;
+/** Fixed derivation note for the D2 statistics modes (estatisticas/agruparPor/topN). */
+export declare const NOTA_DERIVACAO_ESTATISTICAS = "Estat\u00EDsticas (distribui\u00E7\u00E3o, agregados e rankings) computadas pelo servidor a partir dos registros brutos retornados pela fonte; os valores individuais permanecem os originais do IBGE.";
+/**
+ * Reference period of a SIDRA-style result, extracted from the standard period
+ * column when the source exposes one (docs/03: "período SIDRA quando exposto;
+ * null senão"). Distinct values are joined as a deterministic range
+ * ("2022" or "2020–2023"); no period column → null.
+ */
+export declare function extrairPeriodoSidra(colunas: string[], registros: Array<Record<string, string>>): string | null;
+/** Concise projection of a block (the shape embedded in `structuredContent`/`_meta`). */
+export declare const provenanceBlockSchema: z.ZodObject<{
+    source: z.ZodString;
+    source_url: z.ZodString;
+    data_vintage: z.ZodNullable<z.ZodString>;
+    retrieved_at: z.ZodString;
+    citation: z.ZodString;
+    license: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Extends a tool's output schema with the provenance channel of the contract
+ * v1.0: the concise block + the `attribution` URL list (MCP RFC #711). Every
+ * successful response carries both (wired in `toMcpResult`).
+ */
+export declare function comProveniencia<T extends z.ZodObject<z.ZodRawShape>>(schema: T): z.ZodObject<{
+    readonly [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        source_url: z.ZodString;
+        data_vintage: z.ZodNullable<z.ZodString>;
+        retrieved_at: z.ZodString;
+        citation: z.ZodString;
+        license: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    attribution: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** Concise projection + attribution list for a block (used by `toMcpResult`). */
+export declare function projetarProveniencia(p: Provenance): {
+    provenance: ConciseBlock;
+    attribution: string[];
+};
+/** Compact text footer for the Markdown channel (fixed wording, contract v1.0). */
+export declare function rodapeProveniencia(p: Provenance): string;
+//# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAC;AAIlC,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,sDAK5B,CAAC;AAEH,iDAAiD;AACjD,MAAM,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAE7C,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,QAAwC,CAAC;AACzE,eAAO,MAAM,oBAAoB,QAAyC,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6Cd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AAajD,MAAM,WAAW,uBAAuB;IACtC,6CAA6C;IAC7C,KAAK,EAAE,SAAS,CAAC;IACjB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,UAAU,CAiB1E;AAED,wFAAwF;AACxF,eAAO,MAAM,2BAA2B,2MACmJ,CAAC;AAE5L;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,MAAM,GAAG,IAAI,CAYf;AAED,yFAAyF;AACzF,eAAO,MAAM,qBAAqB;;;;;;;iBAUhC,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;;;;;;;;;;;kBAS9E;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,UAAU,GAAG;IACnD,UAAU,EAAE,YAAY,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAEA;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAExD"}

package/dist/provenance.js

@@ -0,0 +1,191 @@
+/**
+ * Provenance block (portfolio contract v1.0) — pt-BR adapter over
+ * `@sbissoli/mcp-provenance`. The canonical model, the `concise`/`detailed`
+ * projections, serialization determinism, timezone handling and the footer
+ * wording live in the package; this module binds them to the IBGE server:
+ *
+ *  - one `ProvenanceContext` for the whole server (namespace
+ *    `br.com.sidneybissoli.ibge`, pt-BR footer, Brasília time, `concise` mode);
+ *  - the source registry (`FONTES_IBGE`) — one entry per IBGE API consumed;
+ *  - the normative license block (no explicit license upstream — the legal
+ *    basis is LAI + Decreto 8.777/2016, verbatim verification `ibge/docs/01`,
+ *    2026-08-08). Never use the IBGE logo/brand;
+ *  - `provenienciaIbge(...)`, the per-call builder every tool uses. It pulls
+ *    the REAL extraction instant (`retrieved_at`) and `served_from_cache` from
+ *    the cache layer via `lastFetchMeta` (contract: cache hits keep the
+ *    original fetch instant — it is the legally relevant extraction date).
+ *
+ * Emission happens in `toMcpResult` (`structured.ts`): tools attach the
+ * canonical block to their `StructuredToolResult` and the handler emits the
+ * three channels — `structuredContent.provenance` + `attribution` (parseable,
+ * visible to the model), `_meta` under namespaced keys (out-of-band, zero
+ * model tokens), and the compact text footer appended to the Markdown.
+ *
+ * `derived` semantics (same rule as senado-br-mcp): raw data that is only
+ * filtered/paginated/reserialized → `false`; the D2 statistics modes
+ * (aggregation/rankings computed server-side) → `true` + `derivation_note`.
+ */
+import { z } from "zod";
+import { attributionList, createProvenanceContext, renderConcise, } from "@sbissoli/mcp-provenance";
+import { lastFetchMeta } from "./cache.js";
+import { API_ENDPOINTS } from "./config.js";
+/** Single provenance context for the server: `_meta` namespace, locale, timezone, mode. */
+export const provenanceContext = createProvenanceContext({
+    metaNamespace: "br.com.sidneybissoli.ibge",
+    locale: "pt-BR",
+    timezone: { offset: "-03:00", label: "horário de Brasília" },
+    defaultMode: "concise",
+});
+/** Namespaced `_meta` keys (stable — audit/UI consumers read by these keys). */
+export const PROVENANCE_META_KEY = provenanceContext.metaKeys.provenance;
+export const ATTRIBUTION_META_KEY = provenanceContext.metaKeys.attribution;
+/**
+ * Normative license block (shared by every response): the IBGE APIs declare no
+ * license of their own — the legal regime is LAI (Lei 12.527/2011) + Decreto
+ * 8.777/2016 (unrestricted reuse, free use, obligation limited to crediting
+ * the source). Verbatim verification: `ibge/docs/01`, 2026-08-08.
+ */
+export const IBGE_LICENSE = {
+    id: null,
+    name: "Dados abertos do Poder Executivo federal (Lei 12.527/2011; Decreto 8.777/2016)",
+    url: null,
+    terms_url: "https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2016/decreto/d8777.htm",
+    verified_at: "2026-08-08",
+};
+/**
+ * Source registry — one entry per IBGE API this server consumes. `name` is
+ * what the concise projection shows as `source`; `endpoint` is the base URL
+ * actually queried. Text only, never the IBGE logo/brand (docs/01).
+ */
+export const FONTES_IBGE = {
+    LOCALIDADES: {
+        name: "IBGE — API de Localidades",
+        endpoint: API_ENDPOINTS.IBGE.LOCALIDADES,
+    },
+    SIDRA: {
+        name: "IBGE — SIDRA (Banco de Tabelas Estatísticas)",
+        endpoint: API_ENDPOINTS.SIDRA,
+    },
+    AGREGADOS: {
+        name: "IBGE — API de Agregados (SIDRA)",
+        endpoint: API_ENDPOINTS.IBGE.AGREGADOS,
+    },
+    NOMES: {
+        name: "IBGE — API de Nomes (Censo Demográfico 2010)",
+        endpoint: API_ENDPOINTS.IBGE.NOMES,
+    },
+    MALHAS: {
+        name: "IBGE — API de Malhas Geográficas",
+        endpoint: API_ENDPOINTS.IBGE.MALHAS,
+    },
+    NOTICIAS: {
+        name: "IBGE — API de Notícias",
+        endpoint: API_ENDPOINTS.IBGE.NOTICIAS,
+    },
+    POPULACAO: {
+        name: "IBGE — API de Projeções de População",
+        endpoint: API_ENDPOINTS.IBGE.POPULACAO,
+    },
+    CNAE: {
+        name: "IBGE — API CNAE",
+        endpoint: API_ENDPOINTS.IBGE.CNAE,
+    },
+    CALENDARIO: {
+        name: "IBGE — API de Calendário de Divulgações",
+        endpoint: API_ENDPOINTS.IBGE.CALENDARIO,
+    },
+    PAISES: {
+        name: "IBGE — API de Países",
+        endpoint: API_ENDPOINTS.IBGE.PAISES,
+    },
+    PESQUISAS: {
+        name: "IBGE — API de Pesquisas (Cidades@)",
+        endpoint: API_ENDPOINTS.IBGE.PESQUISAS,
+    },
+};
+/** "dd/mm/aaaa" of an instant in Brasília time, for the citation text. */
+function dataCitacao(retrievedAt) {
+    const iso = retrievedAt instanceof Date
+        ? // -03:00 fixed offset (Brazil has no DST since 2019).
+            new Date(retrievedAt.getTime() - 3 * 60 * 60 * 1000).toISOString()
+        : retrievedAt;
+    const [ano, mes, dia] = iso.slice(0, 10).split("-");
+    return `${dia}/${mes}/${ano}`;
+}
+/**
+ * Builds the canonical provenance block for one tool response. Citation
+ * follows the pattern fixed by the verbatim verification (docs/01):
+ * "Fonte: IBGE — [pesquisa/tabela], [URL], extraído em [data]."
+ */
+export function provenienciaIbge(opts) {
+    const fonte = FONTES_IBGE[opts.fonte];
+    const meta = opts.chaveCache ? lastFetchMeta(opts.chaveCache) : null;
+    const retrievedAt = meta?.retrievedAt ?? new Date();
+    return provenanceContext.build({
+        source: { name: fonte.name, agency: "IBGE", database: null, endpoint: fonte.endpoint },
+        source_url: opts.url,
+        ...(opts.dataset !== undefined ? { dataset: opts.dataset } : {}),
+        data_vintage: opts.dataVintage ?? null,
+        retrieved_at: retrievedAt,
+        citation: `Fonte: IBGE — ${opts.pesquisa}, ${opts.url}, extraído em ${dataCitacao(retrievedAt)}.`,
+        license: IBGE_LICENSE,
+        derived: opts.derivado !== undefined,
+        ...(opts.derivado !== undefined ? { derivation_note: opts.derivado.nota } : {}),
+        served_from_cache: meta ? meta.servedFromCache : null,
+    });
+}
+/** Fixed derivation note for the D2 statistics modes (estatisticas/agruparPor/topN). */
+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 IBGE.";
+/**
+ * Reference period of a SIDRA-style result, extracted from the standard period
+ * column when the source exposes one (docs/03: "período SIDRA quando exposto;
+ * null senão"). Distinct values are joined as a deterministic range
+ * ("2022" or "2020–2023"); no period column → null.
+ */
+export function extrairPeriodoSidra(colunas, registros) {
+    const candidatas = colunas.filter((c) => /^(ano|trimestre|m[eê]s|semestre|per[ií]odo)\b/i.test(c));
+    // SIDRA exposes "(Código)"/plain column pairs — prefer the readable label.
+    const idx = candidatas.find((c) => !/\(c[oó]digo\)/i.test(c)) ?? candidatas[0];
+    if (!idx)
+        return null;
+    const valores = [
+        ...new Set(registros.map((r) => r[idx]).filter((v) => Boolean(v))),
+    ].sort();
+    if (valores.length === 0)
+        return null;
+    return valores.length === 1 ? valores[0] : `${valores[0]}–${valores[valores.length - 1]}`;
+}
+/** Concise projection of a block (the shape embedded in `structuredContent`/`_meta`). */
+export const provenanceBlockSchema = z.object({
+    source: z.string().describe("Fonte oficial do dado (API do IBGE consultada)"),
+    source_url: z.string().describe("URL canônica que reproduz a consulta"),
+    data_vintage: z
+        .string()
+        .nullable()
+        .describe("Período de referência do dado segundo a fonte; null se a fonte não expõe"),
+    retrieved_at: z.string().describe("Instante real da extração no upstream (ISO-8601, horário de Brasília)"),
+    citation: z.string().describe("Citação pronta para uso"),
+    license: z.string().nullable().describe("Regime legal do dado"),
+});
+/**
+ * Extends a tool's output schema with the provenance channel of the contract
+ * v1.0: the concise block + the `attribution` URL list (MCP RFC #711). Every
+ * successful response carries both (wired in `toMcpResult`).
+ */
+export function comProveniencia(schema) {
+    return schema.extend({
+        provenance: provenanceBlockSchema.describe("Bloco de proveniência (contrato v1.0): fonte, URL, período, extração e licença"),
+        attribution: z
+            .array(z.string())
+            .describe("URLs canônicas das fontes desta resposta (lista de atribuição)"),
+    });
+}
+/** Concise projection + attribution list for a block (used by `toMcpResult`). */
+export function projetarProveniencia(p) {
+    return { provenance: renderConcise(p), attribution: attributionList([p]) };
+}
+/** Compact text footer for the Markdown channel (fixed wording, contract v1.0). */
+export function rodapeProveniencia(p) {
+    return provenanceContext.footer(p);
+}
+//# sourceMappingURL=provenance.js.map

package/dist/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAwB,MAAM,8BAA8B,CAAC;AAoF/E,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAYpB,CAAC;AAgBb;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAUxC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,YAAY,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAEzF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAk0B/E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAwB,MAAM,8BAA8B,CAAC;AAqF/E,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAYpB,CAAC;AAgBb;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAUxC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,YAAY,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAEzF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAk0B/E"}