# ADR 0017: MCP Remote Lua Execution

## Status

Accepted. Transport superseded by [ADR-0019](adr-0019-mcp-over-cloud-gateway.md) — the
MCP tools now ride the cloud gateway and address computers by `traposId`, and
`tools/mcp-bridge` (referenced below in the past tense) has since been removed. The
execution semantics and danger model below still apply.

## 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 MCP tools named `exec-lua` and `run-file` 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.

For existing Lua files, `run-file` sends a target path instead of source code, with an
optional `args` array for CLI-style program arguments. The ComputerCraft side reads that
file and loads the source into the same captured execution environment as `exec-lua`,
using the file path as the chunk name for useful errors. Arguments are passed as Lua
varargs and exposed through the `arg` table.

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. This applies to direct `exec-lua` chunks and to files run through `run-file`. 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.
