Roku Development MCP Server (roku-dev-mcp)

AI 코딩 에이전트(예: Antigravity, Claude, Cursor)가 Roku BrightScript 및 SceneGraph 애플리케이션을 개발, 배포, 탐색, 검사, 디버깅할 수 있게 해주는 자율적인 Model Context Protocol (MCP) 서버입니다.

1. 개요

Roku OS는 개발 API를 서로 다른 4개의 네트워크 프로토콜과 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+에서 "Control by mobile apps"가 활성화되어 있어야 합니다.

3. 사전 요구 사항

3.1 Roku 기기 구성

1. 개발자 모드 활성화:

   • 리모컨 시퀀스: Home ×3 → Up ×2 → Right → Left → Right → Left → Right.

   • 개발자 비밀번호 설정 (ROKU_DEV_PASSWORD로 사용).

2. "Control by mobile apps" 활성화:

   • 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 클라이언트 구성에 서버를 추가하세요 (예: 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 프로젝트 디렉터리를 압축하고 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

하드코딩된 sleep 타이머를 피하기 위한 결정적 조건 기반 폴링.

• 입력:

  • 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 — 퍼블릭 도메인으로 라이선스가 부여됩니다.