Roku Development MCP Server (roku-dev-mcp)

Автономный сервер Model Context Protocol (MCP), который предоставляет AI-агентам кодирования (таким как Antigravity, Claude и Cursor) возможность разрабатывать, развертывать, навигировать, инспектировать и отлаживать приложения Roku BrightScript и SceneGraph.

1. Обзор

Roku OS разделяет API разработки на четыре различных сетевых протокола на четырех разных портах. roku-dev-mcp действует как контроллер-посредник, который связывает структурированный интерфейс вызова инструментов JSON агента с фрагментированной поверхностью API разработчика 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. Матрица архитектуры портов

*Требуется включенная опция «Управление мобильными приложениями» в Roku OS 14.1+.

3. Предварительные требования

3.1 Конфигурация устройства Roku

1. Включен режим разработчика:

   • Последовательность на пульте: Home ×3 → Up ×2 → Right → Left → Right → Left → Right.

   • Установите пароль разработчика (используется как ROKU_DEV_PASSWORD).

2. Включена опция «Управление мобильными приложениями»:

   • Settings → System → Advanced system settings → Control by mobile apps → выберите "Enabled".

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-клиента (например, mcpServers в claude_desktop_config.json или настройки MCP в 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"
      }
    }
  }
}

Подробные инструкции по настройке для 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[], необязательно): Дополнительные glob-шаблоны для исключения.

• Возвращает: Результат развертывания, журналы запуска, длительность установки и статус сбоя.

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 — общественное достояние.