bongocat-mcp

様々な「BongoCat 猫」を MCP ツールとして統一的にラップする独立コントローラー——BongoCat リポジトリから完全に分離しており、astrbot などの MCP クライアント / LLM が猫のキーアニメーション / タイピング / 表情 / チャットバブルを能動的に制御でき、猫の再コンパイルは不要です。ローカル Web ダッシュボード付きで、状態確認と設定編集が簡単にできます。

完全な設計ドキュメント：要件書 docs/requirements.md · アーキテクチャ実装書 docs/architecture.md。

対応する3種類の猫（自動検出、設定で強制指定も可能）

mver 受信モードの代償とミラーレイヤー：Mver がネットワーク受信を有効にすると、ローカルのキーボード/マウスを無視し、ネットワークパケットのみをレンダリングします。 mver ドライバーの送信スレッドは 60fps で実際のキーボード/マウス（GetAsyncKeyState/GetCursorPos）を読み取って転送し、 猫の動作はローカルモードと一致します（遅延は約1フレーム）；AI コマンドはオーバーレイとして重ねられます。MCP/ミラープロセスが停止すると 猫はキーボード/マウス応答を失います（再実行で復旧）；同時に実行できる Mver インスタンスは1つだけです。

Related MCP server: Vox MCP

新しい猫の自動接続（mver）

• 自動認識：ダッシュボードの状態ポーリングが5秒ごとに実行中の Mver プロセスを検出；設定された猫が起動していない（または未設定）場合に 別の猫が起動していれば、自動的に mver_dir を実行中の猫に切り替えてドライバーを再構築（イベントログに切り替え記録が表示されます）

• ワンクリック接続：ダッシュボードの「🚀 一键接入 Mver 新猫」ボタンで自動完了——実行中の猫を特定 → その config.json をテキストレベルで書き換えてネットワーク同期を有効化（受信モード、作者のコメントは保持；猫自身の設定画面と 同じファイルに書き込むため、プログラム本体は変更しません）→ 管理者権限で猫プロセスを再起動 → ドライバーを再構築

• 新しくインストールしたスキン版 Mver はデフォルトで network:false（UDP をリッスンしない）のため、ワンクリック接続で修正可能；手動で 猫の設定でネットワーク同期を有効にし、受信モードに設定することもできます

• 注意：同時に1つの Mver インスタンスだけが受信ポートを占有できます

クイックスタート

python -m venv .venv
.venv\Scripts\activate            # Windows；macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

# 方式一：仪表盘（推荐日常使用，自动打开浏览器）
python dashboard.py               # 默认隐藏窗口后台运行
python dashboard.py --stop        # 停止后台仪表盘
python dashboard.py --visible     # 前台调试模式（终端可见）

# 方式二：MCP stdio server（供 astrbot 拉起）
python server.py

# 方式三：只让接收模式的 Mver 恢复键鼠跟随（不开 AI）
python mver-mirror.py               # 默认隐藏窗口后台运行
python mver-mirror.py --stop        # 停止隐藏运行的镜像
python mver-mirror.py --visible     # 前台调试模式（Ctrl+C 退出）

# 本地回归测试（自动探测 driver；或传 embedded / cdp / mver）
python test_client.py

ZCode プラグイン（bongocat-notify）

zcode-plugin/ ディレクトリはローカルプラグインマーケット + プラグインであり、Zcode をこの MCP サーバーに接続します：

• MCP 接続：.mcp.json で server.py を stdio MCP サーバーとして登録 （ツール名 mcp__bongo-cat__*）、エージェントは直接猫を制御可能；/bongo-test コマンドで全チェーン自己診断

• タスク通知：フックが Zcode の主要イベントで猫のバブル + 表情切り替えを駆動—— Stop（タスク完了→キラキラ目）、PermissionRequest（承認待ち→疑問）、 PostToolUseFailure（エラー→泣き）、SessionStart / UserPromptSubmit（作業開始）

• 表情はインデックスをハードコードせず：毎回 get_cat_status の表情リストをリアルタイムに読み、名前のキーワードでマッチング、 スキン変更に自動対応；フックはダッシュボードの HTTP API を使用（python dashboard.py を実行しておく必要あり）、 ダッシュボードが無い場合は静かにスキップし、セッションをブロックしません

インストール：Zcode → 設定 → プラグイン管理 → 発見 → + でローカルマーケットディレクトリ zcode-plugin/ を追加し、bongocat-notify をインストールするだけです（詳細は zcode-plugin/bongocat-notify/README.md を参照）。

ZCode / AstrBot や他のクライアント向けに独自の猫通知プラグインを開発したいですか？ 接続チャネルの選定、プラグインのスケルトンテンプレート、表情の拡張性に関する規約と検証方法論は 接続開発ガイド docs/zcode-plugin-dev.md を参照してください。

Claude Code プラグイン（bongocat-notify）

claude-plugin/ は同じ「ローカルマーケット + プラグイン」の Claude Code 版です（ZCode 版と機能は同等）：

• MCP 接続：.mcp.json で server.py を stdio MCP サーバーとして登録 （ツール名も同じ mcp__bongo-cat__*）、/bongo-test コマンドで全チェーン自己診断

• タスク通知：イベントモデルに違いあり——Claude Code には PermissionRequest / PostToolUseFailure イベントがなく、承認待ちは Notification で表現（message のキーワードで アイドル通知をフィルタリング）、ツールエラーは PostToolUse の tool_response で控えめに判定

インストール：claude plugin marketplace add claude-plugin/目录 → claude plugin install bongocat-notify@bongocat-local、セッション再起動後に /mcp で確認 （詳細は claude-plugin/bongocat-notify/README.md を参照）。

Codex プラグイン（bongocat-notify）

codex-plugin/ は同じプラグインの OpenAI Codex CLI 版です（ZCode 版と機能は同等）：

• MCP 接続：.mcp.json（Codex ネイティブ直接接続サーバー形式）で server.py を stdio MCP サーバーとして登録、bongo-test スキル（skills/*/SKILL.md、Codex のカスタム prompts は廃止され、スキルが公式の代替）で全チェーン自己診断

• タスク通知：Codex フックは ZCode イベントとほぼ一対一対応——PermissionRequest はネイティブイベント；ツールエラーには PostToolUseFailure がなく、PostToolUse の tool_response で控えめに判定；フックはプラグインマニフェスト（.codex-plugin/plugin.json） にバンドルされ、すべて async でバックグラウンド実行され、ターンをブロックしません

インストール：codex plugin marketplace add codex-plugin/目录 → codex plugin install bongocat-notify@bongocat-local → /hooks で5つのフックを 1つずつ Trust（Codex の信頼審査メカニズム、信頼しないと実行されません）→ 新しいセッションで codex mcp list で確認（詳細は codex-plugin/bongocat-notify/README.md を参照）。

設定（config.json、ダッシュボードで編集可能）

読み込み優先度：環境変数 BONGOCAT_* > config.json > デフォルト値。初回使用時は config.example.json を config.json にコピーしてください。

対応する環境変数：BONGOCAT_MCP_DRIVER、BONGOCAT_APP_PATH、BONGOCAT_CDP_PORT、 BONGOCAT_MVER_DIR、BONGOCAT_MVER_PORT、BONGOCAT_MCP_HOST、 BONGOCAT_MCP_CONFIG、BONGOCAT_MCP_PORT、BONGOCAT_MCP_TOKEN（旧版と互換性あり）。

ダッシュボード

python dashboard.py で起動（ブラウザが自動的に開きます）、内容：

• 状態概要：現在のドライバー、能力マトリクス（緑=対応 / グレー=その猫は非対応）、猫の状態（モデル/モード/ウィンドウ）、 mver ミラースレッド、2秒ポーリングで更新

• ドライバー選択：自動 / embedded / cdp / mver、切り替えると保存してドライバーを再構築

• 設定編集：config.json の全キーをビジュアル編集

• ツールお試し台：Webページ上で全コマンドを直接呼び出し（表情ドロップダウン、キー入力、タイピング、バブル、ウィンドウ表示/非表示、 set-hand）、直近200件のイベントログ付き

ダッシュボードと astrbot の stdio サーバーはそれぞれ独立したドライバーインスタンスを持ち、並行使用可能； embedded / cdp は競合なし、mver の二重ミラーは良性の重ね合わせ（2系統の同一状態フレーム）、 チャットバブルは2つのプロセスでそれぞれ1つずつレンダリングされる可能性があります。

MCP ツール（14個のツール、12個の統一コマンドにマッピング、全ドライバーで共通）

能力はアセット認識です：mver スキンは、モデルディレクトリに実際に表情/動作素材ファイルが存在する場合のみ 対応能力をアドバタイズし、それ以外は正直に非対応と報告します（無効なレガシー設定を能力と誤認するのを防ぎます）。

セキュリティ注意事項

• すべてのチャネルはローカルループバックアドレスのみにバインド；embedded チャネルは起動ごとにランダムな Bearer token

• cdp の WebView2 デバッグポート（デフォルト 127.0.0.1:9223）はローカル制御面のため、使用しないときはデバッグポート付きの猫を長時間起動したままにしないでください

• cdp の引き継ぎは実行中の猫を一度再起動します；同時にサポートする猫は1匹のみ

プロジェクト構造

bongocat-mcp\
  bongocat_mcp\           # 核心包
    config.py             # 统一配置（env > config.json > 默认）
    detect.py             # driver 探测/切换
    dispatch.py           # 命令调度（能力门控 + 事件日志）
    drivers\              # embedded_http / cdp_webview2 / mver_udp / win32_utils
    bubble\overlay.py     # bridge 自绘聊天气泡窗
  server.py               # MCP stdio 入口
  dashboard.py            # FastAPI 仪表盘
  web\index.html          # 仪表盘前端（原生单页，无构建）
  mver-mirror.py          # Mver 独立镜像进程
  zcode-plugin\           # ZCode 插件（本地市场 + bongocat-notify）
  claude-plugin\          # Claude Code 插件（本地市场 + bongocat-notify）
  codex-plugin\           # Codex CLI 插件（本地市场 + bongocat-notify）
  docs\                   # 需求/架构/接入文档；验证截图为本地存档不入库

Mver UDP プロトコル（実証リバースエンジニアリングノート）

• 312バイトの全量状態フレーム、60fpsで連続送信、ハンドシェイクなし

• bytes[0..255]：VK インデックスのキー状態；0x81=押下（押している間ずっと送信）、 0x80=解放エッジフレーム、0x00=アイドル；VK 0x01/0x02 = マウスの左右ボタン

• bytes[256..311]：14個の float、fl[8]=0.8×カーソルx/画面幅、fl[9]=0.8×カーソルy/画面高さ

• 固定スロット 0x90/0xF0/0xF3/0xF6/0xFB = 0x01

• コンビネーションキーバインドは時系列で押下が必要（修飾キーを先に押し続けて ≥0.3s 後にトリガーキーを押す）

• mode：1=標準、2=キーボード、3=ゲームパッド（BongoCatMverUI ソースコードより）