ibge-br-mcp 3.2.0 → 4.0.0

package/README.md

@@ -1,5 +1,3 @@
-[![Verified on MseeP](https://mseep.net/pr/sidneybissoli-ibge-br-mcp-badge.png)](https://mseep.ai/app/sidneybissoli-ibge-br-mcp)
-
 # IBGE Brasil MCP Server
 
 [![npm version](https://img.shields.io/npm/v/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
@@ -9,8 +7,8 @@
 [![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-ibge-br-mcp)](https://lobehub.com/mcp/sidneybissoli-ibge-br-mcp)
 [![smithery badge](https://smithery.ai/badge/sidneybissoli/ibge-br-mcp)](https://smithery.ai/server/sidneybissoli/ibge-br-mcp)
 [![ibge-br-mcp MCP server](https://glama.ai/mcp/servers/@SidneyBissoli/ibge-br-mcp/badges/score.svg)](https://glama.ai/mcp/servers/@SidneyBissoli/ibge-br-mcp)
-[![Tests](https://img.shields.io/badge/tests-456%20passed-brightgreen.svg)](https://github.com/SidneyBissoli/ibge-br-mcp)
-[![Coverage](https://img.shields.io/badge/coverage-core%2097%25-brightgreen.svg)](https://github.com/SidneyBissoli/ibge-br-mcp)
+[![CI](https://github.com/SidneyBissoli/ibge-br-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SidneyBissoli/ibge-br-mcp/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-%E2%89%A588%25-brightgreen.svg)](https://github.com/SidneyBissoli/ibge-br-mcp/blob/main/vitest.config.ts)
 [![GitHub stars](https://img.shields.io/github/stars/SidneyBissoli/ibge-br-mcp?style=flat&logo=github)](https://github.com/SidneyBissoli/ibge-br-mcp)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/SidneyBissoli?logo=githubsponsors&label=Sponsor&color=db61a2)](https://github.com/sponsors/SidneyBissoli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -25,25 +23,60 @@ This server implements the [Model Context Protocol (MCP)](https://modelcontextpr
 
 ## See it in action
 
-Ask your assistant, in plain Portuguese:
+Ask your assistant, in English or Portuguese:
 
-- *"Qual era a população de Belo Horizonte no Censo 2022?"* → `ibge_cidades` / `ibge_censo`
-- *"Liste os municípios do Espírito Santo."* → `ibge_municipios`
-- *"Compare o PIB per capita das capitais do Sudeste."* → `ibge_comparar`
+- *"What was Belo Horizonte's population in the 2022 Census?"* → `ibge_cidades` / `ibge_censo`
+- *"List the municipalities of Espírito Santo."* → `ibge_municipios`
+- *"Compare GDP across the Southeast state capitals."* → `ibge_comparar`
 
 The answers come live from the official IBGE APIs — exact figures with the table and period they came from, not numbers guessed from training data.
 
+Want to see a whole analysis rather than a single answer? The
+[**end-to-end demo**](docs/demo.md) works one real question — *which state grew
+most between the 2010 and 2022 Censuses, and what drove it* — from first call to
+conclusion, with every figure as it came back. The
+[**practical examples**](examples/README.md) are seven shorter recipes, including
+ranking all 5,570 municipalities in a single call.
+
 ## Features
 
-- **22 specialized tools** covering all major IBGE data domains
+- **21 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
+- **565 automated tests** — 88% overall coverage, 92% across the tools
 - **Automatic caching** with configurable TTL for optimal performance
 - **Retry mechanism** with exponential backoff for network resilience
 - **Comprehensive validation** for all input parameters
 - **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
@@ -83,7 +116,6 @@ The answers come live from the official IBGE APIs — exact figures with the tab
 ### Demographics
 | Tool | Description |
 |:-----|:------------|
-| `ibge_populacao` | Real-time Brazilian population projection |
 | `ibge_nomes` | Name frequency and rankings in Brazil |
 
 ### Classifications
@@ -110,13 +142,12 @@ The answers come live from the official IBGE APIs — exact figures with the tab
 
 ## Which tool should I use?
 
-With 22 tools, several can touch the same topic. Quick guide for the common overlaps:
+With 21 tools, several can touch the same topic. Quick guide for the common overlaps:
 
 ### Population & demographics
 
 | You want… | Use |
 |:----------|:----|
-| Brazil's population right now (real-time) | `ibge_populacao` |
 | A single municipality/state panel (population, HDI, GDP…) | `ibge_cidades` |
 | Census data or historical series (1970–2022) | `ibge_censo` |
 | Rank/compare 2–10 localities on one indicator | `ibge_comparar` |
@@ -189,7 +220,7 @@ Add to your Claude Desktop configuration file (`claude_desktop_config.json`):
   "mcpServers": {
     "ibge-br-mcp": {
       "command": "npx",
-      "args": ["ibge-br-mcp"]
+      "args": ["-y", "ibge-br-mcp"]
     }
   }
 }
@@ -215,7 +246,7 @@ Or if installed from source:
   "mcpServers": {
     "ibge-br-mcp": {
       "command": "npx",
-      "args": ["ibge-br-mcp"]
+      "args": ["-y", "ibge-br-mcp"]
     }
   }
 }
@@ -507,7 +538,6 @@ ibge-br-mcp/
 │       ├── localidade.ts     # ibge_localidade
 │       ├── geocodigo.ts      # ibge_geocodigo
 │       ├── censo.ts          # ibge_censo
-│       ├── populacao.ts      # ibge_populacao
 │       ├── sidra.ts          # ibge_sidra
 │       ├── sidra-tabelas.ts  # ibge_sidra_tabelas
 │       ├── sidra-metadados.ts# ibge_sidra_metadados
@@ -534,7 +564,7 @@ ibge-br-mcp/
 
 ## Testing
 
-The project includes a comprehensive test suite with 227 tests covering:
+The project includes a comprehensive test suite with 565 tests covering:
 
 - Validation functions
 - Retry mechanism
@@ -551,8 +581,8 @@ npm test
 
 This project maintains high code quality standards:
 
-- **227 automated tests** covering validation, caching, retry logic, formatting, and integrations
-- **97%+ test coverage** on core modules (cache, validation, errors, types)
+- **565 automated tests** covering validation, caching, retry logic, formatting, and integrations
+- **88% overall test coverage** — cache and validation modules above 97%
 - **ESLint** for code linting with zero warnings
 - **Prettier** for consistent code formatting
 - **TypeScript strict mode** for type safety

package/README.pt-BR.md

@@ -1,5 +1,3 @@
-[![Verified on MseeP](https://mseep.net/pr/sidneybissoli-ibge-br-mcp-badge.png)](https://mseep.ai/app/sidneybissoli-ibge-br-mcp)
-
 # ibge-br-mcp
 
 [![npm version](https://img.shields.io/npm/v/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
@@ -9,8 +7,8 @@
 [![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-ibge-br-mcp)](https://lobehub.com/mcp/sidneybissoli-ibge-br-mcp)
 [![smithery badge](https://smithery.ai/badge/sidneybissoli/ibge-br-mcp)](https://smithery.ai/server/sidneybissoli/ibge-br-mcp)
 [![ibge-br-mcp MCP server](https://glama.ai/mcp/servers/@SidneyBissoli/ibge-br-mcp/badges/score.svg)](https://glama.ai/mcp/servers/@SidneyBissoli/ibge-br-mcp)
-[![Tests](https://img.shields.io/badge/tests-456%20passed-brightgreen.svg)](https://github.com/SidneyBissoli/ibge-br-mcp)
-[![Coverage](https://img.shields.io/badge/coverage-core%2097%25-brightgreen.svg)](https://github.com/SidneyBissoli/ibge-br-mcp)
+[![CI](https://github.com/SidneyBissoli/ibge-br-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SidneyBissoli/ibge-br-mcp/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-%E2%89%A588%25-brightgreen.svg)](https://github.com/SidneyBissoli/ibge-br-mcp/blob/main/vitest.config.ts)
 [![GitHub stars](https://img.shields.io/github/stars/SidneyBissoli/ibge-br-mcp?style=flat&logo=github)](https://github.com/SidneyBissoli/ibge-br-mcp)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/SidneyBissoli?logo=githubsponsors&label=Sponsor&color=db61a2)](https://github.com/sponsors/SidneyBissoli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -29,15 +27,22 @@ Pergunte ao seu assistente, em português:
 
 - *"Qual era a população de Belo Horizonte no Censo 2022?"* → `ibge_cidades` / `ibge_censo`
 - *"Liste os municípios do Espírito Santo."* → `ibge_municipios`
-- *"Compare o PIB per capita das capitais do Sudeste."* → `ibge_comparar`
+- *"Compare o PIB das capitais do Sudeste."* → `ibge_comparar`
 
 As respostas vêm ao vivo das APIs oficiais do IBGE — valores exatos com a tabela e o período de onde vieram, não números chutados do treino.
 
+Quer ver uma análise inteira, e não uma resposta só? A
+[**demo ponta a ponta**](docs/demo.pt-BR.md) percorre uma pergunta real — *qual
+estado mais cresceu entre os Censos de 2010 e 2022, e o que puxou o crescimento*
+— da primeira chamada à conclusão, com cada número como ele voltou. Os
+[**exemplos práticos**](examples/README.pt-BR.md) são sete receitas mais curtas,
+entre elas ranquear os 5.570 municípios numa chamada só.
+
 ## Recursos
 
-- **22 ferramentas especializadas** cobrindo todos os principais domínios de dados do IBGE
+- **21 ferramentas especializadas** cobrindo todos os principais domínios de dados do IBGE
 - **Resources de referência & prompts de análise** (catálogos MCP + templates prontos)
-- **460 testes automatizados** com 97%+ de cobertura no core
+- **565 testes automatizados** — 88% de cobertura geral, 92% nas tools
 - **Cache automático** com TTL configurável para performance otimizada
 - **Mecanismo de retry** com backoff exponencial para resiliência de rede
 - **Validação abrangente** para todos os parâmetros de entrada
@@ -83,7 +88,6 @@ As respostas vêm ao vivo das APIs oficiais do IBGE — valores exatos com a tab
 ### Demografia
 | Ferramenta | Descrição |
 |:-----------|:----------|
-| `ibge_populacao` | Projeção populacional brasileira em tempo real |
 | `ibge_nomes` | Frequência e rankings de nomes no Brasil |
 
 ### Classificações
@@ -110,13 +114,12 @@ As respostas vêm ao vivo das APIs oficiais do IBGE — valores exatos com a tab
 
 ## Qual ferramenta usar?
 
-Com 22 ferramentas, várias podem tocar no mesmo assunto. Guia rápido para as sobreposições comuns:
+Com 21 ferramentas, várias podem tocar no mesmo assunto. Guia rápido para as sobreposições comuns:
 
 ### População e demografia
 
 | Você quer… | Use |
 |:-----------|:----|
-| População do Brasil agora (tempo real) | `ibge_populacao` |
 | Painel de um único município/UF (população, IDH, PIB…) | `ibge_cidades` |
 | Dados censitários ou série histórica (1970–2022) | `ibge_censo` |
 | Ranquear/comparar 2–10 localidades num indicador | `ibge_comparar` |
@@ -511,7 +514,6 @@ ibge-br-mcp/
 │       ├── localidade.ts     # ibge_localidade
 │       ├── geocodigo.ts      # ibge_geocodigo
 │       ├── censo.ts          # ibge_censo
-│       ├── populacao.ts      # ibge_populacao
 │       ├── sidra.ts          # ibge_sidra
 │       ├── sidra-tabelas.ts  # ibge_sidra_tabelas
 │       ├── sidra-metadados.ts# ibge_sidra_metadados
@@ -538,7 +540,7 @@ ibge-br-mcp/
 
 ## Testes
 
-O projeto inclui uma suíte de testes abrangente com 227 testes cobrindo:
+O projeto inclui uma suíte de testes abrangente com 565 testes cobrindo:
 
 - Funções de validação
 - Mecanismo de retry
@@ -555,8 +557,8 @@ npm test
 
 Este projeto mantém altos padrões de qualidade de código:
 
-- **227 testes automatizados** cobrindo validação, cache, retry, formatação e integrações
-- **97%+ de cobertura de testes** nos módulos core (cache, validation, errors, types)
+- **565 testes automatizados** cobrindo validação, cache, retry, formatação e integrações
+- **88% de cobertura de testes no total** — os módulos cache e validation acima de 97%
 - **ESLint** para linting de código sem warnings
 - **Prettier** para formatação consistente
 - **TypeScript modo strict** para segurança de tipos

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/config.d.ts

@@ -106,16 +106,16 @@ export declare const SIDRA_TABLES: {
     readonly POPULACAO_ESTIMATIVA: "6579";
     readonly POPULACAO_CENSO_2022: "9514";
     readonly POPULACAO_CENSOS_HISTORICO: "200";
-    readonly PIB_CORRENTE: "6706";
+    readonly PIB_CORRENTE: "1846";
     readonly PIB_PER_CAPITA: "5938";
-    readonly AREA_TERRITORIAL: "1705";
-    readonly DENSIDADE_DEMOGRAFICA: "1712";
-    readonly TAXA_DESOCUPACAO: "4714";
-    readonly RENDIMENTO_MEDIO: "6381";
-    readonly IPCA_MENSAL: "1737";
-    readonly IPCA_ACUMULADO: "1736";
-    readonly ALFABETIZACAO: "4312";
-    readonly DOMICILIOS: "4311";
+    readonly AREA_TERRITORIAL: "4714";
+    readonly DENSIDADE_DEMOGRAFICA: "4714";
+    readonly TAXA_DESOCUPACAO: "4099";
+    readonly RENDIMENTO_MEDIO: "5436";
+    readonly IPCA_MENSAL: "7060";
+    readonly IPCA_ACUMULADO: "1737";
+    readonly ALFABETIZACAO: "9543";
+    readonly DOMICILIOS: "4711";
 };
 /**
  * Regex patterns for validation

package/dist/config.js

@@ -271,19 +271,19 @@ export const SIDRA_TABLES = {
     POPULACAO_CENSO_2022: "9514",
     POPULACAO_CENSOS_HISTORICO: "200",
     // Economy
-    PIB_CORRENTE: "6706",
+    PIB_CORRENTE: "1846",
     PIB_PER_CAPITA: "5938",
-    AREA_TERRITORIAL: "1705",
-    DENSIDADE_DEMOGRAFICA: "1712",
+    AREA_TERRITORIAL: "4714",
+    DENSIDADE_DEMOGRAFICA: "4714",
     // Labor
-    TAXA_DESOCUPACAO: "4714",
-    RENDIMENTO_MEDIO: "6381",
+    TAXA_DESOCUPACAO: "4099",
+    RENDIMENTO_MEDIO: "5436",
     // Prices
-    IPCA_MENSAL: "1737",
-    IPCA_ACUMULADO: "1736",
+    IPCA_MENSAL: "7060",
+    IPCA_ACUMULADO: "1737",
     // Census themes
-    ALFABETIZACAO: "4312",
-    DOMICILIOS: "4311",
+    ALFABETIZACAO: "9543",
+    DOMICILIOS: "4711",
 };
 // ============================================================================
 // Validation Patterns

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;;;;;;;iBAYhC,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"}