Fix Claude Desktop config to use uvx

[cmeans-claude-dev]

Summary

• Setup snippet: changed from uv --directory <cwd> run mcp-synology to uvx mcp-synology — resolves reliably without needing ~/.local/bin in PATH
• README snippet: updated to match (uvx mcp-synology instead of bare mcp-synology)
• Migration script: now auto-detects and updates claude_desktop_config.json (Linux/macOS/Windows paths) instead of just printing a manual reminder

Context

After publishing v0.4.0 to PyPI and installing via uv tool install, Claude Desktop failed with ENOENT because the bare mcp-synology command wasn't in its PATH. The uvx approach resolves the package from PyPI without PATH dependencies.

Test plan

• Run python scripts/migrate-from-synology-mcp.py (dry run) — verify Claude Desktop section appears
• Run mcp-synology setup — verify generated snippet uses uvx
• Verify uvx mcp-synology serve --config ... launches correctly

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

QA Review — Round 1

Scope: 3 files changed (+101/−12), single commit. Code review + CI check.

CI Status

All checks pass: lint ✅, typecheck ✅, test (3.11/3.12/3.13) ✅

Code Review

setup.py — Clean change. uv --directory <cwd> run → uvx is correct. Removes path dependency. The <path-to-uvx> fallback placeholder is a reasonable UX choice.

README.md — Snippet updated to match. Consistent with setup.py output.

migrate-from-synology-mcp.py — New migrate_claude_desktop_config() function. Detection logic for old-style configs is sound. Two findings:

---

Findings

1. (substantive) No backup before writing claude_desktop_config.json

migrate_claude_desktop_config modifies the user's Claude Desktop config in place with config_path.write_text(json.dumps(...)). If the write fails mid-stream or the reformatted JSON causes unexpected behavior, the user loses their working config. The rest of this script already handles state carefully (e.g., skip-if-exists logic for directory moves). A .bak copy before writing would be consistent:

if not dry_run:
    backup = config_path.with_suffix(".json.bak")
    shutil.copy2(config_path, backup)
    config_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
    print(f"  SAVED {config_path} (backup: {backup})")

2. (observation) Extra args silently dropped during migration

The migration rebuilds args from scratch as ["mcp-synology", "serve"] + optional --config. If a user had additional flags in their old config (e.g., --verbose, --host, --port), those would be silently dropped. Unlikely in practice for the old synology-mcp package, but worth noting. Could log a warning if len(args) suggests extra flags were present.

---

Summary

One substantive finding (no backup), one observation. The core logic is correct and the setup.py/README changes are clean.

[cmeans]

Adding QA Failed — one substantive finding: migration script should back up claude_desktop_config.json before modifying it in place. See review for details.

[cmeans]

QA Review — Round 2

Commit: e930637 — Address QA findings: backup config and preserve extra args

Verification

#	Finding	Status
1	No backup before writing claude_desktop_config.json	Fixed — shutil.copy2 creates .json.bak before write
2	Extra args silently dropped	Fixed — new loop preserves non-structural args, logs them

CI remains green. Zero new findings. All Round 1 issues resolved.

Result: Pass — Ready for QA Signoff.

[cmeans]

Adding Ready for QA Signoff — Round 2 passed, all findings resolved, CI green, checkboxes updated.

[cmeans]

Re-opening review — adding QA Active, removing Ready for QA Signoff. Owner flagged missed findings.

[cmeans]

QA Review — Round 3 (deep re-review)

Re-reviewing from scratch per owner request. Previous rounds caught the backup and extra-args issues, but missed the following:

---

New Findings

3. (substantive) --config=value equals syntax not handled

The config path extraction (line 187) checks arg == "--config" — this only matches the space-separated form (--config /path). If a user's Claude Desktop config uses the equals form (--config=/path/to/synology-mcp/config.yaml), two things break:

• config_arg stays None — the synology-mcp to mcp-synology path rename is silently skipped
• In the extra-args loop (line 198), --config=/path/... is NOT in known_old (the set contains bare --config), so it gets treated as an extra arg
• Result: ["mcp-synology", "serve", "--config=/path/to/synology-mcp/config.yaml"] — stale path, no rename

Same issue applies to --directory=value form in the extra-args filter. Click supports both forms, so manual configs could plausibly use either.

4. (nit) Stale comment on line 207

            # Skip the --directory value (path)
            extra_args.append(arg)

Comment says "Skip" but the code appends. Leftover from editing — should be removed or rewritten (e.g., # Not a known structural arg — preserve it).

5. (observation) endswith("synology-mcp") is a loose match (line 178)

is_old_direct uses endswith which would match any command ending in synology-mcp (e.g., a hypothetical my-synology-mcp). Path(cmd).name == "synology-mcp" would be more precise. Low risk in practice.

---

Prior Findings (Round 1-2)

#	Severity	Finding	Status
1	Substantive	No backup before config write	Fixed in e930637
2	Observation	Extra args silently dropped	Fixed in e930637

Summary

One new substantive finding (#3 — equals syntax), one nit (#4 — stale comment), one observation (#5 — loose endswith). The backup and extra-args fixes from Round 2 are solid.

[cmeans]

Keeping QA Active — Round 3 posted with one new substantive finding (equals syntax in --config/--directory not handled), one nit, one observation.

[cmeans]

Adding QA Failed — Round 3 found one new substantive issue (equals syntax in --config/--directory not handled). See review for details.

[cmeans]

QA Review — Round 4

Commits reviewed: a0bb0d3 (README overhaul), 41f543e (QA round 3 fixes)

Round 3 Finding Verification

#	Finding	Status
3	--config=value equals syntax not handled	Fixed — extraction now handles both --config /path and --config=/path; extra-args filter catches startswith(("--config=", "--directory="))
4	Stale comment on line 207	Fixed — replaced with functional startswith check
5	Loose endswith match	Fixed — now Path(cmd).name == "synology-mcp"

README Changes (a0bb0d3)

Good overhaul — uvx is now the primary path, global install demoted to alternative. All CLI examples and JSON snippets consistently use uvx mcp-synology. New migration section at the top with curl one-liner pointing to main branch (will resolve correctly after merge).

CI Status

All checks pass: lint, typecheck, test (3.11/3.12/3.13)

Summary

All findings from rounds 1-3 resolved. Zero new issues. README improvements are clean and consistent.

Result: Pass

[cmeans]

Adding Ready for QA Signoff — Round 4 passed. All findings from rounds 1-3 resolved, zero new issues, CI green.

[cmeans]

LGTM