MCP debug_session_create

Description

Create a unified debug session for a Roku app, optionally spanning both the TypeScript/Hermes runtime (CDP, port 9999) and the BrightScript runtime (DAP, port 8081).

"DAP" here is Roku's own binary BrightScript debug protocol on TCP 8081 -- NOT the Microsoft Debug Adapter Protocol.

mode is FIXED for the lifetime of the session -- BrightScript debugging cannot be added to a live session later because it requires a different sideload (remotedebug=1). To change mode, call debug_session_end and create a new session.

Required parameters:

• root (string): ABSOLUTE filesystem path to the Roku app root directory.

Optional parameters:

• mode (string): "cdp_only" (default, existing TypeScript/Hermes debugging, unchanged from cdp_session_create),
  "dap_only" (BrightScript debugging only), or "unified" (both runtimes -- requires an rk build --debug
  package, manifest ts_path=pkg:/source/compiled/index.js not index.hbc, so Hermes opens 9999, AND the
  remotedebug sideload fields so BrightScript debug opens 8081; both are validated at session creation
  and a failure names whichever requirement wasn't met).
• device (string), host (string), password (string), config (string): device targeting, same semantics as
  cdp_session_create -- device selects a stored device by id/IP/name, host bypasses the store for direct
  access, and the active device is used when neither is given. This is the ONLY way to target a device;
  there is no separate deviceIp parameter.
• connectionMode (string): "watch" (default, auto-reconnect) or "manual".
• coordinatedStop (boolean, default false): CDP -> DAP only -- when true, a Hermes (TypeScript)
  pause triggers a BrightScript STOP (all threads), budgeted at 500ms. The reverse direction
  (a BrightScript stop triggering a Hermes pause) is not implemented and is not planned: Hermes's
  Debugger.pause() against an idle runtime acknowledges in milliseconds and never emits a pause
  event, so there is nothing on that side to coordinate against. Unified breakpoint routing, eval
  routing, and console/error capture are unaffected by this flag either way.
• resumeOnEnd (boolean, default false): whether debug_session_end should send CONTINUE before
  disconnecting the BrightScript debugger. Without it, the app is left STOPPED on screen.

Known limitation for mode:"unified" with connectionMode:"watch": the two runtimes' auto-reconnect paths are not coordinated. If the BrightScript (DAP) socket drops and reconnects on its own, that recovery does not re-verify or invalidate breakpoints on the TypeScript (CDP) side, and vice versa. A socket drop affecting one runtime while the other stays connected can leave the session's breakpoint state stale until debug_session_update rebuilds it explicitly.

For a dap_only session, creation only completes once the device's console I/O socket is connected and the app's initial stop (frozen before its first statement) has been observed. The app remains stopped after creation -- set breakpoints, then call debug_continue to start it running.

If this call fails (e.g. the app never opened its debug port because it failed to compile), the session is kept readable as "failed" rather than discarded -- call debug_console_read({runtime: "device"}) with no sessionId to see the real cause (compile errors are raw device-console text, not in debug_errors_read; look for "*** ERROR compiling"/"Syntax Error"/"Compilation Failed").

Aliases

Aliases: cdp_session_create.

See also

• HTTP debugCreateSession (POST /api/debug/session/create)
• rk debug session create

Parameters

additionalProperties: false

root

Absolute path to the Roku app root

mode

cdp_only (default), dap_only, or unified (requires an rk build --debug package AND the remotedebug sideload fields; validated at creation)

device

Target device ID, IP, or exact name

host

Direct target host/IP

password

Device password override

config

Build config name

connectionMode

watch (default) or manual

coordinatedStop

CDP -> DAP only: a TypeScript pause triggers a BrightScript stop (budgeted at 500ms)

resumeOnEnd

Send CONTINUE before disconnecting on debug_session_end