🎮 Roku MCP Server

한국어 | English

---

한국어

Roku 기기 개발, 테스트, 인증을 위한 MCP (Model Context Protocol) 서버입니다.
AI 에이전트(Gemini, Claude, Copilot 등)가 Roku 기기를 직접 제어하고 테스트할 수 있게 합니다.

✨ 주요 기능

• 📦 앱 배포 — 사이드로드 배포 및 스크린샷 캡처
• 🖥️ 해상도 검증 — HD/FHD 호환성 자동 확인
• ⌨️ 리모컨 제어 — 키 입력, 시퀀스, 텍스트 입력
• 📱 앱 관리 — 설치된 앱 조회, 실행, 딥링크 테스트
• 📋 로그 수집 — BrightScript 콘솔 실시간 로그
• 🔍 SceneGraph 검사 — 노드 트리, 메모리, 포커스 요소
• 🎥 스트리밍 모니터링 — 재생 상태, 버퍼링, 대역폭
• 🛡️ 인증 검증 — DRM, 접근성(Audio Guide/자막), RAF 광고
• 🧪 통합 테스트 — 여러 동작을 시퀀스로 자동 실행

📋 도구 목록 (25개)

카테고리	도구	설명
배포	roku_deploy	앱 사이드로드 배포
	roku_screenshot	화면 캡처 (base64 이미지)
디스플레이	roku_device_info	기기 정보 (모델, 해상도, 펌웨어)
	roku_check_resolution	HD/FHD 해상도 호환성 검증
입력	roku_keypress	리모컨 키 입력
	roku_keypress_sequence	키 시퀀스 전송
	roku_input	커스텀 이벤트/딥링크 파라미터
앱 관리	roku_apps	설치된 앱 목록
	roku_active_app	현재 실행 중인 앱
	roku_launch	앱 실행/재시작
	roku_deep_link	딥링크 인증 테스트
	roku_registry	앱 레지스트리 데이터 조회
	roku_app_state	앱 라이프사이클 추적
로그	roku_log	BrightScript 콘솔 로그
SceneGraph	roku_sg_nodes	SG 노드 트리 검사
	roku_perf	CPU/메모리 사용량
	roku_graphics_fps	그래픽 FPS
	roku_element	UI 요소 검색 (WebDriver)
	roku_focused_element	포커스 요소 조회
스트리밍	roku_media_player	미디어 재생 상태
	roku_server_check	서버 헬스체크
인증	roku_check_drm	DRM 콘텐츠 보호 상태
	roku_check_accessibility	접근성 준수 검사
	roku_check_raf	RAF 광고 프레임워크 검증
테스트	roku_run_test	통합 테스트 실행

🛠️ 설치

git clone https://github.com/maskelog/roku-mcp.git
cd roku-mcp
npm install
npm run build

⚙️ 설정

.env.example을 .env로 복사한 후 설정:

ROKU_DEV_HOST=192.168.0.100     # Roku 기기 IP (설정 > 네트워크 > 정보)
ROKU_DEV_PASSWORD=your_password  # Developer Mode 비밀번호
ROKU_PROJECT_ROOT=               # 프로젝트 루트 (기본: 상위 디렉토리)
ROKU_APP_SERVER_URL=             # 앱 서버 URL (선택)

⚠️ Roku Developer Mode를 활성화해야 합니다.

🔌 MCP 클라이언트 연결

AI 에이전트의 MCP 설정에 추가:

{
  "mcpServers": {
    "roku-dev": {
      "command": "node",
      "args": ["/path/to/roku-mcp/dist/index.js"],
      "env": {
        "ROKU_DEV_HOST": "192.168.0.100",
        "ROKU_DEV_PASSWORD": "your_password"
      }
    }
  }
}

💡 사용 예시

AI 에이전트에게 자연어로 요청:

• "Roku 기기 정보 알려줘" → roku_device_info
• "앱 배포하고 스크린샷 찍어줘" → roku_deploy → roku_screenshot
• "광고 설정 어떤지 확인해" → roku_check_raf
• "HD/FHD 해상도 호환 되는지 봐줘" → roku_check_resolution
• "통합 테스트 돌려줘" → roku_run_test

---

English

MCP (Model Context Protocol) server for Roku device development, testing, and certification.
Enables AI agents (Gemini, Claude, Copilot, etc.) to directly control and test Roku devices.

✨ Features

• 📦 App Deployment — Sideload apps and capture screenshots
• 🖥️ Resolution Verification — Auto-check HD/FHD compatibility
• ⌨️ Remote Control — Key presses, sequences, text input
• 📱 App Management — List apps, launch, deep link testing
• 📋 Log Collection — Real-time BrightScript console logs
• 🔍 SceneGraph Inspection — Node tree, memory, focused elements
• 🎥 Streaming Monitoring — Playback state, buffering, bandwidth
• 🛡️ Certification Checks — DRM, accessibility (Audio Guide/Captions), RAF ads
• 🧪 Integration Testing — Automated multi-step test sequences

📋 Tools (25)

Category	Tool	Description
Deploy	roku_deploy	Sideload app to device
	roku_screenshot	Capture screen (base64 image)
Display	roku_device_info	Device info (model, resolution, firmware)
	roku_check_resolution	Verify HD/FHD resolution support
Input	roku_keypress	Send remote key press
	roku_keypress_sequence	Send key sequence
	roku_input	Custom events / deep link params
App	roku_apps	List installed apps
	roku_active_app	Currently running app
	roku_launch	Launch / restart app
	roku_deep_link	Test deep linking (certification req.)
	roku_registry	Read app registry data
	roku_app_state	Track app lifecycle
Logging	roku_log	BrightScript console logs
SceneGraph	roku_sg_nodes	Inspect SG node tree
	roku_perf	CPU / memory usage
	roku_graphics_fps	Graphics frame rate
	roku_element	Find UI element (WebDriver)
	roku_focused_element	Get focused element
Streaming	roku_media_player	Media playback state
	roku_server_check	Server health check
Certification	roku_check_drm	DRM content protection status
	roku_check_accessibility	Accessibility compliance
	roku_check_raf	RAF ad framework verification
Testing	roku_run_test	Run integration test sequence

🛠️ Installation

git clone https://github.com/maskelog/roku-mcp.git
cd roku-mcp
npm install
npm run build

⚙️ Configuration

Copy .env.example to .env and configure:

ROKU_DEV_HOST=192.168.0.100     # Roku device IP (Settings > Network > About)
ROKU_DEV_PASSWORD=your_password  # Developer Mode password
ROKU_PROJECT_ROOT=               # Project root (default: parent directory)
ROKU_APP_SERVER_URL=             # App server URL (optional)

⚠️ Roku Developer Mode must be enabled on the target device.

🔌 MCP Client Setup

Add to your AI agent's MCP configuration:

{
  "mcpServers": {
    "roku-dev": {
      "command": "node",
      "args": ["/path/to/roku-mcp/dist/index.js"],
      "env": {
        "ROKU_DEV_HOST": "192.168.0.100",
        "ROKU_DEV_PASSWORD": "your_password"
      }
    }
  }
}

💡 Usage Examples

Ask your AI agent in natural language:

• "Show me the Roku device info" → roku_device_info
• "Deploy the app and take a screenshot" → roku_deploy → roku_screenshot
• "Check if the ad framework is set up correctly" → roku_check_raf
• "Verify HD/FHD resolution support" → roku_check_resolution
• "Run a full integration test" → roku_run_test

🏗️ Architecture

roku-mcp/
├── src/
│   ├── index.ts              # MCP server entry (25 tools + 2 resources)
│   ├── roku-client.ts        # ECP + Dev Web Server client
│   ├── log-client.ts         # BrightScript console (Telnet :8085)
│   ├── webdriver-client.ts   # Roku WebDriver (port 9000)
│   └── test-runner.ts        # Integration test orchestrator
├── dist/                     # Compiled output
├── package.json
├── tsconfig.json
└── .env.example

📡 Roku APIs Used

API	Port	Purpose
ECP (External Control Protocol)	8060	Device control, queries, key presses
Developer Web Server	80	App sideloading, screenshots
BrightScript Console	8085	Runtime logs, debugging
SceneGraph Debug	8080	SG-specific debugging
WebDriver	9000	UI element automation

📝 Self-Documenting

Every tool includes inline Roku API documentation in its description — API endpoints, ports, parameters, expected responses, and links to official docs. AI agents can use the tools without consulting external documentation.

---

License

MIT