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:

{ "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.

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.

3.4 KiB Raw Blame History