# 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`.