# ADR 0017: MCP Remote Lua Execution

## Status

Accepted

## Date

2026-06-11

## Context

`tools/mcp-bridge` links OpenCode MCP tools to ComputerCraft computers through the `mcp-computer` WebSocket program. The initial bridge only supported `probe-computers`, which proved that the host could reach linked computers but did not let the assistant inspect or modify in-game state directly.

For interactive TrapOS development, a remote Lua execution tool is useful: it can inspect files, peripherals, settings, labels, inventory-adjacent APIs, service state, and small runtime hypotheses without asking the player to type each command manually in-game.

This is also explicitly dangerous. A linked assistant can run arbitrary Lua with the same authority as the ComputerCraft computer. That includes file deletion, network traffic, peripheral operations, turtle movement, inventory changes, reboot/shutdown calls, and long-running or stuck programs.

## Decision

Add an MCP tool named `exec-lua` to `tools/mcp-bridge`.

The tool targets one linked computer by `computerId` and sends Lua source over the existing bridge request/response protocol:

```json
{ "type": "request", "id": "...", "method": "exec-lua", "params": { "code": "..." } }
```

The ComputerCraft side executes the code in `mcp-computer` and returns a normal bridge response with:

- `ok` for execution success or failure.
- `result.returns` as JSON-safe descriptors of returned values.
- `result.output` containing captured `print` and `write` output.
- `error` for syntax or runtime failure.

Execution is enabled by default for any computer running the updated `mcp-computer` program. We intentionally do not add an `--allow-exec` flag for this first version because the current workflow is a local, explicitly trusted development bridge and the user accepts the risk.

The execution environment overrides `print` and `write` so their text is captured in the MCP response instead of being emitted to the visible terminal. Code that intentionally wants to affect the ComputerCraft screen should call terminal APIs such as `term.clear`, `term.setCursorPos`, and `term.write` directly.

Timeouts are host-side request timeouts. A timed-out MCP call stops waiting for the response, but it does not preempt a running Lua chunk inside ComputerCraft. Avoid infinite loops and long blocking calls unless the in-game computer can be restarted.

## Consequences

- OpenCode can now inspect and operate linked ComputerCraft computers without manual in-game command entry.
- The trust boundary moves to the act of running `mcp-computer` against a bridge. Only run it against bridges and assistants you trust.
- The bridge remains protocol-compatible with older clients for `probe-computers`; older `mcp-computer` clients will report `unknown method` for `exec-lua`.
- Captured output is deterministic for assistant workflows; visible screen mutation remains explicit through `term.*` APIs.
- Tests must cover both host-side MCP routing and the real CraftOS-PC `mcp-computer` path so regressions are caught across the Node/Lua boundary described in [ADR-0016](adr-0016-js-tool-verification.md).

## Future Work

- Add a separate opt-in flag or per-computer policy if the bridge is used outside local trusted development.
- Add cooperative cancellation for yielding chunks if long-running remote execution becomes common.
- Add more convenience tools on top of the trusted bridge once usage patterns are clear.