brasil-data-mcp 0.2.0 → 0.3.0

package/README.md

@@ -7,9 +7,9 @@
 [![node](https://img.shields.io/node/v/brasil-data-mcp.svg)](https://nodejs.org)
 [![Glama MCP server](https://glama.ai/mcp/servers/alanpcf/brasil-data-mcp/badges/score.svg)](https://glama.ai/mcp/servers/alanpcf/brasil-data-mcp)
 
-> MCP server que expõe dados públicos brasileiros (CNPJ, CEP, bancos, feriados, DDD, ISBN, taxas econômicas, corretoras CVM) como tools pra Claude Desktop, Claude Code, Cursor, Windsurf e qualquer cliente compatível com [Model Context Protocol](https://modelcontextprotocol.io). Inclui também **prompts MCP** (workflows guiados).
+> MCP server que expõe dados públicos brasileiros (CNPJ, CEP, bancos, feriados, DDD, ISBN, taxas econômicas, câmbio, corretoras CVM, estados e municípios IBGE, domínios .br) como tools pra Claude Desktop, Claude Code, Cursor, Windsurf e qualquer cliente compatível com [Model Context Protocol](https://modelcontextprotocol.io). Inclui também **prompts MCP** (workflows guiados).
 >
-> _MCP server exposing Brazilian public data (CNPJ, CEP, banks, holidays, area codes, ISBN, economic rates, CVM brokers) as tools for Claude Desktop, Claude Code, Cursor, Windsurf and any MCP-compatible client. Ships with MCP prompts for guided workflows._
+> _MCP server exposing Brazilian public data (CNPJ, CEP, banks, holidays, area codes, ISBN, economic rates, exchange rates, CVM brokers, IBGE states/municipalities, .br domains) as tools for Claude Desktop, Claude Code, Cursor, Windsurf and any MCP-compatible client. Ships with MCP prompts for guided workflows._
 
 Powered by [BrasilAPI](https://brasilapi.com.br) — sem chave, sem auth, dados oficiais.
 
@@ -27,10 +27,13 @@ Conecte seu cliente de IA aos dados públicos brasileiros sem escrever uma linha
 - _"Me dá o livro do ISBN 9788532530802."_
 - _"Qual a SELIC hoje?"_
 - _"A corretora de CNPJ 02.332.886/0011-78 ainda tá ativa?"_
+- _"Quanto fechou o dólar sexta-feira?"_
+- _"Quais os municípios do Acre?"_
+- _"meuprojeto.com.br tá disponível?"_
 
 O Claude (ou outro cliente MCP) chama a tool, retorna o JSON estruturado, e você lê a resposta em português direto na conversa.
 
-### Tools disponíveis (10)
+### Tools disponíveis (15)
 
 | Tool                   | O que faz                                                                          |
 | ---------------------- | ---------------------------------------------------------------------------------- |
@@ -44,6 +47,11 @@ O Claude (ou outro cliente MCP) chama a tool, retorna o JSON estruturado, e voc
 | `consultar_taxa`       | Valor atual de taxa econômica (SELIC, CDI, IPCA) em % ao ano                       |
 | `listar_taxas`         | Panorama com todas as taxas econômicas vigentes                                    |
 | `consultar_corretora`  | Dados cadastrais de corretora de valores autorizada pela CVM (status, endereço)    |
+| `consultar_cambio`     | Cotação de câmbio (USD, EUR, +8 moedas) em BRL por data — boletins PTAX/BACEN      |
+| `listar_moedas`        | Moedas estrangeiras com cotação disponível (símbolo, nome, tipo)                   |
+| `listar_estados`       | As 27 UFs com código IBGE, nome, região e capital                                  |
+| `consultar_municipios` | Municípios de uma UF com nome e código IBGE de 7 dígitos                           |
+| `consultar_dominio_br` | Disponibilidade/status de domínio .br no registro.br (DNS, expiração, sugestões)   |
 
 ### Prompts disponíveis (2)
 
@@ -60,7 +68,7 @@ Prompts MCP são **workflows guiados** que aparecem como atalho no Claude Deskto
 
 Plug your AI client into Brazilian public data with zero code. Ask in natural language and the LLM picks the right tool, calls it, and answers you with structured data from official sources (Receita Federal, ViaCEP, BACEN, CVM, BrasilAPI).
 
-10 tools covering CNPJ, CEP, banks, holidays, area codes (DDD), ISBN, economic rates (SELIC/CDI/IPCA) and CVM brokers — plus 2 MCP prompts (`analise-cnpj`, `panorama-economico`) for guided workflows.
+15 tools covering CNPJ, CEP, banks, holidays, area codes (DDD), ISBN, economic rates (SELIC/CDI/IPCA), exchange rates (PTAX/BACEN), CVM brokers, IBGE states and municipalities, and .br domain availability — plus 2 MCP prompts (`analise-cnpj`, `panorama-economico`) for guided workflows.
 
 ---
 
@@ -145,6 +153,7 @@ Pra apontar seu cliente MCP pro build local em vez do pacote do npm:
 - [x] **Fase 2** — `consultar_cep`, `consultar_banco`, `listar_bancos`, `consultar_feriados` + testes Vitest
 - [x] **Fase 3** — CI (GitHub Actions), `CONTRIBUTING.md`, cobertura 94%/85%, publicação no [npm](https://www.npmjs.com/package/brasil-data-mcp), listagem no [Glama](https://glama.ai/mcp/servers/alanpcf/brasil-data-mcp)
 - [x] **Fase 4 (v0.2.0)** — `consultar_ddd`, `consultar_isbn`, `consultar_taxa` + `listar_taxas`, `consultar_corretora` (CVM) + MCP prompts (`analise-cnpj`, `panorama-economico`)
+- [x] **Fase 5 (v0.3.0)** — `consultar_cambio` + `listar_moedas` (PTAX/BACEN), `listar_estados` + `consultar_municipios` (IBGE), `consultar_dominio_br` (registro.br); versão single-source; registry declarativo de tools; testes do caminho de retry
 - [ ] **Próximo** — FIPE (aguardando upstream estabilizar, [BrasilAPI#805](https://github.com/BrasilAPI/BrasilAPI/issues/805)); Trusted Publishing (npm OIDC); mais prompts conforme demanda
 
 ---
@@ -163,7 +172,7 @@ Se você é dev brasileiro e usa LLM no dia a dia, esse server é pra você.
 
 Issues e PRs muito bem-vindos. Pra adicionar uma tool nova, siga o padrão de `src/tools/cnpj.ts` (schema Zod + descrição + handler) e registre em `src/index.ts`.
 
-Guia detalhado em `CONTRIBUTING.md` _(em breve)_.
+Guia detalhado em [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ---
 

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  *
  * Boot:
  *   1. Cria um McpServer (high-level API do SDK 1.x).
- *   2. Registra cada tool via registerTool — o SDK deriva o JSON Schema do
+ *   2. Registra cada tool do array TOOLS — o SDK deriva o JSON Schema do
  *      schema Zod, então atendemos "validação dupla" (Zod runtime + JSON
  *      Schema na definição) com uma única declaração por tool.
  *   3. Registra prompts (workflows) via registerPrompt.
@@ -15,9 +15,9 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * REGRA CRÍTICA: nunca escrever em stdout fora do protocolo. Logs em stderr
  * via console.error. console.log corrompe o canal MCP.
  *
- * REGISTRY: adicionar tool nova = uma chamada de registerTool. O helper
- * wrapHandler aplica o try/catch defensivo padronizado (bug numa tool não
- * derruba o server).
+ * REGISTRY: adicionar tool nova = uma entrada no array TOOLS. O loop de
+ * registro aplica o wrapHandler (try/catch defensivo padronizado — bug numa
+ * tool não derruba o server) uniformemente, sem risco de esquecer.
  */
 
 declare function createServer(): McpServer;

package/dist/index.js

@@ -85,12 +85,27 @@ function panoramaEconomicoHandler() {
 // src/tools/banco.ts
 import { z as z2 } from "zod";
 
+// src/version.ts
+import { readFileSync } from "fs";
+function lerVersao() {
+  try {
+    const raw = readFileSync(
+      new URL("../package.json", import.meta.url),
+      "utf-8"
+    );
+    return JSON.parse(raw).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var VERSION = lerVersao();
+
 // src/clients/brasilapi.ts
 var BASE_URL = "https://brasilapi.com.br/api";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
 var MAX_RETRIES = 3;
-var USER_AGENT = "brasil-data-mcp/0.2.0 (+https://github.com/alanpcf/brasil-data-mcp)";
+var USER_AGENT = `brasil-data-mcp/${VERSION} (+https://github.com/alanpcf/brasil-data-mcp)`;
 var BrasilApiError = class extends Error {
   constructor(message, status, path, body) {
     super(message);
@@ -308,10 +323,174 @@ async function listarBancosHandler(_input) {
   }
 }
 
-// src/tools/cep.ts
+// src/tools/cambio.ts
 import { z as z3 } from "zod";
-var consultarCepSchema = z3.object({
-  cep: z3.string().describe(
+var MOEDAS_VALIDAS = /* @__PURE__ */ new Set([
+  "AUD",
+  "CAD",
+  "CHF",
+  "DKK",
+  "EUR",
+  "GBP",
+  "JPY",
+  "NOK",
+  "SEK",
+  "USD"
+]);
+function hojeSaoPaulo() {
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: "America/Sao_Paulo"
+  }).format(/* @__PURE__ */ new Date());
+}
+function diaAnterior(iso) {
+  const d = /* @__PURE__ */ new Date(`${iso}T12:00:00Z`);
+  d.setUTCDate(d.getUTCDate() - 1);
+  return d.toISOString().slice(0, 10);
+}
+function normalizarData(entrada) {
+  const s = entrada.trim();
+  let iso;
+  const brasileira = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(s);
+  if (brasileira) {
+    iso = `${brasileira[3]}-${brasileira[2]}-${brasileira[1]}`;
+  } else if (/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+    iso = s;
+  } else {
+    return null;
+  }
+  const d = /* @__PURE__ */ new Date(`${iso}T12:00:00Z`);
+  if (Number.isNaN(d.getTime()) || d.toISOString().slice(0, 10) !== iso) {
+    return null;
+  }
+  return iso;
+}
+var consultarCambioSchema = z3.object({
+  moeda: z3.string().describe(
+    "C\xF3digo da moeda (ISO 4217), case-insensitive. Aceitas: USD, EUR, GBP, JPY, CHF, CAD, AUD, DKK, NOK, SEK. Ex: 'USD'."
+  ),
+  data: z3.string().optional().describe(
+    "Data da cota\xE7\xE3o no formato YYYY-MM-DD (aceita tamb\xE9m DD/MM/YYYY). Se omitida, usa ontem (fuso de Bras\xEDlia) \u2014 a fonte n\xE3o exp\xF5e o dia corrente. Em data sem preg\xE3o (fim de semana, feriado) a API retorna as cota\xE7\xF5es do \xFAltimo dia \xFAtil anterior."
+  )
+});
+var consultarCambioTool = {
+  name: "consultar_cambio",
+  description: [
+    "Consulta a cota\xE7\xE3o de c\xE2mbio oficial de uma moeda estrangeira em rela\xE7\xE3o ao Real (BRL) numa data, via boletins PTAX do Banco Central (BrasilAPI).",
+    "",
+    "Retorna em JSON os boletins do dia (ABERTURA, INTERMEDI\xC1RIO, FECHAMENTO) com cota\xE7\xE3o de compra e venda em BRL, paridade e data_hora_cotacao. A fonte N\xC3O exp\xF5e o dia corrente: com data omitida a tool consulta ontem (a cota\xE7\xE3o mais recente dispon\xEDvel), e em data sem preg\xE3o a API retorna os boletins do \xFAltimo dia \xFAtil anterior.",
+    "",
+    "Use quando o usu\xE1rio perguntar 'quanto t\xE1 o d\xF3lar?' (retorna a cota\xE7\xE3o mais recente, do dia \xFAtil anterior), 'cota\xE7\xE3o do euro em 26/06', 'quanto fechou a libra sexta-feira' \u2014 qualquer pergunta sobre valor de moeda estrangeira em reais.",
+    "",
+    "N\xC3O use para: criptomoedas (n\xE3o est\xE1 nesta API), BRL (\xE9 a moeda base), s\xE9rie hist\xF3rica (uma data por chamada), ou moedas fora das 10 suportadas \u2014 pra descobrir as moedas dispon\xEDveis use listar_moedas."
+  ].join(" "),
+  inputSchema: consultarCambioSchema
+};
+async function consultarCambioHandler(input) {
+  const moeda = input.moeda.trim().toUpperCase();
+  if (!MOEDAS_VALIDAS.has(moeda)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Moeda n\xE3o suportada: '${input.moeda}'. Use uma de: ${[...MOEDAS_VALIDAS].join(", ")}.`
+        }
+      ],
+      isError: true
+    };
+  }
+  const hoje = hojeSaoPaulo();
+  const ontem = diaAnterior(hoje);
+  let data;
+  if (input.data === void 0) {
+    data = ontem;
+  } else {
+    const normalizada = normalizarData(input.data);
+    if (normalizada === null) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Data inv\xE1lida: '${input.data}'. Use o formato YYYY-MM-DD (ex: ${ontem}) ou DD/MM/YYYY.`
+          }
+        ],
+        isError: true
+      };
+    }
+    data = normalizada;
+  }
+  if (data >= hoje) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `A fonte n\xE3o fornece cota\xE7\xE3o do dia corrente nem de datas futuras ('${data}'). A cota\xE7\xE3o mais recente dispon\xEDvel \xE9 a de ${ontem} \u2014 omita 'data' pra us\xE1-la.`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const dados = await brasilApi.get(
+      `/cambio/v1/cotacao/${moeda}/${data}`
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(dados, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            notFound: `Cota\xE7\xE3o de ${moeda} n\xE3o encontrada para ${data}.`,
+            contextoErro: "Erro ao consultar c\xE2mbio"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+var listarMoedasSchema = z3.object({});
+var listarMoedasTool = {
+  name: "listar_moedas",
+  description: [
+    "Lista as moedas estrangeiras com cota\xE7\xE3o dispon\xEDvel na BrasilAPI (boletins PTAX/BACEN).",
+    "",
+    "Retorna em JSON um array com s\xEDmbolo (ISO 4217), nome e tipo de cada moeda \u2014 10 moedas: USD, EUR, GBP, JPY, CHF, CAD, AUD, DKK, NOK, SEK.",
+    "",
+    "Use quando o usu\xE1rio quiser saber quais moedas t\xEAm cota\xE7\xE3o dispon\xEDvel ou n\xE3o souber o c\xF3digo da moeda.",
+    "",
+    "N\xC3O use para obter a cota\xE7\xE3o em si \u2014 use consultar_cambio."
+  ].join(" "),
+  inputSchema: listarMoedasSchema
+};
+async function listarMoedasHandler(_input) {
+  try {
+    const dados = await brasilApi.get("/cambio/v1/moedas");
+    return {
+      content: [{ type: "text", text: JSON.stringify(dados, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            notFound: "Lista de moedas n\xE3o dispon\xEDvel no momento.",
+            contextoErro: "Erro ao listar moedas"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/cep.ts
+import { z as z4 } from "zod";
+var consultarCepSchema = z4.object({
+  cep: z4.string().describe(
     "CEP brasileiro com ou sem h\xEDfen. Aceita '01310-100' ou '01310100'. Deve ter 8 d\xEDgitos."
   )
 });
@@ -371,7 +550,7 @@ async function consultarCepHandler(input) {
 }
 
 // src/tools/cnpj.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/utils/cnpj.ts
 function limparCnpj(s) {
@@ -384,8 +563,8 @@ function validarCnpj(s) {
 }
 
 // src/tools/cnpj.ts
-var consultarCnpjSchema = z4.object({
-  cnpj: z4.string().describe(
+var consultarCnpjSchema = z5.object({
+  cnpj: z5.string().describe(
     "CNPJ da empresa, com ou sem m\xE1scara. Aceita '12.345.678/0001-90' ou '12345678000190'. Deve ter 14 d\xEDgitos."
   )
 });
@@ -449,9 +628,9 @@ async function consultarCnpjHandler(input) {
 }
 
 // src/tools/corretoras.ts
-import { z as z5 } from "zod";
-var consultarCorretoraSchema = z5.object({
-  cnpj: z5.string().describe(
+import { z as z6 } from "zod";
+var consultarCorretoraSchema = z6.object({
+  cnpj: z6.string().describe(
     "CNPJ da corretora, com ou sem m\xE1scara. 14 d\xEDgitos. Ex: '02.332.886/0011-78' (XP Investimentos)."
   )
 });
@@ -505,9 +684,9 @@ async function consultarCorretoraHandler(input) {
 }
 
 // src/tools/ddd.ts
-import { z as z6 } from "zod";
-var consultarDddSchema = z6.object({
-  ddd: z6.union([z6.string(), z6.number()]).describe(
+import { z as z7 } from "zod";
+var consultarDddSchema = z7.object({
+  ddd: z7.union([z7.string(), z7.number()]).describe(
     "C\xF3digo DDD brasileiro (2 d\xEDgitos). Aceita string ou n\xFAmero. Ex: 11 (S\xE3o Paulo capital), 21 (Rio), 41 (Curitiba), 71 (Salvador)."
   )
 });
@@ -563,10 +742,76 @@ async function consultarDddHandler(input) {
   }
 }
 
+// src/tools/dominio.ts
+import { z as z8 } from "zod";
+function normalizarDominio(entrada) {
+  const semProtocolo = entrada.trim().toLowerCase().replace(/^https?:\/\//, "");
+  const semPath = semProtocolo.split("/")[0] ?? "";
+  return semPath.replace(/^www\./, "");
+}
+function validarDominioBr(dominio) {
+  return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*\.br$/.test(
+    dominio
+  );
+}
+var consultarDominioBrSchema = z8.object({
+  dominio: z8.string().describe(
+    "Dom\xEDnio .br a verificar. Aceita URL completa ou dom\xEDnio puro \u2014 ser\xE1 normalizado (remove http(s)://, www. e caminho). Ex: 'exemplo.com.br' ou 'https://www.exemplo.com.br/pagina'."
+  )
+});
+var consultarDominioBrTool = {
+  name: "consultar_dominio_br",
+  description: [
+    "Consulta o status de registro de um dom\xEDnio .br direto na base do registro.br (via BrasilAPI).",
+    "",
+    "Retorna em JSON: status (AVAILABLE = dispon\xEDvel pra registro, REGISTERED = j\xE1 registrado), fqdn, hosts (servidores DNS) e expires-at quando registrado, e suggestions de extens\xF5es quando dispon\xEDvel. O resultado nunca \xE9 cacheado \u2014 \xE9 sempre o status atual.",
+    "",
+    "Use quando o usu\xE1rio perguntar 'o dom\xEDnio X.com.br t\xE1 livre?', 'quando expira Y.org.br?', 'quem responde pelo DNS de Z.br?'.",
+    "",
+    "N\xC3O use para: dom\xEDnios internacionais .com/.net/gTLDs (a base \xE9 s\xF3 .br), dados de titular/whois completo (a API n\xE3o exp\xF5e), ou hospedagem/conte\xFAdo do site."
+  ].join(" "),
+  inputSchema: consultarDominioBrSchema
+};
+async function consultarDominioBrHandler(input) {
+  const dominio = normalizarDominio(input.dominio);
+  if (!validarDominioBr(dominio)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Dom\xEDnio inv\xE1lido: '${input.dominio}'. Esta tool s\xF3 consulta dom\xEDnios .br (registro.br). Ex: 'exemplo.com.br'.`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const dados = await brasilApi.get(`/registrobr/v1/${dominio}`, {
+      ttlMs: 0
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(dados, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            notFound: `Dom\xEDnio ${dominio} n\xE3o encontrado na base do registro.br.`,
+            contextoErro: "Erro ao consultar dom\xEDnio"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
 // src/tools/feriados.ts
-import { z as z7 } from "zod";
-var consultarFeriadosSchema = z7.object({
-  ano: z7.number().int().describe(
+import { z as z9 } from "zod";
+var consultarFeriadosSchema = z9.object({
+  ano: z9.number().int().describe(
     "Ano dos feriados, 4 d\xEDgitos. Faixa aceita: 1900 a 2199. Ex: 2026."
   )
 });
@@ -619,10 +864,128 @@ async function consultarFeriadosHandler(input) {
   }
 }
 
+// src/tools/ibge.ts
+import { z as z10 } from "zod";
+var UFS_VALIDAS = /* @__PURE__ */ new Set([
+  "AC",
+  "AL",
+  "AP",
+  "AM",
+  "BA",
+  "CE",
+  "DF",
+  "ES",
+  "GO",
+  "MA",
+  "MT",
+  "MS",
+  "MG",
+  "PA",
+  "PB",
+  "PR",
+  "PE",
+  "PI",
+  "RJ",
+  "RN",
+  "RS",
+  "RO",
+  "RR",
+  "SC",
+  "SP",
+  "SE",
+  "TO"
+]);
+var listarEstadosSchema = z10.object({});
+var listarEstadosTool = {
+  name: "listar_estados",
+  description: [
+    "Lista as 27 unidades federativas do Brasil (26 estados + DF) com dados do IBGE, via BrasilAPI.",
+    "",
+    "Retorna em JSON um array com id (c\xF3digo IBGE), sigla, nome, regi\xE3o (Norte/Nordeste/Centro-Oeste/Sudeste/Sul) e capital de cada UF.",
+    "",
+    "Use quando o usu\xE1rio precisar do c\xF3digo IBGE de um estado, agrupar estados por regi\xE3o, validar siglas de UF ou saber a capital.",
+    "",
+    "N\xC3O use para: munic\xEDpios (use consultar_municipios), dados demogr\xE1ficos ou populacionais (n\xE3o est\xE3o nesta API)."
+  ].join(" "),
+  inputSchema: listarEstadosSchema
+};
+async function listarEstadosHandler(_input) {
+  try {
+    const dados = await brasilApi.get("/ibge/uf/v1");
+    return {
+      content: [{ type: "text", text: JSON.stringify(dados, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            notFound: "Lista de estados n\xE3o dispon\xEDvel no momento.",
+            contextoErro: "Erro ao listar estados"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+var consultarMunicipiosSchema = z10.object({
+  uf: z10.string().describe(
+    "Sigla da unidade federativa, 2 letras, case-insensitive. Ex: 'SP', 'rj', 'DF'."
+  )
+});
+var consultarMunicipiosTool = {
+  name: "consultar_municipios",
+  description: [
+    "Lista todos os munic\xEDpios de uma UF brasileira com nome e c\xF3digo IBGE de 7 d\xEDgitos, via BrasilAPI.",
+    "",
+    "Retorna em JSON um array de {nome, codigo_ibge}. Aten\xE7\xE3o: estados grandes retornam listas longas (SP tem 645 munic\xEDpios, ~30KB) \u2014 prefira usar s\xF3 quando precisar da lista ou do c\xF3digo de um munic\xEDpio.",
+    "",
+    "Use quando o usu\xE1rio precisar do c\xF3digo IBGE de um munic\xEDpio ou listar as cidades de um estado.",
+    "",
+    "N\xC3O use para: buscar um munic\xEDpio por nome no pa\xEDs inteiro (a API s\xF3 filtra por UF \u2014 se souber o estado, consulte-o), endere\xE7os/CEP (use consultar_cep), ou dados populacionais."
+  ].join(" "),
+  inputSchema: consultarMunicipiosSchema
+};
+async function consultarMunicipiosHandler(input) {
+  const uf = input.uf.trim().toUpperCase();
+  if (!UFS_VALIDAS.has(uf)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `UF inv\xE1lida: '${input.uf}'. Use uma sigla de estado brasileiro, ex: SP, RJ, MG.`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const dados = await brasilApi.get(`/ibge/municipios/v1/${uf}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(dados, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            notFound: `Munic\xEDpios da UF ${uf} n\xE3o encontrados.`,
+            contextoErro: "Erro ao consultar munic\xEDpios"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
 // src/tools/isbn.ts
-import { z as z8 } from "zod";
-var consultarIsbnSchema = z8.object({
-  codigo: z8.string().describe(
+import { z as z11 } from "zod";
+var consultarIsbnSchema = z11.object({
+  codigo: z11.string().describe(
     "ISBN do livro, 10 ou 13 d\xEDgitos. Aceita com ou sem h\xEDfens. Ex: '978-85-325-3080-2' ou '9788532530802'."
   )
 });
@@ -682,10 +1045,10 @@ async function consultarIsbnHandler(input) {
 }
 
 // src/tools/taxas.ts
-import { z as z9 } from "zod";
+import { z as z12 } from "zod";
 var TTL_TAXAS_MS = 60 * 60 * 1e3;
-var consultarTaxaSchema = z9.object({
-  sigla: z9.string().describe(
+var consultarTaxaSchema = z12.object({
+  sigla: z12.string().describe(
     "Sigla da taxa, case-insensitive. Aceita: 'Selic' (taxa b\xE1sica de juros), 'CDI' (Certificado de Dep\xF3sito Interbanc\xE1rio), 'IPCA' (infla\xE7\xE3o oficial)."
   )
 });
@@ -741,7 +1104,7 @@ async function consultarTaxaHandler(input) {
     };
   }
 }
-var listarTaxasSchema = z9.object({});
+var listarTaxasSchema = z12.object({});
 var listarTaxasTool = {
   name: "listar_taxas",
   description: [
@@ -780,7 +1143,6 @@ async function listarTaxasHandler(_input) {
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
 function wrapHandler(toolName, handler) {
   return async (input) => {
     try {
@@ -799,91 +1161,39 @@ function wrapHandler(toolName, handler) {
     }
   };
 }
+var TOOLS = [
+  { tool: consultarCnpjTool, handler: consultarCnpjHandler },
+  { tool: consultarCepTool, handler: consultarCepHandler },
+  { tool: consultarBancoTool, handler: consultarBancoHandler },
+  { tool: listarBancosTool, handler: listarBancosHandler },
+  { tool: consultarFeriadosTool, handler: consultarFeriadosHandler },
+  { tool: consultarDddTool, handler: consultarDddHandler },
+  { tool: consultarIsbnTool, handler: consultarIsbnHandler },
+  { tool: consultarTaxaTool, handler: consultarTaxaHandler },
+  { tool: listarTaxasTool, handler: listarTaxasHandler },
+  { tool: consultarCorretoraTool, handler: consultarCorretoraHandler },
+  // Fase 5 (v0.3.0):
+  { tool: consultarCambioTool, handler: consultarCambioHandler },
+  { tool: listarMoedasTool, handler: listarMoedasHandler },
+  { tool: listarEstadosTool, handler: listarEstadosHandler },
+  { tool: consultarMunicipiosTool, handler: consultarMunicipiosHandler },
+  { tool: consultarDominioBrTool, handler: consultarDominioBrHandler }
+];
 function createServer() {
   const server = new McpServer({
     name: "brasil-data-mcp",
     version: VERSION
   });
-  server.registerTool(
-    consultarCnpjTool.name,
-    {
-      description: consultarCnpjTool.description,
-      inputSchema: consultarCnpjSchema.shape
-    },
-    wrapHandler(consultarCnpjTool.name, consultarCnpjHandler)
-  );
-  server.registerTool(
-    consultarCepTool.name,
-    {
-      description: consultarCepTool.description,
-      inputSchema: consultarCepSchema.shape
-    },
-    wrapHandler(consultarCepTool.name, consultarCepHandler)
-  );
-  server.registerTool(
-    consultarBancoTool.name,
-    {
-      description: consultarBancoTool.description,
-      inputSchema: consultarBancoSchema.shape
-    },
-    wrapHandler(consultarBancoTool.name, consultarBancoHandler)
-  );
-  server.registerTool(
-    listarBancosTool.name,
-    {
-      description: listarBancosTool.description,
-      inputSchema: listarBancosSchema.shape
-    },
-    wrapHandler(listarBancosTool.name, listarBancosHandler)
-  );
-  server.registerTool(
-    consultarFeriadosTool.name,
-    {
-      description: consultarFeriadosTool.description,
-      inputSchema: consultarFeriadosSchema.shape
-    },
-    wrapHandler(consultarFeriadosTool.name, consultarFeriadosHandler)
-  );
-  server.registerTool(
-    consultarDddTool.name,
-    {
-      description: consultarDddTool.description,
-      inputSchema: consultarDddSchema.shape
-    },
-    wrapHandler(consultarDddTool.name, consultarDddHandler)
-  );
-  server.registerTool(
-    consultarIsbnTool.name,
-    {
-      description: consultarIsbnTool.description,
-      inputSchema: consultarIsbnSchema.shape
-    },
-    wrapHandler(consultarIsbnTool.name, consultarIsbnHandler)
-  );
-  server.registerTool(
-    consultarTaxaTool.name,
-    {
-      description: consultarTaxaTool.description,
-      inputSchema: consultarTaxaSchema.shape
-    },
-    wrapHandler(consultarTaxaTool.name, consultarTaxaHandler)
-  );
-  server.registerTool(
-    listarTaxasTool.name,
-    {
-      description: listarTaxasTool.description,
-      inputSchema: listarTaxasSchema.shape
-    },
-    wrapHandler(listarTaxasTool.name, listarTaxasHandler)
-  );
-  server.registerTool(
-    consultarCorretoraTool.name,
-    {
-      description: consultarCorretoraTool.description,
-      inputSchema: consultarCorretoraSchema.shape
-    },
-    wrapHandler(consultarCorretoraTool.name, consultarCorretoraHandler)
-  );
+  for (const { tool, handler } of TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.inputSchema.shape
+      },
+      wrapHandler(tool.name, handler)
+    );
+  }
   server.registerPrompt(
     analiseCnpjPrompt.name,
     {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "brasil-data-mcp",
-  "version": "0.2.0",
-  "description": "MCP server providing access to Brazilian public data (CNPJ, CEP, banks, holidays, DDD, ISBN, economic rates, CVM brokers) via BrasilAPI. Ships with MCP prompts for guided workflows. For use with Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients.",
+  "version": "0.3.0",
+  "description": "MCP server providing access to Brazilian public data (CNPJ, CEP, banks, holidays, DDD, ISBN, economic rates, exchange rates, CVM brokers, IBGE states/municipalities, .br domains) via BrasilAPI. Ships with MCP prompts for guided workflows. For use with Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -15,6 +15,9 @@
     "selic",
     "cdi",
     "ipca",
+    "cambio",
+    "ibge",
+    "registro-br",
     "cvm",
     "brasilapi",
     "ai-tools"