alexnogueira/mcp-test

MCP Test - Client & Server com OpenAI

Este projeto implementa um cliente e servidor MCP (Model Context Protocol) usando OpenAI GPT-4 e TypeScript, seguindo os tutoriais oficiais do MCP.

Estrutura do Projeto

mcp-test/
├── src/
│   ├── client.ts    # Cliente MCP que usa OpenAI
│   └── server.ts    # Servidor MCP com ferramentas de exemplo
├── build/           # Código compilado
├── .env            # Chaves de API
├── package.json
├── tsconfig.json
└── README.md

Pré-requisitos

• Node.js 17 ou superior
• Chave de API da OpenAI
• npm ou yarn

Configuração

1. Instalar dependências:

   npm install
   

2. Configurar variáveis de ambiente: O arquivo .env já deve conter sua chave da OpenAI:

   OPENAI_API_KEY=sua_chave_aqui
   

3. Compilar o TypeScript:

   npm run build
   

Como Usar

1. Iniciar o Servidor MCP

Em um terminal, execute:

npm run start:server

O servidor disponibiliza as seguintes ferramentas:

• get_alerts: Obter alertas meteorológicos para um estado (código de 2 letras)
• get_forecast: Obter previsão do tempo para coordenadas (latitude, longitude)
• add: Somar dois números
• multiply: Multiplicar dois números
• get_random_fact: Obter um fato interessante aleatório

2. Iniciar o Cliente MCP

Em outro terminal, execute:

npm run start:client build/server.js

3. Interagir com o Sistema

Agora você pode fazer perguntas que utilizarão as ferramentas disponíveis:

Exemplos de consultas:

• "Qual é a previsão do tempo para San Francisco?" (latitude: 37.7749, longitude: -122.4194)
• "Existem alertas meteorológicos no Texas?"
• "Quanto é 15 + 27?"
• "Calcule 8 × 9"
• "Me conte um fato interessante"

Scripts Disponíveis

• npm run build: Compila TypeScript para JavaScript
• npm run start:server: Inicia o servidor MCP
• npm run start:client: Inicia o cliente MCP
• npm run dev:server: Compila e inicia o servidor
• npm run dev:client: Compila e inicia o cliente

Arquitetura

Servidor MCP (server.ts)

• Implementa ferramentas usando o SDK do MCP
• Usa a API do National Weather Service (NWS) para dados meteorológicos
• Fornece ferramentas matemáticas simples e fatos aleatórios
• Comunica via stdio (padrão do MCP)

Cliente MCP (client.ts)

• Conecta-se ao servidor MCP via stdio
• Usa OpenAI GPT-4o-mini para processar consultas
• Converte ferramentas MCP para formato OpenAI
• Executa ferramentas automaticamente quando o LLM decide usá-las

Fluxo de Funcionamento

1. Conexão: Cliente conecta ao servidor via stdio
2. Descoberta: Cliente lista ferramentas disponíveis no servidor
3. Consulta: Usuário faz uma pergunta
4. Análise: OpenAI analisa a pergunta e decide quais ferramentas usar
5. Execução: Cliente executa as ferramentas através do servidor MCP
6. Resposta: OpenAI formula resposta final baseada nos resultados

Tecnologias Utilizadas

• TypeScript: Linguagem principal
• OpenAI SDK: Integração com GPT-4
• MCP SDK: Protocolo de comunicação entre cliente e servidor
• Zod: Validação de esquemas
• dotenv: Gerenciamento de variáveis de ambiente

Solução de Problemas

Erro de conexão com servidor

• Verifique se o caminho para o servidor está correto
• Certifique-se de que o servidor foi compilado (npm run build)

Erro de API Key

• Verifique se OPENAI_API_KEY está definida no .env
• Confirme que a chave é válida e tem créditos disponíveis

Ferramentas não funcionam

• Verifique se o servidor está rodando
• Para ferramentas meteorológicas, use apenas localizações dos EUA

Próximos Passos

• Adicionar mais ferramentas personalizadas
• Implementar recursos (resources) além de ferramentas
• Adicionar prompts pré-definidos
• Criar interface web para o cliente
• Implementar cache para melhor performance

Referências

• MCP Client Quickstart
• MCP Server Quickstart
• OpenAI API Documentation
• Model Context Protocol