MCP dap_variables

Description

Inspect a BrightScript variable or container hierarchically, wrapping the device's VARIABLES command over Roku's socket-based BrightScript debug protocol (TCP 8081) -- NOT the Microsoft Debug Adapter Protocol.

Requires the app to be fully stopped (every thread halted) -- calling this while running returns an error saying to wait for the app to stop and retry.

path may be written either as a dotted/bracketed human string ("m.top.children[0].text") or as the raw wire-form segment array (["m","top","children","0","text"]) -- array indices are just numeric string segments, there is no separate index syntax on the wire. Omit path entirely to list the current frame's top-level locals.

The response ALWAYS leads with the addressed value itself (unnamed), followed by its children when it is a container -- this is the device's own response shape, not a synthesized wrapper. Two internal helper variables (the eval scratch temp and the conditional-breakpoint helper) are filtered out of every listing; they still leak into the underlying protocol but are never useful to inspect. A container's own elementCount field is not adjusted for this filtering -- it still reflects the device's real child count, so it may be one or two higher than the number of children actually returned in a listing that happened to include a helper variable.

includeVirtualKeys additionally returns SceneGraph's $-prefixed pseudo-fields (e.g. $children, $fieldTypes, $hasFocus) on a node -- this needs BrightScript debug protocol 3.3.0+. Requesting it below 3.3 returns a clear error naming the device's actual protocol version rather than silently omitting the fields.

frameIndex is innermost-first, matching debug_stacktrace's own indexing (0 = the current/most recent call) -- NOT the device's own VARIABLES frame numbering, which runs in the opposite direction; this tool converts internally.

A malformed path string (unbalanced brackets, a non-numeric bracket, a double dot) is rejected up front with a 400 error (code: MALFORMED_PATH) naming the problem -- it is never silently reinterpreted as something else. A well-formed path the device doesn't recognize at the current stop location (wrong key, wrong frame/thread) comes back as a 404 error (code: PATH_NOT_FOUND) -- this is a normal, expected outcome when guessing a path, not a failure of the tool itself.

Optional parameters:

• path (string or array of strings): Variable path, e.g. "m.top.children[0].text" or
  ["m","top","children","0","text"]. Omit for the current frame's top-level locals.
• threadId (string): Namespaced thread id, e.g. brs:0. Uses the session's default thread (see
  dap_thread_select) when omitted.
• frameIndex (number): Stack frame, innermost-first (0 = current). Defaults to 0.
• includeVirtualKeys (boolean): Include SceneGraph's $-prefixed pseudo-fields. Requires protocol
  3.3.0+. Defaults to false.
• sessionId (string): Session id returned by debug_session_create. Uses the active session when
  omitted.

See also

• HTTP dapGetVariables (GET /api/dap/variables)
• rk dap variables

Parameters

additionalProperties: false

path

Variable path, dotted/bracketed string or raw segment array

threadId

Namespaced thread id, e.g. brs:0

frameIndex

Stack frame, innermost-first (0 = current)

includeVirtualKeys

Include SceneGraph $-prefixed pseudo-fields (requires protocol 3.3.0+)

sessionId

Session id returned by debug_session_create