Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/features/integrations/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand Down
158 changes: 85 additions & 73 deletions docs/features/integrations/mcp-clients.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/getting-started/connect-a-coding-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <name>` 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
Expand Down
57 changes: 57 additions & 0 deletions frontend/src/lib/clientSetups.fixture.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {}
}
}
},
Expand Down Expand Up @@ -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": {}
}
}
},
Expand Down Expand Up @@ -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": {}
}
}
}
Expand Down
25 changes: 21 additions & 4 deletions frontend/src/lib/clients.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ export type ClientId =
| "cline"
| "windsurf"
| "zed"
| "gemini";
| "gemini"
| "opencode";

interface MCPClient {
id: ClientId;
Expand All @@ -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. */
Expand All @@ -49,7 +51,13 @@ const STDIO_VIA_NPX: ReadonlySet<ClientId> = 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<ClientId> = new Set(["claude-code", "codex", "cursor", "gemini"]);
export const CODING_TOOLSET_CLIENTS: ReadonlySet<ClientId> = 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.
Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -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 });
Expand Down
83 changes: 65 additions & 18 deletions server/cli/install.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
)

Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -362,55 +391,71 @@ def _print_zed_manual(
if dry_run and token:
rendered = rendered.replace(token, "<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


Expand Down Expand Up @@ -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():
Expand Down
Loading
Loading