# ViaCEP Brasil MCP Server

![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-5.7%2B-3178C6?style=flat-square&logo=typescript&logoColor=white)
![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.x-blueviolet?style=flat-square)
![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)

O **ViaCEP Brasil MCP Server** conecta ferramentas de IA à API gratuita [ViaCEP](https://viacep.com.br/), permitindo consultar CEPs e endereços de todo o Brasil via linguagem natural.

Com ele, agentes de IA, assistentes e chatbots podem:

- Recuperar o endereço completo a partir de um CEP
- Descobrir o CEP de um endereço a partir de estado, cidade e logradouro
- Validar e enriquecer dados de endereço brasileiro com informações do IBGE, DDD, SIAFI e GIA

---

## Ferramentas disponíveis (Tools)

### 🔍 `buscar_endereco_por_cep`

Consulta informações completas de um endereço brasileiro a partir do CEP.

| Parâmetro | Tipo   | Obrigatório | Descrição                                                           |
| --------- | ------ | ----------- | ------------------------------------------------------------------- |
| `cep`     | string | ✅ Sim      | CEP com 8 dígitos, com ou sem hífen (ex: `01001-000` ou `01001000`) |

**Retorna:** CEP formatado, logradouro, complemento, unidade, bairro, localidade, UF, estado, região, DDD, código IBGE, GIA e SIAFI.

**Exemplo de resposta:**

```
✅ Endereço encontrado para o CEP 01001000:

📮 CEP: 01001-000
📍 Logradouro: Praça da Sé, lado ímpar
🏘️  Bairro: Sé
🏙️  Cidade: São Paulo - SP
🗺️  Estado: São Paulo
🌎 Região: Sudeste
📞 DDD: 11
🏛️  Código IBGE: 3550308
💼 GIA: 1004
🔖 SIAFI: 7107
```

---

### 🗺️ `buscar_cep_por_endereco`

Pesquisa CEPs brasileiros a partir de informações de endereço. Retorna até **50 resultados**, ordenados por proximidade do nome do logradouro.

| Parâmetro    | Tipo   | Obrigatório | Descrição                                                 |
| ------------ | ------ | ----------- | --------------------------------------------------------- |
| `uf`         | string | ✅ Sim      | Sigla do estado com 2 letras (ex: `SP`, `RJ`, `RS`, `MG`) |
| `cidade`     | string | ✅ Sim      | Nome da cidade — mínimo de 3 caracteres                   |
| `logradouro` | string | ✅ Sim      | Nome do logradouro/rua — mínimo de 3 caracteres           |

**Retorna:** lista de CEPs com logradouro, bairro e cidade correspondentes.

**Exemplo de resposta:**

```
Busca por: Paulista, São Paulo/SP

✅ 4 endereço(s) encontrado(s):
──────────────────────────────────────────────────
[1] CEP: 01311-300
    Logradouro: Avenida Paulista (de 1 a 610 - lado par)
    Bairro: Bela Vista
    Cidade: São Paulo - SP
...
```

---

## Instalação

### Pré-requisitos

- [Node.js](https://nodejs.org/) 18 ou superior
- npm 9 ou superior
- (Opcional) [Docker](https://www.docker.com/) para execução containerizada

### Opção 1: Build a partir do código-fonte

```bash
# Clone ou baixe o repositório
git clone <url-do-repositorio>
cd viacep-brasil-mcpserver

# Instale as dependências
npm install

# Compile o TypeScript
npm run build
```

O servidor compilado estará em `build/index.js`.

### Opção 2: Docker

#### Build da imagem

```bash
docker build -t viacep-brasil-mcpserver .
```

#### Execução com Docker

O servidor usa transporte `stdio`, portanto a flag `-i` é obrigatória:

```bash
docker run -i --rm viacep-brasil-mcpserver
```

---

## Configuração nos Clientes MCP

### VS Code (GitHub Copilot)

Adicione ao arquivo `.vscode/mcp.json` no seu workspace:

```json
{
  "servers": {
    "viacep-brasil": {
      "type": "stdio",
      "command": "node",
      "args": ["/caminho/absoluto/para/viacep-brasil-mcpserver/build/index.js"]
    }
  }
}
```

Ou com Docker:

```json
{
  "servers": {
    "viacep-brasil": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "viacep-brasil-mcpserver"]
    }
  }
}
```

### 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": {
    "viacep-brasil": {
      "command": "node",
      "args": ["/caminho/absoluto/para/viacep-brasil-mcpserver/build/index.js"]
    }
  }
}
```

Com Docker:

```json
{
  "mcpServers": {
    "viacep-brasil": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "viacep-brasil-mcpserver"]
    }
  }
}
```

### Cursor

Adicione ao arquivo de configuração MCP do Cursor (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "viacep-brasil": {
      "command": "node",
      "args": ["/caminho/absoluto/para/viacep-brasil-mcpserver/build/index.js"]
    }
  }
}
```

### Outros clientes MCP (genérico)

Qualquer cliente MCP com suporte a transporte `stdio` pode usar este servidor:

```json
{
  "mcpServers": {
    "viacep-brasil": {
      "command": "node",
      "args": ["/caminho/para/build/index.js"]
    }
  }
}
```

---

## Exemplos de Uso

### Via MCP Inspector (UI)

```bash
# Inicia o Inspector com interface web em http://localhost:6274
npx @modelcontextprotocol/inspector node build/index.js
```

Configure no Inspector:

- **Transport:** `stdio`
- **Command:** `node`
- **Args:** `build/index.js`

### Via MCP Inspector (CLI)

```bash
# Listar todas as ferramentas disponíveis
mcp-inspector --cli node build/index.js --method tools/list

# Buscar endereço pelo CEP da Praça da Sé (SP)
mcp-inspector --cli node build/index.js \
  --method tools/call \
  --tool-name buscar_endereco_por_cep \
  --tool-arg 'cep="01001000"'

# Buscar endereço com hífen
mcp-inspector --cli node build/index.js \
  --method tools/call \
  --tool-name buscar_endereco_por_cep \
  --tool-arg 'cep="01001-000"'

# Buscar CEP por endereço — Avenida Paulista em São Paulo/SP
mcp-inspector --cli node build/index.js \
  --method tools/call \
  --tool-name buscar_cep_por_endereco \
  --tool-arg uf=SP \
  --tool-arg cidade="São Paulo" \
  --tool-arg logradouro=Paulista

# Buscar CEP por endereço — Porto Alegre/RS
mcp-inspector --cli node build/index.js \
  --method tools/call \
  --tool-name buscar_cep_por_endereco \
  --tool-arg uf=RS \
  --tool-arg cidade="Porto Alegre" \
  --tool-arg logradouro=Domingos

# Listar recursos disponíveis (resources)
mcp-inspector --cli node build/index.js --method resources/list

# Ler a documentação do servidor como recurso MCP
mcp-inspector --cli node build/index.js \
  --method resources/read \
  --uri viacep://docs/readme
```

### Docker + MCP Inspector

```bash
npx @modelcontextprotocol/inspector --cli docker run -i --rm viacep-brasil-mcpserver \
  --method tools/list
```

---

## Recursos disponíveis (Resources)

### 📄 `viacep://docs/readme`

Documentação completa do servidor em formato Markdown. Disponível a qualquer cliente MCP para consulta.

```
URI:       viacep://docs/readme
MIME type: text/markdown
```

---

## Desenvolvimento

### Compilar em modo watch

```bash
npm run dev
```

### Build para produção

```bash
npm run build
```

### Build da imagem Docker

```bash
# Build padrão
docker build -t viacep-brasil-mcpserver .

# Build com tag de versão
docker build -t viacep-brasil-mcpserver:1.0.0 .
```

---

## API ViaCEP

Este servidor consome a API pública e gratuita [ViaCEP](https://viacep.com.br/).

| Endpoint                                                        | Descrição                                   |
| --------------------------------------------------------------- | ------------------------------------------- |
| `GET https://viacep.com.br/ws/{cep}/json/`                      | Retorna endereço completo a partir do CEP   |
| `GET https://viacep.com.br/ws/{UF}/{cidade}/{logradouro}/json/` | Retorna lista de CEPs por endereço (até 50) |

**Tratamento de erros:**

- CEP com formato inválido → HTTP `400 Bad Request`
- CEP válido mas inexistente → `{ "erro": "true" }`
- Cidade ou logradouro com menos de 3 caracteres → HTTP `400 Bad Request`

> ⚠️ **Atenção:** O uso massivo da API para validação de bases de dados pode resultar no bloqueio automático do acesso por tempo indeterminado, conforme informado pelo ViaCEP.

---

## Tecnologias

| Tecnologia                                                                   | Versão | Uso                                  |
| ---------------------------------------------------------------------------- | ------ | ------------------------------------ |
| [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) | 1.x    | Framework do servidor MCP            |
| [Zod](https://zod.dev/)                                                      | 3.x    | Validação de esquemas dos parâmetros |
| TypeScript                                                                   | 5.7+   | Linguagem de desenvolvimento         |
| Node.js                                                                      | 22+    | Runtime (recomendado) / 18+ (mínimo) |
| Docker                                                                       | —      | Containerização (opcional)           |

---

## Licença

Este projeto está licenciado sob a [MIT License](./LICENSE).