roku-dev-mcp)
一个自主的模型上下文协议（MCP）服务器，使 AI 编码代理（如 Antigravity、Claude 和 Cursor）能够开发、部署、导航、检查和调试 Roku BrightScript 和 SceneGraph 应用程序。
Roku OS 将开发 API 分布在四个不同的网络协议和四个不同的端口上。roku-dev-mcp 充当中间件控制器，在代理的结构化 JSON 工具调用接口与 Roku 碎片化的开发者 API 表面之间架起桥梁。
┌──────────────────────────────────────────────────────────────────┐
│ MCP Client (Agent) │
│ (Antigravity / Claude / etc.) │
└──────────────────────────┬───────────────────────────────────────┘
│ MCP Protocol (stdio)
▼
┌──────────────────────────────────────────────────────────────────┐
│ roku-dev-mcp Server │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ Tool Router │ │ Log Buffer │ │ Connection Manager │ │
│ │ (Zod Schemas│ │ (Ring Buffer │ │ (Mutex, Reconnect, │ │
│ │ & Handlers)│ │ & Crash Det)│ │ Timeouts) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬─────────────────┘ │
│ │ │ │ │
│ ┌──────┴─────────────────┴──────────────────┴─────────────────┐ │
│ │ Roku Interface Adapters │ │
│ │ ┌─────────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │ │
│ │ │ Port 80 │ │ Port │ │ Port │ │ Port 8085 │ │ │
│ │ │ Installer │ │ 8060 ECP │ │ 8080 SG │ │ BS Console │ │ │
│ │ │ (HTTP/ │ │ (HTTP │ │ Debug │ │ (Telnet / │ │ │
│ │ │ Digest) │ │ REST) │ │ (Telnet) │ │ Persistent)│ │ │
│ │ └──────┬──────┘ └────┬─────┘ └────┬─────┘ └──────┬──────┘ │ │
│ └─────────┼─────────────┼────────────┼──────────────┼──────────┘ │
└────────────┼─────────────┼────────────┼──────────────┼────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────┐
│ Roku Device (TV / Stick) │
│ :80 Installer :8060 ECP :8080 SG Debug :8085 BS Debug │
└──────────────────────────────────────────────────────────────────┘Related MCP server: roku-mcp
端口 | 协议 | 认证 | 连接方式 | 用途 |
80 | HTTP | Digest（ | 每请求 | 侧载（ |
8060 | HTTP REST | 无* | 每请求 | 远程按键、深度链接、设备/媒体状态查询 |
8080 | Telnet (TCP) | 无 | 按需（串行） | SceneGraph 实时节点树转储（ |
8085 | Telnet (TCP) | 无 | 持久后台连接 | BrightScript 控制台日志、实时崩溃捕获、交互式调试器 |
*在 Roku OS 14.1+ 中需要启用“通过移动应用控制”。
启用开发者模式：
遥控器序列：Home ×3 → Up ×2 → Right → Left → Right → Left → Right。
设置开发者密码（用作 ROKU_DEV_PASSWORD）。
启用“通过移动应用控制”：
设置 → 系统 → 高级系统设置 → 通过移动应用控制 → 选择**“已启用”**。
本地网络连接：
确保运行 MCP 服务器的主机与 Roku 设备位于同一子网。
端口 80、8060、8080 和 8085 必须可访问。
Node.js：≥ 20.0.0（推荐 LTS）
npm 或 pnpm
在项目根目录创建 .env 文件，或在 MCP 客户端中配置环境变量：
变量 | 必需 | 默认值 | 描述 |
| 是 | — | 在开发者模式激活期间设置的开发者密码。 |
| 否 | SSDP 发现 | 目标 Roku 设备的 IPv4 地址（例如 |
| 否 |
| BrightScript 环形缓冲区中的最大行数。 |
| 否 |
| 连续按键之间的延迟（毫秒）。 |
| 否 |
| Telnet 套接字的 TCP 连接超时。 |
| 否 |
| Telnet 命令执行超时。 |
将服务器添加到您的 MCP 客户端配置中（例如，claude_desktop_config.json 中的 mcpServers 或 Antigravity MCP 设置）：
{
"mcpServers": {
"roku-dev": {
"command": "node",
"args": ["/absolute/path/to/roku-dev-mcp/dist/index.js"],
"env": {
"ROKU_DEV_PASSWORD": "your_roku_dev_password",
"ROKU_DEVICE_IP": "192.168.1.50"
}
}
}
}有关 Antigravity、Claude CLI / Claude Desktop、Codex 和 Opencode 的详细配置说明，请参阅 docs/INSTALL.md。
roku_build_and_deploy将 BrightScript/SceneGraph 项目目录打包并侧载到 Roku 设备。
输入：
source_dir（string）：项目根目录的绝对路径（必须包含 manifest）。
action（"Install" | "Replace"，默认："Install"）：Install 会替换任何现有的侧载应用。
exclude_patterns（string[]，可选）：额外的 glob 排除模式。
返回：部署结果、启动日志、安装时长和崩溃状态。
roku_send_keys发送连续的 ECP 按键命令，并支持可配置的按键间延迟。
输入：
keys（string[]）：有序的 ECP 按键列表（例如 ["Home", "Down", "Select", "Lit_a"]）。
delay_ms（number，可选）：按键之间的延迟（毫秒）。
返回：发送的按键数、执行时长以及任何错误。
roku_get_ui_tree检查并解析实时 SceneGraph 节点树为 JSON 树结构。
输入：
filter_id（string，可选）：子树根节点 ID。
include_fields（boolean，默认：true）：包含节点字段键值。
max_depth（number，可选）：最大树深度。
返回：解析后的节点树，包含引用计数和字段数据。
roku_capture_state生成设备状态的复合多模态快照。
输入：
log_lines（number，默认：50）：最近的 BrightScript 日志条目。
include_screenshot（boolean，默认：true）：Base64 截图图像。
include_ui_tree（boolean，默认：false）：SceneGraph 树快照。
返回：复合 JSON 状态以及用于多模态代理的内联图像负载。
roku_assert_playback查询 ECP 媒体播放器以验证视频播放状态和指标。
输入：无。
返回：is_playing、is_buffering、progress_percent、时长、流比特率以及音频/视频格式。
roku_wait_for_condition基于条件的确定性轮询，避免硬编码的睡眠定时器。
输入：
condition（string）：条件表达式（node_exists: {id}、node_field: {id}.{field}={val}、playback_state: {state}、app_active: {id}、log_contains: {pattern}、crash_detected）。
timeout_seconds（number，默认：10）：最大等待时长。
poll_interval_ms（number，默认：500）：轮询间隔。
返回：满足标志、经过时间、轮询次数和匹配的快照。
roku_launch深度链接到侧载应用中的特定内容项。
输入：
content_id（string，可选）：目标内容 ID。
media_type（string，可选）：媒体类型提示（movie、series 等）。
params（Record<string, string>，可选）：额外的查询参数。
返回：启动确认和活动应用验证。
# Install dependencies
npm install
# Run unit tests (uses built-in MockRokuDevice)
npm test
# Run unit tests specifically
npm run test:unit
# Run integration tests against a real Roku TV
npm run test:integration
# Run all tests (unit + integration)
ROKU_INTEGRATION_TEST=1 npm test
# Run build
npm run build有关完整的测试文档和逐步验证说明，请参阅 docs/TESTING.md。
本项目根据 Unlicense 许可证授权 — 公有领域。
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Control real Android and iOS devices with LLM agents — tap, swipe, type, automate flows.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Run, build, and validate firmware on virtual hardware from your AI agent. Hardware knowledge corpus.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/voidxela/roku-dev-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
