# 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

```bash
# 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:
```env
# 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.

```json
{
  "query": "authentication API"
}
```

**Respuesta**:
```json
{
  "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.

```json
{
  "id": "auth-api"
}
```

**Respuesta**:
```json
{
  "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

```bash
# 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

```bash
# 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

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

# Desplegar
npm run deploy:railway
```

### AWS ECS

```bash
# 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
```env
# 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)
```env
# 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

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

### Opción 2: JWT Token

```javascript
// 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:

```json
{
  "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:

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