From fea7aefb4aaacd4eb174e70a7847114bd4eaba2b Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Sun, 15 Nov 2026 08:11:38 +0000 Subject: [PATCH 1/9] The repository is a Cursor plugin marketplace that installs Loom's MCP server and skills .cursor-plugin/ at the root holds the marketplace, the clickhouse-loom manifest and its MCP entry. The entry is the server's MCP URL alone, a plugin variable: a single-user server serves it without a token, and a server with OAuth on signs each person in by browser. The plugin ships the root skills, and the release pins its version with theirs. Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- .claude/rules/plugins.md | 3 +- .cursor-plugin/marketplace.json | 14 ++++++++ .cursor-plugin/mcp.json | 5 +++ .cursor-plugin/plugin.json | 34 ++++++++++++++++++ README.md | 4 ++- docs/development/release-process.md | 3 +- docs/development/repository-guide.md | 50 +++++++++++++------------- docs/features/integrations/cursor.md | 32 +++++++++++++---- scripts/release/prepare.py | 1 + tests/unit/test_cursor_plugin.py | 53 ++++++++++++++++++++++++++++ tests/unit/test_published_links.py | 1 + 11 files changed, 165 insertions(+), 35 deletions(-) create mode 100644 .cursor-plugin/marketplace.json create mode 100644 .cursor-plugin/mcp.json create mode 100644 .cursor-plugin/plugin.json create mode 100644 tests/unit/test_cursor_plugin.py diff --git a/.claude/rules/plugins.md b/.claude/rules/plugins.md index ae47b1882a..f88c0c2091 100644 --- a/.claude/rules/plugins.md +++ b/.claude/rules/plugins.md @@ -3,6 +3,7 @@ paths: - "integrations/**" - "skills/**" - ".claude-plugin/**" + - ".cursor-plugin/**" --- # Integrations and coding-agent plugins @@ -14,5 +15,5 @@ paths: - Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here; a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case. - Anything a hook sends to the server goes through `redactSecrets` / `redactHead`, redacting before truncating, and a diff through `diffHeaders`, which sends only its paths, hunk ranges and function names (`integrations/claude-code-plugin/lib/loom-client.mjs`); a new capture path that skips them is a finding. - An integration or its README is held to an open-source bar: the happy path runs end to end as written; an experimental feature says so and names the versions it was tested on; an upstream bug is filed upstream and linked; a cheap CI check keeps the example from rotting. -- The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` plus each `metadata.version`, released with the server; `skills/loom/` is also what `mentor.guide` serves, so the image copies it ([release process](../../docs/development/release-process.md#where-the-version-lives)). +- The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` (and `.cursor-plugin/plugin.json`, whose plugin ships them) plus each `metadata.version`, released with the server; `skills/loom/` is also what `mentor.guide` serves, so the image copies it ([release process](../../docs/development/release-process.md#where-the-version-lives)). - The skills here ship to users. Their text is prompt: every line costs tokens in every session, so keep them short and exact. diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json new file mode 100644 index 0000000000..67f4d551dd --- /dev/null +++ b/.cursor-plugin/marketplace.json @@ -0,0 +1,14 @@ +{ + "name": "clickhouse-loom", + "owner": { "name": "ClickHouse" }, + "metadata": { + "description": "ClickHouse Loom: shared long-term memory and code intelligence for AI coding agents, self-hosted." + }, + "plugins": [ + { + "name": "clickhouse-loom", + "source": "./", + "description": "Shared long-term memory, document search and a code index for Cursor from a self-hosted Loom server, over MCP, with the loom and loom-code skills." + } + ] +} diff --git a/.cursor-plugin/mcp.json b/.cursor-plugin/mcp.json new file mode 100644 index 0000000000..bc984f141a --- /dev/null +++ b/.cursor-plugin/mcp.json @@ -0,0 +1,5 @@ +{ + "mcpServers": { + "loom": { "url": "${LOOM_MCP_URL}" } + } +} diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json new file mode 100644 index 0000000000..9eb90bc9fb --- /dev/null +++ b/.cursor-plugin/plugin.json @@ -0,0 +1,34 @@ +{ + "name": "clickhouse-loom", + "version": "1.2.0", + "displayName": "ClickHouse Loom", + "description": "Shared long-term memory, document search and a code index for Cursor from a self-hosted ClickHouse Loom server, over MCP, with the loom and loom-code skills that say when to recall, save and ask the code index.", + "author": { "name": "ClickHouse" }, + "homepage": "https://clickhouse.github.io/loom/features/integrations/cursor/", + "repository": "https://github.com/ClickHouse/loom", + "license": "Apache-2.0", + "keywords": [ + "agent-memory", + "long-term-memory", + "code-intelligence", + "code-search", + "mcp", + "clickhouse", + "self-hosted" + ], + "logo": "integrations/claude-code-plugin/assets/icon.png", + "skills": "skills/", + "mcpServers": ".cursor-plugin/mcp.json", + "variables": { + "type": "object", + "properties": { + "LOOM_MCP_URL": { + "type": "string", + "title": "Loom MCP URL", + "description": "Your Loom server's MCP endpoint on the coding toolset: http://localhost:7777/mcp?toolset=coding for a single-user server on this machine, or https:///mcp?toolset=coding for a team server with browser sign-in", + "default": "http://localhost:7777/mcp?toolset=coding" + } + }, + "required": ["LOOM_MCP_URL"] + } +} diff --git a/README.md b/README.md index f9d38477cf..9afbdb78ec 100644 --- a/README.md +++ b/README.md @@ -210,7 +210,9 @@ Start a new session; the first one connects to `http://localhost:7777`. In Codex `codex` interactively once and approve the plugin's hooks; until then only the tools work. Tell the agent something worth keeping, then ask about it in the next session. -For Cursor on the machine running a personal installation, the button below adds the +For Cursor, the [Cursor plugin](./docs/features/integrations/cursor.md#plugin) installs +the MCP entry and Loom's skills; its one setting is the server's MCP URL. On the machine +running a personal installation, the button below adds the [local MCP entry](./docs/features/integrations/cursor.md#mcp-tools), which needs no token: [![Add Loom to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=loom&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojc3NzcvbWNwP3Rvb2xzZXQ9Y29kaW5nIn0%3D) diff --git a/docs/development/release-process.md b/docs/development/release-process.md index a4b8cff85f..698bd30238 100644 --- a/docs/development/release-process.md +++ b/docs/development/release-process.md @@ -12,7 +12,7 @@ Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom- | Python SDK | `sdk/python/pyproject.toml` and `sdk/python/loom/_version.py` | | TypeScript SDK | `sdk/typescript/package.json`, `sdk/typescript/package-lock.json`, `sdk/typescript/src/version.ts` | | Web app | `frontend/package.json` and `frontend/package-lock.json` | -| Root skills | `.claude-plugin/plugin.json` and the `metadata.version` of `skills/loom-code/SKILL.md` and `skills/loom/SKILL.md` | +| Root skills | `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json` and the `metadata.version` of `skills/loom-code/SKILL.md` and `skills/loom/SKILL.md` | | Gemini CLI extension | `gemini-extension.json` | | Helm chart | `deploy/helm/loom/Chart.yaml`: `appVersion` (the default tag of the server and extractor images, and the chart's `app.kubernetes.io/version` label) and the chart's own `version`: a minor for a major or minor release, a patch for a patch release | | Coding-agent plugins | `integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json` (their own version; bump it on a behaviour change to any file the plugin ships: `hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) | @@ -390,6 +390,7 @@ Agents and people find Loom through these listings. Each reads files in this rep | npm page of `@clickhouse/loom` | the metadata of `sdk/typescript/package.json`, and `sdk/typescript/README.md` as the page body | the `npm` job on each dispatched release; the page shows the version tagged `latest`, which the job sets only for the highest final | | Claude plugin directory | `integrations/claude-code-plugin/.claude-plugin/plugin.json` (`displayName`, `description`, `keywords`, `icon`, `documentationUrl`, `supportUrl`, `privacyPolicyUrl`) and the README | submitted once in the developer portal; later versions are picked up from the tracked branch. The icon is read only on the first submission | | Claude Code plugin suggestions | the `relevance` block of the `loom` entry in `.claude-plugin/marketplace.json`: the `loom` command, Loom's config files, an SDK dependency in a manifest | read from the marketplace on the default branch; shown only where an administrator allowlists the marketplace (`pluginSuggestionMarketplaces`) | +| Cursor Marketplace | `.cursor-plugin/plugin.json` (`displayName`, `description`, `keywords`, `logo`, `variables`), `.cursor-plugin/marketplace.json` and the README | submitted once at cursor.com/marketplace/publish; Cursor reviews each update before it is listed | | Codex plugin directory | `integrations/codex-plugin/.codex-plugin/plugin.json` (`interface`) | submitted in the plugin portal; a plugin with lifecycle hooks is not eligible there, so the public listing needs a build without them | | Docs index for coding agents | `context7.json` | refreshed from the default branch after the repository is added once | | Agent Skills index | `skills/loom-code`, `skills/loom` and the Claude Code plugin's skills; the contributor skills are marked internal in their frontmatter and are not offered | ranked by `npx skills add ClickHouse/loom` installs; nothing to submit | diff --git a/docs/development/repository-guide.md b/docs/development/repository-guide.md index 018b5a8a46..5fb5570c85 100644 --- a/docs/development/repository-guide.md +++ b/docs/development/repository-guide.md @@ -4,31 +4,31 @@ What every top-level directory holds, where a concern lives inside `server/`, th ## Top-level layout -| Path | Holds | -| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `server/` | the FastAPI server: domain packages (memory, code, tracker, …), the operation registry, workers, transports, CLI, settings | -| `extractor/` | the reference extractor service (`loom_extractor/`): format detection and the document parsers, run outside the server; its image (`Dockerfile`, released as `ghcr.io/clickhouse/loom-extractor`) and lock (`uv.lock`); see [document extraction](../architecture/document-extraction.md) | -| `sdk/python/` | the Python SDK, published as `clickhouse-loom` (`sdk/python/loom/`) | -| `sdk/typescript/` | the TypeScript SDK, published as `@clickhouse/loom` (`sdk/typescript/src/`) | -| `frontend/` | the React dashboard served at `/` (Vite + Tailwind); `src/`, Playwright specs in `e2e/`, `scripts/bundle_budget.mjs` | -| `schemas/` | `migrations/` (numbered SQL), `schema.sql` (generated current shape), `otel/` (ClickStack OTel tables), `ops/` (hand-run SQL); see [`schemas/README.md`](../../schemas/README.md) | -| `dev/` | compose stacks, operator scripts (`loom_ingest.py`, `loom_init.py`, `onboard_tenant.py`, backup and restore, `verify_audit_chain.py`), `ci_start_clickhouse.sh`, `redeploy_preflight.sh` | -| `deploy/` | ClickHouse server config (`clickhouse-config/`), the Lemmagen3 model (`lemmagen3/`), the blue/green proxy (`proxy/`), the Helm chart (`helm/`), the repository-job sandbox AppArmor profile (`apparmor/`), the standalone env template (`standalone/`), the scheduled namespace copy CronJob (`okf-sync/`), dashboards (`dashboards/`, `hyperdx_dashboards.md`, `clickstack_sources.sh`) | -| `bench/` | benchmark harnesses and gates, their fixtures (`fixtures/`), datasets, rubrics, acceptance and skill evals; see [benchmarks](../benchmarks/overview.md) | -| `integrations/` | client integrations: the Claude Code and Codex plugins, the Cline hooks, the grep shim, Cursor and generic transcript hooks, the OKF CI gate | -| `skills/` | the standalone Agent Skills: `loom-code`, and `loom` (the agent guide the server image ships and `mentor.guide` serves) | -| `scripts/` | `codegen/` (generators), `gates/` (CI ratchets and guards), `ops/` (operator tools), `scip_harness/` (compiler-tier producers), `docs_site/` (the documentation site's hook, theme override, pinned builder and IndexNow submission), `i18n/` (the translation generator and its freshness check) | -| `tests/` | `unit/`, `integration/`, `analyzer/`, `code_lanes/`, `fixtures/` (below) | -| `examples/` | runnable integration examples (`claude_agent_loop.py`, `ledger_run.py`, `log_conversation.py`, `onboarding_walkthrough.py`), and the course starter a teacher copies into a repository of their own (`course-starter/`, [teaching](../guides/teaching.md#hand-out-the-labs-as-an-assignment)) | -| `i18n/` | machine translations of the README, the quickstart and the use-case pages into six languages, one folder per language; generated by `scripts/i18n/translate.py` (`.github/workflows/i18n.yml`), never edited by hand | -| `docs/` | this documentation; `mkdocs.yml` and `scripts/docs_site/` build it as the documentation site (`.github/workflows/docs-site.yml`) | -| `.github/` | CI, release and scan workflows (`workflows/`), issue and pull-request templates, and `social-preview.png`, the image uploaded in Settings → General → Social preview (GitHub reads only the uploaded copy) | -| `.devcontainer/` | the GitHub Codespaces try-out: a dev container that installs the latest release with the installer and connects Claude Code; not a development environment ([quickstart](../getting-started/quickstart.md#try-it-in-github-codespaces)) | -| `Dockerfile`, `Makefile`, `redeploy.sh`, `pyproject.toml`, `uv.lock` | the server's image, the task runner, the blue/green deploy script, the server package and its lock file | -| `server.json`, `context7.json`, `CITATION.cff`, `gemini-extension.json`, `.claude-plugin/`, `.agents/plugins/` | the MCP Registry listing, the docs-index config, the citation GitHub shows as "Cite this repository", the Gemini CLI extension manifest, the Claude Code marketplace with the `loom-code` skill manifest, the Codex marketplace | -| `llms-install.md` | the steps a coding agent follows to install Loom and add it as an MCP server | -| `AGENTS.md`, `CLAUDE.md` | the instructions every coding agent reads; `CLAUDE.md` imports `AGENTS.md` | -| `.claude/`, `.agents/skills/` | the agents' skills, path-scoped rules, the read-only reviewer subagent and its hook, and project permission settings; `.agents/skills/` links each skill for Codex | +| Path | Holds | +| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `server/` | the FastAPI server: domain packages (memory, code, tracker, …), the operation registry, workers, transports, CLI, settings | +| `extractor/` | the reference extractor service (`loom_extractor/`): format detection and the document parsers, run outside the server; its image (`Dockerfile`, released as `ghcr.io/clickhouse/loom-extractor`) and lock (`uv.lock`); see [document extraction](../architecture/document-extraction.md) | +| `sdk/python/` | the Python SDK, published as `clickhouse-loom` (`sdk/python/loom/`) | +| `sdk/typescript/` | the TypeScript SDK, published as `@clickhouse/loom` (`sdk/typescript/src/`) | +| `frontend/` | the React dashboard served at `/` (Vite + Tailwind); `src/`, Playwright specs in `e2e/`, `scripts/bundle_budget.mjs` | +| `schemas/` | `migrations/` (numbered SQL), `schema.sql` (generated current shape), `otel/` (ClickStack OTel tables), `ops/` (hand-run SQL); see [`schemas/README.md`](../../schemas/README.md) | +| `dev/` | compose stacks, operator scripts (`loom_ingest.py`, `loom_init.py`, `onboard_tenant.py`, backup and restore, `verify_audit_chain.py`), `ci_start_clickhouse.sh`, `redeploy_preflight.sh` | +| `deploy/` | ClickHouse server config (`clickhouse-config/`), the Lemmagen3 model (`lemmagen3/`), the blue/green proxy (`proxy/`), the Helm chart (`helm/`), the repository-job sandbox AppArmor profile (`apparmor/`), the standalone env template (`standalone/`), the scheduled namespace copy CronJob (`okf-sync/`), dashboards (`dashboards/`, `hyperdx_dashboards.md`, `clickstack_sources.sh`) | +| `bench/` | benchmark harnesses and gates, their fixtures (`fixtures/`), datasets, rubrics, acceptance and skill evals; see [benchmarks](../benchmarks/overview.md) | +| `integrations/` | client integrations: the Claude Code and Codex plugins, the Cline hooks, the grep shim, Cursor and generic transcript hooks, the OKF CI gate | +| `skills/` | the standalone Agent Skills: `loom-code`, and `loom` (the agent guide the server image ships and `mentor.guide` serves) | +| `scripts/` | `codegen/` (generators), `gates/` (CI ratchets and guards), `ops/` (operator tools), `scip_harness/` (compiler-tier producers), `docs_site/` (the documentation site's hook, theme override, pinned builder and IndexNow submission), `i18n/` (the translation generator and its freshness check) | +| `tests/` | `unit/`, `integration/`, `analyzer/`, `code_lanes/`, `fixtures/` (below) | +| `examples/` | runnable integration examples (`claude_agent_loop.py`, `ledger_run.py`, `log_conversation.py`, `onboarding_walkthrough.py`), and the course starter a teacher copies into a repository of their own (`course-starter/`, [teaching](../guides/teaching.md#hand-out-the-labs-as-an-assignment)) | +| `i18n/` | machine translations of the README, the quickstart and the use-case pages into six languages, one folder per language; generated by `scripts/i18n/translate.py` (`.github/workflows/i18n.yml`), never edited by hand | +| `docs/` | this documentation; `mkdocs.yml` and `scripts/docs_site/` build it as the documentation site (`.github/workflows/docs-site.yml`) | +| `.github/` | CI, release and scan workflows (`workflows/`), issue and pull-request templates, and `social-preview.png`, the image uploaded in Settings → General → Social preview (GitHub reads only the uploaded copy) | +| `.devcontainer/` | the GitHub Codespaces try-out: a dev container that installs the latest release with the installer and connects Claude Code; not a development environment ([quickstart](../getting-started/quickstart.md#try-it-in-github-codespaces)) | +| `Dockerfile`, `Makefile`, `redeploy.sh`, `pyproject.toml`, `uv.lock` | the server's image, the task runner, the blue/green deploy script, the server package and its lock file | +| `server.json`, `context7.json`, `CITATION.cff`, `gemini-extension.json`, `.claude-plugin/`, `.cursor-plugin/`, `.agents/plugins/` | the MCP Registry listing, the docs-index config, the citation GitHub shows as "Cite this repository", the Gemini CLI extension manifest, the Claude Code marketplace with the `loom-code` skill manifest, the Cursor marketplace and plugin, the Codex marketplace | +| `llms-install.md` | the steps a coding agent follows to install Loom and add it as an MCP server | +| `AGENTS.md`, `CLAUDE.md` | the instructions every coding agent reads; `CLAUDE.md` imports `AGENTS.md` | +| `.claude/`, `.agents/skills/` | the agents' skills, path-scoped rules, the read-only reviewer subagent and its hook, and project permission settings; `.agents/skills/` links each skill for Codex | ## Inside server/ diff --git a/docs/features/integrations/cursor.md b/docs/features/integrations/cursor.md index 43a939fa4c..a091d2f2a2 100644 --- a/docs/features/integrations/cursor.md +++ b/docs/features/integrations/cursor.md @@ -2,13 +2,31 @@ Cursor gets Loom in two independent pieces: -| Piece | What it gives | How | -| ------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| MCP tools | the `loom_*` tools in Cursor's agent | the [install link](#mcp-tools) for a local single-user server, else `loom install --client cursor` ([MCP clients](mcp-clients.md)) | -| Transcript capture | each conversation's turns in `conversation.append` | the `sessionEnd` hook `integrations/cursor/cursor-session-hook.sh` | - -There is no Cursor plugin, so no code shunt and no capture of tool calls, runs or -working memory; the [Claude Code](claude-code.md) and [Codex](codex.md) plugins have those. +| Piece | What it gives | How | +| ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| MCP tools | the `loom_*` tools in Cursor's agent | the [plugin](#plugin), the [install link](#mcp-tools) for a local single-user server, or `loom install --client cursor` ([MCP clients](mcp-clients.md)) | +| Transcript capture | each conversation's turns in `conversation.append` | the `sessionEnd` hook `integrations/cursor/cursor-session-hook.sh` | + +The Cursor plugin carries the MCP entry and the `loom` and `loom-code` skills, and has no +hooks: no code shunt and no capture of tool calls, runs or working memory; the +[Claude Code](claude-code.md) and [Codex](codex.md) plugins have those. + +## Plugin + +The repository is a Cursor plugin marketplace: `.cursor-plugin/` at its root holds the +`clickhouse-loom` plugin, which installs the `loom` MCP server and the root `skills/`. The +plugin asks for one value, **Loom MCP URL**, set when it is installed or later under +**Configure**: + +| Server | Loom MCP URL | Sign-in | +| ------------------------------------------ | -------------------------------------------------------- | ------------------------- | +| single-user, on the same machine | `http://localhost:7777/mcp?toolset=coding` (the default) | none | +| team server with `LOOM_OAUTH_ENABLED=true` | `https:///mcp?toolset=coding` | browser, on first connect | + +The entry sends no `Authorization` header, so a team server without OAuth answers 401; +for one, write the entry with a token through `loom install --client cursor` below. +[Clients that sign in by browser](mcp-clients.md#clients-that-sign-in-by-browser) has +the OAuth details. ## MCP tools diff --git a/scripts/release/prepare.py b/scripts/release/prepare.py index 91e1d67d65..4d01b607af 100755 --- a/scripts/release/prepare.py +++ b/scripts/release/prepare.py @@ -67,6 +67,7 @@ class Pin(NamedTuple): Pin("frontend/package-lock.json", _TOP_JSON), Pin("frontend/package-lock.json", _LOCK_ROOT), Pin(".claude-plugin/plugin.json", _TOP_JSON), + Pin(".cursor-plugin/plugin.json", _TOP_JSON), Pin("gemini-extension.json", _TOP_JSON), Pin("skills/loom-code/SKILL.md", r'^ version: "(?P[^"]+)"$'), Pin("skills/loom/SKILL.md", r'^ version: "(?P[^"]+)"$'), diff --git a/tests/unit/test_cursor_plugin.py b/tests/unit/test_cursor_plugin.py new file mode 100644 index 0000000000..a7f9479a72 --- /dev/null +++ b/tests/unit/test_cursor_plugin.py @@ -0,0 +1,53 @@ +"""The Cursor plugin at the repository root: `.cursor-plugin/` holds the marketplace, the +manifest and its MCP entry, and the plugin's skills are the root `skills/`.""" + +from __future__ import annotations + +import json +import posixpath +import re +from pathlib import Path + +from server.identity.app.token_clients import client_config + +ROOT = Path(__file__).resolve().parents[2] +PLUGIN_DIR = ROOT / ".cursor-plugin" +MANIFEST = json.loads((PLUGIN_DIR / "plugin.json").read_text()) +MARKETPLACE = json.loads((PLUGIN_DIR / "marketplace.json").read_text()) + + +def test_the_marketplace_lists_the_root_plugin_by_its_name() -> None: + (entry,) = MARKETPLACE["plugins"] + assert entry["source"] == "./" + assert entry["name"] == MANIFEST["name"] + + +def test_manifest_paths_are_relative_and_exist() -> None: + # Cursor's review refuses an absolute path or one that leaves the plugin. + for field in ("logo", "skills", "mcpServers"): + path = MANIFEST[field] + assert not path.startswith("/") and not posixpath.normpath(path).startswith(".."), path + assert (ROOT / path).exists(), path + + +def test_every_variable_the_mcp_entry_uses_is_declared_and_required() -> None: + entry = (ROOT / MANIFEST["mcpServers"]).read_text() + used = set(re.findall(r"\$\{(\w+)\}", entry)) + variables = MANIFEST["variables"] + assert used and used == set(variables["properties"]) == set(variables["required"]) + + +def test_the_default_url_is_the_one_loom_install_writes_for_cursor() -> None: + # The entry has no Authorization header: a single-user server on the machine takes the + # call without one, and a server with OAuth on answers 401 with the metadata pointer + # Cursor follows to its browser sign-in. + entry = json.loads((ROOT / MANIFEST["mcpServers"]).read_text())["mcpServers"]["loom"] + assert entry == {"url": "${LOOM_MCP_URL}"} + local = client_config("cursor", "http://localhost:7777/mcp", "") + default = MANIFEST["variables"]["properties"]["LOOM_MCP_URL"]["default"] + assert default == local["config"]["mcpServers"]["loom"]["url"] + + +def test_the_plugin_ships_the_root_skills() -> None: + names = {p.parent.name for p in (ROOT / MANIFEST["skills"]).glob("*/SKILL.md")} + assert names == {"loom", "loom-code"} diff --git a/tests/unit/test_published_links.py b/tests/unit/test_published_links.py index a50e7356d1..3c9dc6eb8a 100644 --- a/tests/unit/test_published_links.py +++ b/tests/unit/test_published_links.py @@ -44,6 +44,7 @@ def test_published_links_resolve() -> None: for f in ( "server.json", ".claude-plugin/plugin.json", + ".cursor-plugin/plugin.json", "integrations/claude-code-plugin/.claude-plugin/plugin.json", "integrations/codex-plugin/.codex-plugin/plugin.json", "pyproject.toml", From ce1336cd85963f10ba5907e9ec5aa3a9e560199a Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Sun, 15 Nov 2026 08:45:43 +0000 Subject: [PATCH 2/9] The Cursor plugin docs name the team marketplace route and the bare OAuth URL Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- .claude/skills/loom-pre-push/SKILL.md | 2 +- .cursor-plugin/plugin.json | 2 +- README.md | 6 +++--- docs/development/release-process.md | 2 +- docs/features/integrations/cursor.md | 31 ++++++++++++++++----------- docs/features/integrations/index.md | 2 +- llms.txt | 2 +- skills/loom-code/SKILL.md | 4 ++-- tests/unit/test_cursor_plugin.py | 10 +++++---- 9 files changed, 35 insertions(+), 26 deletions(-) diff --git a/.claude/skills/loom-pre-push/SKILL.md b/.claude/skills/loom-pre-push/SKILL.md index fc001d9891..95a602d752 100644 --- a/.claude/skills/loom-pre-push/SKILL.md +++ b/.claude/skills/loom-pre-push/SKILL.md @@ -41,7 +41,7 @@ Run them in the worktree's `.venv`, on CI's Python (3.12), with `LOOM_ENV_FILE=` | `server/workers/` | `LOOM_UPDATE_WORKER_SNAPSHOT=1 .venv/bin/python -m pytest tests/unit/test_worker_registry_snapshot.py` for an intended change | | server behaviour | the integration suite against a private server (`loom-dev-setup` §7) | | auth, write paths, erasure, migrations, the worker supervisor | the per-module branch-coverage floors CI enforces: `make test-unit-cov` (about 30 minutes on two cores, less with more) | -| `integrations/`, `.claude-plugin/` | `.venv/bin/python -m scripts.codegen.agent_plugin_sync`; `claude plugin validate integrations/claude-code-plugin --profile directory --strict` and `claude plugin validate .` (the plugin and the marketplace listing); `node --test integrations/claude-code-plugin/tests/*.test.mjs`, `node --test integrations/grep-shim/tests/*.test.mjs`, `node --test integrations/cline/tests/*.test.mjs`, `bash integrations/cursor/test.sh`, `PYTHON=.venv/bin/python bash integrations/generic/test.sh`, and CI's loops: `node --check` over every hook, helper, shim and adapter `.mjs`, `sh -n` over `integrations/{claude-code-plugin,codex-plugin}/bin/loom-node` and `integrations/cline/hooks/*`, and `test -x` over `integrations/grep-shim/bin/*` and `integrations/cline/hooks/*` (job `agent-plugins` in `.github/workflows/ci.yml`); with `claude` or `codex` installed, `node integrations/claude-code-plugin/tests/e2e/agent-session.mjs claude --bin --port ` (`codex` needs port 7777 free, the URL its plugin ships; the other platforms run in `.github/workflows/plugin-platforms.yml`); for a behaviour change, both manifests bumped to a version no open PR uses | +| `integrations/`, `.claude-plugin/`, `.cursor-plugin/` | `.venv/bin/python -m scripts.codegen.agent_plugin_sync`; `claude plugin validate integrations/claude-code-plugin --profile directory --strict` and `claude plugin validate .` (the plugin and the marketplace listing); `node --test integrations/claude-code-plugin/tests/*.test.mjs`, `node --test integrations/grep-shim/tests/*.test.mjs`, `node --test integrations/cline/tests/*.test.mjs`, `bash integrations/cursor/test.sh`, `PYTHON=.venv/bin/python bash integrations/generic/test.sh`, and CI's loops: `node --check` over every hook, helper, shim and adapter `.mjs`, `sh -n` over `integrations/{claude-code-plugin,codex-plugin}/bin/loom-node` and `integrations/cline/hooks/*`, and `test -x` over `integrations/grep-shim/bin/*` and `integrations/cline/hooks/*` (job `agent-plugins` in `.github/workflows/ci.yml`); with `claude` or `codex` installed, `node integrations/claude-code-plugin/tests/e2e/agent-session.mjs claude --bin --port ` (`codex` needs port 7777 free, the URL its plugin ships; the other platforms run in `.github/workflows/plugin-platforms.yml`); for a behaviour change, both manifests bumped to a version no open PR uses; for `.cursor-plugin/`, `.venv/bin/python -m pytest tests/unit/test_cursor_plugin.py` | | `frontend/` | `npm --prefix frontend run test && npm --prefix frontend run build && npm --prefix frontend run budget`; the Playwright run CI adds (`npx --prefix frontend playwright install chromium` once (its system libraries, `playwright install-deps`, only on a machine you own), then `E2E_PORT= npm --prefix frontend run e2e`); `make lint` covers the accessibility rules | | `deploy/helm/` | the commands of CI's "lint and validate every overlay" step (`.github/workflows/ci.yml`, job `helm`): a `secrets.jwtSecret` of at least 32 characters (CI uses `openssl rand -hex 32`; `helm lint` passes a shorter one, the kind overlay's `helm template` refuses it), `helm lint --strict` and `helm template … \| kubeconform -strict -kubernetes-version 1.30.0` for each overlay, once more with every optional object on; then the job's `scripts/gates/helm_extractor_isolation.py`, `scripts/gates/helm_metadata_egress.py` and `scripts/gates/helm_assistant_isolation.py` | | `extractor/`, `compose.yaml` | the extractor tests (`.venv/bin/python -m pytest tests/unit/test_extractor_service.py tests/unit/test_compose_extractor_service.py`), then push and read `docker-smoke.yml`'s Quickstart jobs, which build both images and run the installed stack's extractor probes; `dev/docker-compose.dev.yml` is checked by that compose test and `make dev`, no CI job runs it | diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 9eb90bc9fb..5dbda0443f 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -25,7 +25,7 @@ "LOOM_MCP_URL": { "type": "string", "title": "Loom MCP URL", - "description": "Your Loom server's MCP endpoint on the coding toolset: http://localhost:7777/mcp?toolset=coding for a single-user server on this machine, or https:///mcp?toolset=coding for a team server with browser sign-in", + "description": "Your Loom server's MCP endpoint on the coding toolset: http://localhost:7777/mcp?toolset=coding for a single-user server on this machine, or https:///mcp for a team server with browser sign-in", "default": "http://localhost:7777/mcp?toolset=coding" } }, diff --git a/README.md b/README.md index 9afbdb78ec..3ba9b49f22 100644 --- a/README.md +++ b/README.md @@ -210,9 +210,9 @@ Start a new session; the first one connects to `http://localhost:7777`. In Codex `codex` interactively once and approve the plugin's hooks; until then only the tools work. Tell the agent something worth keeping, then ask about it in the next session. -For Cursor, the [Cursor plugin](./docs/features/integrations/cursor.md#plugin) installs -the MCP entry and Loom's skills; its one setting is the server's MCP URL. On the machine -running a personal installation, the button below adds the +For Cursor, a team admin can import this repository as a team marketplace; its +[Cursor plugin](./docs/features/integrations/cursor.md#plugin) installs the MCP entry and +Loom's skills. On the machine running a personal installation, the button below adds the [local MCP entry](./docs/features/integrations/cursor.md#mcp-tools), which needs no token: [![Add Loom to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=loom&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojc3NzcvbWNwP3Rvb2xzZXQ9Y29kaW5nIn0%3D) diff --git a/docs/development/release-process.md b/docs/development/release-process.md index 698bd30238..3ca1314165 100644 --- a/docs/development/release-process.md +++ b/docs/development/release-process.md @@ -1,6 +1,6 @@ # Release process -Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`) and the Gemini CLI extension share one version `X.Y.Z`. The two coding-agent plugins share their own version, bumped on a behaviour change to any file the plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`): installed clients pick up a hook change only through a new plugin version. `MIN_SERVER_VERSION` in the plugins' `lib/server-version.mjs` names the oldest server their hooks support: when the server's `GET /v1/health` reports an older `version`, SessionStart prints one `loom:` line asking for a server upgrade, and says nothing when the version cannot be read. It rises with a release ([cutting the release](#cutting-the-release), step 2). +Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`), the Cursor plugin that ships them and the Gemini CLI extension share one version `X.Y.Z`. The Claude Code and Codex plugins share their own version, bumped on a behaviour change to any file the plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`): installed clients pick up a hook change only through a new plugin version. `MIN_SERVER_VERSION` in the plugins' `lib/server-version.mjs` names the oldest server their hooks support: when the server's `GET /v1/health` reports an older `version`, SessionStart prints one `loom:` line asking for a server upgrade, and says nothing when the version cannot be read. It rises with a release ([cutting the release](#cutting-the-release), step 2). ## Where the version lives diff --git a/docs/features/integrations/cursor.md b/docs/features/integrations/cursor.md index a091d2f2a2..167be68e62 100644 --- a/docs/features/integrations/cursor.md +++ b/docs/features/integrations/cursor.md @@ -13,18 +13,25 @@ hooks: no code shunt and no capture of tool calls, runs or working memory; the ## Plugin -The repository is a Cursor plugin marketplace: `.cursor-plugin/` at its root holds the -`clickhouse-loom` plugin, which installs the `loom` MCP server and the root `skills/`. The -plugin asks for one value, **Loom MCP URL**, set when it is installed or later under -**Configure**: - -| Server | Loom MCP URL | Sign-in | -| ------------------------------------------ | -------------------------------------------------------- | ------------------------- | -| single-user, on the same machine | `http://localhost:7777/mcp?toolset=coding` (the default) | none | -| team server with `LOOM_OAUTH_ENABLED=true` | `https:///mcp?toolset=coding` | browser, on first connect | - -The entry sends no `Authorization` header, so a team server without OAuth answers 401; -for one, write the entry with a token through `loom install --client cursor` below. +`.cursor-plugin/` at the repository root makes it a Cursor plugin marketplace with one +plugin, `clickhouse-loom`: the `loom` MCP server and the root `skills/`. The plugin is +not yet listed in Cursor's marketplace and has not been installed in a Cursor build. On +a Teams or Enterprise plan, a team admin adds it under **Dashboard → Plugins & MCPs → +Add Marketplace → Import from Repo** with `https://github.com/ClickHouse/loom`, and +members install it from **Customize**. + +The plugin has one variable, **Loom MCP URL**, whose value is set in Cursor's dashboard +under **Plugins**; for a team marketplace the team admin sets it for every member. + +| Server | Loom MCP URL | Sign-in | +| ------------------------------------------ | -------------------------------------------------------- | ------------------- | +| single-user, on each member's machine | `http://localhost:7777/mcp?toolset=coding` (the default) | none | +| team server with `LOOM_OAUTH_ENABLED=true` | `https:///mcp` | browser, per person | + +A server with OAuth on takes the bare URL, the resource its protected-resource metadata +names; tools outside its default toolset run through `loom_op`. The entry sends no +`Authorization` header, so a team server without OAuth answers 401; for one, write the +entry with a token through `loom install --client cursor` below. [Clients that sign in by browser](mcp-clients.md#clients-that-sign-in-by-browser) has the OAuth details. diff --git a/docs/features/integrations/index.md b/docs/features/integrations/index.md index eba817368a..2590e676a3 100644 --- a/docs/features/integrations/index.md +++ b/docs/features/integrations/index.md @@ -22,7 +22,7 @@ opt-in; one you leave unconfigured does nothing. They fall into three groups: | Gemini CLI | extension: MCP tools and the `loom`, `loom-code` skills | `gemini extensions install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | | JetBrains, Visual Studio, Neovim, Emacs and other agents | MCP client config | [other editors and agents](mcp-clients.md#other-editors-and-agents) | | Cline CLI (experimental) | hooks: session primer, prompt recall, a file's memories on a read | `integrations/cline/`: [README](../../../integrations/cline/README.md) | -| Cursor | MCP tools + `sessionEnd` transcript hook | `integrations/cursor/`: [cursor.md](cursor.md) | +| Cursor | MCP tools and skills (plugin) + `sessionEnd` transcript hook | `.cursor-plugin/`, `integrations/cursor/`: [cursor.md](cursor.md) | | Any Agent-Skills client | the `loom` and `loom-code` skills, no hooks | `skills/loom/`, `skills/loom-code/`: [below](#coding-agents) | | Aider, Continue, OpenCode, JetBrains AI | transcript capture template | `integrations/generic/`: [below](#transcript-capture-hooks) | | Agents that only use shell grep | the grep shim | `integrations/grep-shim/`: [grep-shim.md](grep-shim.md) | diff --git a/llms.txt b/llms.txt index 7778c409bc..51e05217e5 100644 --- a/llms.txt +++ b/llms.txt @@ -174,7 +174,7 @@ Start with docs/index.md (the map). To install Loom, a coding agent reads docs/g - [Extend Loom](docs/development/extending-loom.md): Loom has one registry per kind of thing: operations, workers, settings, providers, language lanes, extraction steps and tracker sources. - [Local development](docs/development/local-development.md): This page sets up a checkout for working on Loom's code. - [Migrations](docs/development/migrations.md): This page holds the rules for writing a migration. -- [Release process](docs/development/release-process.md): Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`) and the Gemini CLI extension share one version `X.Y.Z`. +- [Release process](docs/development/release-process.md): Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`), the Cursor plugin that ships them and the Gemini CLI extension share one version `X.Y.Z`. - [Repository guide](docs/development/repository-guide.md): What every top-level directory holds, where a concern lives inside `server/`, the order to read the code in, and the conventions a pull request fails without. - [Testing](docs/development/testing.md): Which suite a test belongs in, what each suite needs to run, how tests skip when their environment is missing, which gates CI enforces, and how to regenerate what they pin. diff --git a/skills/loom-code/SKILL.md b/skills/loom-code/SKILL.md index 50b61186ba..2f2b4d1591 100644 --- a/skills/loom-code/SKILL.md +++ b/skills/loom-code/SKILL.md @@ -83,8 +83,8 @@ router still works through the shell. ## Install -Install either this skill (`loom-code-skill`) or the `loom` plugin, not -both: the plugin ships its own skill named `loom-code`. +In Claude Code, install either this skill (`loom-code-skill`) or the `loom` +plugin, not both: the plugin ships its own skill named `loom-code`. ## Identity diff --git a/tests/unit/test_cursor_plugin.py b/tests/unit/test_cursor_plugin.py index a7f9479a72..7246726f9e 100644 --- a/tests/unit/test_cursor_plugin.py +++ b/tests/unit/test_cursor_plugin.py @@ -8,7 +8,10 @@ import re from pathlib import Path -from server.identity.app.token_clients import client_config +from server.cli._client import DEFAULT_BASE_URL +from server.cli.install import _install_mcp_url +from server.identity.app.token_clients import CODING_TOOLSET +from tests.unit.test_loom_code_skill import ROOT_SKILLS ROOT = Path(__file__).resolve().parents[2] PLUGIN_DIR = ROOT / ".cursor-plugin" @@ -43,11 +46,10 @@ def test_the_default_url_is_the_one_loom_install_writes_for_cursor() -> None: # Cursor follows to its browser sign-in. entry = json.loads((ROOT / MANIFEST["mcpServers"]).read_text())["mcpServers"]["loom"] assert entry == {"url": "${LOOM_MCP_URL}"} - local = client_config("cursor", "http://localhost:7777/mcp", "") default = MANIFEST["variables"]["properties"]["LOOM_MCP_URL"]["default"] - assert default == local["config"]["mcpServers"]["loom"]["url"] + assert default == _install_mcp_url(DEFAULT_BASE_URL, CODING_TOOLSET) def test_the_plugin_ships_the_root_skills() -> None: names = {p.parent.name for p in (ROOT / MANIFEST["skills"]).glob("*/SKILL.md")} - assert names == {"loom", "loom-code"} + assert names == set(ROOT_SKILLS) From f76ff139ba2c913332e2209240428a2dfaa54a4c Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Sun, 15 Nov 2026 08:53:12 +0000 Subject: [PATCH 3/9] The Cursor plugin docs say only what Cursor documents, and its gate row stands alone Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- .claude/skills/loom-pre-push/SKILL.md | 3 ++- .cursor-plugin/plugin.json | 2 +- README.md | 9 +++++---- docs/development/release-process.md | 2 +- docs/features/integrations/cursor.md | 11 +++++------ tests/unit/test_cursor_plugin.py | 3 ++- 6 files changed, 16 insertions(+), 14 deletions(-) diff --git a/.claude/skills/loom-pre-push/SKILL.md b/.claude/skills/loom-pre-push/SKILL.md index 95a602d752..ad6b32cf7d 100644 --- a/.claude/skills/loom-pre-push/SKILL.md +++ b/.claude/skills/loom-pre-push/SKILL.md @@ -41,7 +41,8 @@ Run them in the worktree's `.venv`, on CI's Python (3.12), with `LOOM_ENV_FILE=` | `server/workers/` | `LOOM_UPDATE_WORKER_SNAPSHOT=1 .venv/bin/python -m pytest tests/unit/test_worker_registry_snapshot.py` for an intended change | | server behaviour | the integration suite against a private server (`loom-dev-setup` §7) | | auth, write paths, erasure, migrations, the worker supervisor | the per-module branch-coverage floors CI enforces: `make test-unit-cov` (about 30 minutes on two cores, less with more) | -| `integrations/`, `.claude-plugin/`, `.cursor-plugin/` | `.venv/bin/python -m scripts.codegen.agent_plugin_sync`; `claude plugin validate integrations/claude-code-plugin --profile directory --strict` and `claude plugin validate .` (the plugin and the marketplace listing); `node --test integrations/claude-code-plugin/tests/*.test.mjs`, `node --test integrations/grep-shim/tests/*.test.mjs`, `node --test integrations/cline/tests/*.test.mjs`, `bash integrations/cursor/test.sh`, `PYTHON=.venv/bin/python bash integrations/generic/test.sh`, and CI's loops: `node --check` over every hook, helper, shim and adapter `.mjs`, `sh -n` over `integrations/{claude-code-plugin,codex-plugin}/bin/loom-node` and `integrations/cline/hooks/*`, and `test -x` over `integrations/grep-shim/bin/*` and `integrations/cline/hooks/*` (job `agent-plugins` in `.github/workflows/ci.yml`); with `claude` or `codex` installed, `node integrations/claude-code-plugin/tests/e2e/agent-session.mjs claude --bin --port ` (`codex` needs port 7777 free, the URL its plugin ships; the other platforms run in `.github/workflows/plugin-platforms.yml`); for a behaviour change, both manifests bumped to a version no open PR uses; for `.cursor-plugin/`, `.venv/bin/python -m pytest tests/unit/test_cursor_plugin.py` | +| `integrations/`, `.claude-plugin/` | `.venv/bin/python -m scripts.codegen.agent_plugin_sync`; `claude plugin validate integrations/claude-code-plugin --profile directory --strict` and `claude plugin validate .` (the plugin and the marketplace listing); `node --test integrations/claude-code-plugin/tests/*.test.mjs`, `node --test integrations/grep-shim/tests/*.test.mjs`, `node --test integrations/cline/tests/*.test.mjs`, `bash integrations/cursor/test.sh`, `PYTHON=.venv/bin/python bash integrations/generic/test.sh`, and CI's loops: `node --check` over every hook, helper, shim and adapter `.mjs`, `sh -n` over `integrations/{claude-code-plugin,codex-plugin}/bin/loom-node` and `integrations/cline/hooks/*`, and `test -x` over `integrations/grep-shim/bin/*` and `integrations/cline/hooks/*` (job `agent-plugins` in `.github/workflows/ci.yml`); with `claude` or `codex` installed, `node integrations/claude-code-plugin/tests/e2e/agent-session.mjs claude --bin --port ` (`codex` needs port 7777 free, the URL its plugin ships; the other platforms run in `.github/workflows/plugin-platforms.yml`); for a behaviour change, both manifests bumped to a version no open PR uses | +| `.cursor-plugin/` | `.venv/bin/python -m pytest tests/unit/test_cursor_plugin.py tests/unit/test_release_prepare.py`; its version follows the server's and is never bumped on its own | | `frontend/` | `npm --prefix frontend run test && npm --prefix frontend run build && npm --prefix frontend run budget`; the Playwright run CI adds (`npx --prefix frontend playwright install chromium` once (its system libraries, `playwright install-deps`, only on a machine you own), then `E2E_PORT= npm --prefix frontend run e2e`); `make lint` covers the accessibility rules | | `deploy/helm/` | the commands of CI's "lint and validate every overlay" step (`.github/workflows/ci.yml`, job `helm`): a `secrets.jwtSecret` of at least 32 characters (CI uses `openssl rand -hex 32`; `helm lint` passes a shorter one, the kind overlay's `helm template` refuses it), `helm lint --strict` and `helm template … \| kubeconform -strict -kubernetes-version 1.30.0` for each overlay, once more with every optional object on; then the job's `scripts/gates/helm_extractor_isolation.py`, `scripts/gates/helm_metadata_egress.py` and `scripts/gates/helm_assistant_isolation.py` | | `extractor/`, `compose.yaml` | the extractor tests (`.venv/bin/python -m pytest tests/unit/test_extractor_service.py tests/unit/test_compose_extractor_service.py`), then push and read `docker-smoke.yml`'s Quickstart jobs, which build both images and run the installed stack's extractor probes; `dev/docker-compose.dev.yml` is checked by that compose test and `make dev`, no CI job runs it | diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 5dbda0443f..98182b16c0 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -25,7 +25,7 @@ "LOOM_MCP_URL": { "type": "string", "title": "Loom MCP URL", - "description": "Your Loom server's MCP endpoint on the coding toolset: http://localhost:7777/mcp?toolset=coding for a single-user server on this machine, or https:///mcp for a team server with browser sign-in", + "description": "Your Loom server's MCP endpoint: http://localhost:7777/mcp?toolset=coding when each member runs a single-user server, or https:///mcp for a team server with browser sign-in", "default": "http://localhost:7777/mcp?toolset=coding" } }, diff --git a/README.md b/README.md index 3ba9b49f22..ee42b1f20a 100644 --- a/README.md +++ b/README.md @@ -210,10 +210,11 @@ Start a new session; the first one connects to `http://localhost:7777`. In Codex `codex` interactively once and approve the plugin's hooks; until then only the tools work. Tell the agent something worth keeping, then ask about it in the next session. -For Cursor, a team admin can import this repository as a team marketplace; its -[Cursor plugin](./docs/features/integrations/cursor.md#plugin) installs the MCP entry and -Loom's skills. On the machine running a personal installation, the button below adds the -[local MCP entry](./docs/features/integrations/cursor.md#mcp-tools), which needs no token: +For Cursor, on a Teams or Enterprise plan, a team admin can import this repository as a +team marketplace; its [Cursor plugin](./docs/features/integrations/cursor.md#plugin) +installs the MCP entry and Loom's skills. On the machine running a personal installation, +the button below adds the [local MCP +entry](./docs/features/integrations/cursor.md#mcp-tools), which needs no token: [![Add Loom to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=loom&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojc3NzcvbWNwP3Rvb2xzZXQ9Y29kaW5nIn0%3D) diff --git a/docs/development/release-process.md b/docs/development/release-process.md index 3ca1314165..cc10f9c6a5 100644 --- a/docs/development/release-process.md +++ b/docs/development/release-process.md @@ -390,7 +390,7 @@ Agents and people find Loom through these listings. Each reads files in this rep | npm page of `@clickhouse/loom` | the metadata of `sdk/typescript/package.json`, and `sdk/typescript/README.md` as the page body | the `npm` job on each dispatched release; the page shows the version tagged `latest`, which the job sets only for the highest final | | Claude plugin directory | `integrations/claude-code-plugin/.claude-plugin/plugin.json` (`displayName`, `description`, `keywords`, `icon`, `documentationUrl`, `supportUrl`, `privacyPolicyUrl`) and the README | submitted once in the developer portal; later versions are picked up from the tracked branch. The icon is read only on the first submission | | Claude Code plugin suggestions | the `relevance` block of the `loom` entry in `.claude-plugin/marketplace.json`: the `loom` command, Loom's config files, an SDK dependency in a manifest | read from the marketplace on the default branch; shown only where an administrator allowlists the marketplace (`pluginSuggestionMarketplaces`) | -| Cursor Marketplace | `.cursor-plugin/plugin.json` (`displayName`, `description`, `keywords`, `logo`, `variables`), `.cursor-plugin/marketplace.json` and the README | submitted once at cursor.com/marketplace/publish; Cursor reviews each update before it is listed | +| Cursor Marketplace | `.cursor-plugin/plugin.json` (`displayName`, `description`, `keywords`, `logo`, `variables`), `.cursor-plugin/marketplace.json` | submitted once at cursor.com/marketplace/publish; each listing is reviewed by hand | | Codex plugin directory | `integrations/codex-plugin/.codex-plugin/plugin.json` (`interface`) | submitted in the plugin portal; a plugin with lifecycle hooks is not eligible there, so the public listing needs a build without them | | Docs index for coding agents | `context7.json` | refreshed from the default branch after the repository is added once | | Agent Skills index | `skills/loom-code`, `skills/loom` and the Claude Code plugin's skills; the contributor skills are marked internal in their frontmatter and are not offered | ranked by `npx skills add ClickHouse/loom` installs; nothing to submit | diff --git a/docs/features/integrations/cursor.md b/docs/features/integrations/cursor.md index 167be68e62..de8bc2413e 100644 --- a/docs/features/integrations/cursor.md +++ b/docs/features/integrations/cursor.md @@ -15,13 +15,12 @@ hooks: no code shunt and no capture of tool calls, runs or working memory; the `.cursor-plugin/` at the repository root makes it a Cursor plugin marketplace with one plugin, `clickhouse-loom`: the `loom` MCP server and the root `skills/`. The plugin is -not yet listed in Cursor's marketplace and has not been installed in a Cursor build. On -a Teams or Enterprise plan, a team admin adds it under **Dashboard → Plugins & MCPs → -Add Marketplace → Import from Repo** with `https://github.com/ClickHouse/loom`, and -members install it from **Customize**. +not listed in Cursor's marketplace and has not been tested in Cursor. On a Teams or +Enterprise plan, a team admin adds it under **Dashboard → Plugins & MCPs → Add +Marketplace → Import from Repo** with `https://github.com/ClickHouse/loom`. -The plugin has one variable, **Loom MCP URL**, whose value is set in Cursor's dashboard -under **Plugins**; for a team marketplace the team admin sets it for every member. +The plugin has one variable, **Loom MCP URL**. A team admin sets it in Cursor's +dashboard under **Plugins**, for every member. | Server | Loom MCP URL | Sign-in | | ------------------------------------------ | -------------------------------------------------------- | ------------------- | diff --git a/tests/unit/test_cursor_plugin.py b/tests/unit/test_cursor_plugin.py index 7246726f9e..3925437385 100644 --- a/tests/unit/test_cursor_plugin.py +++ b/tests/unit/test_cursor_plugin.py @@ -10,7 +10,7 @@ from server.cli._client import DEFAULT_BASE_URL from server.cli.install import _install_mcp_url -from server.identity.app.token_clients import CODING_TOOLSET +from server.identity.app.token_clients import CODING_CLIENTS, CODING_TOOLSET from tests.unit.test_loom_code_skill import ROOT_SKILLS ROOT = Path(__file__).resolve().parents[2] @@ -47,6 +47,7 @@ def test_the_default_url_is_the_one_loom_install_writes_for_cursor() -> None: entry = json.loads((ROOT / MANIFEST["mcpServers"]).read_text())["mcpServers"]["loom"] assert entry == {"url": "${LOOM_MCP_URL}"} default = MANIFEST["variables"]["properties"]["LOOM_MCP_URL"]["default"] + assert "cursor" in CODING_CLIENTS assert default == _install_mcp_url(DEFAULT_BASE_URL, CODING_TOOLSET) From f7f0a2920e1395dcbd1285d5c4fdba1d538d643a Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Sun, 15 Nov 2026 09:10:28 +0000 Subject: [PATCH 4/9] The Cursor plugin is marked untested wherever it is offered, and its skills are listed as a piece Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- .claude/rules/plugins.md | 2 +- README.md | 6 +++--- docs/features/integrations/cursor.md | 3 ++- docs/features/integrations/index.md | 2 +- llms.txt | 2 +- tests/unit/test_cursor_plugin.py | 11 ++++++----- 6 files changed, 14 insertions(+), 12 deletions(-) diff --git a/.claude/rules/plugins.md b/.claude/rules/plugins.md index f88c0c2091..434d86734a 100644 --- a/.claude/rules/plugins.md +++ b/.claude/rules/plugins.md @@ -12,7 +12,7 @@ paths: - A behaviour change to any file the plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests (`integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json`) to a version no other open PR uses: two PRs with one version ship only the first. - A hook, `lib/` or `bin/` change that calls an op or a field the server does not serve yet says so in its changelog entry ("needs the next server release"), so the release notes list it: that release's pull request raises `MIN_SERVER_VERSION` in `lib/server-version.mjs` to its own version and bumps both plugin versions (clients get it only through a new version); a pull request on `main` before it never raises it (`tests/unit/test_codex_plugin.py` keeps it no newer than the server). Between such a hook's merge and that release, a server of the previous release gets no warning. - Hooks run inside a user's session: they never throw to the agent, never block past their timeout, never print a token, and degrade to silence when the server is unreachable. -- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here; a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case. +- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here (the `.cursor-plugin/` row for that directory); a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case. - Anything a hook sends to the server goes through `redactSecrets` / `redactHead`, redacting before truncating, and a diff through `diffHeaders`, which sends only its paths, hunk ranges and function names (`integrations/claude-code-plugin/lib/loom-client.mjs`); a new capture path that skips them is a finding. - An integration or its README is held to an open-source bar: the happy path runs end to end as written; an experimental feature says so and names the versions it was tested on; an upstream bug is filed upstream and linked; a cheap CI check keeps the example from rotting. - The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` (and `.cursor-plugin/plugin.json`, whose plugin ships them) plus each `metadata.version`, released with the server; `skills/loom/` is also what `mentor.guide` serves, so the image copies it ([release process](../../docs/development/release-process.md#where-the-version-lives)). diff --git a/README.md b/README.md index ee42b1f20a..3b3509b270 100644 --- a/README.md +++ b/README.md @@ -211,9 +211,9 @@ Start a new session; the first one connects to `http://localhost:7777`. In Codex work. Tell the agent something worth keeping, then ask about it in the next session. For Cursor, on a Teams or Enterprise plan, a team admin can import this repository as a -team marketplace; its [Cursor plugin](./docs/features/integrations/cursor.md#plugin) -installs the MCP entry and Loom's skills. On the machine running a personal installation, -the button below adds the [local MCP +team marketplace; its [Cursor plugin](./docs/features/integrations/cursor.md#plugin), +untested in Cursor, installs the MCP entry and Loom's skills. On the machine running a +personal installation, the button below adds the [local MCP entry](./docs/features/integrations/cursor.md#mcp-tools), which needs no token: [![Add Loom to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=loom&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojc3NzcvbWNwP3Rvb2xzZXQ9Y29kaW5nIn0%3D) diff --git a/docs/features/integrations/cursor.md b/docs/features/integrations/cursor.md index de8bc2413e..e5999a78a7 100644 --- a/docs/features/integrations/cursor.md +++ b/docs/features/integrations/cursor.md @@ -1,10 +1,11 @@ # Cursor -Cursor gets Loom in two independent pieces: +Cursor gets Loom in three independent pieces: | Piece | What it gives | How | | ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP tools | the `loom_*` tools in Cursor's agent | the [plugin](#plugin), the [install link](#mcp-tools) for a local single-user server, or `loom install --client cursor` ([MCP clients](mcp-clients.md)) | +| Skills | the `loom` and `loom-code` skills | the [plugin](#plugin) | | Transcript capture | each conversation's turns in `conversation.append` | the `sessionEnd` hook `integrations/cursor/cursor-session-hook.sh` | The Cursor plugin carries the MCP entry and the `loom` and `loom-code` skills, and has no diff --git a/docs/features/integrations/index.md b/docs/features/integrations/index.md index 2590e676a3..644f72ed12 100644 --- a/docs/features/integrations/index.md +++ b/docs/features/integrations/index.md @@ -22,7 +22,7 @@ opt-in; one you leave unconfigured does nothing. They fall into three groups: | Gemini CLI | extension: MCP tools and the `loom`, `loom-code` skills | `gemini extensions install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | | JetBrains, Visual Studio, Neovim, Emacs and other agents | MCP client config | [other editors and agents](mcp-clients.md#other-editors-and-agents) | | Cline CLI (experimental) | hooks: session primer, prompt recall, a file's memories on a read | `integrations/cline/`: [README](../../../integrations/cline/README.md) | -| Cursor | MCP tools and skills (plugin) + `sessionEnd` transcript hook | `.cursor-plugin/`, `integrations/cursor/`: [cursor.md](cursor.md) | +| Cursor | MCP tools, skills (untested plugin) + `sessionEnd` capture hook | `.cursor-plugin/`, `integrations/cursor/`: [cursor.md](cursor.md) | | Any Agent-Skills client | the `loom` and `loom-code` skills, no hooks | `skills/loom/`, `skills/loom-code/`: [below](#coding-agents) | | Aider, Continue, OpenCode, JetBrains AI | transcript capture template | `integrations/generic/`: [below](#transcript-capture-hooks) | | Agents that only use shell grep | the grep shim | `integrations/grep-shim/`: [grep-shim.md](grep-shim.md) | diff --git a/llms.txt b/llms.txt index 51e05217e5..2cfc91d799 100644 --- a/llms.txt +++ b/llms.txt @@ -62,7 +62,7 @@ Start with docs/index.md (the map). To install Loom, a coding agent reads docs/g - [Claude Code plugin](docs/features/integrations/claude-code.md): The `loom` plugin for Claude Code does three things in one install: - [ClickStack and HyperDX](docs/features/integrations/clickstack.md): Loom always emits OpenTelemetry; the HyperDX sources, dashboards and the erasure step need configuring. - [Codex plugin](docs/features/integrations/codex.md): The Codex plugin gives Codex the same Loom integration as Claude Code: MCP tools, hooks that capture the session and load a primer, and the code shunt. -- [Cursor](docs/features/integrations/cursor.md): Cursor gets Loom in two independent pieces: +- [Cursor](docs/features/integrations/cursor.md): Cursor gets Loom in three independent pieces: - [Agent frameworks and orchestrators](docs/features/integrations/frameworks.md): The SDKs ship adapters that present Loom through a framework's own memory or retrieval interface. - [The grep shim](docs/features/integrations/grep-shim.md): Needs Node 18 or later, a viewer token, and a repository in the code index. - [Integrations](docs/features/integrations/index.md): Loom on a bare ClickHouse service is a complete deployment. diff --git a/tests/unit/test_cursor_plugin.py b/tests/unit/test_cursor_plugin.py index 3925437385..c91e943170 100644 --- a/tests/unit/test_cursor_plugin.py +++ b/tests/unit/test_cursor_plugin.py @@ -26,7 +26,7 @@ def test_the_marketplace_lists_the_root_plugin_by_its_name() -> None: def test_manifest_paths_are_relative_and_exist() -> None: - # Cursor's review refuses an absolute path or one that leaves the plugin. + # Cursor's template validator refuses an absolute path or one that leaves the plugin. for field in ("logo", "skills", "mcpServers"): path = MANIFEST[field] assert not path.startswith("/") and not posixpath.normpath(path).startswith(".."), path @@ -40,12 +40,13 @@ def test_every_variable_the_mcp_entry_uses_is_declared_and_required() -> None: assert used and used == set(variables["properties"]) == set(variables["required"]) -def test_the_default_url_is_the_one_loom_install_writes_for_cursor() -> None: - # The entry has no Authorization header: a single-user server on the machine takes the - # call without one, and a server with OAuth on answers 401 with the metadata pointer - # Cursor follows to its browser sign-in. +def test_the_entry_sends_no_authorization_header() -> None: + # A local server takes the call without one; an OAuth server answers 401 for sign-in. entry = json.loads((ROOT / MANIFEST["mcpServers"]).read_text())["mcpServers"]["loom"] assert entry == {"url": "${LOOM_MCP_URL}"} + + +def test_the_default_url_is_the_one_loom_install_writes_for_cursor() -> None: default = MANIFEST["variables"]["properties"]["LOOM_MCP_URL"]["default"] assert "cursor" in CODING_CLIENTS assert default == _install_mcp_url(DEFAULT_BASE_URL, CODING_TOOLSET) From 928c8de1be7c64ab7950dec3b224a4e914172800 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Sun, 15 Nov 2026 09:34:06 +0000 Subject: [PATCH 5/9] Cursor's plugin route is offered on the MCP clients and connect pages, and its listing reads as not submitted Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- .claude/skills/loom-pre-push/SKILL.md | 2 +- docs/development/release-process.md | 2 +- docs/features/integrations/mcp-clients.md | 13 +++++++------ docs/getting-started/connect-a-coding-agent.md | 4 ++++ 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/.claude/skills/loom-pre-push/SKILL.md b/.claude/skills/loom-pre-push/SKILL.md index ad6b32cf7d..4ca1c8da67 100644 --- a/.claude/skills/loom-pre-push/SKILL.md +++ b/.claude/skills/loom-pre-push/SKILL.md @@ -42,7 +42,7 @@ Run them in the worktree's `.venv`, on CI's Python (3.12), with `LOOM_ENV_FILE=` | server behaviour | the integration suite against a private server (`loom-dev-setup` §7) | | auth, write paths, erasure, migrations, the worker supervisor | the per-module branch-coverage floors CI enforces: `make test-unit-cov` (about 30 minutes on two cores, less with more) | | `integrations/`, `.claude-plugin/` | `.venv/bin/python -m scripts.codegen.agent_plugin_sync`; `claude plugin validate integrations/claude-code-plugin --profile directory --strict` and `claude plugin validate .` (the plugin and the marketplace listing); `node --test integrations/claude-code-plugin/tests/*.test.mjs`, `node --test integrations/grep-shim/tests/*.test.mjs`, `node --test integrations/cline/tests/*.test.mjs`, `bash integrations/cursor/test.sh`, `PYTHON=.venv/bin/python bash integrations/generic/test.sh`, and CI's loops: `node --check` over every hook, helper, shim and adapter `.mjs`, `sh -n` over `integrations/{claude-code-plugin,codex-plugin}/bin/loom-node` and `integrations/cline/hooks/*`, and `test -x` over `integrations/grep-shim/bin/*` and `integrations/cline/hooks/*` (job `agent-plugins` in `.github/workflows/ci.yml`); with `claude` or `codex` installed, `node integrations/claude-code-plugin/tests/e2e/agent-session.mjs claude --bin --port ` (`codex` needs port 7777 free, the URL its plugin ships; the other platforms run in `.github/workflows/plugin-platforms.yml`); for a behaviour change, both manifests bumped to a version no open PR uses | -| `.cursor-plugin/` | `.venv/bin/python -m pytest tests/unit/test_cursor_plugin.py tests/unit/test_release_prepare.py`; its version follows the server's and is never bumped on its own | +| `.cursor-plugin/` | `.venv/bin/python -m pytest tests/unit/test_cursor_plugin.py tests/unit/test_release_prepare.py tests/unit/test_published_links.py`; its version follows the server's and is never bumped on its own | | `frontend/` | `npm --prefix frontend run test && npm --prefix frontend run build && npm --prefix frontend run budget`; the Playwright run CI adds (`npx --prefix frontend playwright install chromium` once (its system libraries, `playwright install-deps`, only on a machine you own), then `E2E_PORT= npm --prefix frontend run e2e`); `make lint` covers the accessibility rules | | `deploy/helm/` | the commands of CI's "lint and validate every overlay" step (`.github/workflows/ci.yml`, job `helm`): a `secrets.jwtSecret` of at least 32 characters (CI uses `openssl rand -hex 32`; `helm lint` passes a shorter one, the kind overlay's `helm template` refuses it), `helm lint --strict` and `helm template … \| kubeconform -strict -kubernetes-version 1.30.0` for each overlay, once more with every optional object on; then the job's `scripts/gates/helm_extractor_isolation.py`, `scripts/gates/helm_metadata_egress.py` and `scripts/gates/helm_assistant_isolation.py` | | `extractor/`, `compose.yaml` | the extractor tests (`.venv/bin/python -m pytest tests/unit/test_extractor_service.py tests/unit/test_compose_extractor_service.py`), then push and read `docker-smoke.yml`'s Quickstart jobs, which build both images and run the installed stack's extractor probes; `dev/docker-compose.dev.yml` is checked by that compose test and `make dev`, no CI job runs it | diff --git a/docs/development/release-process.md b/docs/development/release-process.md index cc10f9c6a5..22dde7410f 100644 --- a/docs/development/release-process.md +++ b/docs/development/release-process.md @@ -390,7 +390,7 @@ Agents and people find Loom through these listings. Each reads files in this rep | npm page of `@clickhouse/loom` | the metadata of `sdk/typescript/package.json`, and `sdk/typescript/README.md` as the page body | the `npm` job on each dispatched release; the page shows the version tagged `latest`, which the job sets only for the highest final | | Claude plugin directory | `integrations/claude-code-plugin/.claude-plugin/plugin.json` (`displayName`, `description`, `keywords`, `icon`, `documentationUrl`, `supportUrl`, `privacyPolicyUrl`) and the README | submitted once in the developer portal; later versions are picked up from the tracked branch. The icon is read only on the first submission | | Claude Code plugin suggestions | the `relevance` block of the `loom` entry in `.claude-plugin/marketplace.json`: the `loom` command, Loom's config files, an SDK dependency in a manifest | read from the marketplace on the default branch; shown only where an administrator allowlists the marketplace (`pluginSuggestionMarketplaces`) | -| Cursor Marketplace | `.cursor-plugin/plugin.json` (`displayName`, `description`, `keywords`, `logo`, `variables`), `.cursor-plugin/marketplace.json` | submitted once at cursor.com/marketplace/publish; each listing is reviewed by hand | +| Cursor Marketplace | `.cursor-plugin/plugin.json` (`displayName`, `description`, `keywords`, `logo`, `variables`), `.cursor-plugin/marketplace.json` | not submitted; a submission at cursor.com/marketplace/publish is reviewed by hand, and so is each update | | Codex plugin directory | `integrations/codex-plugin/.codex-plugin/plugin.json` (`interface`) | submitted in the plugin portal; a plugin with lifecycle hooks is not eligible there, so the public listing needs a build without them | | Docs index for coding agents | `context7.json` | refreshed from the default branch after the repository is added once | | Agent Skills index | `skills/loom-code`, `skills/loom` and the Claude Code plugin's skills; the contributor skills are marked internal in their frontmatter and are not offered | ranked by `npx skills add ClickHouse/loom` installs; nothing to submit | diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 1ceebe3de1..b50c01bf87 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -9,12 +9,13 @@ 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 | -| Claude Desktop, Cursor, VS Code, Cline, Windsurf, Zed | `loom install --client ` ([below](#wire-a-client-with-loom-install)) | the tools; capture only through a [transcript template](index.md#transcript-capture-hooks) ([Cursor](cursor.md)) | -| 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 its [`sessionEnd` hook](cursor.md) | +| Claude Desktop, VS Code, Cline, Windsurf, Zed | `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 diff --git a/docs/getting-started/connect-a-coding-agent.md b/docs/getting-started/connect-a-coding-agent.md index ca10eef216..0f22bda06d 100644 --- a/docs/getting-started/connect-a-coding-agent.md +++ b/docs/getting-started/connect-a-coding-agent.md @@ -69,6 +69,10 @@ the plugin installed: an entry with the same name replaces the plugin's. ## Cursor and other MCP clients +On a Cursor Teams or Enterprise plan, a team admin can install the [Cursor +plugin](../features/integrations/cursor.md#plugin) (untested in Cursor), which adds the MCP +entry and Loom's skills for every member. + For Cursor or VS Code against a single-user server on the same machine, no token is needed: 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, From 5184201f7706fda92fd215ea69d870ab8a4e366f Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 04:01:14 +0000 Subject: [PATCH 6/9] The Cursor plugin's hook row and release table name which plugins each rule covers Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- .claude/rules/plugins.md | 4 ++-- docs/development/release-process.md | 20 ++++++++++---------- docs/features/integrations/mcp-clients.md | 14 +++++++------- integrations/cursor/README.md | 7 ++++--- 4 files changed, 23 insertions(+), 22 deletions(-) diff --git a/.claude/rules/plugins.md b/.claude/rules/plugins.md index 434d86734a..569f91a53c 100644 --- a/.claude/rules/plugins.md +++ b/.claude/rules/plugins.md @@ -9,10 +9,10 @@ paths: # Integrations and coding-agent plugins - Edit `integrations/claude-code-plugin/`, then `python -m scripts.codegen.agent_plugin_sync` copies its `hooks/*.mjs`, `bin/`, `lib/`, `skills/` and `assets/` to the Codex plugin; never edit a synced copy. Each plugin's manifest, `hooks/hooks.json` and `.mcp.json`, and the Codex `plugin-defaults.json`, differ on purpose and are edited in their own directory. -- A behaviour change to any file the plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests (`integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json`) to a version no other open PR uses: two PRs with one version ship only the first. +- A behaviour change to any file the Claude Code or Codex plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests (`integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json`) to a version no other open PR uses: two PRs with one version ship only the first. - A hook, `lib/` or `bin/` change that calls an op or a field the server does not serve yet says so in its changelog entry ("needs the next server release"), so the release notes list it: that release's pull request raises `MIN_SERVER_VERSION` in `lib/server-version.mjs` to its own version and bumps both plugin versions (clients get it only through a new version); a pull request on `main` before it never raises it (`tests/unit/test_codex_plugin.py` keeps it no newer than the server). Between such a hook's merge and that release, a server of the previous release gets no warning. - Hooks run inside a user's session: they never throw to the agent, never block past their timeout, never print a token, and degrade to silence when the server is unreachable. -- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here (the `.cursor-plugin/` row for that directory); a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case. +- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here, and the `.cursor-plugin/` row covers that directory; a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case. - Anything a hook sends to the server goes through `redactSecrets` / `redactHead`, redacting before truncating, and a diff through `diffHeaders`, which sends only its paths, hunk ranges and function names (`integrations/claude-code-plugin/lib/loom-client.mjs`); a new capture path that skips them is a finding. - An integration or its README is held to an open-source bar: the happy path runs end to end as written; an experimental feature says so and names the versions it was tested on; an upstream bug is filed upstream and linked; a cheap CI check keeps the example from rotting. - The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` (and `.cursor-plugin/plugin.json`, whose plugin ships them) plus each `metadata.version`, released with the server; `skills/loom/` is also what `mentor.guide` serves, so the image copies it ([release process](../../docs/development/release-process.md#where-the-version-lives)). diff --git a/docs/development/release-process.md b/docs/development/release-process.md index 22dde7410f..0cd6285aa6 100644 --- a/docs/development/release-process.md +++ b/docs/development/release-process.md @@ -6,16 +6,16 @@ Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom- `.venv/bin/python scripts/release/prepare.py bump X.Y.Z` bumps each of these in the release commit, except the plugins, and writes the [release notes](#release-notes): -| Component | Files | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Server | `server/__init__.py` (`__version__`), `pyproject.toml`, `uv.lock` and `server.json` | -| Python SDK | `sdk/python/pyproject.toml` and `sdk/python/loom/_version.py` | -| TypeScript SDK | `sdk/typescript/package.json`, `sdk/typescript/package-lock.json`, `sdk/typescript/src/version.ts` | -| Web app | `frontend/package.json` and `frontend/package-lock.json` | -| Root skills | `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json` and the `metadata.version` of `skills/loom-code/SKILL.md` and `skills/loom/SKILL.md` | -| Gemini CLI extension | `gemini-extension.json` | -| Helm chart | `deploy/helm/loom/Chart.yaml`: `appVersion` (the default tag of the server and extractor images, and the chart's `app.kubernetes.io/version` label) and the chart's own `version`: a minor for a major or minor release, a patch for a patch release | -| Coding-agent plugins | `integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json` (their own version; bump it on a behaviour change to any file the plugin ships: `hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) | +| Component | Files | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Server | `server/__init__.py` (`__version__`), `pyproject.toml`, `uv.lock` and `server.json` | +| Python SDK | `sdk/python/pyproject.toml` and `sdk/python/loom/_version.py` | +| TypeScript SDK | `sdk/typescript/package.json`, `sdk/typescript/package-lock.json`, `sdk/typescript/src/version.ts` | +| Web app | `frontend/package.json` and `frontend/package-lock.json` | +| Root skills | `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json` and the `metadata.version` of `skills/loom-code/SKILL.md` and `skills/loom/SKILL.md` | +| Gemini CLI extension | `gemini-extension.json` | +| Helm chart | `deploy/helm/loom/Chart.yaml`: `appVersion` (the default tag of the server and extractor images, and the chart's `app.kubernetes.io/version` label) and the chart's own `version`: a minor for a major or minor release, a patch for a patch release | +| Claude Code and Codex plugins | `integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json` (their own version; bump it on a behaviour change to any file the plugin ships: `hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) | The server reads its version from `server/__init__.py` only; the OpenAPI document, MCP `serverInfo`, `loom report` and `GET /v1/health` (checked by `tests/unit/test_health_problems.py`) report it. These checks keep the numbers consistent: diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index b50c01bf87..45ff9c397d 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -9,13 +9,13 @@ 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 its [`sessionEnd` hook](cursor.md) | -| Claude Desktop, VS Code, Cline, Windsurf, Zed | `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 | `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 diff --git a/integrations/cursor/README.md b/integrations/cursor/README.md index 8b9ae9df9e..b38bcfa926 100644 --- a/integrations/cursor/README.md +++ b/integrations/cursor/README.md @@ -2,9 +2,10 @@ `cursor-session-hook.sh` is a Cursor agent hook that hands a finished conversation's transcript to `loom ingest-transcript`, which posts each turn -to `conversation.append`. For Loom's tools inside Cursor, use the MCP config -instead (`loom install --client cursor`, see [docs/features/integrations/mcp-clients.md](../../docs/features/integrations/mcp-clients.md)); -the two are independent. +to `conversation.append`. For Loom's tools inside Cursor, use the +[Cursor plugin](../../docs/features/integrations/cursor.md#plugin) or the MCP config +(`loom install --client cursor`, see [docs/features/integrations/mcp-clients.md](../../docs/features/integrations/mcp-clients.md)); +the hook is independent of both. ## Install From bc19c62094adee2c0a3ea4ade18fe2829a3f5b02 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 04:11:16 +0000 Subject: [PATCH 7/9] The Cursor page lists the skills install and one dashboard name, and every Cursor link says untested Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- .claude/rules/plugins.md | 2 +- .cursor-plugin/plugin.json | 2 +- docs/development/release-process.md | 2 +- docs/features/integrations/cursor.md | 6 +++--- integrations/cursor/README.md | 2 +- llms.txt | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.claude/rules/plugins.md b/.claude/rules/plugins.md index 569f91a53c..69c11d531b 100644 --- a/.claude/rules/plugins.md +++ b/.claude/rules/plugins.md @@ -12,7 +12,7 @@ paths: - A behaviour change to any file the Claude Code or Codex plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests (`integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json`) to a version no other open PR uses: two PRs with one version ship only the first. - A hook, `lib/` or `bin/` change that calls an op or a field the server does not serve yet says so in its changelog entry ("needs the next server release"), so the release notes list it: that release's pull request raises `MIN_SERVER_VERSION` in `lib/server-version.mjs` to its own version and bumps both plugin versions (clients get it only through a new version); a pull request on `main` before it never raises it (`tests/unit/test_codex_plugin.py` keeps it no newer than the server). Between such a hook's merge and that release, a server of the previous release gets no warning. - Hooks run inside a user's session: they never throw to the agent, never block past their timeout, never print a token, and degrade to silence when the server is unreachable. -- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here, and the `.cursor-plugin/` row covers that directory; a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case. +- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here, and, for `.cursor-plugin/`, its own row; a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case. - Anything a hook sends to the server goes through `redactSecrets` / `redactHead`, redacting before truncating, and a diff through `diffHeaders`, which sends only its paths, hunk ranges and function names (`integrations/claude-code-plugin/lib/loom-client.mjs`); a new capture path that skips them is a finding. - An integration or its README is held to an open-source bar: the happy path runs end to end as written; an experimental feature says so and names the versions it was tested on; an upstream bug is filed upstream and linked; a cheap CI check keeps the example from rotting. - The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` (and `.cursor-plugin/plugin.json`, whose plugin ships them) plus each `metadata.version`, released with the server; `skills/loom/` is also what `mentor.guide` serves, so the image copies it ([release process](../../docs/development/release-process.md#where-the-version-lives)). diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 98182b16c0..781d520dca 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -2,7 +2,7 @@ "name": "clickhouse-loom", "version": "1.2.0", "displayName": "ClickHouse Loom", - "description": "Shared long-term memory, document search and a code index for Cursor from a self-hosted ClickHouse Loom server, over MCP, with the loom and loom-code skills that say when to recall, save and ask the code index.", + "description": "Shared long-term memory, document search and a code index for Cursor from a self-hosted ClickHouse Loom server, over MCP, with the loom and loom-code skills that say when to recall, save and ask the code index. Not yet tested in Cursor.", "author": { "name": "ClickHouse" }, "homepage": "https://clickhouse.github.io/loom/features/integrations/cursor/", "repository": "https://github.com/ClickHouse/loom", diff --git a/docs/development/release-process.md b/docs/development/release-process.md index 0cd6285aa6..4f6fef661f 100644 --- a/docs/development/release-process.md +++ b/docs/development/release-process.md @@ -4,7 +4,7 @@ Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom- ## Where the version lives -`.venv/bin/python scripts/release/prepare.py bump X.Y.Z` bumps each of these in the release commit, except the plugins, and writes the [release notes](#release-notes): +`.venv/bin/python scripts/release/prepare.py bump X.Y.Z` bumps each of these in the release commit, except the Claude Code and Codex plugins, and writes the [release notes](#release-notes): | Component | Files | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/features/integrations/cursor.md b/docs/features/integrations/cursor.md index e5999a78a7..188b9b20b8 100644 --- a/docs/features/integrations/cursor.md +++ b/docs/features/integrations/cursor.md @@ -1,11 +1,11 @@ # Cursor -Cursor gets Loom in three independent pieces: +Cursor gets Loom in three pieces: | Piece | What it gives | How | | ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP tools | the `loom_*` tools in Cursor's agent | the [plugin](#plugin), the [install link](#mcp-tools) for a local single-user server, or `loom install --client cursor` ([MCP clients](mcp-clients.md)) | -| Skills | the `loom` and `loom-code` skills | the [plugin](#plugin) | +| Skills | the `loom` and `loom-code` skills | the [plugin](#plugin), or `npx skills add ClickHouse/loom --skill loom loom-code` | | Transcript capture | each conversation's turns in `conversation.append` | the `sessionEnd` hook `integrations/cursor/cursor-session-hook.sh` | The Cursor plugin carries the MCP entry and the `loom` and `loom-code` skills, and has no @@ -21,7 +21,7 @@ Enterprise plan, a team admin adds it under **Dashboard → Plugins & MCPs → A Marketplace → Import from Repo** with `https://github.com/ClickHouse/loom`. The plugin has one variable, **Loom MCP URL**. A team admin sets it in Cursor's -dashboard under **Plugins**, for every member. +dashboard under **Plugins & MCPs**, for every member. | Server | Loom MCP URL | Sign-in | | ------------------------------------------ | -------------------------------------------------------- | ------------------- | diff --git a/integrations/cursor/README.md b/integrations/cursor/README.md index b38bcfa926..536c458369 100644 --- a/integrations/cursor/README.md +++ b/integrations/cursor/README.md @@ -3,7 +3,7 @@ `cursor-session-hook.sh` is a Cursor agent hook that hands a finished conversation's transcript to `loom ingest-transcript`, which posts each turn to `conversation.append`. For Loom's tools inside Cursor, use the -[Cursor plugin](../../docs/features/integrations/cursor.md#plugin) or the MCP config +[Cursor plugin](../../docs/features/integrations/cursor.md#plugin) (untested in Cursor) or the MCP config (`loom install --client cursor`, see [docs/features/integrations/mcp-clients.md](../../docs/features/integrations/mcp-clients.md)); the hook is independent of both. diff --git a/llms.txt b/llms.txt index 2cfc91d799..7754a04869 100644 --- a/llms.txt +++ b/llms.txt @@ -62,7 +62,7 @@ Start with docs/index.md (the map). To install Loom, a coding agent reads docs/g - [Claude Code plugin](docs/features/integrations/claude-code.md): The `loom` plugin for Claude Code does three things in one install: - [ClickStack and HyperDX](docs/features/integrations/clickstack.md): Loom always emits OpenTelemetry; the HyperDX sources, dashboards and the erasure step need configuring. - [Codex plugin](docs/features/integrations/codex.md): The Codex plugin gives Codex the same Loom integration as Claude Code: MCP tools, hooks that capture the session and load a primer, and the code shunt. -- [Cursor](docs/features/integrations/cursor.md): Cursor gets Loom in three independent pieces: +- [Cursor](docs/features/integrations/cursor.md): Cursor gets Loom in three pieces: - [Agent frameworks and orchestrators](docs/features/integrations/frameworks.md): The SDKs ship adapters that present Loom through a framework's own memory or retrieval interface. - [The grep shim](docs/features/integrations/grep-shim.md): Needs Node 18 or later, a viewer token, and a repository in the code index. - [Integrations](docs/features/integrations/index.md): Loom on a bare ClickHouse service is a complete deployment. From 15b5154b7077fb77c8d8e45910bfa68cc767305f Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 04:19:40 +0000 Subject: [PATCH 8/9] A Cursor team server without OAuth skips the plugin, and the connect page says the admin imports it Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/cursor.md | 5 +++-- docs/getting-started/connect-a-coding-agent.md | 6 +++--- integrations/cursor/README.md | 5 +++-- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/features/integrations/cursor.md b/docs/features/integrations/cursor.md index 188b9b20b8..a82a5b2efe 100644 --- a/docs/features/integrations/cursor.md +++ b/docs/features/integrations/cursor.md @@ -30,8 +30,9 @@ dashboard under **Plugins & MCPs**, for every member. A server with OAuth on takes the bare URL, the resource its protected-resource metadata names; tools outside its default toolset run through `loom_op`. The entry sends no -`Authorization` header, so a team server without OAuth answers 401; for one, write the -entry with a token through `loom install --client cursor` below. +`Authorization` header, so a team server without OAuth answers 401. Such a team skips the +plugin: `loom install --client cursor` [below](#mcp-tools) writes the entry with a token, +and `npx skills add` adds the skills. [Clients that sign in by browser](mcp-clients.md#clients-that-sign-in-by-browser) has the OAuth details. diff --git a/docs/getting-started/connect-a-coding-agent.md b/docs/getting-started/connect-a-coding-agent.md index 0f22bda06d..62ebd9125f 100644 --- a/docs/getting-started/connect-a-coding-agent.md +++ b/docs/getting-started/connect-a-coding-agent.md @@ -69,9 +69,9 @@ the plugin installed: an entry with the same name replaces the plugin's. ## Cursor and other MCP clients -On a Cursor Teams or Enterprise plan, a team admin can install the [Cursor -plugin](../features/integrations/cursor.md#plugin) (untested in Cursor), which adds the MCP -entry and Loom's skills for every member. +On a Cursor Teams or Enterprise plan, a team admin can import the [Cursor +plugin](../features/integrations/cursor.md#plugin) (untested in Cursor), which carries the +MCP entry and Loom's skills. For Cursor or VS Code against a single-user server on the same machine, no token is needed: use the [Cursor](../features/integrations/cursor.md#mcp-tools) or diff --git a/integrations/cursor/README.md b/integrations/cursor/README.md index 536c458369..dcf69df1f6 100644 --- a/integrations/cursor/README.md +++ b/integrations/cursor/README.md @@ -3,8 +3,9 @@ `cursor-session-hook.sh` is a Cursor agent hook that hands a finished conversation's transcript to `loom ingest-transcript`, which posts each turn to `conversation.append`. For Loom's tools inside Cursor, use the -[Cursor plugin](../../docs/features/integrations/cursor.md#plugin) (untested in Cursor) or the MCP config -(`loom install --client cursor`, see [docs/features/integrations/mcp-clients.md](../../docs/features/integrations/mcp-clients.md)); +[Cursor plugin](../../docs/features/integrations/cursor.md#plugin) +(untested in Cursor) or the MCP config (`loom install --client cursor`, see +[docs/features/integrations/mcp-clients.md](../../docs/features/integrations/mcp-clients.md)); the hook is independent of both. ## Install From dab6285e71429078b13d58f76bd78e8c3f29fefb Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 04:39:03 +0000 Subject: [PATCH 9/9] The Cursor plugin test compares its default URL with the entry loom install writes Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/cursor.md | 12 ++++++------ tests/unit/test_cursor_plugin.py | 18 +++++++++++++----- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/features/integrations/cursor.md b/docs/features/integrations/cursor.md index a82a5b2efe..60156746f8 100644 --- a/docs/features/integrations/cursor.md +++ b/docs/features/integrations/cursor.md @@ -14,10 +14,10 @@ hooks: no code shunt and no capture of tool calls, runs or working memory; the ## Plugin -`.cursor-plugin/` at the repository root makes it a Cursor plugin marketplace with one -plugin, `clickhouse-loom`: the `loom` MCP server and the root `skills/`. The plugin is -not listed in Cursor's marketplace and has not been tested in Cursor. On a Teams or -Enterprise plan, a team admin adds it under **Dashboard → Plugins & MCPs → Add +`.cursor-plugin/` at the repository root makes the repository a Cursor plugin marketplace +with one plugin, `clickhouse-loom`: the `loom` MCP server and the root `skills/`. The +plugin is not listed in Cursor's marketplace and has not been tested in Cursor. On a +Teams or Enterprise plan, a team admin adds it under **Dashboard → Plugins & MCPs → Add Marketplace → Import from Repo** with `https://github.com/ClickHouse/loom`. The plugin has one variable, **Loom MCP URL**. A team admin sets it in Cursor's @@ -33,8 +33,8 @@ names; tools outside its default toolset run through `loom_op`. The entry sends `Authorization` header, so a team server without OAuth answers 401. Such a team skips the plugin: `loom install --client cursor` [below](#mcp-tools) writes the entry with a token, and `npx skills add` adds the skills. -[Clients that sign in by browser](mcp-clients.md#clients-that-sign-in-by-browser) has -the OAuth details. +[Clients that sign in by browser](mcp-clients.md#clients-that-sign-in-by-browser) has the +OAuth details. ## MCP tools diff --git a/tests/unit/test_cursor_plugin.py b/tests/unit/test_cursor_plugin.py index c91e943170..877dc2c5b2 100644 --- a/tests/unit/test_cursor_plugin.py +++ b/tests/unit/test_cursor_plugin.py @@ -8,9 +8,10 @@ import re from pathlib import Path +import pytest + +import server.cli.install as cli from server.cli._client import DEFAULT_BASE_URL -from server.cli.install import _install_mcp_url -from server.identity.app.token_clients import CODING_CLIENTS, CODING_TOOLSET from tests.unit.test_loom_code_skill import ROOT_SKILLS ROOT = Path(__file__).resolve().parents[2] @@ -46,10 +47,17 @@ def test_the_entry_sends_no_authorization_header() -> None: assert entry == {"url": "${LOOM_MCP_URL}"} -def test_the_default_url_is_the_one_loom_install_writes_for_cursor() -> None: +def test_the_default_url_is_the_one_loom_install_writes_for_cursor( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + config = tmp_path / "mcp.json" + monkeypatch.setattr(cli, "_resolve_install_path", lambda client: config) + assert cli._install_one( + "cursor", token="", server_url=DEFAULT_BASE_URL, name="loom", dry_run=False + ) + written = json.loads(config.read_text())["mcpServers"]["loom"]["url"] default = MANIFEST["variables"]["properties"]["LOOM_MCP_URL"]["default"] - assert "cursor" in CODING_CLIENTS - assert default == _install_mcp_url(DEFAULT_BASE_URL, CODING_TOOLSET) + assert default == written def test_the_plugin_ships_the_root_skills() -> None: