CLAUDE.md — mcp-synology-filestation

Development context for this project.

Project

mcp-synology-filestation — MCP server exposing Synology FileStation as Claude tools. Sibling project to mcp-synology-container.

Infrastructure

NAS: https://dsm.gecheckt.de
Config file: ~/.config/mcp-synology-filestation/config.yaml
Credentials: OS keyring, service name mcp-synology-filestation
Gitea: https://gitea.gecheckt.de/marcus/mcp-synology-filestation
Local code: D:\Dev\Projects\mcp-synology-filestation
Runtime: Python 3.12+, uv, MCP SDK, httpx, keyring, click, rich

Deploy Workflow

Commit and push via Claude Code.
uv tool install --reinstall git+https://gitea.gecheckt.de/marcus/mcp-synology-filestation.git
Restart Claude Desktop.

Toolchain

Task	Command
Format	`ruff format src/ tests/`
Lint	`ruff check src/ tests/`
Tests	`pytest`
Install dev	`uv sync --dev`
Run server	`uv run mcp-synology-filestation serve`
Setup	`uv run mcp-synology-filestation setup`

Code Standards

Type hints on all public functions and methods.
Docstrings (English) on all public modules, classes, and functions.
Async-first: use httpx.AsyncClient throughout; never requests.
Formatter: ruff format (line length 100).
Linter: ruff check — fix all warnings before committing.

Security Rules

Never log or write credentials, session IDs, or passwords to disk or stderr.
Never store passwords in the config YAML — OS keyring only.
Mask sensitive query parameters (_sid, passwd) before logging request URLs.

Destructive Operation Rules

delete, move with overwrite=True, copy with overwrite=True, and upload with overwrite=True are considered destructive.
The delete tool MUST require confirmed=True to proceed. Without it, return a preview message that describes exactly what would be deleted — never silently proceed.
For overwrite scenarios in move/copy/upload, include a warning in the tool description and default overwrite to False.

Error Handling Rules

DSM error codes must be mapped to human-readable messages. See SPEC.md for the full map.
Never surface raw Python stack traces in tool return values.
Session expiry (codes 106, 107, 119): transparent single retry with re-login.
Network errors: return "Cannot reach NAS at {host} — check connectivity."
Auth failures (400–403): return message + "Run mcp-synology-filestation setup to reconfigure credentials."

Tool Return Format

All tools return str.
Use rich.table.Table (rendered to string) for tabular data.
Include item counts and pagination hints where relevant.
Error messages are prefixed with Error: for easy recognition by Claude.

Module Structure

src/mcp_synology_filestation/
├── __init__.py      # __version__
├── __main__.py      # entry point
├── server.py        # create_server(config, client) → FastMCP
├── client.py        # FileStationClient (async httpx wrapper)
├── auth.py          # AuthManager: keyring, env vars, 2FA, login/logout
├── config.py        # AppConfig, ConnectionConfig, load_config, save_config
├── cli.py           # click: setup / check / serve
└── tools/
    ├── __init__.py
    └── filestation.py  # register_filestation(mcp, config, client)

Implemented Tools

(none yet — pending implementation approval)

See SPEC.md for the full planned tool set.

3.5 KiB Raw Blame History Unescape Escape