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://git.trapcloud.fr/guillaumearm/cc-libs/raw/branch/next/install-ccpm.lua --beta
ccpm update
ccpm install trapos

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 MCP Bridge On Host

From this repository on your real machine:

cd tools/mcp-bridge
npm install
CC_LINK_PORT=4243 npm run dev

Production ports:

MCP endpoint: http://127.0.0.1:3000
ComputerCraft link: ws://<public-host>:4243

5. Link The Computer To MCP

On the ComputerCraft computer:

mcp-computer ws://<public-host>:4243

Leave it running. You should see:

linked as <id> (Label: <label>)
waiting for requests... Press Ctrl+T to stop.

6. Connect OpenCode To MCP

Add the bridge as an MCP HTTP server in your OpenCode MCP config, pointing at:

http://127.0.0.1:3000

Then ask OpenCode to use the MCP tool probe-computers. A working link returns a pong from <id> line.

The bridge also exposes exec-lua, which runs Lua on one linked computer by id. For example, this 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. Only run mcp-computer against a bridge you trust.

The bridge also exposes write-file, which writes content to a path on one linked computer by id 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.
• mcp-computer says WebSocket unavailable: enable ComputerCraft HTTP/WebSocket support.
• MCP sees no computers: keep mcp-computer ws://<public-host>:4243 running in-game.
• exec-lua or write-file is missing after updating the bridge: restart OpenCode so it reloads the MCP tool list.

More detail: opencode_server_guide.md, public-ports.md.