RedTransporteMCP

Servidor MCP (Model Context Protocol) privado paraRedTransporteAPI — transportepúblico de Santiago de Chile: paraderos, recorridos, predicciones en tiemporeal (iBus + RED web) y planificación RAPTOR.

El repositorio de la API se deja intacto como motor REST/CLI; este proyecto esun adaptador MCP que la consume por HTTP. Código libre (GPL-3.0) para quienquiera montarlo, pero el endpoint desplegado es de uso privado (deny-by-default).

Capacidades

Tool	Descripción
`search_stops`	Buscar paraderos por nombre o código parcial
`get_stop`	Detalle de un paradero (coords, accesibilidad, servicios)
`find_nearby_stops`	Paraderos cercanos a una coordenada
`find_closest_station`	Estación metro/tren más cercana
`get_routes_near_point`	Recorridos cerca de un punto
`find_stops_in_bbox`	Paraderos en un bounding box
`list_routes`	Listar recorridos (filtro por modo)
`get_route` / `get_route_stops` / `get_route_shape`	Detalle, paradas y geometría de un recorrido
`get_arrivals`	Predicciones en tiempo real para un paradero
`suggest_direct_routes`	Recorridos directos entre dos puntos
`plan_journey`	Planificación RAPTOR con transbordos y tarifa
`get_system_stats` / `get_gtfs_status`	Estado del dataset

Todas las tools son de solo lectura. No hay tools de escritura ni de administración.

Arquitectura

ChatGPT / Codex / Claude / opencode
        │  (MCP streamable-http o stdio)
        ▼
┌───────────────────────┐
│  RedTransporteMCP     │  ← bearer token MCP (RED_TRANSPORTE_MCP_TOKEN)
│  deny-by-default      │
└──────────┬────────────┘
           │  HTTPS + bearer token API (RED_TRANSPORTE_API_TOKEN)
           ▼
┌───────────────────────┐
│  RedTransporteAPI     │  ← motor GTFS/RAPTOR/iBus/RED (repo aparte)
└───────────────────────┘

El servidor es un proxy delgado: valida parámetros, traduce errores a erroresMCP y reenvía al REST. No carga GTFS en memoria ni duplica el motor. El transporteHTTP usa OAuth 2.1 con PKCE para clientes como ChatGPT; el token MCP existente seusa en la pantalla de consentimiento y sigue funcionando para clientes legacy.

Configuración

Variable	Default	Descripción
`RED_TRANSPORTE_API_URL`	`https://api-red.iroak.dev`	Base URL del REST
`RED_TRANSPORTE_API_TOKEN`	(requerido)	Bearer token de la API (crear en `POST /admin/tokens`)
`RED_TRANSPORTE_MCP_TOKEN`	(requerido para HTTP)	Bearer token exigido al cliente MCP
`RED_TRANSPORTE_MCP_PUBLIC_HOST`	`mcp-red.iroak.dev`	Hostname HTTP permitido por la protección DNS-rebinding
`RED_TRANSPORTE_MCP_BASE_URL`	`https://mcp-red.iroak.dev`	URL canónica del recurso OAuth; el recurso final es `/mcp`
`RED_TRANSPORTE_OAUTH_SECRET`	(deriva del MCP token)	Secreto HMAC opcional separado para clientes y tokens OAuth
`RED_TRANSPORTE_MCP_PORT`	`8001`	Puerto del transporte HTTP
`RED_TRANSPORTE_MCP_TIMEOUT`	`30`	Timeout de llamadas al REST (segundos)

Uso local (stdio)

uv sync
RED_TRANSPORTE_API_TOKEN=tu-token uv run red-transporte-mcp --transport stdio

Configura el cliente MCP con comando uv run red-transporte-mcp (stdio).

Uso remoto (streamable-http)

RED_TRANSPORTE_API_TOKEN=tu-token \
RED_TRANSPORTE_MCP_TOKEN=token-privado \
uv run red-transporte-mcp --transport http --host 0.0.0.0 --port 8001

Endpoint: https://<host>/mcp.

Liveness: GET /health (no authentication; no application data).

Sin RED_TRANSPORTE_MCP_TOKEN, /mcp falla cerrado con 401 y la pantallade consentimiento OAuth no puede autorizar usuarios.
Con token configurado, cualquier request sin un bearer OAuth válido o el tokenlegacy recibe 401 (deny-by-default).

Conexión desde ChatGPT

En ChatGPT web, activa Developer mode en Settings → Apps → Advanced Settings.
Crea una app MCP desde Apps → Create.
Usa el endpoint https://mcp-red.iroak.dev/mcp y selecciona OAuth.
Pulsa Scan Tools; el flujo redirige a la pantalla de consentimiento del MCP.
Introduce el valor de RED_TRANSPORTE_MCP_TOKEN desde Proton Pass.
Crea/publica la app y actívala desde el menú de herramientas de un chat.

El MCP publica los metadatos en /.well-known/oauth-protected-resource/mcp y/.well-known/oauth-authorization-server, registra clientes dinámicamente yrequiere PKCE S256. No hay que pegar el token de la API REST en ChatGPT.

Despliegue (Coolify / Cloudflare)

Idea base, ajustar a tu infraestructura:

Aplicación Docker en Coolify (imagen publicada por CI de este repo).
Hostname mcp-red.iroak.dev → túnel Cloudflare → puerto publicado(p. ej. 10369 → 8001).
Variables secretas en Coolify, nunca en Git: RED_TRANSPORTE_API_TOKEN,RED_TRANSPORTE_MCP_TOKEN y opcionalmente RED_TRANSPORTE_OAUTH_SECRET.
Un solo worker (sin estado de sesión; stateless_http).
Rate limiting a nivel de Cloudflare + el de la API.
Revisar que los logs no contengan tokens ni cuerpos de requests.

Docker local

cp .env.example .env
# completar RED_TRANSPORTE_API_TOKEN y RED_TRANSPORTE_MCP_TOKEN en .env
docker compose up --build

El compose publica solo 127.0.0.1:8001; un reverse proxy o túnel debeterminar TLS y reenviar al puerto local.

Seguridad

Deny-by-default: /mcp requiere un bearer OAuth válido o el token MCP legacy.
OAuth usa authorization code + PKCE S256, resource indicators y tokens ligados a /mcp.
Los access tokens expiran en una hora y los refresh tokens rotan durante 30 días.
El token MCP se compara en tiempo constante (hmac.compare_digest).
El token de la API nunca se expone a los clientes MCP: el servidor lo usasolo contra el REST.
Errores de la API se traducen a errores MCP sin filtrar detalles internos.
Las tools son read-only y no exponen paths del servidor.

Roadmap

mTLS de OpenAI como capa adicional de identificación
CI: tests, build de imagen, smoke test MCP
Imagen Docker reproducible (uv.lock, semver)
Resources MCP para shapes/geometrías grandes

Licencia

GPL-3.0-only. Datos: GTFS DTPM, iBus y RED web — revisar términos de cadafuente antes de un uso público amplio.

RedTransporteMCP