# redbus-mcp

Servidor **MCP (Model Context Protocol)** para consultar pasajes de bus interprovinciales en
Perú a través de [redbus.pe](https://www.redbus.pe/). Permite que asistentes de IA compatibles
con MCP (Cursor, VS Code, etc.) busquen buses en lenguaje natural: _"buses de Lima a Arequipa
el 20 de julio"_.

> **Alcance:** solo **consulta** (lectura). No reserva ni realiza pagos.

## Herramientas expuestas

| Herramienta | Qué hace |
|---|---|
| `buscar_ciudades` | Busca ciudades/terminales por nombre y devuelve su **ID** (ej. Lima = `195105`). |
| `buscar_buses` | Lista buses de una ruta y fecha: empresa, tipo, horarios, duración, precios, asientos disponibles, calificación, embarque/descenso y amenidades. Acepta **nombres o IDs** de ciudad. |
| `detalle_servicio` | Detalle de un servicio: **mapa de asientos** (número, tipo, precio, disponibilidad, piso) y **puntos de embarque/descenso** con horas y direcciones. |

## Requisitos

- Node.js **≥ 18** (probado en Node 22).

## Instalación

```bash
npm install
npm run build
```

## Verificación

Prueba end-to-end contra la API real de RedBus (sin capa MCP):

```bash
npm run smoke            # usa una fecha 3 días en el futuro
npm run smoke 2026-08-05 # o una fecha concreta (ISO yyyy-MM-dd)
```

Inspección interactiva del servidor MCP:

```bash
npm run inspector        # abre el MCP Inspector
```

## Uso en un cliente MCP

Registra el servidor en la configuración MCP de tu cliente (el formato `mcpServers` es común a
la mayoría). Ejemplo:

```json
{
  "mcpServers": {
    "redbus-peru": {
      "command": "node",
      "args": ["C:\\Users\\paranda\\Documents\\Proyectos-personales\\redbus-mcp\\build\\index.js"]
    }
  }
}
```

Reinicia el cliente y pregunta, por ejemplo:
_"¿Qué buses hay de Lima a Cusco el 2026-07-20? Ordénalos por precio."_

En **Cursor** / **VS Code** la configuración es equivalente (`mcp.json` / settings del cliente),
apuntando `command`/`args` al mismo `build/index.js`.

## Fechas

- Entrada del usuario: **ISO `yyyy-MM-dd`** (ej. `2026-07-20`).
- Internamente el cliente convierte al formato que exige cada endpoint de RedBus
  (`dd-MMM-yyyy` para la búsqueda, ISO para el layout de asientos).
- La fecha debe ser **hoy o futura**; RedBus suele vender con pocas semanas de anticipación.

## Cómo funciona (arquitectura)

RedBus expone una API interna en `https://www.redbus.pe/rpw/api/`. Un `fetch` plano es
**rechazado** (protección anti-bot), por lo que `src/redbusClient.ts`:

1. Envía headers realistas de Chrome (User-Agent, Referer, `Accept-Language: es-PE`, etc.).
2. Hace **warm-up**: visita la home para obtener cookies y las reenvía en cada llamada.
3. Reintenta con backoff y re-hace el warm-up si detecta bloqueo (403/429/reset).
4. Aplica un rate-limit suave entre peticiones.

Toda la lógica anti-bot está aislada en `redbusClient.ts`: si RedBus endurece la protección,
se puede migrar ese módulo a un navegador headless (Playwright) sin tocar las herramientas.

### Estructura

```
src/
  index.ts            # arranque del servidor MCP (stdio) + registro de tools
  redbusClient.ts     # cliente HTTP: cookies, headers, warm-up, reintentos, endpoints
  types.ts            # tipos de las respuestas de RedBus
  tools/              # buscar_ciudades, buscar_buses, detalle_servicio
  lib/                # fechas, normalización de datos, catálogo de amenidades
```

## Aviso

Este proyecto consume una API **interna no pública** de RedBus con fines **personales y
educativos**. Respeta sus términos de servicio y evita un uso intensivo (ya incluye un
rate-limit suave). No está afiliado a RedBus.

## Licencia

MIT