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 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:

just 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. 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:

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:

cloud 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 (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, public-ports.md.