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

docker_mcp_server-2.1.3/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -c \"import json,sys,os; d=json.load(sys.stdin); fp=(d.get('tool_input') or {}).get('file_path',''); root=os.environ.get('CLAUDE_PROJECT_DIR') or os.getcwd(); print(json.dumps({'hookSpecificOutput':{'hookEventName':'PostToolUse','additionalContext':'You edited CLAUDE.md \\u2014 MIRROR RULE: make the equivalent change in .github/copilot-instructions.md (it drives GitHub Copilot review of every PR). Treat the change as incomplete until both files reflect it.'}})) if fp and os.path.normpath(os.path.join(root, fp)) == os.path.normpath(os.path.join(root, 'CLAUDE.md')) else None\""
+          }
+        ]
+      }
+    ]
+  }
+}

{docker_mcp_server-2.1.1 → docker_mcp_server-2.1.3}/.github/PULL_REQUEST_TEMPLATE.md

@@ -9,6 +9,6 @@
 ## Checklist
 
 - [ ] `uv run pytest -v`, `uv run ruff check .`, `uv run ruff format --check .`, and `uv run pyright` all pass locally
-- [ ] If this adds or changes a tool: the ["Checklist when adding a new tool module"](https://github.com/GavinLucas/docker-mcp/blob/main/CONTRIBUTING.md#checklist-when-adding-a-new-tool-module) in `CONTRIBUTING.md` has been followed (tests, prompts, resources, README, naming convention)
+- [ ] If this adds or changes a tool: the ["Checklist when adding a new tool module"](https://github.com/L337-org/docker-mcp/blob/main/CONTRIBUTING.md#checklist-when-adding-a-new-tool-module) in `CONTRIBUTING.md` has been followed (tests, prompts, resources, README, naming convention)
 - [ ] If this changes project structure, conventions, env vars, or the tool/prompt/resource surface: both `CLAUDE.md` and `.github/copilot-instructions.md` are updated (see the mirror rule at the top of `CLAUDE.md`)
 - [ ] If this changes a dependency: `uv.lock` is updated (`uv lock`) and committed alongside `pyproject.toml`

{docker_mcp_server-2.1.1 → 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/gavinlucas/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,17 +91,17 @@ 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`)
 
-A discovery listing in the official MCP Registry (`registry.modelcontextprotocol.io`), which stores only metadata pointing at the existing artifacts. `server.json` (repo root, name `io.github.GavinLucas/docker-mcp-server`) declares three package types — `pypi`, `oci` (GHCR image), `mcpb` (release `.mcpb`). The `registry` job in `.github/workflows/publish.yaml` stamps the tag version + the published `.mcpb`'s `fileSha256` into `server.json`, authenticates via GitHub OIDC (`id-token: write`, no secret), and runs `mcp-publisher publish`. Ownership is verified per package against `server.json`'s `name`, so three markers must equal it: the `<!-- mcp-name: … -->` comment in `README.md` (PyPI), the `io.modelcontextprotocol.server.name` image label in the `images` job (OCI), and the `.mcpb` URL + hash (MCPB). Keep them in sync with `server.json`'s `name`.
+A discovery listing in the official MCP Registry (`registry.modelcontextprotocol.io`), which stores only metadata pointing at the existing artifacts. `server.json` (repo root, name `io.github.L337-org/docker-mcp-server`) declares three package types — `pypi`, `oci` (GHCR image), `mcpb` (release `.mcpb`). The `registry` job in `.github/workflows/publish.yaml` stamps the tag version + the published `.mcpb`'s `fileSha256` into `server.json`, authenticates via GitHub OIDC (`id-token: write`, no secret), and runs `mcp-publisher publish`. Ownership is verified per package against `server.json`'s `name`, so three markers must equal it: the `<!-- mcp-name: … -->` comment in `README.md` (PyPI), the `io.modelcontextprotocol.server.name` image label in the `images` job (OCI), and the `.mcpb` URL + hash (MCPB). Keep them in sync with `server.json`'s `name`.
 
 ### Release pipeline (`.github/workflows/publish.yaml`)
 
-All publishing runs through one workflow on each **published GitHub Release**: `preflight` → `pypi` ∥ `images`(→`dockerhub-description`) ∥ `mcpb` → `registry` → `verify`, plus a `notify` job on failure. `preflight` resolves the tag once (every job checks out **the tag ref**) and fails fast if the tag disagrees with the committed `pyproject.toml` / `manifest.json` / `uv.lock` self-entry versions — preventing a split-brain release where PyPI ships the pyproject version and everything else ships the tag version. `verify` confirms all channels serve the version (PyPI JSON API, both GHCR tags, `.mcpb` asset + checksum, registry listing). `notify` files a deduplicated `ci-failure` + `wf:release` issue via `.github/actions/file-failure-issue` (one open issue per failure stream; a scheduled Claude responder routine polls `ci-failure` issues). Re-runs go through `workflow_dispatch` with the tag and are idempotent end-to-end (`skip-existing` on PyPI, re-pushed image tags, `--clobber` on the `.mcpb`, duplicate-tolerant registry publish). **PyPI Trusted Publishing pins the workflow *filename* (`publish.yaml`)** — when reviewing a PR that renames or splits this workflow, flag that the PyPI trusted publisher must be updated first. `.github/release.yml` (GitHub's release-*notes* config — a different file) groups generated notes; `publish-homebrew.yaml` (paused, dispatch-only) stays separate. When reviewing changes to the pipeline's job graph, ownership markers, or re-run semantics, check this section stays accurate.
+All publishing runs through one workflow on each **published GitHub Release**: `preflight` → `pypi` ∥ `images`(→`dockerhub-description`) ∥ `mcpb` → `registry` → `verify`, plus a `notify` job on failure. `preflight` resolves the tag once (every job checks out **the tag ref**) and fails fast if the tag disagrees with the committed `pyproject.toml` / `manifest.json` / `uv.lock` self-entry versions — preventing a split-brain release where PyPI ships the pyproject version and everything else ships the tag version. It also refuses to run when `github.repository_owner` isn't `L337-org`, so a release published from a fork (or mis-timed around a repo transfer) fails before anything ships rather than half-publishing. `verify` confirms all channels serve the version (PyPI JSON API, both GHCR tags, `.mcpb` asset + checksum, registry listing). `notify` files a deduplicated `ci-failure` + `wf:release` issue via `.github/actions/file-failure-issue` (one open issue per failure stream; a scheduled Claude responder routine polls `ci-failure` issues). Re-runs go through `workflow_dispatch` with the tag and are idempotent end-to-end (`skip-existing` on PyPI, re-pushed image tags, `--clobber` on the `.mcpb`, duplicate-tolerant registry publish). **PyPI Trusted Publishing pins the workflow *filename* (`publish.yaml`)** — when reviewing a PR that renames or splits this workflow, flag that the PyPI trusted publisher must be updated first. `.github/release.yml` (GitHub's release-*notes* config — a different file) groups generated notes; `publish-homebrew.yaml` (paused, dispatch-only) stays separate. When reviewing changes to the pipeline's job graph, ownership markers, or re-run semantics, check this section stays accurate.
 
 ## Conventions
 
@@ -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.1 → docker_mcp_server-2.1.3}/.github/workflows/canary.yaml

@@ -41,7 +41,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           # Pinned (matching the Dockerfile's uv image tag) so this step never needs the
           # live "resolve latest" fetch to raw.githubusercontent.com — that network call
@@ -102,7 +102,7 @@ jobs:
         os: [macos-latest, macos-15-intel, windows-latest]
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           # This job deliberately has no checkout — it tests the *published* package, not the
           # repo — so disable the repo-keyed cache and the empty-workdir warning it triggers.

{docker_mcp_server-2.1.1 → docker_mcp_server-2.1.3}/.github/workflows/codeql.yaml

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

{docker_mcp_server-2.1.1 → docker_mcp_server-2.1.3}/.github/workflows/premerge.yaml

@@ -33,7 +33,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Install dependencies
         # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
@@ -62,7 +62,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Install dependencies
         # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
@@ -91,7 +91,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Install dependencies
         # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
@@ -158,7 +158,7 @@ jobs:
           python-version: "3.14"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Install dependencies
         # --locked fails if uv.lock disagrees with pyproject.toml instead of silently

{docker_mcp_server-2.1.1 → 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.
@@ -64,7 +67,7 @@ jobs:
         run: git fetch --depth=1 origin main && git checkout origin/main -- scripts/docker-mcp-server.rb.tpl
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Resolve version, Python target, and macOS floor
         run: |
@@ -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.1 → docker_mcp_server-2.1.3}/.github/workflows/publish.yaml

@@ -15,7 +15,7 @@ name: Release
 # channel actually converged so a partial release is loud instead of silent.
 #
 # PyPI Trusted Publishing pins the WORKFLOW FILENAME: the trusted publisher on PyPI must list
-# `publish.yaml` (owner GavinLucas, repo docker-mcp). If the pypi job fails with an OIDC
+# `publish.yaml` (owner L337-org, repo docker-mcp). If the pypi job fails with an OIDC
 # `invalid-publisher` error, that registration is missing — add it on PyPI, then re-run.
 #
 # Partial-failure semantics: no rollback is attempted (PyPI files are immutable anyway). The
@@ -55,6 +55,16 @@ jobs:
       tag: ${{ steps.resolve.outputs.tag }}
       version: ${{ steps.resolve.outputs.version }}
     steps:
+      - name: Assert canonical repository owner
+        # The GHCR path, MCP Registry name, and PyPI trusted publisher are all pinned to the
+        # L337-org identity. Publishing from anywhere else (a fork, or the window between the
+        # identity sweep landing and the repo transfer) would half-publish — PyPI first, then
+        # fail on GHCR/registry. Fail fast before anything ships; every other job needs preflight.
+        if: github.repository_owner != 'L337-org'
+        run: |
+          echo "::error::This pipeline publishes the L337-org identity but is running in ${GITHUB_REPOSITORY}. Refusing to publish."
+          exit 1
+
       - name: Resolve tag and version
         id: resolve
         env:
@@ -142,7 +152,7 @@ jobs:
           python-version: "3.14"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Build sdist and wheel
         run: uv build
@@ -160,7 +170,7 @@ jobs:
     # Publishes the container images:
     #   full     -> docker-mcp-server:latest    + :<version>
     #   no-scout -> docker-mcp-server:no-scout   + :<version>-no-scout
-    # Images go to GHCR (ghcr.io/gavinlucas/docker-mcp-server) always, and are mirrored to Docker
+    # Images go to GHCR (ghcr.io/l337-org/docker-mcp-server) always, and are mirrored to Docker
     # Hub (docker.io/gavinlucas/docker-mcp-server) when the DOCKERHUB_USER / DOCKERHUB_TOKEN repo
     # secrets are set. The Hub mirror is opt-in: with the secrets unset the Hub login/tags steps
     # are skipped and only GHCR is pushed, so a release never fails for lack of Hub credentials.
@@ -202,7 +212,7 @@ jobs:
           VERSION: ${{ needs.preflight.outputs.version }}
         run: |
           # GHCR always; mirror to Docker Hub only when the credentials are present (see header).
-          registries="ghcr.io/gavinlucas/docker-mcp-server"
+          registries="ghcr.io/l337-org/docker-mcp-server"
           if [ -n "$DOCKERHUB_USER" ] && [ -n "$DOCKERHUB_TOKEN" ]; then
             registries="$registries docker.io/gavinlucas/docker-mcp-server"
           fi
@@ -254,9 +264,9 @@ jobs:
           # match `name` in server.json so the registry can verify we own this image (see the
           # registry job below). image.version is the v-stripped version, matching the image tags.
           labels: |
-            org.opencontainers.image.source=https://github.com/GavinLucas/docker-mcp
+            org.opencontainers.image.source=https://github.com/L337-org/docker-mcp
             org.opencontainers.image.version=${{ needs.preflight.outputs.version }}
-            io.modelcontextprotocol.server.name=io.github.GavinLucas/docker-mcp-server
+            io.modelcontextprotocol.server.name=io.github.L337-org/docker-mcp-server
           build-args: |
             INSTALL_CLI=${{ matrix.install_cli }}
             INSTALL_SCOUT=${{ matrix.install_scout }}
@@ -341,7 +351,7 @@ jobs:
     # Publishes server.json to the official MCP Registry (registry.modelcontextprotocol.io). The
     # registry stores only metadata — it points at the artifacts the sibling jobs above publish —
     # and verifies we own each listed package via a marker that must equal server.json's `name`
-    # (io.github.GavinLucas/docker-mcp-server):
+    # (io.github.L337-org/docker-mcp-server):
     #   - pypi  -> the `<!-- mcp-name: ... -->` comment in README.md (PyPI long-description)
     #   - oci   -> the io.modelcontextprotocol.server.name image label (set in the images job)
     #   - mcpb  -> the .mcpb release-asset URL (must contain "mcp") + a matching fileSha256
@@ -393,9 +403,9 @@ jobs:
             .version = $v
             | (.packages[] | select(.registryType == "pypi") | .version) = $v
             | (.packages[] | select(.registryType == "oci")  | .identifier)
-                = "ghcr.io/gavinlucas/docker-mcp-server:\($v)"
+                = "ghcr.io/l337-org/docker-mcp-server:\($v)"
             | (.packages[] | select(.registryType == "mcpb") | .identifier)
-                = "https://github.com/GavinLucas/docker-mcp/releases/download/\($tag)/docker-mcp-server-\($v).mcpb"
+                = "https://github.com/L337-org/docker-mcp/releases/download/\($tag)/docker-mcp-server-\($v).mcpb"
             | (.packages[] | select(.registryType == "mcpb") | .fileSha256) = $sha
           ' server.json > server.tmp && mv server.tmp server.json
           echo "--- server.json ---"; cat server.json
@@ -481,7 +491,7 @@ jobs:
           for tag in "${VERSION}" "${VERSION}-no-scout"; do
             ok=""
             for i in $(seq 1 5); do
-              if docker buildx imagetools inspect "ghcr.io/gavinlucas/docker-mcp-server:${tag}" >/dev/null 2>&1; then
+              if docker buildx imagetools inspect "ghcr.io/l337-org/docker-mcp-server:${tag}" >/dev/null 2>&1; then
                 echo "GHCR OK: :${tag}"; ok=1; break
               fi
               echo "::notice::GHCR tag :${tag} not readable yet (attempt $i/5); waiting 15s"
@@ -512,7 +522,7 @@ jobs:
       - name: Verify the MCP Registry lists the version
         run: |
           set -euo pipefail
-          url="https://registry.modelcontextprotocol.io/v0/servers?search=io.github.GavinLucas/docker-mcp-server"
+          url="https://registry.modelcontextprotocol.io/v0/servers?search=io.github.L337-org/docker-mcp-server"
           for i in $(seq 1 5); do
             if curl -fsS "$url" | jq -e --arg v "$VERSION" \
                 '.servers[] | select(.server.version == $v)' >/dev/null; then

{docker_mcp_server-2.1.1 → 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/gavinlucas/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,17 +157,17 @@ 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`)
 
-A discovery listing in the official MCP Registry (`registry.modelcontextprotocol.io`), which stores only **metadata** pointing at the artifacts the other channels already publish — so it's not a fourth artifact, just an index entry covering all of them. `server.json` (repo root, server name `io.github.GavinLucas/docker-mcp-server`) declares three package types in one entry: `pypi` (`docker-mcp-server`), `oci` (the GHCR image), and `mcpb` (the release `.mcpb`). The `registry` job in `.github/workflows/publish.yaml` stamps the tag version and the published `.mcpb`'s `fileSha256` into `server.json`, authenticates via **GitHub OIDC** (`id-token: write`, no stored secret), and runs `mcp-publisher publish`. The registry verifies we own each listed package by matching a marker against `server.json`'s `name`, so three markers must stay equal to it: the `<!-- mcp-name: … -->` comment in `README.md` (PyPI long-description), the `io.modelcontextprotocol.server.name` image label in the `images` job (OCI), and the `.mcpb` URL (must contain "mcp") + its hash (MCPB). The job runs `needs: [pypi, images, mcpb]`, so all three markers are live before it starts — its short retries only absorb registry-side read lag. **If `server.json`'s name/markers or the package set change, update this section.**
+A discovery listing in the official MCP Registry (`registry.modelcontextprotocol.io`), which stores only **metadata** pointing at the artifacts the other channels already publish — so it's not a fourth artifact, just an index entry covering all of them. `server.json` (repo root, server name `io.github.L337-org/docker-mcp-server`) declares three package types in one entry: `pypi` (`docker-mcp-server`), `oci` (the GHCR image), and `mcpb` (the release `.mcpb`). The `registry` job in `.github/workflows/publish.yaml` stamps the tag version and the published `.mcpb`'s `fileSha256` into `server.json`, authenticates via **GitHub OIDC** (`id-token: write`, no stored secret), and runs `mcp-publisher publish`. The registry verifies we own each listed package by matching a marker against `server.json`'s `name`, so three markers must stay equal to it: the `<!-- mcp-name: … -->` comment in `README.md` (PyPI long-description), the `io.modelcontextprotocol.server.name` image label in the `images` job (OCI), and the `.mcpb` URL (must contain "mcp") + its hash (MCPB). The job runs `needs: [pypi, images, mcpb]`, so all three markers are live before it starts — its short retries only absorb registry-side read lag. **If `server.json`'s name/markers or the package set change, update this section.**
 
 ### Release pipeline (`.github/workflows/publish.yaml`)
 
-All publishing runs through one workflow on each **published GitHub Release** (nothing publishes without that human step): `preflight` → `pypi` ∥ `images`(→`dockerhub-description`) ∥ `mcpb` → `registry` → `verify`, with a `notify` job on failure. `preflight` resolves the tag once for every job (each checks out **the tag ref**, not the event SHA) and fails fast if the tag disagrees with the committed `pyproject.toml` / `manifest.json` / `uv.lock` self-entry versions — preventing a split-brain release (PyPI ships the pyproject version; every other channel ships the tag version). `verify` confirms all four channels actually serve the version (PyPI JSON API, both GHCR tags, the `.mcpb` asset + checksum, the registry listing) so a partial release is loud. `notify` files (or comments on) a deduplicated issue labeled `ci-failure` + `wf:release` via the composite action `.github/actions/file-failure-issue` — one open issue per failure stream; a scheduled Claude responder routine polls `ci-failure` issues. Re-run a failed release via `workflow_dispatch` with the tag: every job is idempotent (`skip-existing` on PyPI, re-pushed image tags, `--clobber` on the `.mcpb`, duplicate-tolerant registry publish). **PyPI Trusted Publishing pins the workflow *filename*** — the trusted publisher on PyPI must name `publish.yaml`; if the `pypi` job fails OIDC, that registration is missing. Version-bump checklist for a release: edit `pyproject.toml` + `manifest.json`, run `uv lock`, merge, then publish a GitHub Release whose tag matches (`.github/release.yml` — GitHub's release-*notes* config, a different file — groups the generated notes, Dependabot PRs under "Dependencies"). `publish-homebrew.yaml` (paused, dispatch-only) stays separate. **When the pipeline's job graph, markers, or re-run semantics change, update this section.**
+All publishing runs through one workflow on each **published GitHub Release** (nothing publishes without that human step): `preflight` → `pypi` ∥ `images`(→`dockerhub-description`) ∥ `mcpb` → `registry` → `verify`, with a `notify` job on failure. `preflight` resolves the tag once for every job (each checks out **the tag ref**, not the event SHA) and fails fast if the tag disagrees with the committed `pyproject.toml` / `manifest.json` / `uv.lock` self-entry versions — preventing a split-brain release (PyPI ships the pyproject version; every other channel ships the tag version). It also refuses to run when `github.repository_owner` isn't `L337-org`, so a release published from a fork (or mis-timed around a repo transfer) fails before anything ships rather than half-publishing. `verify` confirms all four channels actually serve the version (PyPI JSON API, both GHCR tags, the `.mcpb` asset + checksum, the registry listing) so a partial release is loud. `notify` files (or comments on) a deduplicated issue labeled `ci-failure` + `wf:release` via the composite action `.github/actions/file-failure-issue` — one open issue per failure stream; a scheduled Claude responder routine polls `ci-failure` issues. Re-run a failed release via `workflow_dispatch` with the tag: every job is idempotent (`skip-existing` on PyPI, re-pushed image tags, `--clobber` on the `.mcpb`, duplicate-tolerant registry publish). **PyPI Trusted Publishing pins the workflow *filename*** — the trusted publisher on PyPI must name `publish.yaml`; if the `pypi` job fails OIDC, that registration is missing. Version-bump checklist for a release: edit `pyproject.toml` + `manifest.json`, run `uv lock`, merge, then publish a GitHub Release whose tag matches (`.github/release.yml` — GitHub's release-*notes* config, a different file — groups the generated notes, Dependabot PRs under "Dependencies"). `publish-homebrew.yaml` (paused, dispatch-only) stays separate. **When the pipeline's job graph, markers, or re-run semantics change, update this section.**
 
 ## Conventions
 
@@ -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.1 → docker_mcp_server-2.1.3}/CONTRIBUTING.md

@@ -185,4 +185,4 @@ It reads the version from `pyproject.toml`, creates `dist/` if needed, writes a
 
 ## Reporting issues
 
-Bug reports and feature requests have templates that you can choose when you [`create an issue`](https://github.com/GavinLucas/docker-mcp/issues/new/choose). Please select the correct issue type and follow the template.
+Bug reports and feature requests have templates that you can choose when you [`create an issue`](https://github.com/L337-org/docker-mcp/issues/new/choose). Please select the correct issue type and follow the template.

{docker_mcp_server-2.1.1 → docker_mcp_server-2.1.3}/DOCKERHUB.md

@@ -4,11 +4,11 @@ More than just a fully featured [MCP](https://modelcontextprotocol.io) server th
 
 It can manage multiple Docker daemons, e.g. both your local dev environment and also a remote production environment over TCP, TLS or SSH in a single session. It can also be configured to mark some daemons as read-only, so that you can monitor them without the risk of making accidental changes. It also exposes things like logs and stats as resources so that you can easily monitor and triage your environments with a few prompts.
 
-The server runs entirely on your machine and sends no telemetry. You are entirely in control — see the [Privacy Policy](https://github.com/GavinLucas/docker-mcp#privacy-policy).
+The server runs entirely on your machine and sends no telemetry. You are entirely in control — see the [Privacy Policy](https://github.com/L337-org/docker-mcp#privacy-policy).
 
-This image is the container distribution of the project. **Full documentation, configuration, and source are on GitHub: <https://github.com/GavinLucas/docker-mcp>.**
+This image is the container distribution of the project. **Full documentation, configuration, and source are on GitHub: <https://github.com/L337-org/docker-mcp>.**
 
-> The same images are published to GHCR as [`ghcr.io/gavinlucas/docker-mcp-server`](https://github.com/GavinLucas/docker-mcp/pkgs/container/docker-mcp-server) — identical content, so use whichever registry you prefer.
+> The same images are published to GHCR as [`ghcr.io/l337-org/docker-mcp-server`](https://github.com/L337-org/docker-mcp/pkgs/container/docker-mcp-server) — identical content, so use whichever registry you prefer.
 
 ## Quick start
 
@@ -72,14 +72,14 @@ Set these in the client's `env` block. Three switches restrict which tools are r
 
 `DOCKER_HOST` / `DOCKER_TLS_VERIFY` / `DOCKER_CERT_PATH` retarget the daemon (e.g. `-e DOCKER_HOST=tcp://remote-host:2375`).
 
-See the [full configuration reference](https://github.com/GavinLucas/docker-mcp#configuration) for the complete list and examples.
+See the [full configuration reference](https://github.com/L337-org/docker-mcp#configuration) for the complete list and examples.
 
 ## Security
 
-Connecting this server to an AI agent grants it the same access as a local Docker CLI session against the configured daemon — the daemon's socket is effectively root-equivalent on its host. Prefer pointing it at a daemon dedicated to workloads the agent may touch (a dev VM, a remote sandbox, Docker Desktop, a rootless install) rather than your production socket. See the [Security considerations](https://github.com/GavinLucas/docker-mcp#security-considerations) on GitHub before enabling the server.
+Connecting this server to an AI agent grants it the same access as a local Docker CLI session against the configured daemon — the daemon's socket is effectively root-equivalent on its host. Prefer pointing it at a daemon dedicated to workloads the agent may touch (a dev VM, a remote sandbox, Docker Desktop, a rootless install) rather than your production socket. See the [Security considerations](https://github.com/L337-org/docker-mcp#security-considerations) on GitHub before enabling the server.
 
 ## Links
 
-- **Source, full docs & issues:** <https://github.com/GavinLucas/docker-mcp>
-- **Also on PyPI** (run without a container): `uvx docker-mcp-server` — see the [README](https://github.com/GavinLucas/docker-mcp#using-the-server).
+- **Source, full docs & issues:** <https://github.com/L337-org/docker-mcp>
+- **Also on PyPI** (run without a container): `uvx docker-mcp-server` — see the [README](https://github.com/L337-org/docker-mcp#using-the-server).
 - **License & contributing:** see the GitHub repository.