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

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

@@ -89,7 +89,7 @@ An additional distribution channel alongside the uvx-from-git install (unchanged
 
 ### Desktop Extension (MCPB)
 
-A third distribution channel for one-click install in Claude Desktop. Repo-root sources: `manifest.json` (MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (bundle entry point — `from docker_mcp import main; main()`, at the root so `import docker_mcp` resolves under the host's managed `uv`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + manifest/entry-point + `assets/`), and `assets/icon.png` (512×512). It's a `uv`-type bundle: the host resolves deps from `pyproject.toml` at install time (no vendored venv). `manifest.json`'s `user_config` maps install-dialog fields to env — `DOCKER_MCP_SERVER_HOSTS` (the single host field; `DOCKER_HOST` is **not** exposed — the bare-value shorthand keeps the one-daemon case a one-liner) and the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is intentionally omitted — the bundle never runs containerized). The `mcpb` job in `.github/workflows/publish.yaml` rewrites the manifest `version` from the release tag, packs the `.mcpb` via `npx @anthropic-ai/mcpb`, and attaches it (plus a `.sha256` recording the bare filename, so `sha256sum -c` works on downloads) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (version from `pyproject.toml`, auto-incrementing output in `dist/`, never mutates `manifest.json`) for smoke-testing in Claude Desktop — it is deliberately **not** used by CI. `PRIVACY.md` (no-telemetry statement) is referenced by the manifest's `privacy_policies`. Keep the manifest `version` aligned with `pyproject.toml`; update this section when the manifest's tool/env surface or the bundled file set changes.
+A third distribution channel for one-click install in Claude Desktop. Repo-root sources: `manifest.json` (MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (bundle entry point — `from docker_mcp import main; main()`, at the root so `import docker_mcp` resolves under the host's managed `uv`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + manifest/entry-point + `assets/`), and `assets/icon.png` (512×512). It's a `uv`-type bundle: the host resolves deps from `pyproject.toml` at install time (no vendored venv). `manifest.json`'s `user_config` maps install-dialog fields to env — `DOCKER_MCP_SERVER_HOSTS` (the single host field; `DOCKER_HOST` is **not** exposed — the bare-value shorthand keeps the one-daemon case a one-liner) and the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is intentionally omitted — the bundle never runs containerized). The `mcpb` job in `.github/workflows/publish.yaml` rewrites the manifest `version` from the release tag, packs the `.mcpb` via `npx @anthropic-ai/mcpb`, and attaches it (plus a `.sha256` recording the bare filename, so `sha256sum -c` works on downloads) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (auto-incrementing output in `dist/`) for smoke-testing in Claude Desktop — it is deliberately **not** used by CI. It stamps a **dev version** from `pyproject.toml` + git HEAD — `<version>-dev.<short-commit>[.dirty]` — so a local bundle can't be mistaken for a release and is traceable to its commit; the stamp goes into `manifest.json` only for the pack and is restored by an `EXIT` trap. `PRIVACY.md` (no-telemetry statement) is referenced by the manifest's `privacy_policies`. Keep the manifest `version` aligned with `pyproject.toml`; update this section when the manifest's tool/env surface or the bundled file set changes.
 
 ### Homebrew tap (`L337-org/homebrew-tap`) — PAUSED
 
@@ -205,9 +205,12 @@ touches — do not demand rewrites of untouched legacy docstrings.
    ("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.
+4. **`returns:` names the shape, not just the type.** For computed or partial returns the
+   load-bearing keys must be listed (`{"Titles", "Processes"}`). For a full engine inspect
+   document, key enumeration is NOT wanted — an arbitrary subset of hundreds of keys is noise; the
+   line should identify the document ("full inspect payload, as `docker inspect`"), optionally
+   plus one or two keys a caller typically wants. Flag the shapeless "dict - The X's attrs" on a
+   new/modified tool, which identifies neither form.
 5. **Front-loaded and terse** — the description is paid for in every session's context.
 6. **Every factual claim must be verifiable** against the docker-py docs / Engine API spec (Docker
    SDK Policy below). Flag claims that contradict them — especially identifier semantics ("name or

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

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

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

@@ -155,7 +155,7 @@ An additional distribution channel alongside uvx-from-git (which is unchanged).
 
 ### Desktop Extension (MCPB bundle)
 
-A third distribution channel (alongside uvx/PyPI and the container images) for one-click install in Claude Desktop. The repo root carries the bundle sources: `manifest.json` (the MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (the bundle entry point — `from docker_mcp import main; main()`, kept at the root so `import docker_mcp` resolves however the host's managed `uv` lays out `sys.path`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + `manifest.json`/`mcpb_run.py` + `assets/`), and `assets/icon.png` (512×512). Because it's a `uv`-type bundle, the host resolves dependencies from `pyproject.toml` at install time — there's no vendored venv, so the bundle stays ~250 KB and cross-platform. `manifest.json`'s `user_config` block renders the install-dialog fields and maps them to env: `DOCKER_MCP_SERVER_HOSTS` (the single host field — `DOCKER_HOST` is deliberately **not** exposed; the bare-value shorthand keeps the simple one-daemon case a one-liner) plus the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is deliberately **not** exposed — the bundle never runs containerized). The `manifest.json` `version` is kept in step with `pyproject.toml` (`tests/test_pyproject_pins.py` asserts it), but the `mcpb` job in `.github/workflows/publish.yaml` rewrites it from the release tag at pack time so it can't drift; that job packs the `.mcpb` with `npx @anthropic-ai/mcpb` and attaches it (plus a `.sha256` recording the bare filename, so `sha256sum -c` works on downloads) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (reads the version from `pyproject.toml`, packs to `dist/` with an auto-incrementing name, never mutates `manifest.json`) — for smoke-testing a bundle in Claude Desktop; it is deliberately **not** wired into CI, which uses the workflow above. `PRIVACY.md` (a no-telemetry/no-backend statement) is referenced by the manifest's `privacy_policies` and summarized in the README. **When the manifest's tool/env surface or the bundled file set changes, update this section.**
+A third distribution channel (alongside uvx/PyPI and the container images) for one-click install in Claude Desktop. The repo root carries the bundle sources: `manifest.json` (the MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (the bundle entry point — `from docker_mcp import main; main()`, kept at the root so `import docker_mcp` resolves however the host's managed `uv` lays out `sys.path`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + `manifest.json`/`mcpb_run.py` + `assets/`), and `assets/icon.png` (512×512). Because it's a `uv`-type bundle, the host resolves dependencies from `pyproject.toml` at install time — there's no vendored venv, so the bundle stays ~250 KB and cross-platform. `manifest.json`'s `user_config` block renders the install-dialog fields and maps them to env: `DOCKER_MCP_SERVER_HOSTS` (the single host field — `DOCKER_HOST` is deliberately **not** exposed; the bare-value shorthand keeps the simple one-daemon case a one-liner) plus the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is deliberately **not** exposed — the bundle never runs containerized). The `manifest.json` `version` is kept in step with `pyproject.toml` (`tests/test_pyproject_pins.py` asserts it), but the `mcpb` job in `.github/workflows/publish.yaml` rewrites it from the release tag at pack time so it can't drift; that job packs the `.mcpb` with `npx @anthropic-ai/mcpb` and attaches it (plus a `.sha256` recording the bare filename, so `sha256sum -c` works on downloads) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (packs to `dist/` with an auto-incrementing name) — for smoke-testing a bundle in Claude Desktop. It stamps a **dev version** derived from `pyproject.toml` plus the git HEAD — `<version>-dev.<short-commit>[.dirty]` (`.dirty` = uncommitted changes at pack time) — so a local bundle is never mistaken for a release in Claude Desktop's extension list and is traceable to the commit it was built from despite having no tag; the stamp is written into `manifest.json` only for the duration of the pack and restored by an `EXIT` trap, so the working tree is left unmodified. It is deliberately **not** wired into CI, which uses the workflow above. `PRIVACY.md` (a no-telemetry/no-backend statement) is referenced by the manifest's `privacy_policies` and summarized in the README. **When the manifest's tool/env surface or the bundled file set changes, update this section.**
 
 ### Homebrew tap (`L337-org/homebrew-tap`) — PAUSED
 
@@ -305,8 +305,12 @@ legacy docstrings are cleaned opportunistically, not churned):
    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".
+   all an agent gets. For computed or partial returns, name the load-bearing keys (`{"Titles",
+   "Processes"}`; `{"LayersSize", "Images", "Containers", "Volumes", "BuildCache"}`). For a full
+   engine inspect document, do NOT enumerate an arbitrary subset of its hundreds of keys — say
+   what document it is ("full inspect payload, as `docker inspect`"), optionally plus the one or
+   two keys a caller typically wants from it. What stays banned is the shapeless "dict - The X's
+   attrs", which identifies neither form.
 5. **Front-load and stay terse** — the description is paid for in every session's context; every
    sentence must earn its place.
 6. **Verify every factual claim** against the live docker-py docs / Engine API spec per the Docker

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-mcp-server
-Version: 2.1.3
+Version: 2.1.4
 Summary: MCP server for managing Docker resources via the Docker SDK for Python
 Project-URL: Homepage, https://github.com/L337-org/docker-mcp
 Project-URL: Repository, https://github.com/L337-org/docker-mcp
@@ -412,7 +412,7 @@ Connecting this server to an AI agent grants it the same level of access as a lo
 | Desktop Extension (.mcpb) | [GitHub Releases](https://github.com/L337-org/docker-mcp/releases) |
 | Official MCP Registry | [io.github.L337-org/docker-mcp-server](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.L337-org%2Fdocker-mcp-server/versions) |
 | Glama | [docker-mcp-server](https://glama.ai/mcp/servers/L337-org/docker-mcp) |
-| mcp.so | [docker-mcp-server](https://mcp.so/server/docker-mcp-server/GavinLucas) |
+| mcp.so | [docker-mcp-server](https://mcp.so/servers/docker-1ae67d) |
 | awesome-mcp-servers | [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers#cloud-platforms) |
 
 ## Privacy Policy

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

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

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

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

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

@@ -115,6 +115,10 @@ def compose_down(
     """
     Stop and remove containers, networks (and optionally volumes) for a compose project.
 
+    Inverse of `compose_up`. Images are kept; named volumes go only with volumes=True
+    (destructive). Use `compose_stop` to stop without removing anything.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
+
     args:
         project_dir - Dir with the compose file (default: server cwd)
         files - Explicit compose file paths (repeatable, `-f`)
@@ -145,6 +149,10 @@ def compose_ps(
     """
     List containers in a compose project, parsed from `--format json`.
 
+    Container-level view of one project (state, health, publishers); `compose_list` enumerates
+    projects, and `container_list` covers non-compose containers.
+    Does not raise on a non-zero CLI exit: `services` comes back empty — inspect `raw.stderr`.
+
     args:
         project_dir - Dir with the compose file (default: server cwd)
         files - Explicit compose file paths (repeatable, `-f`)
@@ -190,6 +198,10 @@ def compose_logs(
     """
     Fetch a bounded slice of logs from a compose project (never follows).
 
+    Bounded and non-following by design, so it always returns promptly. For one container's logs
+    use `container_logs`; for a swarm service use `service_logs`. Log text arrives on `stdout`.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
+
     args:
         project_dir - Dir with the compose file (default: server cwd)
         files - Explicit compose file paths (repeatable, `-f`)
@@ -227,6 +239,10 @@ def compose_config(
     """
     Render the canonical compose configuration after merges, profiles, and variable substitution.
 
+    Use it to validate compose files and see exactly what the CLI will run before `compose_up`.
+    Does not raise on a non-zero CLI exit: on a failed render `config` may be None — inspect
+    `raw.stderr`.
+
     args:
         project_dir - Dir with the compose file (default: server cwd)
         files - Explicit compose file paths (repeatable, `-f`)
@@ -269,6 +285,10 @@ def compose_build(
     """
     Build images for a compose project.
 
+    Builds the images declared by the project's `build:` sections without starting anything —
+    `compose_up(build=True)` builds and starts in one step.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
+
     args:
         project_dir - Dir with the compose file (default: server cwd)
         files - Explicit compose file paths (repeatable, `-f`)
@@ -441,7 +461,9 @@ def compose_run(
     """
     Run a one-off command against a compose service.
 
-    Always passes `-T` (no TTY under MCP). Defaults to detached with `--rm` so the call returns promptly.
+    Always passes `-T` (no TTY under MCP). Defaults to detached with `--rm` so the call returns
+    promptly. Unlike `compose_exec`, this starts a NEW container for the service rather than
+    running inside the existing one.
 
     args:
         service - Service name from the compose file
@@ -540,7 +562,8 @@ def compose_images(
 
     Answers "what image and tag does each service container actually run?" — the containers must
     exist (`compose_up`/`compose_create` first). Use `compose_ps` for container state and
-    `image_list` for daemon-wide images. Raises RuntimeError if the CLI call fails.
+    `image_list` for daemon-wide images.
+    Raises RuntimeError if the CLI call fails.
 
     args:
         project_dir - Dir with the compose file (default: server cwd)
@@ -577,7 +600,9 @@ def compose_port(
     Resolve the host binding for a service's container port.
 
     The compose equivalent of `docker port`: which host address/port a service's private port is
-    published on. `published` is None when the port isn't published.
+    published on. `published` is None when the port isn't published. For non-compose containers
+    read `container_inspect`'s NetworkSettings.Ports instead.
+    Raises RuntimeError if the CLI call fails.
 
     args:
         service - Service name from the compose file
@@ -630,7 +655,8 @@ def compose_wait(
 
     For one-shot / batch services. A long-running service that never exits blocks until
     `timeout_seconds`, then the subprocess is killed (TimeoutExpired) — bound it sensibly.
-    Exit codes are on stdout.
+    Exit codes are on stdout. For a single container use `container_wait`; for swarm services
+    use `service_wait`.
 
     args:
         services - One or more services to wait on. At least one is required.
@@ -658,7 +684,9 @@ def compose_top(
     """
     Show the running processes of a compose project's containers.
 
-    Output is the `ps`-style process table per service (not JSON); read it from `stdout`.
+    Output is the `ps`-style process table per service (not JSON); read it from `stdout`. The
+    per-container equivalent is `container_top`.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
 
     args:
         services - Restrict to these services (default: all)
@@ -688,9 +716,11 @@ def compose_cp(
     """
     Copy files/folders between a service container and the server host's filesystem.
 
-    Exactly one of `source`/`dest` is `SERVICE:PATH`; the other is a path on the host running this MCP
-    server, read/written as the server's user (same host exposure as the file-path archive tools — see
-    SECURITY.md). Copying to stdout (`dest="-"`) is unsupported; use the container-archive tools.
+    Exactly one of `source`/`dest` is `SERVICE:PATH`; the other is a path on the host running this
+    MCP server, read/written as the server's user (same host exposure as the file-path archive
+    tools — see SECURITY.md). Copying to stdout (`dest="-"`) is unsupported; use
+    `container_archive_get`.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
 
     args:
         source - `SERVICE:SRC_PATH` or a host path
@@ -726,6 +756,10 @@ def compose_kill(
     """
     Send a signal to a compose project's containers (default SIGKILL).
 
+    Immediate, with no grace period — prefer `compose_stop` for a clean shutdown (stop signal,
+    then kill after a timeout).
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
+
     args:
         services - Restrict to these services (default: all)
         signal - Signal to send (default "SIGKILL"; e.g. "SIGTERM", "SIGHUP")
@@ -757,9 +791,9 @@ def compose_pause(
     Pause the containers of a compose project (freezes their processes in place).
 
     Paused containers stop consuming CPU but keep memory, network endpoints, and state; resume
-    with `compose_unpause`. To actually stop containers (each one's configured stop signal, freeing
-    resources) use `compose_stop`; to stop and delete them use `compose_down`. Does not raise on a
-    non-zero CLI exit — inspect `returncode`/`stderr` in the result.
+    with `compose_unpause`. To actually stop containers (each one's configured stop signal,
+    freeing resources) use `compose_stop`; to stop and delete them use `compose_down`.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
 
     args:
         services - Restrict to these services (default: all)
@@ -785,6 +819,10 @@ def compose_unpause(
     """
     Unpause the containers of a compose project (resumes paused processes).
 
+    Reverse of `compose_pause`: processes continue from where they were frozen (no restart).
+    `compose_start` is the counterpart for stopped containers.
+    Does not raise on a non-zero CLI exit — inspect `returncode`/`stderr` in the result.
+
     args:
         services - Restrict to these services (default: all)
         project_dir - Dir with the compose file (default: server cwd)
@@ -803,6 +841,10 @@ def compose_list(all: bool = False, host: str | None = None) -> list:
     """
     List compose projects known to the daemon (across all directories).
 
+    Project-level view (one entry per project); `compose_ps` lists the containers of a single
+    project.
+    Raises RuntimeError if the CLI call fails.
+
     args: all - Include stopped projects
     returns: list - One dict per project (parsed from `--format json`)
     """

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

@@ -25,7 +25,7 @@ def config_create(
         data - Raw bytes content of the config file
         labels - Labels to set on the config
         templating - Templating driver config (e.g. {"Name": "golang"} for Go template syntax)
-    returns: dict - The created config's attrs including its id
+    returns: dict - The created config's attrs ({"ID", "Version", "CreatedAt", "Spec", ...})
     """
     kwargs: dict = {
         "name": name,
@@ -57,10 +57,10 @@ def config_list(filters: dict | None = None, host: str | None = None) -> list:
 
     Unlike secrets, config attrs include the actual config data (`Spec.Data`, base64-encoded)
     since configs are not treated as sensitive. Valid filter keys: `id`, `name`, `names`,
-    `label` (key or key=value).
+    `label` (key or key=value). Fetch a single config by id/name with `config_inspect`.
 
     args: filters - Narrow the list; omit to return every config
-    returns: list - A list of config attrs dicts
+    returns: list - One full config document ({"ID", "Spec", ...}) per config
     """
     return [c.attrs for c in _get_client(host).configs.list(**drop_none(filters=filters))]
 
@@ -70,6 +70,9 @@ def config_remove(id_or_name: str, host: str | None = None) -> bool:
     """
     Remove a swarm config.
 
+    Requires a swarm manager, and fails while any service still references the config — update or
+    remove those services first. The last step of the rotation flow described in `config_create`.
+
     args: id_or_name - The config id or name
     returns: bool - True after removal
     """

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

@@ -56,7 +56,12 @@ def container_run(
     host: str | None = None,
 ) -> dict | str:
     """
-    Run a container from an image.
+    Run a container from an image (create and start in one call, like `docker run`).
+
+    Use `container_create` to prepare a container without starting it, or `container_exec` to run
+    a command in a container that already exists. With detach=False the call blocks until the
+    container exits and returns its output, so long-running images need detach=True. Created
+    containers are stamped with provenance labels.
 
     args:
         image - The image to run
@@ -158,9 +163,9 @@ def container_inspect(id_or_name: str, host: str | None = None) -> dict:
     Return the full inspect detail for a single container.
 
     Use this when you need complete information about one container — config, state,
-    network settings, mounts, environment variables, and resource limits. For a quick
-    overview of many containers use `container_list` instead (returns a summary per
-    container). For just logs or stats use `container_logs` / `container_stats`.
+    network settings, mounts, environment variables, and resource limits. To enumerate many
+    containers use `container_list` instead (same payload per container by default; abridged
+    with sparse=True). For just logs or stats use `container_logs` / `container_stats`.
 
     args: id_or_name - Container id (full or short) or name
     returns: dict - Full container inspect attrs (equivalent to `docker inspect`)
@@ -181,10 +186,13 @@ def container_list(
     host: str | None = None,
 ) -> list:
     """
-    List containers.
+    List containers on the daemon (running only by default).
+
+    Pass all=True to include stopped containers. For a compose project `compose_ps` groups
+    containers by service; for swarm services use `service_ps` (tasks may live on other nodes).
 
     args:
-        all - Show all containers, including stopped ones
+        all - Show all containers, including stopped ones (default False: running only)
         since - Only show containers created after this id or name
         before - Only show containers created before this id or name
         limit - Maximum number of results
@@ -193,7 +201,9 @@ def container_list(
         ignore_removed - Ignore containers removed during listing
         managed_only - Only return containers created by this MCP server (filters on the
                              docker-mcp-server.managed label); combines with any `filters` given
-    returns: list - A list of container attrs dicts
+    returns: list - One dict per container: full inspect payloads by default (each match is
+        inspected, like `container_inspect`); sparse=True skips the per-container inspect calls
+        and returns the daemon's abridged list entries instead
     """
     if managed_only:
         filters = managed_filter(filters)
@@ -234,7 +244,7 @@ def container_start(id_or_name: str, host: str | None = None) -> dict:
     raised). To stop then start a running container use `container_restart`.
 
     args: id_or_name - Container id (full or short) or name
-    returns: dict - The container's full attrs after starting
+    returns: dict - The container's full inspect payload after starting
     """
     container = _get_client(host).containers.get(id_or_name)
     container.start()
@@ -268,12 +278,17 @@ def container_stop(id_or_name: str, stop_timeout_seconds: int = 10, host: str |
 @tool()
 def container_restart(id_or_name: str, stop_timeout_seconds: int = 10, host: str | None = None) -> dict:
     """
-    Restart a container.
+    Restart a container: stop then start again in one call.
+
+    The container receives its configured stop signal (`STOPSIGNAL`, default SIGTERM), SIGKILL
+    after stop_timeout_seconds, and is then started. Use `container_stop`/`container_start` to do
+    the halves separately. When the server runs containerized it refuses to restart its own
+    container.
 
     args:
         id_or_name - The container id or name
-        stop_timeout_seconds - Seconds to wait for graceful stop before SIGKILL and restart
-    returns: dict - The container's attrs after restart
+        stop_timeout_seconds - Seconds between the stop signal and SIGKILL (default 10)
+    returns: dict - The container's full inspect payload after the restart
     """
     container = _get_client(host).containers.get(id_or_name)
     guard_not_self(container, host=host)
@@ -296,7 +311,7 @@ def container_kill(id_or_name: str, signal: str | None = None, host: str | None
     args:
         id_or_name - The container id or name
         signal - Signal name or number as a string (e.g. "SIGHUP", "9"); default SIGKILL
-    returns: dict - The container's attrs after the signal
+    returns: dict - The container's full inspect payload after the signal
     """
     container = _get_client(host).containers.get(id_or_name)
     guard_not_self(container, host=host)
@@ -316,7 +331,7 @@ def container_pause(id_or_name: str, host: str | None = None) -> dict:
     `container_exec` fails against a paused container until it is unpaused.
 
     args: id_or_name - The container id or name
-    returns: dict - The container's attrs after pause
+    returns: dict - The container's full inspect payload after pause (State.Paused true)
     """
     container = _get_client(host).containers.get(id_or_name)
     guard_not_self(container, host=host)
@@ -347,13 +362,18 @@ def container_remove(
     id_or_name: str, volumes: bool = False, link: bool = False, force: bool = False, host: str | None = None
 ) -> bool:
     """
-    Remove a container.
+    Remove a container, deleting its writable layer.
+
+    The image is untouched (`image_remove` deletes images); named volumes are never removed —
+    volumes=True only covers anonymous ones. A running container is refused unless force=True,
+    which kills it first. When the server runs containerized it refuses to remove its own
+    container.
 
     args:
         id_or_name - The container id or name
-        volumes - Also remove anonymous volumes (the CLI's `--volumes`)
+        volumes - Also remove anonymous volumes (the CLI's `--volumes`); named volumes persist
         link - Remove the specified link
-        force - Force remove a running container
+        force - Kill a running container before removing it (default False: running is an error)
     returns: bool - True after removal completes
     """
     container = _get_client(host).containers.get(id_or_name)
@@ -601,7 +621,8 @@ def container_exec(
         environment - Environment variables
         workdir - Working directory inside the container
         demux - Return stdout and stderr separately
-    returns: dict - Mapping with exit_code and output keys
+    returns: dict - {"exit_code", "output"}; output is combined stdout+stderr, or a
+        [stdout, stderr] pair with demux=True
     """
     container = _get_client(host).containers.get(id_or_name)
     result = container.exec_run(
@@ -641,7 +662,8 @@ def container_commit(
     Snapshot a container's current filesystem state as a new image.
 
     Useful for capturing a debugging state or saving manual changes made inside a container.
-    For repeatable builds use a Dockerfile instead. The container is paused by default during
+    For repeatable builds use `image_build` with a Dockerfile instead; publish the result with
+    `image_tag` + `image_push`. The container is paused by default during
     the snapshot to ensure filesystem consistency — set `pause=False` only if the container
     cannot be paused. `changes` accepts Dockerfile instructions to apply on top of the
     snapshot, e.g. `["CMD [\"python\", \"app.py\"]", "ENV FOO=bar"]`.
@@ -655,7 +677,7 @@ def container_commit(
         pause - Pause the container during commit for consistency (default True)
         changes - Dockerfile instructions (CMD, ENV, EXPOSE, etc.) to apply to the image
         conf - Additional image configuration overrides as a dict
-    returns: dict - The new image's attrs
+    returns: dict - The new image's full inspect payload (Id is the new image id)
     """
     container = _get_client(host).containers.get(id_or_name)
     image = container.commit(
@@ -698,7 +720,7 @@ def container_rename(id_or_name: str, name: str, host: str | None = None) -> dic
     args:
         id_or_name - The container id or name
         name - The new name; must not be in use by any other container
-    returns: dict - The container's attrs after the rename
+    returns: dict - The container's full inspect payload after the rename
     """
     container = _get_client(host).containers.get(id_or_name)
     container.rename(name)
@@ -717,12 +739,13 @@ def container_update(id_or_name: str, updates: dict, host: str | None = None) ->
     default 1024), `cpu_period` / `cpu_quota` (microseconds for CFS throttling),
     `cpuset_cpus` (e.g. "0-1"), `restart_policy` (dict with `Name` such as
     "on-failure"/"always"/"unless-stopped" and optional `MaximumRetryCount`). To change
-    image, env, or volumes the container must be recreated.
+    image, env, or volumes the container must be recreated (`container_remove` +
+    `container_run`).
 
     args:
         id_or_name - Container id or name to update
         updates - Resource fields to update; see description for valid keys
-    returns: dict - The container's full attrs after the update
+    returns: dict - The container's full inspect payload after the update
     """
     container = _get_client(host).containers.get(id_or_name)
     container.update(**updates)
@@ -779,7 +802,8 @@ def container_wait(
     reached) and `timed_out`. The stop conditions ("not-running"/"next-exit"/"removed") use the
     daemon's blocking wait and fill `status_code`/`error` (the container's exit info); "healthy" polls
     the container's HEALTHCHECK every `poll_interval`s and fills `health`/`status`; "log-match" polls
-    recent logs every `poll_interval`s for `pattern` and fills `matched_line`.
+    recent logs every `poll_interval`s for `pattern` and fills `matched_line`. For a compose
+    project use `compose_wait`; for swarm services use `service_wait`.
 
     Health semantics: with no HEALTHCHECK defined, once the container is `running` the tool returns
     promptly with `health: null` and `met: false` (false = "not confirmed healthy", not "unhealthy" —
@@ -891,7 +915,9 @@ def container_export(
     """
     Export a container's filesystem as a tar archive: to a file on the server host, or in band.
 
-    With `dest_path` the archive streams straight to disk (no byte cap), so it handles large
+    The tar is a flat filesystem snapshot with no image metadata or layers — use `image_save` for
+    an archive that `image_load` can restore, and `container_archive_get` for a single file or
+    directory. With `dest_path` the archive streams straight to disk (no byte cap), so it handles large
     containers — the file is written by the server's user, `~` is expanded, and an existing file is
     refused unless `overwrite=True`. Without `dest_path` the tar bytes are returned in band, capped
     at `max_bytes` (default 32 MiB) because MCP base64-encodes them — a fallback for when no
@@ -939,7 +965,9 @@ def container_archive_get_to_file(
     """
     Retrieve a file or directory from a container as a tar archive written to a file on the server host.
 
-    Streams straight to disk (no in-band byte cap). The file is written by the server's user; `~` is
+    File-writing variant of `container_archive_get` — prefer it for anything large, since in-band
+    bytes are base64-encoded by MCP. For the whole filesystem use `container_export`. Streams
+    straight to disk (no in-band byte cap). The file is written by the server's user; `~` is
     expanded and an existing file is refused unless `overwrite=True`.
 
     args:
@@ -966,6 +994,7 @@ def container_archive_put(
     """
     Upload a tar archive to a path inside a container, from in-band bytes or a file on the server host.
 
+    Inverse of `container_archive_get`: the archive is extracted at `path` inside the container.
     Pass exactly one of `data` (tar bytes in band) or `from_file` (a path on the server host, streamed
     straight to the daemon — preferred for large archives, since in-band bytes are base64-encoded by
     MCP). `from_file` is read by the server's user; `~` is expanded.