From ec47b8f239cd65e12b4965cd4031b3029bbc05e5 Mon Sep 17 00:00:00 2001 From: Rahul <132360698+rahulsjha@users.noreply.github.com> Date: Thu, 19 Nov 2026 21:16:35 +0530 Subject: [PATCH 1/5] feat(cli): loom install --client opencode writes OpenCode's MCP entry 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> --- docs/features/integrations/index.md | 2 +- docs/features/integrations/mcp-clients.md | 152 ++++++++------- .../getting-started/connect-a-coding-agent.md | 4 +- docs/getting-started/quickstart.md | 2 +- frontend/src/lib/clientSetups.fixture.json | 60 ++++++ frontend/src/lib/clients.ts | 25 ++- server/cli/install.py | 83 ++++++-- server/cli/jsonc_edit.py | 56 ++++-- server/identity/app/token_clients.py | 40 +++- tests/unit/snapshots/cli_help.json | 4 +- tests/unit/snapshots/cli_tree.json | 5 +- tests/unit/test_cli_install.py | 180 ++++++++++++++++++ tests/unit/test_token_mint.py | 1 + 13 files changed, 488 insertions(+), 126 deletions(-) diff --git a/docs/features/integrations/index.md b/docs/features/integrations/index.md index 436f7d597d..9cc7d425a6 100644 --- a/docs/features/integrations/index.md +++ b/docs/features/integrations/index.md @@ -18,7 +18,7 @@ a bare ClickHouse service is a complete deployment). They fall into three groups | Claude Code | plugin: MCP tools, hooks, code shunt, skills | `integrations/claude-code-plugin/`: [claude-code.md](claude-code.md) | | Codex | plugin: MCP tools, hooks, code shunt, skills | `integrations/codex-plugin/`: [codex.md](codex.md) | | Hermes (experimental) | native memory provider: model-selected recall and fact writes; live server qualification pending | [source setup](../../../integrations/hermes-memory/README.md) | -| Claude Desktop, Cursor, VS Code, Cline, Windsurf, Zed, Gemini CLI | MCP client config | `loom install --client …`: [mcp-clients.md](mcp-clients.md) | +| Claude Desktop, Cursor, VS Code, Cline, Windsurf, Zed, Gemini CLI, OpenCode | MCP client config | `loom install --client …`: [mcp-clients.md](mcp-clients.md) | | VS Code agent mode | MCP tools | install links and `mcp.json`: [vscode.md](vscode.md) | | Any MCP client without a plugin | an instruction block for the client's rule file | [agent-instructions.md](agent-instructions.md) | | Gemini CLI | extension: MCP tools and the `loom`, `loom-code` skills | `gemini extensions install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 2d9983cac3..682e6f210b 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -9,20 +9,20 @@ path as `POST /v1/`. The protocol is in the [MCP reference](../../reference/ ## Plugin or plain MCP -| You run | Use | You get | -| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| Claude Code | the [Claude Code plugin](claude-code.md) | tools, capture hooks, code shunt, skills, the code-scope header | -| Codex | the [Codex plugin](codex.md) | the same, with Codex wiring | -| Cursor | the [Cursor plugin](cursor.md#plugin) (untested in Cursor) or `loom install --client cursor` | the tools; the `loom` and `loom-code` skills from the plugin; capture through the [`sessionEnd` hook](cursor.md#transcript-capture) you register | -| Claude Desktop, VS Code, Cline, Windsurf, Zed, Gemini CLI | `loom install --client ` ([below](#wire-a-client-with-loom-install)) | the tools; capture only through a [transcript template](index.md#transcript-capture-hooks) | -| an orchestrator running several agents | one MCP mount per agent ([frameworks.md](frameworks.md)) | shared memory across the agents | +| You run | Use | You get | +| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Claude Code | the [Claude Code plugin](claude-code.md) | tools, capture hooks, code shunt, skills, the code-scope header | +| Codex | the [Codex plugin](codex.md) | the same, with Codex wiring | +| Cursor | the [Cursor plugin](cursor.md#plugin) (untested in Cursor) or `loom install --client cursor` | the tools; the `loom` and `loom-code` skills from the plugin; capture through the [`sessionEnd` hook](cursor.md#transcript-capture) you register | +| Claude Desktop, VS Code, Cline, Windsurf, Zed, Gemini CLI, OpenCode | `loom install --client ` ([below](#wire-a-client-with-loom-install)) | the tools; capture only through a [transcript template](index.md#transcript-capture-hooks) | +| an orchestrator running several agents | one MCP mount per agent ([frameworks.md](frameworks.md)) | shared memory across the agents | A plain MCP entry gives the tools only: no session capture, primer or code shunt. Loom still records an implicit run per MCP session and names the agent after the client's `clientInfo.name` (`Cursor` becomes `cursor`). To teach the agent when to call the tools, add the [agent instructions](agent-instructions.md) block to a coding client's rule file, with `?toolset=coding` on the entry's URL (`--toolset coding` with `loom install`, the -default only for Claude Code, Codex, Cursor and Gemini CLI). +default only for Claude Code, Codex, Cursor, Gemini CLI and OpenCode). ## Wire a client with `loom install` @@ -33,15 +33,15 @@ and Codex, runs their `mcp add` command: loom install --client cursor --server-url https://loom.example.com --token "$LOOM_API_KEY" ``` -| Flag | Default | Meaning | -| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `--client` | every supported client whose config directory exists (Gemini CLI: its `settings.json` or the `gemini` binary, since Google Antigravity also creates `~/.gemini/`) | one or more of `claude-desktop`, `claude-code`, `codex`, `cursor`, `vscode`, `cline`, `windsurf`, `zed`, `gemini` | -| `--server-url` | `LOOM_BASE_URL`, then `~/.loom/config.json`, else `http://localhost:7777` | the Loom base URL; the entry points at `/mcp` | -| `--token` | `LOOM_API_KEY`, then `~/.loom/config.json`, then `~/.loom/token` | the JWT the entry authenticates with; required | -| `--name` | `loom` | the server key in the config file, and the name `claude mcp add` / `codex mcp add` registers | -| `--toolset` | empty: `coding` for Claude Code, Codex, Cursor and Gemini CLI, else the server default (`LOOM_MCP_TOOLSET`) | appended as `?toolset=`; a toolset name or a `+` union of curated rosters such as `coding+tracker`; anything else is rejected before writing | -| `--dry-run` | off | print what would be written or run, touching nothing | -| `--force` | off | Claude Code only: add the user-scope entry even when the `loom` plugin is installed | +| Flag | Default | Meaning | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `--client` | every supported client whose config directory exists (Gemini CLI: its `settings.json` or the `gemini` binary, since Google Antigravity also creates `~/.gemini/`; OpenCode: `~/.config/opencode/`) | one or more of `claude-desktop`, `claude-code`, `codex`, `cursor`, `vscode`, `cline`, `windsurf`, `zed`, `gemini`, `opencode` | +| `--server-url` | `LOOM_BASE_URL`, then `~/.loom/config.json`, else `http://localhost:7777` | the Loom base URL; the entry points at `/mcp` | +| `--token` | `LOOM_API_KEY`, then `~/.loom/config.json`, then `~/.loom/token` | the JWT the entry authenticates with; required | +| `--name` | `loom` | the server key in the config file, and the name `claude mcp add` / `codex mcp add` registers | +| `--toolset` | empty: `coding` for Claude Code, Codex, Cursor, Gemini CLI and OpenCode, else the server default (`LOOM_MCP_TOOLSET`) | appended as `?toolset=`; a toolset name or a `+` union of curated rosters such as `coding+tracker`; anything else is rejected before writing | +| `--dry-run` | off | print what would be written or run, touching nothing | +| `--force` | off | Claude Code only: add the user-scope entry even when the `loom` plugin is installed | Restart the client afterwards. Exit codes: `2` no token, `5` no client detected, `1` any client failed (the others still run). See the [CLI reference](../../reference/cli.md). @@ -54,22 +54,30 @@ that only reads can use a `viewer` token; see ### What it writes per client -| Client | Config file (Linux; macOS and Windows use the platform equivalent) | Section | Entry shape | -| ---------------- | ------------------------------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | -| `claude-desktop` | `~/.config/Claude/claude_desktop_config.json` | `mcpServers` | `npx mcp-remote` bridge | -| `cursor` | `~/.cursor/mcp.json` | `mcpServers` | `url` + `headers` | -| `vscode` | `~/.config/Code/User/mcp.json` (a separate file, so `settings.json` is left alone) | `servers` | `url` + `headers` + `type: "http"` | -| `cline` | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | `mcpServers` | `npx mcp-remote` bridge | -| `windsurf` | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | `url` + `headers` | -| `zed` | `~/.config/zed/settings.json` | `context_servers` | `url` + `headers` | -| `gemini` | `~/.gemini/settings.json` | `mcpServers` | `httpUrl` + `headers` (Gemini CLI reads streamable HTTP from `httpUrl`) | -| `claude-code` | none: runs `claude mcp add … -s user` | | see [Claude Code](#claude-code-without-the-plugin) | -| `codex` | none: runs `codex mcp add` | | see [Codex](#codex-without-the-plugin) | +| Client | Config file (Linux; macOS and Windows use the platform equivalent) | Section | Entry shape | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | +| `claude-desktop` | `~/.config/Claude/claude_desktop_config.json` | `mcpServers` | `npx mcp-remote` bridge | +| `cursor` | `~/.cursor/mcp.json` | `mcpServers` | `url` + `headers` | +| `vscode` | `~/.config/Code/User/mcp.json` (a separate file, so `settings.json` is left alone) | `servers` | `url` + `headers` + `type: "http"` | +| `cline` | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | `mcpServers` | `npx mcp-remote` bridge | +| `windsurf` | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | `url` + `headers` | +| `zed` | `~/.config/zed/settings.json` | `context_servers` | `url` + `headers` | +| `gemini` | `~/.gemini/settings.json` | `mcpServers` | `httpUrl` + `headers` (Gemini CLI reads streamable HTTP from `httpUrl`) | +| `opencode` | `~/.config/opencode/opencode.json`, or `opencode.jsonc` when that is the file there (`$OPENCODE_CONFIG_DIR` or `$XDG_CONFIG_HOME/opencode` when set) | `mcp.servers` | `type: "remote"` + `url` + `headers` + `oauth: false` | +| `claude-code` | none: runs `claude mcp add … -s user` | | see [Claude Code](#claude-code-without-the-plugin) | +| `codex` | none: runs `codex mcp add` | | see [Codex](#codex-without-the-plugin) | The file is replaced atomically with mode 0600; every other key is kept. A file that is not a valid JSON object is refused, not overwritten. A file that holds `//` or `/* */` comments (Gemini CLI allows them in `settings.json`) is refused as well, since a rewrite -would drop them, and the entry to paste is printed with the token as ``. +would drop them, and the entry to paste is printed with the token as ``. Zed's +`settings.json` and OpenCode's `opencode.json` or `opencode.jsonc` are merged in place +instead: the entry is spliced in and the file's comments and trailing commas stay; a file +that cannot be merged that way is left as it is and the entry to paste is printed. +OpenCode 2.x reads servers from `mcp.servers`, the shape written here; the 1.x +`opencode-ai` npm package reads them from `mcp` directly and does not see this entry. +The entry sets `"oauth": false`, so OpenCode sends the token rather than starting its +OAuth flow when the server also offers OAuth (`LOOM_OAUTH_ENABLED`). Zed reads `context_servers` from `settings.json`. On macOS that file is `~/.config/zed/settings.json`, the same path as on Linux. On Windows it is @@ -193,49 +201,49 @@ a single-user server on the same machine (no header needed) or uses the code index ([choosing a toolset](#choosing-a-toolset)). Restart or reload the client afterwards. -| Client | Where | Entry | Checked | -| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | -| JetBrains AI Assistant (IntelliJ IDEA, PyCharm, WebStorm, GoLand) | Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add | `{"mcpServers": {"loom": {"url": "URL"}}}` (single-user server only: no header field or sign-in is documented) | | -| JetBrains Junie | `~/.junie/mcp/mcp.json`, or `.junie/mcp/mcp.json` in the project | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | installed (26.11.1); MCP status unmeasured | -| Visual Studio (Copilot agent mode) | `%USERPROFILE%\.mcp.json`, or `.mcp.json` in the solution | `{"servers": {"loom": {"type": "http", "url": "URL", "headers": {…}}}}` (Visual Studio also reads `.vscode/mcp.json`) | | -| Kiro | `~/.kiro/settings/mcp.json`, or `.kiro/settings/mcp.json`; Kiro CLI reads the same `~/.kiro/settings/mcp.json` as the Kiro IDE (and copies `~/.aws/amazonq/mcp.json` there once, when Kiro CLI is installed, skipping servers that conflict with ones already there) | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` (Kiro documents that it expands a `${LOOM_API_KEY}` placeholder only for a variable listed in the **Mcp Approved Env Vars** setting); for a single-user server, an install link `https://kiro.dev/launch/mcp/add?name=loom&config=` | installed (CLI 3.3.0); `mcp list` requires login | -| Gemini CLI | `~/.gemini/settings.json`, or `.gemini/settings.json` | `{"mcpServers": {"loom": {"httpUrl": "URL", "headers": {…}}}}`, or `gemini mcp add --transport http --header "Authorization: Bearer " loom URL` (drop `--header` for a single-user server); or the extension, below; Gemini lists a server as disabled in a folder it does not trust | connected (`gemini mcp add`, and the extension) | -| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | `{"mcpServers": {"loom": {"type": "http", "url": "URL", "headers": {…}, "tools": ["*"]}}}`; or the plugin, below | accepted | -| Neovim with mcphub.nvim (also serves avante.nvim and CodeCompanion) | `~/.config/mcphub/servers.json` | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | | -| Emacs with mcp.el and gptel | `mcp-hub-servers` in your init file, then `gptel-mcp-connect` | `(setq mcp-hub-servers '(("loom" . (:url "URL"))))` (single-user server only: no header field is documented) | | -| OpenCode | `opencode.json` or `.opencode/opencode.json` in the project or a folder above it, or `~/.config/opencode/opencode.json` | `opencode mcp add loom --url URL --header "Authorization=Bearer "`, which in OpenCode 2.x writes `{"mcp": {"servers": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}}`; the 1.x `opencode-ai` npm package takes `{"mcp": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}`, which 2.x still reads | connected | -| Kilo Code (extension and CLI) | `kilo.jsonc` in the project, or `~/.config/kilo/kilo.jsonc` | `{"mcp": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}` | connected (CLI) | -| Cline CLI | `~/.cline/data/settings/cline_mcp_settings.json` | `cline mcp add loom URL --transport http --header "Authorization: Bearer " --yes` (the Cline extension: [`loom install`](#what-it-writes-per-client)) | accepted | -| Google Antigravity | `~/.gemini/config/mcp_config.json`, or `.agents/mcp_config.json` in the workspace | `{"mcpServers": {"loom": {"serverUrl": "URL", "headers": {…}}}}` (`url` also works) | | -| Devin Desktop and Devin CLI | `.devin/mcp_config.local.json` in the project (git-ignored, for the token), or `~/.config/devin/mcp_config.json` | `{"mcpServers": {"loom": {"url": "URL", "transport": "http", "headers": {…}}}}` (`loom install --client windsurf` writes the older `~/.codeium/windsurf/` path) | accepted (CLI 3000.12.57 configuration only); Desktop unmeasured | -| Qwen Code | `~/.qwen/settings.json`, or `.qwen/settings.json` | `qwen mcp add --transport http loom URL --header "Authorization: Bearer "` | connected (`qwen mcp list`) | -| Kimi Code CLI | `~/.kimi-code/mcp.json`, or `.kimi-code/mcp.json` in the working directory (read once the folder is trusted); or `/mcp-config` in the TUI | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}`, or `"bearerTokenEnvVar": "LOOM_API_KEY"` in place of `headers` | installed (2.5.3); MCP status unmeasured | -| Grok Build | `~/.grok/config.toml`, or `.grok/config.toml`; below those it also reads a project `.mcp.json`, `~/.claude.json` and `.cursor/mcp.json`, so an existing Claude Code or Cursor entry is picked up (`[compat.claude] mcps = false` and `[compat.cursor] mcps = false` turn that off) | `grok mcp add --transport http loom URL --header "Authorization: Bearer "` | accepted (1.0.77); connection unmeasured | -| Qoder CLI and IDE | CLI: `~/.qoder/settings.json`, `.qoder/settings.json`, or a project `.mcp.json`; IDE: Settings → MCP → My Servers → Add (its docs show no header field: single-user server) | `qodercli mcp add -t http -s user loom URL` (single-user server), or `{"mcpServers": {"loom": {"type": "http", "url": "URL", "headers": {…}}}}` | CLI accepted (1.1.90); connection unmeasured | -| Qoder CN CLI | `~/.qoder-cn/settings.json` | `qoderclicn mcp add -t http -s user loom URL` (single-user server); native HTTP entries use `mcpServers` with `url` and optional `headers` | accepted (1.1.90); connection unmeasured | -| Muse Code | `~/.config/muse/settings.json` | `muse mcp add loom --url URL --user`; add `--bearer-token-env-var LOOM_API_KEY` for a team server with the raw token in that environment variable | accepted (1.4.20), without token; connection unmeasured | -| MiniMax Code | `~/.minimax/mcp.json`, or the MCP Servers tab | `{"mcpServers": {"loom": {"type": "streamable-http", "url": "URL", "headers": {…}}}}` | installed (mcode 0.7.7); MCP status unmeasured | -| goose | `~/.config/goose/config.yaml`, under `extensions` | `goose configure` → Add Extension → Remote Extension (Streamable HTTP), then add the `Authorization` header when asked; or, in the file, `loom: {type: streamable_http, name: loom, enabled: true, uri: URL, headers: {Authorization: "Bearer "}}` | starts (`goose doctor`) | -| Amp | `~/.config/amp/settings.json`, or `.amp/settings.json`, under `amp.mcpServers` | `amp mcp add loom --header "Authorization=Bearer " URL`, which writes `{"loom": {"url": "URL", "headers": {…}}}` | accepted (`amp mcp list`; `amp mcp doctor` needs a sign-in) | -| Warp desktop | `~/.warp/.mcp.json`, `.warp/.mcp.json` in the project (a project server needs approval), or Settings → Agents → MCP servers | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | | -| Factory droid | `~/.factory/mcp.json` | `droid mcp add loom URL --type http --header "Authorization: Bearer " --no-oauth` | connected (`droid mcp list`) | -| Augment (Auggie CLI) | `~/.augment/settings.json` (`--project` writes `.augment/settings.json`) | `auggie mcp add loom --transport http --url URL --header "Authorization:Bearer "` | accepted (`auggie mcp list` does not probe the URL) | -| Hermes Agent | `~/.hermes/config.yaml`, under `mcp_servers` | `hermes mcp add loom --url URL --auth header`, which asks for the token, saves it to `~/.hermes/.env` as `MCP_LOOM_API_KEY` and writes the header as `Bearer ${MCP_LOOM_API_KEY}`; or `loom: {url: URL, headers: {Authorization: "Bearer "}}` in the file | connected (`hermes mcp test loom`) | -| Zed | `context_servers` in `settings.json` | `{"context_servers": {"loom": {"url": "URL", "headers": {…}}}}` ([`loom install`](#what-it-writes-per-client)) | | -| OpenHands cloud UI | Customize → MCP Servers | transport SHTTP, the URL, Authentication `Bearer token` with the token in the API key field | | -| n8n | an MCP Client Tool node on an AI Agent node | **Endpoint** = URL, Server Transport HTTP Streamable, Authentication Bearer Auth, with the token in a new Bearer Auth credential | | -| smolagents (Python) | code | `MCPClient({"url": URL, "transport": "streamable-http", "headers": {…}})`; `ToolCollection.from_mcp` takes the same dict with `trust_remote_code=True` (smolagents 1.26 needs `mcp<2`: its MCP adapter does not load with `mcp` 2) | connected (`MCPClient` listed the tools) | -| OpenClaw | `~/.openclaw/openclaw.json`, under `mcp.servers` | `openclaw mcp set loom '{"url": "URL", "transport": "streamable-http", "headers": {…}}'` | connected (`openclaw mcp probe`) | -| Strix | `~/.strix/mcp-servers.json` (a JSON list), or `--mcp-config ` | `[{"name": "loom", "transport": "http", "url": "URL", "auth": {"kind": "bearer", "token": ""}}]` | connected (Strix's MCP client listed the tools; no status command) | -| Open WebUI | Admin Panel → Settings → Integrations → External Tool Servers → + Add Connection | Type MCP (Streamable HTTP), the URL, Auth Bearer with the bare token as the key (Open WebUI adds `Bearer`) | | -| LibreChat v0.8.8 | a `librechat.yaml` `mcpServers` entry | `type: streamable-http`, `url: /mcp?toolset=assistant`, `headers: {Authorization: "Bearer {{LOOM_TOKEN}}"}` with `LOOM_TOKEN` declared under `customUserVars`, so each person enters their own token; see [LibreChat](librechat.md) | qualified ([cases](librechat.md#qualification)) | -| Continue (no longer actively maintained) | a YAML file in `.continue/mcpServers/` in the workspace | `mcpServers: [{name: loom, type: streamable-http, url: URL, requestOptions: {headers: {Authorization: "Bearer "}}}]`, with the file's `name`, `version` and `schema` fields | | -| Cherry Studio | Settings → MCP, added by JSON import | `{"mcpServers": {"loom": {"type": "streamableHttp", "url": "URL", "headers": {…}}}}`; Cherry Studio switches an imported server on, and hovering the error dot on its server card shows why a connection failed | | -| LM Studio | `mcp.json`, opened from the Program tab → Install → Edit mcp.json | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | | -| Jan | the Jan Agent CLI | `jan cli mcp add loom --type http --url URL --header "Authorization=Bearer " --active` | | -| Crush | `.crushrc` or `crushrc` in the project, or `~/.config/crush/crushrc` (there is no `crush mcp add` command) | `mcp add loom --type http --url URL --header Authorization "Bearer "` | | -| Mistral Vibe | `~/.vibe/config.toml` | `[[mcp_servers]]` with `name = "loom"`, `transport = "streamable-http"`, `url = "URL"`, then `[mcp_servers.auth]` with `type = "static"`, `api_key_env = "LOOM_API_KEY"`, `api_key_header = "Authorization"`, `api_key_format = "Bearer {token}"` | | -| Amazon Q Developer (IDE plugins) | Q Developer chat panel → tools icon → **+**; saved to `~/.aws/amazonq/default.json`, or `.amazonq/default.json` in the project | transport `http`, the URL, and the `Authorization` header under Headers | | +| Client | Where | Entry | Checked | +| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| JetBrains AI Assistant (IntelliJ IDEA, PyCharm, WebStorm, GoLand) | Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add | `{"mcpServers": {"loom": {"url": "URL"}}}` (single-user server only: no header field or sign-in is documented) | | +| JetBrains Junie | `~/.junie/mcp/mcp.json`, or `.junie/mcp/mcp.json` in the project | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | installed (26.11.1); MCP status unmeasured | +| Visual Studio (Copilot agent mode) | `%USERPROFILE%\.mcp.json`, or `.mcp.json` in the solution | `{"servers": {"loom": {"type": "http", "url": "URL", "headers": {…}}}}` (Visual Studio also reads `.vscode/mcp.json`) | | +| Kiro | `~/.kiro/settings/mcp.json`, or `.kiro/settings/mcp.json`; Kiro CLI reads the same `~/.kiro/settings/mcp.json` as the Kiro IDE (and copies `~/.aws/amazonq/mcp.json` there once, when Kiro CLI is installed, skipping servers that conflict with ones already there) | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` (Kiro documents that it expands a `${LOOM_API_KEY}` placeholder only for a variable listed in the **Mcp Approved Env Vars** setting); for a single-user server, an install link `https://kiro.dev/launch/mcp/add?name=loom&config=` | installed (CLI 3.3.0); `mcp list` requires login | +| Gemini CLI | `~/.gemini/settings.json`, or `.gemini/settings.json` | `{"mcpServers": {"loom": {"httpUrl": "URL", "headers": {…}}}}`, or `gemini mcp add --transport http --header "Authorization: Bearer " loom URL` (drop `--header` for a single-user server); or the extension, below; Gemini lists a server as disabled in a folder it does not trust | connected (`gemini mcp add`, and the extension) | +| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | `{"mcpServers": {"loom": {"type": "http", "url": "URL", "headers": {…}, "tools": ["*"]}}}`; or the plugin, below | accepted | +| Neovim with mcphub.nvim (also serves avante.nvim and CodeCompanion) | `~/.config/mcphub/servers.json` | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | | +| Emacs with mcp.el and gptel | `mcp-hub-servers` in your init file, then `gptel-mcp-connect` | `(setq mcp-hub-servers '(("loom" . (:url "URL"))))` (single-user server only: no header field is documented) | | +| OpenCode | `opencode.json` or `.opencode/opencode.json` in the project or a folder above it, or `~/.config/opencode/opencode.json` | `loom install --client opencode`, or `opencode mcp add loom --url URL --header "Authorization=Bearer "`, which in OpenCode 2.x writes `{"mcp": {"servers": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}}`; the 1.x `opencode-ai` npm package takes `{"mcp": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}`, which 2.x still reads | connected | +| Kilo Code (extension and CLI) | `kilo.jsonc` in the project, or `~/.config/kilo/kilo.jsonc` | `{"mcp": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}` | connected (CLI) | +| Cline CLI | `~/.cline/data/settings/cline_mcp_settings.json` | `cline mcp add loom URL --transport http --header "Authorization: Bearer " --yes` (the Cline extension: [`loom install`](#what-it-writes-per-client)) | accepted | +| Google Antigravity | `~/.gemini/config/mcp_config.json`, or `.agents/mcp_config.json` in the workspace | `{"mcpServers": {"loom": {"serverUrl": "URL", "headers": {…}}}}` (`url` also works) | | +| Devin Desktop and Devin CLI | `.devin/mcp_config.local.json` in the project (git-ignored, for the token), or `~/.config/devin/mcp_config.json` | `{"mcpServers": {"loom": {"url": "URL", "transport": "http", "headers": {…}}}}` (`loom install --client windsurf` writes the older `~/.codeium/windsurf/` path) | accepted (CLI 3000.12.57 configuration only); Desktop unmeasured | +| Qwen Code | `~/.qwen/settings.json`, or `.qwen/settings.json` | `qwen mcp add --transport http loom URL --header "Authorization: Bearer "` | connected (`qwen mcp list`) | +| Kimi Code CLI | `~/.kimi-code/mcp.json`, or `.kimi-code/mcp.json` in the working directory (read once the folder is trusted); or `/mcp-config` in the TUI | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}`, or `"bearerTokenEnvVar": "LOOM_API_KEY"` in place of `headers` | installed (2.5.3); MCP status unmeasured | +| Grok Build | `~/.grok/config.toml`, or `.grok/config.toml`; below those it also reads a project `.mcp.json`, `~/.claude.json` and `.cursor/mcp.json`, so an existing Claude Code or Cursor entry is picked up (`[compat.claude] mcps = false` and `[compat.cursor] mcps = false` turn that off) | `grok mcp add --transport http loom URL --header "Authorization: Bearer "` | accepted (1.0.77); connection unmeasured | +| Qoder CLI and IDE | CLI: `~/.qoder/settings.json`, `.qoder/settings.json`, or a project `.mcp.json`; IDE: Settings → MCP → My Servers → Add (its docs show no header field: single-user server) | `qodercli mcp add -t http -s user loom URL` (single-user server), or `{"mcpServers": {"loom": {"type": "http", "url": "URL", "headers": {…}}}}` | CLI accepted (1.1.90); connection unmeasured | +| Qoder CN CLI | `~/.qoder-cn/settings.json` | `qoderclicn mcp add -t http -s user loom URL` (single-user server); native HTTP entries use `mcpServers` with `url` and optional `headers` | accepted (1.1.90); connection unmeasured | +| Muse Code | `~/.config/muse/settings.json` | `muse mcp add loom --url URL --user`; add `--bearer-token-env-var LOOM_API_KEY` for a team server with the raw token in that environment variable | accepted (1.4.20), without token; connection unmeasured | +| MiniMax Code | `~/.minimax/mcp.json`, or the MCP Servers tab | `{"mcpServers": {"loom": {"type": "streamable-http", "url": "URL", "headers": {…}}}}` | installed (mcode 0.7.7); MCP status unmeasured | +| goose | `~/.config/goose/config.yaml`, under `extensions` | `goose configure` → Add Extension → Remote Extension (Streamable HTTP), then add the `Authorization` header when asked; or, in the file, `loom: {type: streamable_http, name: loom, enabled: true, uri: URL, headers: {Authorization: "Bearer "}}` | starts (`goose doctor`) | +| Amp | `~/.config/amp/settings.json`, or `.amp/settings.json`, under `amp.mcpServers` | `amp mcp add loom --header "Authorization=Bearer " URL`, which writes `{"loom": {"url": "URL", "headers": {…}}}` | accepted (`amp mcp list`; `amp mcp doctor` needs a sign-in) | +| Warp desktop | `~/.warp/.mcp.json`, `.warp/.mcp.json` in the project (a project server needs approval), or Settings → Agents → MCP servers | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | | +| Factory droid | `~/.factory/mcp.json` | `droid mcp add loom URL --type http --header "Authorization: Bearer " --no-oauth` | connected (`droid mcp list`) | +| Augment (Auggie CLI) | `~/.augment/settings.json` (`--project` writes `.augment/settings.json`) | `auggie mcp add loom --transport http --url URL --header "Authorization:Bearer "` | accepted (`auggie mcp list` does not probe the URL) | +| Hermes Agent | `~/.hermes/config.yaml`, under `mcp_servers` | `hermes mcp add loom --url URL --auth header`, which asks for the token, saves it to `~/.hermes/.env` as `MCP_LOOM_API_KEY` and writes the header as `Bearer ${MCP_LOOM_API_KEY}`; or `loom: {url: URL, headers: {Authorization: "Bearer "}}` in the file | connected (`hermes mcp test loom`) | +| Zed | `context_servers` in `settings.json` | `{"context_servers": {"loom": {"url": "URL", "headers": {…}}}}` ([`loom install`](#what-it-writes-per-client)) | | +| OpenHands cloud UI | Customize → MCP Servers | transport SHTTP, the URL, Authentication `Bearer token` with the token in the API key field | | +| n8n | an MCP Client Tool node on an AI Agent node | **Endpoint** = URL, Server Transport HTTP Streamable, Authentication Bearer Auth, with the token in a new Bearer Auth credential | | +| smolagents (Python) | code | `MCPClient({"url": URL, "transport": "streamable-http", "headers": {…}})`; `ToolCollection.from_mcp` takes the same dict with `trust_remote_code=True` (smolagents 1.26 needs `mcp<2`: its MCP adapter does not load with `mcp` 2) | connected (`MCPClient` listed the tools) | +| OpenClaw | `~/.openclaw/openclaw.json`, under `mcp.servers` | `openclaw mcp set loom '{"url": "URL", "transport": "streamable-http", "headers": {…}}'` | connected (`openclaw mcp probe`) | +| Strix | `~/.strix/mcp-servers.json` (a JSON list), or `--mcp-config ` | `[{"name": "loom", "transport": "http", "url": "URL", "auth": {"kind": "bearer", "token": ""}}]` | connected (Strix's MCP client listed the tools; no status command) | +| Open WebUI | Admin Panel → Settings → Integrations → External Tool Servers → + Add Connection | Type MCP (Streamable HTTP), the URL, Auth Bearer with the bare token as the key (Open WebUI adds `Bearer`) | | +| LibreChat v0.8.8 | a `librechat.yaml` `mcpServers` entry | `type: streamable-http`, `url: /mcp?toolset=assistant`, `headers: {Authorization: "Bearer {{LOOM_TOKEN}}"}` with `LOOM_TOKEN` declared under `customUserVars`, so each person enters their own token; see [LibreChat](librechat.md) | qualified ([cases](librechat.md#qualification)) | +| Continue (no longer actively maintained) | a YAML file in `.continue/mcpServers/` in the workspace | `mcpServers: [{name: loom, type: streamable-http, url: URL, requestOptions: {headers: {Authorization: "Bearer "}}}]`, with the file's `name`, `version` and `schema` fields | | +| Cherry Studio | Settings → MCP, added by JSON import | `{"mcpServers": {"loom": {"type": "streamableHttp", "url": "URL", "headers": {…}}}}`; Cherry Studio switches an imported server on, and hovering the error dot on its server card shows why a connection failed | | +| LM Studio | `mcp.json`, opened from the Program tab → Install → Edit mcp.json | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | | +| Jan | the Jan Agent CLI | `jan cli mcp add loom --type http --url URL --header "Authorization=Bearer " --active` | | +| Crush | `.crushrc` or `crushrc` in the project, or `~/.config/crush/crushrc` (there is no `crush mcp add` command) | `mcp add loom --type http --url URL --header Authorization "Bearer "` | | +| Mistral Vibe | `~/.vibe/config.toml` | `[[mcp_servers]]` with `name = "loom"`, `transport = "streamable-http"`, `url = "URL"`, then `[mcp_servers.auth]` with `type = "static"`, `api_key_env = "LOOM_API_KEY"`, `api_key_header = "Authorization"`, `api_key_format = "Bearer {token}"` | | +| Amazon Q Developer (IDE plugins) | Q Developer chat panel → tools icon → **+**; saved to `~/.aws/amazonq/default.json`, or `.amazonq/default.json` in the project | transport `http`, the URL, and the `Authorization` header under Headers | | `{…}` is `{"Authorization": "Bearer "}`; leave it out for a single-user server. In **Checked**: diff --git a/docs/getting-started/connect-a-coding-agent.md b/docs/getting-started/connect-a-coding-agent.md index 1572e64686..81122b5ba2 100644 --- a/docs/getting-started/connect-a-coding-agent.md +++ b/docs/getting-started/connect-a-coding-agent.md @@ -97,7 +97,7 @@ use the [Cursor](../features/integrations/cursor.md#mcp-tools) or [VS Code](../features/integrations/vscode.md#local-single-user-server) install link. Otherwise, in the dashboard, open **Settings → Tokens**, fill in the **New token** form (press **New token** first if a token exists) and press **Create token**, then choose your client (Cursor, VS Code, Cline, -Windsurf, Zed, Gemini CLI or Claude Desktop) under **Connect**: the dialog shows the entry for its +Windsurf, Zed, Gemini CLI, OpenCode or Claude Desktop) under **Connect**: the dialog shows the entry for its config file, with the token in it. For any other MCP client, copy the entry from [MCP clients](../features/integrations/mcp-clients.md). With the `loom` CLI installed (`pip install -e .` from a clone of the repository), one command writes the entry instead: @@ -107,7 +107,7 @@ loom install --client cursor --server-url https://loom.example.com --token "$LOO ``` Restart the client afterwards. `--client` also takes `claude-desktop`, `vscode`, `cline`, -`windsurf`, `zed` and `gemini`; without it, `loom install` wires every client it finds. These clients +`windsurf`, `zed`, `gemini` and `opencode`; without it, `loom install` wires every client it finds. These clients get the tools; transcript capture needs a hook, which [Cursor](../features/integrations/cursor.md) has and the others take from a [transcript template](../features/integrations/index.md#transcript-capture-hooks). [MCP clients](../features/integrations/mcp-clients.md) covers toolsets and the entry the diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 91ec26a9a1..a128a751f4 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -527,7 +527,7 @@ with the token in it. Then: before running the dialog's command, which refuses a name that exists. `loom install --client ` writes the MCP entry for Claude Desktop, Claude Code, -Codex, Cursor, VS Code, Cline, Windsurf, Zed and Gemini CLI; with no flag it wires every client it +Codex, Cursor, VS Code, Cline, Windsurf, Zed, Gemini CLI and OpenCode; with no flag it wires every client it finds. [Connect a coding agent](connect-a-coding-agent.md) covers Codex and Cursor. Start a new session and say _"Remember that I never deploy on Friday."_ The agent calls diff --git a/frontend/src/lib/clientSetups.fixture.json b/frontend/src/lib/clientSetups.fixture.json index fbd3560706..e2f7ce6279 100644 --- a/frontend/src/lib/clientSetups.fixture.json +++ b/frontend/src/lib/clientSetups.fixture.json @@ -143,6 +143,26 @@ "config_toml": "", "command": "", "env": {} + }, + "opencode": { + "config_key": "mcp", + "config": { + "mcp": { + "servers": { + "loom": { + "type": "remote", + "url": "http://x/mcp?toolset=coding", + "headers": { + "Authorization": "Bearer T" + }, + "oauth": false + } + } + } + }, + "config_toml": "", + "command": "", + "env": {} } } }, @@ -290,6 +310,26 @@ "config_toml": "", "command": "", "env": {} + }, + "opencode": { + "config_key": "mcp", + "config": { + "mcp": { + "servers": { + "loom": { + "type": "remote", + "url": "http://x/mcp?a=1&toolset=coding", + "headers": { + "Authorization": "Bearer T" + }, + "oauth": false + } + } + } + }, + "config_toml": "", + "command": "", + "env": {} } } }, @@ -451,6 +491,26 @@ "config_toml": "", "command": "", "env": {} + }, + "opencode": { + "config_key": "mcp", + "config": { + "mcp": { + "servers": { + "loom": { + "type": "remote", + "url": "http://x/mcp?mytoolset=x&toolset=coding", + "headers": { + "Authorization": "Bearer T" + }, + "oauth": false + } + } + } + }, + "config_toml": "", + "command": "", + "env": {} } } } diff --git a/frontend/src/lib/clients.ts b/frontend/src/lib/clients.ts index 1e53c6c0b0..3c0555fd39 100644 --- a/frontend/src/lib/clients.ts +++ b/frontend/src/lib/clients.ts @@ -17,7 +17,8 @@ export type ClientId = | "cline" | "windsurf" | "zed" - | "gemini"; + | "gemini" + | "opencode"; interface MCPClient { id: ClientId; @@ -34,6 +35,7 @@ export const CLIENTS: MCPClient[] = [ { id: "windsurf", label: "Windsurf" }, { id: "zed", label: "Zed" }, { id: "gemini", label: "Gemini CLI" }, + { id: "opencode", label: "OpenCode" }, ]; /** True for a value naming one of CLIENTS — a stored or picked id is checked, not cast. */ @@ -49,7 +51,13 @@ const STDIO_VIA_NPX: ReadonlySet = new Set(["claude-desktop", "cline"] // tools, which the deployment default `core` lists only with LOOM_MCP_CODE_TOOLS. // `?toolset=` rides the URL, so one server serves both. const CODING_TOOLSET = "coding"; -export const CODING_TOOLSET_CLIENTS: ReadonlySet = new Set(["claude-code", "codex", "cursor", "gemini"]); +export const CODING_TOOLSET_CLIENTS: ReadonlySet = new Set([ + "claude-code", + "codex", + "cursor", + "gemini", + "opencode", +]); // Codex reads the bearer from an environment variable it is told the NAME of; // the token itself never sits in ~/.codex/config.toml. @@ -109,7 +117,9 @@ export function formatMcpConfig(args: { client: ClientId; token: string; mcpUrl: ? "context_servers" : args.client === "codex" ? "mcp_servers" - : "mcpServers"; + : args.client === "opencode" + ? "mcp" + : "mcpServers"; const mcpUrl = CODING_TOOLSET_CLIENTS.has(args.client) ? withToolset(args.mcpUrl, CODING_TOOLSET) : args.mcpUrl; @@ -138,12 +148,19 @@ export function formatMcpConfig(args: { client: ClientId; token: string; mcpUrl: if (args.client === "claude-code" || args.client === "vscode") { e.type = "http"; } + if (args.client === "opencode") { + // OpenCode 2.x: a remote server, the bearer header as its credential and no OAuth flow. + return { type: "remote", url: mcpUrl, headers: e.headers, oauth: false }; + } return e; })(); const out: FormattedMcpConfig = { configKey, - block: { [configKey]: { loom: entry } }, + // OpenCode 2.x keeps its servers under `mcp.servers`. + block: { + [configKey]: args.client === "opencode" ? { servers: { loom: entry } } : { loom: entry }, + }, }; if (args.client === "claude-code") { out.command = claudeMcpAddCommand({ mcpUrl, token: args.token }); diff --git a/server/cli/install.py b/server/cli/install.py index dfdf1301c7..33cecba4fd 100644 --- a/server/cli/install.py +++ b/server/cli/install.py @@ -13,12 +13,13 @@ from server.cli._client import DEFAULT_BASE_URL, agent_mode, default_base_url, resolve_token from server.cli._paths import write_private -from server.cli.jsonc_edit import JsoncEditError, upsert_object_key +from server.cli.jsonc_edit import JsoncEditError, upsert_nested_key from server.identity.app.token_clients import ( CODING_CLIENTS, CODING_TOOLSET, CONFIG_PATHS, config_key, + config_path_keys, mcp_entry, ) @@ -41,6 +42,8 @@ def _resolve_install_path(client: str) -> Path: """Map (client, current OS) → expanded config file path.""" + if client == "opencode": + return _opencode_config_path() spec = _INSTALL_CLIENTS[client] osname = sys.platform # Unknown platforms fall back to the linux convention. @@ -52,6 +55,31 @@ def _resolve_install_path(client: str) -> Path: return Path(raw) +# The files OpenCode's `mcp add --global` looks for in its config directory, in its +# order; with none there it creates the first. +_OPENCODE_CONFIG_NAMES = ( + "opencode.json", + "opencode.jsonc", + os.path.join(".opencode", "opencode.json"), + os.path.join(".opencode", "opencode.jsonc"), +) + + +def _opencode_config_path() -> Path: + """OpenCode's global config file: in $OPENCODE_CONFIG_DIR, else + $XDG_CONFIG_HOME/opencode, else ~/.config/opencode (Windows too), the first of + `_OPENCODE_CONFIG_NAMES` that exists, or opencode.json when none does.""" + directory = os.environ.get("OPENCODE_CONFIG_DIR") or os.path.join( + os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config"), + "opencode", + ) + for name in _OPENCODE_CONFIG_NAMES: + candidate = Path(directory) / name + if candidate.is_file(): + return candidate + return Path(directory) / _OPENCODE_CONFIG_NAMES[0] + + def _detect_installed_clients() -> list[str]: """Best-effort detection: a client counts as present if its config directory exists. Lets `loom install` (no --client) wire every editor the @@ -345,7 +373,8 @@ def _print_dry_run(path: Path, changes: dict[str, Any], token: str) -> None: print(" (every other key in the file is kept as it is)") -def _print_zed_manual( +def _print_jsonc_manual( + client: str, path: Path, section: str, name: str, @@ -362,55 +391,71 @@ def _print_zed_manual( if dry_run and token: rendered = rendered.replace(token, "") print( - f"ERROR (zed): {path} could not be merged ({reason}). The file was not changed.\n" + f"ERROR ({client}): {path} could not be merged ({reason}). The file was not changed.\n" f'Add this under "{section}" in that file:\n{rendered}', file=sys.stderr, ) -def _install_zed( +def _install_jsonc( + client: str, cfg_path: Path, - section: str, + sections: tuple[str, ...], name: str, entry: dict[str, Any], token: str, *, dry_run: bool, ) -> bool: - """Merge `context_servers` into Zed's settings.json without a full rewrite.""" + """Merge the entry under `sections` (Zed's `context_servers`, OpenCode's + `mcp.servers`) without a full rewrite, so the file's comments and trailing + commas stay.""" import json as _json + changes: dict[str, Any] = {name: entry} + for key in reversed(sections): + changes = {key: changes} + section = ".".join(sections) if not cfg_path.exists(): - rendered = _json.dumps({section: {name: entry}}, indent=2) + "\n" + rendered = _json.dumps(changes, indent=2) + "\n" if dry_run: - _print_dry_run(cfg_path, {section: {name: entry}}, token) + _print_dry_run(cfg_path, changes, token) return True write_private(cfg_path, rendered, newline="") - print(f"✓ zed: wrote {name} → {cfg_path}") + print(f"✓ {client}: wrote {name} → {cfg_path}") return True try: original = cfg_path.read_bytes().decode("utf-8") except (UnicodeDecodeError, OSError) as exc: - _print_zed_manual( - cfg_path, section, name, entry, token, f"could not read it ({exc})", dry_run=dry_run + _print_jsonc_manual( + client, + cfg_path, + section, + name, + entry, + token, + f"could not read it ({exc})", + dry_run=dry_run, ) return False try: - rendered, changed = upsert_object_key(original, section, name, entry) + rendered, changed = upsert_nested_key(original, sections, name, entry) except JsoncEditError as exc: - _print_zed_manual(cfg_path, section, name, entry, token, exc.reason, dry_run=dry_run) + _print_jsonc_manual( + client, cfg_path, section, name, entry, token, exc.reason, dry_run=dry_run + ) return False if dry_run: if changed: - _print_dry_run(cfg_path, {section: {name: entry}}, token) + _print_dry_run(cfg_path, changes, token) else: print(f"unchanged: {cfg_path}") return True if not changed: - print(f"✓ zed: {name} already set → {cfg_path}") + print(f"✓ {client}: {name} already set → {cfg_path}") return True write_private(cfg_path, rendered, newline="") - print(f"✓ zed: wrote {name} → {cfg_path}") + print(f"✓ {client}: wrote {name} → {cfg_path}") return True @@ -468,8 +513,10 @@ def _install_one( cfg_path = _resolve_install_path(client) mcp_url = _install_mcp_url(server_url, toolset) entry = mcp_entry(client, mcp_url, token) - if client == "zed": - return _install_zed(cfg_path, section, name, entry, token, dry_run=dry_run) + if client in ("zed", "opencode"): + return _install_jsonc( + client, cfg_path, config_path_keys(client), name, entry, token, dry_run=dry_run + ) existing: dict[str, Any] = {} if cfg_path.exists(): diff --git a/server/cli/jsonc_edit.py b/server/cli/jsonc_edit.py index 4c604dcb54..6ef9a902f3 100644 --- a/server/cli/jsonc_edit.py +++ b/server/cli/jsonc_edit.py @@ -76,22 +76,40 @@ def upsert_object_key( when the root is not an object, `section` is not one object, or `name` is duplicated there. """ + return upsert_nested_key(text, (section,), name, entry) + + +def upsert_nested_key( + text: str, sections: tuple[str, ...], name: str, entry: dict[str, Any] +) -> tuple[str, bool]: + """`upsert_object_key` under a path of objects: with sections ("mcp", "servers"), + `mcp.servers.name` is set. The first section missing on the way down is inserted + with the rest of the path inside it. Raises JsoncEditError as above for any + section on the path.""" + if not sections: + raise ValueError("sections must name at least one object") + path = (*sections, name) newline = _fragment_newline(text) - root = _parse_root(text) - section_member = _only(root, section) - if section_member is None: - return _commit(text, root, section, {name: entry}, section, name, entry, newline) - if not isinstance(section_member.value, _Object): - raise JsoncEditError(f"{section} is not an object") - current = _only(section_member.value, name) + obj = _parse_root(text) + for depth, key in enumerate(path[:-1]): + member = _only(obj, key) + if member is None: + value: object = entry + for inner in reversed(path[depth + 1 :]): + value = {inner: value} + return _commit(text, obj, key, value, path, entry, newline) + if not isinstance(member.value, _Object): + raise JsoncEditError(f"{'.'.join(path[: depth + 1])} is not an object") + obj = member.value + current = _only(obj, name) if current is None: - return _commit(text, section_member.value, name, entry, section, name, entry, newline) + return _commit(text, obj, name, entry, path, entry, newline) if _to_data(current.value) == entry: return text, False indent = _indent_before(text, current.key_start) or " " rendered = _render(entry, indent, newline) updated = text[: current.value_start] + rendered + text[current.value_end :] - _require_entry(updated, section, name, entry) + _require_entry(updated, path, entry) return updated, True @@ -139,25 +157,25 @@ def _commit( obj: _Object, key: str, value: object, - section: str, - name: str, + path: tuple[str, ...], entry: dict[str, Any], newline: str, ) -> tuple[str, bool]: updated = _insert_member(text, obj, key, value, newline) - _require_entry(updated, section, name, entry) + _require_entry(updated, path, entry) return updated, True -def _require_entry(text: str, section: str, name: str, entry: dict[str, Any]) -> None: +def _require_entry(text: str, path: tuple[str, ...], entry: dict[str, Any]) -> None: """The written text has to parse back to the entry. A splice inside a comment is syntactically quiet and must not count as success.""" - root = _parse_root(text) - section_member = _only(root, section) - if section_member is None or not isinstance(section_member.value, _Object): - raise JsoncEditError("could not place the new key") - current = _only(section_member.value, name) - if current is None or _to_data(current.value) != entry: + value: Any = _parse_root(text) + for key in path: + member = _only(value, key) if isinstance(value, _Object) else None + if member is None: + raise JsoncEditError("could not place the new key") + value = member.value + if _to_data(value) != entry: raise JsoncEditError("could not place the new key") diff --git a/server/identity/app/token_clients.py b/server/identity/app/token_clients.py index 1cedb36745..15ed72d947 100644 --- a/server/identity/app/token_clients.py +++ b/server/identity/app/token_clients.py @@ -12,7 +12,7 @@ # Coding agents mount the `coding` toolset, on the URL, as the dashboard's snippets do # (frontend/src/lib/clients.ts CODING_TOOLSET_CLIENTS) and `loom install` does. -CODING_CLIENTS = frozenset({"claude-code", "codex", "cursor", "gemini"}) +CODING_CLIENTS = frozenset({"claude-code", "codex", "cursor", "gemini", "opencode"}) CODING_TOOLSET = "coding" @@ -64,6 +64,13 @@ "linux": "~/.gemini/settings.json", "win32": "%USERPROFILE%\\.gemini\\settings.json", }, + # OpenCode roots its global config at $XDG_CONFIG_HOME, else ~/.config, on every + # platform (Windows too), and reads opencode.json or opencode.jsonc there. + "opencode": { + "darwin": "~/.config/opencode/opencode.json", + "linux": "~/.config/opencode/opencode.json", + "win32": "%USERPROFILE%\\.config\\opencode\\opencode.json", + }, } @@ -75,8 +82,19 @@ _CONFIG_KEYS = {"vscode": "servers", "zed": "context_servers", "codex": "mcp_servers"} +# OpenCode 2.x keeps its servers one level down, under `mcp.servers`. +_NESTED_CONFIG_KEYS = {"opencode": ("mcp", "servers")} + + def config_key(client: str) -> str: - return _CONFIG_KEYS.get(client, "mcpServers") + """The config's top-level key for its MCP servers (`mcp` for OpenCode, whose + servers sit under `mcp.servers`: see config_path_keys).""" + return config_path_keys(client)[0] + + +def config_path_keys(client: str) -> tuple[str, ...]: + """The keys from the config's root to the object that holds its MCP servers.""" + return _NESTED_CONFIG_KEYS.get(client) or (_CONFIG_KEYS.get(client, "mcpServers"),) def _coding_url(mcp_url: str) -> str: @@ -93,6 +111,15 @@ def mcp_entry(client: str, url: str, minted: str) -> dict[str, object]: streamable-HTTP key; `url` means SSE there), else the URL and its header.""" if client == "gemini": return {"httpUrl": url, "headers": {"Authorization": f"Bearer {minted}"}} + if client == "opencode": + # `oauth: false`: the bearer header is the credential, so OpenCode does not start + # its OAuth flow against a server that also offers OAuth (LOOM_OAUTH_ENABLED). + return { + "type": "remote", + "url": url, + "headers": {"Authorization": f"Bearer {minted}"}, + "oauth": False, + } if client == "codex": # Codex reads the bearer from an env var; the token never sits in config.toml. return {"url": url, "bearer_token_env_var": "LOOM_API_KEY"} @@ -123,10 +150,13 @@ def client_config(client: str, mcp_url: str, minted: str) -> dict[str, object]: # User scope, kept in ~/.claude.json; the dashboard prints the same line. header = f"Authorization: Bearer {minted}" command = f'claude mcp add --transport http loom "{url}" -H "{header}" -s user' - key = config_key(client) + keys = config_path_keys(client) + config: dict[str, object] = {"loom": mcp_entry(client, url, minted)} + for key in reversed(keys): + config = {key: config} return { - "config_key": key, - "config": {key: {"loom": mcp_entry(client, url, minted)}}, + "config_key": keys[0], + "config": config, "config_toml": toml, "command": command, "env": env, diff --git a/tests/unit/snapshots/cli_help.json b/tests/unit/snapshots/cli_help.json index bc9828d3b5..4bd2cad55c 100644 --- a/tests/unit/snapshots/cli_help.json +++ b/tests/unit/snapshots/cli_help.json @@ -521,8 +521,8 @@ "options: -h, --help show this help message and exit" ], "loom install": [ - "usage: loom install [-h] [--client {claude-desktop,claude-code,codex,cursor,vscode,cline,windsurf,zed,gemini} [{claude-desktop,claude-code,codex,cursor,vscode,cline,windsurf,zed,gemini} ...]] [--server-url SERVER_URL] [--token TOKEN] [--name NAME] [--toolset TOOLSET] [--dry-run] [--force]", - "options: -h, --help show this help message and exit --client {claude-desktop,claude-code,codex,cursor,vscode,cline,windsurf,zed,gemini} [{claude-desktop,claude-code,codex,cursor,vscode,cline,windsurf,zed,gemini} ...] Which client(s) to wire. Omit to auto-detect and wire every supported client found on this machine. --server-url SERVER_URL Loom server URL (default LOOM_BASE_URL, else http://localhost:7777). --token TOKEN JWT to embed in the client config. Defaults to LOOM_API_KEY, then ~/.loom/token. Use `loom mint-token` to generate one. --name NAME Server name: the key under mcpServers (cursor) or servers (vscode), and the name `claude mcp add` / `codex mcp add` registers. --toolset TOOLSET MCP toolset the client lists, as `?toolset=` on the URL; when omitted, `coding` for claude-code, codex, cursor, gemini, else the server default (LOOM_MCP_TOOLSET). --dry-run Print what would be written without touching the file. --force claude-code: add the user-scope MCP entry even when the loom plugin is installed (it mounts the server itself; both = every tool listed twice)." + "usage: loom install [-h] [--client {claude-desktop,claude-code,codex,cursor,vscode,cline,windsurf,zed,gemini,opencode} [{claude-desktop,claude-code,codex,cursor,vscode,cline,windsurf,zed,gemini,opencode} ...]] [--server-url SERVER_URL] [--token TOKEN] [--name NAME] [--toolset TOOLSET] [--dry-run] [--force]", + "options: -h, --help show this help message and exit --client {claude-desktop,claude-code,codex,cursor,vscode,cline,windsurf,zed,gemini,opencode} [{claude-desktop,claude-code,codex,cursor,vscode,cline,windsurf,zed,gemini,opencode} ...] Which client(s) to wire. Omit to auto-detect and wire every supported client found on this machine. --server-url SERVER_URL Loom server URL (default LOOM_BASE_URL, else http://localhost:7777). --token TOKEN JWT to embed in the client config. Defaults to LOOM_API_KEY, then ~/.loom/token. Use `loom mint-token` to generate one. --name NAME Server name: the key under mcpServers (cursor) or servers (vscode), and the name `claude mcp add` / `codex mcp add` registers. --toolset TOOLSET MCP toolset the client lists, as `?toolset=` on the URL; when omitted, `coding` for claude-code, codex, cursor, gemini, opencode, else the server default (LOOM_MCP_TOOLSET). --dry-run Print what would be written without touching the file. --force claude-code: add the user-scope MCP entry even when the loom plugin is installed (it mounts the server itself; both = every tool listed twice)." ], "loom demo": [ "usage: loom demo [-h] [--file FILE] [--question QUESTION] [--tags TAGS] [--base-url BASE_URL] [--token TOKEN] [--org ORG] [--namespace NAMESPACE] [--root ROOT] [--search-only]", diff --git a/tests/unit/snapshots/cli_tree.json b/tests/unit/snapshots/cli_tree.json index 65f32b5f65..3d535818c9 100644 --- a/tests/unit/snapshots/cli_tree.json +++ b/tests/unit/snapshots/cli_tree.json @@ -14848,7 +14848,8 @@ "cline", "windsurf", "zed", - "gemini" + "gemini", + "opencode" ], "nargs": "+", "type": null, @@ -14913,7 +14914,7 @@ "nargs": null, "type": "server.cli.install:_toolset_arg", "required": false, - "help": "MCP toolset the client lists, as `?toolset=` on the URL; when omitted, `coding` for claude-code, codex, cursor, gemini, else the server default (LOOM_MCP_TOOLSET).", + "help": "MCP toolset the client lists, as `?toolset=` on the URL; when omitted, `coding` for claude-code, codex, cursor, gemini, opencode, else the server default (LOOM_MCP_TOOLSET).", "metavar": null }, { diff --git a/tests/unit/test_cli_install.py b/tests/unit/test_cli_install.py index 3736b892b9..45b3c3151a 100644 --- a/tests/unit/test_cli_install.py +++ b/tests/unit/test_cli_install.py @@ -1475,3 +1475,183 @@ def resolve(client: str): assert json.loads(cursor.read_text())["mcpServers"]["loom"]["headers"]["Authorization"] == ( "Bearer T" ) + + +# --- OpenCode ----------------------------------------------------------------------- + + +def _opencode_entry(token: str) -> dict[str, object]: + return { + "type": "remote", + "url": "https://h/mcp?toolset=coding", + "headers": {"Authorization": f"Bearer {token}"}, + "oauth": False, + } + + +def test_install_one_opencode_writes_mcp_servers_and_keeps_the_rest( + tmp_path, monkeypatch: pytest.MonkeyPatch +) -> None: + cfg = tmp_path / "opencode" / "opencode.json" + monkeypatch.setattr(cli, "_resolve_install_path", lambda c: cfg) + cfg.parent.mkdir(parents=True) + other = {"type": "local", "command": ["npx", "-y", "other-mcp"]} + cfg.write_text( + json.dumps( + { + "$schema": "https://opencode.ai/config.json", + "theme": "opencode", + "mcp": {"timeout": {"request": 30000}, "servers": {"other": other}}, + }, + indent=2, + ) + ) + + for token in ("T1", "T2"): # a first write, then a rewrite with a new token + assert cli._install_one( + "opencode", token=token, server_url="https://h", name="loom", dry_run=False + ) + d = json.loads(cfg.read_text()) + # a coding agent: the coding toolset; a remote server with the bearer, no OAuth + assert d["mcp"]["servers"]["loom"] == _opencode_entry(token) + assert d["mcp"]["servers"]["other"] == other + assert d["mcp"]["timeout"] == {"request": 30000} + assert d["theme"] == "opencode" and d["$schema"] == "https://opencode.ai/config.json" + + +def test_install_one_opencode_creates_the_file_and_the_nesting( + tmp_path, monkeypatch: pytest.MonkeyPatch +) -> None: + cfg = tmp_path / "opencode" / "opencode.json" + monkeypatch.setattr(cli, "_resolve_install_path", lambda c: cfg) + cfg.parent.mkdir(parents=True) + assert cli._install_one( + "opencode", token="T", server_url="https://h", name="loom", dry_run=False + ) + assert json.loads(cfg.read_text()) == {"mcp": {"servers": {"loom": _opencode_entry("T")}}} + + # an existing `mcp` with no `servers` gets one + cfg.write_text('{"mcp": {"timeout": {"request": 1}}}') + assert cli._install_one( + "opencode", token="T", server_url="https://h", name="loom", dry_run=False + ) + assert json.loads(cfg.read_text())["mcp"] == { + "timeout": {"request": 1}, + "servers": {"loom": _opencode_entry("T")}, + } + + +_OPENCODE_JSONC = """\ +{ + // my OpenCode settings + "$schema": "https://opencode.ai/config.json", + "mcp": { + "servers": { + /* kept */ + "other": { "type": "remote", "url": "https://other/mcp", }, + }, + }, +} +""" + + +def test_install_opencode_merges_into_an_existing_jsonc_and_keeps_its_comments( + tmp_path, monkeypatch: pytest.MonkeyPatch +) -> None: + home = tmp_path / "config" + monkeypatch.setenv("XDG_CONFIG_HOME", str(home)) + monkeypatch.delenv("OPENCODE_CONFIG_DIR", raising=False) + jsonc = home / "opencode" / "opencode.jsonc" + jsonc.parent.mkdir(parents=True) + jsonc.write_text(_OPENCODE_JSONC) + + assert cli._resolve_install_path("opencode") == jsonc + assert cli._install_one( + "opencode", token="T", server_url="https://h", name="loom", dry_run=False + ) + + text = jsonc.read_text() + assert not (home / "opencode" / "opencode.json").exists() + # every byte of the old file is still there, comments and trailing commas included + assert "// my OpenCode settings" in text and "/* kept */" in text + assert '"other": { "type": "remote", "url": "https://other/mcp", },' in text + for line in _OPENCODE_JSONC.splitlines(): + assert line in text + from server.cli.jsonc_edit import _parse_root, _to_data + + servers = _to_data(_parse_root(text))["mcp"]["servers"] + assert servers["loom"] == _opencode_entry("T") + assert servers["other"] == {"type": "remote", "url": "https://other/mcp"} + + # a second run with the same token leaves the file byte for byte + assert cli._install_one( + "opencode", token="T", server_url="https://h", name="loom", dry_run=False + ) + assert jsonc.read_text() == text + + +def test_install_opencode_refuses_a_file_it_cannot_merge_and_prints_the_entry( + tmp_path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + cfg = tmp_path / "opencode" / "opencode.json" + monkeypatch.setattr(cli, "_resolve_install_path", lambda c: cfg) + cfg.parent.mkdir(parents=True) + cfg.write_text('{"mcp": "not an object"}') + assert ( + cli._install_one("opencode", token="T", server_url="https://h", name="loom", dry_run=False) + is False + ) + assert cfg.read_text() == '{"mcp": "not an object"}' + err = capsys.readouterr().err + assert f"ERROR (opencode): {cfg} could not be merged (mcp is not an object)" in err + assert 'Add this under "mcp.servers" in that file:' in err and '"oauth": false' in err + + +def test_opencode_config_path_follows_opencode_lookup( + tmp_path, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.delenv("OPENCODE_CONFIG_DIR", raising=False) + monkeypatch.delenv("XDG_CONFIG_HOME", raising=False) + monkeypatch.setenv("HOME", str(tmp_path)) + monkeypatch.setenv("USERPROFILE", str(tmp_path)) + base = tmp_path / ".config" / "opencode" + # no config yet: the file `opencode mcp add --global` would create + assert cli._resolve_install_path("opencode") == base / "opencode.json" + + base.mkdir(parents=True) + (base / ".opencode").mkdir() + (base / ".opencode" / "opencode.jsonc").write_text("{}") + assert cli._resolve_install_path("opencode") == base / ".opencode" / "opencode.jsonc" + (base / "opencode.jsonc").write_text("{}") + assert cli._resolve_install_path("opencode") == base / "opencode.jsonc" + (base / "opencode.json").write_text("{}") + assert cli._resolve_install_path("opencode") == base / "opencode.json" + + monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg")) + assert cli._resolve_install_path("opencode") == tmp_path / "xdg" / "opencode" / "opencode.json" + monkeypatch.setenv("OPENCODE_CONFIG_DIR", str(tmp_path / "custom")) + assert cli._resolve_install_path("opencode") == tmp_path / "custom" / "opencode.json" + + +def test_install_with_no_client_wires_opencode_when_its_config_dir_exists( + tmp_path, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config")) + monkeypatch.delenv("OPENCODE_CONFIG_DIR", raising=False) + others = {c: tmp_path / "absent" / c / "cfg.json" for c in cli._INSTALL_CLIENTS} + real = cli._resolve_install_path + monkeypatch.setattr( + cli, "_resolve_install_path", lambda c: real(c) if c == "opencode" else others[c] + ) + monkeypatch.setattr(cli.shutil, "which", lambda name: None) + assert "opencode" not in cli._detect_installed_clients() + + (tmp_path / "config" / "opencode").mkdir(parents=True) + assert cli._detect_installed_clients() == ["opencode"] + import argparse + + p = argparse.ArgumentParser() + cli._add_install_flags(p) + assert cli._cmd_install(p.parse_args(["--token", "T", "--server-url", "https://h"])) == 0 + written = json.loads((tmp_path / "config" / "opencode" / "opencode.json").read_text()) + assert written["mcp"]["servers"]["loom"] == _opencode_entry("T") diff --git a/tests/unit/test_token_mint.py b/tests/unit/test_token_mint.py index 91cb743c96..fb697ada2a 100644 --- a/tests/unit/test_token_mint.py +++ b/tests/unit/test_token_mint.py @@ -113,6 +113,7 @@ async def test_the_default_token_follows_live_grants_and_drops_org_wide_roles( "windsurf", "zed", "gemini", + "opencode", } assert out["token"] in str(out["clients"]["cursor"]["config"]) From 87ecfaab08bb60e8a49a67941ebba9a053fa1d9d Mon Sep 17 00:00:00 2001 From: Rahul <132360698+rahulsjha@users.noreply.github.com> Date: Thu, 19 Nov 2026 22:30:33 +0530 Subject: [PATCH 2/5] feat(cli): the OpenCode entry is what opencode mcp add writes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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> --- docs/features/integrations/mcp-clients.md | 6 +++--- frontend/src/lib/clientSetups.fixture.json | 9 +++------ frontend/src/lib/clients.ts | 4 ++-- server/identity/app/token_clients.py | 10 ++-------- tests/unit/test_cli_install.py | 3 +-- 5 files changed, 11 insertions(+), 21 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 682e6f210b..6ad9e39079 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -63,7 +63,7 @@ that only reads can use a `viewer` token; see | `windsurf` | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | `url` + `headers` | | `zed` | `~/.config/zed/settings.json` | `context_servers` | `url` + `headers` | | `gemini` | `~/.gemini/settings.json` | `mcpServers` | `httpUrl` + `headers` (Gemini CLI reads streamable HTTP from `httpUrl`) | -| `opencode` | `~/.config/opencode/opencode.json`, or `opencode.jsonc` when that is the file there (`$OPENCODE_CONFIG_DIR` or `$XDG_CONFIG_HOME/opencode` when set) | `mcp.servers` | `type: "remote"` + `url` + `headers` + `oauth: false` | +| `opencode` | `~/.config/opencode/opencode.json`, or `opencode.jsonc` when that is the file there (`$OPENCODE_CONFIG_DIR` or `$XDG_CONFIG_HOME/opencode` when set) | `mcp.servers` | `type: "remote"` + `url` + `headers` | | `claude-code` | none: runs `claude mcp add … -s user` | | see [Claude Code](#claude-code-without-the-plugin) | | `codex` | none: runs `codex mcp add` | | see [Codex](#codex-without-the-plugin) | @@ -76,8 +76,8 @@ instead: the entry is spliced in and the file's comments and trailing commas sta that cannot be merged that way is left as it is and the entry to paste is printed. OpenCode 2.x reads servers from `mcp.servers`, the shape written here; the 1.x `opencode-ai` npm package reads them from `mcp` directly and does not see this entry. -The entry sets `"oauth": false`, so OpenCode sends the token rather than starting its -OAuth flow when the server also offers OAuth (`LOOM_OAUTH_ENABLED`). +The entry is what `opencode mcp add loom --url URL --header "Authorization=Bearer "` +writes, so OpenCode's own OAuth setting stays at its default. Zed reads `context_servers` from `settings.json`. On macOS that file is `~/.config/zed/settings.json`, the same path as on Linux. On Windows it is diff --git a/frontend/src/lib/clientSetups.fixture.json b/frontend/src/lib/clientSetups.fixture.json index e2f7ce6279..8a1fb5c18b 100644 --- a/frontend/src/lib/clientSetups.fixture.json +++ b/frontend/src/lib/clientSetups.fixture.json @@ -154,8 +154,7 @@ "url": "http://x/mcp?toolset=coding", "headers": { "Authorization": "Bearer T" - }, - "oauth": false + } } } } @@ -321,8 +320,7 @@ "url": "http://x/mcp?a=1&toolset=coding", "headers": { "Authorization": "Bearer T" - }, - "oauth": false + } } } } @@ -502,8 +500,7 @@ "url": "http://x/mcp?mytoolset=x&toolset=coding", "headers": { "Authorization": "Bearer T" - }, - "oauth": false + } } } } diff --git a/frontend/src/lib/clients.ts b/frontend/src/lib/clients.ts index 3c0555fd39..f26a804698 100644 --- a/frontend/src/lib/clients.ts +++ b/frontend/src/lib/clients.ts @@ -149,8 +149,8 @@ export function formatMcpConfig(args: { client: ClientId; token: string; mcpUrl: e.type = "http"; } if (args.client === "opencode") { - // OpenCode 2.x: a remote server, the bearer header as its credential and no OAuth flow. - return { type: "remote", url: mcpUrl, headers: e.headers, oauth: false }; + // OpenCode 2.x: what `opencode mcp add --url … --header …` writes. + return { type: "remote", url: mcpUrl, headers: e.headers }; } return e; })(); diff --git a/server/identity/app/token_clients.py b/server/identity/app/token_clients.py index 15ed72d947..088feb14b0 100644 --- a/server/identity/app/token_clients.py +++ b/server/identity/app/token_clients.py @@ -112,14 +112,8 @@ def mcp_entry(client: str, url: str, minted: str) -> dict[str, object]: if client == "gemini": return {"httpUrl": url, "headers": {"Authorization": f"Bearer {minted}"}} if client == "opencode": - # `oauth: false`: the bearer header is the credential, so OpenCode does not start - # its OAuth flow against a server that also offers OAuth (LOOM_OAUTH_ENABLED). - return { - "type": "remote", - "url": url, - "headers": {"Authorization": f"Bearer {minted}"}, - "oauth": False, - } + # What `opencode mcp add --url … --header …` writes: a remote server and its header. + return {"type": "remote", "url": url, "headers": {"Authorization": f"Bearer {minted}"}} if client == "codex": # Codex reads the bearer from an env var; the token never sits in config.toml. return {"url": url, "bearer_token_env_var": "LOOM_API_KEY"} diff --git a/tests/unit/test_cli_install.py b/tests/unit/test_cli_install.py index 45b3c3151a..4ac046e903 100644 --- a/tests/unit/test_cli_install.py +++ b/tests/unit/test_cli_install.py @@ -1485,7 +1485,6 @@ def _opencode_entry(token: str) -> dict[str, object]: "type": "remote", "url": "https://h/mcp?toolset=coding", "headers": {"Authorization": f"Bearer {token}"}, - "oauth": False, } @@ -1604,7 +1603,7 @@ def test_install_opencode_refuses_a_file_it_cannot_merge_and_prints_the_entry( assert cfg.read_text() == '{"mcp": "not an object"}' err = capsys.readouterr().err assert f"ERROR (opencode): {cfg} could not be merged (mcp is not an object)" in err - assert 'Add this under "mcp.servers" in that file:' in err and '"oauth": false' in err + assert 'Add this under "mcp.servers" in that file:' in err and '"type": "remote"' in err def test_opencode_config_path_follows_opencode_lookup( From 4be27a17f6e976893f75d903521386c7790431aa Mon Sep 17 00:00:00 2001 From: Rahul <132360698+rahulsjha@users.noreply.github.com> Date: Fri, 20 Nov 2026 06:26:11 +0530 Subject: [PATCH 3/5] Remove the upsert_object_key wrapper 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> --- server/cli/jsonc_edit.py | 24 ++++++++---------------- tests/unit/test_cli_install.py | 4 ++-- 2 files changed, 10 insertions(+), 18 deletions(-) diff --git a/server/cli/jsonc_edit.py b/server/cli/jsonc_edit.py index 6ef9a902f3..27af26e9de 100644 --- a/server/cli/jsonc_edit.py +++ b/server/cli/jsonc_edit.py @@ -67,25 +67,17 @@ class _Object: members: tuple[_Member, ...] -def upsert_object_key( - text: str, section: str, name: str, entry: dict[str, Any] -) -> tuple[str, bool]: - """Return the text with `section.name` set to `entry`, and whether it changed. - - An entry that is already equal is left byte for byte. Raises JsoncEditError - when the root is not an object, `section` is not one object, or `name` is - duplicated there. - """ - return upsert_nested_key(text, (section,), name, entry) - - def upsert_nested_key( text: str, sections: tuple[str, ...], name: str, entry: dict[str, Any] ) -> tuple[str, bool]: - """`upsert_object_key` under a path of objects: with sections ("mcp", "servers"), - `mcp.servers.name` is set. The first section missing on the way down is inserted - with the rest of the path inside it. Raises JsoncEditError as above for any - section on the path.""" + """Return the text with `entry` set at `sections` + `name`, and whether it changed. + + With sections ("mcp", "servers"), `mcp.servers.name` is set. The first section + missing on the way down is inserted with the rest of the path inside it. An entry + that is already equal is left byte for byte. Raises JsoncEditError when the root + is not an object, a section on the path is not one object, or `name` is + duplicated in the last one. + """ if not sections: raise ValueError("sections must name at least one object") path = (*sections, name) diff --git a/tests/unit/test_cli_install.py b/tests/unit/test_cli_install.py index 4ac046e903..b6bebe7dfa 100644 --- a/tests/unit/test_cli_install.py +++ b/tests/unit/test_cli_install.py @@ -9,7 +9,7 @@ import pytest import server.cli.install as cli -from server.cli.jsonc_edit import JsoncEditError, upsert_object_key +from server.cli.jsonc_edit import JsoncEditError, upsert_nested_key from server.identity.app.token_clients import MCP_CLIENTS, client_config @@ -1441,7 +1441,7 @@ def wrap(path, text, *args, **kwargs): ) def test_a_non_ascii_or_huge_number_is_a_jsonc_edit_error(text: str) -> None: with pytest.raises(JsoncEditError): - upsert_object_key(text, "context_servers", "loom", {"url": "http://h"}) + upsert_nested_key(text, ("context_servers",), "loom", {"url": "http://h"}) @pytest.mark.parametrize( From c38ef07d6a30ffd43d9581d303abf8646e15115f Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Fri, 20 Nov 2026 20:44:28 +0000 Subject: [PATCH 4/5] State the OpenCode connection check limits Signed-off-by: zlareb1 --- docs/features/integrations/mcp-clients.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index f612fbbe38..62c3156aec 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -209,7 +209,7 @@ client afterwards. | GitHub Copilot CLI | `~/.copilot/mcp-config.json` | `{"mcpServers": {"loom": {"type": "http", "url": "URL", "headers": {…}, "tools": ["*"]}}}`; or the plugin, below | accepted | | Neovim with mcphub.nvim (also serves avante.nvim and CodeCompanion) | `~/.config/mcphub/servers.json` | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | | | Emacs with mcp.el and gptel | `mcp-hub-servers` in your init file, then `gptel-mcp-connect` | `(setq mcp-hub-servers '(("loom" . (:url "URL"))))` (single-user server only: no header field is documented) | | -| OpenCode | `opencode.json` or `.opencode/opencode.json` in the project or a folder above it, or `~/.config/opencode/opencode.json` | `loom install --client opencode`, or `opencode mcp add loom --url URL --header "Authorization=Bearer "`, which in OpenCode 2.x writes `{"mcp": {"servers": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}}`; the 1.x `opencode-ai` npm package takes `{"mcp": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}`, which 2.x still reads | connected | +| OpenCode | `opencode.json` or `.opencode/opencode.json` in the project or a folder above it, or `~/.config/opencode/opencode.json` | `loom install --client opencode`, or `opencode mcp add loom --url URL --header "Authorization=Bearer "`, which in OpenCode 2.x writes `{"mcp": {"servers": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}}`; the 1.x `opencode-ai` npm package takes `{"mcp": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}`, which 2.x still reads | configuration checked; connectivity unverified | | Kilo Code (extension and CLI) | `kilo.jsonc` in the project, or `~/.config/kilo/kilo.jsonc` | `{"mcp": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}` | connected (CLI) | | Cline CLI | `~/.cline/data/settings/cline_mcp_settings.json` | `cline mcp add loom URL --transport http --header "Authorization: Bearer " --yes` (the Cline extension: [`loom install`](#what-it-writes-per-client)) | accepted | | Google Antigravity | `~/.gemini/config/mcp_config.json`, or `.agents/mcp_config.json` in the workspace | `{"mcpServers": {"loom": {"serverUrl": "URL", "headers": {…}}}}` (`url` also works) | | @@ -247,9 +247,13 @@ client afterwards. **Checked**: - `connected`: the client's own status command reported the server connected, against a - local Loom with a token and no model call (OpenCode 2.3.0, Kilo CLI 7.8.27, Gemini CLI + local Loom with a token and no model call (Kilo CLI 7.8.27, Gemini CLI 0.68.0, Qwen Code 0.27.3, Factory droid 1.12.1, Hermes Agent 0.23.1, OpenClaw 2026.9.2); for smolagents 1.26.0 and Strix 1.7.0, their own MCP client listed the tools. +- `configuration checked`: OpenCode 2.3.0's configuration shape and file lookup were + checked against its tagged source. A connection-status run reused a background server + across configuration homes and reported connected for a rejected token; that run does + not establish configuration loading, authentication or connectivity. - `starts`: the client's check started the extension, which a rejected token stops (goose 1.59.1). - `accepted`: the client wrote or accepted the entry; a successful server connection was From 96be03c3d5fa4062c8ca44226a5e138642c86504 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Fri, 20 Nov 2026 21:40:07 +0000 Subject: [PATCH 5/5] Replicated erasure fixtures provide isolated write leases Fenced memory inserts require a lease table in the selected schema. Give each fixture database its own Keeper root while preserving the replicated content checks. Signed-off-by: zlareb1 --- .../integration/test_erasure_replicated_ch.py | 5 + tests/unit/test_erasure_replicated_fixture.py | 96 +++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 tests/unit/test_erasure_replicated_fixture.py diff --git a/tests/integration/test_erasure_replicated_ch.py b/tests/integration/test_erasure_replicated_ch.py index a1fa3f60c9..611f07969d 100644 --- a/tests/integration/test_erasure_replicated_ch.py +++ b/tests/integration/test_erasure_replicated_ch.py @@ -74,6 +74,11 @@ def db(raw: Any, monkeypatch: pytest.MonkeyPatch) -> Iterator[str]: parameters={"db": name}, ).result_rows assert engines == [(True,)] + # Fenced memory inserts need leases isolated from the source schema's keys. + raw.command( + f"CREATE TABLE {name}._migration_lock AS {source}._migration_lock " + f"ENGINE = KeeperMap('/{name}/_migration_lock') PRIMARY KEY name" + ) monkeypatch.setattr(settings, "ch_database", name) yield name finally: diff --git a/tests/unit/test_erasure_replicated_fixture.py b/tests/unit/test_erasure_replicated_fixture.py new file mode 100644 index 0000000000..3147871591 --- /dev/null +++ b/tests/unit/test_erasure_replicated_fixture.py @@ -0,0 +1,96 @@ +"""The replicated erasure fixture supplies an isolated write-lease store.""" + +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +from server.core import leases +from server.settings import settings +from tests.integration import test_erasure_replicated_ch as replicated +from tests.unit.claims_fake import FakeLockTable + + +class Schema: + def __init__(self): + self.tables = {} + self.commands = [] + + def command(self, sql): + self.commands.append(sql) + if sql.startswith("CREATE TABLE "): + self.tables[sql.split()[2]] = sql + + def query(self, sql, parameters=None): + if "engine_full" in sql: + assert parameters["db"] == "source_schema" + return SimpleNamespace(result_rows=[("ReplacingMergeTree(version) ORDER BY tuple()",)]) + assert "SELECT DISTINCT engine" in sql + flags = {"ENGINE = Replicated" in ddl for ddl in self.tables.values()} + return SimpleNamespace(result_rows=[(flag,) for flag in sorted(flags)]) + + +class FixtureLocks(FakeLockTable): + def __init__(self, schema): + super().__init__() + self.schema = schema + + async def query_one(self, sql, params=None): + if "loom._migration_lock" in sql: + if f"{settings.ch_database}._migration_lock" not in self.schema.tables: + raise RuntimeError("Unknown table _migration_lock") + return await super().query_one(sql, params) + + +@pytest.fixture +def isolated_schema(monkeypatch): + monkeypatch.setattr(settings, "ch_database", "source_schema") + schema = Schema() + stream = replicated.db.__wrapped__(schema, monkeypatch) + name = next(stream) + try: + yield schema, name + finally: + stream.close() + assert schema.commands[-1] == f"DROP DATABASE IF EXISTS {name} SYNC" + + +async def test_replicated_erasure_fixture_can_take_and_release_a_write_lease(isolated_schema): + schema, name = isolated_schema + keeper = FixtureLocks(schema) + lease = await leases.take("memory_insert/fixture", ttl_s=60, ch=keeper) + assert lease is not None and lease.held + assert settings.ch_database == name + await lease.release() + assert keeper.keys == {} + + +async def test_a_missing_fixture_lease_table_still_refuses(isolated_schema): + schema, name = isolated_schema + schema.tables.pop(f"{name}._migration_lock", None) + with pytest.raises(leases.LeaseUnavailable): + await leases.take("memory_insert/fixture", ttl_s=60, ch=FixtureLocks(schema)) + + +def test_fixture_lease_paths_are_separate_from_source_and_each_other(monkeypatch): + paths = [] + for _ in range(2): + with monkeypatch.context() as patch: + patch.setattr(settings, "ch_database", "source_schema") + schema = Schema() + stream = replicated.db.__wrapped__(schema, patch) + name = next(stream) + try: + ddl = schema.tables[f"{name}._migration_lock"] + assert "AS source_schema._migration_lock" in ddl + assert f"KeeperMap('/{name}/_migration_lock')" in ddl + assert "PRIMARY KEY name" in ddl + assert all( + "ENGINE = Replicated" in schema.tables[f"{name}.{table}"] + for table in replicated._TABLES + ) + paths.append(name) + finally: + stream.close() + assert paths[0] != paths[1]