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

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/.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).
 
@@ -91,9 +91,9 @@ An additional distribution channel alongside the uvx-from-git install (unchanged
 
 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.
 
-### 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,63 @@ 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 dict/list returns the load-bearing keys
+   must be listed (`{"Titles", "Processes"}`); flag a bare "dict - The X's attrs" on a
+   new/modified tool.
+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.3}/.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.3}/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).
 
@@ -157,9 +157,9 @@ An additional distribution channel alongside uvx-from-git (which is unchanged).
 
 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.**
 
-### 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,70 @@ 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 dict/list returns name the load-bearing keys (`{"Titles", "Processes"}`;
+   `{"LayersSize", "Images", "Containers", "Volumes", "BuildCache"}`), never just "the attrs".
+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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-mcp-server
-Version: 2.1.2
+Version: 2.1.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
@@ -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,7 +411,7 @@ 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) |
+| Glama | [docker-mcp-server](https://glama.ai/mcp/servers/L337-org/docker-mcp) |
 | mcp.so | [docker-mcp-server](https://mcp.so/server/docker-mcp-server/GavinLucas) |
 | awesome-mcp-servers | [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers#cloud-platforms) |
 

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/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,7 +383,7 @@ 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) |
+| Glama | [docker-mcp-server](https://glama.ai/mcp/servers/L337-org/docker-mcp) |
 | mcp.so | [docker-mcp-server](https://mcp.so/server/docker-mcp-server/GavinLucas) |
 | awesome-mcp-servers | [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers#cloud-platforms) |
 

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

@@ -477,7 +477,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)

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/compose.py

@@ -538,6 +538,10 @@ def compose_images(
     """
     List the images used by a compose project's services, parsed from `--format json`.
 
+    Answers "what image and tag does each service container actually run?" — the containers must
+    exist (`compose_up`/`compose_create` first). Use `compose_ps` for container state and
+    `image_list` for daemon-wide images. Raises RuntimeError if the CLI call fails.
+
     args:
         project_dir - Dir with the compose file (default: server cwd)
         files - Explicit compose file paths (repeatable, `-f`)
@@ -750,7 +754,12 @@ def compose_pause(
     host: str | None = None,
 ) -> dict:
     """
-    Pause the containers of a compose project (freezes their processes).
+    Pause the containers of a compose project (freezes their processes in place).
+
+    Paused containers stop consuming CPU but keep memory, network endpoints, and state; resume
+    with `compose_unpause`. To actually stop containers (each one's configured stop signal, freeing
+    resources) use `compose_stop`; to stop and delete them use `compose_down`. Does not raise on a
+    non-zero CLI exit — inspect `returncode`/`stderr` in the result.
 
     args:
         services - Restrict to these services (default: all)

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/configs.py

@@ -38,10 +38,14 @@ def config_create(
 @tool()
 def config_inspect(id_or_name: str, host: str | None = None) -> dict:
     """
-    Get a swarm config by id or name.
+    Get a swarm config's full inspect payload by id or name.
+
+    Requires a swarm manager. Unlike a secret, a config's payload IS readable after creation:
+    `Spec.Data` in the result holds the base64-encoded contents. Use `config_list` to enumerate
+    configs; use this to read one config's contents and metadata.
 
     args: id_or_name - The config id or name
-    returns: dict - The config's attrs
+    returns: dict - The config's attrs (ID, CreatedAt, UpdatedAt, Spec{Name, Labels, Data base64})
     """
     return _get_client(host).configs.get(id_or_name).attrs
 

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/containers.py

@@ -245,12 +245,18 @@ def container_start(id_or_name: str, host: str | None = None) -> dict:
 @tool()
 def container_stop(id_or_name: str, stop_timeout_seconds: int = 10, host: str | None = None) -> dict:
     """
-    Stop a container.
+    Gracefully stop a running container (its configured stop signal, then SIGKILL after a timeout).
+
+    Prefer this over `container_kill` for a clean shutdown: the main process receives the
+    container's stop signal (`STOPSIGNAL`, default SIGTERM) and has stop_timeout_seconds to exit
+    before the daemon force-kills it. Use `container_restart` to stop and start again in one call,
+    or `container_pause` to freeze processes without stopping. When the server runs containerized
+    it refuses to stop its own container.
 
     args:
         id_or_name - The container id or name
-        stop_timeout_seconds - Seconds to wait for graceful stop before SIGKILL
-    returns: dict - The container's attrs after stop
+        stop_timeout_seconds - Seconds between the stop signal and SIGKILL (default 10)
+    returns: dict - The container's attrs after the stop (exit code under State.ExitCode)
     """
     container = _get_client(host).containers.get(id_or_name)
     guard_not_self(container, host=host)
@@ -279,12 +285,18 @@ def container_restart(id_or_name: str, stop_timeout_seconds: int = 10, host: str
 @tool()
 def container_kill(id_or_name: str, signal: str | None = None, host: str | None = None) -> dict:
     """
-    Send a signal to a container.
+    Send a signal to a running container (default SIGKILL — immediate, no graceful shutdown).
+
+    Use it to force-kill a container that ignores `container_stop`, or with `signal` to poke a
+    process without stopping it (e.g. SIGHUP for a config reload). For a normal shutdown prefer
+    `container_stop`, which sends the container's configured stop signal first. Fails with a
+    conflict error if the container is not running. When the server runs containerized it refuses
+    to signal its own container.
 
     args:
         id_or_name - The container id or name
-        signal - Signal to send (defaults to SIGKILL)
-    returns: dict - The container's attrs after kill
+        signal - Signal name or number as a string (e.g. "SIGHUP", "9"); default SIGKILL
+    returns: dict - The container's attrs after the signal
     """
     container = _get_client(host).containers.get(id_or_name)
     guard_not_self(container, host=host)
@@ -316,10 +328,13 @@ def container_pause(id_or_name: str, host: str | None = None) -> dict:
 @tool()
 def container_unpause(id_or_name: str, host: str | None = None) -> dict:
     """
-    Resume all processes in a paused container.
+    Resume all processes in a paused container (the reverse of `container_pause`).
+
+    Only valid on a paused container — it fails if the container is merely stopped; use
+    `container_start` for stopped containers. Processes continue from where they were frozen.
 
     args: id_or_name - The container id or name
-    returns: dict - The container's attrs after unpause
+    returns: dict - The container's attrs after unpause (State.Paused becomes false)
     """
     container = _get_client(host).containers.get(id_or_name)
     container.unpause()
@@ -429,10 +444,15 @@ def container_logs(
 @tool()
 def container_stats(id_or_name: str, host: str | None = None) -> dict:
     """
-    Get a single resource usage stats snapshot for a container.
+    Get one point-in-time resource-usage snapshot for a container (non-streaming).
+
+    Returns the raw engine stats payload; CPU percent must be computed from the delta between
+    `cpu_stats` and `precpu_stats`. For a pre-computed human-readable summary prefer the
+    `docker-stats://{id_or_name}` resource; for a process listing use `container_top`.
 
     args: id_or_name - The container id or name
-    returns: dict - Decoded stats snapshot
+    returns: dict - Engine stats payload (read, cpu_stats, precpu_stats, memory_stats, networks,
+        pids_stats, ...)
     """
     container = _get_client(host).containers.get(id_or_name)
     # `decode` is only valid with stream=True; a one-shot stream=False read already returns a dict.
@@ -530,12 +550,16 @@ def _read_stats_summary(id_or_name: str, host: str | None = None) -> dict:
 @tool()
 def container_top(id_or_name: str, ps_args: str | None = None, host: str | None = None) -> dict:
     """
-    Show the running processes inside a container.
+    List the processes running inside a container (the daemon runs `ps` on the host).
+
+    Works on any running container without executing anything in it, so it needs no shell or `ps`
+    binary in the image — unlike `container_exec` with `ps`. Use `container_stats` for resource
+    usage rather than process lists. Fails if the container is not running.
 
     args:
         id_or_name - The container id or name
-        ps_args - Arguments to pass to ps inside the container
-    returns: dict - Output of the top command
+        ps_args - Extra ps arguments (e.g. "aux"); default is the daemon's standard ps invocation
+    returns: dict - {"Titles": [ps column names], "Processes": [[one row of values per process]]}
     """
     container = _get_client(host).containers.get(id_or_name)
     return cast(dict, container.top(ps_args=ps_args))
@@ -649,10 +673,14 @@ def container_commit(
 @tool()
 def container_diff(id_or_name: str, host: str | None = None) -> list:
     """
-    Inspect changes on a container's filesystem.
+    List filesystem changes a container has made relative to its image.
+
+    Use it to audit what a container wrote before `container_commit` or `container_archive_get`,
+    or to debug unexpected writes. Only the writable container layer is compared — files in
+    volumes and bind mounts never show up.
 
     args: id_or_name - The container id or name
-    returns: list - Filesystem changes since the image was created
+    returns: list - Dicts of {"Path", "Kind"}; Kind 0=modified, 1=added, 2=deleted
     """
     container = _get_client(host).containers.get(id_or_name)
     return container.diff()
@@ -661,12 +689,16 @@ def container_diff(id_or_name: str, host: str | None = None) -> list:
 @tool()
 def container_rename(id_or_name: str, name: str, host: str | None = None) -> dict:
     """
-    Rename a container.
+    Rename a container in place; its id, state, and configuration are unchanged.
+
+    Use it to free up or claim a container name (names are unique per daemon) — e.g. before
+    starting a replacement under the old name. Fails with a conflict error if the new name is
+    already taken. Not related to `image_tag`, which names images.
 
     args:
         id_or_name - The container id or name
-        name - The new name
-    returns: dict - The container's attrs after rename
+        name - The new name; must not be in use by any other container
+    returns: dict - The container's attrs after the rename
     """
     container = _get_client(host).containers.get(id_or_name)
     container.rename(name)

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/networks.py

@@ -24,19 +24,24 @@ def network_create(
     """
     Create a network.
 
+    The daemon default driver is `bridge` (single-host); use `overlay` for swarm-wide networks.
+    Creating a network attaches nothing — connect containers afterwards with `network_connect` or
+    at start via `container_run(network=...)`. Created networks are stamped with provenance labels
+    (find them later via `network_list(managed_only=True)`).
+
     args:
         name - The name of the network
-        driver - Driver name (e.g. bridge, overlay)
-        options - Driver-specific options
-        ipam - IPAM configuration as a dict
-        check_duplicate - Reject creation if a duplicate name exists
+        driver - Driver name (daemon default `bridge`; `overlay` for swarm scope)
+        options - Driver-specific options dict
+        ipam - IPAM configuration as a dict (engine shape: {"Driver", "Config": [{"Subnet", "Gateway", ...}]})
+        check_duplicate - Reject creation if a duplicate name exists (deprecated: recent daemons always check)
         internal - Restrict external access
         labels - Labels to set on the network
         enable_ipv6 - Enable IPv6 networking
-        attachable - Allow standalone containers to attach (swarm)
-        scope - Network scope (local, global, swarm)
+        attachable - Allow standalone containers to attach (swarm overlay networks)
+        scope - Network scope: "local", "global", or "swarm"
         ingress - Make this an ingress network for swarm routing-mesh
-    returns: dict - The created network's attrs
+    returns: dict - The created network's attrs (Id, Name, Driver, Scope, IPAM)
     """
     kwargs: dict = {
         "internal": internal,
@@ -187,10 +192,14 @@ def network_disconnect(id_or_name: str, container: str, force: bool = False, hos
     """
     Disconnect a container from a network.
 
+    The container keeps running with its other network attachments; only this endpoint is removed
+    (the reverse of `network_connect`). A network with connected containers cannot be deleted, so
+    disconnect them before `network_remove`.
+
     args:
         id_or_name - The network id or name
-        container - The container id or name
-        force - Force disconnect
+        container - The container id or name to disconnect
+        force - Force the disconnect; use to clear a stale endpoint (e.g. from a deleted container)
     returns: bool - True after the container is disconnected
     """
     network = _get_client(host).networks.get(id_or_name)

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/nodes.py

@@ -11,10 +11,14 @@ from docker_mcp.tools.system import _get_client
 @tool()
 def node_inspect(id_or_name: str, host: str | None = None) -> dict:
     """
-    Get a swarm node by id or name.
+    Get a swarm node's full inspect payload by id or name.
 
-    args: id_or_name - The node id or name
-    returns: dict - The node's attrs
+    Must run against a swarm manager. Shows role, availability, status, and manager reachability —
+    use `node_list` to enumerate nodes first, or the `docker://nodes` resource for a fleet
+    summary; `service_ps(filters={"node": ...})` shows what a service runs on one node.
+
+    args: id_or_name - The node id or hostname (as shown by `node_list`)
+    returns: dict - The node's attrs (Spec{Role, Availability}, Status, ManagerStatus for managers)
     """
     return _get_client(host).nodes.get(id_or_name).attrs
 

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/plugins.py

@@ -42,9 +42,14 @@ def plugin_install(remote: str, local_name: str | None = None, host: str | None
 @tool()
 def plugin_list(host: str | None = None) -> list:
     """
-    List installed plugins.
+    List installed engine plugins with their full attrs.
 
-    returns: list - A list of plugin attrs dicts
+    Covers managed engine plugins (volume/network/logging drivers installed via `plugin_install`)
+    — not docker CLI plugins such as compose, buildx, or scout. Use it to find exact plugin names
+    for `plugin_inspect`/`plugin_enable`/`plugin_disable`/`plugin_remove`; the `Enabled` key shows
+    each plugin's state.
+
+    returns: list - One attrs dict per installed plugin (Id, Name, Enabled, Settings, Config)
     """
     return [p.attrs for p in _get_client(host).plugins.list()]
 
@@ -110,11 +115,15 @@ def plugin_enable(name: str, timeout_seconds: int = 0, host: str | None = None)
 @tool()
 def plugin_remove(name: str, force: bool = False, host: str | None = None) -> bool:
     """
-    Remove a plugin.
+    Uninstall an engine plugin from the daemon.
+
+    Permanent removal — to deactivate but keep a plugin installed use `plugin_disable` instead. An
+    enabled plugin must be disabled first unless `force=True`. Plugin names come from
+    `plugin_list`.
 
     args:
-        name - The plugin name
-        force - Force removal even if the plugin is enabled
+        name - The plugin name (e.g. "vieux/sshfs:latest")
+        force - Remove even if the plugin is enabled (default False)
     returns: bool - True after removal
     """
     _get_client(host).plugins.get(name).remove(force=force)

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/secrets.py

@@ -11,14 +11,20 @@ def secret_create(
     name: str, data: bytes, labels: dict | None = None, driver: dict | None = None, host: str | None = None
 ) -> dict:
     """
-    Create a swarm secret.
+    Create a swarm secret; requires a swarm manager.
+
+    Write-once: the payload can never be read back through the API (`secret_inspect` returns
+    metadata only) and cannot be changed later — to rotate, create a new secret and update the
+    consuming services, keeping your own copy of the value. For non-sensitive data that should
+    stay readable, use `config_create` instead. Created secrets are stamped with provenance
+    labels.
 
     args:
-        name - The name of the secret
-        data - The secret payload
+        name - Name for the secret (unique within the swarm)
+        data - The secret payload (max 500 KB; must be empty when driver is set)
         labels - Labels to set on the secret
-        driver - Optional secret driver configuration
-    returns: dict - The created secret's attrs
+        driver - Optional secret-driver config for values held in an external store
+    returns: dict - The created secret's attrs (ID and Spec metadata; never the payload)
     """
     kwargs: dict = {
         "name": name,

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/services.py

@@ -174,12 +174,18 @@ def service_remove(id_or_name: str, host: str | None = None) -> bool:
 @tool()
 def service_ps(id_or_name: str, filters: dict | None = None, host: str | None = None) -> list:
     """
-    List the tasks of a swarm service.
+    List a swarm service's tasks (per-replica scheduling units), like `docker service ps`.
+
+    Shows where replicas run and why they fail: each task carries `Status`
+    (State/Message/ContainerStatus), `DesiredState`, `NodeID`, and `Slot`. Prefer this over
+    `container_list` for services (tasks may run on other nodes), `stack_ps` for a whole stack,
+    and the `service-tasks://{id_or_name}` resource for a computed rollout summary. Requires a
+    swarm manager.
 
     args:
         id_or_name - The service id or name
-        filters - Filter by id, name, node, label, desired-state
-    returns: list - A list of task dicts
+        filters - Filter dict; keys: id, name, node, label, desired-state (running|shutdown|accepted)
+    returns: list - Task dicts (ID, Slot, NodeID, Status, DesiredState, Spec)
     """
     service = _get_client(host).services.get(id_or_name)
     return service.tasks(filters=filters)

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/system.py

@@ -261,9 +261,15 @@ def system_info(host: str | None = None) -> dict:
 @tool()
 def system_df(host: str | None = None) -> dict:
     """
-    Return Docker disk usage information.
+    Summarize Docker disk usage: layer storage plus per-object sizes for images, containers, volumes, build cache.
 
-    returns: dict - Data usage information for images, containers and volumes
+    Equivalent to `docker system df`. Use it to find what to reclaim before `image_prune` /
+    `container_prune` / `volume_prune` / `buildx_prune`; use `system_info` for daemon config and
+    counts rather than sizes. The reply enumerates every object on the daemon, so expect a large
+    payload on busy hosts.
+
+    returns: dict - {"LayersSize", "Images", "Containers", "Volumes", "BuildCache"} with per-object
+        size fields
     """
     return _get_client(host).df()
 

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/docker_mcp/tools/volumes.py

@@ -42,10 +42,14 @@ def volume_create(
 @tool()
 def volume_inspect(name: str, host: str | None = None) -> dict:
     """
-    Get a volume by name.
+    Get a volume's full inspect payload by name.
 
-    args: name - The volume name
-    returns: dict - The volume's attrs
+    Use it after `volume_list` to see a volume's on-disk location, driver, and labels — e.g.
+    before a backup or `volume_remove`. Volumes are addressed purely by name; they have no
+    separate id.
+
+    args: name - The volume name (volumes have no ids)
+    returns: dict - The volume's attrs (Name, Driver, Mountpoint, CreatedAt, Labels, Options, Scope)
     """
     return _get_client(host).volumes.get(name).attrs
 

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.4",
   "name": "docker-mcp-server",
   "display_name": "Docker MCP Server",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "Manage Docker through the Docker SDK for Python and the docker CLI: containers, images, networks, volumes, Compose, Swarm, Buildx, Scout, and OCI registries, exposed as MCP tools.",
   "long_description": "Manage one or more Docker daemons through your AI agent — containers, images, networks, volumes, Compose, Swarm, Buildx, Scout, and OCI registries, exposed as MCP tools.\n\nDiscovery is automatic for your local socket with no configuration required. Or point it at additional remote daemons over TCP, TLS, or SSH (and mark any of them read-only to monitor without the risk of accidental changes). It also surfaces logs and stats as resources for triage. Read-only / no-destructive / disabled-domain switches let you register a restricted tool surface.\n\nAnswer questions like: ‘why did my local container crash?’, ‘is my production system under memory pressure?’, ‘what differences are there between my staging and production systems?’\n\nRuns entirely on your machine and sends no telemetry — see the Privacy Policy.",
   "author": {

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docker-mcp-server"
-version = "2.1.2"
+version = "2.1.3"
 description = "MCP server for managing Docker resources via the Docker SDK for Python"
 readme = "README.md"
 license = "MIT"

{docker_mcp_server-2.1.2 → docker_mcp_server-2.1.3}/uv.lock

@@ -282,7 +282,7 @@ ssh = [
 
 [[package]]
 name = "docker-mcp-server"
-version = "2.1.2"
+version = "2.1.3"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography", marker = "platform_machine == 'x86_64' and sys_platform == 'darwin'" },