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.

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

npm install

Copie o arquivo de ambiente:

copy .env.example .env

Edite .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:

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

npm run chat

Exemplos de perguntas:

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:

[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

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.