docker-mcp-server 2.2.7__tar.gz → 2.2.8__tar.gz

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/.claude/commands/docker-sdk.md

@@ -48,6 +48,8 @@ The project structure maps SDK domains to tool files one-to-one:
 
 Read each `docker_mcp/tools/*.py` file and list every `@mcp.tool` decorated function and the `docker` module methods it calls.
 
+The CLI-backed modules shell out to `docker` through `docker_mcp/tools/_cli.py:run_docker`; find them by grepping `docker_mcp/tools/*.py` for `run_docker` rather than from a list (skipping `_cli.py` and `_ssh_proxy.py`, which are the machinery itself), and record the CLI command each tool runs. For each one, check whether a first-party Python API now covers the operation: docker-py, or any other Python package Docker publishes (look in the `docker` GitHub organisation and on PyPI for one covering the features those tools shell out for). Enumerate docker-py's public modules from the source at the release being checked, not from the rendered docs fetched in Step 1, and where the rendered docs have no page for a module, read its source. Read [architecture/cli-shell-out.md](../../architecture/cli-shell-out.md) before judging a candidate: moving a tool off the CLI also moves it off the SSH remote-exec fallback and file staging.
+
 ### Step 3 - Produce a gap analysis
 
 Compare the SDK surface area from Step 1 against the MCP tool inventory from Step 2 and output a structured report:
@@ -63,6 +65,10 @@ Compare the SDK surface area from Step 1 against the MCP tool inventory from Ste
 - <`docker` module method>() - <one-line description> → should go in docker_mcp/tools/<file>.py
 ...
 
+### CLI Shell-outs With a First-party Python API Equivalent
+- <MCP tool name> (docker_mcp/tools/<file>.py) runs `docker <command>` → could use <package and method>(), verified at <source location>; changes for callers: <remote-exec fallback, staging, credentials, context>
+...
+
 ### Verification Notes
 For any specific functions the user asked about: confirmed they exist (or do not exist)
 in the live documentation, with the exact signature.

docker_mcp_server-2.2.8/.github/workflows/announce-pull-requests.yaml

@@ -0,0 +1,18 @@
+name: 'Announce pull requests'
+
+# Posts a pull request that needs action to the project's Slack channel through the shared
+# announcer, which decides what to post (architecture/ci.md).
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review]
+
+permissions: {}
+
+jobs:
+  slack:
+    name: Announce to Slack
+    uses: L337-org/github-workflows/.github/workflows/slack-on-pull-request.yaml@v2
+    with:
+      channel: '#docker-mcp'
+    secrets:
+      SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/.github/workflows/canary.yaml

@@ -42,7 +42,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
         with:
           # Pinned (matching the Dockerfile's uv image tag) so this step never needs the
           # live "resolve latest" fetch to raw.githubusercontent.com — that network call
@@ -58,7 +58,7 @@ jobs:
         run: |
           set -euo pipefail
           if [ "$GITHUB_EVENT_NAME" != "pull_request" ]; then
-            latest="$(curl -fsSL https://pypi.org/pypi/docker-mcp-server/json | jq -r .info.version)"
+            latest="$(curl -fsSL --max-time 30 --retry 3 https://pypi.org/pypi/docker-mcp-server/json | jq -r .info.version)"
             echo "Latest published release: $latest"
           fi
           failed=0
@@ -104,7 +104,7 @@ jobs:
         os: [macos-latest, macos-15-intel, windows-latest]
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
         with:
           # This job deliberately has no checkout — it tests the *published* package, not the
           # repo — so disable the repo-keyed cache and the empty-workdir warning it triggers.

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/.github/workflows/code-review.yaml

@@ -3,7 +3,7 @@ permissions:
   contents: read
 
 # What this caller decides.  The shared workflow decides everything else about the review, and
-# its README describes it at the commit pinned below.
+# its README describes it at the version named below.
 #
 # - Opening a pull request, and every push to one, asks for a review at the depth the shared
 #   workflow picks.  A push is reviewed deliberately: the loop that invites, a reviewing agent and
@@ -41,7 +41,7 @@ jobs:
     permissions:
       contents: read
       pull-requests: write
-    uses: L337-org/github-workflows/.github/workflows/claude-review.yaml@68eac351110ef94d36c0b98cec08339cd22c7ab7 # v1.2.0
+    uses: L337-org/github-workflows/.github/workflows/claude-review.yaml@v2
     with:
       pr-number: ${{ github.event.pull_request.number || github.event.issue.number }}
       depth: >-

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/.github/workflows/codeql.yaml

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

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/.github/workflows/premerge.yaml

@@ -22,7 +22,7 @@ jobs:
 
   repo-hygiene:
     # Conventions every repository in this organisation shares, checked by the one copy in the
-    # shared workflows repository at the commit pinned here.
+    # shared workflows repository at the version tag named here.
     runs-on: [ubuntu-latest]
     name: Repository hygiene
     # 9s for the whole job on the first run of the shared action here, uv setup included.
@@ -32,25 +32,26 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Repository conventions hold
-        uses: L337-org/github-workflows/actions/repo-hygiene@68eac351110ef94d36c0b98cec08339cd22c7ab7 # v1.2.0
+        uses: L337-org/github-workflows/actions/repo-hygiene@v2
 
   action-pins:
-    # Every `uses:` in .github/workflows and .github/actions names a full commit SHA, checked by
-    # the shared copy pinned here.  Its default directories are this repository's, so the local
+    # Every third-party `uses:` in .github/workflows and .github/actions names a full commit SHA,
+    # and the shared workflows repository is named at its major-version tag, checked by the
+    # shared copy.  Its default directories are this repository's, so the local
     # file-failure-issue action is covered too.  Why the pin matters most here: publish.yaml
     # mints an OIDC token for PyPI Trusted Publishing (`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.
+    # (`packages: write`) and uploads release assets (`contents: write`), so a repointed
+    # third-party tag would execute inside the jobs holding this project's strongest credentials.
     runs-on: [ubuntu-latest]
-    name: Action pins are immutable
+    name: Action pin check
     # 5s for the whole job on the first run of the shared action here - a grep over the workflows.
     timeout-minutes: 5
     steps:
       - name: Check out source repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Every `uses:` must name a 40-hex commit SHA
-        uses: L337-org/github-workflows/actions/action-pins@68eac351110ef94d36c0b98cec08339cd22c7ab7 # v1.2.0
+      - name: Every `uses:` must name a 40-hex commit SHA, or the shared workflows' major-version tag
+        uses: L337-org/github-workflows/actions/action-pins@v2
 
   fresh-resolve-import:
     # Answers a question `uv sync --locked` (used by every other job here) cannot: would a
@@ -77,7 +78,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
 
       - name: Resolve and install from pyproject.toml, ignoring uv.lock
         # A failure here is a resolve/build/install failure (an unsatisfiable specifier, a
@@ -127,7 +128,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
         with:
           # The release jobs' uv, so the rehearsal locks with the same version; a test in
           # tests/test_claude_plugin_release.py keeps them equal.
@@ -185,7 +186,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
         with:
           version: "0.11.21"
           enable-cache: false
@@ -214,7 +215,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
 
       - name: Install dependencies
         # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
@@ -245,7 +246,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
 
       - name: Install dependencies
         # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
@@ -278,7 +279,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
 
       - name: Install dependencies
         run: uv sync --all-groups --locked
@@ -308,7 +309,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
 
       - name: Install dependencies
         # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
@@ -347,7 +348,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
 
       - name: Install dependencies
         # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
@@ -366,7 +367,7 @@ jobs:
           docker scout version 2>/dev/null || echo "scout not installed; scout integration tests will skip"
 
       - name: Initialize a single-node swarm
-        # Needed for service_wait / node_wait integration tests (skip_if_no_swarm), which
+        # Needed for system_wait's service / node integration tests (skip_if_no_swarm), which
         # otherwise skip cleanly on a non-swarm daemon. No teardown needed — the runner is
         # ephemeral and torn down after the job.
         run: docker swarm init

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/.github/workflows/publish-homebrew.yaml

@@ -71,7 +71,7 @@ jobs:
         run: git fetch --depth=1 origin main && git checkout origin/main -- scripts/docker-mcp-server.rb.tpl
 
       - name: Install uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
 
       - name: Resolve version, Python target, and macOS floor
         run: |

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/.github/workflows/publish.yaml

@@ -179,7 +179,7 @@ jobs:
           python-version: "3.14"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
 
       - name: Build sdist and wheel
         run: uv build
@@ -202,7 +202,7 @@ jobs:
         env:
           VERSION: ${{ needs.preflight.outputs.version }}
         run: |
-          code="$(curl -sS --max-time 30 -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/docker-mcp-server/$VERSION/json")"
+          code="$(curl -sS --max-time 30 --retry 3 -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/docker-mcp-server/$VERSION/json")"
           case "$code" in
             200) echo "uploaded=false" >> "$GITHUB_OUTPUT"
                  echo "::notice::docker-mcp-server $VERSION is already on PyPI; this run uploads nothing (skip-existing)." ;;
@@ -508,7 +508,7 @@ jobs:
           # asset-CDN lag.
           mkdir -p _mcpb
           for i in $(seq 1 3); do
-            if gh release download "$TAG" --repo "$GITHUB_REPOSITORY" --pattern '*.mcpb' --dir _mcpb --clobber; then
+            if timeout 120 gh release download "$TAG" --repo "$GITHUB_REPOSITORY" --pattern '*.mcpb' --dir _mcpb --clobber; then
               break
             fi
             echo "::notice::.mcpb asset for $TAG not readable yet (attempt $i/3); waiting 10s"
@@ -544,7 +544,8 @@ jobs:
           MCP_PUBLISHER_SHA256: ab128162b0616090b47cf245afe0a23f3ef08936fdce19074f5ba0a4469281ac
         run: |
           set -euo pipefail
-          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz" \
+          curl -fsSL --connect-timeout 30 --speed-limit 102400 --speed-time 30 --max-time 300 --retry 3 \
+            "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz" \
             -o mcp-publisher.tar.gz
           echo "${MCP_PUBLISHER_SHA256}  mcp-publisher.tar.gz" | sha256sum -c -
           tar xzf mcp-publisher.tar.gz mcp-publisher
@@ -617,7 +618,7 @@ jobs:
         run: |
           set -euo pipefail
           for i in $(seq 1 5); do
-            if curl -fsS "https://pypi.org/pypi/docker-mcp-server/${VERSION}/json" >/dev/null; then
+            if curl -fsS --max-time 30 "https://pypi.org/pypi/docker-mcp-server/${VERSION}/json" >/dev/null; then
               echo "PyPI OK: docker-mcp-server ${VERSION}"; exit 0
             fi
             echo "::notice::PyPI does not serve ${VERSION} yet (attempt $i/5); waiting 15s"
@@ -759,7 +760,16 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p _verify
-          gh release download "$TAG" --repo "$GITHUB_REPOSITORY" --pattern '*.mcpb*' --dir _verify
+          # A release asset comes from the same CDN whose 504s these downloads retry elsewhere, and a
+          # failure here turns a converged release red; the count check below catches every attempt
+          # failing.
+          for i in $(seq 1 3); do
+            if timeout 120 gh release download "$TAG" --repo "$GITHUB_REPOSITORY" --pattern '*.mcpb*' --dir _verify --clobber; then
+              break
+            fi
+            echo "::notice::.mcpb assets for $TAG not downloadable (attempt $i/3); waiting 10s"
+            sleep 10
+          done
           shopt -s nullglob
           mcpb=(_verify/*.mcpb); sums=(_verify/*.sha256)
           if [ "${#mcpb[@]}" -ne 1 ] || [ "${#sums[@]}" -ne 1 ]; then
@@ -775,8 +785,14 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p _skill
-          gh release download "$TAG" --repo "$GITHUB_REPOSITORY" \
-            --pattern 'l337-docker-skill-*' --dir _skill
+          for i in $(seq 1 3); do
+            if timeout 120 gh release download "$TAG" --repo "$GITHUB_REPOSITORY" \
+                --pattern 'l337-docker-skill-*' --dir _skill --clobber; then
+              break
+            fi
+            echo "::notice::skill archive for $TAG not downloadable (attempt $i/3); waiting 10s"
+            sleep 10
+          done
           shopt -s nullglob
           tars=(_skill/*.tar.gz); sums=(_skill/*.sha256)
           if [ "${#tars[@]}" -ne 1 ] || [ "${#sums[@]}" -ne 1 ]; then
@@ -802,7 +818,7 @@ jobs:
           set -euo pipefail
           url="https://registry.modelcontextprotocol.io/v0/servers?search=io.github.L337-org/docker-mcp-server"
           for i in $(seq 1 5); do
-            if curl -fsS "$url" | jq -e --arg v "$VERSION" \
+            if curl -fsS --max-time 30 "$url" | jq -e --arg v "$VERSION" \
                 '.servers[] | select(.server.version == $v)' >/dev/null; then
               echo "MCP Registry OK: ${VERSION} listed"; exit 0
             fi
@@ -864,7 +880,7 @@ jobs:
 
       - name: Set up uv
         if: steps.plugin.outputs.has_plugin == 'true'
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
         with:
           # Pinned, so the lock is written by a known uv; a test in
           # tests/test_claude_plugin_release.py keeps the rehearsal's pins equal to these.
@@ -938,7 +954,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
         with:
           version: "0.11.21"
           enable-cache: false

docker_mcp_server-2.2.8/.github/workflows/report-failures.yaml

@@ -0,0 +1,32 @@
+name: 'Report failures'
+
+# Posts a failed run of a workflow named below, started by one of the events below, to the
+# project's Slack channel through the shared reporter (architecture/ci.md).  GitHub reads this
+# trigger only from the default branch.
+on:
+  workflow_run:
+    workflows:
+      - 'Weekly canary'
+      - 'CodeQL'
+      - 'Code review'
+      - 'Build container images'
+      - 'Check inbound changes'
+      - 'Release'
+      - 'Announce pull requests'
+    types: [completed]
+
+permissions:
+  # Both read by the shared reporter, which GitHub refuses to start without them: to name the
+  # failed jobs and find a run that replaced a cancelled one, and to tell a tag from a branch.
+  actions: read
+  contents: read
+
+jobs:
+  slack:
+    name: Report to Slack
+    uses: L337-org/github-workflows/.github/workflows/slack-on-failure.yaml@v2
+    with:
+      channel: '#docker-mcp'
+      events: '["schedule", "push", "release", "pull_request"]'
+    secrets:
+      SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/.gitignore

@@ -2,6 +2,7 @@
 /.*
 !/.agents/
 !/.python-version
+!/.pre-commit-config.yaml
 !/.gitignore
 !/.dockerignore
 !/.mcpbignore

docker_mcp_server-2.2.8/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+# Installed with `uv run pre-commit install` (CONTRIBUTING.md). Local hooks through `uv run`, not the
+# ruff-pre-commit repo, so the hook runs the ruff version uv.lock resolves for the dev group rather than a
+# second pin that can drift from it.
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check --fix
+        entry: uv run ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+        require_serial: true

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/AGENTS.md

@@ -37,7 +37,7 @@ Read the linked file before judging a substantive change to that area.
 | code calling `docker` | [architecture/docker-sdk.md](architecture/docker-sdk.md) | an unverified method; a hand-built route that is not in the Engine API spec; a reach-in past the public SDK introduced without recorded sign-off |
 | `Dockerfile`, `manifest.json`, `server.json`, `claude-plugin/`, release workflows | [architecture/distribution.md](architecture/distribution.md) | a version-declaring file missing from the bump checklist there, `preflight`, or the version tests; a registry ownership marker no longer matching `server.json`'s `name` |
 | `skills/l337-docker/` | [architecture/agent-skill.md](architecture/agent-skill.md) | the skill described as equivalent to the server; tool-permission frontmatter added; a hand-edited figure in `MCP_VS_SKILLS.md` |
-| `.github/workflows/` | [architecture/ci.md](architecture/ci.md) | a `uses:` naming a tag or branch; a new job without `timeout-minutes` where the workflow requires one |
+| `.github/workflows/` | [architecture/ci.md](architecture/ci.md) | a third-party `uses:` naming a tag or branch (`L337-org/github-workflows` is named at its major-version tag); a new job without `timeout-minutes` where the workflow requires one |
 
 ## Project
 
@@ -136,7 +136,10 @@ Any tool wrapping a `docker` CLI feature (Compose, Stack, Buildx, Scout, Context
 `docker_mcp/tools/_cli.py:run_docker` — never call `subprocess.run` directly from a tool module. That
 helper is the single place holding binary resolution, `shell=False`, UTF-8 decoding, the output byte
 cap, Windows console suppression and the environment allow-list. Always pass an explicit `timeout=`.
-Never pass `shell=True`, never build paths by string concatenation, never expand `~` or globs yourself.
+Never pass `shell=True`, never build paths by string concatenation, and never expand a glob or a
+variable. Expand only a leading `~`, only where the tool documents it (`buildx_build`'s path
+parameters), and only with `os.path.expanduser`: pathlib's `expanduser()` raises a bare
+`RuntimeError` for an unknown `~user`, where `os.path` leaves the value for the CLI to report.
 
 **Read [architecture/cli-shell-out.md](architecture/cli-shell-out.md) before touching any of it**, and
 before adding a CLI-backed tool. It covers the SSH remote-exec fallback (which changes *which host* a
@@ -152,8 +155,9 @@ module method you have not confirmed in the docs. Do not assume a method exists
 plausible; if you cannot confirm it, say so and do not use it.
 
 Prefer the high-level object API; drop to `_get_client().api` only for documented gaps, verified the
-same way. **"The method exists" and "the method works" are separate claims** — `plugin_push` is the
-standing example of a documented, importable SDK method that 404s against every daemon.
+same way. **"The method exists" and "the method works" are separate claims** — docker-py's
+`Plugin.push()` is the standing example of a documented, importable SDK method that 404s against
+every daemon.
 
 **Reaching past the public SDK is not an agent's call to make.** Where the public path fails, stop,
 write up what you found, and escalate for a human decision rather than implementing a workaround.
@@ -186,6 +190,17 @@ discovery layers. Four cleanup rounds have chased the same failure.
   `timeout_seconds`. `tests/test_naming.py` enforces all of this (approved prefixes, banned short forms and
   1.x spellings, canonical shared-param descriptions) — a violating tool fails CI.
 - New Docker functionality goes in the matching `docker_mcp/tools/<domain>.py` file, not in a new file.
+- **Waiting is one tool, `system_wait`.** A new thing to wait for is a new `kind` or `until` in `_WAIT_KINDS`
+  (`system.py`) with its helper in the owning domain's module, never a new `*_wait` tool and never a blocking
+  option on an action tool: action tools return once their work is started. The exceptions are
+  `container_exec` and `container_run(timeout_seconds=...)`: both serve running something quick and getting
+  the answer straight back, which would otherwise take several calls. Both are bounded; see
+  [architecture/server.md](architecture/server.md#waiting). `kind`/`until` are built from the
+  enabled domains at import, so a disabled domain's waits are not offered. Its `target` parameter is a
+  deliberate exception to the identifier spellings above, because one argument names a container, service,
+  node, stack, compose project or `repository:tag`. `system` and `containers` cannot be disabled
+  (`ALWAYS_ON_DOMAINS` in `server.py`); naming either in `DOCKER_MCP_SERVER_DISABLE` is reported as ignored,
+  not silently dropped.
 - Every new `docker_mcp/tools/` file must be imported in `docker_mcp/tools/__init__.py` (private `_*.py` helpers excluded).
 - Every new `docker_mcp/tools/<module>.py` must have a matching `tests/test_<module>.py`.
 - Tool functions are decorated with `@tool()` (imported from `docker_mcp.server`) and must have a `TOOL_CATEGORIES` entry in `docker_mcp/server.py`.
@@ -237,7 +252,7 @@ discovery layers. Four cleanup rounds have chased the same failure.
 
 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 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`.
+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. 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`.
 
 ## Invariants that fail silently
 
@@ -354,17 +369,14 @@ Removing an entry is a real decision, not a tidy-up.
 **SDK surface deliberately not wrapped, or wrapped unobviously.** A recurring audit routine
 re-proposes these; it has no memory of last time.
 
-- **`plugin_push`'s hand-built endpoint call.** docker-py's `Plugin.push()` / `APIClient.push_plugin()`
-  both POST to `/plugins/{name}/pull`, a route the Engine does not define, so they 404 against every
-  daemon. Our call is the working path, not debt. Revisit only if upstream fixes the URL.
 - **`Container.attach` / `attach_socket` / `resize` unwrapped.** An interactive bidirectional stream
   does not fit a request/response tool call. `container_exec` covers scripted execution.
 - **`service_rollback`'s `api.inspect_service` + `api.update_service`.** The high-level
   `Service`/`ServiceCollection` expose no `rollback`. Permanently low-level.
 - **`system_logout`'s `api._auth_configs`.** There is no `logout` anywhere in the SDK and no server-side
   session to end. Permanently low-level.
-- **`swarm_task_list` / `swarm_task_inspect`'s `api.tasks()` / `api.inspect_task()`.** docker-py has no
-  task collection at all. These documented `APIClient` methods are the only public path.
+- **`service_ps`'s `api.tasks()` with no service, and `service_logs(task=...)`'s hand-built
+  `GET /tasks/{id}/logs`.** docker-py has no task collection and no task-logs method at all.
 
 **Other settled decisions.**
 
@@ -384,7 +396,7 @@ re-proposes these; it has no memory of last time.
   (pyupgrade, 3.14 target) may rewrite to the unparenthesized form.
 
 - **Image builds are not provenance-stamped.** A build label changes the resulting image digest.
-  Compose and stack containers, and `plugin_create`, are unstamped for their own recorded reasons.
+  Compose and stack containers are unstamped for their own recorded reasons.
 - **Cross-host redirects are followed on purpose.** Registries answer blob fetches with a redirect to a
   CDN on another host as normal operation, so refusing them breaks `registry_image_config`. httpx
   strips `Authorization` on any cross-origin redirect, and a redirect reaches nothing a tool argument
@@ -471,9 +483,8 @@ afterthought: at this server's size it is the dominant cost of connecting to it
 `tests/test_surface_budget.py` holds the ceilings: per tool, per component, and in total.
 
 **What is measured is the wire form, not the docstring.** A tool costs its name, its description
-and its whole input schema, and the schema is usually the larger half - `buildx_build` is 5,091
-bytes on the wire against 3,398 of description. A docstring-only budget would go green on a
-change that added twenty parameters.
+and its whole input schema, so a docstring-only budget would go green on a change that added
+twenty parameters. `tests/test_surface_budget.py`'s header gives the command that measures both.
 
 **Bytes, not tokens.** Tokens are what a model pays, but they need a tokenizer pinned to a model
 that changes underneath us, so the figure moves without the surface moving. That is why

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/CONTRIBUTING.md

@@ -8,7 +8,7 @@ This is an [MCP](https://modelcontextprotocol.io) server: it exposes Docker oper
 
 The practical mental model for finding your way around:
 
-- One file per Docker feature area (`containers.py`, `images.py`, `swarm.py`, ...), each backed by either the [docker-py SDK](https://docker-py.readthedocs.io/en/stable/) or a `docker` CLI shell-out (`compose.py`, `stack.py`, `context.py`, `buildx.py`, `scout.py`). See the tree below for the full map.
+- One file per Docker feature area (`containers.py`, `images.py`, `swarm.py`, ...), each backed by either the [docker-py SDK](https://docker-py.readthedocs.io/en/stable/) or a `docker` CLI shell-out (`compose.py`, `stack.py` for `stack_deploy` only, `context.py`, `buildx.py`, `scout.py`). See the tree below for the full map.
 - Every tool function is registered centrally in `docker_mcp/server.py`, which is also where read-only/destructive classification, naming enforcement, and the domain-disable switches live.
 - `AGENTS.md` (repo root) is the always-loaded brief for every assistant, and the map of everything else: it carries the conventions and a table pointing at the deeper notes. Those notes live in `architecture/` - one file per area (`server.md`, `hosts.md`, `cli-shell-out.md`, `tool-descriptions.md`, `docker-sdk.md`, `distribution.md`, `agent-skill.md`, `ci.md`), and they are the canonical detail for humans and assistants alike. This file (`CONTRIBUTING.md`) covers the practical day-to-day: setup, the checklist for adding a tool, testing conventions, and submitting changes. If something isn't covered here, look at `AGENTS.md`'s table and follow it into `architecture/`.
 
@@ -35,7 +35,7 @@ The practical mental model for finding your way around:
 │       ├── swarm.py
 │       ├── plugins.py
 │       ├── compose.py     # `docker compose` CLI plugin (shells out via _cli.py)
-│       ├── stack.py       # `docker stack` (Compose-on-Swarm) CLI (shells out via _cli.py)
+│       ├── stack.py       # Compose-on-Swarm: `docker stack deploy` via _cli.py, the rest via docker-py
 │       ├── context.py     # `docker context` CLI (shells out via _cli.py)
 │       ├── buildx.py      # `docker buildx` CLI plugin (shells out via _cli.py)
 │       ├── scout.py       # `docker scout` CLI plugin (shells out via _cli.py)

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/DOCKERHUB.md

@@ -38,7 +38,7 @@ The only host prerequisite is Docker. Point your MCP client at `docker run`:
 
 ## Image variants
 
-Two multi-arch (linux/amd64 + linux/arm64) variants are published, both built from one `Dockerfile`. The CLI-backed domains (Compose, Stack, Buildx, Scout, Context) shell out to the `docker` CLI and its plugins.
+Two multi-arch (linux/amd64 + linux/arm64) variants are published, both built from one `Dockerfile`. The CLI-backed domains (Compose, Stack, Buildx, Scout, Context) shell out to the `docker` CLI and its plugins; in Stack, only `stack_deploy` does.
 
 | Variant | Tags | Approx. size | Includes |
 |---------|------|-------------|----------|

{docker_mcp_server-2.2.7 → docker_mcp_server-2.2.8}/Dockerfile

@@ -55,13 +55,19 @@ ARG DISABLE_DOMAINS=""
 ARG SCOUT_VERSION=1.21.0
 
 # Install the docker CLI + compose/buildx plugins (and optionally scout) for the CLI-backed domains.
-# Skipped entirely for the `lite` variant (INSTALL_CLI=0).
+# Skipped entirely for the `lite` variant (INSTALL_CLI=0). Every curl download is bounded and
+# retried, because one 504 from GitHub's release CDN or download.docker.com otherwise fails the
+# whole build; curl's --retry only retries timeouts and HTTP 408, 429, 500, 502, 503 and 504, so a
+# 404 or a bad checksum still fails.  --speed-limit/--speed-time abandon a stalled attempt after
+# 30 s, and --max-time caps a slow one, so it must stay large enough for the scout tarball; both
+# apply per attempt, not in total.  apt's own fetches follow apt's retry settings, which this does
+# not change.
 RUN if [ "$INSTALL_CLI" = "1" ]; then \
         set -eux; \
         apt-get update; \
         apt-get install -y --no-install-recommends ca-certificates curl gnupg; \
         install -m 0755 -d /etc/apt/keyrings; \
-        curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc; \
+        curl -fsSL --connect-timeout 30 --speed-limit 102400 --speed-time 30 --max-time 300 --retry 3 https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc; \
         chmod a+r /etc/apt/keyrings/docker.asc; \
         printf 'deb [arch=%s signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian %s stable\n' \
             "$(dpkg --print-architecture)" "$DEBIAN_RELEASE" > /etc/apt/sources.list.d/docker.list; \
@@ -72,8 +78,8 @@ RUN if [ "$INSTALL_CLI" = "1" ]; then \
             scout_tar="docker-scout_${SCOUT_VERSION}_linux_${scout_arch}.tar.gz"; \
             scout_base="https://github.com/docker/scout-cli/releases/download/v${SCOUT_VERSION}"; \
             mkdir -p /usr/libexec/docker/cli-plugins; \
-            curl -fsSL "${scout_base}/${scout_tar}" -o "/tmp/${scout_tar}"; \
-            curl -fsSL "${scout_base}/docker-scout_${SCOUT_VERSION}_checksums.txt" -o /tmp/scout_checksums.txt; \
+            curl -fsSL --connect-timeout 30 --speed-limit 102400 --speed-time 30 --max-time 300 --retry 3 "${scout_base}/${scout_tar}" -o "/tmp/${scout_tar}"; \
+            curl -fsSL --connect-timeout 30 --speed-limit 102400 --speed-time 30 --max-time 300 --retry 3 "${scout_base}/docker-scout_${SCOUT_VERSION}_checksums.txt" -o /tmp/scout_checksums.txt; \
             (cd /tmp && grep -F "${scout_tar}" scout_checksums.txt | sha256sum -c -); \
             tar -xzf "/tmp/${scout_tar}" -C /usr/libexec/docker/cli-plugins docker-scout; \
             chmod +x /usr/libexec/docker/cli-plugins/docker-scout; \