diff --git a/docs/features/integrations/index.md b/docs/features/integrations/index.md index 649260c4a7..758a79da36 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 61a762f1a9..62c3156aec 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` | +| `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 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 @@ -191,57 +199,61 @@ 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 | 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) | | +| 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**: - `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 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..8a1fb5c18b 100644 --- a/frontend/src/lib/clientSetups.fixture.json +++ b/frontend/src/lib/clientSetups.fixture.json @@ -143,6 +143,25 @@ "config_toml": "", "command": "", "env": {} + }, + "opencode": { + "config_key": "mcp", + "config": { + "mcp": { + "servers": { + "loom": { + "type": "remote", + "url": "http://x/mcp?toolset=coding", + "headers": { + "Authorization": "Bearer T" + } + } + } + } + }, + "config_toml": "", + "command": "", + "env": {} } } }, @@ -290,6 +309,25 @@ "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" + } + } + } + } + }, + "config_toml": "", + "command": "", + "env": {} } } }, @@ -451,6 +489,25 @@ "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" + } + } + } + } + }, + "config_toml": "", + "command": "", + "env": {} } } } diff --git a/frontend/src/lib/clients.ts b/frontend/src/lib/clients.ts index 1e53c6c0b0..f26a804698 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: what `opencode mcp add --url … --header …` writes. + return { type: "remote", url: mcpUrl, headers: e.headers }; + } 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..27af26e9de 100644 --- a/server/cli/jsonc_edit.py +++ b/server/cli/jsonc_edit.py @@ -67,31 +67,41 @@ class _Object: members: tuple[_Member, ...] -def upsert_object_key( - text: str, section: str, name: str, entry: dict[str, Any] +def upsert_nested_key( + text: str, sections: tuple[str, ...], name: str, entry: dict[str, Any] ) -> tuple[str, bool]: - """Return the text with `section.name` set to `entry`, and whether it changed. + """Return the text with `entry` set at `sections` + `name`, 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. + 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) 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 +149,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..088feb14b0 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,9 @@ 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": + # 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"} @@ -123,10 +144,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 8db6694739..fd848f2a93 100644 --- a/tests/unit/snapshots/cli_help.json +++ b/tests/unit/snapshots/cli_help.json @@ -543,8 +543,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 03d434256a..b5ea5829ab 100644 --- a/tests/unit/snapshots/cli_tree.json +++ b/tests/unit/snapshots/cli_tree.json @@ -15532,7 +15532,8 @@ "cline", "windsurf", "zed", - "gemini" + "gemini", + "opencode" ], "nargs": "+", "type": null, @@ -15597,7 +15598,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..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( @@ -1475,3 +1475,182 @@ 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}"}, + } + + +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 '"type": "remote"' 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_repo_job_sandbox.py b/tests/unit/test_repo_job_sandbox.py index ce64aed658..c31db68970 100644 --- a/tests/unit/test_repo_job_sandbox.py +++ b/tests/unit/test_repo_job_sandbox.py @@ -598,14 +598,27 @@ async def test_a_job_that_closes_its_output_still_dies_at_its_timeout(monkeypatc assert loop.time() - started < 5 -async def test_cancelling_a_job_that_closed_its_output_kills_and_reaps_it(monkeypatch) -> None: +@pytest.mark.parametrize("spawn_delay_s", [0.0, 0.4]) +async def test_cancelling_a_job_that_closed_its_output_kills_and_reaps_it( + monkeypatch, spawn_delay_s: float +) -> None: monkeypatch.setattr(sandbox, "_available", False) + output_closed = asyncio.Event() pids: list[int] = [] real_exec = asyncio.create_subprocess_exec async def spy(*args, **kwargs): + await asyncio.sleep(spawn_delay_s) proc = await real_exec(*args, **kwargs) pids.append(proc.pid) + try: + assert proc.stdout is not None and proc.stderr is not None + assert await proc.stdout.read() == b"" + assert await proc.stderr.read() == b"" + output_closed.set() + finally: + if not output_closed.is_set(): + await sandbox._kill_group(proc) return proc monkeypatch.setattr(sandbox.asyncio, "create_subprocess_exec", spy) @@ -614,12 +627,20 @@ async def spy(*args, **kwargs): ["sh", "-c", "exec 1>&- 2>&-; sleep 30"], env={"PATH": "/usr/bin:/bin"}, timeout_s=30 ) ) - await asyncio.sleep(0.3) - job.cancel() - with pytest.raises(asyncio.CancelledError): - await job - with pytest.raises(ProcessLookupError): # killed and reaped: no such pid any more - os.kill(pids[0], 0) + try: + # EOF proves both outputs closed before cancellation reaches the child. + async with asyncio.timeout(5): + await output_closed.wait() + job.cancel() + with pytest.raises(asyncio.CancelledError): + await job + with pytest.raises(ProcessLookupError): # killed and reaped: no such pid any more + os.kill(pids[0], 0) + finally: + if not job.done(): + job.cancel() + with contextlib.suppress(asyncio.CancelledError): + await job def test_a_refused_layout_is_a_health_problem(tmp_path: Path, monkeypatch) -> None: diff --git a/tests/unit/test_token_mint.py b/tests/unit/test_token_mint.py index d23dd3cc06..43a4b0f1d8 100644 --- a/tests/unit/test_token_mint.py +++ b/tests/unit/test_token_mint.py @@ -116,6 +116,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"])