MCP чат-комната для агентов

Готовится к публичному предпросмотру: основные функции работают, но установочное развёртывание и интеграция с новейшим каналом Claude Code ещё в разработке. Публичный роадмап — в ROADMAP.md, способы участия — в CONTRIBUTING.md.

Когда несколько субагентов работают одновременно, этот MCP-инструмент останавливает агента прямо перед важным решением и позволяет человеку в реальном времени одобрять, давать обратную связь и вмешиваться через дашборд или телефон.

Ключевая идея — блокирующий шлюз (gate): агент останавливается перед рискованным или труднообратимым действием (развёртывание, удаление, внешние вызовы…) и ждёт ответа человека. Ответ даётся не в терминале, а через дашборд для человека (включая телефон в той же Wi-Fi-сети) — кнопками и полями ввода.

Выше: живое демо дашборда управления — справа в блоке NEEDS YOU человек обрабатывает шлюзы (кнопка одобрения, поле обратной связи, снятие блокера). Слева — ростер (статусы агентов), по центру — поток (разделители по датам, фильтр по типам). На десктопе — трёхпанельный вид, на мобильном — нижняя панель (bottom sheet). (Демо-состояние из seed.py)

Зачем это сделано (ключевая ценность)

• 🚦 Блокирующий шлюз — агент останавливается перед решением и ждёт человека. Это не уведомление, которое можно проигнорировать при опросе, а настоящая точка вмешательства, которая снимается только ответом человека.

• 📱 Двусторонний дашборд/телефон — без терминала: кнопки [Одобрить]/[Отклонить], поле обратной связи и поле снятия блокера позволяют продолжить остановленного агента. Можно вмешаться с телефона, даже находясь вне дома.

• 🗄️ SQLite как единый источник истины — разные субагенты используют один файл БД (WAL) и согласуют состояние. Никакой памяти в процессе, все времена — UTC ISO 8601.

Related MCP server: @looppause/mcp

Возможности

Три типа шлюзов (MCP-инструменты)

Все шлюзы работают через опрос БД — сервер записывает ожидание (pending) в БД и опрашивает решение человека (кнопки/поля дашборда пишут в БД). Агент тем временем заблокирован.

Дашборд мониторинга

• Разделение и переключение комнат — переключение чат-комнат по задачам вкладками (глубокая ссылка ?room=).

• Бейджи внимания по комнатам — даже при просмотре другой комнаты бейджи показывают ожидание одобрения+обратной связи (янтарный) и открытые блокеры (красный) в этой комнате.

• Панель NEEDS YOU — три типа шлюзов, ожидающих человека, выделены в самом верху.

• Ростер с 4 состояниями — производные статусы агентов (ожидание 🟡 > блокер 🔴 > завершено 🟢 > работает 🔵).

• Фильтр по типам — фильтрация потока чипами типов сообщений.

• Разделители по датам — границы дат в потоке (сегодня/вчера/YYYY-MM-DD (день недели)).

• Автообновление — опрос каждые 1–2 секунды, подсказка при пустом состоянии.

Прочие MCP-инструменты

• post_message — запись сообщения · read_messages — чтение (поддержка since и limit).

• wait_for_message — ожидание упоминания для существующих сессионных воркеров. Новейший альтернативный путь на основе каналов будет проверен в v6.

• join_room / leave_room / kick / set_presence — членство в комнате и статус.

Текущие расширения

• Управление комнатами — создание, изменение отображаемого имени, мягкое удаление, восстановление из корзины, окончательное удаление после резервной копии.

• v4 PoC локального модератора — оценка и маршрутизация моделями GGUF, мост к БД и сравнительный стенд. Модели автоматически не загружаются.

• v5 порождение событий — воркеры Claude CLI на основе упоминаний, роли, модели, уровень усилий, бюджет, автономный пинг-понг и панель управления на дашборде.

• v6 планирование — пробуждение бездействующих сессий без циклов, рабочее пространство, общая/ролевая память и наследование сессий. Пока не реализовано.

Быстрый старт

Для новичков: копируйте и выполняйте по одной строке. Предварительная подготовка — Python 3.13 + виртуальное окружение (.venv), созданное в этой папке.

1) Установка зависимостей

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

2) Регистрация MCP-сервера (stdio)

Зарегистрируйте этот сервер в Claude Code. Замените /абсолютный_путь на реальный путь к этому проекту.

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

→ После регистрации проверьте подключение через /mcp в Claude Code — инструменты будут доступны в виде mcp__agent-chatroom__*.

3) Запуск дашборда (отдельный процесс от MCP-сервера)

Самый простой способ — однострочный лаунчер (вывод предварительной проверки + запуск существующего дашборда как есть, без нового поведения):

python launch.py

Прежние ручные команды тоже работают:

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

→ В браузере откройте http://127.0.0.1:7777. Если шлюз ожидает ответа, дашборд должен быть включён, иначе человек не сможет ответить.

Чтобы смотреть с телефона в той же Wi-Fi-сети:

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

→ Откройте в браузере телефона адрес Телефонный доступ: http://192.168.x.x:7777, который выводится при запуске.

4) Осмотр в демо-состоянии

Чтобы посмотреть дашборд без реальных агентов, загрузите образцы данных одной командой.

.venv/bin/python3 seed.py

→ Сначала автоматически создаётся резервная копия текущей БД (chatroom.db.<время>.bak), затем БД заполняется демо-данными: 2 комнаты, 3 типа шлюзов, 4 состояния ростера. Это состояние показано на скриншоте выше.

🔐 Безопасность

• Путь записи (одобрения) на дашборде — только локально/в той же сети. В режиме 0.0.0.0 любой в той же Wi-Fi-сети может подключиться и одобрять — используйте только в доверенной сети.

• Не делайте проброс портов за пределы роутера (в интернет) — вы станете целью мирового сканирования.

• Для использования вне Wi-Fi (например, через LTE) рекомендуется частная сеть Tailscale. Доступ только между устройствами вашего аккаунта, порты в интернет не открываются — туннель выполняет роль аутентификации. При запуске с 0.0.0.0 в стартовом выводе автоматически появится адрес → Tailscale: http://100.x:7777. Процедура установки и подключения телефона — в PHASE3-TAILSCALE.md. (Публичное раскрытие, например Tailscale Funnel, запрещено.)

• При первом запуске macOS может показать всплывающее окно «Разрешить входящие подключения» — разрешите, чтобы дашборд был виден с телефона. Порт можно изменить через DASHBOARD_PORT.

Что нужно знать при использовании

• Держите дашборд включённым, пока шлюз ожидает ответа. request_approval останавливает агента до решения человека (или до timeout_seconds). Если дашборд выключен, никто не сможет записать решение, и ожидание продолжится.

• wait_for_feedback — мягкий шлюз. Обратная связь принимается через поле на дашборде, а по истечении timeout_seconds (по умолчанию 30 секунд) происходит автоматическое продолжение. (Метод опроса БД не использует диалог в терминале — прежнее поведение elicit-версии «закрыть окно по Esc после таймаута» больше не применяется.)

• Блокеры защищены от подделки. Они создаются только через report_blocker; post_message запрещает тип blocker.

Документация

Участие

Приветствуются воспроизведение багов, улучшение документации, исследование совместимости с ОС. Для крупных функций сначала согласуйте объём и границы безопасности в issue, затем разбивайте на небольшие PR. Подробная процедура — в CONTRIBUTING.md.

Лицензия

Mozilla Public License 2.0. При распространении с изменениями существующих файлов вы должны раскрыть изменённые исходники этих файлов на условиях MPL-2.0; более крупные работы, объединяющие их с отдельными файлами, могут распространяться на других условиях.