# Assistente de CEP com OpenAI + MCP

Mini-laboratorio para o seminario de Servicos Web sobre **Model Context Protocol (MCP)**.

O projeto demonstra uma aplicacao de IA que conversa com a OpenAI e usa um servidor MCP para consultar CEPs brasileiros na API publica ViaCEP.

## Ideia

Quando o usuario pergunta por um CEP, a aplicacao envia a conversa para o modelo da OpenAI com uma ferramenta disponivel. Se o modelo decidir que precisa consultar dados externos, a aplicacao roteia a chamada para o servidor MCP `cep-tools`, que por sua vez consulta a API REST do ViaCEP.

```mermaid
flowchart LR
  U["Usuario"]
  APP["Chat CLI Node.js"]
  OAI["OpenAI"]
  MCP["MCP Server cep-tools"]
  VIA["API REST ViaCEP"]

  U --> APP
  APP --> OAI
  OAI --> APP
  APP --> MCP
  MCP --> VIA
  VIA --> MCP
  MCP --> APP
  APP --> OAI
  OAI --> APP
  APP --> U
```

## O que o MCP Server expoe

- Tool `consultar_cep`: recebe um CEP com ou sem hifen e retorna endereco, bairro, cidade, UF, DDD, codigo IBGE e outros campos.
- Resource `cep://exemplos`: retorna uma lista de CEPs prontos para usar na demonstracao.

## Requisitos

- Node.js 20 ou superior
- NPM
- Chave da OpenAI para usar o chat

## Instalacao

```bash
npm install
```

Copie o arquivo de ambiente:

```bash
copy .env.example .env
```

Edite `.env`:

```env
OPENAI_API_KEY=sua_chave
OPENAI_MODEL=gpt-4.1-mini
```

Voce pode trocar `OPENAI_MODEL` por outro modelo disponivel na sua conta.

## Rodando a demo MCP sem OpenAI

Este comando prova que o servidor MCP esta funcionando:

```bash
npm run demo:cep
```

Ele deve listar a tool `consultar_cep`, o resource `cep://exemplos` e consultar um CEP de Passo Fundo.

## Rodando o chat com OpenAI

```bash
npm run chat
```

Exemplos de perguntas:

```text
Consulta o CEP 01001-000
Qual cidade e bairro do CEP 99010-000?
Me explica o endereco do CEP 20040-020
```

Durante a execucao, o chat imprime uma linha como:

```text
[MCP] Chamando tool consultar_cep com argumentos {"cep":"99010-000"}
```

Essa linha e util para a apresentacao, porque mostra o momento exato em que a IA aciona a ferramenta externa via MCP.

## Scripts

- `npm run build`: valida o TypeScript.
- `npm run mcp:cep`: sobe apenas o servidor MCP em stdio.
- `npm run demo:cep`: conecta em um cliente MCP local e testa tools/resources.
- `npm run chat`: inicia o assistente com OpenAI + MCP.

## Estrutura

```text
src/
  cep.ts              Regras de validacao e chamada ao ViaCEP
  mcp-server.ts       Servidor MCP com tool e resource
  mcp-client.ts       Cliente MCP usado pela aplicacao
  demo-mcp-client.ts  Teste isolado do MCP
  chat.ts             Chat CLI com OpenAI e tool calling
docs/
  roteiro-apresentacao.md
  slides.md
  referencias.md
```

## Relacao com Servicos Web

O projeto usa uma API REST tradicional, o ViaCEP, mas a disponibiliza para uma aplicacao de IA por meio de MCP. Assim, a demo mostra duas camadas importantes:

1. REST continua sendo usado para integrar sistemas web.
2. MCP padroniza como agentes de IA descobrem e executam capacidades externas.

## Pontos para comentar na apresentacao

- MCP resolve o problema de integracoes N x M entre apps de IA e ferramentas externas.
- O host cria um client MCP para conversar com cada server.
- O server MCP expoe primitives como tools, resources e prompts.
- O transporte local usado aqui e stdio.
- A comunicacao logica do protocolo e baseada em JSON-RPC.
- A aplicacao ainda precisa controlar seguranca, validacao, logs e limites de uso.