docker-mcp-server 2.1.2__tar.gz → 2.1.4__tar.gz

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.4}/.github/copilot-instructions.md

@@ -4,7 +4,7 @@ This file provides guidance to GitHub Copilot when working with code in this rep
 
 ## Project
 
-`docker-mcp` is a Python MCP (Model Context Protocol) server that exposes the Docker SDK for Python — plus selected docker CLI features (Compose, Context, Buildx, Scout) and direct OCI-registry HTTPS access — as MCP tools. It requires Python >=3.14 and is managed with `uv`. It is published to PyPI as **`docker-mcp-server`** and as a container image to GHCR (`ghcr.io/l337-org/docker-mcp-server`), mirrored to Docker Hub (`gavinlucas/docker-mcp-server`) when the opt-in `DOCKERHUB_*` release secrets are configured (the import package stays `docker_mcp`, the repo stays `…/docker-mcp`); two console scripts — `docker-mcp` and `docker-mcp-server` — both target `docker_mcp:main`. A third distribution channel packages the server as a **Claude Desktop Extension (`.mcpb`)** attached to each GitHub Release (see "Desktop Extension (MCPB)" below). A fourth channel (**Homebrew tap**) exists in `gavinlucas/homebrew-tap` but is currently **paused** — see "Homebrew tap" below.
+`docker-mcp` is a Python MCP (Model Context Protocol) server that exposes the Docker SDK for Python — plus selected docker CLI features (Compose, Context, Buildx, Scout) and direct OCI-registry HTTPS access — as MCP tools. It requires Python >=3.14 and is managed with `uv`. It is published to PyPI as **`docker-mcp-server`** and as a container image to GHCR (`ghcr.io/l337-org/docker-mcp-server`), mirrored to Docker Hub (`gavinlucas/docker-mcp-server`) when the opt-in `DOCKERHUB_*` release secrets are configured (the import package stays `docker_mcp`, the repo stays `…/docker-mcp`); two console scripts — `docker-mcp` and `docker-mcp-server` — both target `docker_mcp:main`. A third distribution channel packages the server as a **Claude Desktop Extension (`.mcpb`)** attached to each GitHub Release (see "Desktop Extension (MCPB)" below). A fourth channel (**Homebrew tap**) exists in `L337-org/homebrew-tap` but is currently **paused** — see "Homebrew tap" below.
 
 The `docker` dep uses the `[ssh]` extra (paramiko), so `DOCKER_HOST=ssh://…` works via a pure-Python transport (no system `ssh` binary; works in the container images). docker-py auto-selects paramiko for `ssh://`, so there's no transport code — only the `ssh://` branch in `system._connection_help`. CLI-backed tools (Compose, Buildx, Context, Scout) shell out to `docker`, which would otherwise need the system `ssh` client — instead, `_cli.py:run_docker` detects `DOCKER_HOST=ssh://…` and routes the subprocess through a per-call local TCP proxy (`docker_mcp/tools/_ssh_proxy.py`) that opens its own paramiko connection and runs `docker system dial-stdio` over it, so the CLI authenticates the same way the docker-py-backed tools do, with no system `ssh` binary involved (except a `ProxyCommand` in `~/.ssh/config` for bastion/jump-host setups, which paramiko runs as an external command — commonly `ssh -W %h:%p ...` — for both tool families alike).
 
@@ -89,11 +89,11 @@ An additional distribution channel alongside the uvx-from-git install (unchanged
 
 ### Desktop Extension (MCPB)
 
-A third distribution channel for one-click install in Claude Desktop. Repo-root sources: `manifest.json` (MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (bundle entry point — `from docker_mcp import main; main()`, at the root so `import docker_mcp` resolves under the host's managed `uv`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + manifest/entry-point + `assets/`), and `assets/icon.png` (512×512). It's a `uv`-type bundle: the host resolves deps from `pyproject.toml` at install time (no vendored venv). `manifest.json`'s `user_config` maps install-dialog fields to env — `DOCKER_MCP_SERVER_HOSTS` (the single host field; `DOCKER_HOST` is **not** exposed — the bare-value shorthand keeps the one-daemon case a one-liner) and the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is intentionally omitted — the bundle never runs containerized). The `mcpb` job in `.github/workflows/publish.yaml` rewrites the manifest `version` from the release tag, packs the `.mcpb` via `npx @anthropic-ai/mcpb`, and attaches it (plus a `.sha256` recording the bare filename, so `sha256sum -c` works on downloads) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (version from `pyproject.toml`, auto-incrementing output in `dist/`, never mutates `manifest.json`) for smoke-testing in Claude Desktop — it is deliberately **not** used by CI. `PRIVACY.md` (no-telemetry statement) is referenced by the manifest's `privacy_policies`. Keep the manifest `version` aligned with `pyproject.toml`; update this section when the manifest's tool/env surface or the bundled file set changes.
+A third distribution channel for one-click install in Claude Desktop. Repo-root sources: `manifest.json` (MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (bundle entry point — `from docker_mcp import main; main()`, at the root so `import docker_mcp` resolves under the host's managed `uv`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + manifest/entry-point + `assets/`), and `assets/icon.png` (512×512). It's a `uv`-type bundle: the host resolves deps from `pyproject.toml` at install time (no vendored venv). `manifest.json`'s `user_config` maps install-dialog fields to env — `DOCKER_MCP_SERVER_HOSTS` (the single host field; `DOCKER_HOST` is **not** exposed — the bare-value shorthand keeps the one-daemon case a one-liner) and the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is intentionally omitted — the bundle never runs containerized). The `mcpb` job in `.github/workflows/publish.yaml` rewrites the manifest `version` from the release tag, packs the `.mcpb` via `npx @anthropic-ai/mcpb`, and attaches it (plus a `.sha256` recording the bare filename, so `sha256sum -c` works on downloads) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (auto-incrementing output in `dist/`) for smoke-testing in Claude Desktop — it is deliberately **not** used by CI. It stamps a **dev version** from `pyproject.toml` + git HEAD — `<version>-dev.<short-commit>[.dirty]` — so a local bundle can't be mistaken for a release and is traceable to its commit; the stamp goes into `manifest.json` only for the pack and is restored by an `EXIT` trap. `PRIVACY.md` (no-telemetry statement) is referenced by the manifest's `privacy_policies`. Keep the manifest `version` aligned with `pyproject.toml`; update this section when the manifest's tool/env surface or the bundled file set changes.
 
-### Homebrew tap (`gavinlucas/homebrew-tap`) — PAUSED
+### Homebrew tap (`L337-org/homebrew-tap`) — PAUSED
 
-The infrastructure exists (`scripts/docker-mcp-server.rb.tpl`, `.github/workflows/publish-homebrew.yaml`, `GavinLucas/homebrew-tap`) but the **release trigger is disabled** pending resolution of a Homebrew dylib linkage issue: pre-built PyPI wheels for `pydantic_core` lack `-headerpad_max_install_names`, so Homebrew's post-install relocation step fails to rewrite the `@rpath` ID (the binary's Mach-O header has no room for the longer absolute path). The workflow is `workflow_dispatch`-only until a fix is found. The channel is not advertised in the README. To re-enable: add `release: types: [published]` back to `publish-homebrew.yaml`'s `on:` block and re-add the Homebrew section to the README.
+The infrastructure exists (`scripts/docker-mcp-server.rb.tpl`, `.github/workflows/publish-homebrew.yaml`, `L337-org/homebrew-tap`) but the **release trigger is disabled** pending resolution of a Homebrew dylib linkage issue: pre-built PyPI wheels for `pydantic_core` lack `-headerpad_max_install_names`, so Homebrew's post-install relocation step fails to rewrite the `@rpath` ID (the binary's Mach-O header has no room for the longer absolute path). The workflow is `workflow_dispatch`-only until a fix is found. The channel is not advertised in the README. To re-enable: add `release: types: [published]` back to `publish-homebrew.yaml`'s `on:` block and re-add the Homebrew section to the README.
 
 ### MCP Registry (`server.json`)
 
@@ -148,12 +148,18 @@ def mcp_example(name: str):
     """
     Say hello to someone by name.
 
-    args: name - The name to say hello to
+    Use it for a single greeting; use `mcp_example_bulk` to greet many names in one call.
+    Read-only, no side effects.
+
+    args: name - The name to say hello to (any non-empty string)
     returns: str - The greeting
     """
     return f"Hello, {name}!"
 ```
 
+(`mcp_example` and `mcp_example_bulk` are illustrative only and exist nowhere in the repo — in a
+real docstring the discriminator must name an actually-registered sibling tool.)
+
 - One-line summary sentence, then a blank line
 - `args:` section lists each parameter as `name - description`. Do **not** repeat the parameter's
   type — the type annotation already lands in the tool's `inputSchema`, which the client sees
@@ -163,19 +169,66 @@ def mcp_example(name: str):
 - Keep descriptions terse: state every functional fact (defaults, accepted formats/values, return
   keys, important caveats) but cut redundancy and verbose phrasing. The docstring is the entire
   tool `description` the client pays tokens for on every session.
-- **A one-line summary + bare `args`/`returns` is not enough for any tool with non-obvious
-  behavior.** If the tool has side effects, preconditions, a non-obvious failure mode, or overlaps
-  with another tool a caller could reach for instead, add a short paragraph (2-5 sentences,
-  between the summary and `args:`) covering: when to use it vs. the alternative, side
-  effects/preconditions, and concrete parameter formats/values — not just restating the signature.
-  This directly maps to what a low-scoring tool is missing on Glama's per-tool quality rubric
-  (`Behavior`, `Usage Guidelines`, `Parameters` sub-scores) — three separate PRs (#97, the 2.0
-  rename, #129) have had to chase down thin docstrings written without this paragraph. **Write it
-  this way the first time a tool is added or its behavior changes** — don't wait for a future
-  Glama pass to catch it. Verify every factual claim in that paragraph against the live docker-py
-  docs / Engine API spec per the Docker SDK Policy below — an unverified claim about identifier
-  semantics (e.g. "name or id" for a resource actually addressed by name only) is exactly the kind
-  of thing PR review catches late.
+
+#### Docstring quality standard (review checklist — push back on non-compliant docstrings)
+
+Tool descriptions are scored externally on Glama's six-dimension Tool Definition Quality rubric
+(<https://glama.ai/mcp/servers/L337-org/docker-mcp/score>): Purpose Clarity 25%, Usage Guidelines
+20%, Behavioral Transparency 20%, Parameter Semantics 15%, Conciseness & Structure 10%, Contextual
+Completeness 10%. Repeated cleanup PRs (#97, the 2.0 rename, #129, the 2026-07 bottom-20 pass) all
+chased the same failure: docstrings that state *what* the tool does but never *when to use it over
+its neighbors*, plus `args:`/`returns:` lines that merely restate the schema. **When a PR adds or
+modifies an `@tool()` docstring, check it against every numbered item below and request changes
+naming the specific item it fails.** The standard is a ratchet: it applies to docstrings the PR
+touches — do not demand rewrites of untouched legacy docstrings.
+
+1. **Summary = specific verb + resource**, with the distinguishing trait up front when a sibling
+   could be confused ("Send a signal to a running container (default SIGKILL — immediate, no
+   graceful shutdown)").
+2. **A usage-guidance paragraph (1–5 sentences between the summary and `args:`) is required for
+   every tool, not just complex ones.** Flag a new/edited tool whose docstring jumps straight from
+   summary to `args:`. The paragraph must carry:
+   - at least one *discriminator* naming the sibling tool(s) an agent could reach for instead and
+     when to prefer which (`container_stop` vs `container_kill` vs `container_restart`;
+     `service_ps` vs `stack_ps` vs the `service-tasks://` resource);
+   - preconditions in prose (swarm manager only, plugin required, container must be
+     running/paused);
+   - side effects and destructive/irreversible behavior in prose — the scorer explicitly discounts
+     `readOnlyHint`/`destructiveHint` annotations as a substitute for description text;
+   - for CLI-backed tools, the error style ("does not raise on a non-zero CLI exit — inspect
+     `returncode`/`stderr`" vs "raises `RuntimeError` on CLI failure"). Flag an absolute "never
+     raises" claim — a missing binary/plugin or a subprocess timeout still raises even in action
+     tools.
+   Scale to the tool: a trivial read-only tool needs one discriminator sentence, not five.
+3. **Every `args:` line adds semantics the schema cannot carry**: format, accepted values/ranges,
+   defaults, units, parameter interactions. Flag a line that merely echoes the parameter name
+   ("name - The volume name") — it scores 2/5 on the rubric. Canonical shared-param prefixes in
+   `tests/test_naming.py` still apply — tool-specific detail is appended after the canonical
+   prefix, not reworded.
+4. **`returns:` names the shape, not just the type.** For computed or partial returns the
+   load-bearing keys must be listed (`{"Titles", "Processes"}`). For a full engine inspect
+   document, key enumeration is NOT wanted — an arbitrary subset of hundreds of keys is noise; the
+   line should identify the document ("full inspect payload, as `docker inspect`"), optionally
+   plus one or two keys a caller typically wants. Flag the shapeless "dict - The X's attrs" on a
+   new/modified tool, which identifies neither form.
+5. **Front-loaded and terse** — the description is paid for in every session's context.
+6. **Every factual claim must be verifiable** against the docker-py docs / Engine API spec (Docker
+   SDK Policy below). Flag claims that contradict them — especially identifier semantics ("name or
+   id" for a resource actually addressed by name only), default values, and signal/timeout
+   behavior.
+
+**Division of labor across the three discovery layers.** For a lazy-loading client (e.g. Claude
+Code), tool schemas load on demand; always in context are only (1) the **tool names** and (2) the
+**`instructions` router** (`_DOMAIN_BLURBS` / `build_instructions()` in `server.py`). Docstrings
+are layer (3): a deferred tool cannot be invoked without fetching its definition, so it is read at
+the moment of choice, side by side with sibling definitions — where the item-2 discriminators do
+their work. When reviewing, apply the boundary: a *cross-domain* selection caveat that must be
+visible before any schema is fetched (e.g. "prefer `dest_path` for large output") belongs in the
+router's caveat list, not buried in one docstring; *sibling-level* discriminators belong in
+docstrings and should not be duplicated into the router; flag docstrings padded with search
+keywords (discoverability is the naming convention's and the router's job); and flag sibling
+references that don't use the exact tool name (`container_kill`, never "the kill tool") — lazy
+clients keyword-search descriptions, so exact names double as retrieval anchors.
 
 ### Bounding rules
 

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.4}/.github/workflows/codeql.yaml

@@ -31,12 +31,12 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4
+        uses: github/codeql-action/init@7188fc363630916deb702c7fdcf4e481b751f97a # v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4
+        uses: github/codeql-action/autobuild@7188fc363630916deb702c7fdcf4e481b751f97a # v4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4
+        uses: github/codeql-action/analyze@7188fc363630916deb702c7fdcf4e481b751f97a # v4

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.4}/.github/workflows/publish-homebrew.yaml

@@ -2,7 +2,7 @@ name: 'Publish Homebrew formula'
 
 # On each GitHub Release: downloads pre-built macOS wheels for arm64 and x86_64 from PyPI (using
 # the frozen lockfile so versions are pinned), packages each set into a wheelhouse tarball, attaches
-# both to the release, then pushes an updated Formula/docker-mcp-server.rb to GavinLucas/homebrew-tap.
+# both to the release, then pushes an updated Formula/docker-mcp-server.rb to L337-org/homebrew-tap.
 #
 # Runs on ubuntu-latest. Both wheelhouses are built via cross-platform pip downloads:
 #   arm64:   --platform macosx_<floor>_arm64  +  --platform macosx_<floor>_universal2
@@ -23,8 +23,11 @@ name: 'Publish Homebrew formula'
 # guardrail; do not remove it.
 #
 # Requires the repository secret TAP_GITHUB_TOKEN: a fine-grained PAT with Contents read+write on
-# GavinLucas/homebrew-tap. Create it at github.com/settings/tokens and add it as a secret on this
-# repo under Settings → Secrets → Actions.
+# L337-org/homebrew-tap, issued with **L337-org as the resource owner** (a fine-grained PAT scoped
+# to a personal account cannot access org repos, and org settings must allow fine-grained PAT
+# access). Create it at github.com/settings/tokens and add it as a secret on this repo under
+# Settings → Secrets → Actions. The pre-transfer token (resource owner GavinLucas) is invalid for
+# the moved tap — re-issue before re-enabling this channel.
 #
 # workflow_dispatch lets you backfill a release that predates this workflow (supply the tag, e.g.
 # v1.9.2). The release must already exist and docker-mcp-server must be live on PyPI for that version.
@@ -206,7 +209,7 @@ jobs:
           GH_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}
         run: |
           set -euo pipefail
-          git clone "https://x-access-token:${GH_TOKEN}@github.com/GavinLucas/homebrew-tap.git" tap
+          git clone "https://x-access-token:${GH_TOKEN}@github.com/L337-org/homebrew-tap.git" tap
           cd tap
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.4}/CLAUDE.md

@@ -11,7 +11,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project
 
-`docker-mcp` is a Python MCP server (requires Python >=3.14) managed with `uv` that exposes the Docker SDK for Python as MCP tools. The entry point is the `docker_mcp` package, run with `python -m docker_mcp` or via the installed console script. It is **published to PyPI as `docker-mcp-server`** (the `docker-mcp` name was already taken) and as a container image to GHCR (`ghcr.io/l337-org/docker-mcp-server`), mirrored to Docker Hub (`gavinlucas/docker-mcp-server`) when the opt-in `DOCKERHUB_*` release secrets are configured; the import package stays `docker_mcp` and the repo stays `…/docker-mcp`. Two console scripts are installed — `docker-mcp` and `docker-mcp-server` — both targeting `docker_mcp:main`. A third channel packages the server as a **Claude Desktop Extension (`.mcpb`)** attached to each GitHub Release — see "Desktop Extension (MCPB bundle)" below. A fourth channel (**Homebrew tap**) exists in `gavinlucas/homebrew-tap` but is currently **paused** — see "Homebrew tap" below.
+`docker-mcp` is a Python MCP server (requires Python >=3.14) managed with `uv` that exposes the Docker SDK for Python as MCP tools. The entry point is the `docker_mcp` package, run with `python -m docker_mcp` or via the installed console script. It is **published to PyPI as `docker-mcp-server`** (the `docker-mcp` name was already taken) and as a container image to GHCR (`ghcr.io/l337-org/docker-mcp-server`), mirrored to Docker Hub (`gavinlucas/docker-mcp-server`) when the opt-in `DOCKERHUB_*` release secrets are configured; the import package stays `docker_mcp` and the repo stays `…/docker-mcp`. Two console scripts are installed — `docker-mcp` and `docker-mcp-server` — both targeting `docker_mcp:main`. A third channel packages the server as a **Claude Desktop Extension (`.mcpb`)** attached to each GitHub Release — see "Desktop Extension (MCPB bundle)" below. A fourth channel (**Homebrew tap**) exists in `L337-org/homebrew-tap` but is currently **paused** — see "Homebrew tap" below.
 
 The `docker` dependency is pulled with its `[ssh]` extra (paramiko), so `DOCKER_HOST=ssh://…` works through a pure-Python transport — no system `ssh` binary, identical on the host and in the container images. docker-py auto-selects paramiko for `ssh://` when present, so there is no transport code to maintain (just the `ssh://` branch in `system._connection_help`). CLI-backed tools (Compose, Buildx, Context, Scout) shell out to `docker`, which would otherwise use the *system* `ssh` — instead, `_cli.py:run_docker` detects `DOCKER_HOST=ssh://…` and routes the subprocess through a per-call local TCP proxy (`docker_mcp/tools/_ssh_proxy.py`) that opens its own paramiko connection (mirroring docker-py's `SSHHTTPAdapter` defaults) and runs `docker system dial-stdio` over it, so the CLI authenticates identically to the docker-py-backed tools with no system `ssh` binary involved (the one exception being a `ProxyCommand` in `~/.ssh/config` for bastion/jump-host setups, which paramiko runs as an external command — commonly `ssh -W %h:%p ...` — same as it would for the docker-py-backed tools).
 
@@ -155,11 +155,11 @@ An additional distribution channel alongside uvx-from-git (which is unchanged).
 
 ### Desktop Extension (MCPB bundle)
 
-A third distribution channel (alongside uvx/PyPI and the container images) for one-click install in Claude Desktop. The repo root carries the bundle sources: `manifest.json` (the MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (the bundle entry point — `from docker_mcp import main; main()`, kept at the root so `import docker_mcp` resolves however the host's managed `uv` lays out `sys.path`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + `manifest.json`/`mcpb_run.py` + `assets/`), and `assets/icon.png` (512×512). Because it's a `uv`-type bundle, the host resolves dependencies from `pyproject.toml` at install time — there's no vendored venv, so the bundle stays ~250 KB and cross-platform. `manifest.json`'s `user_config` block renders the install-dialog fields and maps them to env: `DOCKER_MCP_SERVER_HOSTS` (the single host field — `DOCKER_HOST` is deliberately **not** exposed; the bare-value shorthand keeps the simple one-daemon case a one-liner) plus the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is deliberately **not** exposed — the bundle never runs containerized). The `manifest.json` `version` is kept in step with `pyproject.toml` (`tests/test_pyproject_pins.py` asserts it), but the `mcpb` job in `.github/workflows/publish.yaml` rewrites it from the release tag at pack time so it can't drift; that job packs the `.mcpb` with `npx @anthropic-ai/mcpb` and attaches it (plus a `.sha256` recording the bare filename, so `sha256sum -c` works on downloads) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (reads the version from `pyproject.toml`, packs to `dist/` with an auto-incrementing name, never mutates `manifest.json`) — for smoke-testing a bundle in Claude Desktop; it is deliberately **not** wired into CI, which uses the workflow above. `PRIVACY.md` (a no-telemetry/no-backend statement) is referenced by the manifest's `privacy_policies` and summarized in the README. **When the manifest's tool/env surface or the bundled file set changes, update this section.**
+A third distribution channel (alongside uvx/PyPI and the container images) for one-click install in Claude Desktop. The repo root carries the bundle sources: `manifest.json` (the MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (the bundle entry point — `from docker_mcp import main; main()`, kept at the root so `import docker_mcp` resolves however the host's managed `uv` lays out `sys.path`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + `manifest.json`/`mcpb_run.py` + `assets/`), and `assets/icon.png` (512×512). Because it's a `uv`-type bundle, the host resolves dependencies from `pyproject.toml` at install time — there's no vendored venv, so the bundle stays ~250 KB and cross-platform. `manifest.json`'s `user_config` block renders the install-dialog fields and maps them to env: `DOCKER_MCP_SERVER_HOSTS` (the single host field — `DOCKER_HOST` is deliberately **not** exposed; the bare-value shorthand keeps the simple one-daemon case a one-liner) plus the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is deliberately **not** exposed — the bundle never runs containerized). The `manifest.json` `version` is kept in step with `pyproject.toml` (`tests/test_pyproject_pins.py` asserts it), but the `mcpb` job in `.github/workflows/publish.yaml` rewrites it from the release tag at pack time so it can't drift; that job packs the `.mcpb` with `npx @anthropic-ai/mcpb` and attaches it (plus a `.sha256` recording the bare filename, so `sha256sum -c` works on downloads) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (packs to `dist/` with an auto-incrementing name) — for smoke-testing a bundle in Claude Desktop. It stamps a **dev version** derived from `pyproject.toml` plus the git HEAD — `<version>-dev.<short-commit>[.dirty]` (`.dirty` = uncommitted changes at pack time) — so a local bundle is never mistaken for a release in Claude Desktop's extension list and is traceable to the commit it was built from despite having no tag; the stamp is written into `manifest.json` only for the duration of the pack and restored by an `EXIT` trap, so the working tree is left unmodified. It is deliberately **not** wired into CI, which uses the workflow above. `PRIVACY.md` (a no-telemetry/no-backend statement) is referenced by the manifest's `privacy_policies` and summarized in the README. **When the manifest's tool/env surface or the bundled file set changes, update this section.**
 
-### Homebrew tap (`gavinlucas/homebrew-tap`) — PAUSED
+### Homebrew tap (`L337-org/homebrew-tap`) — PAUSED
 
-The infrastructure exists (`scripts/docker-mcp-server.rb.tpl`, `.github/workflows/publish-homebrew.yaml`, `GavinLucas/homebrew-tap`) but the **release trigger is disabled** pending resolution of a Homebrew dylib linkage issue: pre-built PyPI wheels for `pydantic_core` lack `-headerpad_max_install_names`, so Homebrew's post-install relocation step fails to rewrite the `@rpath` ID (the binary's Mach-O header has no room for the longer absolute path). The workflow is `workflow_dispatch`-only until a fix is found. The channel is not advertised in the README. To re-enable: add `release: types: [published]` back to `publish-homebrew.yaml`'s `on:` block and re-add the Homebrew section to the README.
+The infrastructure exists (`scripts/docker-mcp-server.rb.tpl`, `.github/workflows/publish-homebrew.yaml`, `L337-org/homebrew-tap`) but the **release trigger is disabled** pending resolution of a Homebrew dylib linkage issue: pre-built PyPI wheels for `pydantic_core` lack `-headerpad_max_install_names`, so Homebrew's post-install relocation step fails to rewrite the `@rpath` ID (the binary's Mach-O header has no room for the longer absolute path). The workflow is `workflow_dispatch`-only until a fix is found. The channel is not advertised in the README. To re-enable: add `release: types: [published]` back to `publish-homebrew.yaml`'s `on:` block and re-add the Homebrew section to the README.
 
 ### MCP Registry (`server.json`)
 
@@ -247,12 +247,18 @@ def mcp_example(name: str):
     """
     Say hello to someone by name.
 
-    args: name - The name to say hello to
+    Use it for a single greeting; use `mcp_example_bulk` to greet many names in one call.
+    Read-only, no side effects.
+
+    args: name - The name to say hello to (any non-empty string)
     returns: str - The greeting
     """
     return f"Hello, {name}!"
 ```
 
+(`mcp_example` and `mcp_example_bulk` are illustrative only and exist nowhere in the repo — in a
+real docstring the discriminator must name an actually-registered sibling tool.)
+
 - One-line summary sentence, then a blank line
 - `args:` section lists each parameter as `name - description`. Do **not** repeat the parameter's
   type — the type annotation already lands in the tool's `inputSchema`, which the client sees
@@ -262,19 +268,74 @@ def mcp_example(name: str):
 - Keep descriptions terse: state every functional fact (defaults, accepted formats/values, return
   keys, important caveats) but cut redundancy and verbose phrasing. The docstring is the entire
   tool `description` the client pays tokens for on every session.
-- **A one-line summary + bare `args`/`returns` is not enough for any tool with non-obvious
-  behavior.** If the tool has side effects, preconditions, a non-obvious failure mode, or overlaps
-  with another tool a caller could reach for instead, add a short paragraph (2-5 sentences,
-  between the summary and `args:`) covering: when to use it vs. the alternative, side
-  effects/preconditions, and concrete parameter formats/values — not just restating the signature.
-  This directly maps to what a low-scoring tool is missing on Glama's per-tool quality rubric
-  (`Behavior`, `Usage Guidelines`, `Parameters` sub-scores) — see [[project_glama_docstring_quality]]
-  in memory for the three rounds of cleanup (#97, the 2.0 rename, #129) this has already taken to
-  chase down thin docstrings written without this paragraph. **Write it this way the first time a
-  tool is added or its behavior changes** — don't wait for a future Glama pass to catch it. Verify
-  every factual claim in that paragraph against the live docker-py docs / Engine API spec per the
-  Docker SDK Policy below — an unverified claim about identifier semantics (e.g. "name or id" for a
-  resource actually addressed by name only) is exactly the kind of thing PR review catches late.
+
+#### Docstring quality standard
+
+Tool descriptions are scored externally on Glama's six-dimension Tool Definition Quality rubric
+(<https://glama.ai/mcp/servers/L337-org/docker-mcp/score>): Purpose Clarity 25%, Usage Guidelines
+20%, Behavioral Transparency 20%, Parameter Semantics 15%, Conciseness & Structure 10%, Contextual
+Completeness 10%. Four rounds of cleanup (#97, the 2.0 rename, #129, and the 2026-07 bottom-20
+pass — see [[project_glama_docstring_quality]] in memory) all chased the same failure: docstrings
+that state *what* the tool does but never *when to use it over its neighbors*, plus `args:` /
+`returns:` lines that merely restate the schema. The standard below exists to prevent a fifth
+round. It applies to **every `@tool()` docstring added or modified in a PR** (a ratchet — untouched
+legacy docstrings are cleaned opportunistically, not churned):
+
+1. **Summary = specific verb + resource**, with the distinguishing trait up front when a sibling
+   could be confused ("Send a signal to a running container (default SIGKILL — immediate, no
+   graceful shutdown)").
+2. **A usage-guidance paragraph (1–5 sentences between the summary and `args:`) is required for
+   every tool, not just complex ones.** Every tool in a 150+-tool server has neighbors. It must
+   carry:
+   - at least one *discriminator* naming the sibling tool(s) an agent could reach for instead and
+     when to prefer which (`container_stop` vs `container_kill` vs `container_restart`;
+     `service_ps` vs `stack_ps` vs the `service-tasks://` resource);
+   - preconditions in prose (swarm manager only, plugin required, container must be
+     running/paused);
+   - side effects and destructive/irreversible behavior in prose — the scorer explicitly discounts
+     `readOnlyHint`/`destructiveHint` annotations as a substitute for description text;
+   - for CLI-backed tools, the error style ("does not raise on a non-zero CLI exit — inspect
+     `returncode`/`stderr`" vs "raises `RuntimeError` on CLI failure"). Don't overpromise "never
+     raises" — a missing binary/plugin or a subprocess timeout still raises even in action tools.
+   Scale it to the tool: a trivial read-only tool needs one discriminator sentence, not five.
+3. **Every `args:` line adds semantics the schema cannot carry**: format, accepted values/ranges,
+   defaults, units, and interactions with other parameters. A line that echoes the parameter name
+   ("name - The volume name") scores 2/5 on the rubric — say what makes a value valid or how it
+   behaves ("name - The volume name (volumes have no separate id)"). Canonical shared-param
+   prefixes in `tests/test_naming.py` still apply — append tool-specific detail after the
+   canonical prefix rather than rewording it.
+4. **`returns:` names the shape, not just the type.** There is no output schema, so this line is
+   all an agent gets. For computed or partial returns, name the load-bearing keys (`{"Titles",
+   "Processes"}`; `{"LayersSize", "Images", "Containers", "Volumes", "BuildCache"}`). For a full
+   engine inspect document, do NOT enumerate an arbitrary subset of its hundreds of keys — say
+   what document it is ("full inspect payload, as `docker inspect`"), optionally plus the one or
+   two keys a caller typically wants from it. What stays banned is the shapeless "dict - The X's
+   attrs", which identifies neither form.
+5. **Front-load and stay terse** — the description is paid for in every session's context; every
+   sentence must earn its place.
+6. **Verify every factual claim** against the live docker-py docs / Engine API spec per the Docker
+   SDK Policy below — an unverified claim about identifier semantics (e.g. "name or id" for a
+   resource actually addressed by name only) is exactly the kind of thing PR review catches late.
+
+**Division of labor across the three discovery layers.** For a lazy-loading client (e.g. Claude
+Code), tool schemas load on demand; what is always in context is only (1) the **tool names** and
+(2) the **`instructions` router**. Docstrings are layer (3): a deferred tool cannot be invoked
+without fetching its definition, so the docstring is guaranteed to be read at the moment of
+choice — typically side by side with the sibling definitions the same search returned, which is
+where the item-2 discriminators do their work. Consequences: pre-fetch discoverability belongs to
+the naming convention and the router, not the docstring (don't pad docstrings with search
+keywords); a *cross-domain* selection caveat that must be visible before any schema is fetched
+(e.g. "prefer `dest_path` for large output") goes in the router's caveat list (`_DOMAIN_BLURBS` /
+`build_instructions()` — see "Server singleton" above), while *sibling-level* discriminators stay
+in docstrings and are never duplicated into the router; and sibling references must use the exact
+tool name (`container_kill`, never "the kill tool") — lazy clients keyword-search descriptions, so
+exact names double as retrieval anchors that surface the right alternative even when the agent
+searched for the wrong one.
+
+Self-check before opening the PR: read the docstring as an agent holding 150+ tool names and
+nothing else — could you pick this tool over its neighbors and call it correctly on the first try?
+**Write it this way the first time a tool is added or its behavior changes** — don't wait for a
+future Glama pass to catch it.
 
 ### MCP resources
 

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-mcp-server
-Version: 2.1.2
+Version: 2.1.4
 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
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 # docker-mcp-server
 
-[![docker-mcp MCP server](https://glama.ai/mcp/servers/GavinLucas/docker-mcp/badges/score.svg)](https://glama.ai/mcp/servers/GavinLucas/docker-mcp)
+[![docker-mcp MCP server](https://glama.ai/mcp/servers/L337-org/docker-mcp/badges/score.svg)](https://glama.ai/mcp/servers/L337-org/docker-mcp)
 
 <!-- mcp-name: io.github.L337-org/docker-mcp-server -->
 
@@ -411,8 +411,8 @@ Connecting this server to an AI agent grants it the same level of access as a lo
 | Docker Hub (container) | [gavinlucas/docker-mcp-server](https://hub.docker.com/r/gavinlucas/docker-mcp-server) |
 | Desktop Extension (.mcpb) | [GitHub Releases](https://github.com/L337-org/docker-mcp/releases) |
 | Official MCP Registry | [io.github.L337-org/docker-mcp-server](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.L337-org%2Fdocker-mcp-server/versions) |
-| Glama | [docker-mcp-server](https://glama.ai/mcp/servers/GavinLucas/docker-mcp) |
-| mcp.so | [docker-mcp-server](https://mcp.so/server/docker-mcp-server/GavinLucas) |
+| Glama | [docker-mcp-server](https://glama.ai/mcp/servers/L337-org/docker-mcp) |
+| mcp.so | [docker-mcp-server](https://mcp.so/servers/docker-1ae67d) |
 | awesome-mcp-servers | [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers#cloud-platforms) |
 
 ## Privacy Policy

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.4}/README.md

@@ -2,7 +2,7 @@
 
 # docker-mcp-server
 
-[![docker-mcp MCP server](https://glama.ai/mcp/servers/GavinLucas/docker-mcp/badges/score.svg)](https://glama.ai/mcp/servers/GavinLucas/docker-mcp)
+[![docker-mcp MCP server](https://glama.ai/mcp/servers/L337-org/docker-mcp/badges/score.svg)](https://glama.ai/mcp/servers/L337-org/docker-mcp)
 
 <!-- mcp-name: io.github.L337-org/docker-mcp-server -->
 
@@ -383,8 +383,8 @@ Connecting this server to an AI agent grants it the same level of access as a lo
 | Docker Hub (container) | [gavinlucas/docker-mcp-server](https://hub.docker.com/r/gavinlucas/docker-mcp-server) |
 | Desktop Extension (.mcpb) | [GitHub Releases](https://github.com/L337-org/docker-mcp/releases) |
 | Official MCP Registry | [io.github.L337-org/docker-mcp-server](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.L337-org%2Fdocker-mcp-server/versions) |
-| Glama | [docker-mcp-server](https://glama.ai/mcp/servers/GavinLucas/docker-mcp) |
-| mcp.so | [docker-mcp-server](https://mcp.so/server/docker-mcp-server/GavinLucas) |
+| Glama | [docker-mcp-server](https://glama.ai/mcp/servers/L337-org/docker-mcp) |
+| mcp.so | [docker-mcp-server](https://mcp.so/servers/docker-1ae67d) |
 | awesome-mcp-servers | [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers#cloud-platforms) |
 
 ## Privacy Policy

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.4}/docker_mcp/tools/buildx.py

@@ -178,6 +178,10 @@ def buildx_bake(
     """
     Build multiple targets defined in a bake file (HCL, JSON, or compose).
 
+    Use it for multi-target builds declared in `docker-bake.hcl`/compose files; for a single
+    Dockerfile target use `buildx_build`.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
+
     args:
         targets - Bake targets to build (default: the `default` group)
         files - Bake file paths (`-f`, repeatable)
@@ -273,7 +277,9 @@ def buildx_imagetools_create(
     Create a manifest list / OCI image index from existing per-platform tags.
 
     Replaces `docker manifest create` + `docker manifest push` — builds the index and pushes it in
-    one operation. Source tags must already be pushed; this only stitches them together.
+    one operation. Source tags must already be pushed; this only stitches them together. Verify
+    the result with `buildx_imagetools_inspect`.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
 
     args:
         target - Tag for the new manifest list (`-t`)
@@ -311,6 +317,10 @@ def buildx_list(host: str | None = None) -> list:
     """
     List builder instances.
 
+    Machine-parsed view of every builder; use `buildx_inspect` for one builder's human-readable
+    detail and `buildx_use` to switch the default.
+    Raises RuntimeError if the CLI call fails.
+
     returns: list - One dict per builder (parsed from `--format '{{json .}}'`).
                     If the captured stdout was truncated by MAX_CLI_OUTPUT_BYTES the
                     last (likely partial) record is dropped before parsing.
@@ -346,8 +356,10 @@ def buildx_history_inspect(ref: str = "", builder: str | None = None, host: str
     """
     Inspect a single build record by ref, parsed from `--format json`.
 
-    Returns the full record for one build — duration, materials, attestations, error (if any) — for
-    debugging a failed or slow build found via `buildx_history_list`. Requires buildx >= v0.13.
+    Returns the full record for one build — duration, materials, attestations, error (if any) —
+    for debugging a failed or slow build found via `buildx_history_list`. Requires buildx >=
+    v0.13.
+    Raises RuntimeError if the CLI call fails.
 
     args:
         ref - Build record ref. Pass the `ref` field from `buildx_history_list` directly — it
@@ -386,6 +398,10 @@ def buildx_inspect(name: str | None = None, bootstrap: bool = False, host: str |
     """
     Inspect a builder instance.
 
+    Human-readable detail (driver, status, supported platforms) for one builder; `buildx_list`
+    returns machine-parsed JSON for all builders.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
+
     args:
         name - Builder name (defaults to the active builder)
         bootstrap - Boot the builder if it isn't already running
@@ -405,10 +421,12 @@ def buildx_du(builder: str | None = None, host: str | None = None) -> list:
     """
     Report BuildKit cache disk usage as a list of records.
 
-    A large cache can easily generate more output than MAX_CLI_OUTPUT_BYTES; if that
-    happens the captured stdout is truncated and this tool drops the final (partial)
-    record before parsing. For an exhaustive accounting on a busy builder, run
-    `docker buildx du --format '{{json .}}'` on the host directly.
+    A large cache can easily generate more output than MAX_CLI_OUTPUT_BYTES; if that happens the
+    captured stdout is truncated and this tool drops the final (partial) record before parsing.
+    For an exhaustive accounting on a busy builder, run `docker buildx du --format '{{json .}}'`
+    on the host directly. Reclaim the cache with `buildx_prune` (`system_df` covers daemon-side
+    disk, not builder cache).
+    Raises RuntimeError if the CLI call fails.
 
     args: builder - Override the active builder
     returns: list - One dict per cache record (parsed from `--format '{{json .}}'`)
@@ -477,7 +495,13 @@ def buildx_create(
     host: str | None = None,
 ) -> dict:
     """
-    Create a new builder instance.
+    Create a new BuildKit builder instance.
+
+    Needed when the default `docker` driver falls short: multi-platform builds and cache export
+    require a `docker-container` (or `kubernetes`/`remote`) builder. Pass `use=True` to make it
+    the default for later `buildx_build` calls (else switch with `buildx_use`); `bootstrap=True`
+    starts the builder now rather than on first build.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
 
     args:
         name - Name for the new builder (defaults to a generated name)
@@ -551,6 +575,10 @@ def buildx_remove(
     """
     Remove a builder instance.
 
+    Deletes a builder made by `buildx_create`, including its build cache unless keep_state=True;
+    use `buildx_prune` to reclaim cache while keeping the builder.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
+
     args:
         name - Builder name to remove (mutually exclusive with `all_inactive`)
         all_inactive - Remove every inactive builder