docker-mcp-server 2.2.2__tar.gz → 2.2.4__tar.gz

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.4}/.dockerignore

@@ -20,6 +20,7 @@ wheels
 .cursor
 .claude
 tests
+skills
 .DS_Store
 *~
 *.bak

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.4}/.github/copilot-instructions.md

@@ -4,7 +4,7 @@ This file provides guidance to GitHub Copilot when working with code in this rep
 
 ## Project
 
-`docker-mcp` is a Python MCP (Model Context Protocol) server that exposes the Docker SDK for Python — plus selected docker CLI features (Compose, Stack, Buildx, Scout, Context) and direct OCI-registry HTTPS access — as MCP tools. It requires Python >=3.14 and is managed with `uv`. It is published to PyPI as **`docker-mcp-server`** and as a container image to GHCR (`ghcr.io/l337-org/docker-mcp-server`), mirrored to Docker Hub (`gavinlucas/docker-mcp-server`) when the opt-in `DOCKERHUB_*` release secrets are configured (the import package stays `docker_mcp`, the repo stays `…/docker-mcp`); two console scripts — `docker-mcp` and `docker-mcp-server` — both target `docker_mcp:main`. A third distribution channel packages the server as a **Claude Desktop Extension (`.mcpb`)** attached to each GitHub Release (see "Desktop Extension (MCPB)" below). A fourth channel (**Homebrew tap**) exists in `L337-org/homebrew-tap` but is currently **paused** — see "Homebrew tap" below.
+`docker-mcp` is a Python MCP (Model Context Protocol) server that exposes the Docker SDK for Python - plus selected docker CLI features (Compose, Stack, Buildx, Scout, Context) and direct OCI-registry HTTPS access - as MCP tools. It requires Python >=3.14 and is managed with `uv`. It is published to PyPI as **`docker-mcp-server`** and as a container image to GHCR (`ghcr.io/l337-org/docker-mcp-server`), mirrored to Docker Hub (`gavinlucas/docker-mcp-server`) when the opt-in `DOCKERHUB_*` release secrets are configured (the import package stays `docker_mcp`, the repo stays `…/docker-mcp`); two console scripts - `docker-mcp` and `docker-mcp-server` - both target `docker_mcp:main`. A third distribution channel packages the server as a **Claude Desktop Extension (`.mcpb`)** attached to each GitHub Release (see "Desktop Extension (MCPB)" below). A fourth channel (**Homebrew tap**) exists in `L337-org/homebrew-tap` but is currently **paused** - see "Homebrew tap" below. The repo additionally ships a **Claude Code agent skill** in `skills/l337-docker/` - deliberately **not** a channel for the server but a CLI-only *alternative* to it, attached to each Release as a single `.tar.gz`; see "Agent skill" below.
 
 The `docker` dep uses the `[ssh]` extra (paramiko), so `DOCKER_HOST=ssh://…` works via a pure-Python transport (no system `ssh` binary; works in the container images). docker-py auto-selects paramiko for `ssh://`, so there's no transport code — only the `ssh://` branch in `system._connection_help`. CLI-backed tools (Compose, Stack, Buildx, Scout, Context) shell out to `docker`, which would otherwise need the system `ssh` client — instead, `_cli.py:run_docker` detects `DOCKER_HOST=ssh://…` and routes the subprocess through a per-call local TCP proxy (`docker_mcp/tools/_ssh_proxy.py`) that opens its own paramiko connection and runs `docker system dial-stdio` over it, so the CLI authenticates the same way the docker-py-backed tools do, with no system `ssh` binary involved (except a `ProxyCommand` in `~/.ssh/config` for bastion/jump-host setups, which paramiko runs as an external command — commonly `ssh -W %h:%p ...` — for both tool families alike). With no local `docker` binary (or plugin) at all, all of those except the `context_*` tools (which manage *this* host's own CLI contexts) fall back to running the command on the `ssh://` host itself — see "SSH remote-exec fallback" under the CLI shell-out policy. Both the docker-py-backed and CLI-backed SSH connections fall back from IPv6 to IPv4 on any connect failure (not just paramiko's own narrower retry) via `_ssh_proxy.py:connect_socket_with_family_fallback` — see "Client / CLI" below.
 
@@ -34,10 +34,10 @@ from docker_mcp.server import mcp       # resource modules only
 
 `DOCKER_MCP_SERVER_HOSTS` lets one server manage several daemons in a session (e.g. local dev + remote prod). **When set, `DOCKER_HOST` is ignored** (a one-time stderr notice fires when both are set); unset = today's single-daemon behavior (`DOCKER_HOST`, else auto-discovery). The mcpb bundle exposes only this field. `_hosts.py` lives at the package root (like `_env.py`, so `server.py` can import it without pulling in `docker_mcp.tools`) and parses the var into a pinned `{label: Host}` registry — pure env + Docker-config-file reads, no docker-py/CLI calls:
 
-- **Grammar.** No `=` in the value → bare single-host shorthand (`ssh://ops@prod(ro)`, `auto`, `local`, empty → `auto`); with `=` → comma-separated `label=endpoint` list. `endpoint` is the keyword `auto`/`local` or a `unix://`/`tcp://`/`ssh://`/`npipe://` URL, with combinable trailing markers `(ro)` (read-only) and `(tls=<dir>)` (a tcp+TLS cert dir; **`ca.pem` is required** — the daemon is always verified against it — and `cert.pem`+`key.pem` are optional, present together for mutual TLS or absent for verify-the-daemon-only, e.g. a self-signed daemon pinned via `ca.pem`). **Fail-fast** (`HostConfigError` → stderr + non-zero exit) on duplicate/empty/invalid labels, a missing `=`, an unknown marker, `(tls=)` on a non-tcp endpoint, a missing `ca.pem` or a lone `cert.pem`/`key.pem`, or an unrecognized scheme.
+- **Grammar.** No `=` in the value → bare single-host shorthand (`ssh://ops@prod(ro)`, `auto`, `local`, empty → `auto`); with `=` → comma-separated `label=endpoint` list. `endpoint` is the keyword `auto`/`local` or a `unix://`/`tcp://`/`ssh://`/`npipe://` URL, with combinable trailing markers `(ro)` (read-only), `(nd)` (non-destructive — blocks only DESTRUCTIVE calls; `(ro)` already implies it, so combining is harmless but redundant) and `(tls=<dir>)` (a tcp+TLS cert dir; **`ca.pem` is required** — the daemon is always verified against it — and `cert.pem`+`key.pem` are optional, present together for mutual TLS or absent for verify-the-daemon-only, e.g. a self-signed daemon pinned via `ca.pem`). **Fail-fast** (`HostConfigError` → stderr + non-zero exit) on duplicate/empty/invalid labels, a missing `=`, an unknown marker, `(tls=)` on a non-tcp endpoint, a missing `ca.pem` or a lone `cert.pem`/`key.pem`, or an unrecognized scheme.
 - **`auto`/`local`/`default` are resolved to concrete URLs by us and pinned at `load()` (startup)** so the docker-py SDK and the CLI shell-out target the *same* daemon for a label (auditable) and a mid-session `docker context use` can't silently move a label. `default` = the first registry entry = the omitted-`host` fallback, and is **not** a selectable label. `load()` runs in `docker_mcp/__init__.py` before the tools import (the `@tool()` decorator and resources read `is_multi()`/`labels()` at registration) and scrubs whole-value `${...}` placeholders first.
-- **Per-call host selection (no modal active-host state).** Every daemon-targeting tool declares `host: str | None = None` and threads it to `_get_client(host)` / `run_docker(..., host=host)`. The `@tool()` decorator does **display-only schema surgery** (`_apply_host_schema`, like `_slim_schema`, gated on `_hosts.is_multi()`) — strip `host` in single-host mode (footprint-neutral), or constrain it to an `enum` of the labels and mark it required for writes in multi-host mode — and wraps the tool with `_enforce_host_guard` (multi-host: writes require an explicit `host`, unknown labels rejected, writes to an `(ro)` host refused; read-only tools and the `_CONNECTION_CONTROL` set `system_close`/`system_reconnect`/`system_login`/`system_logout` may omit `host`). The guard is wrapped on when `_host_guard_needed()` — multi-host **or a single host flagged `(ro)`**: a lone `(ro)` host has its `host` param stripped (footprint-neutral) but its writes are still refused, so the per-host `(ro)` marker is honored even in single-host mode (distinct from `DOCKER_MCP_SERVER_READONLY`, which drops write tools entirely); a single *writable* host wires no guard. **Excluded** (no `host` param): `registry`/`hub_*` (HTTPS, no daemon) and `context` (manages the host's CLI contexts).
-- **Client / CLI.** `system.py` keeps a lazy pool `_clients` keyed by label with tiered per-host TLS (`(tls=)` dir → global `DOCKER_CERT_PATH`/`DOCKER_TLS_VERIFY` → plaintext); the legacy single host still uses `_build_default_client`/`from_env` unchanged. **`system_reconnect(host=None)` is rebuild-only** — it can't retarget to an arbitrary URL (edit the registry + restart), closing a trust-expansion hole. `system_close(host=None)` closes all/one. `startup_preflight` pings the default host but detects self-id against the *self host* (first local-transport entry, which can differ from a remote default); `guard_not_self(container, host=)` only fires on the self host. `_cli.py:_apply_host_env` injects the resolved `DOCKER_HOST` + per-host TLS into the child env for an explicit host. Every `ssh://` URL is run through `_ensure_reachable_family(_ensure_ssh_port(url))` before being handed to docker-py: `_ensure_ssh_port` splices in a `~/.ssh/config` `Port` that `docker.utils.parse_host()` would otherwise hardcode to 22 before `SSHHTTPAdapter` ever sees it; `_ensure_reachable_family` works around paramiko's own connect() only retrying the next resolved address family on `ECONNREFUSED`/`EHOSTUNREACH` (not `ETIMEDOUT`, what a broken IPv6 route actually produces) by probe-connecting itself via `_ssh_proxy.connect_socket_with_family_fallback` and splicing the address that answered into the URL as a literal IP — no monkeypatching of docker-py internals. A URL that's already a literal address, or where every candidate fails, is left unchanged. When reviewing a change near ssh:// connection handling, check whether both `_ensure_ssh_port` and `_ensure_reachable_family` are still being composed at every call site that builds a docker-py client from a URL.
+- **Per-call host selection (no modal active-host state).** Every daemon-targeting tool declares `host: str | None = None` and threads it to `_get_client(host)` / `run_docker(..., host=host)`. The `@tool()` decorator does **display-only schema surgery** (`_apply_host_schema`, like `_slim_schema`, gated on `_hosts.is_multi()`) — strip `host` in single-host mode (footprint-neutral), or constrain it to an `enum` of the labels and mark it required for writes in multi-host mode — and wraps the tool with `_enforce_host_guard` (multi-host: writes require an explicit `host`, unknown labels rejected, writes to an `(ro)` host refused, DESTRUCTIVE calls to an `(nd)` host refused; read-only tools and the `_CONNECTION_CONTROL` set `system_close`/`system_reconnect`/`system_login`/`system_logout` may omit `host`). The guard is wrapped on when `_host_guard_needed()` — multi-host **or a single host flagged `(ro)` or `(nd)`**: a lone `(ro)`/`(nd)` host has its `host` param stripped (footprint-neutral) but its refusals still apply, so the per-host markers are honored even in single-host mode (distinct from `DOCKER_MCP_SERVER_READONLY`/`_NO_DESTRUCTIVE`, which drop tools entirely). A host with both markers is refused by `(ro)` first — it's strictly stronger, so `(nd)` never fires for it. A single *unrestricted* host wires no guard. **Excluded** (no `host` param): `registry`/`hub_*` (HTTPS, no daemon) and `context` (manages the host's CLI contexts).
+- **Client / CLI.** `system.py` keeps a lazy pool `_clients` keyed by label with tiered per-host TLS (`(tls=)` dir → global `DOCKER_CERT_PATH`/`DOCKER_TLS_VERIFY` → plaintext); the legacy single host still uses `_build_default_client`/`from_env` unchanged. **Every `from_env` call must pass `use_context=False`** — docker-py 7.2.0 (the declared floor, for this reason) made `from_env` resolve the active Docker CLI context when the environment yields no `base_url`, duplicating resolution `_hosts.py` already does and pins at `load()`; a new `from_env` call site without it is a review finding, as is relaxing the `docker[ssh]>=7.2.0` floor. **`system_reconnect(host=None)` is rebuild-only** — it can't retarget to an arbitrary URL (edit the registry + restart), closing a trust-expansion hole. `system_close(host=None)` closes all/one. `startup_preflight` pings the default host but detects self-id against the *self host* (first local-transport entry, which can differ from a remote default); `guard_not_self(container, host=)` only fires on the self host. `_cli.py:_apply_host_env` injects the resolved `DOCKER_HOST` + per-host TLS into the child env for an explicit host. Every `ssh://` URL is run through `_ensure_reachable_family(_ensure_ssh_port(url))` before being handed to docker-py: `_ensure_ssh_port` splices in a `~/.ssh/config` `Port` that `docker.utils.parse_host()` would otherwise hardcode to 22 before `SSHHTTPAdapter` ever sees it; `_ensure_reachable_family` works around paramiko's own connect() only retrying the next resolved address family on `ECONNREFUSED`/`EHOSTUNREACH` (not `ETIMEDOUT`, what a broken IPv6 route actually produces) by probe-connecting itself via `_ssh_proxy.connect_socket_with_family_fallback` and splicing the address that answered into the URL as a literal IP — no monkeypatching of docker-py internals. A URL that's already a literal address, or where every candidate fails, is left unchanged. When reviewing a change near ssh:// connection handling, check whether both `_ensure_ssh_port` and `_ensure_reachable_family` are still being composed at every call site that builds a docker-py client from a URL.
 - **Surfaces.** `host_list` tool + `docker-mcp://hosts` resource expose the resolved registry; the router gains a multi-host caveat; the container observability resources go host-aware (empty-authority `docker:///…` for the default + `docker://{host}/…` variants); a `prompt(multi_host=True)` gate plus the `survey_hosts` prompt register only with 2+ hosts.
 
 **When reviewing a PR that changes the host grammar, env precedence, or the per-tool/resource/prompt host surface, this section is the spec.**
@@ -74,9 +74,11 @@ Each file maps to one Docker SDK domain or one CLI/registry feature area. Unders
 `docker_mcp/tools/__init__.py` star-imports all public modules so `docker_mcp/__init__.py` only needs `from docker_mcp import tools`.
 
 ### Tests (`tests/`)
-Each `docker_mcp/tools/<module>.py` has a corresponding `tests/test_<module>.py`; `tests/test_server.py` covers the classification/registration machinery. Tests use pytest with mocks. `tests/integration/` holds tests that need a real Docker daemon — excluded by default, run with `uv run pytest -m integration`; `tests/integration/test_remote_exec.py` needs a remote *ssh://* host instead and is gated on `DOCKER_MCP_TEST_SSH_HOST` (not a server tunable, so deliberately outside the `DOCKER_MCP_SERVER_*` namespace). `tests/conftest.py` clears the `DOCKER_MCP_SERVER_*` env switches (and pins the host registry to one local daemon) so the suite is hermetic. `tests/test_docs.py` checks the repo's own prose — today that any line describing the CLI-backed surface names a complete set of those domains, derived from `server.py`'s domain tuples; when reviewing a docs change, an incomplete enumeration fails there rather than needing to be spotted.
+Each `docker_mcp/tools/<module>.py` has a corresponding `tests/test_<module>.py`; `tests/test_server.py` covers the classification/registration machinery. Tests use pytest with mocks. `tests/integration/` holds tests that need a real Docker daemon - excluded by default, run with `uv run pytest -m integration`; `tests/integration/test_remote_exec.py` needs a remote *ssh://* host instead and is gated on `DOCKER_MCP_TEST_SSH_HOST` (not a server tunable, so deliberately outside the `DOCKER_MCP_SERVER_*` namespace). `tests/conftest.py` clears the `DOCKER_MCP_SERVER_*` env switches (and pins the host registry to one local daemon) so the suite is hermetic. `tests/test_docs.py` checks the repo's own prose - today that any line describing the CLI-backed surface names a complete set of those domains, derived from `server.py`'s domain tuples; when reviewing a docs change, an incomplete enumeration fails there rather than needing to be spotted. `tests/test_skill.py` (static) and `tests/integration/test_skill.py` (daemon-backed) cover the `skills/l337-docker/` agent skill: frontmatter, cross-references, orphaned files, licence/attribution, one canonical lowercase provenance label, and a regression guard per shell/CLI trap the skill hit (`--until now` rejected, `timeout(1)` absent on macOS, `status` read-only in zsh, `compose ps` NDJSON vs `compose ls` array). Its parity checks derive from `tool_catalog()`, so **a PR adding a tool or domain fails until `MCP_VS_SKILLS.md`'s per-domain counts are updated** - when reviewing such a PR, expect that file to change too. The integration tests extract the skill's shell snippets from its markdown and execute them, so a snippet cannot drift from the CLI's actual behaviour; when reviewing a change to a snippet, check it is still the executed one rather than newly-unreferenced prose.
 
-CI (`.github/workflows/premerge.yaml`) enforces `pytest`, `ruff check`, `ruff format --check`, and `pyright` on every PR and push to main — all via `uv run`, so the dev-group pins in `pyproject.toml` (bumped by Dependabot's monthly uv pass) are the single tool-version source; the pre-commit hooks are local hooks running `uv run ruff …` for the same reason. CI installs with `uv sync --locked`, which fails if `uv.lock` disagrees with `pyproject.toml` instead of silently re-locking — so when reviewing a PR that touches only `uv.lock`, check its recorded `requires-dist` specifiers still match pyproject (a Dependabot lock rewrite once raised the cryptography cap in the lock alone). A non-required `Check docs mirror` job flags a PR that edits `CLAUDE.md` or `.github/copilot-instructions.md` without the other (the MIRROR RULE) — when reviewing such a PR, check whether the one-sided edit was intentional.
+**An integration test skips only for a cause it can name**, via `fail_unless_environmental` / `fail_unless_environmental_error` in `tests/integration/conftest.py`, which fail when the failure matches no entry in `_ENVIRONMENTAL_SIGNALS`. Three `scout` tools shipped broken because the tests skipped on any non-zero exit and reported a real defect as "offline or auth required". When reviewing a PR that adds an integration skip, check it names a specific tolerated condition; a blanket `except Exception` or `if returncode != 0: skip` is the defect, and the fix is to widen `_ENVIRONMENTAL_SIGNALS`, not the skip. `tests/integration/test_cli_flag_drift.py` asserts every literal CLI flag the tool modules pass still exists in the installed `--help`, which a mocked test cannot do; it has no exemption list by design, so a flag surviving as a hidden alias should be migrated to the documented spelling.
+
+CI (`.github/workflows/premerge.yaml`) enforces `pytest`, `ruff check`, `ruff format --check`, and `pyright` on every PR and push to main — all via `uv run`, so the dev-group pins in `pyproject.toml` (bumped by Dependabot's monthly uv pass) are the single tool-version source; the pre-commit hooks are local hooks running `uv run ruff …` for the same reason. CI installs with `uv sync --locked`, which fails if `uv.lock` disagrees with `pyproject.toml` instead of silently re-locking — so when reviewing a PR that touches only `uv.lock`, check its recorded `requires-dist` specifiers still match pyproject (a Dependabot lock rewrite once raised the cryptography cap in the lock alone). A non-required `Check docs mirror` job flags a PR that edits `CLAUDE.md` or `.github/copilot-instructions.md` without the other (the MIRROR RULE) — when reviewing such a PR, check whether the one-sided edit was intentional. An `Action pins are immutable` job fails the build when any `uses:` reference in `.github/workflows` or `.github/actions` names a tag or branch instead of a full 40-hex commit SHA: `publish.yaml` mints a PyPI Trusted Publishing OIDC token (`id-token: write`), pushes to GHCR (`packages: write`) and uploads release assets (`contents: write`), so a repointed tag would execute inside the jobs holding this project's strongest credentials - and Trusted Publishing has no stored token to steal, so executing there is the whole attack. First-party `actions/*` get no exemption (Dependabot maintains the SHA and its trailing `# vX.Y.Z` comment); local `./` actions are exempt; bare, quoted and uppercase SHAs are all accepted, since hex is case-insensitive and GitHub resolves an uppercase ref. The trailing version comment is convention, not enforced. When adding a step, look up the SHA (`gh api repos/<owner>/<action>/git/ref/tags/<tag> --jq .object.sha`) rather than writing `@vN`. The job is a port of the identically-named one in [L337-org/apt](https://github.com/L337-org/apt) (the reference implementation; `send-to-influx` has the third copy) - keep all three in step rather than letting them drift.
 
 A required `Check fresh resolve still imports` job (same workflow) covers what every `--locked` job above cannot: it resolves `pyproject.toml` with `uv pip install` (the pip-compatible interface, which never touches `uv.lock`) into a throwaway venv, then runs `import docker_mcp` and `docker-mcp-server --version` against that fresh install — the same set a `uvx`/`pip install` would actually get today, not the pinned known-good set in `uv.lock`. It reports a resolution failure (specifier unsatisfiable) separately from an import failure (resolved fine, broke on import), since a PR fixing one looks different from a PR fixing the other. When reviewing a dependency-cap change (raising or removing a cap, e.g. on `mcp` or `cryptography`), this job's result is the one that tells you whether the wider range still imports — a green `pytest-run` does not, since it stays on the locked pins.
 
@@ -95,15 +97,29 @@ A third distribution channel for one-click install in Claude Desktop. Repo-root
 
 ### Homebrew tap (`L337-org/homebrew-tap`) — PAUSED
 
-The infrastructure exists (`scripts/docker-mcp-server.rb.tpl`, `.github/workflows/publish-homebrew.yaml`, `L337-org/homebrew-tap`) but the **release trigger is disabled** pending resolution of a Homebrew dylib linkage issue: pre-built PyPI wheels for `pydantic_core` lack `-headerpad_max_install_names`, so Homebrew's post-install relocation step fails to rewrite the `@rpath` ID (the binary's Mach-O header has no room for the longer absolute path). The workflow is `workflow_dispatch`-only until a fix is found. The channel is not advertised in the README. To re-enable: add `release: types: [published]` back to `publish-homebrew.yaml`'s `on:` block and re-add the Homebrew section to the README.
+The infrastructure exists (`scripts/docker-mcp-server.rb.tpl`, `.github/workflows/publish-homebrew.yaml`, `L337-org/homebrew-tap`) but the **release trigger is disabled** pending resolution of a Homebrew dylib linkage issue: pre-built PyPI wheels for `pydantic_core` lack `-headerpad_max_install_names`, so Homebrew's post-install relocation step fails to rewrite the `@rpath` ID (the binary's Mach-O header has no room for the longer absolute path). The workflow is `workflow_dispatch`-only until a fix is found. The channel is not advertised in this repo's README, and the tap's own README documents the pause rather than offering an install command.
+
+**`skip_clean "libexec"` in the template is a candidate workaround, not the fix, and it is unverified.** `skip_clean` affects only Homebrew's post-install *cleanup* phase (symbol stripping, `.la` pruning, permission fixing) — verified against Homebrew 6.0.17, where `skip_clean?` is read only in `cleaner.rb`. It does **not** disable the separate keg-relocation step that rewrites dylib IDs via `install_name_tool`, which is where the headerpad failure occurs. Do not read its presence as evidence the issue is closed, and reject any claim that it suppresses relocation — that error has now been caught twice in review, both times in the Ruby formula comment rather than in Python code. The template also keeps `Formula[...].opt_bin` rather than the `formula_opt_bin` helper `brew style` recommends, deliberately: that helper only exists from Homebrew 6.0.3, so adopting it would fail the formula on older Homebrew for a style-only gain (labelled at the line).
+
+To re-enable: (1) add `release: types: [published]` back to `publish-homebrew.yaml`'s `on:` block; (2) re-add the Homebrew section to this repo's README; (3) restore the tap's own README, which currently documents the pause — a release regenerates only `Formula/docker-mcp-server.rb`, never that file, so it will keep saying "paused" until edited by hand; (4) confirm the tap push still lands. That last one has never been exercised since the tap gained a `main` ruleset (2026-08-11) requiring signed commits, a PR, and Copilot review: the workflow does a raw `git push` of an unsigned `github-actions[bot]` commit, which only succeeds if the identity behind `secrets.TAP_GITHUB_TOKEN` holds a ruleset bypass. The tap's ruleset does grant `OrganizationAdmin` and repo-admin bypass `always`, so an org-admin-owned PAT should pass — but that is an inference, not an observation, so watch the first run.
 
 ### MCP Registry (`server.json`)
 
-A discovery listing in the official MCP Registry (`registry.modelcontextprotocol.io`), which stores only metadata pointing at the existing artifacts. `server.json` (repo root, name `io.github.L337-org/docker-mcp-server`) declares three package types — `pypi`, `oci` (GHCR image), `mcpb` (release `.mcpb`). The `registry` job in `.github/workflows/publish.yaml` stamps the tag version + the published `.mcpb`'s `fileSha256` into `server.json`, authenticates via GitHub OIDC (`id-token: write`, no secret), and runs `mcp-publisher publish`. Ownership is verified per package against `server.json`'s `name`, so three markers must equal it: the `<!-- mcp-name: … -->` comment in `README.md` (PyPI), the `io.modelcontextprotocol.server.name` image label in the `images` job (OCI), and the `.mcpb` URL + hash (MCPB). Keep them in sync with `server.json`'s `name`.
+A discovery listing in the official MCP Registry (`registry.modelcontextprotocol.io`), which stores only metadata pointing at the existing artifacts. `server.json` (repo root, name `io.github.L337-org/docker-mcp-server`) declares three package types — `pypi`, `oci` (GHCR image), `mcpb` (release `.mcpb`). The `registry` job in `.github/workflows/publish.yaml` stamps the tag version + the published `.mcpb`'s `fileSha256` into `server.json`, authenticates via GitHub OIDC (`id-token: write`, no secret), and runs `mcp-publisher publish`. Ownership is verified per package against `server.json`'s `name`, so three markers must equal it: the `<!-- mcp-name: … -->` comment in `README.md` (PyPI), the `io.modelcontextprotocol.server.name` image label in the `images` job (OCI), and the `.mcpb` URL + hash (MCPB). Keep them in sync with `server.json`'s `name`. **`server.json`'s committed version is also kept in step with `pyproject.toml`** - `tests/test_pyproject_pins.py::test_server_json_versions_match_pyproject` scans every version-shaped token (the version appears in `version`, the pypi package's `version`, and inside both the oci and mcpb `identifier` strings), so a version-bump PR must touch `server.json` too. It was previously left stale on the grounds that the release job restamps it; that is true but the stale value read as drift to every reader and every scheduled audit, so consistency won. When reviewing a version bump, expect `pyproject.toml`, `manifest.json`, `server.json` and `uv.lock` to move together.
+
+### Agent skill (`skills/l337-docker/`)
+
+A **Claude Code agent skill** driving Docker entirely through the `docker` CLI - the CLI-only alternative to running this server, a peer of it rather than a channel for it. Nothing in `docker_mcp/` imports or depends on it. Layout mirrors the server's three-layer discovery model: `SKILL.md` is the always-loaded router (preflight, always-apply rules, JSON-parsing contract, daemon targeting) mapping into `reference/` (11 domain files) and `workflows/` (5 files, ported from the MCP prompts); the comparison/coverage record is `MCP_VS_SKILLS.md` at the repo root (not inside the skill, which ships standalone and links to it on GitHub); `LICENSE` is a copy of the repo's MIT licence so the skill stands alone when downloaded. It follows the open [Agent Skills specification](https://agentskills.io/specification), so it is not Claude-specific: GitHub Copilot reads the same `SKILL.md` from `.github/skills`, `.agents/skills` or the same `.claude/skills` directory. `tests/test_skill.py` asserts the spec's `name`/`description` constraints, so an edit cannot quietly make it Claude-only.
+
+**Guards are conventions here, not enforcement** - do not let a PR describe them otherwise. `DOCKER_MCP_SERVER_READONLY`, per-host `(ro)`/`(nd)` and the self-termination guard refuse at the server's call boundary; a skill has none, so its rules are instructions a model can skip. The skill declares **no tool-permission frontmatter** (`tools` / `disallowedTools`, nor the slash-command `allowed-tools` spelling) on purpose: an allow-list covering `docker` would pre-approve `docker rm -f` and defeat the skill's own confirmation rule - flag any PR adding one. Provenance labels are `l337-docker-skill.*`, a separate footprint from the server's `docker-mcp-server.managed=true`; the skill must never stamp the server's label, and the prefix stays **lowercase** because Docker label keys are case-sensitive (a mixed-case key silently matches nothing in a lowercase filter, so a teardown reports a clean daemon while resources remain).
+
+Distribution is the `skill` job in `publish.yaml`. There is no official packaging format for a skill (unlike `.mcpb` for MCP servers) - a plain directory is the unit, so the archive is that directory rooted at `l337-docker/`, which is load-bearing for the install UX. tar.gz only: `tar` ships by default on macOS, Linux and Windows 10 1803+, while `unzip` is often absent on minimal Linux images. When reviewing a change to the skill's structure, provenance label, or the server's tool/prompt surface, check this section and `MCP_VS_SKILLS.md` stay accurate.
+
+**`MCP_VS_SKILLS.md`'s measured figures are regenerated by `scripts/measure-comparison-figures.py`, never hand-counted** - token costs for all five configurations the document names (full, read-only, triage, core, floor), the description/parameter statistics, the skill's per-file costs and the per-task comparisons. Run it with `uv run scripts/measure-comparison-figures.py` (`--json` for structured output); a PEP 723 header pins its own `tiktoken` and installs the working tree editable, so it needs nothing in the dev group. It is developer-only and **report-only** (same footing as `scripts/build-mcpb.sh`) and **deliberately not a CI gate**: token figures move a few tokens on any docstring edit, so asserting them would fail constantly and signal nothing - **flag any PR proposing to promote it to a merge gate**, and flag a PR that edits a figure by hand instead of regenerating it. Drift is watched by the weekly "MCP vs skills figure drift" routine in `L337-org/claude-routines`, which opens a PR when a movement is worth republishing. What `tests/test_skill.py` *does* assert (binary, silent when broken): every configuration the script measures is still a document row, the published `DOCKER_MCP_SERVER_DISABLE` line matches the triage config the figures were measured with, and every per-task composition names registered tools and existing skill files. The method lives in the script's docstring: `tiktoken` `cl100k_base` over the wire form (`model_dump_json(by_alias=True, exclude_none=True)` - a client is sent `inputSchema`, not `input_schema`). Per-task compositions and the two skill prose counts are **chosen or heuristic, not measured**, and labelled so in the output; the document's eager-idle total omits resource templates, so the script reports that figure both ways.
 
 ### Release pipeline (`.github/workflows/publish.yaml`)
 
-All publishing runs through one workflow on each **published GitHub Release**: `preflight` → `pypi` ∥ `images`(→`dockerhub-description`) ∥ `mcpb` → `registry` → `verify`, plus a `notify` job on failure. `preflight` resolves the tag once (every job checks out **the tag ref**) and fails fast if the tag disagrees with the committed `pyproject.toml` / `manifest.json` / `uv.lock` self-entry versions — preventing a split-brain release where PyPI ships the pyproject version and everything else ships the tag version. It also refuses to run when `github.repository_owner` isn't `L337-org`, so a release published from a fork (or mis-timed around a repo transfer) fails before anything ships rather than half-publishing. `verify` confirms all channels serve the version (PyPI JSON API, both GHCR tags, `.mcpb` asset + checksum, registry listing). `notify` files a deduplicated `ci-failure` + `wf:release` issue via `.github/actions/file-failure-issue` (one open issue per failure stream; a scheduled Claude responder routine polls `ci-failure` issues). Re-runs go through `workflow_dispatch` with the tag and are idempotent end-to-end (`skip-existing` on PyPI, re-pushed image tags, `--clobber` on the `.mcpb`, duplicate-tolerant registry publish). **PyPI Trusted Publishing pins the workflow *filename* (`publish.yaml`)** — when reviewing a PR that renames or splits this workflow, flag that the PyPI trusted publisher must be updated first. `.github/release.yml` (GitHub's release-*notes* config — a different file) groups generated notes; `publish-homebrew.yaml` (paused, dispatch-only) stays separate. When reviewing changes to the pipeline's job graph, ownership markers, or re-run semantics, check this section stays accurate.
+All publishing runs through one workflow on each **published GitHub Release**: `preflight` → `pypi` ∥ `images`(→`dockerhub-description`) ∥ `mcpb` → `registry` → `verify`, with `skill` running in parallel from `preflight` and joining at `verify`, plus a `notify` job on failure. `skill` is deliberately absent from `registry`'s `needs` (the registry entry doesn't reference the skill archives) but present in `verify`'s and `notify`'s - when reviewing a change to the job graph, check a new artifact job is wired into both, or verify races ahead of it and a pack failure files no issue. `preflight` resolves the tag once (every job checks out **the tag ref**) and fails fast if the tag disagrees with the committed `pyproject.toml` / `manifest.json` / `uv.lock` self-entry versions - preventing a split-brain release where PyPI ships the pyproject version and everything else ships the tag version. It also refuses to run when `github.repository_owner` isn't `L337-org`, so a release published from a fork (or mis-timed around a repo transfer) fails before anything ships rather than half-publishing. `verify` confirms all channels serve the version (PyPI JSON API, both GHCR tags, `.mcpb` asset + checksum, registry listing, and the skill archive - checksum plus an extraction asserting it is rooted at `l337-docker/SKILL.md` and stamps this release's `VERSION`). `notify` files a deduplicated `ci-failure` + `wf:release` issue via `.github/actions/file-failure-issue` (one open issue per failure stream; a scheduled Claude responder routine polls `ci-failure` issues). Re-runs go through `workflow_dispatch` with the tag and are idempotent end-to-end (`skip-existing` on PyPI, re-pushed image tags, `--clobber` on the `.mcpb` and the skill archive, duplicate-tolerant registry publish); the skill archive is additionally byte-reproducible (sorted entries, zeroed ownership, normalised mtimes, `gzip -n`), so a re-run republishes an identical checksum. **PyPI Trusted Publishing pins the workflow *filename* (`publish.yaml`)** - when reviewing a PR that renames or splits this workflow, flag that the PyPI trusted publisher must be updated first. `.github/release.yml` (GitHub's release-*notes* config - a different file) groups generated notes; `publish-homebrew.yaml` (paused, dispatch-only) stays separate. When reviewing changes to the pipeline's job graph, ownership markers, or re-run semantics, check this section stays accurate.
 
 ## Conventions
 
@@ -118,16 +134,38 @@ All publishing runs through one workflow on each **published GitHub Release**: `
   1.x spellings, canonical shared-param descriptions) — a violating tool fails CI.
 - **MIRROR RULE:** this file mirrors `CLAUDE.md` and drives Copilot review of every PR. Any change to project structure, conventions, env vars, or the tool/prompt/resource surface must update **both** files in the same PR — flag a PR that updates one but not the other.
 - New Docker functionality goes in the matching `docker_mcp/tools/<domain>.py` — do not create new tool files without a corresponding entry in `docker_mcp/tools/__init__.py` and a matching test file.
-- Tool functions are decorated with `@tool()` (imported from `docker_mcp.server`) and **must have a `TOOL_CATEGORIES` entry** in `docker_mcp/server.py`. A new tool module is a new domain — also add a `_DOMAIN_BLURBS` entry so the `instructions` router advertises it.
+- Tool functions are decorated with `@tool()` (imported from `docker_mcp.server`) and **must have a `TOOL_CATEGORIES` entry** in `docker_mcp/server.py`. A new tool module is a new domain - also add a `_DOMAIN_BLURBS` entry so the `instructions` router advertises it. A PR adding a tool must also bump the domain's count in `MCP_VS_SKILLS.md` (and cover the CLI equivalent in the matching `reference/` file); `tests/test_skill.py` derives the counts from `tool_catalog()`, so an unbumped count fails CI - a genuinely uncoverable tool belongs under "Structural gaps", not omitted silently.
 - A daemon-targeting tool declares `host: str | None = None` (last parameter) and threads it to `_get_client(host)` / `run_docker(..., host=host)`; it is intentionally **not** documented in the docstring `args:` (the `@tool()` decorator generates its description and strips/enum-injects it per mode — see the host-registry section). Registry/hub and context tools omit `host`.
+- **A parameter whose legal values are a genuinely closed set is typed `Literal[...]`, not `str`.**
+  Pydantic turns that into an `enum` in the advertised `inputSchema` (`_slim_schema` preserves it,
+  proven by a test) so an out-of-set value fails validation before anything executes, and the
+  docstring then drops the value list rather than repeating it. Verify the set against a primary
+  source - the subcommand's own `--help`, or docker-py's documented value list - never from
+  memory: `docker scout cves --only-severity CRITICAL` exits 0 reporting no vulnerabilities on an
+  image with three critical CVEs, and the daemon records an unrecognised `--scope` verbatim, so a
+  wrong value is not reliably rejected by Docker itself. Where the set is *not* provably closed
+  (compose validates `--protocol` not at all; buildx drivers are pluggable; docker-py documents no
+  values for `isolation`), leave it a `str` and record why at the parameter, so a later pass does
+  not re-propose it. `tests/test_server.py::test_closed_value_sets_are_advertised_as_enums` pins
+  the current set.
+- **The `@tool()` decorator is generic (`def tool[F: Callable[..., Any]](...) -> Callable[[F], F]`)
+  so pyright checks arguments at every tool call site**, in tests and at internal callers alike.
+  Annotating it as a bare `Callable` erases the parameter list and silently disables that checking
+  everywhere: a wrong type, an unknown keyword and a value outside a `Literal` all passed the gate
+  until this was fixed. `tests/test_server.py::test_pyright_still_checks_arguments_at_tool_call_sites`
+  runs pyright over those three deliberate errors, so it also fails if only the return annotation is
+  loosened while the type parameter stays. A test that must pass a deliberately invalid value marks
+  that one call `# pyright: ignore[reportArgumentType]` with a reason, rather than being softened to
+  a legal one.
 - Line length limit: 120 characters.
 - **Bound any externally-sourced bytes before buffering/parsing them, and parse safely.** CLI output is capped in `run_docker` (`MAX_CLI_OUTPUT_BYTES`); registry HTTP bodies are streamed and capped at `_MAX_RESPONSE_BYTES` in `registry.py` (registries are agent-pointed/untrusted; the cap is on the *decoded* stream, so it also stops a decompression bomb). New code reading an untrusted file or network body must apply a similar bound. Always `json.loads` (never `eval`); if YAML is ever parsed in Python, `yaml.safe_load` only — today nothing parses YAML in Python (Compose YAML is read by the `docker` CLI). Flag a PR that buffers an untrusted body unbounded.
+- **A URL taken from a response body is pinned to the origin it came from; a URL the caller named is not.** Who chose the destination is the distinction. A registry host in a tool argument is the caller's choice and the point of the `registry_*`/`hub_*` tools, so it is not restricted. A `next`/`Link` URL is the *response's* choice: `_validate_hub_next` requires Hub pagination to stay on `_HUB_API_BASE`'s scheme/host/port, and the OCI tag-list path keeps only the path from a `Link` header and re-applies the registry already being queried. A new paginating or link-following tool must do the same. **Do not flag `follow_redirects=True`, and do not suggest restricting redirects to the same host** - registries answer blob fetches with a redirect to a CDN on another host as normal operation (Docker Hub answers a config-blob GET with `307` to `production.cloudfront.docker.com`), so refusing cross-host redirects breaks `registry_image_config`; httpx strips `Authorization` on any cross-origin redirect, so a redirect cannot carry credentials, and it reaches nothing a tool argument could not reach directly. The read-only/no-destructive switches are **not** egress controls (the registry tools are read-only); `DOCKER_MCP_SERVER_DISABLE=registry` is.
 - Do not add comments that describe what the code does — only add comments for non-obvious constraints or workarounds.
 - **Target runtime is Python >=3.14** — when reviewing, assume current stable CPython grammar and stdlib are available and valid; do not flag 3.14-valid syntax as a bug. A concrete example reviewers (and older models) get wrong: [PEP 758](https://peps.python.org/pep-0758/) — **Status: Final, Python-Version: 3.14** — makes parentheses optional in `except` / `except*` clauses, so `except OSError, ValueError:` is a valid two-exception handler, **not** a `SyntaxError` (verifiable: `python3.14 -c "import ast; ast.parse('try:\n pass\nexcept OSError, ValueError:\n pass')"` parses it as a tuple handler). The `as`-binding form still requires parens (`except (OSError, ValueError) as e:`), and `ruff` (pyupgrade, 3.14 target) may rewrite to the unparenthesized form.
 
 ### Provenance labels
 
-Resources this server **creates** are stamped with `docker-mcp-server.*` provenance labels (`.managed=true`, `.version`, `.tool`, `.created`) so the agent/operator can later enumerate that footprint (the `managed_only=True` arg on `container_list` / `network_list` / `volume_list` / `service_list`, or `--filter label=docker-mcp-server.managed=true`; the `prune_managed` prompt removes only the managed footprint). On by default; opt out with `DOCKER_MCP_SERVER_NO_LABELS=1`. When adding a new create tool that accepts a `labels` dict, route it through `docker_mcp/tools/_labels.py:with_provenance(labels, "<tool_name>")` — it merges provenance without overwriting caller keys and returns `None` (drop it via `drop_none`) when stamping is disabled and the caller passed nothing. **Image builds are intentionally not stamped** (a build label changes the image digest).
+Resources this server **creates** are stamped with `docker-mcp-server.*` provenance labels (`.managed=true`, `.version`, `.tool`, `.created`) so the agent/operator can later enumerate that footprint (the `managed_only=True` arg on `container_list` / `network_list` / `volume_list` / `service_list`, or `--filter label=docker-mcp-server.managed=true`; the `prune_managed` prompt removes only the managed footprint). On by default; opt out with `DOCKER_MCP_SERVER_NO_LABELS=1`. When adding a new create tool that accepts a `labels` dict, route it through `docker_mcp/tools/_labels.py:with_provenance(labels, "<tool_name>")` — it merges provenance without overwriting caller keys and returns `None` (drop it via `drop_none`) when stamping is disabled and the caller passed nothing. The seven stamped creators today are `container_run`, `container_create`, `network_create`, `volume_create`, `service_create`, `config_create`, `secret_create`. **Image builds are intentionally not stamped** (a build label changes the image digest); Compose/stack containers and `plugin_create` are also unstamped. The rule is conditional on the tool *accepting a `labels` dict* — a creator with nowhere to put a label is an expected exception, not an oversight, and should say so in its docstring rather than being flagged in review.
 
 ### CLI shell-out policy
 
@@ -251,6 +289,8 @@ clients keyword-search descriptions, so exact names double as retrieval anchors.
 
 `resources.py` also has one `@tool()`: **`docs_lookup(section=None)`** — a tool-callable mirror of `docker-docs://` for clients that can't read MCP resources (Claude Desktop, Cursor). It wraps `list_docs_sections()`/`get_docs_section()` directly (same behavior either way, including per-section domain refusal) and is one of `_NO_DOMAIN_TOOLS` — always registered regardless of `DOCKER_MCP_SERVER_DISABLE`. Several `extra_kwargs`-heavy tool docstrings and docs-reliant prompts point at it as the resource-read fallback — do the same for new ones in that shape.
 
+`resources.py` carries a second `@tool()`: **`tool_list(domain=None, category=None, keyword=None)`** — a tool-callable mirror of `docker-mcp://tool-catalog` and the only way to express structured queries over the surface (destructive tools, tools taking a `host`, what actually registered). Thin pass-through to `server.py:query_catalog()`, which reads `_tool_registry` (`ToolRecord` captures each tool's docstring summary and parameter names at registration). Lists **only registered** tools — a tool dropped by a switch or disabled domain is absent, not flagged, so a disabled capability is never advertised; `hidden_by_configuration` keeps the config auditable in aggregate. In `_NO_DOMAIN_TOOLS`, so it survives `DOCKER_MCP_SERVER_DISABLE` naming every domain. A new tool appears automatically; its docstring's first line is the summary a row carries, so keep that line standalone.
+
 ### MCP prompts
 
 `docker_mcp/tools/prompts.py` exposes `@prompt(description=..., domain=...)` templates (the `prompt` helper from `docker_mcp.server`, not `@mcp.prompt` directly) that return prompt strings to guide multi-step docker workflows (deploy, migrate, troubleshoot, prune, audit/security, networking, volume backup/restore, doc lookup). Each declares its primary `domain` so `DOCKER_MCP_SERVER_DISABLE` drops it with that domain; `domain=None` for general/cross-domain prompts. Use the same docstring format as tools.
@@ -262,16 +302,14 @@ Always verify the exact method name, parameter names, and return type at https:/
 
 When the high-level SDK lacks a method (e.g. swarm node removal, service rollback), use the low-level `APIClient` via `_get_client().api` (`remove_node`, `update_service`, `inspect_service`, …), documented at https://docker-py.readthedocs.io/en/stable/api.html — verified the same way. Prefer the high-level object API where it exists.
 
+Treat "the method exists" as separate from "the method works": the rendered docs show a docstring, not the URL a method builds. `plugin_push` is the standing example — docker-py's `Plugin.push()` / `APIClient.push_plugin()` POST to `/plugins/{name}/pull`, which the Engine does not define (push is `POST /plugins/{name}/push`), so they 404 everywhere; broken since 2017 and still in `main`, because upstream has no test for it. Where a documented method is provably broken, the ladder is: another public SDK path, then the correct endpoint via docker-py's private request helpers (`_url`/`_post`/`_raise_for_status`/`_stream_helper`) resolved through `getattr` and guarded to raise an actionable message rather than `AttributeError` (as `system_logout` does with `api._auth_configs`), then a CLI shell-out if the domain is already CLI-backed. Anything below the first rung leaves the supported surface and is **a human's call, not an agent's**: a PR that adds a *new* private-helper reach-in should be flagged as needing explicit maintainer sign-off, even when it is well built — say so rather than approving it on the strength of the guards. Do flag one that is unguarded, undocumented, or that hits an endpoint absent from the Engine API spec (no compatibility promise, no deprecation cycle — a categorically worse bet than `plugin_push`'s, which uses a spec'd endpoint the CLI itself calls and reaches it through unofficial plumbing). Do **not** re-litigate the reach-ins already blessed above (`plugin_push`, `system_logout`, `stage_build_context`): being present on `main` *is* the sign-off, so a PR that merely touches or refactors one needs no fresh approval — only a genuinely new reach-in does. If a diff both adds and blesses one, that has already been decided; say nothing. And do not treat an audit or routine that *declined* to implement something and documented why as an unfinished job — that write-up is the intended escalation path, and is how `plugin_push` reached a human decision in the first place.
+
+**SDK audit exclusions.** A recurring audit routine looks for uncovered SDK surface and for low-level `client.api.*` calls a high-level method could replace. These were decided on the merits and must not be re-proposed (in review or by the routine): `Plugin.push()`/`APIClient.push_plugin()` — broken upstream, so `plugin_push`'s hand-built endpoint call is the working path, not debt to tidy away; `Container.attach`/`attach_socket`/`resize` — deliberately unwrapped, as an interactive bidirectional stream doesn't fit a request/response tool call (`container_exec` covers scripted exec); `service_rollback`'s `inspect_service`/`update_service` and `system_logout`'s `_auth_configs` — permanently low-level, as the high-level SDK has no `rollback` and no `logout` at all. Anything deliberately not wrapped, or wrapped unobviously, belongs on that list in `CLAUDE.md`.
+
 Docker SDK docs: https://docker-py.readthedocs.io/en/stable/index.html
 Docker SDK low-level API: https://docker-py.readthedocs.io/en/stable/api.html
 Docker SDK GitHub: https://github.com/docker/docker-py
 
 ### Review Notes
 
-There is a dependencies line in pyproject.toml: `"cryptography<49; platform_system == 'Darwin' and platform_machine == 'x86_64'"`
-Changing this line to a later version of cryptography can break installs on Intel (x86_64) macOS, which premerge CI does not cover (the canary workflow checks wheels-only resolution for x86_64 macOS — weekly and on PRs into main — and the pin guard in tests/test_pyproject_pins.py is the merge-time enforcement).
-From version 49, cryptography no longer ships a universal2 macOS wheel; on Intel macOS the resolver typically falls back to a source build that requires a newer Rust toolchain and may fail.
-Changing to a later version of cryptography for other platforms is fine, but this pin should remain for macOS x86_64.
-Do not change this line. If a PR touches this line, please add a strong comment and do not allow the change to be merged without a strong justification and approval from the repo owner.
-
-There used to also be a major-version cap on `mcp` (`"mcp>=1.27.1,<2"`), a hotfix for mcp 2.0.0 (2026-07-28) removing `mcp.server.fastmcp`, which `server.py` imported `FastMCP` from — premerge CI could not see this because it installs `--locked`, so the lockfile's 1.x kept every test green while a *fresh* resolve broke at import (the published 2.2.0 shipped uncapped and `uvx docker-mcp-server` failed at import on a clean machine; 2.2.1 was the hotfix). `server.py` has since been ported to `mcp.server.mcpserver.MCPServer` and the cap removed; `mcp` is now unpinned above `2.0.0`. Rather than a version cap, `tests/test_pyproject_pins.py::test_the_declared_mcp_bound_matches_what_the_code_imports` asserts the module `server.py` imports its server class from is one the installed mcp actually provides — a permanent guard against a future mcp release removing that import path, with no cap to remember to add first. If a PR touches this import or that test, check the change is not silently narrowing that guard.
+There used to be a major-version cap on `mcp` (`"mcp>=1.27.1,<2"`), a hotfix for mcp 2.0.0 (2026-07-28) removing `mcp.server.fastmcp`, which `server.py` imported `FastMCP` from — premerge CI could not see this because it installs `--locked`, so the lockfile's 1.x kept every test green while a *fresh* resolve broke at import (the published 2.2.0 shipped uncapped and `uvx docker-mcp-server` failed at import on a clean machine; 2.2.1 was the hotfix). `server.py` has since been ported to `mcp.server.mcpserver.MCPServer` and the cap removed; `mcp` is now unpinned above `2.0.0`. Rather than a version cap, `tests/test_pyproject_pins.py::test_the_declared_mcp_bound_matches_what_the_code_imports` asserts the module `server.py` imports its server class from is one the installed mcp actually provides — a permanent guard against a future mcp release removing that import path, with no cap to remember to add first. If a PR touches this import or that test, check the change is not silently narrowing that guard. The same principle applies to any new direct dependency whose import surface this project touches — check whether a cap or a guard like this belongs with it.

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.4}/.github/workflows/canary.yaml

@@ -95,7 +95,8 @@ jobs:
     if: github.event_name != 'pull_request'
     name: Install smoke (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 15
+    # 20, not 15: macos-15-intel now source-builds cryptography (brew install + Rust compile).
+    timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
@@ -112,6 +113,18 @@ jobs:
           # live "resolve latest" fetch to raw.githubusercontent.com.
           version: "0.11.21"
 
+      - name: Point the build at Homebrew's OpenSSL 3.x (Intel macOS only)
+        # macos-15-intel ships OpenSSL 1.1.1w (see actions/runner-images); cryptography >=44
+        # dropped OpenSSL 1.1.x support and now requires 3.0+. No x86_64 wheel exists (see
+        # resolve-crossplatform above), so this install source-builds — the Rust toolchain is
+        # already on the runner, but it still needs a compatible OpenSSL to link against.
+        if: matrix.os == 'macos-15-intel'
+        run: |
+          brew install openssl@3
+          prefix="$(brew --prefix openssl@3)"
+          echo "OPENSSL_DIR=$prefix" >> "$GITHUB_ENV"
+          echo "PKG_CONFIG_PATH=$prefix/lib/pkgconfig" >> "$GITHUB_ENV"
+
       - name: Import smoke (full tool-registration path, no daemon needed)
         run: uv run --no-project --python 3.14 --with docker-mcp-server python -c "import docker_mcp"
 

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.4}/.github/workflows/codeql.yaml

@@ -31,12 +31,12 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4
+        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4
+        uses: github/codeql-action/autobuild@5595ccaf912efad79be6eef63a5619ff05969be3 # v4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4
+        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.4}/.github/workflows/premerge.yaml

@@ -20,6 +20,58 @@ concurrency:
 # Jobs
 jobs:
 
+  action-pins:
+    # Ported from L337-org/apt's job of the same name, which is the org's reference
+    # implementation, and kept identical in logic to it and to send-to-influx's copy - three
+    # repos carrying the same guard is only an advantage while they agree, and the
+    # uppercase-SHA defect this arrives with the fix for was found in one copy and had to be
+    # chased into the other two.
+    #
+    # Every ref here was already pinned when this job was added; it exists so that stays true
+    # without anyone having to remember.
+    runs-on: [ubuntu-latest]
+    name: Action pins are immutable
+    steps:
+      - name: Check out source repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Every `uses:` must name a 40-hex commit SHA
+        run: |
+          # A tag or branch ref can be repointed by the action's owner at any time, so
+          # `@v7` means CI runs whatever that owner last pushed to it. That matters most in
+          # publish.yaml, which mints an OIDC token for PyPI Trusted Publishing
+          # (`id-token: write`), pushes to GHCR (`packages: write`) and uploads release
+          # assets (`contents: write`) - a repointed tag would execute inside jobs holding
+          # the strongest credentials this project has, and Trusted Publishing needs no
+          # stored token for an attacker to steal in order to publish as this project.
+          # First-party actions/* are not exempt: the standard makes no exception for them,
+          # and the pin costs nothing to hold, because Dependabot bumps the SHA and rewrites
+          # the trailing "# vX.Y.Z" comment. Local actions (./...) are exempt - they are
+          # this repo's own code at this repo's own commit, so there is no third party to
+          # repoint them.
+          #
+          # Quoting is optional in YAML, so `uses: "owner/action@<sha>"` is exactly as
+          # pinned as the bare form, and hex is case-insensitive, so an uppercase SHA is
+          # equally pinned - GitHub resolves one (verified: both the commits and tarball
+          # API endpoints answer 200 for an upper-cased SHA). All are accepted: a guard
+          # that fails a legitimately pinned action is one someone eventually switches
+          # off wholesale, which costs more than it ever caught. In practice every pin
+          # here is lowercase, because that is what Dependabot writes.
+          #
+          # The trailing "# vX.Y.Z" comment is a convention, not something this guard
+          # enforces - the immutability of the ref is the security property, and the
+          # comment only tells a human which tag the SHA was.
+          bad=$(grep -rnE '^[[:space:]]*(-[[:space:]]+)?uses:' .github/workflows .github/actions 2>/dev/null \
+                | grep -vE "uses:[[:space:]]*[\"']?\./" \
+                | grep -vE "uses:[[:space:]]*[\"']?[^[:space:]\"']+@[0-9a-fA-F]{40}[\"']?([[:space:]]|\$)" \
+                || true)
+          if [ -n "$bad" ]; then
+            echo "::error::Every action must be pinned to a full 40-hex commit SHA." >&2
+            printf '%s\n' "$bad" >&2
+            exit 1
+          fi
+          echo "All action references are pinned to commit SHAs."
+
   fresh-resolve-import:
     # Answers a question `uv sync --locked` (used by every other job here) cannot: would a
     # CLEAN install of what we're about to ship actually import? `uv sync --locked` only ever

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.4}/.github/workflows/publish.yaml

@@ -158,7 +158,7 @@ jobs:
         run: uv build
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
         with:
           # Makes a dispatch re-run after a partial failure idempotent (PyPI files are immutable,
           # so a re-upload of the same files would otherwise 400). This can't mask publishing a
@@ -239,7 +239,7 @@ jobs:
         uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
 
       - name: Log in to GHCR
-        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -247,7 +247,7 @@ jobs:
 
       - name: Log in to Docker Hub
         if: env.DOCKERHUB_USER != '' && env.DOCKERHUB_TOKEN != ''
-        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           username: ${{ secrets.DOCKERHUB_USER }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
@@ -347,6 +347,68 @@ jobs:
             "${{ steps.pack.outputs.file }}.sha256" \
             --clobber
 
+  skill:
+    # Packs the `skills/l337-docker` agent skill as a .tar.gz and attaches it - with its SHA-256 -
+    # to the release. Skills have no official packaging format (unlike .mcpb for MCP servers): a
+    # plain directory is the unit, so the archive is just that directory, rooted at `l337-docker/`
+    # to match the skill's frontmatter `name`. That root is load-bearing for the install UX - it
+    # makes `tar -xzf ... -C ~/.claude/skills` land the skill exactly where Claude Code looks, with
+    # no --strip-components and no rename.
+    #
+    # tar.gz only, deliberately: `tar` is present by default on macOS, Linux and Windows 10 1803+,
+    # whereas `unzip` is routinely absent from minimal Linux images - so a single tarball is the
+    # more universally extractable of the two for a terminal-based audience. Zip would only win for
+    # Windows GUI double-click, which is not the install path.
+    #
+    # A VERSION file is stamped in at pack time because a skill directory carries no version of its
+    # own (the frontmatter has no `version` field), so a downloaded copy would otherwise be
+    # untraceable to the release it came from.
+    #
+    # The archive is byte-reproducible: entries sorted, ownership zeroed, mtimes normalised, and
+    # `gzip -n` to drop the embedded timestamp. Repacking the same commit yields the same checksum,
+    # so the published SHA-256 is verifiable by anyone rebuilding from source.
+    name: Pack and attach the agent skill
+    runs-on: ubuntu-latest
+    needs: [preflight]
+    permissions:
+      contents: write  # upload the archives as release assets
+    steps:
+      - name: Check out the release tag
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.preflight.outputs.tag }}
+
+      - name: Pack the skill
+        id: pack
+        env:
+          VERSION: ${{ needs.preflight.outputs.version }}
+        run: |
+          set -euo pipefail
+          test -f skills/l337-docker/SKILL.md || { echo "::error::skills/l337-docker/SKILL.md is missing"; exit 1; }
+          rm -rf dist _stage && mkdir -p dist _stage
+          cp -R skills/l337-docker _stage/l337-docker
+          printf '%s\n' "$VERSION" > _stage/l337-docker/VERSION
+          find _stage -exec touch -t 198001010000 {} +
+          base="l337-docker-skill-${VERSION}"
+          tar --sort=name --owner=0 --group=0 --numeric-owner --mtime="1980-01-01 00:00:00Z" \
+              -cf - -C _stage l337-docker | gzip -n > "dist/${base}.tar.gz"
+          # Record the bare filename in the .sha256 so `sha256sum -c` works for anyone who
+          # downloads both assets into one directory - including the verify job below.
+          (cd dist && sha256sum "${base}.tar.gz" | tee "${base}.tar.gz.sha256")
+          echo "base=$base" >> "$GITHUB_OUTPUT"
+          echo "Packed \`dist/${base}.tar.gz\`" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Attach to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.preflight.outputs.tag }}
+          BASE: ${{ steps.pack.outputs.base }}
+        run: |
+          set -euo pipefail
+          gh release upload "$RELEASE_TAG" \
+            "dist/${BASE}.tar.gz" "dist/${BASE}.tar.gz.sha256" \
+            --clobber
+
   registry:
     # Publishes server.json to the official MCP Registry (registry.modelcontextprotocol.io). The
     # registry stores only metadata — it points at the artifacts the sibling jobs above publish —
@@ -467,7 +529,10 @@ jobs:
     # silently. Each check retries briefly (5 x 15s) to absorb CDN/index lag.
     name: Verify release convergence
     runs-on: ubuntu-latest
-    needs: [preflight, registry]
+    # `skill` is listed explicitly: it hangs off `preflight` alone and is not in `registry`'s
+    # needs (the registry entry does not reference the skill archives), so without it here verify
+    # could run while the skill job is still packing and report a missing asset.
+    needs: [preflight, registry, skill]
     env:
       TAG: ${{ needs.preflight.outputs.tag }}
       VERSION: ${{ needs.preflight.outputs.version }}
@@ -519,6 +584,34 @@ jobs:
           (cd _verify && sha256sum -c ./*.sha256)
           echo "Release asset OK: $(basename "${mcpb[0]}")"
 
+      - name: Verify the skill archive, its checksum and its layout
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          mkdir -p _skill
+          gh release download "$TAG" --repo "$GITHUB_REPOSITORY" \
+            --pattern 'l337-docker-skill-*' --dir _skill
+          shopt -s nullglob
+          tars=(_skill/*.tar.gz); sums=(_skill/*.sha256)
+          if [ "${#tars[@]}" -ne 1 ] || [ "${#sums[@]}" -ne 1 ]; then
+            echo "::error::expected one .tar.gz and one .sha256 on $TAG, found ${#tars[@]} / ${#sums[@]}"
+            exit 1
+          fi
+          (cd _skill && sha256sum -c ./*.sha256)
+          # Extracting into a skills directory must land the skill at <dir>/l337-docker/SKILL.md
+          # with no renaming or --strip-components, and the stamped VERSION must match this release.
+          mkdir -p _skill/extract
+          tar -xzf "${tars[0]}" -C _skill/extract
+          test -f _skill/extract/l337-docker/SKILL.md \
+            || { echo "::error::archive does not contain l337-docker/SKILL.md"; exit 1; }
+          packed="$(cat _skill/extract/l337-docker/VERSION)"
+          if [ "$packed" != "$VERSION" ]; then
+            echo "::error::skill archive stamps VERSION '$packed' but this release is '$VERSION'"
+            exit 1
+          fi
+          echo "Skill archive OK: $(basename "${tars[0]}") (VERSION $packed)"
+
       - name: Verify the MCP Registry lists the version
         run: |
           set -euo pipefail
@@ -540,7 +633,7 @@ jobs:
     # anything in the needs chain failed. Silent on cancellation.
     name: File failure issue
     runs-on: ubuntu-latest
-    needs: [preflight, pypi, images, dockerhub-description, mcpb, registry, verify]
+    needs: [preflight, pypi, images, dockerhub-description, mcpb, skill, registry, verify]
     if: failure()
     permissions:
       contents: read   # checkout, to use the local composite action

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.4}/.mcpbignore

@@ -9,6 +9,9 @@ server/venv/
 # Tests, tooling, CI, and dev metadata add nothing at runtime.
 tests/
 scripts/
+# The agent skill is a separate artifact (its own release archives) and an *alternative* to this
+# server, not part of it — packing it here would ship ~140 KB of markdown the bundle never reads.
+skills/
 .github/
 .idea/
 .vscode/
@@ -26,6 +29,7 @@ DOCKERHUB.md
 
 # Agent / project docs not needed inside the bundle.
 CLAUDE.md
+MCP_VS_SKILLS.md
 SECURITY.md
 CONTRIBUTING.md
 CODE_OF_CONDUCT.md