Skip to content

loom install --client opencode writes OpenCode's MCP entry - #986

Open
rahulsjha wants to merge 3 commits into
ClickHouse:mainfrom
rahulsjha:feat/install-client-opencode
Open

rahulsjha wants to merge 3 commits into
ClickHouse:mainfrom
rahulsjha:feat/install-client-opencode

Conversation

@rahulsjha

Copy link
Copy Markdown
Contributor

Closes #722.

loom install --client opencode writes Loom's entry into OpenCode's global config, merging with what is there, and the dashboard's token dialog offers OpenCode too.

What it writes

{
  "mcp": {
    "servers": {
      "loom": {
        "type": "remote",
        "url": "https://loom.example.com/mcp?toolset=coding",
        "headers": { "Authorization": "Bearer <token>" }
      }
    }
  }
}
  • Where. OpenCode 2.3.0 roots its global config at $XDG_CONFIG_HOME, else ~/.config, on every platform, Windows included (packages/util/src/global-roots.ts). $OPENCODE_CONFIG_DIR overrides the directory. opencode mcp add --global (packages/cli/src/commands/handlers/mcp/add.ts) writes the first of opencode.json, opencode.jsonc, .opencode/opencode.json and .opencode/opencode.jsonc that exists there, and creates opencode.json when none does. loom install follows the same order, so with only opencode.jsonc present it merges into that file and creates no opencode.json.
  • JSONC. The file is merged in place with the editor Zed's install already uses (server/cli/jsonc_edit.py). It now takes a path of sections (upsert_nested_key(text, ("mcp", "servers"), name, entry)), inserting mcp or servers when either is missing. Comments and trailing commas stay, and an entry already equal leaves the file byte for byte. A file it cannot merge is left as it is, and the entry to paste is printed.
  • Versions. OpenCode 2.x reads servers from mcp.servers, the shape written here. The npm opencode-ai 1.x package reads them from mcp directly and does not see this entry. The docs say so.
  • No oauth key. The issue asked whether to set "oauth": false. The entry leaves it out, so it is exactly what opencode mcp add loom --url URL --header "Authorization=Bearer <JWT>" writes (compared below), and OpenCode's OAuth setting stays at its default. I tried both against a server with LOOM_OAUTH_ENABLED=true and saw no difference in opencode mcp list. The caveat below explains why that run doesn't settle it either way.
  • Toolset. OpenCode is a coding agent, so it joins CODING_CLIENTS / CODING_TOOLSET_CLIENTS and its URL carries ?toolset=coding.
  • Detection. loom install with no --client wires OpenCode when its config directory exists.

Files

  • server/identity/app/token_clients.py: the opencode CONFIG_PATHS row, config_path_keys() (("mcp", "servers") for OpenCode, one key for the rest), the entry, and client_config() nesting the block. config_key() still returns the top-level key.
  • server/cli/install.py: _opencode_config_path(). _install_zed is now _install_jsonc(client, …, sections) and serves Zed and OpenCode.
  • server/cli/jsonc_edit.py: upsert_nested_key. upsert_object_key calls it with one section, so Zed's behaviour is unchanged.
  • frontend/src/lib/clients.ts and clientSetups.fixture.json: OpenCode in ClientId, CLIENTS and CODING_TOOLSET_CLIENTS, and the nested mcp.servers block with a type: "remote" entry in formatMcpConfig(). The fixture rows come from client_config().
  • Tests:
    • test_cli_install.py: 6 OpenCode tests covering a write and rewrite that keep other servers and top-level keys, creating the nesting, a .jsonc-only config merged with its comments and trailing commas and no opencode.json created, the refusal message, path lookup and env vars, and loom install with no --client.
    • test_token_mint.py: OpenCode added to the client set.
    • cli_tree.json and cli_help.json: regenerated with LOOM_UPDATE_CLI_SNAPSHOT=1.
  • Docs:
    • mcp-clients.md: the --client and --toolset rows, "Plugin or plain MCP", "What it writes per client", the merge note, and the OpenCode row under other editors.
    • connect-a-coding-agent.md, integrations/index.md and quickstart.md.

Checks (Linux containers)

  • pytest tests/unit/test_token_clients.py test_cli_install.py test_token_mint.py test_cli_surface_snapshot.py: 141 passed, on the final head too.
  • ruff check, ruff format --check, the function-length gate (54, at its baseline) and the mypy gate (0 new errors): pass.
  • pytest tests/unit/test_doc_links.py tests/unit/test_public_copy.py: 267 passed. scripts.codegen.docs_reference --check: current.
  • npm test (vitest, node 24): 317 files and 3687 tests passed, including the fixture parity test for opencode. npm run build: built. On the final head, clients.test.ts (47 tests) and tsc -b pass again. Biome format and lint: clean.
  • Not run locally: npm run e2e (Playwright). This machine was short on memory, so I'm leaving it to CI's frontend-e2e job.

Real OpenCode 2.3.0 against a local Loom

Local Loom from source on this branch (ClickHouse 26.10 with the repo's deploy/clickhouse-config, auth on, the local embedder), with a minted writer token and OpenCode 2.3.0 (opencode-linux-x64).

Same file as opencode mcp add. Each command wrote to its own empty $XDG_CONFIG_HOME:

$ opencode mcp add loom --global --url "http://127.0.0.1:7777/mcp?toolset=coding" --header "Authorization=Bearer <token>"
MCP server "loom" added to /tmp/tmp.PxskChECHC/opencode/opencode.json
$ loom install --client opencode --server-url http://127.0.0.1:7777 --token <token>
✓ opencode: wrote loom → /tmp/tmp.3cs7MB71Tg/opencode/opencode.json

Both files hold the mcp.servers.loom entry shown above. At the time of that run, loom install also added "oauth": false, which this PR no longer writes.

Auto-detection. loom install with no --client, in a home where only ~/.config/opencode/ exists:

Auto-detected client(s): opencode
✓ opencode: wrote loom → …/.config/opencode/opencode.json

opencode mcp list (caveat).

  • In one run, against a server with LOOM_OAUTH_ENABLED=true, it printed ✓ loom connected for the written entry, both with and without "oauth": false.
  • In the same container I could not make the result follow the config directory I pointed it at. It printed No MCP servers configured for the entry OpenCode's own mcp add had just written, and connected for an entry with a rejected token.
  • In 2.3.0, mcp list asks a background OpenCode server (ServerConnection.resolve()) rather than reading the file, so I think one server was reused across my calls, each with a different XDG_CONFIG_HOME.
  • So I'm not claiming this as a clean check. If you have a one-config setup, opencode mcp list there is the check that counts.

OpenCode 2.x reads its servers from mcp.servers in ~/.config/opencode/opencode.json
(or opencode.jsonc). loom install merges a remote entry with the bearer header and
oauth: false there, keeping the file's comments and trailing commas, and the token
dialog offers OpenCode too. The JSONC editor now places a key under a nested path.

Signed-off-by: Rahul <132360698+rahulsjha@users.noreply.github.com>
No oauth: false. A run with OpenCode 2.3.0 showed no difference with or without it, and
the entry now matches opencode mcp add --url … --header … key for key.

Signed-off-by: Rahul <132360698+rahulsjha@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 17:01

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@zlareb1 zlareb1 self-assigned this Nov 19, 2026

@zlareb1 zlareb1 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No blocking findings. Checked nested configuration writes, JSONC preservation, client detection, token setup and dashboard parity against the documented V2 configuration. All 141 focused client, installer, token and CLI snapshot tests pass.

@zlareb1 zlareb1 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The JSONC editor retains a compatibility entry point with only a unit-test caller. Remove it and exercise the nested editor directly in that test.

Comment thread server/cli/jsonc_edit.py Resolved
The installer calls upsert_nested_key directly. The one test that still used
the wrapper now calls upsert_nested_key with a one-section path, and the nested
editor's docstring carries the contract on its own.

Signed-off-by: Rahul <132360698+rahulsjha@users.noreply.github.com>

@zlareb1 zlareb1 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The unused JSONC wrapper is removed, and its rejection test calls the nested editor directly. No further blocking findings after checking configuration paths, nested writes, token setup and dashboard parity. All 141 focused installer, client, token and CLI snapshot tests pass.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

loom install --client opencode writes OpenCode's MCP entry

3 participants