# 🖥️​ MCP CEP

Servidor MCP (Model Context Protocol) construído com [FastMCP](https://gofastmcp.com/) que expõe a ferramenta `cep_lookup`, consultando a API pública [ViaCEP](https://viacep.com.br) para resolver CEPs brasileiros em dados de endereço retornando um template HTML com os dados.

## ✅Requisitos

- Python >= 3.13, < 4.0
- FastMCP >= 3.4.4
- Requests >= 2.34.2

## ⚙️​Instalação

### 📍​ Opção 1 — Poetry (recomendado)

```powershell
poetry install
```

### 📍​ Opção 2 — Pip

```powershell
python -m venv .venv
.venv\Scripts\activate
pip install .
```

## ✋​Executando manualmente(não é obrigatório.)

```powershell
poetry run python src/mcp_cep/mcp_cep_server.py
```
Ou quem usar Pip
```powershell
python src/mcp_cep/mcp_cep_server.py
```

O servidor usa transporte **stdio**: normalmente você não precisa executá-lo manualmente, pois o cliente MCP (Claude Code, Claude Desktop, etc.) inicia e encerra o processo automaticamente quando a ferramenta é chamada.

## 📖Registrando no Claude Code

Registre o servidor como MCP no escopo `user`, para que fique disponível em qualquer projeto:
```forneça o caminho da sua venv do projeto e depois o caminho do script.```  

Exemplo de caminhos:  
📂 **​.venv:** ```C:\project\mcp_app\.venv\Scripts\python.exe```  
📂 ​**script:** ```C:\project\mcp_app\MCP_CEP\src\mcp_cep\mcp_cep_server.py```

#### 👀​ Se quiser ver se ele foi registrado digite no terminal do VSCode ou do Claude Code: ```claude mcp list```  
- Vai listar os MCP Server's registrados, e nela vai aparecer o nome  ```mcp-cep``` e no final da linha tem que ter um ```✔ Connected```

A linha de comando de registro ficará assim:
```powershell
claude mcp add mcp-cep -s user -- "C:\project\mcp_app\.venv\Scripts\python.exe" "C:\project\mcp_app\MCP_CEP\src\mcp_cep\mcp_cep_server.py"
```

Caso queira, após testar, remover o registro do MCP CEP:

```powershell
claude mcp remove mcp-cep -s user
```

## 🔥​ MCP independe de IA

Os exemplos acima usam o Claude Code porque eu o utilizo, mas isso é só um detalhe de configuração — o registro em si não depende de qual IA você usa.  

O MCP (Model Context Protocol) é um protocolo **agnóstico**: ele define um contrato padrão de comunicação entre cliente e servidor, e não amarra o servidor a nenhum modelo ou fornecedor específico.

Na prática, isso significa que o MCP CEP é só um processo local que expõe a ferramenta `cep_lookup` via stdio (ou HTTP).  

Qualquer cliente que "fale" o protocolo MCP — Claude Desktop, Claude Code, ou qualquer outra IA/Ferramenta compatível com o padrão — consegue descobrir e chamar essa ferramenta da mesma forma, seguindo os mesmos passos de registro (apontar o cliente para o interpretador Python(.venv) e depois o script python(.py) do servidor).👍​

O servidor não sabe e nem precisa saber qual é IA que está do outro lado da conversa.😉​  


## 👨🏻‍💻 Obrigado por visitar. ​✌️​