# Roku MCP

A standalone Model Context Protocol (MCP) server for Roku development. Create projects, look up BrightScript APIs, validate and package channels, run script tests, and capture headless SceneGraph or Draw2D previews.

Uses stdio transport. Requires Node.js 22 or newer and a working native `canvas` installation. No build step is needed to start the server.

## Install

```sh
git clone https://github.com/vynxc/roku-mcp.git
cd roku-mcp
npm ci
```

`canvas` may need native build prerequisites if a prebuilt binary is unavailable for your platform. Run `roku_doctor` after connecting to check the runtime and PNG encoder.

## Connect an MCP client

Add this entry to your client's MCP configuration, replacing both absolute paths:

```json
{
  "mcpServers": {
    "roku": {
      "command": "node",
      "args": [
        "/absolute/path/to/roku-mcp/scripts/mcp.mjs",
        "--workspace",
        "/absolute/path/to/your/roku-projects"
      ]
    }
  }
}
```

The workspace directory must already exist. The server also accepts `ROKU_WORKSPACE`; otherwise it uses its working directory. Relative tool paths resolve inside that workspace. Absolute paths must also stay inside it. Diagnostics go to stderr; stdout is reserved for MCP messages.

## Tools

| Tool | Purpose |
| --- | --- |
| `roku_doctor` | Check dependencies, native PNG support, and simulator capabilities. |
| `roku_project` | Create a `scenegraph`, `draw2d`, or `basic` project, or inspect an existing one. |
| `roku_reference` | Search the bundled BrightScript type snapshot and guidance topics. |
| `roku_check` | Validate BrightScript, BrighterScript, and SceneGraph XML. |
| `roku_build` | Validate, transpile, and produce a development ZIP. |
| `roku_test` | Run finite `.brs` scripts with optional literal log assertions. |
| `roku_preview` | Run a project, ZIP, or `.brs` with remote steps and initial/final PNGs. |

Start with `roku_doctor`, create or inspect a project, edit its sources with your client's file tools, then check, build, test, and preview. Each result includes `ok`; failed calls also set MCP `isError`. Preview reports include local artifact paths for PNGs and JSON logs.

Example tool arguments:

```json
{"action":"create","project":"my-channel","template":"scenegraph","title":"My Channel"}
```

```json
{"project":"my-channel","steps":[{"key":"up","wait_ms":100},{"key":"select","wait_ms":100}],"duration_ms":500,"output":"preview-001"}
```

```json
{"files":["tests/main.brs"],"expect_logs":["TEST_PASS"],"timeout_ms":10000}
```

Project creation and explicit output paths must be new. Default outputs use unique directories under `.roku-artifacts`. Preview steps, execution time, logs, archive sizes, and file counts are bounded. Cancellation and connection closure terminate active tool subprocesses.

## Limits

This is a simulator, not Roku OS. Hardware validation is still required for playback, DRM, performance, signing, and certification. No physical device discovery, deployment, or control is exposed. Reference data is bundled with BrighterScript and may differ from the current Roku SDK.

Run trusted apps only. Subprocesses inherit the server's OS permissions and environment; simulator apps may make network requests. Workspace path checks and symlink rejection are not an OS sandbox. Configure isolation in your MCP host or operating system when needed. Custom build hooks and file mappings are not executed.

## Development

```sh
npm ci
npm test
npm run check:roku
```

Tests build sample ZIPs under `dist/`, exercise the MCP stdio connection, and cover project validation, packaging, runtime failures, remote input, and PNG output. Runtime implementation lives in `src/headless`; `scripts/roku.mjs` is the internal subprocess worker.

MIT licensed. Derived from dsh-roku-dev; original copyright is retained in LICENSE. Uses [BrighterScript](https://github.com/rokucommunity/brighterscript) and the [BrightScript simulator](https://github.com/lvcabral/brs-engine); dependencies retain their respective licenses. Not affiliated with Roku.