内容
# roku-mcp
一款适用于Roku设备自动化的[模型上下文协议](https://modelcontextprotocol.io/)(MCP)服务器。提供应用程序部署、ECP远程控制、截图捕获、SceneGraph节点检查和BrightScript调试控制台访问等工具。
## 安装
该服务器作为单个`npx`命令提供。您可以选择全局安装一次，也可以让MCP客户端通过`npx -y roku-mcp`按需启动。
```bash
npm install -g roku-mcp # 可选，全局安装
# 或直接指向：npx -y roku-mcp
```
配置您的AI客户端。下面每个平台都使用相同的启动行；只有配置文件和重新加载步骤会发生变化。
<details>
<summary><strong>Cursor</strong> — 代理模式工具，自动发现MCP服务器</summary>
**前提条件：** Cursor 0.45+，代理模式。
**安装：** 在项目根目录（或`~/.cursor/mcp.json`用于全局）创建`.cursor/mcp.json`：
```json
{
"mcpServers": {
"roku": {
"command": "npx",
"args": ["-y", "roku-mcp"],
"env": {
"ROKU_DEVICE_HOST": "192.168.1.XXX",
"ROKU_DEVICE_PASSWORD": "your-password"
}
}
}
}
```
然后重新加载窗口（`Cmd+Shift+P` / `Ctrl+Shift+P` → **Developer: Reload Window**）。
**验证：** 打开**Cursor Settings → MCP**，确认`roku`行显示绿色圆点。如果它显示为禁用，点击切换开关。在新的代理聊天中，输入`list roku tools` — 您应该看到`roku_deploy`、`roku_screenshot`等。
**路由规则（推荐）：** 仓库还提供了一个[`AGENTS.md`](./AGENTS.md)。Cursor会自动拾取它，因此代理知道规范的*观察 → 操作 → 等待 → 验证*循环和RTA `uiElementId`陷阱，而无需您每次会话都重新解释。
**故障排除：** 如果服务器保持灰色/禁用状态，请检查`View → Output → MCP Logs` — 最常见的原因是`ROKU_DEVICE_HOST`在LAN上无法访问。省略`env`块以回退到SSDP自动发现。
</details>
<details>
<summary><strong>VS Code (GitHub Copilot)</strong> — 代理模式，通过<code>.vscode/mcp.json</code>MCP</summary>
**前提条件：** VS Code 1.99+，带有GitHub Copilot扩展和活跃的Copilot订阅，包括代理模式。
**安装：** 在项目根目录创建`.vscode/mcp.json`：
```json
{
"servers": {
"roku": {
"command": "npx",
"args": ["-y", "roku-mcp"],
"env": {
"ROKU_DEVICE_HOST": "192.168.1.XXX",
"ROKU_DEVICE_PASSWORD": "your-password"
}
}
}
}
```
重新加载窗口（`Cmd+Shift+P` / `Ctrl+Shift+P` → **Developer: Reload Window**）。
**验证：** 打开Copilot Chat，将聊天模式下拉菜单切换到**Agent**，然后询问“你有哪些roku工具？”。您应该看到完整的`roku_*`列表。MCP面板（`Cmd+Shift+P` → **MCP: List Servers**）应显示`roku`为`Running`。
**故障排除：** 如果服务器无法启动，请在常规终端中运行`npx -y roku-mcp --help` — 这确认Node 18+和`npx`正在运行，然后VS Code启动它。
</details>
<details>
<summary><strong>Claude Desktop</strong> — 官方Anthropic桌面应用</summary>
**前提条件：** Claude Desktop（从claude.ai/download获取最新版本），`PATH`上的Node.js 18+。
**安装：** 编辑Claude Desktop配置：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"roku": {
"command": "npx",
"args": ["-y", "roku-mcp"],
"env": {
"ROKU_DEVICE_HOST": "192.168.1.XXX",
"ROKU_DEVICE_PASSWORD": "your-password"
}
}
}
}
```
完全退出并重新启动Claude Desktop（菜单栏图标必须关闭 — macOS上的`Cmd+Q`）。
**验证：** 打开新的聊天。对话框输入栏中的🛠️图标应列出`roku-mcp`及其所有工具。询问“拍摄Roku截图” — Claude将请求`roku_screenshot`的批准并运行它。
**故障排除：** 如果没有工具图标出现，请检查`~/Library/Logs/Claude/mcp-server-roku.log`（macOS） — `command not found: npx`表示Node不在GUI应用程序的`PATH`上。或者安装Node通过官方`.pkg`，或硬编码绝对路径：`"command": "/usr/local/bin/node"`，`"args": ["/usr/local/bin/npx", "-y", "roku-mcp"]`。
</details>
<details>
<summary><strong>Windsurf</strong> — Codeium的代理IDE</summary>
**前提条件：** Windsurf启用Cascade。
**安装：** 在项目根目录（或全局`~/.codeium/windsurf/mcp_config.json`）创建`.windsurf/mcp.json`：
```json
{
"mcpServers": {
"roku": {
"command": "npx",
"args": ["-y", "roku-mcp"],
"env": {
"ROKU_DEVICE_HOST": "192.168.1.XXX",
"ROKU_DEVICE_PASSWORD": "your-password"
}
}
}
}
```
重新加载窗口。在Cascade设置中，刷新MCP服务器列表。
**验证：** 询问Cascade“列出可用的MCP工具” — 应该出现`roku_*`条目。
**故障排除：** Windsurf偶尔会缓存过时的服务器。如果重新加载不能更新，请完全退出Windsurf并重新打开。
</details>
<details>
<summary><strong>任何MCP兼容的客户端</strong>（Continue、Cline、Zed、Codex、Claude Code、OpenCode等）</summary>
服务器使用标准的MCP **stdio**传输协议。在任何地方声明：
```
command: npx
args: ["-y", "roku-mcp"]
env: { ROKU_DEVICE_HOST: "...", ROKU_DEVICE_PASSWORD: "..." }
```
…服务器就会运行。两个环境变量都是可选的：省略`ROKU_DEVICE_HOST`以使用LAN上的SSDP自动发现，并传递`host` / `password`以覆盖每个工具调用。
仓库根目录中的[`AGENTS.md`](./AGENTS.md)被Claude Code、OpenCode、Codex CLI等遵循AGENTS.md约定的工具自动拾取，因此这些代理继承相同的用法指导，无需额外设置。
</details>
## 代理规则
为了获得更好的代理行为（`observe → act → wait → verify`循环，RTA `uiElementId`陷阱，当使用哪个工具时），仓库提供了预先格式化为每个主要代理的规则。主体相同 — 只有包装器不同，以匹配每个代理自动加载的内容。
| 代理 | 文件 | 安装路径 |
|---|---|---|
| Cursor | [`rules/cursor/roku-mcp.mdc`](./rules/cursor/roku-mcp.mdc) | `.cursor/rules/roku-mcp.mdc` |
| Claude Code | [`rules/claude-code/CLAUDE.md`](./rules/claude-code/CLAUDE.md) | `CLAUDE.md`（仓库根目录） |
| Claude Desktop | [`rules/claude-desktop/roku-mcp.md`](./rules/claude-desktop/roku-mcp.md) | 设置 → 系统提示 |
| Windsurf | [`rules/windsurf/roku-mcp.md`](./rules/windsurf/roku-mcp.md) | `.windsurf/rules/roku-mcp.md` |
| Codex CLI / OpenCode / Aider | [`AGENTS.md`](./AGENTS.md)（仓库根目录） | `AGENTS.md`（仓库根目录） |
参见[`rules/README.md`](./rules/README.md)，获取每个代理的一行复制命令。
## 快速入门
一旦您的客户端连接正确，以下三个提示即可开箱即用，并锻炼主要功能组。
**1. 确认设备可访问**
```
使用roku-mcp查询我的Roku设备信息，并告诉我型号、固件和IP。
```
代理应调用`roku_query_device_info`（如果未配置主机，可能还会调用`roku_discover`）并在一轮中回复。
**2. 使用截图驱动UI**
```
按下Home键，等待2秒，截图，然后向右移动两次，截图。描述两次截图之间的变化。
```
这练习了`roku_keypress`、`roku_sleep`和`roku_screenshot` — 标准*观察 → 操作 → 等待 → 验证*循环。
**3. 实时编辑正在运行的频道（需要RTA — 参见[运行时UI编辑](#runtime-ui-editing)）**
```
在当前运行的开发频道上，找到显示页面标题的标签，将其文本更改为“Hello from MCP”，使用roku_get_value验证更改，然后更改回原样。
```
代理将`roku_query_app_ui`以定位节点，获取`uiElementId`，调用`roku_edit_node` + `roku_get_value`，并回滚 — 证明端到端RTA线路。
## 环境变量
| 变量 | 描述 |
|---|---|
| `ROKU_DEVICE_HOST` | Roku设备的IP地址或主机名 |
| `ROKU_DEVICE_PASSWORD` | Roku设备的开发密码 |
也可以在每个工具调用时传递这些参数，覆盖环境变量。
### 自动发现
如果未设置`ROKU_DEVICE_HOST`，并且未提供`host`参数，则服务器会自动使用SSDP在本地网络上发现Roku设备，并使用找到的第一个设备。您还可以使用`roku_discover`工具列出所有可用的设备。请注意，密码无法被发现，仍必须配置。
### `.env`文件支持
服务器自动从当前工作目录使用[dotenv](https://www.npmjs.com/package/dotenv)加载`.env`文件。如果您的项目的`.env`已经使用`ROKU_DEVICE_HOST`和`ROKU_DEVICE_PASSWORD`，则服务器会直接获取它们 — 只需省略MCP配置中的`env`块：
```
ROKU_DEVICE_HOST=192.168.1.100
ROKU_DEVICE_PASSWORD=my-password
```
如果您的项目使用不同的变量名称（例如`ROKU_IP`、`ROKU_DEV_PASSWORD`），您可以在`env`块中映射它们：
```json
"env": {
"ROKU_DEVICE_HOST": "${ROKU_IP}",
"ROKU_DEVICE_PASSWORD": "${ROKU_DEV_PASSWORD}"
}
```
或者只需将两个预期变量添加到您的`.env`中，与现有的变量一起。
## 可用工具
### 部署
| 工具 | 描述 |
|---|---|
| `roku_deploy` | 将Roku应用侧载（部署）到设备 |
| `roku_delete_dev_channel` | 删除当前侧载的开发频道 |
### 发现
| 工具 | 描述 |
|---|---|
| `roku_discover` | 通过SSDP扫描本地网络中的Roku设备 |
### ECP（外部控制协议）
| 工具 | 描述 |
|---|---|
| `roku_keypress` | 发送单个按键（Home、Select、Up、Down、Left、Right、Back等） |
| `roku_keypress_sequence` | 以可配置的延迟顺序发送多个按键 |
| `roku_type_text` | 将文本字符串键入聚焦字段（例如电子邮件、密码、搜索） |
| `roku_launch` | 启动或深入链接到频道 |
| `roku_query_device_info` | 获取设备型号、固件、序列号、网络信息 |
| `roku_query_active_app` | 获取当前运行的应用 |
| `roku_query_media_player` | 获取媒体播放器状态（播放/暂停/缓冲/停止）、位置和持续时间 |
| `roku_query_app_ui` | 获取当前应用UI树为XML |
| `roku_query_sg_nodes` | 查询SceneGraph节点（全部、根或按节点ID） |
| `roku_find_node` | 按ID或属性（子类型、文本等）搜索UI树中的节点 |
| `roku_get_focused_node` | 获取当前聚焦节点及其所有属性 |
| `roku_sleep` | 等待指定持续时间（在导航步骤之间很有用） |
### 截图
| 工具 | 描述 |
|---|---|
| `roku_screenshot` | 捕获截图（返回base64图像和文件路径） |
### 调试控制台
| 工具 | 描述 |
|---|---|
| `roku_console_connect` | 打开到BrightScript调试控制台的TCP连接（端口8085） |
| `roku_console_read` | 读取缓冲的控制台输出并自动断开连接 |
| `roku_console_send` | 向调试控制台发送命令并自动断开连接 |
| `roku_console_disconnect` | 关闭控制台连接（安全网） |
### 运行时UI编辑
编辑正在运行的侧载开发频道的SceneGraph UI，无需重新部署 — 与[vscode-brightscript-language](https://github.com/rokucommunity/vscode-brightscript-language)扩展程序中的SceneGraph Inspector使用的后端相同。这些工具针对频道的**设备组件**上的[roku-test-automation](https://github.com/triwav/roku-test-automation)（RTA）协议进行通信，TCP端口为9000，因此更改立即生效，无需调试器暂停。
| 工具 | 描述 |
|---|---|
| `roku_edit_node` | 按ID设置一个或多个节点字段（可见性、翻译、文本、颜色、不透明度等） |
| `roku_set_node_visible` | 显示或隐藏ID的节点 |
| `roku_move_node` | 将节点移动到 `[x, y]` |
| `roku_focus_node` | 按ID设置节点焦点（RTA `focusNode`） |
| `roku_remove_node` | 运行时从其父节点分离节点（RTA `removeNode`） |
| `roku_create_node` | 创建新节点并将其追加到ID的父节点（RTA `createChild`） |
| `roku_get_value` | 从运行的场景读取字段值（或完整的`keyPath`）（RTA `getValue`） |
| `roku_observe_field` | 等待字段更改或匹配值（RTA `onFieldChangeOnce`） — 非常适合“直到X”断言 |
**工作原理。** 每个工具都打开一个短寿命的TCP连接到运行频道的RTA On-Device Component（端口9000），发送长度前缀的JSON请求（`setValue` / `getValue` / `focusNode` / ...）并解析帧JSON响应。更改在SceneGraph线程上应用，无需进入调试器。
**节点寻址。** `nodeId`接受：
- 像`RTA_1773`这样的`uiElementId`（在`roku_query_sg_nodes` / `roku_query_app_ui`输出中每个节点时可见）。这是最强大的目标。
- 节点在频道源中定义的实际BrightScript `id`属性。
任何匹配`/^RTA_\d+$/`的内容都带有RTA `base: "elementId"`；否则发送时带有`base: "scene"`。
#### 必需：安装RTA On-Device Component
这些工具仅在测试的频道包含RTA时才有效。您有两个选项：
**选项A — 让`roku-debug`在每次侧载时注入RTA（推荐VS Code用户）。**
1. 在您的`launch.json`中启用：
```json
"injectRdbOnDeviceComponent": true
```
2. 在`source/main.brs`中添加标记注释：
```brightscript
sub main()
screen = createObject("roSGScreen")
' ...
screen.show()
' vscode_rdb_on_device_component_entry
' ...
end sub
```
**选项B — 您自己打包RTA组件。** 复制[roku-test-automation](https://github.com/triwav/roku-test-automation)中的`device/components`文件夹到您的频道并实例化`RTA_OnDeviceComponent`一次，从您的场景。
无论哪种方式，成功安装后，您将在设备日志中看到：
```
[RTA][INFO] OnDeviceComponent init
```
Either way, on a successful install you will see this in the device log at channel launch:
```
[RTA][INFO] OnDeviceComponent init
```
If a runtime UI tool returns a connection-refused error, RTA is not present in the running channel — apply one of the two install options above and redeploy.
### BrightScript Profiler
分析Roku设备生成的`.bsprof`文件。这些工具使用[bsprof-cli](https://www.npmjs.com/package/bsprof-cli)解析二进制分析器格式并返回结构化的JSON报告。
| 工具 | 描述 |
|---|---|
| `analyze_bsprof` | 分析.bsprof文件 — 内存泄漏、CPU热点路径、完整报告或摘要。支持按模块/文件筛选和排序选项。 |
| `compare_bsprof` | 比较两个.bsprof配置文件以检测回归、改进、新泄漏和已解决的泄漏。 |
| `bsprof_info` | 获取目标名称、设备、固件、格式版本、功能等头部元数据，无需完整解析。 |
要生成`.bsprof`文件，请在您的Roku应用的`manifest`中启用分析器（`bs_prof_enabled=true`），运行应用，然后从`http://<device-ip>:8080`下载分析文件。
### Perfetto Tracing
记录、分析和比较Roku设备的Perfetto跟踪信息。需要**Roku OS 15.1+**。这些工具使用[roku-perfetto](https://www.npmjs.com/package/roku-perfetto)进行ECP控制、WebSocket记录和PerfettoSQL分析。
| 工具 | 描述 |
|---|---|
| `roku_perfetto_enable` | 通过ECP启用频道的Perfetto跟踪（跟踪在下一次应用启动时开始） |
| `roku_perfetto_start` | 通过WebSocket二进制流启动Perfetto跟踪记录 |
| `roku_perfetto_stop` | 停止记录并返回文件路径、大小和持续时间 |
| `analyze_perfetto` | 分析.trace文件 — 摘要、帧丢失、关键事件、观察者、汇聚、设置字段或线程。返回带有建议的AI友好结构化JSON。 |
| `compare_perfetto` | 比较两个.trace文件以检测性能回归和改进 |
| `query_perfetto` | 对.trace文件运行原始PerfettoSQL查询以进行自定义分析 |
工作流程：启用跟踪 → 启动记录 → 与应用交互 → 停止记录 → 分析。`.trace`文件也可以在[ui.perfetto.dev](https://ui.perfetto.dev/)上打开。
### 流诊断
找出HLS/DASH流在其他地方播放正常，但在Roku上失败的原因。
| 工具 | 描述 |
|---|---|
| `roku_diagnose_stream` | 将Video节点的`errorInfo`、清单（可获取的`url`或粘贴的`content`）和可选的Charles/HAR捕获相关联到排名的Roku特定根本原因（原因、证据、置信度、严重性、修复、文档链接）。可选`captureLive=true`部署捆绑的StreamProbe工具包以捕获设备错误。 |
它检测Roku特有的陷阱，例如fMP4/CMAF HLS中的muxed音频+视频（播放视频但静音）、硬件解码器不支持的视频编解码器/级别（例如4K H.264或8K HEVC）、令牌/403受限的CDN和DRM许可拒绝。静态清单检查被视为提示；当您提供实际的设备`errorInfo`时，诊断被证实为高置信度。
## 需求
- Node.js 18+
- 一个Roku设备，启用[开发者模式](https://developer.roku.com/docs/developer-program/getting-started/developer-setup.md)
- 用于截图和部署：必须运行一个侧载的开发频道
## 许可
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器