DEPLOYMENT.md•7.86 kB
# RTIdeas MCP API Server - Guía de Despliegue
## Descripción
Este documento describe cómo desplegar el servidor MCP de RTIdeas como una API REST remota en lugar de un servidor local con stdio.
## Cambios Realizados
### 1. Servidor API REST
- **Archivo**: `rtideas_api_server.py`
- **Tecnología**: FastAPI + Uvicorn
- **Protocolo**: HTTP/HTTPS en lugar de stdio
- **Puerto**: 8000 (configurable)
### 2. Endpoints Disponibles
#### Información del Servidor
- `GET /` - Información del servidor
- `GET /health` - Health check
- `GET /docs` - Documentación interactiva (Swagger)
- `GET /redoc` - Documentación alternativa
#### Herramientas MCP (POST)
- `POST /tools/list_sessions` - Listar sesiones
- `POST /tools/get_session` - Obtener sesión específica
- `POST /tools/list_ideas` - Listar ideas de una sesión
- `POST /tools/search_ideas` - Buscar ideas
- `POST /tools/get_idea_connections` - Obtener conexiones
- `POST /tools/get_idea_clusters` - Obtener clusters
- `POST /tools/get_session_stats` - Estadísticas de sesión
- `POST /tools/analyze_session` - Análisis completo
- `POST /tools/hello_rtideas` - Herramienta de prueba
#### Recursos MCP (GET)
- `GET /resources/sessions` - Todas las sesiones
- `GET /resources/ideas/{session_id}` - Ideas de una sesión
- `GET /resources/connections/{session_id}` - Conexiones de una sesión
- `GET /resources/clusters/{session_id}` - Clusters de una sesión
- `GET /resources/stats/{session_id}` - Estadísticas de una sesión
## Instalación
### 1. Dependencias
```bash
pip install -r requirements.txt
```
### 2. Variables de Entorno
Crear archivo `.env`:
```env
# MongoDB
MONGODB_URI=mongodb://localhost:27017
MONGODB_DATABASE=rtideas
# API Server
API_HOST=0.0.0.0
API_PORT=8000
API_RELOAD=false
# CORS
CORS_ORIGINS=*
CORS_CREDENTIALS=true
# Logging
LOG_LEVEL=INFO
```
## Ejecución
### Desarrollo Local
```bash
python rtideas_api_server.py --reload
```
### Producción
```bash
python rtideas_api_server.py
```
### Con Gunicorn (Recomendado para producción)
```bash
gunicorn rtideas_api_server:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```
## Configuración del Servidor
### Variables de Entorno Disponibles
| Variable | Descripción | Valor por Defecto |
|----------|-------------|-------------------|
| `API_HOST` | Host del servidor | `0.0.0.0` |
| `API_PORT` | Puerto del servidor | `8000` |
| `API_RELOAD` | Auto-reload en desarrollo | `false` |
| `CORS_ORIGINS` | Orígenes permitidos (separados por coma) | `*` |
| `CORS_CREDENTIALS` | Permitir credenciales CORS | `true` |
| `MONGODB_URI` | URI de conexión MongoDB | Requerido |
| `MONGODB_DATABASE` | Nombre de la base de datos | `rtideas` |
| `LOG_LEVEL` | Nivel de logging | `INFO` |
## Despliegue en Servidor
### 1. Docker (Recomendado)
Crear `Dockerfile`:
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "rtideas_api_server.py"]
```
Crear `docker-compose.yml`:
```yaml
version: '3.8'
services:
rtideas-api:
build: .
ports:
- "8000:8000"
environment:
- MONGODB_URI=mongodb://mongodb:27017
- MONGODB_DATABASE=rtideas
- API_HOST=0.0.0.0
- API_PORT=8000
depends_on:
- mongodb
restart: unless-stopped
mongodb:
image: mongo:7
ports:
- "27017:27017"
volumes:
- mongodb_data:/data/db
restart: unless-stopped
volumes:
mongodb_data:
```
Ejecutar:
```bash
docker-compose up -d
```
### 2. Servidor VPS/Cloud
#### Ubuntu/Debian
```bash
# Instalar dependencias del sistema
sudo apt update
sudo apt install python3 python3-pip nginx
# Clonar el proyecto
git clone <tu-repo>
cd mcp
# Instalar dependencias Python
pip3 install -r requirements.txt
# Configurar variables de entorno
cp env.example .env
nano .env # Editar con tus valores
# Ejecutar con systemd
sudo nano /etc/systemd/system/rtideas-api.service
```
Contenido de `/etc/systemd/system/rtideas-api.service`:
```ini
[Unit]
Description=RTIdeas MCP API Server
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/your/mcp
Environment=PATH=/path/to/your/mcp/venv/bin
ExecStart=/path/to/your/mcp/venv/bin/python rtideas_api_server.py
Restart=always
[Install]
WantedBy=multi-user.target
```
```bash
sudo systemctl daemon-reload
sudo systemctl enable rtideas-api
sudo systemctl start rtideas-api
```
#### Nginx (Proxy Reverso)
```nginx
server {
listen 80;
server_name tu-dominio.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
## Uso de la API
### Ejemplo: Listar Sesiones
```bash
curl -X POST "http://localhost:8000/tools/list_sessions" \
-H "Content-Type: application/json" \
-d '{"limit": 10}'
```
### Ejemplo: Buscar Ideas
```bash
curl -X POST "http://localhost:8000/tools/search_ideas" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "session123",
"query": "innovación",
"limit": 5
}'
```
### Ejemplo: Obtener Recursos
```bash
curl "http://localhost:8000/resources/sessions"
curl "http://localhost:8000/resources/ideas/session123"
```
## Monitoreo
### Health Check
```bash
curl http://localhost:8000/health
```
### Logs
```bash
# Ver logs del servicio
sudo journalctl -u rtideas-api -f
# Ver logs de Docker
docker-compose logs -f rtideas-api
```
## Seguridad
### 1. CORS
Configurar orígenes específicos en producción:
```env
CORS_ORIGINS=https://tu-dominio.com,https://app.tu-dominio.com
```
### 2. Autenticación (Opcional)
Para agregar autenticación, modificar `rtideas_api_server.py`:
```python
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer
security = HTTPBearer()
async def verify_token(token: str = Depends(security)):
# Implementar verificación de token
if not verify_your_token(token.credentials):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid token"
)
return token
# Agregar a los endpoints que requieren autenticación
@self.app.post("/tools/list_sessions", dependencies=[Depends(verify_token)])
```
### 3. HTTPS
Usar un proxy reverso con SSL (Nginx, Traefik, etc.)
## Migración desde MCP Local
### 1. Cambiar Configuración de Claude
En lugar de usar stdio, configurar Claude para usar la API:
```json
{
"mcpServers": {
"rtideas": {
"command": "curl",
"args": ["-X", "POST", "http://tu-servidor:8000/tools/{tool_name}"]
}
}
}
```
### 2. Actualizar Cliente
Cambiar de stdio a HTTP requests en tu cliente MCP.
## Troubleshooting
### Error de Conexión MongoDB
```bash
# Verificar que MongoDB esté corriendo
sudo systemctl status mongod
# Verificar conectividad
mongo --host localhost --port 27017
```
### Puerto en Uso
```bash
# Verificar qué proceso usa el puerto
sudo lsof -i :8000
# Cambiar puerto en .env
API_PORT=8001
```
### Permisos
```bash
# Dar permisos al usuario
sudo chown -R www-data:www-data /path/to/your/mcp
sudo chmod -R 755 /path/to/your/mcp
```
## Soporte
Para problemas o preguntas:
1. Revisar logs del servidor
2. Verificar configuración de variables de entorno
3. Comprobar conectividad a MongoDB
4. Verificar que todos los puertos estén disponibles