bongocat-mcp

Единый контроллер, который оборачивает различных «BongoCat-котиков» в MCP tools — полностью развязан с репозиторием BongoCat, позволяет MCP-клиентам/LLM (например, astrbot) активно управлять анимациями нажатий / печатью / выражениями / чат-пузырями котика, без перекомпиляции кота. В комплекте локальная веб-панель для просмотра состояния и редактирования конфигурации.

Полная документация по дизайну: требования docs/requirements.md · архитектура docs/architecture.md.

Поддерживаются три вида котиков (автоопределение, возможна принудительная настройка)

Цена режима приёма mver и зеркальный слой: после включения сетевого приёма Mver игнорирует локальные клавиатуру и мышь и рендерит только сетевые пакеты. Поток отправки драйвера mver с 60fps считывает реальные клавиатуру/мышь (GetAsyncKeyState/GetCursorPos) и пересылает, поведение кота совпадает с локальным режимом (задержка около одного кадра); AI-команды накладываются как оверлей. После остановки MCP/зеркального процесса кот перестаёт реагировать на клавиатуру и мышь (перезапуск восстанавливает); одновременно может работать только один экземпляр Mver.

Related MCP server: Vox MCP

Автоматическое подключение нового кота (mver)

• Автоопределение: панель состояния каждые 5 секунд опрашивает запущенные процессы Mver; если настроенный кот не запущен (или не настроен), а запущен другой, mver_dir автоматически переключается на работающего кота и driver пересоздаётся (в журнале событий видны записи переключения)

• Подключение в один клик: кнопка «🚀 Подключить нового Mver-кота в один клик» на панели выполняет всё автоматически — находит запущенного кота → на текстовом уровне переписывает его config.json, включая сетевую синхронизацию (режим приёма, сохраняя авторские комментарии; пишется тот же файл, что и через собственный интерфейс настроек кота, программа не изменяется) → перезапускает процесс кота с повышенными правами → пересоздаёт driver

• У свежеустановленных скиновых версий Mver по умолчанию network:false (UDP не слушается); подключение в один клик это исправляет; также можно вручную включить сетевую синхронизацию в настройках кота и выбрать режим приёма

• Примечание: одновременно только один экземпляр 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 выполняет сквозную самопроверку

• Оповещения о задачах: hooks на ключевых событиях Zcode запускают пузырь и смену выражения кота — Stop (задача выполнена → звёздные глаза), PermissionRequest (ожидание одобрения → вопрос), PostToolUseFailure (ошибка → плач), SessionStart / UserPromptSubmit (начало работы)

• Выражения не зашиты индексами: каждый раз список выражений из get_cat_status читается в реальном времени и сопоставляется по ключевым словам в названиях, при смене скина адаптируется автоматически; hook работает через 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 фильтруются уведомления о простое), ошибки инструментов консервативно определяются по tool_response из PostToolUse

Установка: 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, кастомные prompts в Codex устарели, навыки — официальная замена) выполняет сквозную самопроверку

• Оповещения о задачах: hooks Codex почти один в один соответствуют событиям ZCode — PermissionRequest является нативным событием; для ошибок инструментов нет PostToolUseFailure, они консервативно определяются по tool_response из PostToolUse; hooks поставляются вместе с манифестом плагина (.codex-plugin/plugin.json) и выполняются в фоне как async, не блокируя ход

Установка: codex plugin marketplace add codex-plugin/目录 → codex plugin install bongocat-notify@bongocat-local → последовательно выдайте Trust для этих 5 hook'ов (механизм проверки доверия 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 запускает панель (автоматически открывает браузер), включает:

• Обзор состояния: текущий driver, матрица возможностей (зелёный = поддерживается / серый = данный кот не поддерживает), состояние кота (модель/режим/окно), поток-зеркало mver, обновление по опросу каждые 2 секунды

• Выбор драйвера: автоматически / embedded / cdp / mver, переключение сохраняется и driver пересоздаётся

• Редактирование конфигурации: визуальное редактирование всех ключей config.json

• Площадка для опробования инструментов: вызов всех команд прямо на веб-странице (выпадающий список выражений, нажатия, печать, пузыри, показ/скрытие окна, set-hand), с журналом последних 200 событий

Панель и stdio-сервер astrbot имеют независимые экземпляры driver и могут использоваться параллельно; embedded / cdp не конфликтуют, двойное зеркало mver — безвредное наложение (два потока одинаковых кадров состояния), чат-пузырь может быть отрисован по одному в каждом процессе.

MCP Tools (14 инструментов, отображаются на 12 единых команд, одинаковы для всех driver)

Возможности — с учётом активов (asset-aware): скин mver объявляет соответствующую возможность, только если в каталоге модели действительно есть файлы ресурсов выражений/движений; в противном случае честно сообщает о неподдержке (чтобы не принимать недействительные устаревшие конфиги за возможности).

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

• Все каналы привязываются только к адресу локальной петли; канал embedded при каждом запуске получает случайный Bearer token

• WebView2-порт отладки cdp (по умолчанию 127.0.0.1:9223) — локальная управляющая поверхность; когда не нужен, не держите кота с открытым портом отладки надолго

• Перехват cdp перезапускает запущенного кота один раз; одновременно поддерживается только один кот

Структура проекта

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)