内容
# 🎮 Roku MCP 服务器
[中文](#中文)
---
## 中文
Roku 设备开发、测试和认证的 **MCP（模型上下文协议）服务器**。
使 AI 代理（如 Gemini、Claude、Copilot 等）可以直接控制和测试 Roku 设备。
### ✨ 主要功能
- 📦 **应用部署** — 侧载部署和截图
- 🖥️ **分辨率验证** — 自动检查 HD/FHD 兼容性
- ⌨️ **遥控器控制** — 键入、序列、文本输入
- 📱 **应用管理** — 安装的应用查询、运行、深链接测试
- 📋 **日志收集** — BrightScript 控制台实时日志
- 🔍 **SceneGraph 检查** — 节点树、内存、焦点元素
- 🎥 **流媒体监测** — 播放状态、缓冲、带宽
- 🛡️ **认证验证** — DRM、辅助功能（音频指南/字幕）、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` | 图形帧率 |
| | `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 # 开发者模式密码
ROKU_PROJECT_ROOT= # 项目根目录（默认：上级目录）
ROKU_APP_SERVER_URL= # 应用服务器 URL（可选）
```
> ⚠️ Roku 开发者模式必须在目标设备上启用。
### 🔌 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`
### 🏗️ 架构
```
roku-mcp/
├── src/
│ ├── index.ts # MCP 服务器入口（25 个工具 + 2 个资源）
│ ├── roku-client.ts # ECP + Dev Web 服务器客户端
│ ├── log-client.ts # BrightScript 控制台（Telnet :8085）
│ ├── webdriver-client.ts # Roku WebDriver（端口 9000）
│ └── test-runner.ts # 集成测试编排器
├── dist/ # 编译输出
├── package.json
├── tsconfig.json
└── .env.example
```
### 📡 使用的 Roku API
| API | 端口 | 目的 |
|-----|------|---------|
| ECP（外部控制协议） | 8060 | 设备控制、查询、键入 |
| 开发者 Web 服务器 | 80 | 应用侧载、截图 |
| BrightScript 控制台 | 8085 | 运行时日志、调试 |
| SceneGraph 调试 | 8080 | SG 特定调试 |
| WebDriver | 9000 | UI 元素自动化 |
### 📝 自文档
每个工具在其描述中都包含内联 Roku API 文档 — API 端点、端口、参数、预期响应和官方文档链接。AI 代理可以使用这些工具而无需查阅外部文档。
---
## 许可证
MIT
