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

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

@@ -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.**
@@ -127,7 +127,7 @@ All publishing runs through one workflow on each **published GitHub Release**: `
 
 ### 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
 
@@ -262,16 +262,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.3}/.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.3}/.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.3}/.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 }}

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.3}/CLAUDE.md

@@ -55,20 +55,15 @@ non-required `Check docs mirror` job flags a PR that edits `CLAUDE.md` or
 `.github/copilot-instructions.md` without the other (see the MIRROR RULE above) — it's a prompt to
 double-check, not a merge blocker.
 
-**A dependency cap exists because a fresh resolve can break what `--locked` CI cannot see**,
-enforced by `tests/test_pyproject_pins.py`: `cryptography<49` on Intel macOS (49 dropped the
-universal2 wheel). When adding a direct dependency whose *import surface* we touch, consider
-whether a major-version cap plus a pin guard belongs with it.
-
-An `mcp<2` cap of this kind existed briefly: mcp 2.0.0 removed `mcp.server.fastmcp`, which
-`server.py` imported `FastMCP` from, and an uncapped 2.2.0 shipped dead on arrival at import while
-every CI job stayed green, because CI installs `--locked` against a lockfile pinning mcp 1.x;
-2.2.1 hotfixed the cap. `server.py` has since been ported to `mcp.server.mcpserver.MCPServer` and
-the cap lifted. Rather than re-adding a cap for the next major (there is no known 3.x
-incompatibility to guard against), `tests/test_pyproject_pins.py::
-test_the_declared_mcp_bound_matches_what_the_code_imports` is a living guard: it fails whenever
-the installed mcp stops providing the import path `server.py` actually uses, with no reliance on
-remembering to add a cap first.
+An `mcp<2` cap existed briefly: mcp 2.0.0 removed `mcp.server.fastmcp`, which `server.py` imported
+`FastMCP` from, and an uncapped 2.2.0 shipped dead on arrival at import while every CI job stayed
+green, because CI installs `--locked` against a lockfile pinning mcp 1.x; 2.2.1 hotfixed the cap.
+`server.py` has since been ported to `mcp.server.mcpserver.MCPServer` and the cap lifted. Rather
+than re-adding a cap for the next major (there is no known 3.x incompatibility to guard against),
+`tests/test_pyproject_pins.py::test_the_declared_mcp_bound_matches_what_the_code_imports` is a
+living guard: it fails whenever the installed mcp stops providing the import path `server.py`
+actually uses, with no reliance on remembering to add a cap first. When adding a direct dependency
+whose *import surface* we touch, consider whether a cap or a guard like this belongs with it.
 
 **A required `Check fresh resolve still imports` job** (`premerge.yaml`) closes the blind spot that
 let the 2.2.0 incident through: every job above installs with `uv sync --locked`, so none of them
@@ -127,15 +122,15 @@ A handful of tools have **no domain at all** — `_NO_DOMAIN_TOOLS` (today just
 
 `_hosts.py` lives at the package root (like `_env.py`, so `server.py` can import it without pulling in `docker_mcp.tools`). It parses the var into a pinned `{label: Host}` registry and owns all host resolution — no docker-py/CLI calls, just env + Docker config-file reads:
 
-- **Grammar.** No `=` in the value → bare single-host shorthand (`ssh://ops@prod(ro)`, `auto`, `local`, or 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 + exit non-zero) 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`, or 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 the two 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 + exit non-zero) 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 OUR concepts, resolved to concrete URLs by us and pinned at `load()` (startup)** — so the docker-py SDK and the docker-CLI shell-out provably target the *same* daemon for a given label (auditable), and a mid-session `docker context use` can't silently move a label (restart to re-resolve). `auto` = the active CLI context's endpoint (`DOCKER_CONTEXT` / config.json `currentContext` → its `meta.json` Host) else the `local` socket probe; `local` = the platform-local socket (the `_probe_default_socket` candidate list); `default` = the omitted-`host` fallback = the first registry entry, and is **not** a selectable label. These resolution helpers were relocated *from* `system.py` (then `client.py`) into `_hosts.py`.
 - **`load()` runs in `docker_mcp/__init__.py` before the tools import** (the `@tool()` decorator and resources read `is_multi()`/`labels()` at registration time) and scrubs whole-value `${...}` placeholders first (`_env.scrub_unresolved_env`, so an mcpb blank field resolves to the default host instead of fail-fasting).
 
 **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 the rest (the schema surgery is gated on `_hosts.is_multi()`; the call-time guard on the broader `_host_guard_needed()`):
 - **Schema surgery** (`_apply_host_schema`, display-only like `_slim_schema` — call-time validation runs off `fn_metadata`, gated on `_hosts.is_multi()`): single-host → strip the `host` property entirely (footprint-neutral, schema byte-identical to today); multi-host → constrain `host` to an `enum` of the labels and mark it required for writes.
-- **Call-time guard** (`_enforce_host_guard`, wrapped onto the tool via `_wrap_with_host_guard`, which preserves the signature and sync/async-ness): in multi-host mode writes require an explicit `host`, unknown labels are rejected, and writes to an `(ro)` host are 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 whenever there is something to enforce — `_host_guard_needed()` = multi-host **or a single host flagged `(ro)`**: a lone `(ro)` host carries no `host` param (schema is still stripped, footprint-neutral) but its writes are still refused, so the per-host `(ro)` marker is honored even in single-host mode (distinct from the `DOCKER_MCP_SERVER_READONLY` switch, which drops write tools from the surface entirely). A single *writable* host wires no guard (today's path). **Excluded** (no `host` param at all): `registry`/`hub_*` (HTTPS, no daemon) and `context` (manages the host's CLI contexts).
+- **Call-time guard** (`_enforce_host_guard`, wrapped onto the tool via `_wrap_with_host_guard`, which preserves the signature and sync/async-ness): in multi-host mode writes require an explicit `host`, unknown labels are rejected, writes to an `(ro)` host are refused, and DESTRUCTIVE calls to an `(nd)` host are 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 whenever there is something to enforce — `_host_guard_needed()` = multi-host **or a single host flagged `(ro)` or `(nd)`**: a lone `(ro)`/`(nd)` host carries no `host` param (schema is still stripped, footprint-neutral) but its refusals still apply, so the per-host markers are honored even in single-host mode (distinct from the `DOCKER_MCP_SERVER_READONLY`/`_NO_DESTRUCTIVE` switches, which drop tools from the surface entirely). A host with both markers is refused by the `(ro)` check first — `(ro)` is strictly stronger, so `(nd)` never fires for it. A single *unrestricted* host wires no guard (today's path). **Excluded** (no `host` param at all): `registry`/`hub_*` (HTTPS, no daemon) and `context` (manages the host's CLI contexts).
 
-**Client side** (`system.py`): a lazy pool `_clients` keyed by label; `_get_client(host)` builds per host with tiered TLS (`(tls=)` cert dir → global `DOCKER_CERT_PATH`/`DOCKER_TLS_VERIFY` → plaintext); the legacy single host (unset var) still goes through `_build_default_client`/`from_env` unchanged, and an explicit host that resolves to the platform default (url `None`) is built without a `base_url` so it never re-reads the ignored ambient `DOCKER_HOST`. `system_close(host=None)` closes all/one; **`system_reconnect(host=None)` is rebuild-only** — it cannot retarget to an arbitrary URL (to change a daemon, edit the registry and restart), which closes a trust-expansion hole. `_cli.py:_apply_host_env` injects the resolved `DOCKER_HOST` + per-host TLS into the child env for an explicit host (the ssh:// proxy keys off it). `startup_preflight` pings the *default* host but detects self-id against the *self host* (first local-transport entry, which may differ from a remote default), and `guard_not_self(container, host=)` only fires on the self host.
+**Client side** (`system.py`): a lazy pool `_clients` keyed by label; `_get_client(host)` builds per host with tiered TLS (`(tls=)` cert dir → global `DOCKER_CERT_PATH`/`DOCKER_TLS_VERIFY` → plaintext); the legacy single host (unset var) still goes through `_build_default_client`/`from_env` unchanged, and an explicit host that resolves to the platform default (url `None`) is built without a `base_url` so it never re-reads the ignored ambient `DOCKER_HOST`. **Every `from_env` call passes `use_context=False`** — the reason `docker[ssh]>=7.2.0` is a hard floor rather than a preference. 7.2.0 made `from_env` resolve the active Docker CLI context whenever the environment yields no `base_url`, which is *our* job: `resolve_auto()` reads `DOCKER_CONTEXT` / config.json `currentContext` itself and pins the result at `load()`, so letting docker-py resolve independently would reintroduce the mid-session `docker context use` drift that pinning exists to prevent, and could disagree with the endpoint the CLI shell-out targets for the same label. `tests/test_pyproject_pins.py::test_the_declared_docker_floor_supports_the_kwarg_the_code_passes` fails if the floor stops excluding 7.1.0 or an installed docker-py drops the kwarg. `system_close(host=None)` closes all/one; **`system_reconnect(host=None)` is rebuild-only** — it cannot retarget to an arbitrary URL (to change a daemon, edit the registry and restart), which closes a trust-expansion hole. `_cli.py:_apply_host_env` injects the resolved `DOCKER_HOST` + per-host TLS into the child env for an explicit host (the ssh:// proxy keys off it). `startup_preflight` pings the *default* host but detects self-id against the *self host* (first local-transport entry, which may differ from a remote default), and `guard_not_self(container, host=)` only fires on the self host.
 
 Both `_build_default_client` and `_build_client` run every `ssh://` URL through two docker-py workarounds before handing it to `docker.from_env()`/`docker.DockerClient()`, composed as `_ensure_reachable_family(_ensure_ssh_port(url))`:
 - **`_ensure_ssh_port`**: `docker.utils.parse_host()` hardcodes port 22 into the URL *before* `SSHHTTPAdapter._create_paramiko_client` ever runs, so that adapter's own `~/.ssh/config` `Port` fallback (which only fires while the port is still unset) never triggers — a non-22 `Port` in `~/.ssh/config` would otherwise be silently ignored. Splices in the configured port first, reusing the same `~/.ssh/config` lookup `_ssh_proxy.parse_ssh_url` does for the CLI-backed tools.
@@ -226,7 +221,7 @@ All publishing runs through one workflow on each **published GitHub Release** (n
 
 Resources this server **creates** are stamped with `docker-mcp-server.*` provenance labels (`.managed=true`, `.version`, `.tool`, `.created`) via `docker_mcp/tools/_labels.py`, 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 tears down only the managed footprint. Stamping is **on by default** and additive (a caller-supplied label always wins on a key collision); `DOCKER_MCP_SERVER_NO_LABELS=1` turns it off. The prefix is the bare project name (deliberately not reverse-DNS) and is a single constant in `_labels.py`.
 
-When adding a new create tool that accepts a `labels` dict, route it through `_labels.py:with_provenance(labels, "<tool_name>")` (it accepts the dict/list/None shapes the SDK accepts and returns `None` — feed it through `drop_none` — when stamping is off and the caller passed nothing). The six stamped creators today are `container_run`, `container_create`, `network_create`, `volume_create`, `service_create` (service-level `labels` only, not `container_labels`), `config_create`, `secret_create`. **Image builds are intentionally NOT stamped** — a build label changes the resulting image digest. Compose/stack containers (created via CLI shell-out) are also unstamped. New `managed_only`-style label filters go through `_labels.py:managed_filter`.
+When adding a new create tool that accepts a `labels` dict, route it through `_labels.py:with_provenance(labels, "<tool_name>")` (it accepts the dict/list/None shapes the SDK accepts and returns `None` — feed it through `drop_none` — when stamping is off and the caller passed nothing). The seven stamped creators today are `container_run`, `container_create`, `network_create`, `volume_create`, `service_create` (service-level `labels` only, not `container_labels`), `config_create`, `secret_create`. **Image builds are intentionally NOT stamped** — a build label changes the resulting image digest. Compose/stack containers (created via CLI shell-out) are also unstamped, as is `plugin_create` — the Engine's plugin-create call accepts no labels field, so there is nothing to stamp. 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. New `managed_only`-style label filters go through `_labels.py:managed_filter`.
 
 ## CLI shell-out policy
 
@@ -415,6 +410,42 @@ Do not assume any method exists because it sounds plausible. If you cannot confi
 
 When the high-level SDK has no method for an operation (e.g. swarm node removal, service rollback), drop to the low-level **`APIClient` via `_get_client().api`** — its methods (`remove_node`, `update_service`, `inspect_service`, …) are documented at https://docker-py.readthedocs.io/en/stable/api.html and must be verified the same way. Prefer the high-level object API when it exists; reach for `client.api` only for the gaps.
 
+**Verify against the source, not just the rendered docs, and treat "the method exists" as separate from "the method works."** The rendered docs show a method's docstring, not the URL it builds, so a method can be documented, importable, and still non-functional. `plugin_push` is the standing example: docker-py's `Plugin.push()` / `APIClient.push_plugin()` both POST to `/plugins/{name}/pull`, a route the Engine does not define (push is `POST /plugins/{name}/push`), so they 404 against every daemon — a copy-paste from the pull method present since 2017 and still in `main`, surviving because upstream has no test covering it. Where a *documented* method is provably broken, the fallback ladder is: (1) another public SDK path, (2) the correct endpoint through docker-py's private request helpers (`_url`/`_post`/`_raise_for_status`/`_stream_helper`), resolved via `getattr` and guarded so a missing helper raises an actionable message rather than an `AttributeError` — the same treatment as `system_logout`'s `api._auth_configs` reach-in and `stage_build_context`'s use of docker-py's `tar`/`exclude_paths`, (3) a CLI shell-out, if the domain is already CLI-backed. Each such reach-in must name the bug and the escape hatch in the tool's docstring, so it can be removed when upstream fixes it.
+
+**Rungs (2) and (3) are not an agent's call to make.** Rung (1) is ordinary work; anything below it leaves the supported surface, so an agent — a routine, or anyone implementing from an audit issue — must **stop, write up what it found and why the public path fails, and escalate for a human decision** rather than implementing it. This is not a formality: it is how `plugin_push` was actually settled. The draft-PR routine hit the broken method, declined to reach past the public SDK, shipped the rest, and *documented the omission*; that write-up is what prompted the investigation that found the real endpoint and the human judgement to take it. A routine that had "helpfully" hand-rolled the call instead would have made a trust decision nobody asked it to make, and one that silently dropped the candidate would have buried it. **Document and escalate is the correct behavior, not a failure to finish the job** — a parked candidate with a clear rationale is a better outcome than an autonomous workaround. Sign-off is needed once, when the reach-in is introduced: the ones listed here are already blessed, so touching or refactoring them later needs no fresh approval.
+
+**Confirm the real route from the Engine API spec (`moby/moby`'s `api/swagger.yaml`) before writing a hand-built path, and note which kind of bet it is** — the two are not equivalent risks:
+
+- **A published endpoint reached through private client plumbing** (what `plugin_push` does): `POST /plugins/{name}/push` is in the Engine API spec and is what `docker plugin push` itself calls, so the *contract* is stable and unlikely to move; only docker-py's `_url`/`_post` internals are unofficial, which is what the `getattr` guard covers. This is the acceptable shape.
+- **An endpoint that is not in the spec at all** is a different proposition — no compatibility promise, no deprecation cycle, nothing to pin the behavior. Do not use one, even guarded, without explicit human sign-off recorded in the PR; never on an agent's own initiative.
+
+### SDK audit exclusions (deliberate non-candidates)
+
+A recurring cloud routine audits the docker-py surface for coverage gaps and for low-level
+`client.api.*` calls a high-level method could replace. The decisions below were made once, on the
+merits, and are **not** to be re-proposed — a periodic audit has no memory of last time, so without
+this list it re-files the same rejected candidates forever. Removing an entry is a real decision;
+say why. **Anything deliberately not wrapped, or wrapped in an unobvious way, belongs here.**
+
+- **`Plugin.push()` / `APIClient.push_plugin()`** — never migrate `plugin_push` onto these. They are
+  broken upstream (wrong URL, see above); our hand-built endpoint call is the working path, not
+  technical debt to be tidied away. Revisit only if upstream fixes the URL, at which point the
+  reach-in should be replaced by the public method.
+- **`Container.attach` / `attach_socket` / `resize`** — real methods, deliberately unwrapped: they
+  open an interactive bidirectional stream/TTY, which does not fit a request/response tool call.
+  `container_exec` covers scripted one-shot execution.
+- **`service_rollback`'s `api.inspect_service` + `api.update_service`** — stays low-level
+  permanently. The high-level `Service`/`ServiceCollection` expose no `rollback`.
+- **`system_logout`'s `api._auth_configs`** — stays low-level permanently. There is no `logout`
+  anywhere in the SDK and no server-side session to end, so there is nothing to migrate to.
+
+The audit must also **check the latest published docker-py, not the pinned one**: `uv.lock` is
+routinely behind what `pyproject.toml`'s floor lets a fresh `uvx`/`pip install` resolve, so auditing
+the installed tree alone misses whatever published users are already running. And it should flag
+**deprecated** surface we still depend on, not only missing coverage — e.g. `image_prune_builds`'s
+`keep_storage`, which the Engine renamed `reserved-space` at API v1.48 — so a migration happens on
+our schedule rather than when removal breaks us.
+
 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

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.3}/DOCKERHUB.md

@@ -2,8 +2,12 @@
 
 More than just a fully featured [MCP](https://modelcontextprotocol.io) server that lets AI agents manage Docker — containers, images, networks, volumes, swarm services, secrets, configs, nodes, plugins, etc., it helps you create workflows to easily manage your Docker environments.
 
+It gives you much more control and flexibility than calling the Docker CLI directly: each operation is exposed as its own typed tool, marked read-only or not, with destructive actions separately flagged. This means a client can auto-approve reads while always confirming anything destructive, and the whole server can also be switched into a read-only or no-destructive mode as a blanket safeguard. Output is bounded rather than left to grow unboundedly — capped with a `truncated` flag instead of silently overflowing the agent's context.
+
 It can manage multiple Docker daemons, e.g. both your local dev environment and also a remote production environment over TCP, TLS or SSH in a single session. It can also be configured to mark some daemons as read-only, so that you can monitor them without the risk of making accidental changes. It also exposes things like logs and stats as resources so that you can easily monitor and triage your environments with a few prompts.
 
+Documentation is built for the agent, not just the person configuring it: an MCP resource exposes the Docker SDK reference in-session (with a tool-callable fallback for clients that can't read resources), and a live tool-catalog resource reports exactly what's registered under the current configuration. Each tool's own description names its nearest siblings and when to prefer each, states preconditions and side effects in plain language, and is honest about when it can still fail — so an agent can pick the right tool on the first try among 150+ options, not guess.
+
 The server runs entirely on your machine and sends no telemetry. You are entirely in control — see the [Privacy Policy](https://github.com/L337-org/docker-mcp#privacy-policy).
 
 This image is the container distribution of the project. **Full documentation, configuration, and source are on GitHub: <https://github.com/L337-org/docker-mcp>.**

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-mcp-server
-Version: 2.2.2
+Version: 2.2.3
 Summary: MCP server for managing Docker resources via the Docker SDK for Python
 Project-URL: Homepage, https://github.com/L337-org/docker-mcp
 Project-URL: Repository, https://github.com/L337-org/docker-mcp
@@ -19,8 +19,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.14
-Requires-Dist: cryptography<49; platform_system == 'Darwin' and platform_machine == 'x86_64'
-Requires-Dist: docker[ssh]>=7.1.0
+Requires-Dist: docker[ssh]>=7.2.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: mcp>=2.0.0
 Requires-Dist: requests>=2.26.0
@@ -36,12 +35,16 @@ Description-Content-Type: text/markdown
 
 More than just a fully featured [MCP](https://modelcontextprotocol.io) server that lets AI agents manage Docker — containers, images, networks, volumes, swarm services, secrets, configs, nodes, plugins, etc., it helps you create workflows to easily manage your Docker environments.
 
+It gives you much more control and flexibility than calling the Docker CLI directly: each operation is exposed as its own typed tool, marked read-only or not, with destructive actions separately flagged. This means a client can auto-approve reads while always confirming anything destructive, and the whole server can also be switched into a read-only or no-destructive mode as a blanket safeguard. Output is bounded rather than left to grow unboundedly — capped with a `truncated` flag instead of silently overflowing the agent's context.
+
 For simple cases, you can just install and go with no configuration required - once loaded it will discover your local Docker socket and expose the full command surface to your AI agent. For more advanced users it can [manage multiple Docker daemons](#managing-several-daemons), e.g. both your local dev environment and also a remote production environment [over TCP, TLS or SSH](#talking-to-a-remote-daemon) in a single session. It can also be configured to mark some daemons as read-only, so you can monitor them without the risk of making accidental changes.
 
 It can even be run on a machine [without Docker installed](#no-local-docker) and manage remote daemons over SSH, TLS or TCP (some features require SSH). The AI itself does not require shell or SSH access.
 
 The MCP server also exposes things like logs and stats as resources so that you can monitor and triage, enabling you to [answer questions](#example-prompts) like 'why did my container crash?', 'what is the state of my swarm?', 'am I suffering memory pressure?', 'what is the disk usage of my volumes?', 'what differences are there between my test and production systems?', and more...
 
+Documentation is built for the agent, not just the person configuring it: an MCP resource exposes the Docker SDK reference in-session (with a tool-callable fallback for clients that can't read resources), and a live tool-catalog resource reports exactly what's registered under the current configuration. Each tool's own description names its nearest siblings and when to prefer each, states preconditions and side effects in plain language, and is honest about when it can still fail — so an agent can pick the right tool on the first try among 150+ options, not guess.
+
 docker-mcp-server is optimized to work efficiently with the new generation of MCP clients that support lazy tool loading. For clients that still eagerly load all tools, the server can optionally be configured to exclude tools from a subset of domains (e.g. exclude 'swarm' and 'scout' tools) to reduce the tool list size. It's also possible to put the MCP server into 'read-only' or 'no-destructive' modes that prevent any tools with write or destructive capabilities from being registered, which again reduces the footprint.
 
 The server runs entirely on your machine, either [natively](#using-the-server), as an [mcpb bundle](#install-as-a-desktop-extension-mcpb), or [containerized](#run-as-a-container), and sends no telemetry. You are entirely in control — see the [Privacy Policy](#privacy-policy).
@@ -53,6 +56,13 @@ Note: If you're using the containerized MCP server or MCPB bundle, the Python an
 - A running Docker daemon reachable from the host that runs the server (the standard `DOCKER_HOST` / unix socket conventions apply)
 - [Python ≥ 3.14](https://www.python.org/downloads/)
 - [uv](https://docs.astral.sh/uv/) for dependency management
+- **Intel (x86_64) macOS only:** installing natively (via `uvx`/`pip`, or the `.mcpb` bundle, both of
+  which resolve dependencies locally) requires [Rust](https://rustup.rs/) and OpenSSL 3.x, because
+  `cryptography` — a transitive dependency, via `mcp` → `pyjwt[crypto]` — has shipped no x86_64
+  macOS wheel since version 49.0.0 and must be built from source there. If you'd rather not install
+  a build toolchain, use the [container image](#run-as-a-container) instead — it runs the same
+  prebuilt Linux binary regardless of your Mac's CPU architecture, so this doesn't apply to it. See
+  [Security considerations](#security-considerations) for more.
 
 ## Using the server
 
@@ -245,6 +255,7 @@ Everything above targets one daemon. To manage **several in a single session**
 
 - **`endpoint`** is `auto` (your default context/socket, as [above](#talking-to-a-remote-daemon)), `local` (the platform-local socket, ignoring contexts), or a `unix://` / `tcp://` / `ssh://` / `npipe://` URL. `ssh://` is the recommended remote transport (per-host auth via your SSH keys, no TLS cert plumbing). A `tcp://` daemon over TLS takes a `(tls=<dir>)` marker pointing at a cert directory, e.g. `prod=tcp://prod:2376(tls=/etc/docker/prod)`. That directory must hold **`ca.pem`** (the daemon is always verified against it — so a self-signed daemon works, you just pin its cert here); add **`cert.pem`** and **`key.pem`** only if the daemon requires a client certificate (mutual TLS). There is no unverified-TLS mode — a TLS connection always authenticates the daemon, so encryption never comes without verification.
 - **`(ro)`** after an endpoint marks that host **read-only**: mutating and destructive tools refuse to act on it. This is a per-host guard enforced at call time, independent of the server-wide `DOCKER_MCP_SERVER_READONLY` switch — mark production `(ro)` and the agent can inspect it all day but can't change it, while local stays read-write.
+- **`(nd)`** marks a host **non-destructive**: only destructive tools (removals, prunes, kills) refuse to act on it — reads and ordinary mutations (start/stop/create) still work. This mirrors the server-wide `DOCKER_MCP_SERVER_NO_DESTRUCTIVE` switch, per host. `(ro)` already implies it, so `(ro)(nd)` combines without error but is redundant.
 - **Single daemon, simpler form.** A bare value with no `name=` is shorthand for one host — `DOCKER_MCP_SERVER_HOSTS=ssh://ops@prod` (or `auto`, or blank). So this one field also covers the single-remote case. `DOCKER_HOST` keeps working when `DOCKER_MCP_SERVER_HOSTS` is unset, but **`DOCKER_MCP_SERVER_HOSTS` takes over when set** (`DOCKER_HOST` is then ignored, with a one-time notice to stderr).
 
 **How the agent drives it.** With two or more hosts, every daemon-targeting tool gains an optional **`host`** argument constrained to your configured names: read-only tools default to the first host when you omit it, while mutating and destructive tools **require** an explicit `host` (so the agent can't change the wrong daemon by accident). `host_list` (and the `docker-mcp://hosts` resource) report the configured hosts and which is the default; the container/service/node observability resources become host-aware — the **default** host's index is `docker:///containers` (note the empty authority) and a **named** host's is `docker://{host}/containers` (likewise `docker-logs:///{id}` vs `docker-logs://{host}/{id}`, and the same pattern for `docker://services`/`service-logs://`/`service-tasks://` and `docker://nodes`); the single-host bare forms (`docker://containers`, `docker://services`, `docker://nodes`, …) are not registered once several hosts are configured. The `survey_hosts` prompt sweeps every host read-only. The `auto`/`local` endpoints are resolved to concrete URLs and **pinned at startup**, so the SDK and CLI always agree on which daemon a name means — restart to re-resolve after changing a Docker context.
@@ -254,7 +265,8 @@ Everything above targets one daemon. To manage **several in a single session**
 Once loaded, the agent gets MCP tools grouped by Docker domain. A few examples:
 
 - **Containers** — `container_run`, `container_list` (`managed_only=True` to list only what this server created — see [Provenance labels](#provenance-labels)), `container_exec`, `container_logs`, `container_stop`, `container_commit`, `container_wait` (block until exit, `until="healthy"` to poll a healthcheck, or `until="log-match"` to poll for a log line containing `pattern`), `container_export` / `container_archive_get_to_file` / `container_archive_put` (stream tar archives to/from a host path)
-- **Images** — `image_build`, `image_pull`, `image_push`, `image_tag`, `image_prune`, `image_save` / `image_load` (stream image tarballs to/from a host path via `dest_path` / `from_file`)
+- **Images** — `image_build`, `image_pull`, `image_push`, `image_tag`, `image_prune`, `image_prune_builds` (clear the daemon's build cache — a separate resource from dangling images), `image_save` / `image_load` (stream image tarballs to/from a host path via `dest_path` / `from_file`)
+- **Plugins** — `plugin_install` (pull from a registry), `plugin_create` (build one from a local `config.json` + `rootfs`), `plugin_push` (publish it back), `plugin_enable` / `plugin_disable`, `plugin_configure`, `plugin_upgrade`, `plugin_list` / `plugin_inspect`, `plugin_remove` *(managed engine plugins — volume/network/logging drivers — not the CLI plugins that extend the `docker` command itself)*
 - **Networks / Volumes** — `network_create`, `network_connect`, `volume_create`, `volume_prune`
 - **Swarm** — `swarm_init`, `swarm_join_tokens` (close the init → join loop), `swarm_update` (rotate join tokens / unlock key), `service_create`, `service_scale`, `service_rollback` (re-apply the previous service spec), `service_wait` (block until tasks converge, or a rolling update completes), `node_list`, `node_wait` (block until a node reaches a target state — e.g. `ready` after joining), `node_remove`, `secret_create`, `config_create`
 - **System** — `system_ping`, `system_info`, `system_version`, `system_df`, `system_events`, `host_list` (the configured daemons and which is the default — see [Managing several daemons](#managing-several-daemons)), `system_login` / `system_logout` (cache or clear registry credentials), `system_reconnect` (rebuild a host's SDK client to recover a wedged connection)
@@ -419,6 +431,8 @@ Connecting this server to an AI agent grants it the same level of access as a lo
 - **CLI shell-out attack surface.** Compose, Stack, Buildx, Scout, and Context tools spawn `docker` subprocesses on the host running this MCP server. Every invocation passes arguments as a list (no shell, no metacharacter interpretation), resolves the binary via `shutil.which`, and runs against a scrubbed environment (DOCKER_HOST and related vars only). Positional values (image refs, service / context / builder names, build contexts, bake targets) are additionally rejected if they start with `-`, so an argument can't be smuggled in as a CLI flag (e.g. a service named `--output=…`); the one deliberate exception is the trailing command in `compose_exec` / `compose_run`, which is meant to be an arbitrary argv. Filesystem paths supplied to `compose_*` (project_dir, files) are read by the docker CLI on the server host — passing an unfamiliar path can expose any compose file the server's user can read. **With no local docker CLI and an `ssh://` target** those subprocesses run on the remote host instead ([above](#talking-to-a-remote-daemon)), which shifts two things: the command executes as the remote SSH user with *its* registry credentials, and the files a command reads are copied to that host's temp directory first — so a `buildx_build` `--secret src=` file, or anything else in a staged directory, exists briefly on the remote disk (mode `0700`, removed when the call returns; only a dropped connection can leave it behind). Point staging-backed tools at directories you would be content to copy.
 - **The daemon set is fixed at startup; pick it deliberately.** When `DOCKER_HOST` / `DOCKER_MCP_SERVER_HOSTS` are unset, the server's *initial* SDK connection follows your active Docker context (`DOCKER_CONTEXT` / `currentContext`) — the same daemon your `docker` CLI targets — so if that context points at a remote or production daemon, the agent connects there too. Set `DOCKER_MCP_SERVER_HOSTS` (or `DOCKER_HOST`, or select a scoped context) before starting the server to pin the target(s) deliberately; with `DOCKER_MCP_SERVER_HOSTS` the `auto`/`local` endpoints are resolved and **pinned at startup**, so they can't drift if a context changes later. After startup, `context_use` only changes the CLI default for subsequent CLI-backed tools; SDK-backed tools keep using the daemon their pooled client connected to. **There is no runtime way to introduce or retarget a daemon at an arbitrary endpoint** — `system_reconnect` only *rebuilds* an already-configured host's client (to recover a wedged connection), it can't point it elsewhere; to add or change a daemon, edit `DOCKER_MCP_SERVER_HOSTS` and restart. This deliberately closes a trust-expansion vector (an agent can't move the root-equivalent boundary to an unvetted endpoint mid-session). `context_create(skip_tls_verify=True)` disables TLS verification for a context; use only against trusted local daemons.
 - **Per-host read-only is an accident guard, not a security boundary.** A host marked `(ro)` in `DOCKER_MCP_SERVER_HOSTS` makes mutating/destructive tools refuse to act on it at call time (and, with several hosts, writes require naming the target host explicitly — so the agent can't change the wrong daemon by omission). Like `guard_not_self`, this is in-process convenience: it constrains the agent through this server's tools, but the daemon itself is still the trust boundary, so for a host the agent must never modify, prefer pointing it at a genuinely read-only or scoped daemon over relying on the marker alone.
+- **Per-host non-destructive is the same accident guard, scoped narrower.** A host marked `(nd)` refuses only destructive tool calls (kills, removals, prunes) while reads and ordinary mutations still go through. Like `(ro)`, this is in-process convenience enforced by this server's guard, not a daemon-level boundary.
+- **`cryptography` (a transitive dependency, via `mcp` → `pyjwt[crypto]`) has shipped no x86_64/universal2 macOS wheel since 49.0.0 — confirmed permanent, not transient — so a native install there (`uvx`, `pip`, or the `.mcpb` bundle) resolves to a current version and builds it from source, needing [Rust](https://rustup.rs/) and OpenSSL 3.x.** This project briefly tried to avoid that build step with its own `cryptography<49` cap scoped to Intel macOS — that cap turned out to hold back *every* platform, not just the one it named (a platform-scoped upper bound alone doesn't make `uv lock` fork the resolution), so it silently left everyone on a version within a later high-severity CVE's range (a PKCS#7 EnvelopedData decryption Bleichenbacher oracle). The cap was removed rather than replaced: this project doesn't decrypt PKCS#7 envelopes itself, but a dependency carrying a known-exploitable flaw is not something to ship knowingly just to keep one platform wheel-only. If you'd rather not install a build toolchain, use the [container image](#run-as-a-container) instead (built centrally on Linux, so it never hits this).
 
 ## Packages and listings
 

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.3}/README.md

@@ -8,12 +8,16 @@
 
 More than just a fully featured [MCP](https://modelcontextprotocol.io) server that lets AI agents manage Docker — containers, images, networks, volumes, swarm services, secrets, configs, nodes, plugins, etc., it helps you create workflows to easily manage your Docker environments.
 
+It gives you much more control and flexibility than calling the Docker CLI directly: each operation is exposed as its own typed tool, marked read-only or not, with destructive actions separately flagged. This means a client can auto-approve reads while always confirming anything destructive, and the whole server can also be switched into a read-only or no-destructive mode as a blanket safeguard. Output is bounded rather than left to grow unboundedly — capped with a `truncated` flag instead of silently overflowing the agent's context.
+
 For simple cases, you can just install and go with no configuration required - once loaded it will discover your local Docker socket and expose the full command surface to your AI agent. For more advanced users it can [manage multiple Docker daemons](#managing-several-daemons), e.g. both your local dev environment and also a remote production environment [over TCP, TLS or SSH](#talking-to-a-remote-daemon) in a single session. It can also be configured to mark some daemons as read-only, so you can monitor them without the risk of making accidental changes.
 
 It can even be run on a machine [without Docker installed](#no-local-docker) and manage remote daemons over SSH, TLS or TCP (some features require SSH). The AI itself does not require shell or SSH access.
 
 The MCP server also exposes things like logs and stats as resources so that you can monitor and triage, enabling you to [answer questions](#example-prompts) like 'why did my container crash?', 'what is the state of my swarm?', 'am I suffering memory pressure?', 'what is the disk usage of my volumes?', 'what differences are there between my test and production systems?', and more...
 
+Documentation is built for the agent, not just the person configuring it: an MCP resource exposes the Docker SDK reference in-session (with a tool-callable fallback for clients that can't read resources), and a live tool-catalog resource reports exactly what's registered under the current configuration. Each tool's own description names its nearest siblings and when to prefer each, states preconditions and side effects in plain language, and is honest about when it can still fail — so an agent can pick the right tool on the first try among 150+ options, not guess.
+
 docker-mcp-server is optimized to work efficiently with the new generation of MCP clients that support lazy tool loading. For clients that still eagerly load all tools, the server can optionally be configured to exclude tools from a subset of domains (e.g. exclude 'swarm' and 'scout' tools) to reduce the tool list size. It's also possible to put the MCP server into 'read-only' or 'no-destructive' modes that prevent any tools with write or destructive capabilities from being registered, which again reduces the footprint.
 
 The server runs entirely on your machine, either [natively](#using-the-server), as an [mcpb bundle](#install-as-a-desktop-extension-mcpb), or [containerized](#run-as-a-container), and sends no telemetry. You are entirely in control — see the [Privacy Policy](#privacy-policy).
@@ -25,6 +29,13 @@ Note: If you're using the containerized MCP server or MCPB bundle, the Python an
 - A running Docker daemon reachable from the host that runs the server (the standard `DOCKER_HOST` / unix socket conventions apply)
 - [Python ≥ 3.14](https://www.python.org/downloads/)
 - [uv](https://docs.astral.sh/uv/) for dependency management
+- **Intel (x86_64) macOS only:** installing natively (via `uvx`/`pip`, or the `.mcpb` bundle, both of
+  which resolve dependencies locally) requires [Rust](https://rustup.rs/) and OpenSSL 3.x, because
+  `cryptography` — a transitive dependency, via `mcp` → `pyjwt[crypto]` — has shipped no x86_64
+  macOS wheel since version 49.0.0 and must be built from source there. If you'd rather not install
+  a build toolchain, use the [container image](#run-as-a-container) instead — it runs the same
+  prebuilt Linux binary regardless of your Mac's CPU architecture, so this doesn't apply to it. See
+  [Security considerations](#security-considerations) for more.
 
 ## Using the server
 
@@ -217,6 +228,7 @@ Everything above targets one daemon. To manage **several in a single session**
 
 - **`endpoint`** is `auto` (your default context/socket, as [above](#talking-to-a-remote-daemon)), `local` (the platform-local socket, ignoring contexts), or a `unix://` / `tcp://` / `ssh://` / `npipe://` URL. `ssh://` is the recommended remote transport (per-host auth via your SSH keys, no TLS cert plumbing). A `tcp://` daemon over TLS takes a `(tls=<dir>)` marker pointing at a cert directory, e.g. `prod=tcp://prod:2376(tls=/etc/docker/prod)`. That directory must hold **`ca.pem`** (the daemon is always verified against it — so a self-signed daemon works, you just pin its cert here); add **`cert.pem`** and **`key.pem`** only if the daemon requires a client certificate (mutual TLS). There is no unverified-TLS mode — a TLS connection always authenticates the daemon, so encryption never comes without verification.
 - **`(ro)`** after an endpoint marks that host **read-only**: mutating and destructive tools refuse to act on it. This is a per-host guard enforced at call time, independent of the server-wide `DOCKER_MCP_SERVER_READONLY` switch — mark production `(ro)` and the agent can inspect it all day but can't change it, while local stays read-write.
+- **`(nd)`** marks a host **non-destructive**: only destructive tools (removals, prunes, kills) refuse to act on it — reads and ordinary mutations (start/stop/create) still work. This mirrors the server-wide `DOCKER_MCP_SERVER_NO_DESTRUCTIVE` switch, per host. `(ro)` already implies it, so `(ro)(nd)` combines without error but is redundant.
 - **Single daemon, simpler form.** A bare value with no `name=` is shorthand for one host — `DOCKER_MCP_SERVER_HOSTS=ssh://ops@prod` (or `auto`, or blank). So this one field also covers the single-remote case. `DOCKER_HOST` keeps working when `DOCKER_MCP_SERVER_HOSTS` is unset, but **`DOCKER_MCP_SERVER_HOSTS` takes over when set** (`DOCKER_HOST` is then ignored, with a one-time notice to stderr).
 
 **How the agent drives it.** With two or more hosts, every daemon-targeting tool gains an optional **`host`** argument constrained to your configured names: read-only tools default to the first host when you omit it, while mutating and destructive tools **require** an explicit `host` (so the agent can't change the wrong daemon by accident). `host_list` (and the `docker-mcp://hosts` resource) report the configured hosts and which is the default; the container/service/node observability resources become host-aware — the **default** host's index is `docker:///containers` (note the empty authority) and a **named** host's is `docker://{host}/containers` (likewise `docker-logs:///{id}` vs `docker-logs://{host}/{id}`, and the same pattern for `docker://services`/`service-logs://`/`service-tasks://` and `docker://nodes`); the single-host bare forms (`docker://containers`, `docker://services`, `docker://nodes`, …) are not registered once several hosts are configured. The `survey_hosts` prompt sweeps every host read-only. The `auto`/`local` endpoints are resolved to concrete URLs and **pinned at startup**, so the SDK and CLI always agree on which daemon a name means — restart to re-resolve after changing a Docker context.
@@ -226,7 +238,8 @@ Everything above targets one daemon. To manage **several in a single session**
 Once loaded, the agent gets MCP tools grouped by Docker domain. A few examples:
 
 - **Containers** — `container_run`, `container_list` (`managed_only=True` to list only what this server created — see [Provenance labels](#provenance-labels)), `container_exec`, `container_logs`, `container_stop`, `container_commit`, `container_wait` (block until exit, `until="healthy"` to poll a healthcheck, or `until="log-match"` to poll for a log line containing `pattern`), `container_export` / `container_archive_get_to_file` / `container_archive_put` (stream tar archives to/from a host path)
-- **Images** — `image_build`, `image_pull`, `image_push`, `image_tag`, `image_prune`, `image_save` / `image_load` (stream image tarballs to/from a host path via `dest_path` / `from_file`)
+- **Images** — `image_build`, `image_pull`, `image_push`, `image_tag`, `image_prune`, `image_prune_builds` (clear the daemon's build cache — a separate resource from dangling images), `image_save` / `image_load` (stream image tarballs to/from a host path via `dest_path` / `from_file`)
+- **Plugins** — `plugin_install` (pull from a registry), `plugin_create` (build one from a local `config.json` + `rootfs`), `plugin_push` (publish it back), `plugin_enable` / `plugin_disable`, `plugin_configure`, `plugin_upgrade`, `plugin_list` / `plugin_inspect`, `plugin_remove` *(managed engine plugins — volume/network/logging drivers — not the CLI plugins that extend the `docker` command itself)*
 - **Networks / Volumes** — `network_create`, `network_connect`, `volume_create`, `volume_prune`
 - **Swarm** — `swarm_init`, `swarm_join_tokens` (close the init → join loop), `swarm_update` (rotate join tokens / unlock key), `service_create`, `service_scale`, `service_rollback` (re-apply the previous service spec), `service_wait` (block until tasks converge, or a rolling update completes), `node_list`, `node_wait` (block until a node reaches a target state — e.g. `ready` after joining), `node_remove`, `secret_create`, `config_create`
 - **System** — `system_ping`, `system_info`, `system_version`, `system_df`, `system_events`, `host_list` (the configured daemons and which is the default — see [Managing several daemons](#managing-several-daemons)), `system_login` / `system_logout` (cache or clear registry credentials), `system_reconnect` (rebuild a host's SDK client to recover a wedged connection)
@@ -391,6 +404,8 @@ Connecting this server to an AI agent grants it the same level of access as a lo
 - **CLI shell-out attack surface.** Compose, Stack, Buildx, Scout, and Context tools spawn `docker` subprocesses on the host running this MCP server. Every invocation passes arguments as a list (no shell, no metacharacter interpretation), resolves the binary via `shutil.which`, and runs against a scrubbed environment (DOCKER_HOST and related vars only). Positional values (image refs, service / context / builder names, build contexts, bake targets) are additionally rejected if they start with `-`, so an argument can't be smuggled in as a CLI flag (e.g. a service named `--output=…`); the one deliberate exception is the trailing command in `compose_exec` / `compose_run`, which is meant to be an arbitrary argv. Filesystem paths supplied to `compose_*` (project_dir, files) are read by the docker CLI on the server host — passing an unfamiliar path can expose any compose file the server's user can read. **With no local docker CLI and an `ssh://` target** those subprocesses run on the remote host instead ([above](#talking-to-a-remote-daemon)), which shifts two things: the command executes as the remote SSH user with *its* registry credentials, and the files a command reads are copied to that host's temp directory first — so a `buildx_build` `--secret src=` file, or anything else in a staged directory, exists briefly on the remote disk (mode `0700`, removed when the call returns; only a dropped connection can leave it behind). Point staging-backed tools at directories you would be content to copy.
 - **The daemon set is fixed at startup; pick it deliberately.** When `DOCKER_HOST` / `DOCKER_MCP_SERVER_HOSTS` are unset, the server's *initial* SDK connection follows your active Docker context (`DOCKER_CONTEXT` / `currentContext`) — the same daemon your `docker` CLI targets — so if that context points at a remote or production daemon, the agent connects there too. Set `DOCKER_MCP_SERVER_HOSTS` (or `DOCKER_HOST`, or select a scoped context) before starting the server to pin the target(s) deliberately; with `DOCKER_MCP_SERVER_HOSTS` the `auto`/`local` endpoints are resolved and **pinned at startup**, so they can't drift if a context changes later. After startup, `context_use` only changes the CLI default for subsequent CLI-backed tools; SDK-backed tools keep using the daemon their pooled client connected to. **There is no runtime way to introduce or retarget a daemon at an arbitrary endpoint** — `system_reconnect` only *rebuilds* an already-configured host's client (to recover a wedged connection), it can't point it elsewhere; to add or change a daemon, edit `DOCKER_MCP_SERVER_HOSTS` and restart. This deliberately closes a trust-expansion vector (an agent can't move the root-equivalent boundary to an unvetted endpoint mid-session). `context_create(skip_tls_verify=True)` disables TLS verification for a context; use only against trusted local daemons.
 - **Per-host read-only is an accident guard, not a security boundary.** A host marked `(ro)` in `DOCKER_MCP_SERVER_HOSTS` makes mutating/destructive tools refuse to act on it at call time (and, with several hosts, writes require naming the target host explicitly — so the agent can't change the wrong daemon by omission). Like `guard_not_self`, this is in-process convenience: it constrains the agent through this server's tools, but the daemon itself is still the trust boundary, so for a host the agent must never modify, prefer pointing it at a genuinely read-only or scoped daemon over relying on the marker alone.
+- **Per-host non-destructive is the same accident guard, scoped narrower.** A host marked `(nd)` refuses only destructive tool calls (kills, removals, prunes) while reads and ordinary mutations still go through. Like `(ro)`, this is in-process convenience enforced by this server's guard, not a daemon-level boundary.
+- **`cryptography` (a transitive dependency, via `mcp` → `pyjwt[crypto]`) has shipped no x86_64/universal2 macOS wheel since 49.0.0 — confirmed permanent, not transient — so a native install there (`uvx`, `pip`, or the `.mcpb` bundle) resolves to a current version and builds it from source, needing [Rust](https://rustup.rs/) and OpenSSL 3.x.** This project briefly tried to avoid that build step with its own `cryptography<49` cap scoped to Intel macOS — that cap turned out to hold back *every* platform, not just the one it named (a platform-scoped upper bound alone doesn't make `uv lock` fork the resolution), so it silently left everyone on a version within a later high-severity CVE's range (a PKCS#7 EnvelopedData decryption Bleichenbacher oracle). The cap was removed rather than replaced: this project doesn't decrypt PKCS#7 envelopes itself, but a dependency carrying a known-exploitable flaw is not something to ship knowingly just to keep one platform wheel-only. If you'd rather not install a build toolchain, use the [container image](#run-as-a-container) instead (built centrally on Linux, so it never hits this).
 
 ## Packages and listings
 

{docker_mcp_server-2.2.2 → docker_mcp_server-2.2.3}/docker_mcp/_hosts.py

@@ -65,6 +65,7 @@ class Host:
     label: str
     url: str | None
     read_only: bool = False
+    non_destructive: bool = False
     cert_dir: str | None = None
 
     @property
@@ -108,8 +109,10 @@ def _context_host(name: str) -> str | None:
 def resolve_local() -> str | None:
     """
     The platform-local daemon socket — first existing well-known location, Docker Desktop / rootless
-    first. Context-bypassing. Returns None to let from_env() apply its platform default (e.g. the
-    Windows named pipe, which has nothing to probe on disk).
+    first. Context-bypassing by design: `local` means the machine's own socket, never wherever a CLI
+    context happens to point. Returns None to let from_env() apply its platform default (e.g. the
+    Windows named pipe, which has nothing to probe on disk) — which is context-free because that call
+    goes through `system._from_env_no_context`.
     """
     if sys.platform == "win32":  # pyright: ignore[reportUnreachable]
         return None
@@ -135,8 +138,12 @@ def resolve_auto() -> str | None:
     """
     The daemon a context-aware `docker` with no DOCKER_HOST would use: the active CLI context's
     endpoint (DOCKER_CONTEXT / config.json currentContext -> its meta.json Host), else the local-socket
-    probe. docker-py's from_env() is context-blind, so we resolve the context ourselves. Returns None
-    to let from_env() apply its own platform default.
+    probe. Returns None to let from_env() apply its own platform default.
+
+    We resolve the context ourselves rather than delegating. docker-py's from_env() was context-blind
+    until 7.2.0 and now does its own resolution, but we keep ours and switch theirs off (see
+    `system._from_env_no_context`): the result has to be pinned at `load()` and shared with the docker
+    CLI shell-out, neither of which a per-client-build lookup inside docker-py can give us.
     """
     name = _active_context_name()
     if name and name != "default":
@@ -153,24 +160,28 @@ def _fail(message: str) -> NoReturn:
     raise HostConfigError(message)
 
 
-def _parse_markers(text: str, context: str) -> tuple[str, bool, str | None]:
-    """Strip trailing (ro)/(tls=<dir>) markers (any order, case-insensitive) off an endpoint string,
-    returning (endpoint, read_only, cert_dir)."""
+def _parse_markers(text: str, context: str) -> tuple[str, bool, bool, str | None]:
+    """Strip trailing (ro)/(nd)/(tls=<dir>) markers (any order, case-insensitive) off an endpoint
+    string, returning (endpoint, read_only, non_destructive, cert_dir). (ro) and (nd) may combine
+    with no error — (ro) is strictly stronger and wins at enforcement time (see server.py)."""
     read_only = False
+    non_destructive = False
     cert_dir: str | None = None
     while (match := _TRAILING_MARKER.search(text)) is not None:
         body = match.group(1).strip()
         low = body.lower()
         if low == "ro":
             read_only = True
+        elif low == "nd":
+            non_destructive = True
         elif low.startswith("tls="):
             cert_dir = body[len("tls=") :].strip()  # preserve the path's case
             if not cert_dir:
                 _fail(f"{context!r}: (tls=) needs a directory, e.g. (tls=/etc/docker/prod)")
         else:
-            _fail(f"{context!r}: unknown marker '({body})'; only (ro) and (tls=<dir>) are allowed")
+            _fail(f"{context!r}: unknown marker '({body})'; only (ro), (nd), and (tls=<dir>) are allowed")
         text = text[: match.start()].rstrip()
-    return text.strip(), read_only, cert_dir
+    return text.strip(), read_only, non_destructive, cert_dir
 
 
 def _readable(path: Path) -> bool:
@@ -211,7 +222,7 @@ def _validate_cert_dir(label: str, cert_dir: str) -> None:
 
 def _make_host(label: str, raw_endpoint: str, context: str) -> Host:
     """Build a Host from one endpoint spec: parse markers, validate, and resolve to a concrete URL."""
-    endpoint, read_only, cert_dir = _parse_markers(raw_endpoint.strip(), context)
+    endpoint, read_only, non_destructive, cert_dir = _parse_markers(raw_endpoint.strip(), context)
     low = endpoint.lower()
     if cert_dir is not None:
         if not low.startswith("tcp://"):
@@ -229,7 +240,7 @@ def _make_host(label: str, raw_endpoint: str, context: str) -> Host:
             f"host {label!r}: unrecognized endpoint {endpoint!r} "
             f"(use 'auto', 'local', or a unix:// / tcp:// / ssh:// / npipe:// URL)"
         )
-    return Host(label=label, url=url, read_only=read_only, cert_dir=cert_dir)
+    return Host(label=label, url=url, read_only=read_only, non_destructive=non_destructive, cert_dir=cert_dir)
 
 
 def _legacy_host() -> Host:
@@ -341,6 +352,11 @@ def is_read_only(host: str | None = None) -> bool:
     return resolve(host).read_only
 
 
+def is_non_destructive(host: str | None = None) -> bool:
+    """Whether the named (or default) host is flagged non-destructive (blocks DESTRUCTIVE calls only)."""
+    return resolve(host).non_destructive
+
+
 def is_multi() -> bool:
     """True when 2+ hosts are configured (gates the per-call host param, its enum, and multi-host prompts)."""
     return len(_registry) >= 2