MCP debug_step

Description

Steps execution on the debugged Roku app: over, into, or out. This is the recommended, cross-cutting tool for debugsession-based workflows -- stepping is cross-cutting, so there is one tool with a type parameter instead of three per-backend ones. The per-backend cdp_debugger_step_over/_into/out tools remain fully valid for direct cdp_session usage; this tool does not replace or deprecate them.

On the BrightScript side (device command STEP), the WHOLE app must already be stopped (every thread) before stepping -- calling this while running returns a typed NOT_STOPPED error, the same as every BrightScript inspection tool. Stepping a specific thread (threadId) makes it the session's new default/primary thread going forward (read from firmware source; not yet independently verified on real hardware): a subsequent debug_continue (which always resumes the primary, with no thread argument) will resume whichever thread was last stepped, not necessarily the one that was primary before.

Error codes this tool can return on the BrightScript side: NOT_STOPPED (app running), THREAD_DETACHED (the target thread is no longer attached on the device -- call dap_threads to refresh), CANT_CONTINUE (the thread is stopped and attached but cannot step from its current state), INVALID_THREAD (the device rejected the resolved thread index), STEP_TIMEOUT (see below).

STEP_TIMEOUT (device-verified): stepping "over" or "out" of a statement that blocks on external input -- e.g. a message-port wait with nothing pending, such as a top-level "wait(0, port)" loop -- does not complete until that blocking call itself returns, exactly like stepping over a blocking call in any debugger. If nothing is ever going to arrive on that port, the step never completes on its own; STEP_TIMEOUT after a fixed 5s wait is the correct, honest outcome here, not a sign that an update was lost. That wait is currently a fixed internal default -- there is no parameter, on this tool or on debug_session_create, to raise it. If you expect a blocking call to unblock on its own, retry debug_step after waiting; otherwise avoid stepping over it in the first place (step "into" a called sub instead, or set a breakpoint further down and continue).

Stepping "out" of the outermost function on a thread (e.g. Main(), which has no caller) has also been device-verified to restart the whole channel from its very first statement rather than erroring or simply resuming -- expect a STEP_TIMEOUT here too if the restart takes longer than that same fixed 5s wait, followed by a fresh initial stop once it completes.

Required parameters:

• type ("over" | "into" | "out"): Step direction.

Optional parameters:

• threadId (string): BrightScript-only. Namespaced thread id, e.g. "brs:0". Uses the session's
  default thread when omitted. Rejected (400) for a TypeScript-routed call -- CDP has no
  thread-selection concept to route it to.
• runtime ("typescript" | "brightscript"): Force a backend. Defaults to the session's own mode.
• sessionId (string): Session id returned by debug_session_create. Uses the active session when
  omitted.

Aliases

Aliases: cdp_debugger_step_over, cdp_debugger_step_into, cdp_debugger_step_out.

See also

• HTTP debugStep (POST /api/debug/step)
• rk debug step

Parameters

additionalProperties: false

type

Step direction

threadId

BrightScript-only. Namespaced thread id, e.g. brs:0

runtime

Force a backend

sessionId

Session id returned by debug_session_create