Roku MCP Server

# 🎮 Roku MCP Server [한국어](#한국어) | [English](#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` | 통합 테스트 실행 | ### 🛠️ 설치 ```bash git clone https://github.com/maskelog/roku-mcp.git cd roku-mcp npm install npm run build ``` ### ⚙️ 설정 `.env.example`을 `.env`로 복사한 후 설정: ```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 설정에 추가: ```json { "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 ```bash 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: ```env 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: ```json { "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