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

cd traffic_mcp_server
pip install mcp httpx starlette uvicorn[standard]

O usando el archivo de proyecto:

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

# 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

# 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

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

# 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

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

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

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

   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:

curl https://tu-servidor.com/health

Respuesta esperada:

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

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=traffic-mcp-server" --limit 50

Heroku:

heroku logs --tail -a traffic-mcp-server

Docker:

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

pip install -e ".[dev]"
pytest

Desarrollo local con hot reload

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.