mcp-synology-filestation/CLAUDE.md

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

1. Commit and push via Claude Code.
2. uv tool install --reinstall git+https://gitea.gecheckt.de/marcus/mcp-synology-filestation.git
3. 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

Tool	Description
list_shares	List all shared folders with volume usage
list_dir	List directory contents with pagination and sorting
get_info	Get detailed metadata for one or more paths
search	Search for files by glob pattern with async polling
download	Download a file as base64 (max 10 MB)
create_folder	Create a new folder (optionally with parent dirs)
rename	Rename a file or folder
copy	Copy a file or folder (async polling, overwrite=False default)
move	Move a file or folder (async polling, overwrite=False default)
delete	Delete a file or folder — requires confirmed=True
upload	Upload base64-encoded content to a path (max 50 MB)

See SPEC.md for the full planned tool set.