CyberBrick

cyberbrick-mcp

English | 简体中文

Chrome DevTools Protocol 経由で Bambu Lab CyberBrick デスクトップアプリ（Electron）を操作する MCP サーバーです。

デバイスのセットアップワークフロー全体を網羅しています：ハードウェア接続の計画 → ファームウェアの作成 → 書き込み。

ツール（41）

このサーバーは CyberBrick アプリの薄いパススルー層です。各ツールはアプリ独自の API（ストアアクション／デバイスメソッド）を呼び出し、即時に実行します。例外として、flash_mpy、flash_firmware、および hardwareMappings を指定した flash_config（先にファームウェアをアップグレードします）では confirm: true が必要です。これはユーザーが明示的に同意した後にのみ設定してください。デバイスへの書き込み操作では、target がデバイス 1 台だけに正確に一致しない場合、呼び出しは拒否されます。

読み取り専用／プローブ（readOnlyHint: true）

• インフラストラクチャ：cb_health、app_logs（アプリのコンソールログ。アップグレードやペアリングなど、時間のかかる処理の追跡に使用）
• デバイス：device_list、device_detail、board_info、device_status、device_config_get、device_config_block、device_config_read（全データの読み戻し＋MD5）、device_ble_state（ライブ GATT／connectionCount の状態）、device_pool_state、device_request
• 接続計画：connect_scan_ports
• 書き込み前の確認：flash_check（hardwareMappings を指定した書き込みでアップグレードされるファームウェア／MPY／ローダーを確認）
• ファームウェアの読み取り：firmware_config_get、firmware_edit_actions（全 60 アクションの意味に関するパラメーターのドキュメント）
• プロジェクトの読み取り：project_state（ページ認識＋段階的開示のための nextTools）、project_list、project_export

書き込み／フラッシュ（直接実行、状態を変更）

• 起動：cb_launch（アプリがデバッグポートなしで実行中の場合、kill_existing: true のときに限り終了します）
• 接続：connect_bluetooth、connect_serial、device_ble_heal（NaN の connectionCount を修復し、再起動せずに再接続できるようにします）
• ファームウェアの作成：firmware_config_set、firmware_config_edit、firmware_config_reset、firmware_config_load_template（組み込みテンプレートをエディターに読み込みます）
• フラッシュ：flash_config（デフォルトでは SET_DEVICE_CONFIG ファイルプロトコルを使用します。単一のレシーバーで動作し、新しいプロジェクトは作成しません）、flash_mpy（destructiveHint: true）、flash_firmware（destructiveHint: true）、flash_test
• プロジェクト管理：project_create（組み込みテンプレート 6 種）、project_import、project_rename、project_delete（destructiveHint: true）、project_load、project_save、project_open_editor
• ウィンドウ：window_list（読み取り専用）、window_close、window_close_others

検証スクリプト

• ユニットテスト（アプリやハードウェアは不要）：npm test
• リリースバージョンの確認：node scripts/check_release.mjs [vX.Y.Z]
• 読み取り専用パス：node scripts/verify_readonly.mjs
• サーバーとツールの登録：node scripts/mcp_list.mjs
• ローカルスモークテスト（アプリの実行が必要）：node scripts/smoke.js
• プロジェクト管理スモークテスト（作成 → 名前変更 → エクスポート → インポート → 読み込み → 保存 → 削除）：node scripts/smoke_project.mjs
• プロジェクト管理 MCP E2E：node scripts/mcp_e2e_project.mjs
• RC カーのエンドツーエンド例（送信機＋受信機のマッピング → 保存 → 読み戻しのアサーション → エクスポート。--flash を指定するとフラッシュと LED テストを追加）：node scripts/demo_rc_car.mjs
• 任意のツールを呼び出すアドホック実行：node scripts/mcp_call.mjs <tool> '<json>' [...]
• テンプレートデータの再抽出（アプリのアップグレード後）：python3 scripts/extract_templates.py

実行

Node.js 18 以降と、同じマシン上の CyberBrick デスクトップアプリが必要です。

npm からインストールする場合の MCP クライアント設定（JSON）：

{
  "command": "npx",
  "args": ["-y", "cyberbrick-mcp"]
}

ローカルのチェックアウトから実行する場合：

npm install
node src/server.js        # stdio MCP server

CDP ポート

デフォルトは 127.0.0.1:9223（一般的な 9222 は使用しません）です。CB_CDP_HOST／CB_CDP_PORT で上書きできます。cb_launch はデフォルトで /Applications/CyberBrick.app/Contents/MacOS/CyberBrick を起動します。CB_APP_BINARY で上書きできます。

安全上のルール

• 認証トークン、秘密鍵、AES キーを読み取ったりエクスポートしたりすることはありません（connection.js の sanitize がキー名に基づいてフィルタリングします）。
• 破壊的なツール（flash_mpy、flash_firmware）には destructiveHint が設定されており、confirm: true が必要です。エージェントはまずユーザーに影響（ボードへの書き込み／再起動／動作不能になる可能性）を説明し、同意を得る必要があります。
• device_request で許可されているのは読み取り専用メソッドのみです（読み取り専用許可リストにあるコマンドの isInLoader、getDeviceById、sendGetMessage）。
• cb_launch はデフォルトでは実行中のアプリを終了しません（未保存の作業が失われるため）。終了するには、明示的に kill_existing: true を指定する必要があります。
• 意図的に公開していない機能：BIND_DEVICE、SET_PRIVATE_KEY、証明書関連のフロー、PIN 関連のフロー（src/core/devices.js の ALLOWED_COMMANDS を参照）。

リリース

CI（.github/workflows/ci.yml）は、main へのプッシュおよびすべての PR で実行されます。Node 18/20/22/24 でのテスト、サーバーの起動チェック、バージョンチェック、npm pack --dry-run を行います。

vX.Y.Z タグをプッシュすると、.github/workflows/release.yml が実行されます。検証 → npm への公開（プロベナンス付き） → MCP Registry への server.json の公開 → CHANGELOG の該当セクションから GitHub Release を作成します。バージョンがすでに公開済みの場合、各ステップはスキップされるため、失敗した実行はそのまま再実行できます。

1. package.json／package-lock.json のバージョン（npm version X.Y.Z --no-git-tag-version）、server.json（2 つの version フィールド）および src/server.js のバージョンを更新します。
2. CHANGELOG.md に ## [X.Y.Z] - YYYY-MM-DD セクションを追加します。
3. node scripts/check_release.mjs vX.Y.Z を実行します。成功する必要があります。
4. コミットし、git tag vX.Y.Z && git push origin main vX.Y.Z を実行します。

サフィックス付きのタグ（v1.0.0-rc.1）は npm の next dist-tag で公開され、プレリリースとしてマークされます。

初回のみ必要な設定：

• npm：npmjs.com で、このパッケージに信頼済みパブリッシャーを追加します（GitHub Actions、ワークフロー release.yml、環境 release）。パッケージが存在するまでは信頼済みパブリッシングを設定できないため、最初のリリースに限り、手動で一度公開するか、NPM_TOKEN リポジトリシークレット（npm の自動化トークン）を追加してください。信頼済みパブリッシングが有効になったら、シークレットを削除します。
• MCP Registry：設定は不要です。ワークフローは GitHub OIDC でサインインします。これは、実行元リポジトリの io.github.<owner>/ 名前空間で有効です。

ライセンス

MIT