graph TB
    subgraph "AI Agent (Hermes, VS Code, etc.)"
        MCP[<b>MCP Client</b><br/>stdio JSON-RPC]
    end

    subgraph "roku-debug-mcp (MCP Server)"
        Server[<b>MCP Server</b><br/>21 tools]
        Config[<b>Config</b><br/>ROKU_* env vars]
        Server --> Config
    end

    subgraph "Roku Device"
        direction LR

        subgraph "Port 80 — HTTP"
            Installer[<b>Sideloader</b><br/>Digest auth<br/>Expect: 100-continue]
        end

        subgraph "Port 8060 — ECP"
            ECP[<b>ECP Client</b><br/>Device info<br/>Scene graph<br/>Postback/keys]
        end

        subgraph "Port 8081 — Binary Debug"
            Debug[<b>Debug Client</b><br/>Binary protocol<br/>BSDBG magic]
        end

        subgraph "Port 8085 — Telnet"
            Console[<b>Text Console</b><br/>Fallback logs]
        end
    end

    MCP --> Server
    Server --> Installer
    Server --> ECP
    Server --> Debug
    Server --> Console

sequenceDiagram
    participant C as Client (roku-debug-mcp)
    participant R as Roku Device (port 8081)

    C->>R: Handshake<br/>[magic(8)][protocol_version(4)]
    R-->>C: [magic(8)][protocol_version(4)][packet_len(4)][revision]

    Note over C,R: Request/Response Format:<br/>[packet_length(4)][request_id(4)][cmd_code(4)][payload]

    C->>R: GET_THREADS (cmd=3)
    R-->>C: THREADS response

    C->>R: STACKTRACE (cmd=4, thread_index)
    R-->>C: Stack frames

    C->>R: ADD_BREAKPOINTS (cmd=7)
    R-->>C: Confirmation

    Note over C,R: Update notifications (request_id=0):<br/>CONNECT_IO_PORT, ALL_THREADS_STOPPED, etc.

sequenceDiagram
    participant C as Client
    participant R as Roku (port 80)

    C->>R: POST /plugin_package (Expect: 100-continue)
    R-->>C: 401 Unauthorized (WWW-Authenticate: Digest)
    C->>C: Compute digest hash
    C->>R: POST /plugin_package (Authorization: Digest)
    R-->>C: 100 Continue
    C->>R: [ZIP payload]
    R-->>C: 200 OK [chunked response with Dev Kit HTML]

cd /home/dom/src/roku-debug-mcp
pip install -e .

export ROKU_DEVICE_IP=192.168.1.10      # Roku device IP
export ROKU_DEV_USER=rokudev            # Dev channel username
export ROKU_DEV_PASSWORD=your-password  # Dev channel password

{
  "roku-debug-mcp": {
    "command": "roku-debug-mcp",
    "args": []
  }
}

roku_device_info()
roku_scene_graph()
roku_debug_threads()
roku_debug_stacktrace(thread_index=0)
roku_debug_variables(thread_index=0, frame_index=0)
roku_debug_execute(thread_index=0, frame_index=0, code="x = 42")
roku_debug_breakpoints_add(breakpoints=[{...}])
roku_debug_console_output()

# Run all tests (uses mock server on ephemeral ports)
pytest tests/ -v

# Mock server runs automatically via conftest fixtures
# No manual setup required

# Requires env vars set
ROKU_DEV_IP=10.71.71.151 \
ROKU_DEV_PASSWORD=your-password \
pytest tests/test_integration_real_device.py -v

src/rokumcp/
  config.py          # Environment-based configuration
  protocol.py        # Binary protocol constants and Stream I/O
  debug_client.py    # Synchronous binary debug client (port 8081)
  text_console.py    # Telnet text console client (port 8085)
  ecp.py             # ECP HTTP client (port 8060)
  installer.py       # HTTP Digest-auth sideloader (port 80)
  server.py          # MCP server entrypoint — 21 tools

tests/
  conftest.py                  # Pytest fixtures (mock server setup)
  mock_roku_server.py          # Mock Roku device simulator
  test_protocol.py             # Stream round-trips, ProtocolVersion
  test_config.py               # Config defaults, from_env
  test_ecp.py                  # ECP HTTP client
  test_text_console.py         # Telnet console client
  test_installer.py            # Digest auth + multipart
  test_debug_client.py         # Full E2E vs mock binary server
  test_integration_real_device.py  # Real device (gated on env vars)
  fixtures/                    # Test channel ZIP fixtures

# Run mock server manually
python tests/mock_roku_server.py

# Test specific protocol interaction
ROKU_DEVICE_IP=127.0.0.1 ROKU_DEBUG_PORT=8081 python -m rokumcp.server

pip install -e .
roku-debug-mcp  # runs MCP server over stdio