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

O usando el archivo de proyecto:

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

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

Opción 2: Google Cloud Run

Opción 3: AWS (ECS/Fargate)

Opción 4: Heroku

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:

Ejemplo con Google Cloud Run:

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:

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:

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:

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

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:

Respuesta esperada:

Logs

El servidor usa logging estándar de Python. En producción:

Google Cloud Run:

Heroku:

Docker:

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

Desarrollo local con hot reload

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.