# Agenda MCP con revisión humana

Servidor MCP de agendamiento para agentes de IA, con un panel donde una persona aprueba cada acción antes de ejecutarla.

El agente puede consultar horarios y preparar citas, pero **no tiene ninguna herramienta para crearlas o cancelarlas**. Esa acción solo ocurre cuando una persona la aprueba en el panel.

![Panel de revisión](docs/panel.jpg)

> Es la versión pública de un sistema que construí para atención por chat. La reescribí con un negocio ficticio, **Taller Ruta Verde**, para que se pueda ejecutar sin credenciales ni datos reales.

## El problema

Un agente puede equivocarse o malinterpretar a un cliente. En una conversación eso se corrige con otro mensaje, pero una cita duplicada o cancelada por error tiene un costo real.

Este proyecto separa lo que el modelo puede decidir de lo que el sistema le permite ejecutar:

- **Doble confirmación:** el cliente debe confirmar de forma explícita y luego una persona debe aprobar.
- **Idempotencia:** los reintentos no duplican citas.
- **Recuperación:** si el horario se ocupa durante la revisión, el sistema propone alternativas.

## Cómo funciona

```mermaid
sequenceDiagram
    actor C as Cliente
    participant A as Agente de IA
    participant M as Servidor MCP
    actor R as Revisor
    participant K as Calendario

    C->>A: Quiero una cita el viernes
    A->>M: ver_disponibilidad
    M-->>A: Ofertas ligadas a la conversación
    A->>M: preparar_reserva
    M-->>A: confirmation_required
    C->>A: Sí, confirmo
    A->>M: confirmar_solicitud
    M->>R: Solicitud en la cola
    R->>M: Aprueba en el panel
    M->>K: Crea el evento
    M-->>A: Respuesta aprobada
    A-->>C: Tu cita quedó agendada
```

Cada solicitud avanza por estos estados:

```text
awaiting_customer → ready_for_review → committing → completed
                                                  → failed (horario ocupado)
```

También puede terminar como `cancelled` o `expired`.

## Pruébalo

Necesitas Node.js 22.13 o superior.

```bash
git clone https://github.com/juansebastianvelez/agenda-mcp-hitl.git
cd agenda-mcp-hitl
npm run setup

# Pruebas
npm test

# Demo por terminal: aprobación y horario ocupado
npm run demo
```

Para usar el panel:

```bash
# Terminal 1
npm start

# Terminal 2: crea solicitudes de ejemplo
npm run poblar
```

Abre <http://127.0.0.1:4000> y entra con estas credenciales de demostración:

- **Correo:** `revisor@rutaverde.test`
- **Contraseña:** `demo1234`

## Conectar un cliente MCP

El servidor usa el SDK oficial de MCP con transporte Streamable HTTP.

- **URL:** `http://127.0.0.1:4000/mcp`
- **Encabezado:** `x-api-key: clave-local-de-demo`

| Herramienta | Qué hace |
|---|---|
| `ver_servicios` | Lista servicios y técnicos |
| `ver_disponibilidad` | Devuelve ofertas temporales de horarios |
| `preparar_reserva` | Registra el horario elegido, sin agendar |
| `preparar_cancelacion` | Registra una cancelación, sin ejecutarla |
| `confirmar_solicitud` | Valida la confirmación del cliente y envía a revisión |
| `ver_respuesta` | Devuelve los mensajes aprobados |

## Decisiones técnicas

- **Ofertas ligadas a la conversación:** una conversación no puede usar la oferta de otra, y las ofertas vencen.
- **Confirmación validada por código:** "la primera opción" o "no, mejor otra" no cuentan como confirmación.
- **Control de reintentos:** el mismo mensaje con los mismos datos devuelve el mismo resultado; con datos distintos genera un conflicto.
- **Una solicitud abierta por conversación:** lo garantiza un índice único en la base de datos.
- **Cola con bloqueo y vencimiento:** un revisor reclama el item, y lo vencido no se puede aprobar.
- **Aprobación explícita:** la API la exige aunque alguien salte la interfaz.
- **Cancelación verificada:** solo se puede solicitar con el teléfono de la cita.
- **Panel en vivo:** la cola se actualiza por WebSocket.

## Stack

Node.js, Express, SDK oficial de MCP, Zod, SQLite, Luxon, JWT, WebSocket, React y Vite.

## Estructura

```text
src/agenda/   Disponibilidad, calendario simulado y reglas de reserva
src/mcp/      Servidor y herramientas MCP
src/panel/    Cola de revisión, API y WebSocket
frontend/     Panel en React
scripts/      Demo y datos de ejemplo
test/         Pruebas unitarias y de punta a punta
```

## Limitaciones

- El calendario es simulado. Un proveedor real debe implementar las funciones de `src/agenda/calendario.js`.
- Las credenciales son de demostración y el servidor escucha solo en `127.0.0.1`. Cámbialas antes de exponerlo.
- SQLite sirve para esta demo con un solo proceso. Para varias instancias habría que usar otra base de datos.
- `ver_respuesta` reemplaza la integración con un canal real de mensajería.

## Licencia

[MIT](LICENSE)