From e3b0dc46feace7cb0fbbd3f86ada389f94f159a5 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 07:18:27 +0000 Subject: [PATCH 01/11] GitHub Copilot CLI installs Loom's MCP server and skills from the repository's Agent Plugins package The root plugin.json and mcp.json are an Agent Plugins 1.0.0 package: the manifest has only the spec's fields, and the entry is the URL of a single-user server on the same machine, with no headers. The package 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 | 6 ++- .claude/skills/loom-pre-push/SKILL.md | 1 + docs/development/release-process.md | 27 ++++++------ docs/development/repository-guide.md | 50 ++++++++++----------- docs/features/integrations/index.md | 1 + docs/features/integrations/mcp-clients.md | 15 +++++++ llms.txt | 2 +- mcp.json | 6 +++ plugin.json | 19 ++++++++ scripts/release/prepare.py | 1 + tests/unit/test_agent_plugin.py | 53 +++++++++++++++++++++++ tests/unit/test_published_links.py | 1 + 12 files changed, 141 insertions(+), 41 deletions(-) create mode 100644 mcp.json create mode 100644 plugin.json create mode 100644 tests/unit/test_agent_plugin.py diff --git a/.claude/rules/plugins.md b/.claude/rules/plugins.md index 69c11d531b..140a6b48c2 100644 --- a/.claude/rules/plugins.md +++ b/.claude/rules/plugins.md @@ -4,6 +4,8 @@ paths: - "skills/**" - ".claude-plugin/**" - ".cursor-plugin/**" + - "plugin.json" + - "mcp.json" --- # Integrations and coding-agent plugins @@ -12,8 +14,8 @@ 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, 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. +- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here, and, for `.cursor-plugin/` and the root `plugin.json`, their own rows; 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)). +- The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` (and `.cursor-plugin/plugin.json` and the root `plugin.json`, whose plugins ship 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/.claude/skills/loom-pre-push/SKILL.md b/.claude/skills/loom-pre-push/SKILL.md index 4ca1c8da67..d9ef7e4287 100644 --- a/.claude/skills/loom-pre-push/SKILL.md +++ b/.claude/skills/loom-pre-push/SKILL.md @@ -43,6 +43,7 @@ Run them in the worktree's `.venv`, on CI's Python (3.12), with `LOOM_ENV_FILE=` | 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 tests/unit/test_published_links.py`; its version follows the server's and is never bumped on its own | +| `plugin.json`, `mcp.json` (the Agent Plugins package) | `.venv/bin/python -m pytest tests/unit/test_agent_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 aa3ed102ba..bfb922f98e 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`), 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). +Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`), the Cursor plugin and the Agent Plugins package that ship 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 @@ -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`, `.cursor-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`, `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`) | @@ -420,17 +420,18 @@ The coding-agent plugins install from the repository's marketplaces (`claude plu Agents and people find Loom through these listings. Each reads files in this repository: -| Listing | Reads | How it updates | -| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| MCP Registry, and the directories that copy it | `server.json`: its metadata and a remote at `https://{loom_host}/mcp` with an optional secret `Authorization` header | the `mcp-registry` job on each dispatched final release | -| PyPI page of `clickhouse-loom` | the `[project]` metadata of `sdk/python/pyproject.toml`, and `sdk/python/README.md` as the page body | the `pypi` job on each dispatched release; the page shows the highest final version, or the highest candidate before the first final | -| 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` | 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 | +| Listing | Reads | How it updates | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| MCP Registry, and the directories that copy it | `server.json`: its metadata and a remote at `https://{loom_host}/mcp` with an optional secret `Authorization` header | the `mcp-registry` job on each dispatched final release | +| PyPI page of `clickhouse-loom` | the `[project]` metadata of `sdk/python/pyproject.toml`, and `sdk/python/README.md` as the page body | the `pypi` job on each dispatched release; the page shows the highest final version, or the highest candidate before the first final | +| 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` | not submitted; a submission at cursor.com/marketplace/publish is reviewed by hand, and so is each update | +| Awesome Copilot marketplace | the root `plugin.json` and `mcp.json` (the Agent Plugins package), at the release tag and commit the submission names | submitted through the external-plugin issue form of `github/awesome-copilot`, which checks the package and installs it with Copilot CLI; a new version is a pull request to that repository's `plugins/external.json` | +| 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 | The `mcp-registry` job runs in the `mcp-registry` environment. Give it the same protection rules as `pypi` and `npm` before the first dispatch: GitHub creates a missing environment with none. Its login needs no secret. diff --git a/docs/development/repository-guide.md b/docs/development/repository-guide.md index 4f6bf09a14..680d8d038e 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, one folder per language in `LANGUAGES`; 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 | +| 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, one folder per language in `LANGUAGES`; 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/`, `plugin.json`, `mcp.json`, `.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 Agent Plugins package GitHub Copilot CLI installs, 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/index.md b/docs/features/integrations/index.md index 26b55d7744..c12e061150 100644 --- a/docs/features/integrations/index.md +++ b/docs/features/integrations/index.md @@ -21,6 +21,7 @@ a bare ClickHouse service is a complete deployment). They fall into three groups | VS Code agent mode | MCP tools | install links and `mcp.json`: [vscode.md](vscode.md) | | Any MCP client without a plugin | an instruction block for the client's rule file | [agent-instructions.md](agent-instructions.md) | | Gemini CLI | extension: MCP tools and the `loom`, `loom-code` skills | `gemini extensions install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | +| GitHub Copilot CLI | plugin: MCP tools and the `loom`, `loom-code` skills | `copilot plugin 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) | | claude.ai, ChatGPT, Copilot Studio, Replit Agent, Lovable, v0, n8n, Dify, Zapier, Make and other hosted services | a custom connector to a Loom the service can reach | [hosted builders and chat apps](mcp-clients.md#hosted-builders-and-chat-apps) | | Cline CLI (experimental) | hooks: session primer, prompt recall, a file's memories on a read | `integrations/cline/`: [README](../../../integrations/cline/README.md) | diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 351f0422e4..d4b240f809 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -257,6 +257,21 @@ On a single-user server, an empty token still sends `Authorization: Bearer`, whi server accepts with a warning in its log for each request; `gemini mcp add` without `--header` (above) avoids it. +GitHub Copilot CLI installs Loom as a plugin from the repository's root `plugin.json`, an +[Agent Plugins](https://agent-plugins.org) package: + +```bash +copilot plugin install ClickHouse/loom +``` + +The plugin adds the `loom` MCP server at `http://localhost:7777/mcp?toolset=coding`, a +single-user server on the same machine, and the `loom` and `loom-code` skills; `copilot mcp +get loom` shows the entry. The URL is fixed and a user entry named `loom` does not replace +it, so for a team server skip the plugin and add the entry from the table. Checked with +Copilot CLI 1.0.112: the install and `copilot mcp get loom`, and the same entry pointed at a +local Loom answering MCP `initialize` and `tools/list`; a Copilot session needs a sign-in +and was not run. + ### Hosted builders and chat apps A hosted agent or app builder (Replit Agent, Lovable, v0, Zapier, Make, Microsoft Copilot diff --git a/llms.txt b/llms.txt index 70323038bc..59574de5c7 100644 --- a/llms.txt +++ b/llms.txt @@ -175,7 +175,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`), the Cursor plugin that ships them 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 and the Agent Plugins package that ship 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/mcp.json b/mcp.json new file mode 100644 index 0000000000..631a562f03 --- /dev/null +++ b/mcp.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "loom": { "type": "streamable-http", "url": "http://localhost:7777/mcp?toolset=coding" } + } +} diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000000..f42bb487c4 --- /dev/null +++ b/plugin.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "clickhouse-loom", + "version": "1.2.0", + "description": "Shared long-term memory, document search and a code index 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", "url": "https://github.com/ClickHouse" }, + "homepage": "https://clickhouse.github.io/loom/", + "repository": "https://github.com/ClickHouse/loom", + "license": "Apache-2.0", + "keywords": [ + "agent-memory", + "long-term-memory", + "code-intelligence", + "code-search", + "mcp", + "clickhouse", + "self-hosted" + ] +} diff --git a/scripts/release/prepare.py b/scripts/release/prepare.py index 4d01b607af..4e23533a82 100755 --- a/scripts/release/prepare.py +++ b/scripts/release/prepare.py @@ -68,6 +68,7 @@ class Pin(NamedTuple): Pin("frontend/package-lock.json", _LOCK_ROOT), Pin(".claude-plugin/plugin.json", _TOP_JSON), Pin(".cursor-plugin/plugin.json", _TOP_JSON), + Pin("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_agent_plugin.py b/tests/unit/test_agent_plugin.py new file mode 100644 index 0000000000..4cbed5121c --- /dev/null +++ b/tests/unit/test_agent_plugin.py @@ -0,0 +1,53 @@ +"""The Agent Plugins package at the repository root: `plugin.json` is the manifest GitHub +Copilot CLI installs, `mcp.json` its MCP entry, and its skills are the root `skills/`.""" + +from __future__ import annotations + +import json +import re +from pathlib import Path + +from tests.unit.test_loom_code_skill import ROOT_SKILLS + +ROOT = Path(__file__).resolve().parents[2] +MANIFEST = json.loads((ROOT / "plugin.json").read_text()) +MCP = json.loads((ROOT / "mcp.json").read_text()) +CURSOR = json.loads((ROOT / ".cursor-plugin" / "plugin.json").read_text()) + +# Agent Plugins 1.0.0 refuses any other top-level field. +MANIFEST_FIELDS = { + "$schema", + "name", + "version", + "description", + "author", + "homepage", + "repository", + "license", + "keywords", + "extensions", +} + + +def test_the_manifest_holds_only_agent_plugins_fields() -> None: + assert MANIFEST["$schema"] == "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json" + assert set(MANIFEST) <= MANIFEST_FIELDS + assert re.fullmatch(r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?", MANIFEST["name"]) + + +def test_the_plugin_has_the_cursor_plugins_name_and_version() -> None: + assert MANIFEST["name"] == CURSOR["name"] + assert MANIFEST["version"] == CURSOR["version"] + + +def test_the_entry_is_the_local_server_with_no_headers() -> None: + # Agent Plugins forbids credentials in headers; a single-user server needs none. + assert MCP["$schema"] == "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json" + entry = MCP["mcpServers"]["loom"] + default = CURSOR["variables"]["properties"]["LOOM_MCP_URL"]["default"] + assert entry == {"type": "streamable-http", "url": default} + + +def test_the_plugin_ships_the_root_skills() -> None: + names = {p.parent.name for p in (ROOT / "skills").glob("*/SKILL.md")} + assert names == set(ROOT_SKILLS) diff --git a/tests/unit/test_published_links.py b/tests/unit/test_published_links.py index 3c9dc6eb8a..264a97119a 100644 --- a/tests/unit/test_published_links.py +++ b/tests/unit/test_published_links.py @@ -45,6 +45,7 @@ def test_published_links_resolve() -> None: "server.json", ".claude-plugin/plugin.json", ".cursor-plugin/plugin.json", + "plugin.json", "integrations/claude-code-plugin/.claude-plugin/plugin.json", "integrations/codex-plugin/.codex-plugin/plugin.json", "pyproject.toml", From 02a8bc5ca0ac82f02c022d51c502787eb5cac533 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 07:41:39 +0000 Subject: [PATCH 02/11] The Copilot CLI docs name the uninstall step, and the plugin test checks the fixed skills directory Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/mcp-clients.md | 8 ++++---- tests/unit/test_agent_plugin.py | 4 +++- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index d4b240f809..c8e9f4fc46 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -267,10 +267,10 @@ copilot plugin install ClickHouse/loom The plugin adds the `loom` MCP server at `http://localhost:7777/mcp?toolset=coding`, a single-user server on the same machine, and the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. The URL is fixed and a user entry named `loom` does not replace -it, so for a team server skip the plugin and add the entry from the table. Checked with -Copilot CLI 1.0.112: the install and `copilot mcp get loom`, and the same entry pointed at a -local Loom answering MCP `initialize` and `tools/list`; a Copilot session needs a sign-in -and was not run. +it, so for a team server skip the plugin, or remove it with `copilot plugin uninstall +clickhouse-loom`, and add the entry from the table. Checked with Copilot CLI 1.0.112: the +install and `copilot mcp get loom`, and the same entry pointed at a local Loom answering MCP +`initialize` and `tools/list`; a Copilot session needs a sign-in and was not run. ### Hosted builders and chat apps diff --git a/tests/unit/test_agent_plugin.py b/tests/unit/test_agent_plugin.py index 4cbed5121c..94a919496c 100644 --- a/tests/unit/test_agent_plugin.py +++ b/tests/unit/test_agent_plugin.py @@ -48,6 +48,8 @@ def test_the_entry_is_the_local_server_with_no_headers() -> None: assert entry == {"type": "streamable-http", "url": default} -def test_the_plugin_ships_the_root_skills() -> None: +def test_the_skills_are_the_root_skills_in_the_fixed_directory() -> None: + # Agent Plugins has no skills field: a client loads skills/ next to plugin.json. + assert "skills" not in MANIFEST names = {p.parent.name for p in (ROOT / "skills").glob("*/SKILL.md")} assert names == set(ROOT_SKILLS) From d051106194f9406a7a6df9b790c8880730292392 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 07:49:06 +0000 Subject: [PATCH 03/11] The Copilot CLI row points to the plugin, the docs name the branch it installs, and the plugin test keeps only its own checks Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/mcp-clients.md | 17 +++++++++-------- tests/unit/test_agent_plugin.py | 18 +++++------------- 2 files changed, 14 insertions(+), 21 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index c8e9f4fc46..46d2349475 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -184,7 +184,7 @@ client afterwards. | Visual Studio (Copilot agent mode) | `%USERPROFILE%\.mcp.json`, or `.mcp.json` in the solution | `{"servers": {"loom": {"type": "http", "url": "URL", "headers": {…}}}}` (Visual Studio also reads `.vscode/mcp.json`) | | | Kiro | `~/.kiro/settings/mcp.json`, or `.kiro/settings/mcp.json`; Kiro CLI reads the same `~/.kiro/settings/mcp.json` as the Kiro IDE (and copies `~/.aws/amazonq/mcp.json` there once, when Kiro CLI is installed, skipping servers that conflict with ones already there) | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` (Kiro documents that it expands a `${LOOM_API_KEY}` placeholder only for a variable listed in the **Mcp Approved Env Vars** setting); for a single-user server, an install link `https://kiro.dev/launch/mcp/add?name=loom&config=` | | | Gemini CLI | `~/.gemini/settings.json`, or `.gemini/settings.json` | `{"mcpServers": {"loom": {"httpUrl": "URL", "headers": {…}}}}`, or `gemini mcp add --transport http --header "Authorization: Bearer " loom URL` (drop `--header` for a single-user server); or the extension, below; Gemini lists a server as disabled in a folder it does not trust | connected (`gemini mcp add`, and the extension) | -| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | `{"mcpServers": {"loom": {"type": "http", "url": "URL", "headers": {…}, "tools": ["*"]}}}` | accepted | +| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | `{"mcpServers": {"loom": {"type": "http", "url": "URL", "headers": {…}, "tools": ["*"]}}}`; or the plugin, below | accepted | | Neovim with mcphub.nvim (also serves avante.nvim and CodeCompanion) | `~/.config/mcphub/servers.json` | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | | | Emacs with mcp.el and gptel | `mcp-hub-servers` in your init file, then `gptel-mcp-connect` | `(setq mcp-hub-servers '(("loom" . (:url "URL"))))` (single-user server only: no header field is documented) | | | OpenCode | `opencode.json` or `.opencode/opencode.json` in the project or a folder above it, or `~/.config/opencode/opencode.json` | `opencode mcp add loom --url URL --header "Authorization=Bearer "`, which in OpenCode 2.x writes `{"mcp": {"servers": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}}`; the 1.x `opencode-ai` npm package takes `{"mcp": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}`, which 2.x still reads | connected | @@ -264,13 +264,14 @@ GitHub Copilot CLI installs Loom as a plugin from the repository's root `plugin. copilot plugin install ClickHouse/loom ``` -The plugin adds the `loom` MCP server at `http://localhost:7777/mcp?toolset=coding`, a -single-user server on the same machine, and the `loom` and `loom-code` skills; `copilot mcp -get loom` shows the entry. The URL is fixed and a user entry named `loom` does not replace -it, so for a team server skip the plugin, or remove it with `copilot plugin uninstall -clickhouse-loom`, and add the entry from the table. Checked with Copilot CLI 1.0.112: the -install and `copilot mcp get loom`, and the same entry pointed at a local Loom answering MCP -`initialize` and `tools/list`; a Copilot session needs a sign-in and was not run. +Copilot CLI installs it from the default branch. The plugin adds the `loom` MCP server at +`http://localhost:7777/mcp?toolset=coding`, a single-user server on the same machine, and +the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. The URL is fixed +and a user entry named `loom` does not replace it, so for a team server skip the plugin, or +remove it with `copilot plugin uninstall clickhouse-loom`, and add the entry from the table. +Checked with Copilot CLI 1.0.112: the install and `copilot mcp get loom`, and the same entry +pointed at a local Loom answering MCP `initialize` and `tools/list`; a Copilot session needs +a sign-in and was not run. ### Hosted builders and chat apps diff --git a/tests/unit/test_agent_plugin.py b/tests/unit/test_agent_plugin.py index 94a919496c..adc2525fba 100644 --- a/tests/unit/test_agent_plugin.py +++ b/tests/unit/test_agent_plugin.py @@ -1,5 +1,6 @@ """The Agent Plugins package at the repository root: `plugin.json` is the manifest GitHub -Copilot CLI installs, `mcp.json` its MCP entry, and its skills are the root `skills/`.""" +Copilot CLI installs, `mcp.json` its MCP entry, and its skills are the root `skills/` +(`tests/unit/test_cursor_plugin.py` checks that directory).""" from __future__ import annotations @@ -7,14 +8,13 @@ import re from pathlib import Path -from tests.unit.test_loom_code_skill import ROOT_SKILLS - ROOT = Path(__file__).resolve().parents[2] MANIFEST = json.loads((ROOT / "plugin.json").read_text()) MCP = json.loads((ROOT / "mcp.json").read_text()) CURSOR = json.loads((ROOT / ".cursor-plugin" / "plugin.json").read_text()) -# Agent Plugins 1.0.0 refuses any other top-level field. +# Agent Plugins 1.0.0 refuses any other top-level field; it has no skills field, and a +# client loads the skills/ directory next to plugin.json. MANIFEST_FIELDS = { "$schema", "name", @@ -35,9 +35,8 @@ def test_the_manifest_holds_only_agent_plugins_fields() -> None: assert re.fullmatch(r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?", MANIFEST["name"]) -def test_the_plugin_has_the_cursor_plugins_name_and_version() -> None: +def test_the_plugin_has_the_cursor_plugins_name() -> None: assert MANIFEST["name"] == CURSOR["name"] - assert MANIFEST["version"] == CURSOR["version"] def test_the_entry_is_the_local_server_with_no_headers() -> None: @@ -46,10 +45,3 @@ def test_the_entry_is_the_local_server_with_no_headers() -> None: entry = MCP["mcpServers"]["loom"] default = CURSOR["variables"]["properties"]["LOOM_MCP_URL"]["default"] assert entry == {"type": "streamable-http", "url": default} - - -def test_the_skills_are_the_root_skills_in_the_fixed_directory() -> None: - # Agent Plugins has no skills field: a client loads skills/ next to plugin.json. - assert "skills" not in MANIFEST - names = {p.parent.name for p in (ROOT / "skills").glob("*/SKILL.md")} - assert names == set(ROOT_SKILLS) From 0684dacb6ed192492e10bff432a99cfc61744e3c Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 07:54:50 +0000 Subject: [PATCH 04/11] The Copilot CLI docs mark the plugin experimental and say how its entry was checked Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/index.md | 2 +- docs/features/integrations/mcp-clients.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/features/integrations/index.md b/docs/features/integrations/index.md index c12e061150..aab0811a87 100644 --- a/docs/features/integrations/index.md +++ b/docs/features/integrations/index.md @@ -21,7 +21,7 @@ a bare ClickHouse service is a complete deployment). They fall into three groups | VS Code agent mode | MCP tools | install links and `mcp.json`: [vscode.md](vscode.md) | | Any MCP client without a plugin | an instruction block for the client's rule file | [agent-instructions.md](agent-instructions.md) | | Gemini CLI | extension: MCP tools and the `loom`, `loom-code` skills | `gemini extensions install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | -| GitHub Copilot CLI | plugin: MCP tools and the `loom`, `loom-code` skills | `copilot plugin install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | +| GitHub Copilot CLI (experimental) | plugin: MCP tools and the `loom`, `loom-code` skills | `copilot plugin 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) | | claude.ai, ChatGPT, Copilot Studio, Replit Agent, Lovable, v0, n8n, Dify, Zapier, Make and other hosted services | a custom connector to a Loom the service can reach | [hosted builders and chat apps](mcp-clients.md#hosted-builders-and-chat-apps) | | Cline CLI (experimental) | hooks: session primer, prompt recall, a file's memories on a read | `integrations/cline/`: [README](../../../integrations/cline/README.md) | diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 46d2349475..23a61da24b 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -269,9 +269,9 @@ Copilot CLI installs it from the default branch. The plugin adds the `loom` MCP the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. The URL is fixed and a user entry named `loom` does not replace it, so for a team server skip the plugin, or remove it with `copilot plugin uninstall clickhouse-loom`, and add the entry from the table. -Checked with Copilot CLI 1.0.112: the install and `copilot mcp get loom`, and the same entry -pointed at a local Loom answering MCP `initialize` and `tools/list`; a Copilot session needs -a sign-in and was not run. +Checked with Copilot CLI 1.0.112: the install and `copilot mcp get loom`, and the entry, +with its port changed to a local Loom's, answering MCP `initialize` and `tools/list`; a +Copilot session needs a sign-in and was not run. ### Hosted builders and chat apps From dbbdfaa3d62a334a9c1ebd83f5f3debc919c6d63 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 08:00:16 +0000 Subject: [PATCH 05/11] The Copilot CLI plugin section says it is experimental where a reader lands Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/mcp-clients.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 23a61da24b..aa0e262357 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -257,8 +257,9 @@ On a single-user server, an empty token still sends `Authorization: Bearer`, whi server accepts with a warning in its log for each request; `gemini mcp add` without `--header` (above) avoids it. -GitHub Copilot CLI installs Loom as a plugin from the repository's root `plugin.json`, an -[Agent Plugins](https://agent-plugins.org) package: +GitHub Copilot CLI (experimental: a Copilot session was not run) installs Loom as a plugin +from the repository's root `plugin.json`, an [Agent Plugins](https://agent-plugins.org) +package: ```bash copilot plugin install ClickHouse/loom @@ -271,7 +272,7 @@ and a user entry named `loom` does not replace it, so for a team server skip the remove it with `copilot plugin uninstall clickhouse-loom`, and add the entry from the table. Checked with Copilot CLI 1.0.112: the install and `copilot mcp get loom`, and the entry, with its port changed to a local Loom's, answering MCP `initialize` and `tools/list`; a -Copilot session needs a sign-in and was not run. +Copilot session needs a sign-in. ### Hosted builders and chat apps From cd0248492d5433e732415b419db95a128b2da9ee Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 08:07:34 +0000 Subject: [PATCH 06/11] The Copilot CLI docs say what happens to an earlier skills-only install and to the marketplace entry Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/mcp-clients.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index aa0e262357..58943275a8 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -257,9 +257,8 @@ On a single-user server, an empty token still sends `Authorization: Bearer`, whi server accepts with a warning in its log for each request; `gemini mcp add` without `--header` (above) avoids it. -GitHub Copilot CLI (experimental: a Copilot session was not run) installs Loom as a plugin -from the repository's root `plugin.json`, an [Agent Plugins](https://agent-plugins.org) -package: +GitHub Copilot CLI (experimental) installs Loom as a plugin from the repository's root +`plugin.json`, an [Agent Plugins](https://agent-plugins.org) package: ```bash copilot plugin install ClickHouse/loom @@ -270,9 +269,14 @@ Copilot CLI installs it from the default branch. The plugin adds the `loom` MCP the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. The URL is fixed and a user entry named `loom` does not replace it, so for a team server skip the plugin, or remove it with `copilot plugin uninstall clickhouse-loom`, and add the entry from the table. -Checked with Copilot CLI 1.0.112: the install and `copilot mcp get loom`, and the entry, -with its port changed to a local Loom's, answering MCP `initialize` and `tools/list`; a -Copilot session needs a sign-in. +An earlier install of this repository is named `loom-code-skill` and has only the skills: +`copilot plugin update loom-code-skill` turns it into this plugin, while installing again +without updating keeps both and loads the skills twice. The `loom-code-skill` entry of the +Claude Code marketplace (`copilot plugin marketplace add ClickHouse/loom`) installs the same +package, MCP server included. Checked with Copilot CLI 1.0.112: the install, the update, the +marketplace install, `copilot mcp get loom`, and MCP `initialize` and `tools/list` through +the entry pointed at a local Loom on another port. A Copilot session needs a sign-in and was +not run. ### Hosted builders and chat apps From 4b6a54fb27f4ccadfb5e3b2f58dbc20098bbbf77 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 08:11:55 +0000 Subject: [PATCH 07/11] The marketplace entry, the plugins rule and the listings table describe the Agent Plugins package as it is Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- .claude-plugin/marketplace.json | 2 +- .claude/rules/plugins.md | 2 +- docs/development/release-process.md | 24 ++++++++++++------------ 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index eba00f9b82..9838dcd968 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -33,7 +33,7 @@ { "name": "loom-code-skill", "source": "./", - "description": "Code search and code intelligence for repositories in a Loom code index (the loom-code Agent Skill: code.* first, then read only that), and the loom Agent Skill: how an agent uses Loom. Skills only, no hooks.", + "description": "Code search and code intelligence for repositories in a Loom code index (the loom-code Agent Skill: code.* first, then read only that), and the loom Agent Skill: how an agent uses Loom. No hooks; GitHub Copilot CLI also adds the loom MCP server.", "license": "Apache-2.0", "category": "code-intelligence" } diff --git a/.claude/rules/plugins.md b/.claude/rules/plugins.md index 140a6b48c2..6628f8ea92 100644 --- a/.claude/rules/plugins.md +++ b/.claude/rules/plugins.md @@ -14,7 +14,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, for `.cursor-plugin/` and the root `plugin.json`, their own rows; 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/` and the root Agent Plugins package (`plugin.json`, `mcp.json`), their own rows; 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` and the root `plugin.json`, whose plugins ship 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 bfb922f98e..c00327d2be 100644 --- a/docs/development/release-process.md +++ b/docs/development/release-process.md @@ -420,18 +420,18 @@ The coding-agent plugins install from the repository's marketplaces (`claude plu Agents and people find Loom through these listings. Each reads files in this repository: -| Listing | Reads | How it updates | -| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| MCP Registry, and the directories that copy it | `server.json`: its metadata and a remote at `https://{loom_host}/mcp` with an optional secret `Authorization` header | the `mcp-registry` job on each dispatched final release | -| PyPI page of `clickhouse-loom` | the `[project]` metadata of `sdk/python/pyproject.toml`, and `sdk/python/README.md` as the page body | the `pypi` job on each dispatched release; the page shows the highest final version, or the highest candidate before the first final | -| 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` | not submitted; a submission at cursor.com/marketplace/publish is reviewed by hand, and so is each update | -| Awesome Copilot marketplace | the root `plugin.json` and `mcp.json` (the Agent Plugins package), at the release tag and commit the submission names | submitted through the external-plugin issue form of `github/awesome-copilot`, which checks the package and installs it with Copilot CLI; a new version is a pull request to that repository's `plugins/external.json` | -| 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 | +| Listing | Reads | How it updates | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| MCP Registry, and the directories that copy it | `server.json`: its metadata and a remote at `https://{loom_host}/mcp` with an optional secret `Authorization` header | the `mcp-registry` job on each dispatched final release | +| PyPI page of `clickhouse-loom` | the `[project]` metadata of `sdk/python/pyproject.toml`, and `sdk/python/README.md` as the page body | the `pypi` job on each dispatched release; the page shows the highest final version, or the highest candidate before the first final | +| 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` | not submitted; a submission at cursor.com/marketplace/publish is reviewed by hand, and so is each update | +| Awesome Copilot marketplace | the root `plugin.json` and `mcp.json` (the Agent Plugins package), at the release tag and commit the submission names | not submitted; a submission goes through the external-plugin issue form of `github/awesome-copilot`, which checks the package and installs it with Copilot CLI; a new version is a pull request to that repository's `plugins/external.json` | +| 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 | The `mcp-registry` job runs in the `mcp-registry` environment. Give it the same protection rules as `pypi` and `npm` before the first dispatch: GitHub creates a missing environment with none. Its login needs no secret. From ce75c3b92908adf087a8200f05894c3a83c69272 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 08:16:16 +0000 Subject: [PATCH 08/11] The Agent Plugins manifest says it is experimental and links its docs, and the test ties the documented uninstall to its name Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/mcp-clients.md | 18 +++++++++--------- plugin.json | 4 ++-- tests/unit/test_agent_plugin.py | 5 +++-- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 58943275a8..67c119e0fa 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -268,15 +268,15 @@ Copilot CLI installs it from the default branch. The plugin adds the `loom` MCP `http://localhost:7777/mcp?toolset=coding`, a single-user server on the same machine, and the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. The URL is fixed and a user entry named `loom` does not replace it, so for a team server skip the plugin, or -remove it with `copilot plugin uninstall clickhouse-loom`, and add the entry from the table. -An earlier install of this repository is named `loom-code-skill` and has only the skills: -`copilot plugin update loom-code-skill` turns it into this plugin, while installing again -without updating keeps both and loads the skills twice. The `loom-code-skill` entry of the -Claude Code marketplace (`copilot plugin marketplace add ClickHouse/loom`) installs the same -package, MCP server included. Checked with Copilot CLI 1.0.112: the install, the update, the -marketplace install, `copilot mcp get loom`, and MCP `initialize` and `tools/list` through -the entry pointed at a local Loom on another port. A Copilot session needs a sign-in and was -not run. +remove it with `copilot plugin uninstall clickhouse-loom` (`loom-code-skill` for the +marketplace install below), and add the entry from the table. An earlier install of this +repository is named `loom-code-skill` and has only the skills: `copilot plugin update +loom-code-skill` turns it into this plugin, while installing again without updating keeps +both and loads the skills twice. The `loom-code-skill` entry of the Claude Code marketplace +(`copilot plugin marketplace add ClickHouse/loom`) installs the same package, MCP server +included. Checked with Copilot CLI 1.0.112: the install, the update, the marketplace +install, `copilot mcp get loom`, and MCP `initialize` and `tools/list` through the entry +pointed at a local Loom on another port. A Copilot session needs a sign-in and was not run. ### Hosted builders and chat apps diff --git a/plugin.json b/plugin.json index f42bb487c4..47fd3099bc 100644 --- a/plugin.json +++ b/plugin.json @@ -2,9 +2,9 @@ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "clickhouse-loom", "version": "1.2.0", - "description": "Shared long-term memory, document search and a code index 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 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. Experimental: checked with Copilot CLI 1.0.112.", "author": { "name": "ClickHouse", "url": "https://github.com/ClickHouse" }, - "homepage": "https://clickhouse.github.io/loom/", + "homepage": "https://clickhouse.github.io/loom/features/integrations/mcp-clients/#other-editors-and-agents", "repository": "https://github.com/ClickHouse/loom", "license": "Apache-2.0", "keywords": [ diff --git a/tests/unit/test_agent_plugin.py b/tests/unit/test_agent_plugin.py index adc2525fba..a3554f13c0 100644 --- a/tests/unit/test_agent_plugin.py +++ b/tests/unit/test_agent_plugin.py @@ -35,8 +35,9 @@ def test_the_manifest_holds_only_agent_plugins_fields() -> None: assert re.fullmatch(r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?", MANIFEST["name"]) -def test_the_plugin_has_the_cursor_plugins_name() -> None: - assert MANIFEST["name"] == CURSOR["name"] +def test_the_docs_uninstall_the_plugin_by_its_name() -> None: + docs = (ROOT / "docs" / "features" / "integrations" / "mcp-clients.md").read_text() + assert f"`copilot plugin uninstall {MANIFEST['name']}`" in " ".join(docs.split()) def test_the_entry_is_the_local_server_with_no_headers() -> None: From ebefcf8a5a536dd76901677a299e5906d8f88f45 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 08:20:43 +0000 Subject: [PATCH 09/11] The Copilot CLI section lists each case with the commands it needs Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/mcp-clients.md | 28 ++++++++++++++--------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 67c119e0fa..d0830a6c52 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -266,17 +266,23 @@ copilot plugin install ClickHouse/loom Copilot CLI installs it from the default branch. The plugin adds the `loom` MCP server at `http://localhost:7777/mcp?toolset=coding`, a single-user server on the same machine, and -the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. The URL is fixed -and a user entry named `loom` does not replace it, so for a team server skip the plugin, or -remove it with `copilot plugin uninstall clickhouse-loom` (`loom-code-skill` for the -marketplace install below), and add the entry from the table. An earlier install of this -repository is named `loom-code-skill` and has only the skills: `copilot plugin update -loom-code-skill` turns it into this plugin, while installing again without updating keeps -both and loads the skills twice. The `loom-code-skill` entry of the Claude Code marketplace -(`copilot plugin marketplace add ClickHouse/loom`) installs the same package, MCP server -included. Checked with Copilot CLI 1.0.112: the install, the update, the marketplace -install, `copilot mcp get loom`, and MCP `initialize` and `tools/list` through the entry -pointed at a local Loom on another port. A Copilot session needs a sign-in and was not run. +the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. + +- **Team server**: the URL is fixed and a user entry named `loom` does not replace it, so + skip the plugin, or remove it with `copilot plugin uninstall clickhouse-loom`, and add the + entry from the table. +- **Earlier install**: an install of this repository made before the plugin is named + `loom-code-skill` and has only the skills. `copilot plugin update loom-code-skill` turns + it into this plugin; installing again without updating keeps both and loads the skills + twice. +- **Claude Code marketplace**: `copilot plugin marketplace add ClickHouse/loom`, then + `copilot plugin install loom-code-skill@loom`, installs the same package, MCP server + included, under the name `loom-code-skill`. + +Checked with Copilot CLI 1.0.112: the install, the update, the marketplace install, +`copilot mcp get loom`, and MCP `initialize` and `tools/list` through the entry pointed at +a local Loom on another port. A Copilot session needs a sign-in and was not run, so whether +a session offers the tools to the model is untested. ### Hosted builders and chat apps From 32414e4c68f930eecaafdc1c3ce18910bf5a0e74 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 08:26:05 +0000 Subject: [PATCH 10/11] The Copilot CLI section names both uninstall commands and keeps a team server off the update Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/mcp-clients.md | 13 +++++++------ tests/unit/test_agent_plugin.py | 11 ++++++++--- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index d0830a6c52..f89e5a6ec2 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -269,12 +269,13 @@ Copilot CLI installs it from the default branch. The plugin adds the `loom` MCP the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. - **Team server**: the URL is fixed and a user entry named `loom` does not replace it, so - skip the plugin, or remove it with `copilot plugin uninstall clickhouse-loom`, and add the - entry from the table. -- **Earlier install**: an install of this repository made before the plugin is named - `loom-code-skill` and has only the skills. `copilot plugin update loom-code-skill` turns - it into this plugin; installing again without updating keeps both and loads the skills - twice. + skip the plugin and add the entry from the table. To remove an installed one, run + `copilot plugin uninstall clickhouse-loom`, or `copilot plugin uninstall loom-code-skill` + for an install named `loom-code-skill` (below). +- **Skills only**: an install named `loom-code-skill` from this repository has only the + skills. `copilot plugin update loom-code-skill` turns it into this plugin, local entry + included, so on a team server uninstall it instead; installing again without updating + keeps both and loads the skills twice. - **Claude Code marketplace**: `copilot plugin marketplace add ClickHouse/loom`, then `copilot plugin install loom-code-skill@loom`, installs the same package, MCP server included, under the name `loom-code-skill`. diff --git a/tests/unit/test_agent_plugin.py b/tests/unit/test_agent_plugin.py index a3554f13c0..c07dd58a54 100644 --- a/tests/unit/test_agent_plugin.py +++ b/tests/unit/test_agent_plugin.py @@ -35,9 +35,14 @@ def test_the_manifest_holds_only_agent_plugins_fields() -> None: assert re.fullmatch(r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?", MANIFEST["name"]) -def test_the_docs_uninstall_the_plugin_by_its_name() -> None: - docs = (ROOT / "docs" / "features" / "integrations" / "mcp-clients.md").read_text() - assert f"`copilot plugin uninstall {MANIFEST['name']}`" in " ".join(docs.split()) +def test_the_docs_uninstall_both_install_names() -> None: + # A repository install is named by plugin.json; Copilot CLI names a marketplace install + # after the .claude-plugin marketplace entry whose source is the repository root. + marketplace = json.loads((ROOT / ".claude-plugin" / "marketplace.json").read_text()) + (root_entry,) = [e for e in marketplace["plugins"] if e["source"] == "./"] + docs = " ".join((ROOT / "docs/features/integrations/mcp-clients.md").read_text().split()) + for name in (MANIFEST["name"], root_entry["name"]): + assert f"`copilot plugin uninstall {name}`" in docs def test_the_entry_is_the_local_server_with_no_headers() -> None: From 9fa69728c69263852cf6c061ffcb86928485ea25 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Mon, 16 Nov 2026 08:33:55 +0000 Subject: [PATCH 11/11] The Copilot CLI skills-only case names how to tell it apart Co-Authored-By: Claude Opus 5.5 Signed-off-by: zlareb1 --- docs/features/integrations/mcp-clients.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index f89e5a6ec2..b066fc8ecf 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -272,10 +272,10 @@ the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. skip the plugin and add the entry from the table. To remove an installed one, run `copilot plugin uninstall clickhouse-loom`, or `copilot plugin uninstall loom-code-skill` for an install named `loom-code-skill` (below). -- **Skills only**: an install named `loom-code-skill` from this repository has only the - skills. `copilot plugin update loom-code-skill` turns it into this plugin, local entry - included, so on a team server uninstall it instead; installing again without updating - keeps both and loads the skills twice. +- **Skills only**: a `loom-code-skill` install that `copilot mcp get loom` does not list + has only the skills. `copilot plugin update loom-code-skill` turns it into this plugin, + local entry included, so on a team server uninstall it instead; installing again without + updating keeps both and loads the skills twice. - **Claude Code marketplace**: `copilot plugin marketplace add ClickHouse/loom`, then `copilot plugin install loom-code-skill@loom`, installs the same package, MCP server included, under the name `loom-code-skill`.