Sala de chat de agentes MCP

Vista previa pública en preparación: las funciones principales funcionan, pero la distribución instalable y la integración con el canal más reciente de Claude Code aún están en desarrollo. Consulta la hoja de ruta pública en ROADMAP.md y cómo contribuir en CONTRIBUTING.md.

Cuando varios subagentes trabajan a la vez, detén al agente justo antes de una decisión importante y permite que una persona apruebe, intervenga o dé feedback en tiempo real desde un panel de control o el teléfono. Es una herramienta MCP.

El núcleo es la puerta de bloqueo — el agente se detiene justo antes de una acción arriesgada o difícil de revertir (despliegues, eliminaciones, llamadas externas…) y espera hasta que una persona responda. La respuesta no se da en la terminal, sino directamente con botones y campos de entrada en el panel de control para humanos (incluido desde el teléfono en la misma red wifi).

Arriba: demostración en vivo del panel de control — a la derecha, la puerta NEEDS YOU (botón de aprobar, campo de feedback, resolución de bloqueos) la gestiona una persona directamente. A la izquierda, el roster (estado por agente), en el centro, el stream (separadores por fecha, filtros por tipo). En escritorio se adapta a 3 paneles, en móvil a una hoja inferior. (Estado de demostración con seed.py)

Por qué se creó (valores fundamentales)

• 🚦 Puerta de bloqueo — el agente se detiene justo antes de decidir y espera a la persona. No es una notificación que pueda ignorarse mediante sondeo, sino un punto de intervención real que solo se desbloquea cuando la persona responde.

• 📱 Panel de control/teléfono bidireccional — sin terminal, con botones [aprobar]/[rechazar], campos de feedback y resolución de bloqueos se hace avanzar al agente detenido. Intervención desde el teléfono incluso estando fuera.

• 🗄️ SQLite como fuente única de verdad — los distintos subagentes comparten un único archivo de base de datos (WAL) para consolidar el estado. Sin modo en memoria, todas las marcas de tiempo en UTC ISO 8601.

Related MCP server: @looppause/mcp

Funciones

Puertas de 3 tipos (herramientas MCP)

Todas las puertas usan sondeo de base de datos — el servidor registra el estado pendiente en la base de datos y espera sondeando la decisión de la persona (el botón o el campo del panel escriben en la base de datos). Mientras tanto, el agente permanece bloqueado.

Panel de control de monitoreo

• Separación y cambio de salas — cambio entre salas de chat por pestañas según la tarea (enlace directo ?room=).

• Insignia de atención por sala — incluso al ver otra sala, una insignia indica aprobación + feedback pendiente (ámbar) y bloqueos abiertos (rojo) en esa sala.

• Panel NEEDS YOU — las 3 puertas que esperan a una persona se destacan en la parte superior.

• Roster con 4 estados — estado derivado por agente (en espera 🟡 > bloqueado 🔴 > completado 🟢 > trabajando 🔵).

• Filtro por tipo — filtra el stream por tipo de mensaje mediante chips.

• Separadores por fecha — límites de fecha en el stream (hoy/ayer/AAAA-MM-DD (día de la semana)).

• Actualización automática — sondeo cada 1~2 segundos, con indicación de estado vacío.

Otras herramientas MCP

• post_message — registra mensajes · read_messages — consulta (admite since·limit).

• wait_for_message — espera de menciones para workers de sesión existentes. La ruta alternativa basada en el canal más reciente se validará en v6.

• join_room / leave_room / kick / set_presence — pertenencia a salas y estado.

Funciones actuales de extensión

• Gestión de salas — creación, cambio de nombre visible, eliminación suave, restauración desde papelera, eliminación permanente tras copia de seguridad.

• PoC de moderador local v4 — comparativa con modelos GGUF para juicio, enrutamiento y puente con la base de datos. El modelo no se descarga automáticamente.

• Generación de eventos v5 — workers de Claude CLI basados en menciones, con roles, modelos, nivel de esfuerzo, presupuesto y ping-pong de autonomía, más controles en el panel.

• Planificación v6 — activación de sesiones inactivas sin bucle, espacio de trabajo, memoria compartida por rol y sucesión de sesiones. Aún no implementado.

Inicio rápido

Para principiantes: copia y ejecuta línea por línea. Requisito previo: Python 3.13 + entorno virtual creado en esta carpeta (.venv).

1) Instalación de dependencias

.venv/bin/python3 -m pip install -r requirements.txt

2) Registro del servidor MCP (stdio)

Registra este servidor en Claude Code. Reemplaza /ruta/absoluta por la ruta real de este proyecto.

claude mcp add agent-chatroom -e CHATROOM_DB=/절대경로/chatroom.db -- /절대경로/.venv/bin/python3 /절대경로/src/server.py

→ Tras el registro, verifica la conexión en Claude Code con /mcp; las herramientas aparecerán con el formato mcp__agent-chatroom__*.

3) Encender el panel de control (proceso independiente del servidor MCP)

La forma más sencilla es un lanzador de una sola línea (muestra la verificación previa y enciende el panel existente, sin comportamientos nuevos):

python launch.py

El comando manual existente también funciona igual:

.venv/bin/python3 src/dashboard/server.py

→ Abre en el navegador http://127.0.0.1:7777. Si hay puertas en espera, el panel debe estar encendido para que una persona pueda responder.

¿Quieres verlo también desde el teléfono en la misma red wifi?

DASHBOARD_HOST=0.0.0.0 .venv/bin/python3 src/dashboard/server.py

→ Al encenderlo se muestra la dirección Conexión desde el teléfono: http://192.168.x.x:7777; ábrela en el navegador del teléfono.

4) Explorar con el estado de demostración

Para ver el panel sin agentes reales, introduce los datos de ejemplo de una vez.

.venv/bin/python3 seed.py

→ Se hace una copia de seguridad automática de la base de datos actual (chatroom.db.<marca de tiempo>.bak) y se rellena con una demostración que muestra 2 salas, las 3 puertas y el roster con 4 estados. La captura de pantalla anterior corresponde a este estado.

🔐 Seguridad

• La ruta de escritura del panel (aprobaciones) es solo para red local/misma red. El modo 0.0.0.0 permite que cualquiera en la misma wifi acceda y apruebe; úsalo solo en redes de confianza.

• No hagas reenvío de puertos hacia fuera del router (internet) — tu equipo se convertirá en objetivo de escaneos globales.

• Para usarlo fuera de la wifi (p. ej., con LTE), se recomienda una red privada Tailscale. Solo los dispositivos de tu cuenta pueden alcanzarlo y no se abre ningún puerto a internet, de modo que el túnel actúa como autenticación. Al encenderlo con 0.0.0.0, en la salida inicial se muestra automáticamente → Tailscale: http://100.x:7777. El procedimiento de instalación y conexión desde el teléfono está en PHASE3-TAILSCALE.md. (Queda prohibida la exposición pública, como Tailscale Funnel).

• Al iniciarlo por primera vez, si macOS muestra el aviso "Permitir conexiones entrantes", debes permitirlo para que se vea desde el teléfono. El puerto se puede cambiar con DASHBOARD_PORT.

Cosas a tener en cuenta al usarlo

• Mantén el panel encendido mientras haya puertas en espera. request_approval detiene al agente hasta que una persona decide (o hasta timeout_seconds). Si el panel está apagado, nadie puede escribir la decisión y la espera continúa indefinidamente.

• wait_for_feedback es una puerta blanda. Recibe el feedback mediante el campo de entrada del panel y, cuando pasa timeout_seconds (por defecto 30 segundos), avanza automáticamente. (Al ser por sondeo de base de datos, no hay diálogo en la terminal — el antiguo comportamiento de la versión elicit de "cerrar la ventana con Esc tras el tiempo de espera" ya no aplica.)

• Los bloqueos están protegidos contra falsificación. Solo se crean mediante report_blocker, y post_message impide el tipo blocker.

Documentación

Contribuciones

Son bienvenidas desde la reproducción de errores, la mejora de la documentación y la investigación de compatibilidad con sistemas operativos. Para funciones grandes, primero acuerda el alcance y los límites de seguridad en un issue y luego divide el trabajo en PR pequeños. El procedimiento detallado está en CONTRIBUTING.md.

Licencia

Mozilla Public License 2.0. Si distribuyes archivos existentes modificados, debes publicar el código fuente modificado de esos archivos según las condiciones de MPL-2.0; los trabajos más grandes que se combinen como archivos separados pueden distribuirse bajo otras condiciones.