🎮 Roku MCP Server

한국어 | English

한국어

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

✨ 주요 기능

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

📋 도구 목록 (25개)

🛠️ 설치

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)

🛠️ 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

📝 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