# Traffic MCP Server (SSE Transport)
Servidor MCP (Model Context Protocol) con transporte SSE (Server-Sent Events) que consume una API REST de predicción de tráfico. Diseñado para despliegue en la nube y consumo remoto.
## Características
Este servidor MCP proporciona 3 herramientas principales:
1. **get_traffic_stations** - Obtiene la lista de estaciones de tráfico disponibles
2. **predict_traffic_spi** - Predice el Speed Performance Index usando modelo LSTM
3. **suggest_routes** - Sugiere rutas óptimas entre estaciones usando Dijkstra
## Instalación Local
### Requisitos
- Python 3.10 o superior
- pip
### Instalar dependencias
```bash
cd traffic_mcp_server
pip install mcp httpx starlette uvicorn[standard]
```
O usando el archivo de proyecto:
```bash
pip install -e .
```
## Configuración
### Variables de Entorno
- `TRAFFIC_API_URL`: URL base de la API de tráfico (default: https://traffict-predict-api-452792205673.southamerica-west1.run.app)
- `MCP_API_KEY`: API key para autenticación (default: your-secure-api-key-here)
- `PORT`: Puerto del servidor (default: 8080)
### Ejecutar localmente
```bash
# Con variables de entorno por defecto
python server.py
# Con variables de entorno personalizadas
export MCP_API_KEY="mi-api-key-segura"
export PORT=3000
python server.py
```
El servidor estará disponible en:
- SSE endpoint: `http://localhost:8080/sse`
- Health check: `http://localhost:8080/health`
## Despliegue en la Nube
### Opción 1: Docker Local
```bash
# Construir la imagen
docker build -t traffic-mcp-server .
# Ejecutar el contenedor
docker run -p 8080:8080 \
-e MCP_API_KEY="mi-api-key-segura" \
-e TRAFFIC_API_URL="https://traffict-predict-api-452792205673.southamerica-west1.run.app" \
traffic-mcp-server
```
### Opción 2: Google Cloud Run
```bash
# Configurar el proyecto de Google Cloud
export PROJECT_ID="tu-proyecto-gcp"
export SERVICE_NAME="traffic-mcp-server"
export REGION="us-central1"
# Construir y subir la imagen a Google Container Registry
gcloud builds submit --tag gcr.io/$PROJECT_ID/$SERVICE_NAME
# Desplegar en Cloud Run
gcloud run deploy $SERVICE_NAME \
--image gcr.io/$PROJECT_ID/$SERVICE_NAME \
--platform managed \
--region $REGION \
--allow-unauthenticated \
--set-env-vars MCP_API_KEY="tu-api-key-segura" \
--set-env-vars TRAFFIC_API_URL="https://traffict-predict-api-452792205673.southamerica-west1.run.app" \
--port 8080
# Obtener la URL del servicio
gcloud run services describe $SERVICE_NAME --region $REGION --format='value(status.url)'
```
### Opción 3: AWS (ECS/Fargate)
```bash
# Crear repositorio ECR
aws ecr create-repository --repository-name traffic-mcp-server
# Autenticar Docker con ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com
# Construir y subir imagen
docker build -t traffic-mcp-server .
docker tag traffic-mcp-server:latest <account-id>.dkr.ecr.us-east-1.amazonaws.com/traffic-mcp-server:latest
docker push <account-id>.dkr.ecr.us-east-1.amazonaws.com/traffic-mcp-server:latest
# Crear tarea y servicio en ECS (usar consola de AWS o CLI)
```
### Opción 4: Heroku
```bash
# Login en Heroku
heroku login
# Crear app
heroku create traffic-mcp-server
# Configurar variables de entorno
heroku config:set MCP_API_KEY="tu-api-key-segura"
heroku config:set TRAFFIC_API_URL="https://traffict-predict-api-452792205673.southamerica-west1.run.app"
# Desplegar usando Git
git init
git add .
git commit -m "Initial commit"
heroku git:remote -a traffic-mcp-server
git push heroku main
```
## Configuración en Claude Desktop
Una vez desplegado el servidor, configura Claude Desktop para usar el servidor remoto:
### Configuración con SSE Transport
Agrega la siguiente configuración a tu archivo `claude_desktop_config.json`:
```json
{
"mcpServers": {
"traffic-api": {
"url": "https://tu-servidor-desplegado.com/sse",
"transport": {
"type": "sse",
"headers": {
"Authorization": "Bearer tu-api-key-segura"
}
}
}
}
}
```
**Ejemplo con Google Cloud Run:**
```json
{
"mcpServers": {
"traffic-api": {
"url": "https://traffic-mcp-server-xxxxx.a.run.app/sse",
"transport": {
"type": "sse",
"headers": {
"Authorization": "Bearer mi-api-key-super-segura-2024"
}
}
}
}
}
```
**Notas importantes:**
- Reemplaza `tu-servidor-desplegado.com` con la URL real de tu servidor desplegado
- Reemplaza `tu-api-key-segura` con la misma API key que configuraste en el servidor (variable `MCP_API_KEY`)
- Reinicia Claude Desktop después de modificar la configuración
## Uso
### Herramientas Disponibles
#### 1. get_traffic_stations
Obtiene información de estaciones de tráfico con filtros opcionales.
**Parámetros:**
- `freeway` (opcional): Número de autopista para filtrar
- `direction` (opcional): Dirección (N, S, E, W)
**Ejemplo de uso en Claude:**
```
¿Cuáles son las estaciones de la autopista 101 dirección Norte?
```
#### 2. predict_traffic_spi
Predice el índice de rendimiento de velocidad usando datos históricos de 1 hora.
**Parámetros:**
- `sequence` (requerido): Lista de 12 intervalos de 5 minutos, cada uno con 7 valores:
- Total_Flow
- Avg_Occupancy
- Avg_Speed
- Hour
- Day_of_Week
- Lanes
- Lane_Type_encoded
**Ejemplo de uso en Claude:**
```
Predice el tráfico con esta secuencia: [[100, 0.5, 60, 8, 1, 4, 1], [105, 0.52, 58, 8, 1, 4, 1], ...]
```
**Respuesta incluye:**
- SPI predicho (0-100)
- Nivel de congestión (0-3)
- Clasificación difusa con membresías
- Descripción lingüística del estado
- Estado de transición
#### 3. suggest_routes
Sugiere rutas óptimas entre dos estaciones considerando condiciones actuales.
**Parámetros:**
- `origin_station` (requerido): ID de estación origen
- `destination_station` (requerido): ID de estación destino
- `current_predictions` (requerido): Diccionario {station_id: spi_value}
- `num_routes` (opcional): Número de rutas alternativas (1-5, default: 3)
**Ejemplo de uso en Claude:**
```
Sugiere la mejor ruta desde la estación 400001 hasta la 400050 considerando estas predicciones de SPI: {400001: 85.5, 400002: 75.2, ...}
```
**Respuesta incluye:**
- Rutas ordenadas por tiempo total
- Distancia y tiempo estimado
- SPI promedio y mínimo por ruta
- Porcentaje de congestión
- Recomendación de mejor ruta
## Endpoints del Servidor
- `POST /sse` - Endpoint SSE para conexiones MCP (requiere autenticación)
- `GET /health` - Health check del servidor
## API Endpoints Consumidos
El servidor se conecta a los siguientes endpoints de la API de tráfico:
- `GET /stations` - Obtiene todas las estaciones disponibles
- `POST /predict` - Realiza predicción SPI usando LSTM
- `POST /routes/suggest` - Calcula rutas óptimas con Dijkstra
## Estructura del Proyecto
```
traffic_mcp_server/
├── server.py # Servidor MCP con SSE transport
├── pyproject.toml # Configuración del proyecto
├── Dockerfile # Configuración Docker para despliegue
└── README.md # Esta documentación
```
## Seguridad
### Autenticación
El servidor implementa autenticación básica mediante API Key:
- Las solicitudes al endpoint `/sse` deben incluir el header: `Authorization: Bearer <API_KEY>`
- La API key se valida contra la variable de entorno `MCP_API_KEY`
- Conexiones no autenticadas reciben error 401
### Recomendaciones
1. **Genera una API key segura:**
```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```
2. **Usa HTTPS en producción** (Cloud Run, Heroku y similares lo proporcionan automáticamente)
3. **No expongas la API key en código fuente** - usa variables de entorno
4. **Restringe CORS en producción** si es necesario (modificar `allow_origins` en `server.py`)
## Monitoreo
### Health Check
Verifica el estado del servidor:
```bash
curl https://tu-servidor.com/health
```
Respuesta esperada:
```json
{
"status": "healthy",
"service": "traffic-mcp-server",
"traffic_api_url": "https://traffict-predict-api-452792205673.southamerica-west1.run.app"
}
```
### Logs
El servidor usa logging estándar de Python. En producción:
**Google Cloud Run:**
```bash
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=traffic-mcp-server" --limit 50
```
**Heroku:**
```bash
heroku logs --tail -a traffic-mcp-server
```
**Docker:**
```bash
docker logs <container-id> -f
```
## Troubleshooting
### Error 401 Unauthorized
Verifica que:
1. El header `Authorization` esté incluido en la configuración de Claude Desktop
2. La API key coincida exactamente con `MCP_API_KEY` del servidor
3. El formato sea `Bearer <tu-api-key>` (con espacio después de Bearer)
### Conexión rechazada
Verifica que:
1. El servidor esté corriendo (`/health` endpoint responde)
2. La URL en `claude_desktop_config.json` sea correcta
3. El firewall/security group permita conexiones entrantes
### Errores de la API de tráfico
Verifica que:
1. `TRAFFIC_API_URL` esté configurada correctamente
2. La API de tráfico esté disponible
3. Los logs del servidor para detalles específicos
### El servidor no aparece en Claude Desktop
Asegúrate de:
1. Haber reiniciado Claude Desktop después de modificar la configuración
2. La configuración JSON esté bien formada (sin errores de sintaxis)
3. La URL del servidor incluya el path `/sse`
## Desarrollo
### Ejecutar tests
```bash
pip install -e ".[dev]"
pytest
```
### Desarrollo local con hot reload
```bash
uvicorn server:app --reload --host 0.0.0.0 --port 8080
```
## Escalabilidad
### Consideraciones de Rendimiento
- El servidor es asíncrono y puede manejar múltiples conexiones concurrentes
- Cada conexión SSE mantiene una sesión activa
- Timeouts configurados: 10s connect, 30s total por request
### Escalado Horizontal
En Cloud Run o ECS, configura auto-scaling basado en:
- Número de conexiones concurrentes
- CPU/Memoria usage
- Request latency
## Licencia
MIT
## Soporte
Para reportar problemas o solicitar características, abre un issue en el repositorio del proyecto.
