Roku Development MCP Server (roku-dev-mcp)

AIコーディングエージェント（Antigravity、Claude、Cursorなど）がRoku BrightScriptおよびSceneGraphアプリケーションの開発、デプロイ、ナビゲーション、検査、デバッグを実行できるようにする自律型Model Context Protocol（MCP）サーバーです。

1. 概要

Roku OSは開発用APIを4つの異なるネットワークプロトコルに分離し、それぞれ異なるポートで提供しています。roku-dev-mcpは、エージェントの構造化されたJSONツールコールインターフェースと、Rokuの断片的な開発者APIサーフェスを橋渡しするミドルウェアコントローラーとして機能します。

┌──────────────────────────────────────────────────────────────────┐
│                        MCP Client (Agent)                        │
│                  (Antigravity / Claude / etc.)                    │
└──────────────────────────┬───────────────────────────────────────┘
                           │  MCP Protocol (stdio)
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│                     roku-dev-mcp Server                          │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │  Tool Router  │  │  Log Buffer  │  │  Connection Manager    │  │
│  │  (Zod Schemas│  │  (Ring Buffer │  │  (Mutex, Reconnect,   │  │
│  │   & Handlers)│  │   & Crash Det)│  │   Timeouts)           │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬─────────────────┘  │
│         │                 │                  │                    │
│  ┌──────┴─────────────────┴──────────────────┴─────────────────┐ │
│  │                   Roku Interface Adapters                    │ │
│  │  ┌─────────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐  │ │
│  │  │ Port 80     │ │ Port     │ │ Port     │ │ Port 8085   │  │ │
│  │  │ Installer   │ │ 8060 ECP │ │ 8080 SG  │ │ BS Console  │  │ │
│  │  │ (HTTP/      │ │ (HTTP    │ │ Debug    │ │ (Telnet /   │  │ │
│  │  │  Digest)    │ │  REST)   │ │ (Telnet) │ │  Persistent)│  │ │
│  │  └──────┬──────┘ └────┬─────┘ └────┬─────┘ └──────┬──────┘  │ │
│  └─────────┼─────────────┼────────────┼──────────────┼──────────┘ │
└────────────┼─────────────┼────────────┼──────────────┼────────────┘
             │             │            │              │
             ▼             ▼            ▼              ▼
┌──────────────────────────────────────────────────────────────────┐
│                      Roku Device (TV / Stick)                    │
│   :80 Installer   :8060 ECP   :8080 SG Debug   :8085 BS Debug   │
└──────────────────────────────────────────────────────────────────┘

Related MCP server: roku-mcp

2. ポートアーキテクチャマトリクス

*Roku OS 14.1以降で「モバイルアプリによる制御」を有効にする必要があります。

3. 前提条件

3.1 Rokuデバイスの設定

1. 開発者モードを有効にする：

   • リモコン操作：ホーム ×3 → 上 ×2 → 右 → 左 → 右 → 左 → 右。

   • 開発者パスワードを設定します（ROKU_DEV_PASSWORDとして使用）。

2. 「モバイルアプリによる制御」を有効にする：

   • 設定 → システム → 詳細システム設定 → モバイルアプリによる制御 → **「有効」**を選択。

3. ローカルネットワーク接続：

   • MCPサーバーを実行しているホストマシンがRokuデバイスと同じサブネットにあることを確認します。

   • ポート80、8060、8080、8085にアクセスできる必要があります。

3.2 ホスト環境

• Node.js：≥ 20.0.0（LTS推奨）

• npmまたはpnpm

4. 設定と環境変数

プロジェクトルートに.envファイルを作成するか、MCPクライアントで環境変数を設定します：

5. MCPクライアントのセットアップ

5.1 Antigravity / Claude Desktopの設定

MCPクライアント設定にサーバーを追加します（例：claude_desktop_config.jsonのmcpServers、またはAntigravityのMCP設定）：

{
  "mcpServers": {
    "roku-dev": {
      "command": "node",
      "args": ["/absolute/path/to/roku-dev-mcp/dist/index.js"],
      "env": {
        "ROKU_DEV_PASSWORD": "your_roku_dev_password",
        "ROKU_DEVICE_IP": "192.168.1.50"
      }
    }
  }
}

Antigravity、Claude CLI / Claude Desktop、Codex、Opencodeの詳細な設定手順については、docs/INSTALL.mdを参照してください。

6. 利用可能なMCPツール

1. roku_build_and_deploy

BrightScript/SceneGraphプロジェクトディレクトリをZIP圧縮し、Rokuデバイスにサイドロードします。

• 入力：

  • source_dir（string）：プロジェクトルートへの絶対パス（manifestを含む必要があります）。

  • action（"Install" | "Replace"、デフォルト："Install"）：Installは既存のサイドロードアプリを置き換えます。

  • exclude_patterns（string[]、オプション）：除外する追加のグロブパターン。

• 戻り値：デプロイ結果、起動ログ、インストール時間、クラッシュステータス。

2. roku_send_keys

設定可能なキー間遅延で、連続的なECPキー操作コマンドを送信します。

• 入力：

  • keys（string[]）：順序付きECPキーリスト（例：["Home", "Down", "Select", "Lit_a"]）。

  • delay_ms（number、オプション）：キー操作間の遅延（ミリ秒）。

• 戻り値：送信されたキー数、実行時間、エラー（存在する場合）。

3. roku_get_ui_tree

ライブのSceneGraphノードツリーを検査し、JSONツリー構造に解析します。

• 入力：

  • filter_id（string、オプション）：サブツリールートのノードID。

  • include_fields（boolean、デフォルト：true）：ノードフィールドのキーと値を含めるかどうか。

  • max_depth（number、オプション）：最大ツリー深度。

• 戻り値：参照カウントとフィールドデータを含む解析済みノードツリー。

4. roku_capture_state

デバイス状態の複合マルチモーダルスナップショットを生成します。

• 入力：

  • log_lines（number、デフォルト：50）：最近のBrightScriptログエントリ。

  • include_screenshot（boolean、デフォルト：true）：Base64スクリーンショット画像。

  • include_ui_tree（boolean、デフォルト：false）：SceneGraphツリースナップショット。

• 戻り値：複合JSON状態と、マルチモーダルエージェント用のインライン画像ペイロード。

5. roku_assert_playback

ECPメディアプレーヤーにクエリを実行し、ビデオ再生状態とメトリクスを検証します。

• 入力：なし。

• 戻り値：is_playing、is_buffering、progress_percent、再生時間、ストリームビットレート、オーディオ/ビデオ形式。

6. roku_wait_for_condition

ハードコードされたスリープタイマーを避けるための、決定的な条件ベースのポーリング。

• 入力：

  • condition（string）：条件式（node_exists: {id}、node_field: {id}.{field}={val}、playback_state: {state}、app_active: {id}、log_contains: {pattern}、crash_detected）。

  • timeout_seconds（number、デフォルト：10）：最大待機時間。

  • poll_interval_ms（number、デフォルト：500）：ポーリング間隔。

• 戻り値：条件充足フラグ、経過時間、ポーリング回数、一致したスナップショット。

7. roku_launch

サイドロードされたアプリケーション内の特定のコンテンツアイテムにディープリンクします。

• 入力：

  • content_id（string、オプション）：ターゲットコンテンツID。

  • media_type（string、オプション）：メディアタイプのヒント（movie、seriesなど）。

  • params（Record<string, string>、オプション）：追加のクエリパラメータ。

• 戻り値：起動確認とアクティブアプリの検証。

7. 開発とテスト

# Install dependencies
npm install

# Run unit tests (uses built-in MockRokuDevice)
npm test

# Run unit tests specifically
npm run test:unit

# Run integration tests against a real Roku TV
npm run test:integration

# Run all tests (unit + integration)
ROKU_INTEGRATION_TEST=1 npm test

# Run build
npm run build

完全なテストドキュメントとステップバイステップの検証手順については、docs/TESTING.mdを参照してください。

8. ライセンス

このプロジェクトはUnlicenseの下でライセンスされています — パブリックドメインです。