Agent-Chatroom-MCP

Öffentliche Vorschau in Vorbereitung: Die Kernfunktionen funktionieren, aber die installierbare Distribution und die Anbindung an den neuesten Claude Code channel befinden sich noch in der Entwicklung. Die öffentliche Roadmap finden Sie in ROADMAP.md, Informationen zur Mitarbeit in CONTRIBUTING.md.

Wenn mehrere Sub-Agenten gleichzeitig arbeiten, ist dies ein MCP-Tool, das Agenten unmittelbar vor wichtigen Entscheidungen anhält und es einem Menschen ermöglicht, in Echtzeit über Dashboard oder Telefon zu genehmigen, Feedback zu geben und einzugreifen.

Der Kern ist ein Blocking-Gate – der Agent stoppt unmittelbar vor riskanten oder schwer umkehrbaren Aktionen (Deploy, Löschung, externe Aufrufe …) und wartet, bis ein Mensch antwortet. Die Antwort erfolgt nicht im Terminal, sondern direkt über Buttons und Eingabefelder im menschlichen Kontroll-Dashboard (einschließlich Telefon im selben WLAN).

Oben: Live-Demo des Kontroll-Dashboards – rechts wird das NEEDS YOU-Gate (Genehmigungs-Button, Feedback-Eingabe, Blocker-Auflösung) direkt von einem Menschen bearbeitet. Links die Roster (Status pro Agent), in der Mitte der Stream (Datums-Trennlinien, Typ-Filter). Auf dem Desktop als 3-Pane-Layout, auf Mobilgeräten als Bottom Sheet adaptiert. (Demo-Status aus seed.py)

Warum wurde das entwickelt (Kernwerte)

• 🚦 Blocking-Gate – Der Agent stoppt unmittelbar vor einer Entscheidung und wartet auf einen Menschen. Keine Benachrichtigung, die durch Polling ignoriert werden kann, sondern ein echter Eingriffspunkt, der erst durch eine menschliche Antwort aufgelöst wird.

• 📱 Dashboard/Telefon bidirektional – Ohne Terminal wird der gestoppte Agent über [Genehmigen]/[Ablehnen]-Buttons, Feedback-Eingabefelder und Blocker-Auflösungs-Eingabefelder fortgesetzt. Auch unterwegs per Telefon eingreifbar.

• 🗄️ SQLite als Single Source of Truth – Verschiedene Sub-Agenten teilen sich eine einzige DB-Datei (WAL) und führen ihre Zustände zusammen. Kein In-Memory, alle Zeiten in UTC ISO 8601.

Related MCP server: @looppause/mcp

Funktionen

Drei Arten von Gates (MCP-Tools)

Alle Gates arbeiten DB-poll-basiert – der Server schreibt pending in die DB und wartet per Polling auf die menschliche Entscheidung (Dashboard-Buttons/Eingabefelder schreiben in die DB). Der Agent ist währenddessen blockiert.

Monitoring-Dashboard

• Raum-Trennung und -Wechsel – Chatrooms pro Aufgabe als Tabs wechseln (Deep-Link ?room=).

• Aufmerksamkeits-Badge pro Raum – Auch wenn man andere Räume ansieht, werden Genehmigungs- + Feedback-Warteschlangen (Amber) und offene Blocker (Rot) dieses Raums als Badge angezeigt.

• NEEDS YOU-Panel – Die drei Gate-Arten, die auf einen Menschen warten, werden ganz oben hervorgehoben.

• Roster mit 4 Zuständen – Abgeleiteter Status pro Agent (Wartend 🟡 > Blocker 🔴 > Fertig 🟢 > In Arbeit 🔵).

• Typ-Filter – Stream über Nachrichtentyp-Chips filtern.

• Datums-Trennlinien – Datumsgrenzen im Stream anzeigen (Heute/Gestern/YYYY-MM-DD (Wochentag)).

• Automatische Aktualisierung – Polling alle 1–2 Sekunden, Hinweis bei leerem Zustand.

Weitere MCP-Tools

• post_message – Nachricht protokollieren · read_messages – Abrufen (unterstützt since·limit).

• wait_for_message – Warten auf Erwähnung für bestehende sitzungsbasierte Worker. Der neueste channel-basierte Ersatzpfad wird in v6 validiert.

• join_room / leave_room / kick / set_presence – Raum-Mitgliedschaft und Status.

Aktuelle Erweiterungen

• Raumverwaltung – Erstellen, Anzeigenamen ändern, Soft Delete, Wiederherstellen aus dem Papierkorb, endgültiges Löschen nach Backup.

• v4 Lokaler Moderator-PoC – GGUF-Modell-Bewertung, Routing, DB-Bridge und Vergleichs-Harness. Modelle werden nicht automatisch heruntergeladen.

• v5 Event-Spawn – Erwähnungsbasierte Claude-CLI-Worker, Rollen, Modelle, Aufwand, Budget, autonomes Ping-Pong und Dashboard-Steuerpult.

• v6-Planung – Aufwecken von idle-Sitzungen ohne Schleifen, Arbeitsbereiche, gemeinsames/Rollen-Speicher und Sitzungsnachfolge. Noch nicht implementiert.

Schnellstart

Anfängerfreundlich: Kopieren und führen Sie Zeile für Zeile aus. Voraussetzung: Python 3.13 + ein in diesem Ordner erstelltes virtuelles Environment (.venv).

1) Abhängigkeiten installieren

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

2) MCP-Server registrieren (stdio)

Registrieren Sie diesen Server in Claude Code. Ersetzen Sie /absoluter/pfad durch den tatsächlichen Pfad dieses Projekts.

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

→ Nach der Registrierung können Sie die Verbindung in Claude Code mit /mcp prüfen; die Tools werden in der Form mcp__agent-chatroom__* angezeigt.

3) Dashboard starten (separater Prozess vom MCP-Server)

Der einfachste Weg ist ein Einzeiler-Launcher (Vorab-Prüfungsausgabe + startet das vorhandene Dashboard unverändert, kein neues Verhalten):

python launch.py

Die bisherigen manuellen Befehle funktionieren weiterhin:

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

→ Im Browser http://127.0.0.1:7777 öffnen. Wenn ein Gate wartet, muss das Dashboard eingeschaltet sein, damit ein Mensch antworten kann.

Auch vom Telefon im selben WLAN ansehen:

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

→ Die beim Start ausgegebene Adresse Telefon-Zugriff: http://192.168.x.x:7777 im Telefon-Browser öffnen.

4) Demo-Zustand erkunden

Um das Dashboard ohne echte Agenten anzusehen, werden die Beispieldaten auf einmal eingefügt.

.venv/bin/python3 seed.py

→ Die aktuelle DB wird automatisch gesichert (chatroom.db.<Zeitstempel>.bak) und dann mit einer Demo gefüllt, die 2 Räume, 3 Gate-Arten und den Roster mit 4 Zuständen zeigt. Der obige Screenshot zeigt diesen Zustand.

🔐 Sicherheit

• Der Schreibpfad (Genehmigung) des Dashboards ist nur für lokal/dasselbe Netzwerk gedacht. Im 0.0.0.0-Modus kann jeder im selben WLAN zugreifen und genehmigen – nur in vertrauenswürdigen Netzwerken verwenden.

• Kein Port-Forwarding über den Router hinaus (Internet) – das wird zum Ziel weltweiter Scans.

• Für die Nutzung außerhalb des WLANs (z. B. LTE) wird ein Tailscale-Privatnetz empfohlen. Nur Geräte des eigenen Kontos erreichen es, und da kein Port ins Internet geöffnet wird, übernimmt der Tunnel die Authentifizierung. Beim Start mit 0.0.0.0 wird automatisch → Tailscale: http://100.x:7777 in der Startausgabe angezeigt. Installations- bis Telefon-Zugriffsverfahren: PHASE3-TAILSCALE.md. (Öffentliche Freigabe wie Tailscale Funnel ist verboten.)

• Wenn beim ersten Start der macOS-Dialog „Eingehende Verbindungen erlauben“ erscheint, muss dieser erlaubt werden, damit das Telefon das Dashboard sehen kann. Der Port kann über DASHBOARD_PORT geändert werden.

Hinweise zur Verwendung

• Lassen Sie das Dashboard während eines wartenden Gates eingeschaltet. request_approval stoppt den Agenten, bis ein Mensch entscheidet (oder bis timeout_seconds abläuft). Wenn das Dashboard ausgeschaltet ist, kann niemand eine Entscheidung schreiben, und es wird weiter gewartet.

• wait_for_feedback ist ein Soft Gate. Feedback wird über das Dashboard-Eingabefeld empfangen; nach Ablauf von timeout_seconds (Standard 30 Sekunden) wird automatisch fortgefahren. (Da es DB-poll-basiert ist, gibt es keinen Terminal-Dialog – das frühere „Fenster nach Timeout mit Esc schließen“ der elicit-Version ist nicht mehr relevant.)

• Blocker sind fälschungssicher. Sie werden nur über report_blocker erstellt; post_message blockiert den Typ blocker.

Dokumentation

Mitwirken

Willkommen sind Bug-Reproduktionen, Dokumentationsverbesserungen und Untersuchungen zur Betriebssystem-Kompatibilität. Bei größeren Funktionen bitte zuerst in einem Issue Umfang und Sicherheitsgrenzen abstimmen und dann in kleinen PRs umsetzen. Detaillierte Abläufe finden Sie in CONTRIBUTING.md.

Lizenz

Mozilla Public License 2.0. Wenn Sie vorhandene Dateien ändern und verteilen, müssen Sie den geänderten Quellcode dieser Dateien gemäß den MPL-2.0-Bedingungen offenlegen; größere Werke, die als separate Dateien kombiniert werden, können unter anderen Bedingungen verteilt werden.