bongocat-mcp

A standalone controller that unifies various "BongoCat cats" into MCP tools—fully decoupled from the BongoCat repository, so MCP clients / LLMs such as astrbot can actively control the cat's key-press animations / typing / expressions / chat bubbles, without requiring the cat to be recompiled. Comes with a local web dashboard for viewing status and editing configuration.

Full design docs: Requirements docs/requirements.md · Architecture docs/architecture.md.

Supports three cats (auto-detected, or force-specified via config)

Cost of mver receive mode and the mirror layer: Once Mver enables network receive, it ignores the local keyboard/mouse and only renders network packets. The mver driver's send thread reads real keyboard/mouse at 60fps (GetAsyncKeyState/GetCursorPos) and forwards them, so the cat behaves identically to local mode (about one frame of latency); AI commands are layered on top as an overlay. If the MCP/mirror process stops, the cat loses keyboard/mouse response (restarting restores it); only one Mver instance can run at a time.

Related MCP server: Vox MCP

Auto-onboarding new cats (mver)

• Auto-detection: The dashboard status poll probes for a running Mver process every 5 seconds; if the configured cat is not running (or none is configured) and another one is running, it automatically switches mver_dir to the running cat and rebuilds the driver (switch records are visible in the event log)

• One-click onboarding: The dashboard's "🚀 One-click onboard new Mver cat" button does it all automatically—locate the running cat → rewrite its config.json at the text level to enable network sync (receive mode, preserving author comments; this is the same file its own settings UI writes, without modifying the program itself) → restart the cat process with elevation → rebuild the driver

• Newly installed skin builds of Mver default to network:false (no UDP listening); one-click onboarding fixes it; you can also manually enable network sync in the cat's settings and set it to receive mode

• Note: only one Mver instance can occupy the receive port at a time

Quick start

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 plugin (bongocat-notify)

The zcode-plugin/ directory is a local plugin marketplace + plugin that connects Zcode to this MCP server:

• MCP integration: .mcp.json registers server.py as a stdio MCP server (tool names mcp__bongo-cat__*), so agents can directly control the cat; the /bongo-test command does a full end-to-end self-check

• Task notifications: hooks drive the cat's bubble + expression switching on key Zcode events— Stop (task complete → starry eyes), PermissionRequest (awaiting approval → question), PostToolUseFailure (error → crying), SessionStart / UserPromptSubmit (starting work)

• Expressions are not hardcoded by index: each time it reads the expression list from get_cat_status in real time and matches by name keyword, so it auto-adapts when skins change; hooks go through the dashboard HTTP API (python dashboard.py must stay running), and silently skip when the dashboard is absent—never blocking the session

Install: Zcode → Settings → Plugin management → Discover → + add local marketplace directory zcode-plugin/, then install bongocat-notify (see zcode-plugin/bongocat-notify/README.md for details).

Want to develop your own cat notification plugin for ZCode / AstrBot or other clients? See Integration development guide docs/zcode-plugin-dev.md for channel selection, plugin skeleton templates, expression extensibility conventions, and validation methodology.

Claude Code plugin (bongocat-notify)

claude-plugin/ is the Claude Code version of the same "local marketplace + plugin" setup (feature-equivalent to the ZCode version):

• MCP integration: .mcp.json registers server.py as a stdio MCP server (tool names also mcp__bongo-cat__*); the /bongo-test command does a full end-to-end self-check

• Task notifications: the event model differs—Claude Code has no PermissionRequest / PostToolUseFailure events; pending approval is expressed via Notification (filtered by message keywords for idle prompts), and tool errors are conservatively determined from PostToolUse's tool_response

Install: claude plugin marketplace add claude-plugin/目录 → claude plugin install bongocat-notify@bongocat-local, then verify with /mcp after restarting the session (see claude-plugin/bongocat-notify/README.md for details).

Codex plugin (bongocat-notify)

codex-plugin/ is the OpenAI Codex CLI version of the same plugin (feature-equivalent to the ZCode version):

• MCP integration: .mcp.json (Codex's native direct-connect server format) registers server.py as a stdio MCP server; the bongo-test skill (skills/*/SKILL.md—Codex custom prompts are deprecated, skills are the official replacement) does a full end-to-end self-check

• Task notifications: Codex hooks map almost one-to-one to ZCode events—PermissionRequest is a native event; tool errors have no PostToolUseFailure, so they are conservatively determined from PostToolUse's tool_response; hooks are bundled by the plugin manifest (.codex-plugin/plugin.json), all running async in the background without blocking turns

Install: codex plugin marketplace add codex-plugin/目录 → codex plugin install bongocat-notify@bongocat-local → Trust each of the 5 hooks one by one in /hooks (Codex trust review mechanism—untrusted hooks don't run) → verify in a new session with codex mcp list (see codex-plugin/bongocat-notify/README.md for details).

Configuration (config.json, editable from the dashboard)

Read priority: environment variable BONGOCAT_* > config.json > defaults. On first use, copy config.example.json to config.json.

Corresponding environment variables: 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 (backward compatible with older versions).

Dashboard

Start with python dashboard.py (auto-opens the browser), includes:

• Status overview: current driver, capability matrix (green=supported / gray=not supported by that cat), cat status (model/mode/window), mver mirror thread, 2-second polling refresh

• Driver selection: auto / embedded / cdp / mver, switching saves and rebuilds the driver

• Config editing: visual editing of all config.json keys

• Tool playground: call all commands directly from the web page (expression dropdown, key presses, typing, bubbles, window show/hide, set-hand), with the latest 200 event log entries

The dashboard and astrbot's stdio server each hold independent driver instances and can be used in parallel; embedded / cdp have no conflicts, dual mver mirrors are a benign overlay (two paths with identical state frames), and the chat bubble may be rendered once by each of the two processes.

MCP Tools (14 tools, mapped to 12 unified commands, consistent across all drivers)

Capabilities are asset-aware: an mver skin only advertises expression/motion capabilities when the model directory actually contains the corresponding asset files; otherwise it honestly reports unsupported (to avoid treating stale leftover config as a real capability).

Security notes

• All channels bind only to the local loopback address; the embedded channel uses a random Bearer token on every startup

• cdp's WebView2 debug port (default 127.0.0.1:9223) is a local control surface; don't leave a cat running with the debug port open for long periods when not in use

• cdp takeover restarts a running cat once; only one cat is supported at a time

Project structure

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 protocol (empirically reverse-engineered notes)

• 312-byte full state frame, sent continuously at 60fps, no handshake

• bytes[0..255]: VK-indexed key states; 0x81=pressed (sent continuously for the entire hold duration), 0x80=release edge frame, 0x00=idle; VK 0x01/0x02 = mouse left/right buttons

• bytes[256..311]: 14 floats, fl[8]=0.8×cursor x/screen width, fl[9]=0.8×cursor y/screen height

• Constant slots 0x90/0xF0/0xF3/0xF6/0xFB = 0x01

• Combo key bindings require timed pressing (hold the modifier first for ≥0.3s, then press the trigger key)

• mode: 1=standard, 2=keyboard, 3=gamepad (from BongoCatMverUI source code)