marcus
80ac894165
All path/name params are json.dumps-wrapped per confirmed DSM behaviour. copy and move use async polling via a shared _poll_task helper (exponential backoff 200ms→2s, 60s timeout). delete requires confirmed=True; without it only a preview is returned and no DSM call is made. upload decodes base64 and enforces a 50 MB cap. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
# 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](SPEC.md) for the full planned tool set.
|