# 🎮 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