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.

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.

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.

3.0 KiB Raw Blame History