# In-Game TrapOS, AI, MCP Guide

Follow this order while playing.

## 1. Install TrapOS

On the ComputerCraft computer:

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

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

From this repository on your real machine:

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

Production ports:

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

## 5. Link The Computer To MCP

On the ComputerCraft computer:

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

Leave it running. You should see:

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

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

```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. 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`](opencode_server_guide.md), [`public-ports.md`](public-ports.md).