Debugging Roku apps with AI

This document shows you how to direct an AI assistant (for example, GitHub Copilot, Claude, or Cursor) to debug your Roku app on a real device with Model Context Protocol (MCP) tools.

You configure MCP with the rk mcp command, install the packaged mcp-ai-dev-loop skill that the AI follows, and then give the AI a prompt. See AI integration via MCP (rk mcp) for more information about setup. See Installing the skill (recommended) for more information about installing the skill. See debug-with-mcp.skill.md for more information about advanced techniques that go beyond the standard loop.

Instead of running commands yourself and copying the output into a chat, you can ask the AI to run them and reason about the results.

Using AI for device debugging

The Roku SDK's MCP integration gives an AI assistant the same access to your dev device that the rk CLI has: it can capture screenshots, query the SceneGraph UI tree, send remote-control sequences, read logs, and decode stack traces.

AI helps with the following tasks:

Investigating focus, layout, or visual bugs (it can see the screen)
Reproducing a multi-step user flow with keysequence and capturing each state
Decoding crash logs back to TypeScript source positions
Inserting trace console.log statements, deploying, reading logs, and removing them

AI does not help with the following tasks:

Anything that requires you to physically interact with the TV remote
Live log streaming (MCP reads the buffer of a log session; therefore, you can use rk logs tail to watch output as it happens)

Directing your AI to use the skill

After you configure MCP, you should install the skill so that your agent follows the mcp-ai-dev-loop procedure and does not bypass MCP with raw curl commands. You can install the skill in your project, or you can remind the AI in each conversation.

Installing the skill (recommended)

Run the following command to install the skill:

npx rk update-ai-context

The command writes the SDK's AI skills into your project under .agents/skills/roku-sdk-<name>/, including roku-sdk-mcp-ai-dev-loop, the skill for the device loop. This location follows the tool-neutral Agent Skills convention, and agents that follow the convention read it directly. The command does not modify your AGENTS.md or any other file of your own. You can run npx rk update-ai-context --help to see what the command writes and where, and you can run it again after an SDK upgrade to pick up changes.

You do not need to copy anything out of node_modules by hand, and you do not need to keep any path up to date in your own files.

Reminding the AI in each conversation

You can paste the following text at the start of a debugging session:

Use the Roku SDK MCP tools (provided by rk mcp) to debug the device. Do not use curl or raw HTTP for ECP. If you need to query UI state, capture the screen, send keys, or read logs, use the corresponding MCP tool.

Prompt recipes

You can copy the following prompts into your AI chat. The AI runs them through MCP.

Looking at what is on the screen

The following prompt asks the AI to describe the current screen:

Capture the screen on my active Roku and tell me what you see.

The AI calls capture_screen, views the returned image, and describes it.

Finding the focused component

The following prompt asks the AI to identify the component that has focus:

Capture the screen and query the UI hierarchy. Tell me which component currently has focus and where it is on the screen.

The AI calls capture_screen and ecp query/app-ui, correlates the two, and reports.

Reproducing a navigation flow

The following prompt asks the AI to run a sequence of key presses and capture each state:

Press Home, then launch the trivia app and navigate down three times and select. Capture the screen after each step.

The AI uses ecp keysequence for the navigation and capture_screen for verification.

Decoding a crash

The following prompt asks the AI to decode a stack trace from a crash log:

Here is a crash log from my device. Decode the stack trace and show me the source.
<paste log>

The AI calls decode_stack_trace with the raw text; it auto-detects the source map SHA.

Tracing a runtime issue

The following prompt asks the AI to add temporary logging, reproduce the problem, and report what the logs show:

The Continue button does not fire its onClick when I press Select. Add temporary console.log statements to the click handler and the surrounding state, deploy the app, press Select on the Continue button, then read the logs and tell me what is happening. Remove the logs when you are done.

The AI performs the following steps:

Edits the source to add console.log("[DEBUG] ...", value) lines.
Deploys the app with deploy_app.
Presses Select with ecp keypress key: Select.
Reads the logs with logs get or logs search filter: "DEBUG".
Analyzes the logs and reports.
Reverts the temporary log statements.

Capturing device info for a bug report

The following prompt asks the AI to collect device details for a bug report:

What model and firmware version is my active Roku running? Get me everything I need for a bug report.

The AI uses ecp query/device-info and summarizes.

Checking logs for an error pattern

The following prompt asks the AI to search the device logs and decode any stack traces:

Search the device logs for "Uncaught" or "Stack trace" in the last 5 minutes and show me what you find. Decode any stack traces you find.

The AI calls logs search and chains into decode_stack_trace for any crashes.

Understanding what to expect

A well-instructed AI does the following:

Builds and deploys with deploy_app, never by manually copying files
Drives the app with ecp keysequence and captures state with capture_screen
Uses a unique tag such as [DEBUG-1] when it inserts trace logs so that they are easy to filter and remove
Decodes stack traces with decode_stack_trace (it works with raw log noise around the trace)
Tells you when something it tried failed and why

If your AI starts running curl commands or shelling out to ssh, you can stop it and remind it to use MCP. The skill file is designed to prevent this behavior, but a long conversation can let the AI lose track of the skill's instructions.

Troubleshooting

The following problems and fixes apply to AI debugging with MCP.

The AI does not know about MCP tools: Verify that .vscode/mcp.json (or your editor's equivalent) is configured as described in AI integration via MCP (rk mcp). Reload the window. Try a simple prompt such as "list my Roku devices". If that prompt does not trigger an MCP call, MCP is not connected.
The AI keeps using curl instead of MCP: You can add the skill reference to AGENTS.md. See Installing the skill (recommended) for more information. You can also paste the reminder from Reminding the AI in each conversation.
Screenshots are not returning: Some MCP clients limit inline image size. You can ask the AI to save the file and tell you the path instead: "Capture the screen, save it to disk, and tell me the path."
Logs are empty: The log session may not be started. You can tell the AI: "Start a log session on the active device, then …"