feat: initial project structure

2026-04-14 07:51:51 +02:00
commit 9fc5a3d68c
15 changed files with 597 additions and 0 deletions
@@ -0,0 +1,95 @@
+# 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
+
+_(none yet — pending implementation approval)_
+
+See [SPEC.md](SPEC.md) for the full planned tool set.