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.

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.

Related MCP server: @looppause/mcp

Cómo funciona

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:

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.

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:

# 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

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

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