API Manager Server

Un servidor multi-protocolo para gestionar APIs, compatible con ChatGPT Plugins y Claude MCP (Model Context Protocol).

🚀 Características

ChatGPT Plugin Compatible

• 2 Tools Obligatorios: search y fetch según especificación oficial
• OAuth2 Authentication: Flujo completo de autenticación para ChatGPT
• Server-Sent Events (SSE): Endpoint de eventos en tiempo real
• Plugin Manifest: Configuración automática para ChatGPT
• OpenAPI 3.0: Especificación completa de la API

Claude MCP Compatible

• Servidor WebSocket: Protocolo MCP nativo
• 5 Tools MCP: save_api, make_request, list_apis, get_api, delete_api
• Autenticación JWT y API Keys: Seguridad integrada

Características Generales

• Base de datos MongoDB: Almacenamiento persistente con búsqueda
• Multi-usuario: Soporte para múltiples usuarios con aislamiento de datos
• Docker Ready: Containerizado para fácil despliegue
• Compatible con múltiples nubes: AWS, Heroku, Railway, etc.

📦 Instalación Local

# Clonar el repositorio
git clone <tu-repo>
cd api-manager-server

# Instalar dependencias
npm install

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tus configuraciones

# Compilar TypeScript
npm run build

# Ejecutar servidor ChatGPT (recomendado)
npm run start:chatgpt

# O ejecutar servidor MCP original
npm run start:mcp

🤖 Integración con ChatGPT

Configuración del Plugin

1. Despliega el servidor en tu plataforma preferida (Heroku, Railway, etc.)

2. Configura las variables de entorno necesarias:

# OAuth2 para ChatGPT
OAUTH_CLIENT_ID=chatgpt-mcp-client
OAUTH_CLIENT_SECRET=tu-secret-super-seguro
REDIRECT_URI=https://chatgpt.com/aip/g-callback

# Base de datos y autenticación
MONGODB_URI=tu-mongodb-uri
JWT_SECRET=tu-jwt-secret
API_KEY=tu-api-key

3. Registra el plugin en ChatGPT:

   • Ve a ChatGPT Plugin Store (o configuración de plugins)
   • Selecciona "Develop your own plugin"
   • Ingresa la URL de tu servidor: https://tu-servidor.com
   • ChatGPT automáticamente detectará el manifest en /.well-known/ai-plugin.json

4. Autoriza el plugin:

   • ChatGPT te redirigirá al flujo OAuth2
   • Acepta los permisos solicitados
   • El plugin quedará instalado y listo para usar

Tools Disponibles en ChatGPT

🔍 search

Busca configuraciones de APIs guardadas.

{
  "query": "authentication API"
}

Respuesta:

{
  "results": [
    {
      "id": "auth-api",
      "title": "auth-api - Authentication Service API",
      "url": "https://tu-servidor.com/api/auth-api"
    }
  ]
}

📄 fetch

Obtiene información detallada de una API específica.

{
  "id": "auth-api"
}

Respuesta:

{
  "id": "auth-api",
  "title": "auth-api API Configuration", 
  "text": "# auth-api API Configuration\n\n## Description\nAuthentication service...",
  "url": "https://tu-servidor.com/api/auth-api",
  "metadata": {
    "baseUrl": "https://api.example.com",
    "authType": "bearer",
    "hasHeaders": true
  }
}

Casos de Uso con ChatGPT

1. "Busca APIs relacionadas con autenticación"

   • ChatGPT usará search con query "authentication"
   • Mostrará todas las APIs que contengan esa palabra

2. "Muéstrame los detalles de la API auth-service"

   • ChatGPT usará fetch con id "auth-service"
   • Mostrará documentación completa, endpoints, autenticación, etc.

3. "¿Qué APIs tengo configuradas para pagos?"

   • ChatGPT buscará APIs con términos relacionados a pagos
   • Te dará un resumen de todas las APIs de pago disponibles

🐳 Docker

Construcción y ejecución local

# Construir imagen
npm run docker:build

# Ejecutar con Docker
npm run docker:run

# O usar Docker Compose (incluye MongoDB)
npm run docker:compose

☁️ Despliegue en la Nube

Heroku

# Configurar variables de entorno
export HEROKU_APP_NAME=tu-app-name
export JWT_SECRET=tu-secret
export API_KEY=tu-api-key
export MONGODB_URI=tu-mongodb-uri

# Desplegar
npm run deploy:heroku

Railway

# Instalar Railway CLI
npm install -g @railway/cli

# Desplegar
npm run deploy:railway

AWS ECS

# Configurar AWS CLI y variables
export AWS_REGION=us-east-1
export ECR_REPOSITORY=api-manager-mcp

# Desplegar
npm run deploy:aws

🔧 Variables de Entorno

Para ChatGPT Plugin

# Server
PORT=3000
NODE_ENV=production

# OAuth2 ChatGPT
OAUTH_CLIENT_ID=chatgpt-mcp-client
OAUTH_CLIENT_SECRET=your-super-secure-oauth-secret
REDIRECT_URI=https://chatgpt.com/aip/g-callback

# Security
JWT_SECRET=your-secure-jwt-secret
API_KEY=your-secure-api-key

# Database
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net
DB_NAME=api_manager

Para Claude MCP (modo legacy)

# Server  
PORT=3000
NODE_ENV=production

# Security (solo necesario para MCP)
JWT_SECRET=your-secure-jwt-secret
API_KEY=your-secure-api-key

# Database
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net
DB_NAME=api_manager

📡 Endpoints

ChatGPT Plugin Endpoints

• GET /.well-known/ai-plugin.json - Plugin manifest
• GET /openapi.yaml - OpenAPI specification
• GET /oauth/authorize - OAuth2 authorization
• POST /oauth/token - OAuth2 token exchange
• POST /oauth/refresh - OAuth2 token refresh
• POST /search - Search APIs (ChatGPT tool)
• POST /fetch - Fetch API details (ChatGPT tool)
• GET /events - Server-Sent Events
• GET /health - Health check

Claude MCP Endpoints (Legacy)

• POST /auth/token - Obtener token JWT
• POST /api/tools - Ejecutar herramientas MCP
• GET /health - Estado del servidor

WebSocket (Solo MCP)

• ws://tu-servidor:3000/mcp?apiKey=TU_API_KEY
• ws://tu-servidor:3000/mcp?token=TU_JWT_TOKEN

🔐 Autenticación

Opción 1: API Key

headers: {
  'x-api-key': 'tu-api-key'
}

Opción 2: JWT Token

// Obtener token
const response = await fetch('/auth/token', {
  method: 'POST',
  body: JSON.stringify({ apiKey: 'tu-api-key' })
});
const { token } = await response.json();

// Usar token
headers: {
  'Authorization': `Bearer ${token}`
}

📚 Uso con Claude Desktop (MCP Legacy)

Para conectar este servidor MCP con Claude Desktop desde la nube:

1. Despliega el servidor en tu plataforma preferida
2. Configura Claude Desktop para usar el endpoint WebSocket:

{
  "mcpServers": {
    "api-manager": {
      "command": "npx", 
      "args": ["@modelcontextprotocol/ws-client", "wss://tu-servidor.com/mcp?apiKey=TU_API_KEY"]
    }
  }
}

🛠️ Herramientas Disponibles

ChatGPT Plugin Tools

• search: Buscar configuraciones de APIs por consulta de texto
• fetch: Obtener información detallada de una API específica

Claude MCP Tools (Legacy)

• save_api: Guardar configuración de API
• make_request: Hacer peticiones a APIs guardadas
• list_apis: Listar todas las APIs
• get_api: Obtener detalles de una API
• delete_api: Eliminar una API

📈 Monitoreo

El servidor incluye un endpoint de salud:

curl https://tu-servidor.com/health

🔒 Seguridad

• Usa siempre HTTPS en producción
• Cambia las claves por defecto (especialmente OAuth2 secrets)
• Configura CORS apropiadamente para ChatGPT (https://chatgpt.com)
• Implementa rate limiting si es necesario
• Usa MongoDB Atlas o similar para base de datos segura
• Los tokens OAuth2 expiran en 1 hora (configurable)

🐛 Troubleshooting

ChatGPT Plugin Issues

Error: "Plugin manifest not found"

• Verifica que /.well-known/ai-plugin.json sea accesible
• Asegúrate de que el servidor esté en HTTPS en producción

Error: "OAuth2 authorization failed"

• Verifica OAUTH_CLIENT_ID y OAUTH_CLIENT_SECRET
• Confirma que REDIRECT_URI coincide con ChatGPT
• Revisa logs del servidor para errores específicos

Error: "Search/Fetch tools not working"

• Verifica que MongoDB esté conectado correctamente
• Confirma que tienes APIs guardadas para buscar
• Revisa que el token OAuth2 no haya expirado

MCP Legacy Issues

Error: "WebSocket connection failed"

• Verifica que el servidor MCP esté ejecutándose (npm run start:mcp)
• Confirma la API key en la URL de conexión
• Asegúrate de usar wss:// en producción, no ws://

General Issues

Error: "Database connection failed"

• Verifica MONGODB_URI en variables de entorno
• Confirma que MongoDB está ejecutándose
• Revisa permisos de red si usas MongoDB Atlas

🚀 Próximos Pasos

1. Mejoras de Autenticación: Implementar scopes más específicos para OAuth2
2. Rate Limiting: Agregar limitación de velocidad por usuario
3. Webhooks: Soporte para notificaciones de cambios en APIs
4. API Documentation: Auto-generación de documentación de APIs guardadas
5. Monitoring: Métricas avanzadas y logging estructurado

📞 Soporte

Si necesitas ayuda:

1. Revisa la sección de Troubleshooting
2. Verifica que todas las variables de entorno estén configuradas
3. Consulta los logs del servidor para errores específicos
4. Abre un issue en el repositorio con detalles completos

📝 Licencia

MIT