# Reported issues for Synology NAS

Pod holds 16 of 29 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Synology NAS](/mcp/synology-nas).

## Most discussed

### Wire ServerState load_state / save_state lifecycle in SharedClientManager

## Summary

Surfaced as F2 on PR #73 (#37 fix) — one of two ACs from #37 that's deferred to a follow-up. Filing now so "Closes #37" on PR #73 is honest about scope.

`src/mcp_synology/core/state.py` defines `ServerState` with `api_info_cache`, `negotiated_versions`, `recycle_bin_status`, and a few connection metadata fields. The model exists, `load_state(instance_id)` / `save_state(instance_id, state)` are implemented and (since #69) write atomically. But:

- `src/mcp_synology/server.py:83` cons

[Read the thread](https://github.com/cmeans/mcp-synology/issues/75) · 2026-05-01 · open · outside contributor · 1 comment

### Learn usage patterns from tool telemetry (downstream of #48)

## Summary

Post-baggage feature opportunity, depends on #48 landing first.

Once write-operation events are flowing to awareness, a background aggregator (or just periodic human-driven review via the awareness `search` / `get_knowledge` tools) can spot patterns:

- 'User deletes `*.tmp` files in `/video/Downloads` every Sunday' → `learn_pattern` so cleanup suggestions are proactive.
- 'User copies from `/photo/Camera` to `/photo/Sorted/YYYY-MM` every weekend' → pattern matching for assistance.

[Read the thread](https://github.com/cmeans/mcp-synology/issues/50) · 2026-04-16 · open · outside contributor · 1 comment

### New module: Storage + health tools that feed awareness alerts

## Summary

Post-baggage feature opportunity surfaced during the 2026-04-16 review. The `system` module exposes `get_system_info` and `get_resource_usage` today — point-in-time queries the user has to remember to run. For a NAS, the interesting questions are anomaly-driven: 'is anything going wrong?' The right place to put that signal is the awareness briefing.

## Proposal

New `storage` module (or expand `system`) with:

- `get_volume_status()` — healthy / degraded / crashed / rebuilding, free

[Read the thread](https://github.com/cmeans/mcp-synology/issues/49) · 2026-04-16 · open · outside contributor · 1 comment

### Awareness integration: emit add_context events after significant write operations

## Summary

Opportunity surfaced during the 2026-04-16 review (post-baggage). Expanding the DSM tool surface creates a parallel opportunity: give the user durable, cross-platform memory of what actually happened on their NAS.

Claude Code on this workstation can see the operations it ran. Claude.ai on the couch, Claude Desktop on a phone, and future agents cannot — unless we write to awareness. When a user asks 'what did I do with my movies last month?' the answer today is 'grep my shell history

[Read the thread](https://github.com/cmeans/mcp-synology/issues/48) · 2026-04-16 · open · outside contributor · 1 comment

### Tidy-up bundle: test duplication, setup input stripping, fallback truthiness, minor robustness

## Summary

A batch of small, low-risk cleanups surfaced during the 2026-04-16 project-wide review. None are bugs on their own; grouped here to keep the baggage list short.

## Items

- [ ] **BASE_URL duplicated** across `tests/conftest.py:16` and `tests/core/test_client.py:18`. Import the conftest value everywhere.
- [ ] **Test helpers duplicated** — `_make_client()` / `_default_cache()` in `tests/core/test_client.py` and `make_test_config()` / `make_api_cache()` in `tests/conftest.py` overlap.

[Read the thread](https://github.com/cmeans/mcp-synology/issues/45) · 2026-04-16 · closed · outside contributor · 2 comments

### CLAUDE.md 'three ways to enable debug' is misleading for serve invocations

## Summary

`CLAUDE.md` says there are three ways to enable debug logging: `mcp-synology check -v` (CLI flag), `SYNOLOGY_LOG_LEVEL=debug` (env var), and `logging.level: debug` (config). But the `serve` subcommand — the one Claude Desktop actually invokes — has no `-v` flag (this is acknowledged in the doc, but only in a short parenthetical).

Readers skim the bullet list and walk away thinking they can pass `-v` to `serve`. They can't. Only env var or config applies.

## Acceptance criteria

- [

[Read the thread](https://github.com/cmeans/mcp-synology/issues/43) · 2026-04-16 · closed · outside contributor · 1 comment

### Document Upload v2 pin in CLAUDE.md alongside CopyMove/Delete/Search

## Summary

`src/mcp_synology/core/client.py:354` pins the Upload API to `min(info.max_version, 2)` for the same reason CopyMove/Delete/Search are pinned — DSM v3 uses a JSON request format that causes silent failures. The rationale is in the code comment but `CLAUDE.md` only lists CopyMove/Delete/Search as v2-pinned APIs (`## Key Conventions → DSM API Client`).

A future refactor could remove the pin without realizing why it was added, because the written convention doesn't mention Upload.

## 

[Read the thread](https://github.com/cmeans/mcp-synology/issues/42) · 2026-04-16 · closed · outside contributor · 1 comment

### 'additional' parameter not exposed on list_shares / list_files / search_files tools

## Summary

The underlying handlers `list_shares()`, `list_files()`, and `search_files()` all accept an `additional` parameter — a list of DSM metadata fields to request (e.g., `["real_path", "size", "owner", "perm"]`). The spec at `docs/specs/filestation-module-spec.md:117` declares `additional` as a configurable parameter with a default. However, the FastMCP tool registrations (`src/mcp_synology/modules/filestation/__init__.py`) hardcode the list internally and never surface it as a tool param

[Read the thread](https://github.com/cmeans/mcp-synology/issues/41) · 2026-04-16 · closed · outside contributor · 1 comment

## Most recent

### vdsm: add Download Station integration test coverage

## Background

Phase 1 (#104) and Phase 2 (#105) of the Download Station module shipped with the design-doc note "vdsm integration tests — out of scope; vdsm doesn't ship the Download Station package." This issue tracks the work to add DS to the vdsm golden image so CI exercises DS tools against a real DSM instance.

## Scope

- Install Download Station into the vdsm golden image at bake time via Playwright through Package Center UI (matches the existing operator-driven Playwright pattern in `te

[Read the thread](https://github.com/cmeans/mcp-synology/issues/106) · 2026-05-14 · open · outside contributor · 0 comments

### Phase 2 (downloadstation): use negotiate_version(max_version=2) for Task.list / Task.getinfo

## Background

Phase 1 of the Download Station module (Plan + spec at `docs/superpowers/specs/2026-05-13-downloadstation-module-design.md`) shipped `list_downloads` and `get_download_info` with `version=1` hard-pinned on both calls.

The spec's Data Flow section says:

> **DS2 dip:** \`Task.list\` and \`Task.getinfo\` try v2 first if available (richer \`additional\` fields), fall back to v1.

…but Phase 1 deliberately kept v=1 across the board because the spec also has an Open Questions section 

[Read the thread](https://github.com/cmeans/mcp-synology/issues/103) · 2026-05-13 · open · outside contributor · 0 comments

### Operational test coverage gaps: re-auth retry on upload/download, get_dir_size edge cases, restore_from_recycle_bin integration

## Motivation

Companion to #96. Where #96 systematizes coverage for the **multipath/array-flattening regression class**, this issue tracks operational error-path gaps in the File Station and core client that are unrelated to multipath — specifically session re-auth retries, async-task edge cases on `get_dir_size`, and the absence of any integration/vdsm exercise of `restore_from_recycle_bin`.

Verified against current code at `8b0d200` (post-#97 merge). One scope item from the original brain-du

[Read the thread](https://github.com/cmeans/mcp-synology/issues/99) · 2026-05-04 · open · outside contributor · 0 comments

### create_folder silently mangles multi-path arrays (regression in v0.5.2)

## Summary

`create_folder` with multiple paths in `paths=` does not create N folders. DSM receives the comma-joined `name` as a single literal name and the comma-joined `folder_path` as a single literal parent, so one folder with a mangled name is created (or an error surfaces — but not always). The tool reports `"Created 1 folder(s):"` regardless, so the failure is silent from the caller's perspective.

QA reproducer:
- Call: `create_folder(paths=['/<share>/__cftest_a', '/<share>/__cftest_b'])

[Read the thread](https://github.com/cmeans/mcp-synology/issues/95) · 2026-05-02 · closed · outside contributor · 0 comments

### Read-modify-write race on ~/.local/state/mcp-synology/global.yaml

## Summary

`atomic_write_text` (PR #69) prevents torn writes via `os.replace`, so a single write is always all-or-nothing. But the **read-modify-write** sequence — load YAML → mutate dict → save — has no synchronization between processes. Three callers can interleave:

1. Main process startup writes `running_version` and `previous_version`.
2. Background update task writes `last_version_check` and `latest_known_version`.
3. Manual `mcp-synology --check-update` writes the same as #2.

If two of 

[Read the thread](https://github.com/cmeans/mcp-synology/issues/93) · 2026-05-02 · closed · outside contributor · 0 comments

### bug: pr-labels-ci.yml is pre-hardening (shell-injection risk) and lacks the PR-#28 comment escape

## Summary

`.github/workflows/pr-labels-ci.yml` on this repo has two related issues that have been fixed in sibling `cmeans/*` repos:

1. **Shell-injection surface on fork PRs (pre-PR-#87 state).** The current file inlines `${{ github.event.workflow_run.head_branch }}` directly inside `run:` blocks. `head_branch` is contributor-controlled on fork PRs, and git refnames allow shell metacharacters (`$`, backtick, `;`, `&`, `|`, etc.), so a malicious fork branch name renders as directly-executed sh

[Read the thread](https://github.com/cmeans/mcp-synology/issues/52) · 2026-04-20 · closed · outside contributor · 0 comments

### ADR needed: per-client DSM sessions (session_key parameter) and Streamable HTTP roadmap

## Summary

`docs/specs/architecture.md` documents a future `session_key` parameter on `AuthManager.get_session()` to enable per-MCP-client DSM sessions under Streamable HTTP. The current implementation (`src/mcp_synology/core/auth.py:196`) is `async def get_session(self) -> str:` — the parameter is absent, and `logout()` (`auth.py:177-194`) hardcodes `_session_name` with no way to derive a per-client variant.

So long as the server runs under stdio (single MCP client per process), this is fine.

[Read the thread](https://github.com/cmeans/mcp-synology/issues/47) · 2026-04-16 · closed · outside contributor · 1 comment

### publish.yml: gate PyPI on MCP-registry schema validation to avoid half-published releases

## Summary

`.github/workflows/publish.yml` runs `publish-pypi` first, then `publish-registry`. The registry step is idempotent on duplicate-version errors (PR #28), but if the registry rejects `server.json` for a *schema* reason (not a duplicate — e.g. a new required field in a future mcp-publisher release), PyPI will already have published. The world then has a discoverable PyPI release that isn't in the MCP registry, and re-running the workflow can't fix PyPI.

The `validate-server-json` job 

[Read the thread](https://github.com/cmeans/mcp-synology/issues/44) · 2026-04-16 · closed · outside contributor · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/cmeans/mcp-synology/issues).