# 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.

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`.
- 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 additional tools on top of `exec-lua` for common safe operations once usage patterns are clear.