ibge-br-mcp 3.0.2 → 3.2.0

package/README.md

@@ -4,11 +4,16 @@
 
 [![npm version](https://img.shields.io/npm/v/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
+[![node](https://img.shields.io/node/v/ibge-br-mcp)](https://www.npmjs.com/package/ibge-br-mcp)
+[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
+[![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)
+[![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)
-[![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)
 
 **Live, exact Brazilian public data for your AI assistant — with provenance, not guesswork.**
 
@@ -18,6 +23,16 @@ Ask an LLM _"what was Belo Horizonte's population in the 2022 Census?"_ and you
 
 This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to give AI assistants live, structured access to Brazil's public geographic, demographic, economic, and health data — sourced from the IBGE APIs (including health indicators served through IBGE's SIDRA system).
 
+## See it in action
+
+Ask your assistant, in plain 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`
+
+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.
+
 ## Features
 
 - **22 specialized tools** covering all major IBGE data domains
@@ -107,6 +122,7 @@ With 22 tools, several can touch the same topic. Quick guide for the common over
 | Rank/compare 2–10 localities on one indicator | `ibge_comparar` |
 | A macro indicator time series (GDP, IPCA, unemployment…) | `ibge_indicadores` |
 | A specific SIDRA table / fine control | `ibge_sidra` |
+| The largest/smallest/mean/median across a whole table | `ibge_sidra`/`ibge_censo`/`ibge_indicadores`/`ibge_datasaude` with `estatisticas=true` |
 
 ### Economic indicators
 
@@ -309,6 +325,21 @@ ibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")
 | 127 | Legal Amazon |
 | 128 | Semi-arid |
 
+**Statistics mode** (also on `ibge_censo`, `ibge_indicadores`, `ibge_datasaude`):
+for largest/smallest/mean/median/distribution/ranking questions, pass
+`estatisticas=true` — the server computes the full distribution (min/max/mean/
+median/std-dev/labeled percentiles) over **all** rows before pagination and
+returns `top`/`bottom` rankings (`topN`, default 10). `agruparPor="<column
+label>"` ranks groups by descending sum, each with its own mini-distribution.
+
+```
+# Which state has the largest estimated population?
+ibge_sidra(tabela="6579", nivel_territorial="3", estatisticas=true)
+
+# Census 2022 population distribution grouped by state
+ibge_censo(ano="2022", tema="populacao", nivel_territorial="3", estatisticas=true, agruparPor="Unidade da Federação")
+```
+
 ### ibge_censo
 
 Query Census data (1970-2022).

package/README.pt-BR.md

@@ -4,11 +4,16 @@
 
 [![npm version](https://img.shields.io/npm/v/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
+[![node](https://img.shields.io/node/v/ibge-br-mcp)](https://www.npmjs.com/package/ibge-br-mcp)
+[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
+[![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)
+[![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)
-[![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)
 
 **Dados públicos brasileiros ao vivo e exatos para o seu assistente de IA — com procedência, não chute.**
 
@@ -18,6 +23,16 @@ Pergunte a um LLM _"qual era a população de Belo Horizonte no Censo 2022?"_ e
 
 Este servidor implementa o [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) para dar aos assistentes de IA acesso ao vivo e estruturado aos dados públicos geográficos, demográficos, econômicos e de saúde do Brasil — vindos das APIs do IBGE (inclusive os indicadores de saúde, servidos pelo SIDRA do IBGE).
 
+## Veja na prática
+
+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`
+
+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.
+
 ## Recursos
 
 - **22 ferramentas especializadas** cobrindo todos os principais domínios de dados do IBGE
@@ -107,6 +122,7 @@ Com 22 ferramentas, várias podem tocar no mesmo assunto. Guia rápido para as s
 | Ranquear/comparar 2–10 localidades num indicador | `ibge_comparar` |
 | Série temporal de indicador macro (PIB, IPCA, desemprego…) | `ibge_indicadores` |
 | Uma tabela SIDRA específica / controle fino | `ibge_sidra` |
+| O maior/menor/média/mediana de uma tabela inteira | `ibge_sidra`/`ibge_censo`/`ibge_indicadores`/`ibge_datasaude` com `estatisticas=true` |
 
 ### Indicadores econômicos
 
@@ -309,6 +325,22 @@ ibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")
 | 127 | Amazônia Legal |
 | 128 | Semiárido |
 
+**Modo estatístico** (também em `ibge_censo`, `ibge_indicadores`,
+`ibge_datasaude`): para perguntas de maior/menor/média/mediana/distribuição/
+ranking, passe `estatisticas=true` — o servidor computa a distribuição completa
+(mínimo/máximo/média/mediana/desvio-padrão/percentis rotulados) sobre **todos**
+os registros, antes da paginação, e devolve rankings `top`/`bottom` (`topN`,
+padrão 10). `agruparPor="<rótulo da coluna>"` ranqueia os grupos por soma
+decrescente, cada um com sua mini-distribuição.
+
+```
+# Qual estado tem a maior população estimada?
+ibge_sidra(tabela="6579", nivel_territorial="3", estatisticas=true)
+
+# Distribuição da população do Censo 2022 agrupada por UF
+ibge_censo(ano="2022", tema="populacao", nivel_territorial="3", estatisticas=true, agruparPor="Unidade da Federação")
+```
+
 ### ibge_censo
 
 Consulta dados censitários (1970-2022).

package/dist/index.js

@@ -1,21 +1,17 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
 /**
  * Entry point: build the IBGE MCP Server and serve it over STDIO.
  *
  * Server construction lives in `server.ts` (side-effect-free, testable); this
- * file only wires it to the STDIO transport — stdout is the MCP protocol
+ * file only wires it to the STDIO transport. `serveStdio` owns the connection:
+ * it pins one server instance from the factory per connection and serves both
+ * the modern and the 2025-era protocol openings. stdout is the MCP protocol
  * channel, so all logging goes to stderr.
  */
-async function main() {
-    const server = createServer();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
-}
-main().catch((error) => {
-    console.error("Fatal error:", error);
-    process.exit(1);
+serveStdio(() => createServer(), {
+    onerror: (error) => console.error("Transport error:", error),
 });
+console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;GAMG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAE9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,KAAK,cAAc,UAAU,CAAC,CAAC;AAC7D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;;;GAQG;AACH,UAAU,CAAC,GAAG,EAAE,CAAC,YAAY,EAAE,EAAE;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC;CAC7D,CAAC,CAAC;AAEH,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,KAAK,cAAc,UAAU,CAAC,CAAC"}

package/dist/prompts.d.ts

@@ -6,7 +6,7 @@
  * building a demographic profile — so users don't have to remember which tools
  * to chain.
  */
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 /** Registers all analysis-template prompts on the server. */
 export declare function registerPrompts(server: McpServer): void;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAczE,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6DvD"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAc9D,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6DvD"}

package/dist/prompts.js

@@ -24,7 +24,7 @@ export function registerPrompts(server) {
     server.registerPrompt("comparar-municipios", {
         title: "Comparar municípios",
         description: "Compara 2 a 10 localidades (municípios ou UFs) em um indicador e produz um ranking comentado.",
-        argsSchema: {
+        argsSchema: z.object({
             localidades: z
                 .string()
                 .describe("Localidades separadas por vírgula — códigos IBGE ou nomes (ex.: 'São Paulo, Rio de Janeiro, Belo Horizonte')"),
@@ -32,7 +32,7 @@ export function registerPrompts(server) {
                 .string()
                 .optional()
                 .describe("Indicador a comparar (ex.: populacao, pib, densidade, alfabetizacao). Padrão: populacao"),
-        },
+        }),
     }, ({ localidades, indicador }) => {
         const ind = indicador?.trim() || "populacao";
         return userMessage(`Compare as seguintes localidades pelo indicador "${ind}": ${localidades}.
@@ -47,11 +47,11 @@ Passos:
     server.registerPrompt("perfil-demografico", {
         title: "Perfil demográfico",
         description: "Monta um perfil demográfico de uma localidade combinando população, censo e indicadores socioeconômicos.",
-        argsSchema: {
+        argsSchema: z.object({
             localidade: z
                 .string()
                 .describe("Município ou UF — código IBGE ou nome (ex.: '3550308' ou 'São Paulo')"),
-        },
+        }),
     }, ({ localidade }) => userMessage(`Monte um perfil demográfico da localidade: ${localidade}.
 
 Passos:

package/dist/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,6EAA6E;AAC7E,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAe;gBACrB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE;aACzC;SACF;KACF,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,iDAAiD;IACjD,MAAM,CAAC,cAAc,CACnB,qBAAqB,EACrB;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,+FAA+F;QACjG,UAAU,EAAE;YACV,WAAW,EAAE,CAAC;iBACX,MAAM,EAAE;iBACR,QAAQ,CACP,8GAA8G,CAC/G;YACH,SAAS,EAAE,CAAC;iBACT,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,yFAAyF,CAC1F;SACJ;KACF,EACD,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,EAAE;QAC7B,MAAM,GAAG,GAAG,SAAS,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC;QAC7C,OAAO,WAAW,CAChB,oDAAoD,GAAG,MAAM,WAAW;;;;6FAIa,GAAG;;0FAEN,CACnF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,+CAA+C;IAC/C,MAAM,CAAC,cAAc,CACnB,oBAAoB,EACpB;QACE,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EACT,0GAA0G;QAC5G,UAAU,EAAE;YACV,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,CAAC,uEAAuE,CAAC;SACrF;KACF,EACD,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CACjB,WAAW,CACT,8CAA8C,UAAU;;;;;;;iJAOiF,CAC1I,CACJ,CAAC;AACJ,CAAC"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,6EAA6E;AAC7E,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAe;gBACrB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE;aACzC;SACF;KACF,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,iDAAiD;IACjD,MAAM,CAAC,cAAc,CACnB,qBAAqB,EACrB;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,+FAA+F;QACjG,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC;YACnB,WAAW,EAAE,CAAC;iBACX,MAAM,EAAE;iBACR,QAAQ,CACP,8GAA8G,CAC/G;YACH,SAAS,EAAE,CAAC;iBACT,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,yFAAyF,CAC1F;SACJ,CAAC;KACH,EACD,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,EAAE;QAC7B,MAAM,GAAG,GAAG,SAAS,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC;QAC7C,OAAO,WAAW,CAChB,oDAAoD,GAAG,MAAM,WAAW;;;;6FAIa,GAAG;;0FAEN,CACnF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,+CAA+C;IAC/C,MAAM,CAAC,cAAc,CACnB,oBAAoB,EACpB;QACE,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EACT,0GAA0G;QAC5G,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC;YACnB,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,CAAC,uEAAuE,CAAC;SACrF,CAAC;KACH,EACD,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CACjB,WAAW,CACT,8CAA8C,UAAU;;;;;;;iJAOiF,CAC1I,CACJ,CAAC;AACJ,CAAC"}

package/dist/resources.d.ts

@@ -6,7 +6,7 @@
  * codes, biome codes — without guessing or spending a tool round-trip. Each is
  * a static `ibge://catalogos/...` resource returning JSON.
  */
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 /** Registers all reference-catalog resources on the server. */
 export declare function registerResources(server: McpServer): void;
 //# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAwFzE,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmEzD"}
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAwF9D,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmEzD"}

package/dist/server.d.ts

@@ -1,6 +1,14 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 export declare const SERVER_NAME = "ibge-br-mcp";
-export declare const SERVER_VERSION = "3.0.2";
+export declare const SERVER_VERSION: string;
+/**
+ * Server instructions sent on the MCP handshake (initialize result). They carry
+ * what individual tool descriptions cannot: the disambiguation map across the
+ * overlapping tool clusters and the cross-tool guidance for the D2 statistics
+ * modes. User-facing → pt-BR (repo convention). Shared verbatim by the STDIO
+ * entry (`createServer`) and the Cloudflare Worker (`worker/src/server.ts`).
+ */
+export declare const SERVER_INSTRUCTIONS: string;
 /**
  * Builds and configures the IBGE MCP Server with all tools, resources, and
  * prompts registered. Side-effect-free: it does NOT connect a transport, so it
@@ -10,11 +18,19 @@ export declare const SERVER_VERSION = "3.0.2";
  * Statistics) APIs (health data is served via IBGE's SIDRA).
  */
 export declare function createServer(): McpServer;
+/**
+ * Optional per-tool usage hook: called with `tool_call` on every invocation and
+ * additionally with `tool_error` when the call fails (error result or throw).
+ * The STDIO entry passes nothing; the Cloudflare Worker passes its Durable
+ * Object recorder (fire-and-forget telemetry — names and counts only, never
+ * tool arguments or results).
+ */
+export type ToolUsageRecorder = (kind: "tool_call" | "tool_error", name: string) => void;
 /**
  * Registers every tool, resource, and prompt onto a given `McpServer`. Kept
  * separate from `createServer` so an alternative transport (e.g. the Cloudflare
  * Worker in `worker/`, which builds its own `McpServer` with hosted metadata)
  * can reuse the exact same registrations.
  */
-export declare function registerAll(server: McpServer): void;
+export declare function registerAll(server: McpServer, record?: ToolUsageRecorder): void;
 //# sourceMappingURL=server.d.ts.map

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,EAAE,MAAM,yCAAyC,CAAC;AAkFpE,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,cAAc,UAAU,CAAC;AAgBtC;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAOxC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAg0BnD"}
+{"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"}