150 lines
4.2 KiB
Markdown
150 lines
4.2 KiB
Markdown
# In-Game TrapOS, AI, MCP Guide
|
|
|
|
Follow this order while playing.
|
|
|
|
## 1. Install TrapOS
|
|
|
|
On the ComputerCraft computer:
|
|
|
|
```sh
|
|
wget run https://os.trapcloud.fr/install
|
|
```
|
|
|
|
If the computer asks to reboot, reboot it.
|
|
|
|
## 2. Start OpenCode On Host
|
|
|
|
On your real machine:
|
|
|
|
```sh
|
|
opencode serve --hostname 0.0.0.0 --port 4242
|
|
```
|
|
|
|
If exposing beyond your machine, use a password:
|
|
|
|
```sh
|
|
OPENCODE_SERVER_PASSWORD=secret opencode serve --hostname 0.0.0.0 --port 4242
|
|
```
|
|
|
|
## 3. Connect `ai.lua`
|
|
|
|
On the ComputerCraft computer, use your public host:
|
|
|
|
```sh
|
|
set opencc.server_url http://<public-host>:4242
|
|
```
|
|
|
|
If you set a password:
|
|
|
|
```sh
|
|
set opencc.password secret
|
|
```
|
|
|
|
Optional model settings:
|
|
|
|
```sh
|
|
set opencc.provider_id anthropic
|
|
set opencc.model_id claude-opus-4-7
|
|
```
|
|
|
|
Optional agent setting for the in-game ComputerCraft assistant:
|
|
|
|
```sh
|
|
set opencc.agent atm10-expert
|
|
```
|
|
|
|
Test it:
|
|
|
|
```sh
|
|
ai ping
|
|
ai "say hello from TrapOS"
|
|
```
|
|
|
|
Expected ping: `pong`.
|
|
|
|
## 4. Start The Cloud Gateway On Host
|
|
|
|
The MCP tools now ride on the `trapos-server` gateway (the same WS connection used for
|
|
cloud health). From this repository on your real machine:
|
|
|
|
```sh
|
|
just serve
|
|
```
|
|
|
|
This serves two listeners:
|
|
|
|
```text
|
|
Gateway (in-game computers connect here): ws://<public-host>:4444/gateway
|
|
MCP endpoint (OpenCode connects here): http://127.0.0.1:4445
|
|
```
|
|
|
|
The MCP endpoint stays bound to `127.0.0.1` on purpose: `exec-lua` / `write-file` are
|
|
as powerful as the linked computer, so only local processes (your OpenCode) reach them.
|
|
`TRAPOS_SERVER_PASSWORD` (and `OPENCODE_SERVER_PASSWORD`) must be set in `.env`: the
|
|
gateway connection requires this shared secret, and the server refuses to start if either
|
|
is empty (run `just install` to generate them). An empty password would expose the gateway
|
|
unauthenticated, so it is never allowed.
|
|
|
|
## 5. Link The Computer To The Gateway
|
|
|
|
On the ComputerCraft computer, point it at the gateway and reboot:
|
|
|
|
```sh
|
|
set cloud.url ws://<public-host>:4444
|
|
set cloud.password secret # must match TRAPOS_SERVER_PASSWORD on the host
|
|
reboot
|
|
```
|
|
|
|
The `servers/cloud` daemon connects automatically at boot, and `servers/mcp-computer-server`
|
|
starts serving `exec-lua` / `write-file` over that one connection. Check the link with:
|
|
|
|
```sh
|
|
cloud health
|
|
```
|
|
|
|
## 6. Connect OpenCode To MCP
|
|
|
|
Add the gateway's MCP endpoint as an MCP HTTP server in your OpenCode MCP config:
|
|
|
|
```text
|
|
http://127.0.0.1:4445
|
|
```
|
|
|
|
Then ask OpenCode to use the MCP tool `probe-computers`. It lists each connected
|
|
computer's `traposId` (the `"<id>:<label>"` string), for example `ok from 7:base`.
|
|
|
|
`exec-lua` and `write-file` address a computer by that `traposId`. `exec-lua` runs Lua
|
|
on the target and returns captured output to OpenCode:
|
|
|
|
```lua
|
|
print('captured in MCP output')
|
|
```
|
|
|
|
To write to the visible ComputerCraft screen, use terminal APIs directly:
|
|
|
|
```lua
|
|
term.clear()
|
|
term.setCursorPos(1, 1)
|
|
term.write('visible on screen')
|
|
```
|
|
|
|
`exec-lua` is powerful and unsafe by design: it can do anything the linked computer can
|
|
do, including file, peripheral, turtle, and reboot operations. The trust boundary is the
|
|
authenticated gateway connection (`cloud.url` + `TRAPOS_SERVER_PASSWORD`) plus the local-only
|
|
MCP bind — only connect a computer to a gateway you control.
|
|
|
|
`write-file` writes content to a path on the target computer and overwrites any existing
|
|
file. It follows normal ComputerCraft filesystem behavior, so missing parent directories
|
|
fail instead of being created automatically.
|
|
|
|
## Quick Fixes
|
|
|
|
- `ai` says missing `opencc.server_url`: run the `set opencc.server_url ...` command again.
|
|
- `ai` cannot reach server: check `opencode serve`, public host, port `4242`, and ComputerCraft HTTP rules.
|
|
- `cloud health` fails: enable ComputerCraft HTTP/WebSocket support and check `cloud.url` (port `4444`).
|
|
- MCP sees no computers: confirm `cloud.url` is set and the computer was rebooted so `servers/cloud` is running.
|
|
- `exec-lua` / `write-file` return `unknown_type`: that computer is not running `servers/mcp-computer-server` (set `cloud.url` and reboot).
|
|
- `exec-lua` or `write-file` is missing after updating: restart OpenCode so it reloads the MCP tool list.
|
|
|
|
More detail: [`opencode_server_guide.md`](opencode_server_guide.md), [`public-ports.md`](public-ports.md).
|