CEP Claude Plugin

Plugin que integra o Claude à API pública ViaCEP, permitindo consultar endereços brasileiros a partir de um CEP — ou o inverso, o CEP a partir de UF + cidade + logradouro — diretamente na conversa, sem sair do Claude.

Origem. Este repositório é um template de referência, construído deliberadamente no mesmo padrão arquitetural observado nos plugins Claude Code de heitorrapcinski — em especial GovBR-Claude-Plugin (servidor MCP + skill por domínio, núcleo genérico reaproveitável, empacotamento .mcpb/.plugin, observabilidade desde o dia 1). O domínio aqui (ViaCEP) foi escolhido por ser público, simples e sem autenticação — ideal para servir de esqueleto para o seu próximo domínio.

O servidor MCP é a camada de acesso aos dados (sabe chamar a API); a skill /cep é a camada de interpretação (entende o pedido em português e escolhe a ferramenta e os parâmetros). Ao instalar o plugin, tudo é registrado automaticamente.

API base

REST/JSON, GET, sem autenticação.

Related MCP server: Brazilian ZIP Code Lookup

Requisitos

• Node.js 22 ou superior — para compilar o plugin (gerar os bundles). O plugin já compilado roda sem node_modules.

• App do Claude com suporte a plugins (Claude Code, ou Claude Desktop com a área de plugins em Customize).

Instalação

git clone https://github.com/emerson-rossi/cep-claude-plugin.git
cd cep-claude-plugin
npm install        # instala deps e compila os bundles (script "prepare")
npm run package     # gera build/cep-claude-plugin.plugin

O npm run package compila o servidor num bundle autossuficiente (build/viacep.cjs, com todas as dependências embutidas), empacota como MCPB (build/cep-viacep.mcpb) e monta o build/cep-claude-plugin.plugin — pronto para upload, sem node_modules.

No app do Claude, abra Personalizar → "Fazer upload de plugin local" e selecione build/cep-claude-plugin.plugin. O Claude lê o .claude-plugin/plugin.json e registra o servidor MCP (cep-viacep) e a skill /cep.

Desenvolvimento

npm install          # instala deps e gera o bundle
npm run dev:viacep   # roda o servidor direto do TypeScript (tsx), sem empacotar
npm run build        # regenera o bundle com esbuild
npm run mcpb         # gera o bundle MCPB (build/cep-viacep.mcpb)
npm run package      # gera build/cep-claude-plugin.plugin (mcpb embutido)
npm run typecheck    # checagem de tipos (tsc --noEmit)
npm test             # testes unitários (vitest)

Para iterar sem reinstalar o .plugin, rode npm run dev:viacep e inspecione com o MCP Inspector.

Estrutura

cep-claude-plugin/
├── .claude-plugin/plugin.json   # manifesto do plugin
├── skills/
│   └── cep/SKILL.md             # skill /cep (interpretação em linguagem natural)
├── src/
│   ├── core/                    # framework genérico (reaproveitável para qualquer API)
│   │   ├── types.ts             #   ApiDefinition, ToolDef, ParamDef
│   │   ├── http.ts              #   cliente HTTP + tratamento de erros
│   │   ├── logger.ts            #   observabilidade (stderr + arquivo, configurável)
│   │   ├── server.ts            #   gera o servidor MCP a partir de uma definição
│   │   └── version.ts
│   └── apis/
│       └── viacep/              # domínio de exemplo — troque por outro API aqui
│           ├── definition.ts    #   contrato das tools expostas
│           ├── domain.ts        #   regras específicas (validação de CEP, UFs)
│           └── index.ts         #   entrypoint do servidor MCP
├── test/                        # testes unitários (vitest)
├── build.mjs                    # esbuild (bundle do servidor)
├── mcpb.mjs                     # empacotamento (.mcpb)
├── package.mjs                  # empacotamento (.plugin, mcpb embutido)
├── .github/workflows/ci.yml     # typecheck + test + build em cada push/PR
└── build/                       # gerado, gitignored

Como trocar o domínio de exemplo por um seu

1. Duplique src/apis/viacep/ para src/apis/<seu-dominio>/ e ajuste definition.ts (tools/params) e domain.ts (regras locais, se houver).

2. Adicione a entrada em build.mjs (entries) e em mcpb.mjs (server).

3. Crie skills/<seu-dominio>/SKILL.md descrevendo quando/como usar as tools.

4. Ajuste .claude-plugin/plugin.json (nome, descrição, keywords) e este README.

5. npm run typecheck && npm test && npm run build antes de empacotar.

Nada em src/core/ deveria precisar mudar — é o framework genérico que o padrão original (GovBR/CAD) também mantém estável entre domínios.

Observabilidade (logs)

O servidor MCP registra suas chamadas de ferramenta para diagnóstico (latência, taxa de erro, timeouts). Como o servidor se comunica por stdio — onde o stdout é reservado ao protocolo JSON-RPC —, os logs vão para o stderr (capturado pelo Claude Code; visível com claude --debug ou no painel /mcp) e, opcionalmente, para um arquivo.

O arquivo fica fora do diretório de instalação do plugin (que é sobrescrito a cada update), com rotação simples ao passar de 5 MB. Se a pasta não puder ser criada, o servidor segue só com stderr — logging nunca derruba o servidor.

Licença

MIT — veja LICENSE.