MCP Agent Workflows

MCP is most effective when agents use high-level state tools first and only fall back to large trees when needed.

A good agent loop starts with health and state, drives short input bursts, checks the result, then uses logs, traces, screenshots, or slices only when needed.

Default Session Flow

1. health()
2. get_state()
3. drive() or diff_state()
4. check()
5. logs() / diagnose() when something fails

Use get_state before navigating. It combines focus, route context, and CollectionView state in one smaller response.

Navigation Debugging

Use diff_state for "what changed after these keys?":

diff_state({ keys: ["Down"] })

For multi-step flows, turn on timeline output:

diff_state({
  keys: ["Down", "Down", "Select"],
  timeline: true,
  format: "table"
})

Useful options include:

Option	Use
timeline: true	show state after each key
watch_cells: true	track focused CollectionView row cells
watch_hids	track specific views
properties	limit watched view fields
animation_frames: true	sample scroll/animation frames
format: "table"	readable terminal output
format: "markdown"	chat-friendly output

CollectionView Debugging

For CollectionView issues, prefer:

get_state()
get_collection_view()
get_collection_view_slice()
diff_state({ keys: ["Down"], watch_cells: true })
trace_cv_rows()
diagnose({ scope: "collection_view" })

Avoid starting with the full Hosanna tree unless you need unknown _hid values. get_collection_view exposes row labels, focused indices, visible windows, cell metadata, and truncation hints. get_collection_view_slice is better for targeted row/cell tracking.

Handler and Render Debugging

Use tracing when focus moves unexpectedly or a key press triggers a rebuild:

trace_handlers({ keys: ["Down"], watch_hids: ["506"] })
trace_render({ keys: ["Down"], watch_hids: ["506"] })
render_frequency()
inspect_lifecycle({ _hid: "506" })

Handler tracing records onInputEvent, focus/blur, focused-child changes, consumption results, and selected property writes. Render tracing records state mutations and rebuilds around navigation.

Logging

Use MCP log tools before asking a developer for copied output:

logs()
search_app_logs({ query: "error" })
get_roku_errors()
search_roku_logs({ query: "BrightScript" })

For Roku logs, configure the device first:

configure_roku_device({ ip: "192.168.1.10", password: "..." })
connect_roku_logs()

Screenshots

Use screenshots when layout or visual state is ambiguous:

take_web_screenshot()
take_screenshot()

take_web_screenshot captures the web app through browser automation. take_screenshot uses Roku's developer application installer endpoint and requires the Roku dev password.

Repeatable Tests

MCP supports recording and replaying UI flows:

start_test_recording()
record_step()
stop_test_recording()
replay_test_recording()
list_test_recordings()

The CLI equivalents are:

npx hst test:record
npx hst test:ui

hst test:ui can replay all recordings or selected recording IDs, compare screenshots, emit reports, update baselines, and run coverage-only analysis.

Anti-Patterns

• Do not call get_view_hierarchy as the first step for every issue.
• Do not send long key sequences blind; use short bursts and verify.
• Do not assume focus after Back; call get_state.
• Do not ignore app IDs when multiple apps are connected.
• Do not use device screenshot or ECP tools in cloud agents unless the device is network-reachable from that agent.