cc-libs/.plans/remove-mcp-bridge-plan.md

Plan: Remove tools/mcp-bridge

Context

tools/mcp-bridge used to provide two separate host-side surfaces:

1. MCP tools and a dedicated ComputerCraft link transport.
2. An opencode HTTP-over-WebSocket proxy used by the in-game ai bridge mode.

The MCP tools have already moved to tools/trapos-server and .mcp.json already points at the cloud MCP endpoint (http://127.0.0.1:4445). The remaining live dependency is the old opencode proxy path (opencc.bridge_url / packages/trapos-ai/apis/libhttpws.lua).

Post-pull path note: Lua source files now live under packages/<pkg>/.... The CraftOS-PC test harness stages those files into flat runtime roots via just/stage.just, and package descriptors still list installed flat paths such as apis/libai.lua.

Decision: remove tools/mcp-bridge completely and intentionally drop the old opencode proxy implementation for now. If bridge/proxy behavior is needed again, re-implement it from scratch later; the old implementation remains available in git history.

Scope

• Delete tools/mcp-bridge/ entirely.
• Remove ai WebSocket bridge-mode support.
• Keep direct HTTP/HTTPS opencode support through packages/trapos-ai/apis/libhttp.lua.
• Keep current MCP tooling in tools/trapos-server unchanged, except for docs/tooling cleanup.

Runtime Changes

Drop libhttpws

• Delete packages/trapos-ai/apis/libhttpws.lua.
• Remove require('/apis/libhttpws') from packages/trapos-ai/apis/libai.lua.
• Remove opencc.bridge_url handling from packages/trapos-ai/apis/libai.lua.
• Remove the fallback that treats ws:// / wss:// opencc.server_url as bridge mode.
• Remove opencc.request_timeout_seconds usage if it only exists for the WebSocket transport.

Update ai CLI Help

Update packages/trapos-ai/programs/ai.lua help text:

• Remove opencc.bridge_url from required settings.
• Remove opencc.request_timeout_seconds from optional settings.
• Make opencc.server_url clearly HTTP/HTTPS-only.

Expected behavior after removal: users configure opencc.server_url to an HTTP/HTTPS opencode serve endpoint. There is no WebSocket bridge mode until a new implementation is added later.

Tests

Lua Tests

Update packages/trapos-ai/tests/ai.lua:

• Remove bridge-specific tests under the ask over the bridge ws transport section.
• Remove fake WebSocket helper code if it becomes unused.
• Keep direct HTTP opencode behavior tests.

Node / Integration Tests

• Delete all tools/mcp-bridge/test/ and tools/mcp-bridge/test-integration/ tests with the directory.
• Do not port opencode-proxy.test.ts or ai-cli.test.ts to tools/trapos-server; the proxy behavior is intentionally removed.
• Keep tools/trapos-server/test/ and tools/trapos-server/test-integration/ as the supported MCP/gateway coverage.

Tooling Changes

just/npm.just

• Remove npm-install-mcp-bridge.
• Remove npm-build-mcp-bridge.
• Remove npm-check-mcp-bridge.
• Remove npm-test-mcp-bridge.
• Remove npm-test-integration-mcp-bridge.
• Make aggregate Node recipes target only tools/trapos-server:
  • npm-install
  • npm-build
  • npm-check
  • npm-test
  • npm-test-integration

just/install.just

• Change clean to clean tools/trapos-server caches instead of tools/mcp-bridge, or make it a broader Node-tool clean if useful.
• Update the comment above clean.

just/test.just

• Update comments that describe end-to-end tests as spanning the MCP bridge; they now span the cloud gateway / MCP endpoint.

just/stage.just

• No behavior change expected. It already stages package-owned sources into .stage/; deleting packages/trapos-ai/apis/libhttpws.lua and removing it from packages/trapos-ai/ccpm.json is sufficient.

Packaging

Update packages/trapos-ai/ccpm.json:

• Remove apis/libhttpws.lua from files.
• Bump the trapos-ai package version because runtime behavior/help changes.

Update packages/index.json:

• Mirror the new trapos-ai version.

No trapos-cloud package bump is required unless its behavior changes during cleanup.

Documentation Cleanup

Required Docs

• DEVELOPMENT.md: update just clean description so it no longer mentions mcp-bridge.
• docs/public-ports.md: remove the old 4243 / CC_LINK_PORT ComputerCraft bridge entry, unless a new service explicitly claims that port later.
• docs/adrs/adr-0019-mcp-over-cloud-gateway.md: replace the statement that tools/mcp-bridge is kept for the opencode proxy with a note that it has been removed and the proxy was intentionally dropped pending a future rewrite.
• docs/adrs/adr-0016-js-tool-verification.md: replace tools/mcp-bridge as the JS tool verification example with tools/trapos-server.

Historical / Optional Cleanup

• docs/adrs/adr-0017-mcp-remote-lua-execution.md: this is historical; either leave it as-is or add a short superseded note pointing to ADR-0019.
• .opencode/agent/atm10-expert.md: update old computercraft-mcp-bridge_* permission names if they are still relevant.
• .plans/archived/*: leave old references as archived history unless doing a full text cleanup pass.

Files Expected To Change

• Delete: tools/mcp-bridge/
• Delete: packages/trapos-ai/apis/libhttpws.lua
• Modify: packages/trapos-ai/apis/libai.lua
• Modify: packages/trapos-ai/programs/ai.lua
• Modify: packages/trapos-ai/tests/ai.lua
• Modify: just/npm.just
• Modify: just/install.just
• Modify: just/test.just
• Modify: packages/trapos-ai/ccpm.json
• Modify: packages/index.json
• Modify: DEVELOPMENT.md
• Modify: docs/public-ports.md
• Modify: docs/adrs/adr-0019-mcp-over-cloud-gateway.md
• Modify: docs/adrs/adr-0016-js-tool-verification.md
• Optional: docs/adrs/adr-0017-mcp-remote-lua-execution.md
• Optional: .opencode/agent/atm10-expert.md

Verification

After implementation:

1. Run just check.
2. Run just test.
3. Run just npm-test-integration if not already covered by the selected test target.
4. Optionally run full just ci before merging.

Expected result:

• No recipe references tools/mcp-bridge.
• No package descriptor references apis/libhttpws.lua.
• No source file references require('/apis/libhttpws'), opencc.bridge_url, or opencc.request_timeout_seconds except archived history or generated/local CraftOS state.
• ai works only through direct HTTP/HTTPS opencc.server_url.
• MCP tools continue to work through tools/trapos-server.