cc-libs/docs/ingame-trapos-ai-mcp-guide.md

In-Game TrapOS, AI, MCP Guide

Follow this order while playing.

1. Install TrapOS

On the ComputerCraft computer:

wget run https://os.trapcloud.fr/install

If the computer asks to reboot, reboot it.

2. Start OpenCode On Host

On your real machine:

opencode serve --hostname 0.0.0.0 --port 4242

If exposing beyond your machine, use a password:

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:

set opencc.server_url http://<public-host>:4242

If you set a password:

set opencc.password secret

Optional model settings:

set opencc.provider_id anthropic
set opencc.model_id claude-opus-4-7

Optional agent setting for the in-game ComputerCraft assistant:

set opencc.agent atm10-expert

Test it:

ai ping
ai "say hello from TrapOS"

Expected ping: pong.

4. Start The Sandbox Gateway On Host

The MCP tools now ride on the trap-sandbox gateway (the same WS connection used for sandbox health). From this repository on your real machine:

just sandbox-serve

This serves two listeners:

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. Set SANDBOX_PASSWORD in .env to require a shared secret on the gateway connection.

5. Link The Computer To The Gateway

On the ComputerCraft computer, point it at the gateway and reboot:

set sandbox.url ws://<public-host>:4444
set sandbox.password secret   # only if SANDBOX_PASSWORD is set on the host
reboot

The servers/sandbox daemon connects automatically at boot, and servers/mcp-computer-server starts serving exec-lua / write-file over that one connection. Check the link with:

sandbox health

6. Connect OpenCode To MCP

Add the gateway's MCP endpoint as an MCP HTTP server in your OpenCode MCP config:

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:

print('captured in MCP output')

To write to the visible ComputerCraft screen, use terminal APIs directly:

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 (sandbox.url + SANDBOX_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.
• sandbox health fails: enable ComputerCraft HTTP/WebSocket support and check sandbox.url (port 4444).
• MCP sees no computers: confirm sandbox.url is set and the computer was rebooted so servers/sandbox is running.
• exec-lua / write-file return unknown_type: that computer is not running servers/mcp-computer-server (set sandbox.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, public-ports.md.