mcp-synology-container/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

[0.5.0] - 2026-05-18

Added

Welle B Teil 1 — Registry tools (#3, #5). Three new SYNO.Docker.Registry tools, reverse-engineered from a live DSM API capture (the n4s4 reference disagrees on parameter names and methods; the live capture wins):

• search_registry (#5) — search the active Docker registry by query string. Uses SYNO.Docker.Registry/search (version 1) with the query JSON-encoded as q, plus offset, limit, and page_size. Renders stars, downloads, the official-image flag, and a truncated description per hit, and shows the total match count so the caller knows when to raise limit. No confirmation gate (read-only).
• list_image_tags — list available tags for a repository (bonus tool). Uses SYNO.Docker.Registry/tags (version 1) with the repository JSON-encoded as repo — note the parameter name diverges from the n4s4 reference which uses name. The response shape is unusual: DSM returns the tag list as the envelope's data field directly (not wrapped in a sub-key), so the tool accepts both shapes defensively. Output is capped by limit (default 50) because popular images like alpine ship 200+ tags. No confirmation gate (read-only).
• pull_image (#3) — pull an image into the local cache via SYNO.Docker.Registry/pull_start (version 1) with both repository and tag JSON-encoded. Requires confirmed=True. DSM exposes no confirmed pull_status method, so completion is detected by polling SYNO.Docker.Image/list for the new repository:tag pair with a 2–10 s backoff schedule and a 240 s overall budget (kept under the Claude Desktop ~4 min tool-call ceiling). A timeout returns a non-fatal "still running" hint pointing at list_images instead of raising — DSM keeps pulling server-side regardless. Short-circuits when the image is already present locally so a repeated call is cheap. Closes #3 and #5.

Tool count rises from 31 to 34.

Fixed

• inspect_image rendering polish (follow-up to #4 after the 0.4.2 parameter-contract fix). Three live-NAS observations that the initial implementation got wrong:
  • Header showed ?:? — DSM SYNO.Docker.Image/get returns image="" and tag="" when the lookup is by name:tag, so the response fields are unreliable. The header now echoes the user- supplied image_id (e.g. gitea/gitea:1.26.1), falling back to the sha256 id only if image_id itself were empty.
  • Ports rendered as raw Python dicts like {'port': '22', 'protocol': 'tcp'}. The ports array is actually a list of {"port", "protocol"} objects; each entry is now formatted as 22/tcp.
  • Environment rendered as raw Python dicts like {'key': 'PATH', 'value': '...'}. The env array is actually a list of {"key", "value"} objects; each entry is now formatted as PATH=/usr/local/.... cmd, entrypoint, and volumes (plain string arrays) were already correct and are unchanged. Referencing #4 (already closed).

[0.4.2] - 2026-05-18

Fixed

• inspect_image (#4): the 0.4.0 implementation called SYNO.Docker.Image/get with name + tag + id parameters, which DSM rejected with error 114 ("invalid parameter"). Reverse- engineering the live API capture revealed the correct contract: one JSON-encoded parameter named identity that accepts either form:
  • name:tag (e.g. "gitea/gitea:1.26.1")
  • sha256:<hash> (e.g. "sha256:cd21e54e...") The pre-resolution lookup against list_images is no longer needed — the user input is JSON-encoded and passed straight through.
• inspect_image response parsing: the endpoint does NOT return details.Config.* / RootFS.Layers (the Docker-engine inspect shape the previous code assumed). The actual top-level fields are image, tag, id, digest, size, virtual_size, author, docker_version, cmd, entrypoint, env, ports, volumes. Layer rendering is removed (the endpoint does not surface layers); digest, author, docker version, and volumes are now displayed.

[0.4.1] - 2026-05-18

Removed

• pause_container and unpause_container (added in 0.4.0) — live test against DSM revealed that Container Manager on this firmware does not expose pause/resume at all. The GUI action menu only offers Start / Stop / Force-Stop / Restart / Reset, and direct calls to SYNO.Docker.Container/pause and /unpause return "Method does not exist". Both tools have been removed rather than left as a broken surface. The remaining three lifecycle tools (start_container, stop_container, restart_container) are unaffected. Tool count drops from 33 to 31. Closes #7 (won't fix — DSM-side limitation).

[0.4.0] - 2026-05-18

Added

Container lifecycle (#1, #7) — five new tools fill the gap between "project" and "exec" operations. Until now the only way to stop or restart a single container was to stop the whole project. All five use SYNO.Docker.Container (version=1) with the same JSON-encoded name parameter pattern as delete_container, and route through _resolve_container_name so a clean name like jenkins resolves to DSM's hash-prefixed f93cb8b504f7_jenkins:

• start_container — start a stopped container (no confirmation).
• stop_container — stop a running container (confirmation required).
• restart_container — stop + start in one call (confirmation required).
• pause_container — SIGSTOP the container's processes (confirmation required).
• unpause_container — SIGCONT the container's processes (no confirmation; reversing a pause is non-destructive).

stop is live-verified against DSM; start, restart, pause, and unpause are implemented by symmetry on the same API surface. If any of them turns out to need a different parameter shape in production, it will be reverse-engineered via DevTools capture in a follow-up.

Image inspection (#4) — inspect_image returns the full image detail blob (layers + sizes, environment variables, exposed ports, entrypoint/cmd, working directory, labels) via SYNO.Docker.Image/get. Accepts the same identifier forms as delete_image — name:tag, registry-prefixed ghcr.io/foo/bar:v1, and bare hash — and resolves the user input against list_images first so typos produce a clean "not found" rather than an opaque DSM error. The response parser is defensive about wrapper shape (details.<docker fields> vs. flat) so the tool keeps working if DSM varies the envelope between firmware versions.

System overview (#6) — system_overview aggregates CPU %, RAM used/limit, network I/O, and block I/O across all running containers plus running/stopped counts. No new DSM endpoint: composed from SYNO.Docker.Container/list + SYNO.Docker.Container/stats, re-using the same Docker-formula CPU calculation as container_stats. Errors from either upstream call are non-fatal — the available section is rendered and the failure is surfaced under a Warnings: block.

[0.3.3] - 2026-05-18

Fixed

• delete_container: SYNO.Docker.Container/delete requires three parameters — name (JSON-encoded), force=false, and preserve_profile=false. Previously only name was sent (without JSON-encoding), causing DSM to reject the call with error 114.
• delete_project: DSM does not reject Project/delete on a running project — it silently removes the registration and leaves the containers running as orphans. The connector now blocks the call itself when the project status is RUNNING, before issuing any DSM request, and tells the user to stop_project first. The previous implementation relied on a DSM-level rejection that never occurs in practice; the corresponding unit test was a false positive (mocked an error that real DSM never returns) and has been replaced with a test that asserts Project/delete is never called for a RUNNING project.

Added

• delete_project — remove a Container Manager project's registration via SYNO.Docker.Project/delete with the UUID JSON-encoded as the id parameter (per DSM convention). Mirrors the "Delete project" action in Container Manager: only the registration is removed; the project folder and compose file remain on the NAS. The success message explicitly states the folder was preserved so the user is not surprised. Closes the project lifecycle (create → start/stop/redeploy → delete). Safety:
  • Project-name validation runs before any I/O.
  • A _find_project pre-flight returns "not found" with a clear message rather than letting DSM reject an unknown UUID.
  • The tool deliberately does NOT auto-stop a running project. If DSM rejects the delete on a RUNNING project, the response tells the user to stop_project first rather than silently halting containers under the guise of a "delete" call.
  • Requires confirmed=True; the preview shows name, UUID, status, full path, and share path so the user can verify before deleting.

Added

• create_project — register a new Container Manager project from a compose YAML string. Three-step flow:
  1. Create the target folder via SYNO.FileStation.CreateFolder with force_parent=true (idempotent — does not fail if the folder already exists, and creates missing intermediate directories). Without this step, SYNO.Docker.Project/create fails with DSM error code 2100.
  2. SYNO.Docker.Project/create (form-encoded POST, JSON-encoded string parameters per DSM convention) returns the new project's UUID.
  3. trigger_build_stream + _wait_for_project_running — reuses the existing image-pull / start / poll machinery (including the BUILD_FAILED early-exit from welle 2). Defaults: share_path is derived from compose_base_path (e.g. /volume1/docker + myapp → /docker/myapp). The compose content is validated as YAML before any side effects. A pre-flight list_projects check rejects duplicate names with a clear message rather than leaving an orphaned folder on the NAS. Requires confirmed=True; the preview shows the resolved share path and the service count parsed from the compose content.

Fixed

• DsmClient.trigger_build_stream: broaden transport-error handling (M-4). httpx.ReadTimeout is still treated as a success signal (the request was sent; DSM is processing it server-side), but all other httpx.HTTPError subclasses (ConnectError, ConnectTimeout, WriteError, RemoteProtocolError, …) are now converted into a SynologyError with a clear message. Previously these propagated as raw httpx exceptions and left callers with a stack trace.
• redeploy_project: when build_stream (or the polling step) fails after the project has already been stopped, the response now explicitly tells the user that the project is in STOPPED state and must be recovered with start_project or another redeploy_project call. Previously the response suggested "use stop + start separately", which was misleading because stop had already happened.
• _wait_for_project_running: exit the polling loop early on BUILD_FAILED / ERROR (M-5). DSM signals these statuses within seconds of a failed image pull; the old polling loop kept waiting up to 5 minutes for RUNNING. redeploy_project surfaces the terminal status with a hint to update_image_tag and retry when the cause is BUILD_FAILED.
• system_prune preview: count unused user-created networks alongside dangling images and stopped containers (M-6). Built-in networks (bridge, host, none) are excluded because Docker never prunes them. Previously the preview noted "Unused networks: (not counted)", even though the underlying SYNO.Docker.Utils/prune call deletes them — users could lose networks they had not been warned about.

Changed

• Minor version bump because redeploy_project and system_prune return different strings (and redeploy_project returns earlier on BUILD_FAILED). No tool signatures changed.

[0.2.9] - 2026-05-18

Fixed

• __version__ is now derived from package metadata via importlib.metadata.version(), eliminating the drift between pyproject.toml and src/mcp_synology_container/__init__.py (was stuck at 0.1.0 since the initial release).
• compose.py: reject project names that contain path separators or other unsafe characters before they reach _find_compose_path. Previously a name like "../../etc" could traverse out of compose_base_path when the project was not yet registered with Container Manager. The new _validate_project_name helper enforces ^[a-zA-Z0-9_-]+$ and is applied to read_compose, update_compose, update_image_tag, and update_env_var. Addresses M-3 from the v0.2.8 review.

Docs

• CHANGELOG.md backfilled for releases 0.2.7 and 0.2.8 (entries had been missed during those releases).

[0.2.8] - 2026-04-21

Added

• tests/test_dsm_client.py — comprehensive offline test suite for DsmClient:
  • _scrub_url and _error_message pure helpers.
  • request() happy-path, API-not-cached, _sid scrubbing in HTTPStatusError, sensitive-param log masking.
  • Session re-auth retry: single-retry semantics, auth-manager-absent path, re-auth failure path, thundering-herd (login called once under concurrent 106 responses).
  • trigger_build_stream: SSE fire-and-forget, JSON error detection, ReadTimeout swallowing, HTTP-error scrubbing.
  • upload_text and download_text happy-path + error-response branches.
  • _ensure_initialized double-checked locking and negative-cache cooldown behavior.

Fixed

• DsmClient._ensure_initialized: cache failed init outcomes for 60 s so that repeated tool calls during a credential outage (wrong password, IP-blocked 407, DNS failure) do not keep hammering DSM. Each caller receives the cached exception until the cooldown window expires, after which a fresh attempt is made. Adds INIT_ERROR_COOLDOWN module constant and _init_error / _init_error_until state. Addresses M4 from the 0.2.7 review.

[0.2.7] - 2026-04-21

Fixed

• DsmClient: scrub _sid query-parameter values from URLs embedded in httpx.HTTPStatusError messages so the raw DSM session ID never reaches log output or MCP tool responses (C1).
• DsmClient: re-auth lock now snapshots _sid before entering the lock and skips the redundant login if another task has already refreshed the session, eliminating duplicate logins on concurrent 106/107/119 responses (M3).
• DsmClient.trigger_build_stream: re-instates immediate JSON-error detection (regression from 0.2.6). Inspects the Content-Type header and reads a small capped prefix of the body for application/json responses to surface DSM error codes without forcing the caller into a multi-minute polling timeout. SSE responses remain fire-and-forget (C2/M8).
• compose.update_env_var: parenthesise the apply-branch match condition so (isinstance AND startswith) OR (entry == var_name) no longer evaluates the equality branch for non-string entries — aligns the apply side with the preview-side detection logic (M1).

Changed

• All 23 @mcp.tool() functions: strip -> str return annotations and trim docstrings to a single line (≤100 chars). FastMCP generates an outputSchema entry for every annotated tool, which roughly doubles the tools/list payload size; multi-line docstrings with Args:/Returns: sections add further bulk that Claude Desktop must parse on every connection.

Chore

• uv.lock resynced (was stale at 0.2.2).
• .gitignore: exclude .claude/ per-user Claude Code settings.
• Mechanical ruff check --fix + ruff format cleanup (import sorting, unused-import removal). No functional change.

[0.2.6] - 2026-04-21

Fixed

• DsmClient.trigger_build_stream: Claude Desktop aborts tool calls after ~4 minutes. The previous implementation read the first SSE chunk before returning, which could block for the entire duration of an image pull. Fixed by making the call truly fire-and-forget: the HTTP request is sent, response headers are received (HTTP status check only), then the connection is closed immediately without reading any SSE events. DSM continues the build server-side regardless. The _json import added in 0.2.5 is removed.

[0.2.5] - 2026-04-21

Changed

• redeploy_project: Replaced the delete-before-start image workaround with SYNO.Docker.Project/build_stream — the programmatic equivalent of the DSM "Erstellen" (Build) button, confirmed via browser DevTools capture. New 3-step flow for all project states:
  1. Stop (skipped for STOPPED; error-suppressed for BUILD_FAILED)
  2. build_stream — DSM pulls updated images and starts the project via SSE
  3. Poll for RUNNING (timeout raised from 30 s to 5 min to accommodate image pulls) build_stream errors are now fatal (abort the redeploy with a clear message).

Added

• DsmClient.trigger_build_stream(project_id) — fires a streaming GET to SYNO.Docker.Project/build_stream, reads the first SSE chunk to confirm DSM accepted the request, then closes the connection. The build continues server-side. Handles immediate JSON error responses; swallows ReadTimeout (stream still open = build running).

[0.2.4] - 2026-04-21

Changed

• redeploy_project: Replaced broken SYNO.Docker.Image/pull with a delete-before-start workaround. The tool now reads image tags from the project's compose file via FileStation, deletes each cached image before calling start (so DSM auto-pulls the latest version), then polls for RUNNING. Image deletion is non-fatal — if it fails the project still starts. Unified 4-step flow for all project states (RUNNING, STOPPED, BUILD_FAILED).

Added

• update_image_tag: Auto-updates environment variables whose value equals the numeric version prefix of the old tag when the new tag shares the same <digits>-<suffix> pattern. For example, changing 2.558-jdk21 → 2.560-jdk21 automatically updates JENKINS_VERSION=2.558 to JENKINS_VERSION=2.560. The preview (unconfirmed call) now lists which env vars will be updated. Only triggers when the variable exists and the pattern matches; no change for plain tags like latest.

[0.2.3] - 2026-04-21

Changed

• CLAUDE.md rewritten: removed all operator-specific infrastructure details (hostnames, container names, image tags, personal notes). Kept DSM API quirks, implementation rules, and tool inventory.

[0.2.2] - 2026-04-21

Fixed

• redeploy_project (BUILD_FAILED): Pull errors are no longer silently suppressed. If the image pull fails (e.g. the tag in compose.yaml does not exist on the registry), redeploy aborts immediately with a clear message pointing to update_image_tag.

[0.2.1] - 2026-04-21

Fixed

• redeploy_project: After issuing start, the tool now polls the project status every 2 seconds for up to 30 seconds until the project reaches RUNNING. Previously DSM returned immediately while containers were still starting, causing the project to appear as exited when checked right after redeploy. On timeout a warning is returned instead of an error.
• delete_image: Now distinguishes between running and stopped container references. A stopped container holding the image produces a clear hint to use delete_container or system_prune instead of a generic "in use" error.
• redeploy_project (BUILD_FAILED path): Added explicit image pull step before restart (stop → pull → start). Previously the old cached image could be reused.

Added

• delete_container — delete a stopped container by name; refuses if container is still running; requires confirmed=True.

[0.2.0] - 2026-04-14

Added

Images

• list_images — list local images sorted by size; marks images in use and with available updates
• delete_image — delete image by name:tag or hash; refuses if image is used by a container

Container

• container_stats — live CPU %, RAM used/limit, network I/O, block I/O

System

• system_df — Docker disk usage: image count/size, running/stopped containers, reclaimable space
• system_prune — remove dangling images, stopped containers, and unused networks

Networks

• list_networks — list all Docker networks with driver, subnet, gateway, attached containers
• create_network — create a new bridge (or other driver) network
• delete_network — delete a network; refuses if any container is still attached

Fixed

• get_container_status now reads the correct DSM response fields (details.State for status/running, profile.image for image name) and displays IP addresses, port bindings, and mounts
• redeploy_project is now status-aware: RUNNING → stop + start; STOPPED → start directly; BUILD_FAILED → force-stop + start; unknown status returns a clear error with workaround hint
• Container names with hash prefix (e.g. f93cb8b504f7_jenkins) are now transparently stripped in list_containers, container_stats, get_container_status, get_container_logs, and exec_in_container

Changed

• DsmClient gained a post_request() method for form-encoded POST operations required by image delete, network create/delete

[0.1.0] - 2026-04-13

Added

• Initial implementation
• Projects: list_projects, get_project_status, start_project, stop_project, redeploy_project
• Containers: list_containers, get_container_status, get_container_logs, exec_in_container
• Compose: read_compose, update_compose, update_image_tag, update_env_var
• Images: check_image_updates
• DSM session management with auto re-authentication on session timeout
• OS keyring integration for secure credential storage
• 2FA / device token support
• Interactive setup wizard and check connectivity command