marcus
f27a5456f6
Three new SYNO.Docker.Registry tools, reverse-engineered from a live DSM API capture (n4s4 reference disagrees on param names and methods). - search_registry (#5): SYNO.Docker.Registry/search v1 with JSON-encoded q, plus offset/limit/page_size. Renders stars, downloads, official flag, truncated description, and total match count. Read-only. - list_image_tags: SYNO.Docker.Registry/tags v1 with JSON-encoded repo (not name — DSM live capture diverges from n4s4). Response shape is unusual: tag list comes back as the envelope's data field directly. Output capped by limit (default 50); accepts both list and dict response shapes defensively. Read-only. - pull_image (#3): SYNO.Docker.Registry/pull_start v1 with both repository and tag JSON-encoded. Async pull — no pull_status method confirmed on this DSM, so completion is detected by polling SYNO.Docker.Image/list (2–10 s backoff, 240 s budget under the Claude Desktop ~4 min tool-call ceiling). Timeout returns a non-fatal "still running" hint. Short-circuits when the image is already present locally. Confirmation gate required. Tool count: 31 → 34. CLAUDE.md confirmation list updated. New DSM quirks documented for pull_start (no pull_status) and tags (repo param name, top-level data array). Closes #3 Closes #5 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
118 lines
5.3 KiB
Markdown
118 lines
5.3 KiB
Markdown
# mcp-synology-container
|
||
|
||
## Project
|
||
|
||
`mcp-synology-container` is an MCP server for managing Docker projects on a
|
||
Synology DiskStation via Container Manager. It exposes tools for projects,
|
||
containers, images, compose files, networks, and system housekeeping.
|
||
|
||
---
|
||
|
||
## Tech stack
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Language** | Python 3.12+, `uv` |
|
||
| **Key deps** | MCP SDK, `httpx`, `keyring`, `click`, `rich` |
|
||
| **Compose paths** | `/volume1/docker/<project>/` (default Synology layout) |
|
||
|
||
---
|
||
|
||
## Deploy workflow (after every code change)
|
||
|
||
```
|
||
1. Claude Code commits and pushes
|
||
2. uv tool install --reinstall git+<repo-url>
|
||
3. Restart Claude Desktop (tray icon → Quit → relaunch)
|
||
```
|
||
|
||
**Push retry:** the Gitea remote (`gitea.gecheckt.de`) occasionally
|
||
returns `Unauthorized` on the first push attempt. If `git push` fails
|
||
with an auth error, wait 1 s and retry once before reporting back.
|
||
Only a second consecutive failure is treated as a real auth problem.
|
||
|
||
---
|
||
|
||
## Implemented tools (34)
|
||
|
||
| Category | Tools |
|
||
|---|---|
|
||
| Projects | `list_projects`, `get_project_status`, `start_project`, `stop_project`, `redeploy_project`, `create_project`, `delete_project` |
|
||
| Containers | `list_containers`, `get_container_status`, `get_container_logs`, `exec_in_container`, `container_stats`, `delete_container`, `start_container`, `stop_container`, `restart_container` |
|
||
| Compose | `read_compose`, `update_compose`, `update_image_tag`, `update_env_var` |
|
||
| Images | `check_image_updates`, `list_images`, `delete_image`, `inspect_image` |
|
||
| Registry | `search_registry`, `list_image_tags`, `pull_image` |
|
||
| Networks | `list_networks`, `create_network`, `delete_network` |
|
||
| System | `system_df`, `system_prune`, `system_overview` |
|
||
|
||
---
|
||
|
||
## DSM API quirks
|
||
|
||
- **Hash-prefixed container names** — DSM sometimes returns names like
|
||
`a1b2c3d4e5f6_myservice` when the compose service name differs from
|
||
`container_name`. All container tools strip this prefix transparently via
|
||
`_strip_hash_prefix` / `_resolve_container_name`.
|
||
- **Async project start** — `SYNO.Docker.Project/start` returns immediately
|
||
while containers are still initialising. `redeploy_project` polls
|
||
`SYNO.Docker.Project/list` every 2 s for up to 30 s after issuing start.
|
||
- **Image delete** — requires a form-encoded POST with a JSON `images` array
|
||
(confirmed via browser DevTools); uses `DsmClient.post_request()`.
|
||
- **`SYNO.Docker.Image/pull`** — API method exists but behaviour varies by
|
||
DSM version; not exposed as a standalone tool. `pull_image` uses
|
||
`SYNO.Docker.Registry/pull_start` instead (see below).
|
||
- **`SYNO.Docker.Registry/pull_start`** — asynchronous pull entry point;
|
||
no matching `pull_status` method confirmed. `pull_image` polls
|
||
`SYNO.Docker.Image/list` until `repository:tag` appears (2–10 s backoff,
|
||
240 s budget) and returns a "still running" hint on timeout instead of
|
||
raising — DSM keeps pulling server-side regardless of the HTTP response.
|
||
- **`SYNO.Docker.Registry/tags`** — uses `repo` (JSON-encoded) as the
|
||
parameter name; the n4s4 reference's `name` does not work on this DSM
|
||
version. Returns the tag list as the envelope's `data` field directly,
|
||
not wrapped in a sub-key.
|
||
- **`SYNO.Docker.Volume`** — endpoint does not exist; volume management is
|
||
not available via the DSM WebAPI.
|
||
- **`SYNO.Docker.Registry/get`** — does not behave as documented; registry
|
||
listing omitted.
|
||
- **`SYNO.Docker.Container/pause` and `/unpause`** — not implemented in
|
||
DSM Container Manager on this firmware. The action menu only offers
|
||
start/stop/force-stop/restart/reset; calls to `pause`/`unpause` return
|
||
"Method does not exist". `pause_container` and `unpause_container`
|
||
were briefly shipped in 0.4.0 and removed in 0.4.1.
|
||
|
||
---
|
||
|
||
## Implementation rules
|
||
|
||
- Confirmation required before destructive operations: `stop_project`,
|
||
`redeploy_project`, `create_project`, `delete_project`,
|
||
`exec_in_container`, `update_image_tag`, `update_env_var`,
|
||
`update_compose`, `delete_container`, `stop_container`,
|
||
`restart_container`, `pull_image`
|
||
- After compose changes: suggest `redeploy_project`
|
||
- DSM errors → human-readable message, no stack traces
|
||
- No secrets in stderr output
|
||
- Type hints and docstrings everywhere
|
||
- Formatter: `ruff format` · Linter: `ruff check` · Tests: `pytest`
|
||
- All text (docstrings, comments, README): English
|
||
- **CHANGELOG.md:** every user-visible change (bug fix, new/changed
|
||
tool, behavior change, security fix, dependency bump) gets a
|
||
`CHANGELOG.md` entry in the same commit — under a `## [Unreleased]`
|
||
heading between releases, which becomes `## [X.Y.Z] - YYYY-MM-DD` on
|
||
version bump. Pure internal cleanup (renames without external callers,
|
||
comment-only edits, ruff autofix) needs no entry. Don't ship a release
|
||
with a stale changelog (this was the C-2 gap that caused 0.2.7 and
|
||
0.2.8 to ship undocumented).
|
||
- **Version consistency:** the package version lives in `pyproject.toml`
|
||
and must stay in sync with `uv.lock` and the `[X.Y.Z]` heading in
|
||
`CHANGELOG.md`. `src/mcp_synology_container/__init__.py` derives
|
||
`__version__` from `importlib.metadata` and is never hand-edited.
|
||
Every version bump touches all three files in the same commit.
|
||
|
||
---
|
||
|
||
## DSM API reference
|
||
|
||
- `cmeans/mcp-synology` (GitHub) — auth, keyring, CLI structure
|
||
- `N4S4/synology-api` `docker_api.py` (GitHub) — `SYNO.Docker.*` calls
|