brasil-data-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan Castriola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# brasil-data-mcp
+
+[![npm version](https://img.shields.io/npm/v/brasil-data-mcp.svg)](https://www.npmjs.com/package/brasil-data-mcp)
+[![license](https://img.shields.io/npm/l/brasil-data-mcp.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/brasil-data-mcp.svg)](https://nodejs.org)
+
+> MCP server que expõe dados públicos brasileiros (CNPJ, CEP, bancos, feriados) como tools pra Claude Desktop, Claude Code, Cursor, Windsurf e qualquer cliente compatível com [Model Context Protocol](https://modelcontextprotocol.io).
+>
+> _MCP server exposing Brazilian public data (CNPJ, CEP, banks, holidays) as tools for Claude Desktop, Claude Code, Cursor, Windsurf and any MCP-compatible client._
+
+Powered by [BrasilAPI](https://brasilapi.com.br) — sem chave, sem auth, dados oficiais.
+
+---
+
+## 🇧🇷 PT — O que é?
+
+Conecte seu cliente de IA aos dados públicos brasileiros sem escrever uma linha de código. Pergunte em linguagem natural:
+
+- _"Qual a razão social do CNPJ 33.000.167/0001-01?"_
+- _"Esse CEP 01310-100 é em qual cidade?"_
+- _"Quem é o banco com código 341?"_
+- _"Quais os feriados nacionais de 2026?"_
+
+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
+
+| Tool                  | O que faz                                                                       |
+| --------------------- | ------------------------------------------------------------------------------- |
+| `consultar_cnpj`      | Dados cadastrais de empresa: razão social, situação, endereço, sócios, CNAE     |
+| `consultar_cep`       | Endereço completo a partir de CEP (logradouro, bairro, cidade, UF, coordenadas) |
+| `consultar_banco`     | Nome e ISPB de banco brasileiro pelo código COMPE (ex: 341 = Itaú, 260 = Nubank) |
+| `listar_bancos`       | Lista completa de bancos brasileiros cadastrados no BACEN (~250 instituições)   |
+| `consultar_feriados`  | Feriados nacionais de um ano (datas, nome, tipo) — inclui Carnaval e Páscoa     |
+
+---
+
+## 🇺🇸 EN — What is it?
+
+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).
+
+Currently ships with `consultar_cnpj`. CEP, banks and holidays are landing next.
+
+---
+
+## 🚀 Instalação / Installation
+
+Todas as instruções abaixo usam `npx -y brasil-data-mcp`, o que baixa e roda a última versão sem instalação global.
+
+### Claude Desktop
+
+Edite o arquivo de configuração:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "brasil-data": {
+      "command": "npx",
+      "args": ["-y", "brasil-data-mcp"]
+    }
+  }
+}
+```
+
+Reinicie o Claude Desktop. Pronto.
+
+### Claude Code
+
+```bash
+claude mcp add brasil-data -- npx -y brasil-data-mcp
+```
+
+### Cursor
+
+Crie ou edite `.cursor/mcp.json` na raiz do projeto:
+
+```json
+{
+  "mcpServers": {
+    "brasil-data": {
+      "command": "npx",
+      "args": ["-y", "brasil-data-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Desenvolvimento / Development
+
+```bash
+git clone https://github.com/alanpcf/brasil-data-mcp.git
+cd brasil-data-mcp
+npm install
+
+npm run dev      # tsx watch — hot reload em desenvolvimento
+npm run lint     # tsc --noEmit
+npm run build    # tsup → dist/index.js
+npm test         # vitest
+```
+
+Pra apontar seu cliente MCP pro build local em vez do pacote do npm:
+
+```json
+{
+  "mcpServers": {
+    "brasil-data-local": {
+      "command": "node",
+      "args": ["/caminho/absoluto/para/brasil-data-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## 🗺️ Roadmap
+
+- [x] **Fase 1** — Esqueleto + cliente HTTP + `consultar_cnpj`
+- [x] **Fase 2** — `consultar_cep`, `consultar_banco`, `listar_bancos`, `consultar_feriados` + testes Vitest
+- [ ] **Fase 3** — CI (GitHub Actions), CONTRIBUTING.md, cobertura > 80%, publicação no npm
+- [ ] **Fase 4** — FIPE, DDD, ISBN, taxas (SELIC/CDI/IPCA), CVM, MCP prompts pra workflows
+
+---
+
+## 💡 Por que esse projeto existe
+
+A maior parte das ferramentas de IA é treinada e demonstrada com dados americanos: ZIP code, EIN, FedEx tracking. Quando um dev brasileiro quer perguntar pra um LLM "me dá o cadastro do CNPJ X", ou cai em scraping, ou monta uma integração HTTP no braço, ou desiste.
+
+`brasil-data-mcp` é o caminho mais curto: um único `npx` e o seu Claude (ou Cursor, ou Windsurf) já fala "português de dado público brasileiro". Tudo open source, MIT, sem chave, sem rate limit hostil — porque a [BrasilAPI](https://brasilapi.com.br) já fez o trabalho pesado de unificar e cachear dados oficiais.
+
+Se você é dev brasileiro e usa LLM no dia a dia, esse server é pra você.
+
+---
+
+## 🤝 Contribuindo / Contributing
+
+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)_.
+
+---
+
+Built with ❤️ in Brazil. Powered by [BrasilAPI](https://brasilapi.com.br).

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Entry point do brasil-data-mcp.
+ *
+ * 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
+ *      schema Zod, então atendemos "validação dupla" (Zod runtime + JSON
+ *      Schema na definição) com uma única declaração por tool.
+ *   3. Conecta no StdioServerTransport e fica em loop atendendo requisições.
+ *
+ * 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).
+ */
+
+declare function createServer(): McpServer;
+
+export { createServer };

package/dist/index.js

@@ -0,0 +1,504 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools/banco.ts
+import { z } from "zod";
+
+// 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.1.0 (+https://github.com/alanpcf/brasil-data-mcp)";
+var BrasilApiError = class extends Error {
+  constructor(message, status, path, body) {
+    super(message);
+    this.status = status;
+    this.path = path;
+    this.body = body;
+    this.name = "BrasilApiError";
+  }
+  status;
+  path;
+  body;
+};
+var cache = /* @__PURE__ */ new Map();
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function deveRetentar(status) {
+  if (status === null) return true;
+  if (status === 429) return true;
+  if (status >= 500 && status < 600) return true;
+  return false;
+}
+async function executarRequisicao(path, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${BASE_URL}${path}`, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        "User-Agent": USER_AGENT
+      },
+      signal: controller.signal
+    });
+    let body;
+    const text = await response.text();
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = text;
+    }
+    return { status: response.status, body, ok: response.ok };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function getInterno(path, opts) {
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (ttlMs > 0) {
+    const hit = cache.get(path);
+    if (hit && hit.expiresAt > Date.now()) {
+      return hit.value;
+    }
+  }
+  let ultimoErro;
+  for (let tentativa = 0; tentativa <= MAX_RETRIES; tentativa++) {
+    try {
+      const { status, body, ok } = await executarRequisicao(path, timeoutMs);
+      if (ok) {
+        if (ttlMs > 0) {
+          cache.set(path, { value: body, expiresAt: Date.now() + ttlMs });
+        }
+        return body;
+      }
+      if (!deveRetentar(status) || tentativa === MAX_RETRIES) {
+        throw new BrasilApiError(
+          `BrasilAPI retornou ${status} em ${path}`,
+          status,
+          path,
+          body
+        );
+      }
+      ultimoErro = new BrasilApiError(
+        `BrasilAPI ${status} (transiente)`,
+        status,
+        path,
+        body
+      );
+    } catch (err) {
+      if (err instanceof BrasilApiError) throw err;
+      ultimoErro = err;
+      if (tentativa === MAX_RETRIES) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new BrasilApiError(`Falha de rede em ${path}: ${msg}`, 0, path);
+      }
+    }
+    const delayMs = 200 * Math.pow(2, tentativa);
+    await sleep(delayMs);
+  }
+  throw ultimoErro instanceof Error ? ultimoErro : new Error(`Falha desconhecida em ${path}`);
+}
+var brasilApi = {
+  get(path, opts = {}) {
+    return getInterno(path, opts);
+  },
+  clearCache() {
+    cache.clear();
+  }
+};
+
+// src/utils/errors.ts
+function traduzirErroBrasilApi(err, mapa) {
+  const ctx = mapa.contextoErro ?? "Erro ao consultar dados";
+  if (err instanceof BrasilApiError) {
+    if (err.status === 404) return mapa.notFound;
+    if (err.status === 400) {
+      return `${ctx}: dados inv\xE1lidos enviados ao servi\xE7o.`;
+    }
+    if (err.status === 429) {
+      return `${ctx}: limite de requisi\xE7\xF5es temporariamente atingido. Tente novamente em alguns segundos.`;
+    }
+    if (err.status >= 500) {
+      return `${ctx}: servi\xE7o temporariamente indispon\xEDvel. Tente novamente em alguns instantes.`;
+    }
+    if (err.status === 0) {
+      return `${ctx}: falha de rede ao alcan\xE7ar o servi\xE7o.`;
+    }
+    return `${ctx}: o servi\xE7o retornou erro inesperado (${err.status}).`;
+  }
+  const msg = err instanceof Error ? err.message : String(err);
+  return `${ctx}: ${msg}`;
+}
+
+// src/tools/banco.ts
+var consultarBancoSchema = z.object({
+  codigo: z.union([z.string(), z.number()]).describe(
+    "C\xF3digo COMPE/Febraban do banco (1 a 4 d\xEDgitos). Aceita string ou n\xFAmero. Ex: 341 (Ita\xFA), 260 (Nubank), 237 (Bradesco)."
+  )
+});
+var consultarBancoTool = {
+  name: "consultar_banco",
+  description: [
+    "Consulta os dados de um banco brasileiro pelo c\xF3digo COMPE/Febraban via BrasilAPI (fonte: BACEN).",
+    "",
+    "Retorna em JSON: nome curto, nome completo, c\xF3digo, ISPB (identificador no SPB).",
+    "",
+    "Use quando o usu\xE1rio fornecer um c\xF3digo de banco e quiser saber o nome, ou quando precisar do ISPB pra montar um PIX/TED.",
+    "",
+    "N\xC3O use para: buscar banco por nome (use listar_bancos e filtre), validar conta corrente, ou consultar ag\xEAncia/conta. C\xF3digos comuns: 001=BB, 104=CEF, 237=Bradesco, 341=Ita\xFA, 260=Nubank, 077=Inter."
+  ].join(" "),
+  inputSchema: consultarBancoSchema
+};
+function normalizarCodigo(codigo) {
+  const s = String(codigo).trim();
+  if (!/^\d{1,4}$/.test(s)) return "";
+  return s;
+}
+async function consultarBancoHandler(input) {
+  const codigo = normalizarCodigo(input.codigo);
+  if (!codigo) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `C\xF3digo de banco inv\xE1lido: '${input.codigo}'. Deve ser num\xE9rico, de 1 a 4 d\xEDgitos.`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const dados = await brasilApi.get(`/banks/v1/${codigo}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(dados, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            notFound: `Banco com c\xF3digo ${codigo} n\xE3o encontrado no cadastro do BACEN.`,
+            contextoErro: "Erro ao consultar banco"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+var listarBancosSchema = z.object({});
+var listarBancosTool = {
+  name: "listar_bancos",
+  description: [
+    "Lista TODOS os bancos brasileiros cadastrados no BACEN via BrasilAPI.",
+    "",
+    "Retorna em JSON um array com nome, c\xF3digo COMPE/Febraban e ISPB de cada institui\xE7\xE3o.",
+    "",
+    "Use quando o usu\xE1rio quiser uma lista completa, buscar banco por nome (voc\xEA filtra o resultado), ou descobrir o c\xF3digo de um banco espec\xEDfico cujo nome ele forneceu.",
+    "",
+    "N\xC3O use quando o usu\xE1rio j\xE1 forneceu o c\xF3digo num\xE9rico \u2014 nesse caso use consultar_banco que \xE9 mais barato. A lista tem ~250 entradas; cite s\xF3 os relevantes na resposta."
+  ].join(" "),
+  inputSchema: listarBancosSchema
+};
+async function listarBancosHandler(_input) {
+  try {
+    const dados = await brasilApi.get("/banks/v1");
+    return {
+      content: [{ type: "text", text: JSON.stringify(dados, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            // Não há "404" semântico pra lista — se a API errar, todos
+            // caem no mesmo balde de "indisponível".
+            notFound: "Lista de bancos n\xE3o dispon\xEDvel no momento.",
+            contextoErro: "Erro ao listar bancos"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/cep.ts
+import { z as z2 } from "zod";
+var consultarCepSchema = z2.object({
+  cep: z2.string().describe(
+    "CEP brasileiro com ou sem h\xEDfen. Aceita '01310-100' ou '01310100'. Deve ter 8 d\xEDgitos."
+  )
+});
+var consultarCepTool = {
+  name: "consultar_cep",
+  description: [
+    "Consulta endere\xE7o completo a partir de um CEP brasileiro via BrasilAPI v2 (agrega ViaCEP, Postmon e outros provedores com fallback autom\xE1tico).",
+    "",
+    "Retorna em JSON: estado (UF), cidade, bairro, logradouro e, quando dispon\xEDvel, coordenadas geogr\xE1ficas.",
+    "",
+    "Use quando o usu\xE1rio pedir o endere\xE7o de um CEP, validar um CEP, ou descobrir cidade/UF a partir de um CEP.",
+    "",
+    "N\xC3O use para: c\xF3digos postais de outros pa\xEDses, descobrir CEP a partir de endere\xE7o (a opera\xE7\xE3o \xE9 s\xF3 CEP \u2192 endere\xE7o, n\xE3o inversa). Aceita CEP com ou sem h\xEDfen."
+  ].join(" "),
+  inputSchema: consultarCepSchema
+};
+function limparCep(s) {
+  return s.replace(/\D/g, "");
+}
+function validarCep(s) {
+  if (!/^\d{8}$/.test(s)) return false;
+  if (/^(\d)\1{7}$/.test(s)) return false;
+  return true;
+}
+async function consultarCepHandler(input) {
+  const cepLimpo = limparCep(input.cep);
+  if (!validarCep(cepLimpo)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `CEP inv\xE1lido: '${input.cep}'. Deve conter 8 d\xEDgitos (com ou sem h\xEDfen) e n\xE3o pode ser uma sequ\xEAncia repetida.`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const dados = await brasilApi.get(`/cep/v2/${cepLimpo}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(dados, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            notFound: `CEP ${cepLimpo} n\xE3o encontrado. Verifique se est\xE1 correto \u2014 alguns CEPs muito espec\xEDficos s\xF3 existem em provedores pagos.`,
+            contextoErro: "Erro ao consultar CEP"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/cnpj.ts
+import { z as z3 } from "zod";
+var consultarCnpjSchema = z3.object({
+  cnpj: z3.string().describe(
+    "CNPJ da empresa, com ou sem m\xE1scara. Aceita '12.345.678/0001-90' ou '12345678000190'. Deve ter 14 d\xEDgitos."
+  )
+});
+var consultarCnpjTool = {
+  name: "consultar_cnpj",
+  // Descrição é PRODUTO: é o que o LLM lê pra decidir quando chamar.
+  // Explicita o que retorna, quando usar e quando NÃO usar.
+  description: [
+    "Consulta dados cadastrais de uma empresa brasileira pelo CNPJ na Receita Federal (via BrasilAPI).",
+    "",
+    "Retorna em JSON: raz\xE3o social, nome fantasia, situa\xE7\xE3o cadastral (ativa/baixada/etc), data de abertura, ",
+    "endere\xE7o completo, CNAE principal e secund\xE1rios, s\xF3cios (QSA), capital social, natureza jur\xEDdica, ",
+    "porte (MEI/ME/EPP/Demais), telefones, e-mail, simples nacional/MEI.",
+    "",
+    "Use quando o usu\xE1rio pedir informa\xE7\xF5es sobre uma empresa identificada por CNPJ.",
+    "",
+    "N\xC3O use para: CPF (pessoa f\xEDsica), empresas estrangeiras, ou valida\xE7\xE3o local de formato ",
+    "(rejeite formato inv\xE1lido sem chamar a tool). Aceita CNPJ com ou sem m\xE1scara."
+  ].join(" "),
+  inputSchema: consultarCnpjSchema
+};
+function limparCnpj(s) {
+  return s.replace(/\D/g, "");
+}
+function validarCnpj(s) {
+  if (!/^\d{14}$/.test(s)) return false;
+  if (/^(\d)\1{13}$/.test(s)) return false;
+  return true;
+}
+async function consultarCnpjHandler(input) {
+  const cnpjLimpo = limparCnpj(input.cnpj);
+  if (!validarCnpj(cnpjLimpo)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `CNPJ inv\xE1lido: '${input.cnpj}'. Deve conter 14 d\xEDgitos (com ou sem m\xE1scara) e n\xE3o pode ser uma sequ\xEAncia repetida.`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const dados = await brasilApi.get(`/cnpj/v1/${cnpjLimpo}`);
+    return {
+      content: [
+        {
+          type: "text",
+          // JSON estruturado, não texto livre — o modelo extrai campos com
+          // mais confiabilidade quando recebe JSON.
+          text: JSON.stringify(dados, null, 2)
+        }
+      ]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            notFound: `CNPJ ${cnpjLimpo} n\xE3o encontrado na base da Receita Federal. Verifique se est\xE1 correto.`,
+            contextoErro: "Erro ao consultar CNPJ"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/feriados.ts
+import { z as z4 } from "zod";
+var consultarFeriadosSchema = z4.object({
+  ano: z4.number().int().describe(
+    "Ano dos feriados, 4 d\xEDgitos. Faixa aceita: 1900 a 2199. Ex: 2026."
+  )
+});
+var consultarFeriadosTool = {
+  name: "consultar_feriados",
+  description: [
+    "Lista os feriados NACIONAIS brasileiros de um ano espec\xEDfico via BrasilAPI.",
+    "",
+    "Retorna em JSON um array com data (YYYY-MM-DD), nome do feriado e tipo (national/optional). Inclui feriados m\xF3veis calculados (Carnaval, P\xE1scoa, Corpus Christi).",
+    "",
+    "Use quando o usu\xE1rio perguntar quando cai um feriado, listar feriados do ano, planejar emendas/pontes, ou calcular dias \xFAteis.",
+    "",
+    "N\xC3O use para: feriados estaduais ou municipais (a API s\xF3 cobre nacionais), datas comemorativas sem dia de folga (Dia das M\xE3es etc.), ou anos fora da faixa 1900-2199."
+  ].join(" "),
+  inputSchema: consultarFeriadosSchema
+};
+function validarAno(ano) {
+  return Number.isInteger(ano) && ano >= 1900 && ano <= 2199;
+}
+async function consultarFeriadosHandler(input) {
+  if (!validarAno(input.ano)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Ano inv\xE1lido: ${input.ano}. Deve ser inteiro entre 1900 e 2199.`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const dados = await brasilApi.get(`/feriados/v1/${input.ano}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(dados, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: traduzirErroBrasilApi(err, {
+            notFound: `Feriados de ${input.ano} n\xE3o encontrados na base.`,
+            contextoErro: "Erro ao consultar feriados"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+function wrapHandler(toolName, handler) {
+  return async (input) => {
+    try {
+      return await handler(input);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Erro interno na tool ${toolName}: ${msg}`
+          }
+        ],
+        isError: true
+      };
+    }
+  };
+}
+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)
+  );
+  return server;
+}
+async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`[brasil-data-mcp] v${VERSION} iniciado via stdio`);
+}
+main().catch((err) => {
+  console.error("[brasil-data-mcp] falha fatal:", err);
+  process.exit(1);
+});
+export {
+  createServer
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "brasil-data-mcp",
+  "version": "0.1.0",
+  "description": "MCP server providing access to Brazilian public data (CNPJ, CEP, banks, holidays) via BrasilAPI. For use with Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "brasil",
+    "brazil",
+    "cnpj",
+    "cep",
+    "brasilapi",
+    "ai-tools"
+  ],
+  "author": "Alan Castriola <alanpcf87@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alanpcf/brasil-data-mcp.git"
+  },
+  "homepage": "https://github.com/alanpcf/brasil-data-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/alanpcf/brasil-data-mcp/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "brasil-data-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --shims",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}