docker-mcp-server 2.0.0__tar.gz → 2.0.1__tar.gz

docker_mcp_server-2.0.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- What does this change do, and why? -->
+
+## Test plan
+
+<!-- How did you verify this? e.g. `uv run pytest -v`, `uv run ruff check . && uv run ruff format --check .`, `uv run pyright`, manual steps. -->
+
+## 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 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.0.0 → docker_mcp_server-2.0.1}/.github/copilot-instructions.md

@@ -148,15 +148,34 @@ def mcp_example(name: str):
     """
     Say hello to someone by name.
 
-    args: name: str - The name to say hello to
+    args: name - The name to say hello to
     returns: str - The greeting
     """
     return f"Hello, {name}!"
 ```
 
 - One-line summary sentence, then a blank line
-- `args:` section lists each parameter as `name: type - description`
+- `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
+  alongside the description, so a `name: type - ...` form just duplicates it as prose tokens. (The
+  `returns:` line keeps its type, since the return shape is not in the input schema.)
 - `returns:` line documents the return type and what it contains
+- 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.
 
 ### Bounding rules
 

{docker_mcp_server-2.0.0 → docker_mcp_server-2.0.1}/.github/workflows/canary.yaml

@@ -42,6 +42,11 @@ jobs:
 
       - name: Set up uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          # Pinned (matching the Dockerfile's uv image tag) so this step never needs the
+          # live "resolve latest" fetch to raw.githubusercontent.com — that network call
+          # failed transiently on 2026-07-06 and blocked an unrelated PR (#130).
+          version: "0.11.21"
 
       - name: Resolve runtime deps as wheels-only for each platform
         # --only-binary :all: makes resolution fail if any dependency lacks a wheel for the
@@ -103,6 +108,9 @@ jobs:
           # repo — so disable the repo-keyed cache and the empty-workdir warning it triggers.
           enable-cache: false
           ignore-empty-workdir: true
+          # Pinned (matching the Dockerfile's uv image tag) so this step never needs the
+          # live "resolve latest" fetch to raw.githubusercontent.com.
+          version: "0.11.21"
 
       - name: Import smoke (full tool-registration path, no daemon needed)
         run: uv run --no-project --python 3.14 --with docker-mcp-server python -c "import docker_mcp"

{docker_mcp_server-2.0.0 → docker_mcp_server-2.0.1}/.github/workflows/codeql.yaml

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

{docker_mcp_server-2.0.0 → docker_mcp_server-2.0.1}/.github/workflows/images.yaml

@@ -50,10 +50,10 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
 
       - name: Build image (${{ matrix.variant }})
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
           platforms: linux/amd64
@@ -85,13 +85,13 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0
+        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
 
       - name: Build full variant for amd64 + arm64
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
           platforms: linux/amd64,linux/arm64

{docker_mcp_server-2.0.0 → docker_mcp_server-2.0.1}/.github/workflows/publish.yaml

@@ -219,17 +219,17 @@ jobs:
           echo "Publishing \`${{ matrix.variant }}\` as: $tags" >> "$GITHUB_STEP_SUMMARY"
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0
+        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
         with:
           # The two matrix jobs race to cache the same binfmt image; skip the cache to avoid the
           # harmless "unable to reserve cache" warning while keeping both builds parallel.
           cache-image: false
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
 
       - name: Log in to GHCR
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -237,13 +237,13 @@ jobs:
 
       - name: Log in to Docker Hub
         if: env.DOCKERHUB_USER != '' && env.DOCKERHUB_TOKEN != ''
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
         with:
           username: ${{ secrets.DOCKERHUB_USER }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build and push ${{ matrix.variant }}
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
           platforms: linux/amd64,linux/arm64

{docker_mcp_server-2.0.0 → docker_mcp_server-2.0.1}/.mcpbignore

@@ -27,6 +27,8 @@ DOCKERHUB.md
 # Agent / project docs not needed inside the bundle.
 CLAUDE.md
 SECURITY.md
+CONTRIBUTING.md
+CODE_OF_CONDUCT.md
 
 # Caches and VCS.
 __pycache__/

{docker_mcp_server-2.0.0 → docker_mcp_server-2.0.1}/CLAUDE.md

@@ -260,6 +260,19 @@ 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.
 
 ### MCP resources
 

docker_mcp_server-2.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [Gavin@L337.org](mailto:Gavin@L337.org). All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

docker_mcp_server-2.0.1/CONTRIBUTING.md

@@ -0,0 +1,188 @@
+# Contributing to docker-mcp-server
+
+Contributions are welcome. The project values a tight mapping between the Docker SDK's public surface and the MCP tools we expose. By participating, you're expected to uphold the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Before you start
+
+This is an [MCP](https://modelcontextprotocol.io) server: it exposes Docker operations as `@tool()`-decorated Python functions that an AI agent calls over the Model Context Protocol. If that sentence is new to you, the short version is: each function in `docker_mcp/tools/` becomes one callable "tool" an agent can invoke, with the function's docstring as the description the agent sees and its type-annotated parameters as the input schema.
+
+The practical mental model for finding your way around:
+
+- One file per Docker feature area (`containers.py`, `images.py`, `swarm.py`, …), each backed by either the [docker-py SDK](https://docker-py.readthedocs.io/en/stable/) or a `docker` CLI shell-out (`compose.py`, `buildx.py`, …). See the tree below for the full map.
+- Every tool function is registered centrally in `docker_mcp/server.py`, which is also where read-only/destructive classification, naming enforcement, and the domain-disable switches live.
+- `CLAUDE.md` (repo root) is the full architecture reference — written to brief Claude Code, but equally the canonical source for humans. This file (`CONTRIBUTING.md`) covers the practical day-to-day: setup, the checklist for adding a tool, testing, and submitting changes. If something isn't covered here, it's almost certainly in `CLAUDE.md`.
+
+## Project layout
+
+```
+.
+├── docker_mcp/            # the package — `python -m docker_mcp` runs the server
+│   ├── __init__.py        # defines `main()`; side-effect-imports `server` and `tools`
+│   ├── __main__.py        # calls `main()` so `python -m docker_mcp` works
+│   ├── server.py          # creates the FastMCP singleton (`mcp`) shared by every tool module
+│   └── tools/             # one file per Docker SDK domain or CLI/registry feature
+│       ├── _cli.py        # cross-platform subprocess helper for docker CLI shell-outs (private)
+│       ├── _utils.py      # shared helpers (drop_none, join_bounded, MAX_PAYLOAD_BYTES) (private)
+│       ├── system.py      # DockerClient connection + lazy `_get_client()` helper
+│       ├── containers.py
+│       ├── images.py
+│       ├── networks.py
+│       ├── volumes.py
+│       ├── configs.py
+│       ├── secrets.py
+│       ├── nodes.py
+│       ├── services.py
+│       ├── swarm.py
+│       ├── plugins.py
+│       ├── compose.py     # `docker compose` CLI plugin (shells out via _cli.py)
+│       ├── stack.py       # `docker stack` (Compose-on-Swarm) CLI (shells out via _cli.py)
+│       ├── context.py     # `docker context` CLI (shells out via _cli.py)
+│       ├── buildx.py      # `docker buildx` CLI plugin (shells out via _cli.py)
+│       ├── scout.py       # `docker scout` CLI plugin (shells out via _cli.py)
+│       ├── registry.py    # OCI v2 registries + Docker Hub HTTPS APIs (no daemon)
+│       ├── prompts.py     # @prompt(...) templates for common docker workflows
+│       └── resources.py   # @mcp.resource() endpoints exposing SDK + CLI + registry docs
+├── tests/                 # pytest suite, mirrors `docker_mcp/tools/` one-to-one
+│   └── integration/       # tests that hit a real Docker daemon or docker.io
+├── assets/                # bundle assets (e.g. the .mcpb icon) packed into the Desktop Extension
+├── scripts/               # developer convenience scripts (not used by CI) — e.g. build-mcpb.sh
+└── dist/                  # build output (git-ignored) — local .mcpb test bundles land here
+```
+
+Each `docker_mcp/tools/<file>.py` has a matching `tests/test_<file>.py`. New modules must be added to `docker_mcp/tools/__init__.py` and have a corresponding test file. Tool modules that wrap CLI features must funnel every subprocess call through `docker_mcp/tools/_cli.py` so the cross-platform safety concerns (binary discovery, no shell, UTF-8 decoding, output capping, Windows console suppression, env scrubbing) live in one place.
+
+New Docker functionality goes in the matching existing file (e.g. a new volume operation goes in `volumes.py`), not a new file — a new `docker_mcp/tools/<domain>.py` is only for a Docker feature area that doesn't exist in the tree above.
+
+## Conventions
+
+Tool functions are decorated with `@tool()` (the project's wrapper around `@mcp.tool()`, imported from `docker_mcp.server`) and follow this docstring style:
+
+```python
+from docker_mcp.server import tool
+
+
+@tool()
+def mcp_example(name: str):
+    """
+    Say hello to someone by name.
+
+    args: name - The name to say hello to
+    returns: str - The greeting
+    """
+    return f"Hello, {name}!"
+```
+
+- Tool modules import `tool` from `docker_mcp.server`; prompt modules import `prompt` from `docker_mcp.server`. Only resource modules (`@mcp.resource(...)`) import `mcp` directly — never import `mcp` directly in a tool or prompt module, that creates a circular import.
+- Every tool needs a `TOOL_CATEGORIES` entry in `docker_mcp/server.py` (`READ_ONLY` / `MUTATING` / `DESTRUCTIVE`); the central map drives the tool's `ToolAnnotations` and the read-only env switches, and `tests/test_server.py` fails if it drifts from the registered set. A tool's *domain* (for `DOCKER_MCP_SERVER_DISABLE` and the tool catalog) is derived automatically from its module name, so putting a tool in the right `docker_mcp/tools/<domain>.py` file is all that's needed.
+- Tool names follow `<management-command>_<verb>`, anchored to the docker CLI's own management-command structure (`docker container ls` → `container_list`), with long-form verbs (`list`/`remove`/`inspect`, never `ls`/`rm`/`get`). `tests/test_naming.py` enforces this — a new tool with a short-form verb or an unapproved prefix fails CI. See `CLAUDE.md`'s "Tool naming convention" section for the full rule, including identifier parameter naming (`id_or_name`, `name`/`names`, `repository`).
+- Line length is 120 characters (enforced by ruff).
+- CLI shell-outs must go through `docker_mcp/tools/_cli.py:run_docker` — never call `subprocess.run` directly from a tool module. The helper enforces `shell=False`, resolves the binary via `shutil.which` (cross-platform), decodes output as UTF-8 with replace, caps the captured bytes, scrubs the environment, and suppresses console pop-ups on Windows.
+- A tool with non-obvious behavior (side effects, preconditions, a non-obvious failure mode, or overlap with another tool) needs more than a one-line summary — add a short paragraph covering when to use it vs. the alternative, side effects/preconditions, and concrete parameter formats. Verify any factual claim against the live docker-py docs / Engine API spec rather than assuming; see [`CLAUDE.md`](CLAUDE.md)'s "Tool function format" section for the full convention and why it matters.
+
+## Verifying the SDK before writing code
+
+To prevent hallucinated method names, the project includes a `/docker-sdk` Claude Code skill that fetches the live Docker SDK for Python documentation, inventories what's already exposed, and produces a gap analysis. Run it before adding new tools:
+
+```
+/docker-sdk                    # full gap analysis
+/docker-sdk containers         # focus on a single domain
+```
+
+If you're not using Claude Code, check method names and signatures directly against the [docker-py docs](https://docker-py.readthedocs.io/en/stable/index.html) (or, for SDK gaps, the [low-level `APIClient`](https://docker-py.readthedocs.io/en/stable/api.html)) before writing a call — don't assume a method exists because it sounds plausible.
+
+## Testing conventions
+
+Unit tests mock the Docker client rather than hitting a real daemon, patching `_get_client` (or, for CLI-backed modules, `run_docker`) at the point the tool module looks it up. A minimal example, from `tests/test_volumes.py`:
+
+```python
+from unittest.mock import MagicMock, patch
+
+from docker_mcp.tools.volumes import volume_inspect
+
+
+def test_volume_inspect():
+    volume = MagicMock()
+    volume.attrs = {"Name": "myvol"}
+    with patch("docker_mcp.tools.volumes._get_client") as mock_client:
+        mock_client.return_value.volumes.get.return_value = volume
+        assert volume_inspect("myvol") == {"Name": "myvol"}
+```
+
+Integration tests (`tests/integration/`) call the real tool function against an actual Docker daemon and are auto-marked `@pytest.mark.integration` by `tests/integration/conftest.py`, which also provides an autouse `skip_if_no_daemon` fixture — they're skipped automatically (not failed) when no daemon is reachable, so it's safe to run the full suite without Docker running. They're excluded from the default `pytest` invocation (`-m 'not integration'` in `pyproject.toml`); run them explicitly with `uv run pytest -m integration -v`.
+
+## Checklist when adding a new tool module
+
+When you add a new `docker_mcp/tools/<domain>.py`, also update:
+
+1. **`docker_mcp/tools/__init__.py`** — star-import the module (private helpers prefixed with `_` are excluded).
+2. **`tests/test_<domain>.py`** — unit tests using mocks (no real daemon).
+3. **`tests/integration/test_<domain>.py`** — at least one happy-path test against a real daemon (or override the `skip_if_no_daemon` fixture if the module doesn't need one).
+4. **`docker_mcp/tools/prompts.py`** — at least one `@prompt(...)` template that exercises the new tools end-to-end.
+5. **`docker_mcp/tools/resources.py`** — add an entry under `SDK_SECTIONS` or `EXTERNAL_SECTIONS` if the new domain has authoritative docs the agent should be able to read at runtime.
+6. **README.md** — append to the "What the agent can do" list and (if relevant) the "Security considerations" section.
+7. **SECURITY.md** — only if the new module exposes a new class of risk not already covered by the README's Security section.
+
+If you're only adding a tool or two to an *existing* domain file rather than a whole new module, items 1 and 7 don't apply, but 2-6 still do wherever relevant (e.g. a new tool still needs unit + integration test cases, even if the test file itself already exists).
+
+## Local development
+
+```bash
+# install dependencies (creates .venv, installs runtime + dev deps)
+uv sync
+
+# run the server
+uv run python -m docker_mcp
+# …or via the installed console script
+uv run docker-mcp
+
+# unit tests (integration tests are excluded by default)
+uv run pytest -v
+
+# integration tests — require a running Docker daemon at $DOCKER_HOST
+uv run pytest -m integration -v
+
+# lint, format, type-check
+uv run ruff check .
+uv run ruff format .
+uv run pyright
+
+# install the pre-commit hook (one-time, runs ruff on every commit)
+uv run pre-commit install
+
+# add a runtime dependency
+uv add <package>
+
+# add a development dependency
+uv add --group dev <package>
+```
+
+## Submitting your change
+
+CI (`.github/workflows/premerge.yaml`) runs on every pull request and push to `main`, and must pass before merging:
+
+- `pytest` — two separate jobs: unit tests (`uv run pytest -v`, same as local) and integration tests (`uv run pytest -m integration -v`) against the real Docker Engine the `ubuntu-latest` runner ships with. You don't need a local daemon to contribute — `uv run pytest -v` alone (which excludes integration tests by default) is enough to check your change; the integration job will exercise it in CI.
+- `ruff check` and `ruff format --check` — lint and formatting; run `uv run ruff check . && uv run ruff format .` locally to fix both before committing (the pre-commit hook from `uv run pre-commit install` runs `ruff check --fix` and `ruff format` automatically on each commit, so this is usually already handled for you).
+- `pyright` — type-check.
+- CI installs with `uv sync --locked`, which **fails** if `uv.lock` disagrees with `pyproject.toml` rather than silently re-locking. If you change a dependency, run `uv lock` and commit the updated lockfile alongside `pyproject.toml`.
+
+A separate, non-blocking `Check docs mirror` job flags a PR that edits `CLAUDE.md` or `.github/copilot-instructions.md` without the other — the two files intentionally mirror each other (Copilot's own PR review is driven by `copilot-instructions.md`), so a change to project structure, conventions, or the tool surface should update both.
+
+Keep PRs focused — one logical change per PR is easier to review than a bundle of unrelated fixes. For anything beyond a small, self-contained fix, consider opening an issue first (see "Reporting issues" below) so the approach can be discussed before you invest time in an implementation.
+
+## Building a local Desktop Extension (.mcpb)
+
+To smoke-test the Claude Desktop Extension locally, pack a bundle with the developer helper in `scripts/`:
+
+```bash
+# pack dist/docker-mcp-server-<version>.mcpb (auto-increments -1, -2, … if it exists)
+scripts/build-mcpb.sh
+
+# …or give it an explicit name (a .mcpb extension is added if missing)
+scripts/build-mcpb.sh my-test-bundle
+```
+
+It reads the version from `pyproject.toml`, creates `dist/` if needed, writes a `.sha256` alongside the bundle, and packs via Anthropic's `mcpb` CLI (a global `mcpb`, else `npx @anthropic-ai/mcpb`; see `--help` for the `MCPB=` override). The official release bundle is built separately by the `mcpb` job in `.github/workflows/publish.yaml` — this script is for local testing only and is **not** used by CI.
+
+## 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.

{docker_mcp_server-2.0.0 → docker_mcp_server-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-mcp-server
-Version: 2.0.0
+Version: 2.0.1
 Summary: MCP server for managing Docker resources via the Docker SDK for Python
 Project-URL: Homepage, https://github.com/GavinLucas/docker-mcp
 Project-URL: Repository, https://github.com/GavinLucas/docker-mcp
@@ -413,6 +413,7 @@ Connecting this server to an AI agent grants it the same level of access as a lo
 | Official MCP Registry | [io.github.GavinLucas/docker-mcp-server](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.GavinLucas%2Fdocker-mcp-server/versions) |
 | Glama | [docker-mcp-server](https://glama.ai/mcp/servers/GavinLucas/docker-mcp) |
 | mcp.so | [docker-mcp-server](https://mcp.so/server/docker-mcp-server/GavinLucas) |
+| awesome-mcp-servers | [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers#cloud-platforms) |
 
 ## Privacy Policy
 
@@ -422,140 +423,4 @@ the operations you request. The full statement is in [PRIVACY.md](https://github
 
 ## Contributing
 
-Contributions are welcome. The project values a tight mapping between the Docker SDK's public surface and the MCP tools we expose.
-
-### Project layout
-
-```
-.
-├── docker_mcp/            # the package — `python -m docker_mcp` runs the server
-│   ├── __init__.py        # defines `main()`; side-effect-imports `server` and `tools`
-│   ├── __main__.py        # calls `main()` so `python -m docker_mcp` works
-│   ├── server.py          # creates the FastMCP singleton (`mcp`) shared by every tool module
-│   └── tools/             # one file per Docker SDK domain or CLI/registry feature
-│       ├── _cli.py        # cross-platform subprocess helper for docker CLI shell-outs (private)
-│       ├── _utils.py      # shared helpers (drop_none, join_bounded, MAX_PAYLOAD_BYTES) (private)
-│       ├── system.py      # DockerClient connection + lazy `_get_client()` helper
-│       ├── containers.py
-│       ├── images.py
-│       ├── networks.py
-│       ├── volumes.py
-│       ├── configs.py
-│       ├── secrets.py
-│       ├── nodes.py
-│       ├── services.py
-│       ├── swarm.py
-│       ├── plugins.py
-│       ├── compose.py     # `docker compose` CLI plugin (shells out via _cli.py)
-│       ├── stack.py       # `docker stack` (Compose-on-Swarm) CLI (shells out via _cli.py)
-│       ├── context.py     # `docker context` CLI (shells out via _cli.py)
-│       ├── buildx.py      # `docker buildx` CLI plugin (shells out via _cli.py)
-│       ├── scout.py       # `docker scout` CLI plugin (shells out via _cli.py)
-│       ├── registry.py    # OCI v2 registries + Docker Hub HTTPS APIs (no daemon)
-│       ├── prompts.py     # @mcp.prompt() templates for common docker workflows
-│       └── resources.py   # @mcp.resource() endpoints exposing SDK + CLI + registry docs
-├── tests/                 # pytest suite, mirrors `docker_mcp/tools/` one-to-one
-│   └── integration/       # tests that hit a real Docker daemon or docker.io
-├── assets/                # bundle assets (e.g. the .mcpb icon) packed into the Desktop Extension
-├── scripts/               # developer convenience scripts (not used by CI) — e.g. build-mcpb.sh
-└── dist/                  # build output (git-ignored) — local .mcpb test bundles land here
-```
-
-Each `docker_mcp/tools/<file>.py` has a matching `tests/test_<file>.py`. New modules must be added to `docker_mcp/tools/__init__.py` and have a corresponding test file. Tool modules that wrap CLI features must funnel every subprocess call through `docker_mcp/tools/_cli.py` so the cross-platform safety concerns (binary discovery, no shell, UTF-8 decoding, output capping, Windows console suppression, env scrubbing) live in one place.
-
-### Conventions
-
-Tool functions are decorated with `@tool()` (the project's wrapper around `@mcp.tool()`, imported from `docker_mcp.server`) and follow this docstring style:
-
-```python
-from docker_mcp.server import tool
-
-
-@tool()
-def mcp_example(name: str):
-    """
-    Say hello to someone by name.
-
-    args: name: str - The name to say hello to
-    returns: str - The greeting
-    """
-    return f"Hello, {name}!"
-```
-
-- Import `tool` from `docker_mcp.server` (and, for prompts/resources, `mcp`), never directly from the `mcp` package — that creates a circular import.
-- Every tool needs a `TOOL_CATEGORIES` entry in `docker_mcp/server.py` (`READ_ONLY` / `MUTATING` / `DESTRUCTIVE`); the central map drives the tool's `ToolAnnotations` and the read-only env switches, and `tests/test_server.py` fails if it drifts from the registered set. A tool's *domain* (for `DOCKER_MCP_SERVER_DISABLE` and the tool catalog) is derived automatically from its module name, so putting a tool in the right `docker_mcp/tools/<domain>.py` file is all that's needed.
-- Line length is 120 characters (enforced by ruff).
-- CLI shell-outs must go through `docker_mcp/tools/_cli.py:run_docker` — never call `subprocess.run` directly from a tool module. The helper enforces `shell=False`, resolves the binary via `shutil.which` (cross-platform), decodes output as UTF-8 with replace, caps the captured bytes, scrubs the environment, and suppresses console pop-ups on Windows.
-
-### Checklist when adding a new tool module
-
-When you add a new `docker_mcp/tools/<domain>.py`, also update:
-
-1. **`docker_mcp/tools/__init__.py`** — star-import the module (private helpers prefixed with `_` are excluded).
-2. **`tests/test_<domain>.py`** — unit tests using mocks (no real daemon).
-3. **`tests/integration/test_<domain>.py`** — at least one happy-path test against a real daemon (or override the `skip_if_no_daemon` fixture if the module doesn't need one).
-4. **`docker_mcp/tools/prompts.py`** — at least one `@mcp.prompt(...)` template that exercises the new tools end-to-end.
-5. **`docker_mcp/tools/resources.py`** — add an entry under `SDK_SECTIONS` or `EXTERNAL_SECTIONS` if the new domain has authoritative docs the agent should be able to read at runtime.
-6. **README.md** — append to the "What the agent can do" list and (if relevant) the "Security considerations" section.
-7. **SECURITY.md** — only if the new module exposes a new class of risk not already covered by the README's Security section.
-
-### Verifying the SDK before writing code
-
-To prevent hallucinated method names, the project includes a `/docker-sdk` Claude Code skill that fetches the live Docker SDK for Python documentation, inventories what's already exposed, and produces a gap analysis. Run it before adding new tools:
-
-```
-/docker-sdk                    # full gap analysis
-/docker-sdk containers         # focus on a single domain
-```
-
-### Local development
-
-```bash
-# install dependencies (creates .venv, installs runtime + dev deps)
-uv sync
-
-# run the server
-uv run python -m docker_mcp
-# …or via the installed console script
-uv run docker-mcp
-
-# unit tests (integration tests are excluded by default)
-uv run pytest -v
-
-# integration tests — require a running Docker daemon at $DOCKER_HOST
-uv run pytest -m integration -v
-
-# lint, format, type-check
-uv run ruff check .
-uv run ruff format .
-uv run pyright
-
-# install the pre-commit hook (one-time, runs ruff on every commit)
-uv run pre-commit install
-
-# add a runtime dependency
-uv add <package>
-
-# add a development dependency
-uv add --group dev <package>
-```
-
-CI runs `pytest` (unit + integration), `ruff` (lint + format check), and `pyright` on every pull request and push to `main` via `.github/workflows/premerge.yaml`.
-
-### Building a local Desktop Extension (.mcpb)
-
-To smoke-test the Claude Desktop Extension locally, pack a bundle with the developer helper in `scripts/`:
-
-```bash
-# pack dist/docker-mcp-server-<version>.mcpb (auto-increments -1, -2, … if it exists)
-scripts/build-mcpb.sh
-
-# …or give it an explicit name (a .mcpb extension is added if missing)
-scripts/build-mcpb.sh my-test-bundle
-```
-
-It reads the version from `pyproject.toml`, creates `dist/` if needed, writes a `.sha256` alongside the bundle, and packs via Anthropic's `mcpb` CLI (a global `mcpb`, else `npx @anthropic-ai/mcpb`; see `--help` for the `MCPB=` override). The official release bundle is built separately by the `mcpb` job in `.github/workflows/publish.yaml` — this script is for local testing only and is **not** used by CI.
-
-### 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.
+Contributions are welcome. The project values a tight mapping between the Docker SDK's public surface and the MCP tools we expose. See [CONTRIBUTING.md](https://github.com/GavinLucas/docker-mcp/blob/main/CONTRIBUTING.md) for the project layout, tool conventions, the checklist for adding a new tool module, and local development setup.