bongocat-mcp

Controlador independiente que unifica varios «gatos BongoCat» como herramientas MCP —totalmente desacoplado del repositorio de BongoCat, para que clientes MCP / LLM como astrbot puedan controlar activamente las animaciones de teclas / escritura / expresiones / burbujas de chat del gato, sin necesidad de recompilar el gato. Incluye un panel web local para ver el estado y editar la configuración.

Documento de diseño completo: requisitos docs/requirements.md · documento de implementación de arquitectura docs/architecture.md.

Compatible con tres tipos de gato (detección automática, también se puede forzar por configuración)

Coste del modo recepción de mver y capa de espejo: cuando Mver activa la recepción de red, ignora el teclado/ratón local y solo renderiza los paquetes de red. El hilo de envío del driver mver lee el teclado/ratón reales a 60fps (GetAsyncKeyState/GetCursorPos) y los reenvía, el comportamiento del gato es idéntico al modo local (retraso de aproximadamente un frame); las instrucciones de IA se superponen como capa de cobertura. Si el proceso MCP/espejo se detiene, el gato pierde la respuesta a teclado/ratón (se recupera al volver a ejecutarlo); solo puede haber una instancia de Mver a la vez.

Related MCP server: Vox MCP

Integración automática de nuevos gatos (mver)

• Reconocimiento automático: la encuesta de estado del panel detecta cada 5 segundos los procesos Mver en ejecución; si el gato configurado no está en ejecución (o no está configurado) y hay otro en ejecución, cambia automáticamente mver_dir al gato en ejecución y reconstruye el driver (el registro de eventos muestra el cambio)

• Integración con un clic: el botón «🚀 Integrar nuevo gato Mver con un clic» del panel hace todo automáticamente: localiza el gato en ejecución → reescribe su config.json a nivel de texto para activar la sincronización de red (modo recepción, conservando los comentarios del autor; escribe en el mismo archivo que la interfaz de configuración propia del gato, sin modificar el programa en sí) → reinicia el proceso del gato con privilegios elevados → reconstruye el driver

• Las versiones de skins Mver recién instaladas tienen network:false por defecto (no escuchan UDP); la integración con un clic lo soluciona; también se puede activar manualmente la sincronización de red en la configuración del gato y configurarlo en modo recepción

• Nota: solo puede haber una instancia de Mver ocupando el puerto de recepción a la vez

Inicio rápido

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

Plugin ZCode (bongocat-notify)

El directorio zcode-plugin/ es un mercado de plugins local + plugin que permite a Zcode conectarse a este servidor MCP:

• Conexión MCP: .mcp.json registra server.py como servidor MCP stdio (nombres de herramientas mcp__bongo-cat__*), el agente puede controlar el gato directamente; el comando /bongo-test verifica toda la cadena

• Notificaciones de tareas: los hooks activan burbujas del gato + cambio de expresiones en eventos clave de Zcode: Stop (tarea completada → ojos de estrella), PermissionRequest (esperando aprobación → interrogación), PostToolUseFailure (error → llanto), SessionStart / UserPromptSubmit (inicio de trabajo)

• Las expresiones no usan índices fijos: cada vez lee en tiempo real la lista de expresiones de get_cat_status y las empareja por palabras clave del nombre, adaptándose automáticamente al cambiar de skin; los hooks usan la API HTTP del panel (python dashboard.py debe permanecer en ejecución), si el panel no está disponible se omiten silenciosamente, nunca bloquean la sesión

Instalación: Zcode → Configuración → Gestión de plugins → Descubrir → + añadir directorio de mercado local zcode-plugin/, instalar bongocat-notify (ver zcode-plugin/bongocat-notify/README.md).

¿Quieres desarrollar tu propio plugin de notificaciones del gato para ZCode / AstrBot u otros clientes? Selección de canales de conexión, plantilla de esqueleto de plugin, convenciones de extensibilidad de expresiones y metodología de verificación en Guía de desarrollo de integración docs/zcode-plugin-dev.md.

Plugin Claude Code (bongocat-notify)

claude-plugin/ es la versión Claude Code del mismo «mercado local + plugin» (funcionalmente equivalente a la versión ZCode):

• Conexión MCP: .mcp.json registra server.py como servidor MCP stdio (nombres de herramientas también mcp__bongo-cat__*), el comando /bongo-test verifica toda la cadena

• Notificaciones de tareas: el modelo de eventos difiere — Claude Code no tiene eventos PermissionRequest / PostToolUseFailure; la espera de aprobación se expresa mediante Notification (filtrado por palabras clave del mensaje para descartar avisos de inactividad), los errores de herramientas se determinan de forma conservadora mediante tool_response de PostToolUse

Instalación: claude plugin marketplace add claude-plugin/directorio → claude plugin install bongocat-notify@bongocat-local, tras reiniciar la sesión verificar con /mcp (ver claude-plugin/bongocat-notify/README.md).

Plugin Codex (bongocat-notify)

codex-plugin/ es la versión OpenAI Codex CLI del mismo plugin (funcionalmente equivalente a la versión ZCode):

• Conexión MCP: .mcp.json (formato de conexión directa nativa de Codex) registra server.py como servidor MCP stdio, la habilidad bongo-test (skills/*/SKILL.md, los prompts personalizados de Codex están obsoletos, las habilidades son el reemplazo oficial) verifica toda la cadena

• Notificaciones de tareas: los hooks de Codex se corresponden casi uno a uno con los eventos de ZCode — PermissionRequest es un evento nativo; los errores de herramientas no tienen PostToolUseFailure, se determinan de forma conservadora mediante tool_response de PostToolUse; los hooks se agrupan mediante el manifiesto del plugin (.codex-plugin/plugin.json), todos se ejecutan en segundo plano con async sin bloquear el turno

Instalación: codex plugin marketplace add codex-plugin/directorio → codex plugin install bongocat-notify@bongocat-local → en /hooks confiar uno a uno en estos 5 hooks (mecanismo de revisión de confianza de Codex, sin confianza no se ejecutan) → en una nueva sesión verificar con codex mcp list (ver codex-plugin/bongocat-notify/README.md).

Configuración (config.json, editable desde el panel)

Prioridad de lectura: variables de entorno BONGOCAT_* > config.json > valores por defecto. En el primer uso se puede copiar config.example.json como config.json.

Variables de entorno correspondientes: 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 (compatibles con versiones anteriores).

Panel

python dashboard.py para iniciar (abre el navegador automáticamente), incluye:

• Resumen de estado: driver actual, matriz de capacidades (verde=soporta / gris=ese gato no lo soporta), estado del gato (modelo/modo/ventana), hilo de espejo mver, actualización por encuesta cada 2 segundos

• Selección de driver: automático / embedded / cdp / mver, al cambiar se guarda y reconstruye el driver

• Edición de configuración: edición visual de todas las claves de config.json

• Zona de pruebas de herramientas: llamada directa de todos los comandos desde la web (desplegable de expresiones, teclas, escritura, burbujas, mostrar/ocultar ventana, set-hand), con registro de los últimos 200 eventos

El panel y el servidor stdio de astrbot mantienen instancias de driver independientes, se pueden usar en paralelo; embedded / cdp no tienen conflictos, el doble espejo de mver es una superposición benigna (dos flujos del mismo frame de estado), la burbuja de chat puede renderizarse una en cada proceso.

Herramientas MCP (14 herramientas, mapeadas a 12 comandos unificados, consistentes en todos los drivers)

Las capacidades son conscientes de los recursos: el skin mver solo anuncia la capacidad correspondiente si el directorio del modelo realmente contiene archivos de recursos de expresiones/movimientos; de lo contrario, informa honestamente que no lo soporta (para no tratar configuraciones heredadas inválidas como capacidades).

Notas de seguridad

• Todos los canales se vinculan solo a la dirección de bucle local; el canal embedded genera un token Bearer aleatorio en cada inicio

• El puerto de depuración WebView2 de cdp (por defecto 127.0.0.1:9223) es una superficie de control local; no dejes el gato con el puerto de depuración abierto durante mucho tiempo cuando no lo uses

• La toma de control de cdp reinicia una vez el gato en ejecución; solo se soporta un gato a la vez

Estructura del proyecto

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\                   # 需求/架构/接入文档；验证截图为本地存档不入库

Protocolo UDP de Mver (notas de ingeniería inversa empírica)

• Frame de estado completo de 312 bytes, envío continuo a 60fps, sin handshake

• bytes[0..255]: estado de teclas por índice VK; 0x81=pulsada (se envía continuamente durante todo el tiempo de pulsación), 0x80=frame de borde de liberación, 0x00=inactiva; VK 0x01/0x02 = botones izquierdo/derecho del ratón

• bytes[256..311]: 14 floats, fl[8]=0.8×cursor x/ancho de pantalla, fl[9]=0.8×cursor y/alto de pantalla

• Slots constantes 0x90/0xF0/0xF3/0xF6/0xFB = 0x01

• Los enlaces de combinaciones de teclas requieren pulsación secuencial (mantener la tecla modificadora pulsada ≥0.3s antes de pulsar la tecla de activación)

• mode: 1=estándar, 2=teclado, 3=mando (del código fuente de BongoCatMverUI)