From e0439ac6c552f183ba2b936c041794cf77641642 Mon Sep 17 00:00:00 2001
From: Guillaume ARM <trapcodien@gmail.com>
Date: Thu, 11 Jun 2026 03:08:39 +0200
Subject: [PATCH] docs(mcp): add in-game setup guide

---
 docs/ingame-trapos-ai-mcp-guide.md | 110 +++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 docs/ingame-trapos-ai-mcp-guide.md

diff --git a/docs/ingame-trapos-ai-mcp-guide.md b/docs/ingame-trapos-ai-mcp-guide.md
new file mode 100644
index 0000000..f4f6f63
--- /dev/null
+++ b/docs/ingame-trapos-ai-mcp-guide.md
@@ -0,0 +1,110 @@
+# In-Game TrapOS, AI, MCP Guide
+
+Follow this order while playing.
+
+## 1. Install TrapOS
+
+On the ComputerCraft computer:
+
+```sh
+wget run https://raw.githubusercontent.com/guillaumearm/cc-libs/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
+```
+
+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.
+
+## 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.
+
+More detail: [`opencode_server_guide.md`](opencode_server_guide.md), [`public-ports.md`](public-ports.md).