52 lines
3.0 KiB
Markdown
52 lines
3.0 KiB
Markdown
# 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.
|