bongocat-mcp

다양한 「BongoCat 고양이」를 MCP tools로 통일해 캡슐화하는 독립 컨트롤러——BongoCat 저장소와 완전히 디커플링되어, astrbot 등의 MCP client / LLM이 고양이의 키 입력 애니메이션 / 타이핑 / 표정 / 채팅 버블을 능동적으로 제어할 수 있으며, 고양이를 다시 컴파일할 필요가 없습니다. 로컬 Web 대시보드가 포함되어 상태 확인과 설정 편집이 가능합니다.

전체 설계 문서: 요구사항서 docs/requirements.md · 아키텍처 구현서 docs/architecture.md.

세 가지 고양이 지원 (자동 탐지, 설정으로 강제 지정 가능)

mver 수신 모드의 대가와 미러 레이어: Mver가 네트워크 수신을 켜면 로컬 키보드/마우스를 무시하고 네트워크 패킷만 렌더링합니다. mver driver의 전송 스레드는 60fps로 실제 키보드/마우스를 읽어(GetAsyncKeyState/GetCursorPos) 포워딩하므로, 고양이의 동작은 로컬 모드와 동일합니다(약 1프레임 지연); 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 server에 연동되게 합니다:

• 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 키워드로 유휴 알림 필터링), 도구 오류는 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 hooks는 ZCode 이벤트와 거의 일대일 대응——PermissionRequest 는 네이티브 이벤트; 도구 오류에는 PostToolUseFailure가 없어 PostToolUse의 tool_response로 보수적으로 판단; hooks는 플러그인 매니페스트(.codex-plugin/plugin.json) 에 번들되며, 모두 async 백그라운드 실행으로 턴을 차단하지 않음

설치: codex plugin marketplace add codex-plugin/디렉터리 → codex plugin install bongocat-notify@bongocat-local → /hooks에서 5개 hook을 하나씩 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 실행(브라우저 자동 열림), 포함 내용:

• 상태 개요: 현재 driver, 기능 매트릭스(초록=지원 / 회색=해당 고양이 미지원), 고양이 상태(모델/모드/창), mver 미러 스레드, 2초 폴링 새로고침

• 드라이버 선택: 자동 / embedded / cdp / mver, 전환 즉시 저장 및 driver 재구축

• 설정 편집: config.json 전체 키를 시각적으로 편집

• 도구 체험대: 웹페이지에서 모든 명령 직접 호출(표정 드롭다운, 키 입력, 타이핑, 버블, 창 표시/숨김, set-hand), 최근 200개 이벤트 로그 포함

대시보드와 astrbot의 stdio server는 각각 독립 driver 인스턴스를 보유하며 병렬 사용 가능; embedded / cdp는 충돌 없음, mver 이중 미러는 양성 중첩(두 경로가 동일한 상태 프레임), 채팅 버블은 두 프로세스에서 각각 하나씩 렌더링될 수 있음.

MCP Tools (14개 도구, 12개 통합 명령에 매핑, 모든 driver 일관)

기능은 에셋 인지형입니다: mver 스킨은 모델 디렉터리에 표정/동작 에셋 파일이 실제로 존재할 때만 해당 기능을 advertise하고, 그렇지 않으면 정직하게 미지원을 보고합니다(유효하지 않은 잔여 설정을 기능으로 오인하지 않음).

보안 설명

• 모든 채널은 로컬 루프백 주소에만 바인딩; embedded 채널은 시작 시마다 랜덤 Bearer token

• cdp의 WebView2 디버그 포트(기본 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.3초 누른 후 트리거 키 누름)

• mode: 1=표준, 2=키보드, 3=게임패드(BongoCatMverUI 소스 코드에서 확인)