mcp-api-manager-server by luiso2 - MCP Server

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

Despliega el servidor en tu plataforma preferida (Heroku, Railway, etc.)
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

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
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

"Busca APIs relacionadas con autenticación"
- ChatGPT usará search con query "authentication"
- Mostrará todas las APIs que contengan esa palabra
"Muéstrame los detalles de la API auth-service"
- ChatGPT usará fetch con id "auth-service"
- Mostrará documentación completa, endpoints, autenticación, etc.
"¿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:

Despliega el servidor en tu plataforma preferida
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

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

📞 Soporte

Si necesitas ayuda:

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

📝 Licencia

MIT