docs: rewrite README, mark v0.3 complete in CLAUDE.md (v0.3.6)

- README.md: replace v0.1 placeholder with full v0.3.5 reference docs
  (all 26 tools documented with parameters, return values, caveats)
- CLAUDE.md: bump implemented-tools header to v0.3.5; roadmap updated
  (v0.3 complete, v0.4 candidates: none planned)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -146,7 +146,7 @@ src/mcp_synology_filestation/
     └── filestation.py   # register_filestation(mcp, config, client)
 ```
 
-## Implemented Tools (v0.3.4 — 26 tools)
+## Implemented Tools (v0.3.5 — 26 tools)
 
 | Tool                  | Description                                                  |
 |-----------------------|--------------------------------------------------------------|

README.md

@@ -1,40 +1,304 @@
 # mcp-synology-filestation
 
-MCP server for Synology FileStation — browse, search, transfer, and manage files
+MCP server that exposes a **Synology NAS FileStation** as tools for Claude Desktop (and any
-on your NAS via Claude.
+other MCP client). All 26 tools are production-tested against DSM 7.x.
 
-## Status
+---
 
-Work in progress. See [SPEC.md](SPEC.md) for the planned tool set.
+## Features
 
-## Planned Tools
+26 tools covering the full FileStation surface:
 
-| Tool | Description |
+| Group | Tools |
-|------|-------------|
+|-------|-------|
-| `list_shares` | List all shared folders |
+| **Browse** | `list_shares`, `list_dir`, `get_info`, `check_exist`, `search` |
-| `list_dir` | Directory contents with pagination and sorting |
+| **Transfer** | `download`, `upload`, `get_thumbnail` |
-| `get_info` | File or folder metadata |
+| **Organise** | `create_folder`, `rename`, `copy`, `move`, `delete`, `compress`, `extract` |
-| `search` | Recursive pattern search |
+| **Analyse** | `dir_size`, `get_md5`, `check_permission` |
-| `download` | Download a file (base64 content) |
+| **Sharing** | `create_sharing_link`, `list_sharing_links`, `delete_sharing_link` |
-| `create_folder` | Create a new directory |
+| **Favorites** | `list_favorites`, `add_favorite`, `delete_favorite` |
-| `rename` | Rename a file or folder |
+| **System** | `background_tasks`, `list_snapshots` |
-| `move` | Move to a new location |
-| `copy` | Copy to a new location |
-| `delete` | Delete a path (requires confirmation) |
-| `upload` | Upload a file from base64 content |
 
-## Setup
+---
+
+## Requirements
+
+- Python 3.12+
+- [`uv`](https://docs.astral.sh/uv/) (recommended) or pip
+- Synology NAS running DSM 7.x with FileStation enabled
+- A DSM user account with FileStation access
+
+---
+
+## Installation
+
+### From Gitea
 
 ```bash
 uv tool install git+https://gitea.gecheckt.de/marcus/mcp-synology-filestation.git
+```
+
+### Reinstall (upgrade)
+
+```bash
+uv tool install --reinstall git+https://gitea.gecheckt.de/marcus/mcp-synology-filestation.git
+```
+
+> **Windows / Claude Desktop:** close Claude Desktop before reinstalling — Windows holds
+> file locks on running executables.
+
+---
+
+## Setup
+
+Run the interactive wizard once to configure the NAS connection and store credentials
+securely in the OS keyring:
+
+```bash
 mcp-synology-filestation setup
 ```
 
+The wizard will:
+1. Ask for your NAS host, port, and HTTPS settings
+2. Ask for your DSM username and password (stored in OS keyring — never written to disk)
+3. Handle 2FA / device token if required
+4. Verify the FileStation API is reachable
+5. Print a ready-to-paste Claude Desktop config snippet
+
+### Verify the setup
+
+```bash
+mcp-synology-filestation check
+```
+
+---
+
+## Claude Desktop integration
+
+Add the server to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "synology-filestation": {
+      "command": "mcp-synology-filestation",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+The server uses **stdio transport** and is fully compatible with Claude Desktop on
+Windows, macOS, and Linux.
+
+### Environment variable overrides
+
+| Variable | Purpose |
+|----------|---------|
+| `SYNOLOGY_HOST` | Override NAS hostname |
+| `SYNOLOGY_USERNAME` | Override DSM username |
+| `SYNOLOGY_PASSWORD` | Override DSM password (not stored) |
+
+---
+
+## Tool reference
+
+### Browse
+
+#### `list_shares`
+List all shared folders with volume usage (total / used / %).
+
+#### `list_dir`
+List a directory's contents with pagination and sorting.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `path` | — | Share-relative path (e.g. `/docker`, `/data/photos`) |
+| `offset` | 0 | Items to skip |
+| `limit` | 100 | Max items (hard cap: 500) |
+| `sort_by` | `name` | `name` \| `size` \| `user` \| `group` \| `mtime` \| `atime` \| `crtime` \| `type` |
+| `sort_direction` | `asc` | `asc` \| `desc` |
+
+#### `get_info`
+Detailed metadata (size, owner, permissions, timestamps) for one or more paths.
+Accepts comma-separated paths.
+
+#### `check_exist`
+Yes/No existence check for one or more comma-separated paths.
+
+#### `search`
+Glob-pattern search across a directory tree with async DSM polling.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `path` | — | Root directory |
+| `pattern` | — | Filename glob, e.g. `*.log` |
+| `recursive` | `true` | Search subdirectories |
+| `max_results` | 200 | Cap on returned matches |
+
+---
+
+### Transfer
+
+#### `download`
+Download a file as base64-encoded content. Files > 10 MB are rejected.
+Returns JSON: `{filename, size, content_base64}`
+
+#### `upload`
+Upload base64-encoded content to the NAS. Files > 50 MB are rejected.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `path` | — | Destination directory |
+| `filename` | — | Name for the new file |
+| `content_base64` | — | Base64-encoded bytes |
+| `overwrite` | `false` | ⚠ Overwrites existing file if `true` |
+| `create_parents` | `true` | Create missing parent directories |
+
+#### `get_thumbnail`
+Fetch a JPEG thumbnail for an image or video file.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `path` | — | Share-relative file path |
+| `size` | `small` | `small` \| `medium` \| `large` \| `original` |
+
+Returns JSON: `{filename, size_bytes, content_base64}`.
+A `"warning"` field is added when the thumbnail exceeds ~500 KB base64.
+Thumbnails > ~2 MB base64 are rejected with an error — use `size=small` in that case.
+
+> **Note:** The DSM `quality` parameter has no effect — DSM ignores it. `size=small` is
+> the default and recommended value; larger sizes can exceed MCP buffer limits.
+
+---
+
+### Organise
+
+#### `create_folder`
+Create a folder. Set `create_parents=true` to create intermediate directories.
+
+#### `rename`
+Rename a file or folder. `new_name` is a bare name (not a full path).
+
+#### `copy` / `move`
+Async copy or move. Default `overwrite=false`.
+
+#### `delete`
+**Irreversible.** Requires `confirmed=true`.
+Without it, returns a preview of what would be deleted — nothing is removed.
+
+#### `compress`
+Compress one or more paths into a ZIP or 7z archive (async DSM task).
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `paths` | — | List of source paths |
+| `dest_file_path` | — | Output archive path including filename |
+| `level` | `moderate` | `store` \| `fastest` \| `fast` \| `normal` \| `moderate` \| `maximum` |
+| `format` | `zip` | `zip` \| `7z` |
+| `password` | `""` | Archive password |
+
+#### `extract`
+Extract a ZIP or 7z archive to a destination folder (async DSM task).
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `file_path` | — | Archive path on NAS |
+| `dest_folder_path` | — | Destination directory |
+| `overwrite` | `false` | ⚠ Overwrite existing files if `true` |
+| `keep_dir` | `true` | Preserve directory structure |
+| `create_subfolder` | `false` | Extract into a new subfolder |
+| `password` | `""` | Archive password |
+
+---
+
+### Analyse
+
+#### `dir_size`
+Total size, file count, and folder count for one or more directories (comma-separated).
+
+#### `get_md5`
+Compute the MD5 checksum of a file.
+
+#### `check_permission`
+Check whether the current DSM user can write a given filename into a directory.
+
+---
+
+### Sharing
+
+#### `create_sharing_link`
+Create a public sharing link with optional password and expiry date (`YYYY-MM-DD`).
+
+#### `list_sharing_links`
+Paginated table of all sharing links (ID, URL, path, owner, expiry, status).
+
+#### `delete_sharing_link`
+Delete a sharing link by its ID (from `list_sharing_links`).
+
+---
+
+### Favorites
+
+#### `list_favorites`
+List all FileStation user favorites (name, path, type, status, real path, modified).
+
+#### `add_favorite`
+Pin a path as a FileStation favorite with a display label.
+
+#### `delete_favorite`
+Remove a favorite by its path.
+
+---
+
+### System
+
+#### `background_tasks`
+Paginated list of active/recent FileStation background tasks
+(copy, move, delete, extract, compress) with type, status, path, and file progress.
+
+> Only the `list` method is available on DSM 7.x — tasks cannot be cancelled via this API.
+
+#### `list_snapshots`
+List Btrfs snapshots for a shared folder (snapshot ID, creation time, description, locked).
+
+> Requires a Btrfs-formatted volume. Returns a clear error on ext4/non-Btrfs shares
+> ("requires Btrfs-formatted volume").
+
+---
+
 ## Development
 
 ```bash
+# Install with dev dependencies
 uv sync --dev
+
+# Format
+uv run ruff format src/ tests/
+
+# Lint
+uv run ruff check src/ tests/
+
+# Tests (113 tests)
 uv run pytest
-uv run ruff check src/
+
-uv run ruff format src/
+# Run server locally (stdio)
+uv run mcp-synology-filestation serve
 ```
+
+See [CLAUDE.md](CLAUDE.md) for the full development context and
+[SPEC.md](SPEC.md) for DSM API call details and quirks.
+
+---
+
+## Security
+
+- Passwords are stored in the **OS keyring only** — never in the config file or logs.
+- Session IDs and credentials are masked in all debug output.
+- The `delete` tool requires explicit `confirmed=true` to prevent accidents.
+
+---
+
+## License
+
+MIT

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-synology-filestation"
-version = "0.3.5"
+version = "0.3.6"
 description = "MCP server for Synology FileStation"
 requires-python = ">=3.12"
 dependencies = [

src/mcp_synology_filestation/__init__.py

@@ -1,3 +1,3 @@
 """MCP server for Synology FileStation."""
 
-__version__ = "0.3.5"
+__version__ = "0.3.6"