63 lines
4.1 KiB
Markdown
63 lines
4.1 KiB
Markdown
# ADR 0017: MCP Remote Lua Execution
|
|
|
|
## Status
|
|
|
|
Accepted. Transport superseded by [ADR-0019](adr-0019-mcp-over-sandbox-gateway.md) — the
|
|
MCP tools now ride the sandbox gateway and address computers by `traposId`. 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.
|