transmi-cli

Planea viajes en transporte público por Bogotá desde la terminal o desde cualquier agente compatible con MCP.

Qué hace

• Acepta direcciones, estaciones, universidades, empresas y nombres de lugares.
• Devuelve varias alternativas ordenadas por tiempo o por cantidad de transbordos.
• Indica dónde caminar, en qué parada tomar cada bus y en qué parada bajarse.
• Busca rutas por nombre o código usando datos de TransMilenio.
• Se integra con Claude Code, Codex, Cursor y Windsurf mediante MCP.
• No abre un navegador ni requiere una API key durante una consulta.

Ejemplo

¿Cómo llego de Portal Norte a Universidad Nacional?
Dame la opción más rápida y dime exactamente dónde tomar cada bus.

Una respuesta incluye instrucciones como:

1. Camina hasta Portal Norte.
2. Toma A02 en Portal Norte hasta Estación Av. Calle 68 (8 paradas).
3. Camina hasta Estación Universidad Nacional.
4. Llegaste a tu destino.

Instalación

Requisitos

• Bun 1.2 o superior.
• Acceso a internet para consultar rutas.
• Un cliente MCP es opcional; la CLI también funciona por sí sola.

git clone https://github.com/JGaldo-beep/transmi-cli.git
cd transmi-cli
bun install

Uso desde terminal

Planear un viaje:

bun run dev -- viaje "Portal Norte" "Universidad Nacional"

Priorizar menos transbordos y mostrar hasta cinco alternativas:

bun run dev -- viaje "Calle 72 con Caracas" "Calle 85" \
  --optimizar transbordos --alternativas 5

Buscar rutas:

bun run dev -- rutas "Portal Norte"

Uso con agentes de IA

Ejecuta el instalador interactivo:

bun run setup-mcp

El instalador detecta Claude Code, Codex, Cursor o Windsurf y registra el servidor MCP. Después reinicia el agente y pregunta por una ruta con lenguaje natural.

El servidor expone dos herramientas:

Herramienta	Descripción
plan_trip	Planea un viaje entre dos direcciones o lugares.
search_routes	Busca rutas de TransMilenio por nombre o código.

Para comprobar manualmente que el servidor inicia:

bun run mcp

El proceso permanece abierto porque espera solicitudes por stdio; no está bloqueado.

Cómo funciona

transmi-cli combina el catálogo de rutas de TransMilenio con resultados de transporte público de Google Maps Web. La consulta de viajes se realiza por HTTP y la respuesta se convierte a un formato estable para la CLI y el MCP.

Consulta Arquitectura y fuentes de datos para conocer el diseño, las decisiones técnicas y las limitaciones.

Limitaciones

• Google puede cambiar su endpoint web no documentado y romper temporalmente la planificación.
• Los nombres ambiguos pueden resolverse a un lugar distinto; siempre se muestra el origen y destino interpretados para que el usuario pueda corregirlos.
• Las alertas operacionales en tiempo real y el saldo de TuLlave no están implementados.
• Esta herramienta no reemplaza información oficial durante cierres o emergencias.

Desarrollo

bun test
bun run lint

Roadmap

• Selección interactiva cuando un lugar tenga varias coincidencias.
• Consultas por hora de salida o de llegada.
• Alertas operacionales verificadas.
• Publicación como paquete para instalarlo con un solo comando.

Aviso

Este proyecto es independiente y no está afiliado con TransMilenio S.A. ni con Google. Los nombres y marcas pertenecen a sus respectivos propietarios.

Licencia

MIT