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