brs-mcp
Scaffolds runnable Roku channels from an AppSpec, zips them, and optionally sideloads them to a Roku device in developer mode.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@brs-mcpGenerate a screensaver channel from my AppSpec and sideload to my Roku"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
brs-mcp
An MCP server that scaffolds runnable Roku channels (BrightScript + SceneGraph) from a validated
AppSpec, zips them, and optionally sideloads them to a Roku in developer mode.
What it does
An AI assistant (or any MCP client) passes a strict, versioned AppSpec. The server returns a complete project tree, produces a sideload-ready zip, and optionally installs it on a Roku device. Every generated file comes from a curated, hand-authored, device-tested template; the server never asks an LLM to write BrightScript.
Same spec in, same bytes out, every time. Zips are byte-reproducible across hosts (sorted entries, fixed mtime). Re-running on a machine in a different time zone produces identical output.
For a fuller styled reference with per-tool I/O examples, see docs/index.html.
Related MCP server: Echo MCP Server
Install
For a styled walkthrough with prereqs, four numbered steps, and update guidance on one page, see docs/install.html.
npm install -g brs-mcpWire it into your MCP client (e.g., Claude Desktop):
{
"mcpServers": {
"brs-mcp": {
"command": "brs-mcp"
}
}
}The server speaks MCP over stdio. Logs go to stderr; stdout is reserved for JSON-RPC.
Verify
One-liner that cold-fetches the published package and exercises a real MCP initialize handshake. No global install required:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"x","version":"1"}}}' | npx -y brs-mcpExpected response on stdout (one JSON object, formatted here for readability):
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": { "tools": {} },
"serverInfo": { "name": "brs-mcp", "version": "0.1.0" }
}
}Exit code 0, stderr silent. If you see any stdout output that isn't a single JSON-RPC object, something in your shell is polluting the transport; verify with npx -y brs-mcp <<< '{}' 2>/dev/null | head -c 200.
Tools
list_templates
List every template bundled with this server.
Input:
{}Output:
{ "templates": [{ "id", "category", "version", "description" }] }
get_template_schema
Return the JSON Schema (Draft 7) for a template's AppSpec, plus a minimal example.
Input:
{ "id": "video_grid_channel" }Output:
{ "schema": <JSON Schema>, "example_spec": <AppSpec> }
generate_app
Render a Roku channel project from a validated AppSpec. Optionally zip and sideload.
Input:
{ "spec", "output_dir", "assets_root"?, "overwrite"?, "zip"?, "sideload"? }Output (success):
{ "ok": true, "project_dir", "files_written", "zip_path"?, "sideload"? }sideloadimplieszip: true(enforced by schema).
package_app
Zip an already-generated project directory into a sideload-ready archive. Validates a top-level manifest. Output is byte-reproducible.
Input:
{ "project_dir", "output_zip"? }Output:
{ "ok": true, "zip_path", "size_bytes", "entry_count" }
sideload_app
Install a zip on a Roku in developer mode via HTTP Digest-authenticated multipart POST to /plugin_install. dev_password is never logged or echoed.
Input:
{ "zip_path", "device_ip", "dev_password" }Output:
{ "ok": true, "status": "installed" | "identical", "message", "duration_ms", "raw_html"? }
Templates
screensaver
Roku screensaver channel. Three styles:
slideshow: crossfade through bundled images.animated: bouncing colored shapes (no images required).quadrant: 4-up grid of bundled images with rotating cells.
{
"template": "screensaver",
"spec_version": 1,
"app": { "name": "My Screensaver", "major_version": 1, "minor_version": 0, "build_version": 0 },
"style": "animated"
}Roku menu label note: When sideloaded via the dev web server, screensavers always appear in
Settings -> Theme -> Screensaversas the literal string(dev), not as theapp.namevalue. This is a Roku dev-build UX quirk and applies to every sideloaded screensaver including Roku's own canonical samples. Thescreensaver_titlemanifest field IS still required (and is presumably used once the screensaver is published through the channel store), but for sideload-based testing, look for the(dev)entry.
video_grid_channel
VOD grid: home (RowList) → detail → video player. Consumes mRSS, Roku Direct Publisher JSON, or a custom JSON feed.
{
"template": "video_grid_channel",
"spec_version": 1,
"app": { "name": "Example", "major_version": 1, "minor_version": 0, "build_version": 0 },
"branding": {
"primary_color": "#E50914",
"background_color": "#141414",
"text_color": "#FFFFFF",
"splash": { "hd": "./splash_hd.png", "fhd": "./splash_fhd.png" },
"icon": { "hd": "./icon_hd.png", "fhd": "./icon_fhd.png" }
},
"content": {
"feed_url": "https://example.com/feed.json",
"feed_format": "roku_direct_publisher_json"
}
}Highlights: deep-link aware (Main(args) + roInput runtime listener); centralized screen-stack with focus restoration; canonical Roku Overhang brand bar; BusySpinner during feed load; async feed fetch via roUrlTransfer.asyncGetToString.
Error taxonomy
Code | Meaning |
| Tool input or |
|
|
|
|
| Path is on the blocklist or outside an allowed directory. |
| Target directory exists and is non-empty (overwrite not requested). |
| A spec-referenced asset (icon/splash/etc.) is missing. |
|
|
| EJS render error inside a template. |
| Writer failed during atomic project write. |
| Packager failed. |
|
|
| Network failure reaching the Roku. |
| Roku is not in developer mode. |
| HTTP Digest auth was rejected. |
| Roku returned a failure body (e.g., bad archive). |
| Operation timed out before the device responded. |
Every failure response carries { ok: false, stage, code, message, details? }. stage is one of validate, render, write, package, sideload.
Architecture
Strict one-way dependency flow under src/:
tools/: MCP handlers. Composition root.templates/: Static template registry + EJS engine + render helpers. No network.build/: Atomic writer + deterministic zip packager (yazl, STORED, forced DOS timestamps). No network.device/: The ONLY module that imports a network client (undici). RFC 2617 Digest auth, multipart streaming viafs.openAsBlob, parsed Roku response markers.spec/: Shared zod schemas + error factory.
Real-device fixtures
test/fixtures/roku-responses/ contains the HTML response bodies the parser is tested against. They are captured against a live Roku via scripts/smoke.ts. Provenance and capture date live in test/fixtures/roku-responses/README.md.
Determinism
No Date.now(), no Math.random(), no clock skew leak into template output or the zip. Same AppSpec produces the same bytes on any host.
Contributing
Run npm install once after cloning. This installs the husky pre-commit hook via the prepare lifecycle script. Without it, your first commit bypasses the lint / format check.
The full local quality gate is:
npm run format:check && npm run lint && npm run typecheck && npm run build && npm testLicense
MIT; see LICENSE.
Available Tools
5 toolsgenerate_appB
Render a Roku channel project from a validated AppSpec and write it to output_dir. Set zip: true to also produce a sideload-ready archive at .zip. Set sideload: { device_ip, dev_password } to install the zip on a Roku device in developer mode (this implies zip: true).
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | ||
| output_dir | Yes | ||
| assets_root | No | ||
| overwrite | No | ||
| zip | No | ||
| sideload | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| project_dir | Yes | |
| files_written | Yes | |
| zip_path | No | |
| sideload | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions that sideload implies zip and requires developer mode. However, it does not discuss the overwrite parameter, error conditions, or whether the tool modifies the original spec. Overall, some useful context but significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the main purpose and then adding optional features. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, nested objects, output schema present), the description covers the core workflow and two optional features. However, it misses documenting assets_root and overwrite, and does not address prerequisites (validated AppSpec) or error scenarios. The output schema exists, so return values are covered, but the description could still be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain all parameters. It covers spec, output_dir, zip, and sideload, but leaves assets_root and overwrite unexplained. With 2 of 6 parameters undocumented, the description adds limited value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it renders a Roku channel project from a validated AppSpec and writes to output_dir. It also mentions optional zip and sideload. However, it does not differentiate from sibling tools like package_app or sideload_app, missing a chance to clarify when to use this combined tool vs separate steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives usage context for optional parameters (zip, sideload) and explains that sideload implies zip. But it lacks guidance on when not to use this tool or when to use siblings. For instance, it does not say 'use sideload_app if you only need to install an existing zip'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_template_schemaA
Return the JSON Schema (Draft 7) for a registered template's AppSpec, plus a minimal example spec.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| example_spec | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states what is returned, with no mention of side effects, permissions, rate limits, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loading the purpose with no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. Missing context on prerequisites (e.g., template must be registered) and valid ID sources, but overall adequate for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It implies 'id' is a template identifier but does not explicitly explain its role or constraints. Partial compensation above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns the JSON Schema (Draft 7) and a minimal example spec for a registered template's AppSpec. The verb 'Return' and specific resource distinguish it from siblings like list_templates, generate_app, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing a template's schema but provides no explicit when-to-use or when-not-to-use guidance, nor alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_templatesA
List every template bundled with this server. Returns metadata only; fetch a template's schema with get_template_schema.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| templates | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool returns only metadata (not full schemas), implying a read-only operation, which is adequate behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, no wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no input parameters and an output schema exists, the description is complete. It states the scope (metadata only) and points to a sibling for schema retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers that aspect. Baseline 4 is appropriate as there is nothing more to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List every template bundled with this server.' It specifies the verb (list) and resource (templates), and explicitly distinguishes from the sibling tool get_template_schema by noting that this tool returns only metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context for use: when you need to list templates. It also tells when not to use it (for schema details) and directs the agent to the appropriate sibling tool (get_template_schema).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
package_appA
Zip an already-generated Roku project directory into a sideload-ready archive. Validates that project_dir contains a top-level manifest. Output zip is byte-reproducible across hosts.
| Name | Required | Description | Default |
|---|---|---|---|
| project_dir | Yes | ||
| output_zip | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| zip_path | Yes | |
| size_bytes | Yes | |
| entry_count | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses validation (checks for manifest) and byte-reproducibility, but omits side effects, permissions, default behaviors, or error conditions. This is adequate but incomplete for a fully transparent definition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. Front-loaded with the core action, followed by validation and a key property. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the main use case, validation, and a notable feature. However, it does not explain what happens when output_zip is omitted (since it's optional) or describe the return value. The presence of an output schema mitigates this somewhat, but the optional parameter handling remains unclear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no individual parameter explanations. It only mentions that project_dir is an already-generated directory with a manifest. The optional output_zip parameter is not described, leaving ambiguity about its default behavior. This is insufficient for high-quality tool selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (zip), the resource (Roku project directory), and the purpose (sideload-ready archive). It distinguishes from sibling tools by specifying the input is an already-generated project, setting it apart from generate_app and sideload_app.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used after generation and before sideloading, providing contextual placement. However, it lacks explicit when-not-to-use directives or alternative mentions, though the sibling list partially compensates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sideload_appA
Install a zip on a Roku device in developer mode via HTTP Digest-authenticated multipart POST to /plugin_install. Returns the parsed device response. dev_password is never logged or echoed.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_path | Yes | ||
| device_ip | Yes | ||
| dev_password | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| status | Yes | |
| message | Yes | |
| raw_html | No | |
| duration_ms | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behaviors: HTTP Digest authentication, multipart POST to specific endpoint, parsed response, and that dev_password is never logged. No annotations provided, so description carries the full burden and does well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences: first covers the core operation, second adds return value and security note. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main action and output, but lacks prerequisites (device must be in developer mode, network reachable) and error behavior. Output schema exists but description doesn't reference it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are 0% covered, and the description provides minimal parameter-specific details. Only dev_password's non-logging is mentioned; zip_path and device_ip are not explained beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Install a zip on a Roku device in developer mode.' It distinguishes from sibling tools (generate_app, package_app, etc.) which focus on app creation and packaging, not installation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied but not explicit. No guidance on when to use this over alternatives or prerequisites like device must be in developer mode and network accessible.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
5 tool updates
v0.2.1- First observed
generate_app - First observed
get_template_schema - First observed
list_templates - First observed
package_app - First observed
sideload_app
TDQS
Each tool has a clearly distinct purpose: generating a project, fetching schema, listing templates, packaging, and sideloading. No overlap exists.
All tool names follow a consistent verb_noun pattern in lowercase snake_case (generate_app, get_template_schema, list_templates, package_app, sideload_app), making the set predictable.
With 5 tools covering the core workflow of generating, packaging, and deploying Roku channels, the count is well-scoped and appropriate for the domain.
The tool surface covers the main lifecycle: template discovery, schema retrieval, project generation, packaging, and sideloading. A minor gap is the lack of a standalone validation tool, but generate_app implicitly validates the AppSpec.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
The official MCP Server for the Mux API
The official Planning Center MCP server for interacting with your ministry's data.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseAqualityCmaintenanceA MCP server do create and deploy backend applications using https://heim.dev6233MIT
- FlicenseNot gradedqualityDmaintenanceA simple demonstration MCP server that provides an echo tool and resource for learning how to build MCP servers. Serves as a starting point and template for creating custom MCP server implementations.1-
- FlicenseNot gradedqualityBmaintenanceMCP server for Roku BrightScript documentation and device control, enabling doc search, device introspection, keypress/keysequence input, app launch, and sideloading.-
- AlicenseNot gradedqualityDmaintenanceEnables building MCP servers using TypeSpec, with tools for learning, scaffolding projects, and compiling TypeSpec to generate server assets.29,0079MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/bblietz/brs-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server