Roku Development MCP Server (roku-dev-mcp)

Ein autonomer Model Context Protocol (MCP)-Server, der KI-Codierungsagenten (wie Antigravity, Claude und Cursor) befähigt, Roku BrightScript- und SceneGraph-Anwendungen zu entwickeln, bereitzustellen, zu navigieren, zu inspizieren und zu debuggen.

1. Übersicht

Roku OS trennt die Entwicklungs-APIs über vier verschiedene Netzwerkprotokolle auf vier verschiedenen Ports. roku-dev-mcp fungiert als Middleware-Controller, der die strukturierte JSON-Tool-Call-Schnittstelle des Agenten mit der fragmentierten Entwickler-API-Oberfläche von Roku verbindet.

┌──────────────────────────────────────────────────────────────────┐
│                        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. Port-Architektur-Matrix

*Erfordert, dass „Control by mobile apps“ in Roku OS 14.1+ aktiviert ist.

3. Voraussetzungen

3.1 Roku-Gerätekonfiguration

1. Entwicklermodus aktiviert:

   • Fernbedienungssequenz: Home ×3 → Up ×2 → Right → Left → Right → Left → Right.

   • Legen Sie ein Entwicklerpasswort fest (wird als ROKU_DEV_PASSWORD verwendet).

2. „Control by mobile apps“ aktiviert:

   • Einstellungen → System → Erweiterte Systemeinstellungen → Steuerung durch mobile Apps → wählen Sie „Aktiviert“.

3. Lokale Netzwerkverbindung:

   • Stellen Sie sicher, dass der Host, auf dem der MCP-Server läuft, sich im selben Subnetz wie das Roku-Gerät befindet.

   • Die Ports 80, 8060, 8080 und 8085 müssen erreichbar sein.

3.2 Host-Umgebung

• Node.js: ≥ 20.0.0 (LTS empfohlen)

• npm oder pnpm

4. Konfiguration & Umgebungsvariablen

Erstellen Sie eine .env-Datei im Projektstamm oder konfigurieren Sie Umgebungsvariablen in Ihrem MCP-Client:

5. MCP-Client-Einrichtung

5.1 Antigravity / Claude Desktop-Konfiguration

Fügen Sie den Server zu Ihrer MCP-Client-Konfiguration hinzu (z. B. mcpServers in claude_desktop_config.json oder Antigravity-MCP-Einstellungen):

{
  "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"
      }
    }
  }
}

Detaillierte Konfigurationsanweisungen für Antigravity, Claude CLI / Claude Desktop, Codex und Opencode finden Sie in docs/INSTALL.md.

6. Verfügbare MCP-Tools

1. roku_build_and_deploy

Zippt ein BrightScript/SceneGraph-Projektverzeichnis und lädt es auf das Roku-Gerät (Sideloading).

• Eingaben:

  • source_dir (string): Absoluter Pfad zum Projektstamm (muss manifest enthalten).

  • action ("Install" | "Replace", Standard: "Install"): Installieren ersetzt eine vorhandene Sideload-App.

  • exclude_patterns (string[], optional): Zusätzliche Glob-Muster zum Ausschließen.

• Rückgabe: Bereitstellungsergebnis, Startprotokolle, Installationsdauer und Absturzstatus.

2. roku_send_keys

Sendet sequenzielle ECP-Tastendruckbefehle mit konfigurierbaren Verzögerungen zwischen den Tasten.

• Eingaben:

  • keys (string[]): Geordnete Liste von ECP-Tasten (z. B. ["Home", "Down", "Select", "Lit_a"]).

  • delay_ms (number, optional): Verzögerung zwischen Tastendrücken in Millisekunden.

• Rückgabe: Anzahl gesendeter Tasten, Ausführungsdauer und ggf. Fehler.

3. roku_get_ui_tree

Inspiziert und analysiert den Live-SceneGraph-Knotenbaum in eine JSON-Baumstruktur.

• Eingaben:

  • filter_id (string, optional): Knoten-ID der Teilbaumwurzel.

  • include_fields (boolean, Standard: true): Knotenfeld-Schlüssel-Werte einbeziehen.

  • max_depth (number, optional): Maximale Baumtiefe.

• Rückgabe: Analysierter Knotenbaum mit Referenzzählern und Felddaten.

4. roku_capture_state

Erstellt eine zusammengesetzte multimodale Momentaufnahme des Gerätezustands.

• Eingaben:

  • log_lines (number, Standard: 50): Letzte BrightScript-Protokolleinträge.

  • include_screenshot (boolean, Standard: true): Base64-Screenshot-Bild.

  • include_ui_tree (boolean, Standard: false): SceneGraph-Baum-Momentaufnahme.

• Rückgabe: Zusammengesetzter JSON-Zustand plus Inline-Bild-Payload für multimodale Agenten.

5. roku_assert_playback

Fragt den ECP-Mediaplayer ab, um den Videowiedergabestatus und Metriken zu überprüfen.

• Eingaben: Keine.

• Rückgabe: is_playing, is_buffering, progress_percent, Dauer, Stream-Bitrate sowie Audio-/Videoformate.

6. roku_wait_for_condition

Deterministisches, bedingungsbasiertes Polling, um fest codierte Schlaf-Timer zu vermeiden.

• Eingaben:

  • condition (string): Bedingungsausdruck (node_exists: {id}, node_field: {id}.{field}={val}, playback_state: {state}, app_active: {id}, log_contains: {pattern}, crash_detected).

  • timeout_seconds (number, Standard: 10): Maximale Wartedauer.

  • poll_interval_ms (number, Standard: 500): Abfrageintervall.

• Rückgabe: Erfüllungsflag, verstrichene Zeit, Anzahl der Abfragen und passende Momentaufnahme.

7. roku_launch

Stellt Deep-Links zu bestimmten Inhaltselementen in der sideloadeten Anwendung her.

• Eingaben:

  • content_id (string, optional): Ziel-Inhalts-ID.

  • media_type (string, optional): Medientyp-Hinweis (movie, series, usw.).

  • params (Record<string, string>, optional): Zusätzliche Abfrageparameter.

• Rückgabe: Startbestätigung und Überprüfung der aktiven App.

7. Entwicklung & Testen

# 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

Die vollständige Testdokumentation und Schritt-für-Schritt-Verifizierungsanweisungen finden Sie in docs/TESTING.md.

8. Lizenz

Dieses Projekt ist unter der Unlicense lizenziert — Public Domain.