174 lines
6.4 KiB
Markdown
174 lines
6.4 KiB
Markdown
# 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/trap-sandbox` and `.mcp.json` already points at
|
|
the sandbox 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/trap-sandbox` 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/trap-sandbox`; the proxy
|
|
behavior is intentionally removed.
|
|
- Keep `tools/trap-sandbox/test/` and `tools/trap-sandbox/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/trap-sandbox`:
|
|
- `npm-install`
|
|
- `npm-build`
|
|
- `npm-check`
|
|
- `npm-test`
|
|
- `npm-test-integration`
|
|
|
|
### `just/install.just`
|
|
|
|
- Change `clean` to clean `tools/trap-sandbox` 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
|
|
sandbox 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-sandbox` 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-sandbox-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/trap-sandbox`.
|
|
|
|
### 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-sandbox-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/trap-sandbox`.
|