CHANGELOG_OPENAI.md•4.54 kB
# Changelog - Suporte OpenAI MCP
## Mudanças Realizadas
### 1. Endpoints REST Adicionados
#### `GET /tools`
- Lista todas as tools disponíveis
- Retorna formato MCP padrão: `{ tools: [...] }`
- Headers: `Content-Type: application/json`, `X-MCP-Server`, `X-MCP-Version`
#### `POST /tools/call`
- Executa uma tool específica
- Body: `{ name: string, arguments: object }`
- Retorna formato MCP padrão: `{ content: [{ type: "text", text: string }] }`
#### `GET /`
- Endpoint raiz com informações do servidor
- Lista todos os endpoints disponíveis
- Útil para descoberta automática
#### `GET /mcp/info`
- Informações específicas do protocolo MCP
- Capacidades do servidor
### 2. Funções Auxiliares
#### `listTools()`
- Função reutilizável para listar tools
- Usada tanto no endpoint REST quanto no handler MCP
#### `callTool(name: string, args: any)`
- Função reutilizável para executar tools
- Validação de parâmetros obrigatórios
- Tratamento de erros padronizado
- Usada tanto no endpoint REST quanto no handler MCP
### 3. Melhorias de CORS
- CORS configurado para aceitar requisições de qualquer origem
- Headers permitidos: `Content-Type`, `Authorization`
- Métodos permitidos: `GET`, `POST`, `OPTIONS`
- Handler para requisições OPTIONS (preflight)
### 4. Headers Personalizados
- `X-MCP-Server`: Identifica o servidor MCP
- `X-MCP-Version`: Versão do servidor MCP
- `Content-Type`: Sempre `application/json`
### 5. Validação de Parâmetros
- Validação de parâmetros obrigatórios em todas as tools
- Mensagens de erro descritivas
- Formato de erro padronizado: `{ content: [...], isError: true }`
### 6. Documentação
- `OPENAI_CONFIG.md`: Guia completo de configuração para OpenAI
- `README.md`: Atualizado com informações sobre endpoints REST
- Exemplos de uso e troubleshooting
## Como Usar com OpenAI
### Passo 1: Deploy do Servidor
1. Faça deploy do servidor em uma plataforma que suporte HTTPS (Render, Railway, etc.)
2. Anote a URL do servidor (ex: `https://seu-servidor.com`)
### Passo 2: Configurar na OpenAI
1. Acesse a plataforma OpenAI
2. Configure o servidor MCP com:
- **URL Base**: `https://seu-servidor.com`
- **Endpoint de Tools**: `GET /tools`
- **Endpoint de Call**: `POST /tools/call`
### Passo 3: Testar
1. A OpenAI deve descobrir automaticamente as tools através do endpoint `/tools`
2. Teste fazendo uma pergunta como: "Quais foram os dados de PIX em dezembro de 2023?"
## Troubleshooting
### Problema: OpenAI não encontra as tools
**Solução 1**: Verifique se o endpoint `/tools` está acessível:
```bash
curl https://seu-servidor.com/tools
```
**Solução 2**: Verifique se o formato da resposta está correto:
```json
{
"tools": [
{
"name": "...",
"description": "...",
"inputSchema": { ... }
}
]
}
```
**Solução 3**: Use o endpoint SSE como alternativa:
- URL: `https://seu-servidor.com/sse`
- Tipo: Server-Sent Events (SSE)
### Problema: Erro ao chamar tool
**Solução 1**: Verifique se os parâmetros obrigatórios estão sendo enviados
**Solução 2**: Verifique os logs do servidor para detalhes do erro
**Solução 3**: Teste manualmente:
```bash
curl -X POST https://seu-servidor.com/tools/call \
-H "Content-Type: application/json" \
-d '{
"name": "consultar_meios_pagamento_mensal",
"arguments": {
"ano_mes": "202312"
}
}'
```
## Formato das Tools
Todas as tools seguem o formato MCP padrão:
```typescript
{
name: string; // Nome único da tool
description: string; // Descrição da tool
inputSchema: { // JSON Schema
type: "object";
properties: { ... };
required: string[];
};
}
```
## Endpoints Disponíveis
- `GET /` - Informações do servidor
- `GET /tools` - Lista todas as tools
- `POST /tools/call` - Executa uma tool
- `GET /sse` - Endpoint SSE (alternativo)
- `GET /health` - Health check
- `GET /mcp/info` - Informações MCP
## Próximos Passos
1. Testar o servidor em produção
2. Verificar se a OpenAI consegue descobrir as tools automaticamente
3. Ajustar conforme necessário baseado no feedback da OpenAI
4. Adicionar autenticação se necessário
5. Implementar rate limiting se necessário
## Notas
- O servidor está configurado para aceitar requisições de qualquer origem (CORS)
- Para produção, considere restringir CORS para domínios específicos
- O servidor não requer autenticação por padrão
- Para produção, considere adicionar autenticação (API keys, OAuth, etc.)