Roku Development MCP Server (roku-dev-mcp)

Un servidor autónomo de Protocolo de Contexto de Modelo (MCP) que permite a los agentes de codificación de IA (como Antigravity, Claude y Cursor) desarrollar, implementar, navegar, inspeccionar y depurar aplicaciones Roku BrightScript y SceneGraph.

1. Resumen

Roku OS separa las API de desarrollo en cuatro protocolos de red distintos en cuatro puertos diferentes. roku-dev-mcp actúa como un controlador de middleware que conecta la interfaz estructurada de llamadas a herramientas JSON del agente con la superficie fragmentada de API de desarrollador de Roku.

┌──────────────────────────────────────────────────────────────────┐
│                        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. Matriz de Arquitectura de Puertos

*Requiere "Control por aplicaciones móviles" habilitado en Roku OS 14.1+.

3. Requisitos previos

3.1 Configuración del dispositivo Roku

1. Modo desarrollador habilitado:

   • Secuencia remota: Home ×3 → Up ×2 → Right → Left → Right → Left → Right.

   • Establezca una contraseña de desarrollador (usada como ROKU_DEV_PASSWORD).

2. "Control por aplicaciones móviles" habilitado:

   • Settings → System → Advanced system settings → Control by mobile apps → seleccione "Enabled".

3. Conectividad de red local:

   • Asegúrese de que la máquina host que ejecuta el servidor MCP esté en la misma subred que el dispositivo Roku.

   • Los puertos 80, 8060, 8080 y 8085 deben ser accesibles.

3.2 Entorno del host

• Node.js: ≥ 20.0.0 (LTS recomendado)

• npm o pnpm

4. Configuración y variables de entorno

Cree un archivo .env en la raíz del proyecto o configure las variables de entorno en su cliente MCP:

5. Configuración del cliente MCP

5.1 Configuración de Antigravity / Claude Desktop

Agregue el servidor a la configuración de su cliente MCP (por ejemplo, mcpServers en claude_desktop_config.json o la configuración MCP de Antigravity):

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

Para instrucciones de configuración detalladas para Antigravity, Claude CLI / Claude Desktop, Codex y Opencode, consulte docs/INSTALL.md.

6. Herramientas MCP disponibles

1. roku_build_and_deploy

Comprime un directorio de proyecto BrightScript/SceneGraph y lo carga lateralmente en el dispositivo Roku.

• Entradas:

  • source_dir (string): Ruta absoluta a la raíz del proyecto (debe contener manifest).

  • action ("Install" | "Replace", predeterminado: "Install"): Install reemplaza cualquier aplicación cargada lateralmente existente.

  • exclude_patterns (string[], opcional): Patrones glob adicionales a excluir.

• Devuelve: Resultado de la implementación, registros de inicio, duración de la instalación y estado de fallos.

2. roku_send_keys

Envía comandos de pulsación de teclas ECP secuenciales con retrasos configurables entre teclas.

• Entradas:

  • keys (string[]): Lista ordenada de teclas ECP (p. ej., ["Home", "Down", "Select", "Lit_a"]).

  • delay_ms (number, opcional): Retraso entre pulsaciones de teclas en milisegundos.

• Devuelve: Cantidad de teclas enviadas, duración de la ejecución y errores si los hay.

3. roku_get_ui_tree

Inspecciona y analiza el árbol de nodos SceneGraph en vivo en una estructura de árbol JSON.

• Entradas:

  • filter_id (string, opcional): ID del nodo raíz del subárbol.

  • include_fields (boolean, predeterminado: true): Incluir valores de campos de nodo.

  • max_depth (number, opcional): Profundidad máxima del árbol.

• Devuelve: Árbol de nodos analizado con recuentos de referencias y datos de campos.

4. roku_capture_state

Produce una instantánea multimodal compuesta del estado del dispositivo.

• Entradas:

  • log_lines (number, predeterminado: 50): Entradas recientes del registro BrightScript.

  • include_screenshot (boolean, predeterminado: true): Imagen de captura de pantalla en Base64.

  • include_ui_tree (boolean, predeterminado: false): Instantánea del árbol SceneGraph.

• Devuelve: Estado JSON compuesto más carga útil de imagen en línea para agentes multimodales.

5. roku_assert_playback

Consulta el reproductor de medios ECP para verificar el estado y las métricas de reproducción de video.

• Entradas: Ninguna.

• Devuelve: is_playing, is_buffering, progress_percent, duración, tasa de bits de transmisión y formatos de audio/video.

6. roku_wait_for_condition

Sondeo determinista basado en condiciones para evitar temporizadores de espera fijos.

• Entradas:

  • condition (string): Expresión de condición (node_exists: {id}, node_field: {id}.{field}={val}, playback_state: {state}, app_active: {id}, log_contains: {pattern}, crash_detected).

  • timeout_seconds (number, predeterminado: 10): Duración máxima de espera.

  • poll_interval_ms (number, predeterminado: 500): Intervalo de sondeo.

• Devuelve: Indicador de satisfacción, tiempo transcurrido, recuento de sondeos e instantánea coincidente.

7. roku_launch

Enlaza profundamente a elementos de contenido específicos dentro de la aplicación cargada lateralmente.

• Entradas:

  • content_id (string, opcional): ID de contenido objetivo.

  • media_type (string, opcional): Sugerencia de tipo de medio (movie, series, etc.).

  • params (Record<string, string>, opcional): Parámetros de consulta adicionales.

• Devuelve: Confirmación de lanzamiento y verificación de la aplicación activa.

7. Desarrollo y pruebas

# 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

Para documentación completa de pruebas e instrucciones de verificación paso a paso, consulte docs/TESTING.md.

8. Licencia

Este proyecto está licenciado bajo la Unlicense — dominio público.