エージェントチャットルーム MCP

公開プレビュー準備中: コア機能は動作しますが、インストール型配布と最新の Claude Code channel 連携はまだ開発中です。公開ロードマップは ROADMAP.md、コントリビュート方法は CONTRIBUTING.md を参照してください。

複数のサブエージェントが同時に作業するとき、重要な決定の直前にエージェントを停止させ、人がダッシュボード・スマホからリアルタイムに承認・フィードバック・介入を行えるようにする MCP ツールです。

核心はブロッキングゲート — エージェントが危険または取り消しの難しい行動(デプロイ、削除、外部呼び出し…)の直前に停止し、人が回答するまで待機します。回答はターミナルではなく人用の監視ダッシュボード(同じWi-Fi上のスマホを含む)でボタン・入力欄から直接行います。

上: 監視ダッシュボードのライブデモ — 右側の NEEDS YOU にあるゲート(承認ボタン・フィードバック入力・ブロッカー解消)を人が直接処理します。左側は ロスター(エージェント別ステータス)、中央は ストリーム(日付区切り線・タイプフィルター)。デスクトップは3ペイン、モバイルはボトムシートに適応します。これは(seed.py デモ状態)

なぜ作ったのか (コアバリュー)

• 🚦 ブロッキングゲート — エージェントが決定直前に停止して人を待ちます。ポーリングで確認される通知ではなく、人が回答して初めて解除される真の介入ポイントです。

• 📖 ダッシュボード/スマホ 双方向 — ターミナルなしで [承認]/[拒否]ボタン、フィードバック入力欄、ブロッカー解消入力欄から停止中のエージェントを再開させます。外出先でもスマホから介入できます。

• 🗄️ SQLite 単一真実ソース — 異なるサブエージェントがひとつのDBファイルを共通して状態を統合します。インメモリはなく、時刻はすべて UTC 環境 ISO 8601 です。

Related MCP server: Agent Team MCP Server

機能

ゲート3種 (MCPツール)

ゲートはすべて DBポーリング方式 — サーバーが pending を DBに記録し、人の決定(ダッシュボードのボタン・入力欄がDBに書き込む)をポーリングしながら待ちます。その間エージェントはブロッキングされます。

監視ダッシュボード

• 部屋の分離・切替 — 作業ごとのチャットルームをタブで切替(ディープリンク ?room=)。

• 部屋ごとの注意バッジ — 他の部屋を表示していても、その部屋の 承認+フィードバック待ち(アンバー)・通行ブロッカー(レッド)をバッジで通知します。

• NEEDS YOUパネル — 人を待つゲート3種を最上部に強調表示します。

• ロスター4状態 — エージェント別ステータスを導出(待機 🟡 > ブロッカー 🔴 > 完了 🟢 > 作業中 🔵)。

• タイプフィルタ — メッセージタイプのチップでストリームを絞り込みます。

• 日付区切り線 — ストリームに日付境界を表示(今日/昨日/YYYY-MM-DD (요일))。

• 自動更新 — 1〜2秒のポーリング、空ステートの表示。

その他の MCP ツール

• post_message — メッセージ記録 ・ read_messages — 照会(since・limit 対応)。

• wait_for_message — 既存のセッション型ワーカーがミコンションを待機する。最新の channel ベースの代替パスは v6 で検証予定。

• join_room / leave_room / kick / set_presence — ルームのメンバーシップと状態。

現在の拡張機能

• 部屋管理 — 作成、表示名変更、論理削除、ゴミ箱の復元、バックアップ後の消去。

• v4 ローカル仲裁者 PoC — GGUF モデルの格付け・ルーティング・DB ブリッジとの比較ハーネス。モデルは自動ダウンロードしません。

• v5 イベントスポーン — メンションベースの Claude CLI ワーカー、役割・モデル・働き・予算・自律ピンポンとダッシュボードのコントロールパネル。

• v6 企画 — ループなしのアイドルセッション復帰、ワークスペース、共通ロールメモリ、セッション引継ぎ。まだ実装前です。

クイックスタート

初心者向け: 1行ずつコピーして実行してください。事前準備は 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

→ 登録後、Claude Code で /mcp 接続を確認すると、ツールが 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

→ 現在のDBを自動バックアップ(chatroom.db.<시각>.bak)したあと、2つの部屋・3つのゲート・4状態のロスターが確認できるデモに更新します。上のスクリーンショットはこの状態です。

🔐 セキュリティ

• **ダッシュボードへの書き込み(承認)経路はローカル/同一ネットワーク専用。**スパム 0.0.0.0 モードでは同じWi-Fi内の誰でもアクセス・承認できるため、信頼できるネットワークでのみ使ってください。

• ルーターの外側(インターネット)へのポートフォワーディングはしないでください — 世界中のスキャン対象になります。

• Wi-Fi の外(例: LTE)でも使うには Tailscale プライベートネットワークを推奨します。 自分のアカウントの端末間だけで閉じ、インターネットにポートを open しないため、トンネルが認証を代行します。0.0.0.0 で起動すると、起動出力に → Tailscale: http://100.x:7777 が自動表示されます。インストール〜スマホ接続の手順は PHASE3-TAILSCALE.md。(Tailscale Funnel などの公開塗布は禁止。)

• 初回起動時に macOS の「受信する接続を許可」ポップアップが出たら許可すると、スマホから見えます。ポートは DASHBOARD_PORT で変更できます。

利用時の注意点

• ゲート待機中のダッシュボードを ON にしてください。 request_approval は人が決定するまで(または timeout_seconds まで)エージェントを停止します。ダッシュボードが OFF だと誰も決定を書き込めず、待機し続けます。

• wait_for_feedback はソフトゲート。 ダッシュボードの入力欄でフィードバックを受け取り、timeout_seconds(デフォルト 30秒)の経過後は 自動で進行します。(DB ポーリング方式のためターミナルダイアログは存在しません — 従来の elicit 版の「タイムアウト後に Esc でウィンドウを閉じる」はもはや該当しません。)

• ブロッカーは非改ざん。 report_blocker でのみ生成され、post_message は blocker を拒否します。

ドキュメント

コントリビュート

バグの再現、ドキュメントの改善、OS の互換性調査などから歓迎します。大きな機能はまず課題で範囲と安全境界を合意した後、小さな PR に分けてください。詳細な手順は CONTRIBUTING.md にあります。

ライセンス

Mozilla Public License 2.0。既存のファイルを変更して配布する場合は、そのファイルの修正ソースを MPL-2.0 条件に従って公開する必要があります。別ファイルで結合したより大きな成果物は、別の条件で配布できます。