proton-drive-mcp 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 1.3.0 — 2026-09-30
+
+Proton Drive has no search, and its end-to-end encryption rules out server-side indexing. This release adds the client-side layer: find things, understand what uses your space, and clean up safely. 4 builders worked in parallel, then 3 verifiers (live on a real account, an independent security review, packaging/CI) and a re-check of every fix. Review findings fixed before release include two ReDoS vectors in search and a local-path guard gap.
+
+### Added
+- **`drive_tree`** and **`drive_search`** (also in the `core` tier): a bounded, parallel walk of the drive (8 concurrent calls, `.git` and `node_modules` skipped, call cap, cancellable) with a 5-minute in-memory cache that the server's own writes invalidate. Search by name, glob (relative to the search folder when it contains `/`), extension, media type, size and date, with stable pagination. The first walk of a large drive takes minutes (about 25 s per 1,200 files); later calls are instant.
+- **`drive_usage`**: largest files and folders, breakdown by type, old files and trash stats (sums of file sizes, not the account quota).
+- **`drive_find_duplicates`**: groups by the uploader-claimed sha1 or by size; `verify` downloads and hashes candidates within a size and total budget. It never deletes.
+- **`drive_sharing_audit`**: public links (role, expiry, password; the URL is never printed), invitees, pending invitations and risk flags.
+- **`drive_sync_plan`**: compares a local folder with a Drive folder (plan only).
+- **`drive_bulk_move`** and **`drive_bulk_trash`**: up to 200 items in one batched call. Always two steps: without `confirmed` you get a plan and any problems; `confirmed:true` applies only if there are none. Trash stays reversible.
+- **MCP prompts** (`organise-folder`, `find-files`, `storage-audit`, `sharing-audit`), listed only when the tools they need are in the active tier; also declared in the MCPB manifest.
+- **Human confirmation through elicitation** for clients that support it (Claude Code CLI; Claude Desktop is unverified): gated calls and bulk applies ask the person instead of only failing. Clients without it behave as before. It does not protect against a model that passes `confirmed:true` itself.
+- `drive_list` and `drive_info` now return `mtime`, `uploadedAt` and `sha1` (claimed, often absent); `drive_list` takes a `type` filter; `drive_share_status` adds `shareUrlRole`.
+- Tool titles on every tool, corrected annotations (for example `drive_trash` is not destructive), `maxResultSizeChars` hints on the large-result tools.
+
+### Changed
+- The full tool list is now 46 tools (about 39 KB, was 29.5 KB); `core` is 18 tools (16.8 KB). Use `PROTON_DRIVE_TOOL_TIER=core` to keep the token cost down.
+- Folder uploads and `drive_sync_plan` refuse a local folder that contains protected locations (home directory, `/`, `~/.ssh`, ...); scans skip secret-named files and report `protectedSkipped`. Downloads into your home folder still work. Note that for uploads the CLI does the recursion, so a `.env` inside an uploaded subfolder is not filtered.
+- `.gitignore` covers `node_modules` as a symlink too.
+
+### Known limitations
+- Windows is not supported. The CLI has no search, version history, quota or change notifications, so none of those are offered.
+- The walk cache does not see changes made by other clients until it expires or `refresh:true`.
+- `drive_share_leave`, `drive_invitation_accept` and `drive_invitation_reject` have never been tested live (no second Proton account). Elicitation and prompts are verified with the official SDK client and Claude Code semantics, not with Claude Desktop.
+
+## 1.2.0 — 2026-09-28
+
+Setup, packaging and reliability round. Five features were built in parallel on separate branches, merged, then verified live (real account, 3 concurrent servers), on Node 22/24 and on the new Ubuntu + macOS CI matrix, plus an independent code review. Review and CI findings were fixed before release.
+
+**Breaking:** Node 20 is no longer supported (`engines` is `>=22`; Node 20 is past end-of-life). It may still start, but it is not tested and `doctor` fails on it.
+
+### Added
+- **`proton-drive-cli doctor`**: checks Node, the `proton-drive` CLI, login state, sync folder and the Claude Desktop config; `--json` output; exits 1 on failure. It only reports on our own config entry, never other servers' entries.
+- **`proton-drive-cli setup-claude-desktop`**: prints (default) or writes (`--write`) the Claude Desktop entry with absolute paths. Touches only `mcpServers["proton-drive-mcp"]`, keeps a timestamped `.bak`, writes atomically, skips the write if nothing changed, and refuses to run from a temporary `npx` cache or on invalid JSON.
+- **MCPB bundle** (`npm run package:mcpb`): one-click Claude Desktop extension attached to each GitHub release (macOS and Linux only; installing it into Claude Desktop is untested).
+- **`PROTON_DRIVE_TOOL_TIER=core`**: exposes 16 everyday tools (~13 KB of tool definitions instead of ~29 KB). Hidden tools are refused at call time. Tool descriptions were also shortened; every safety note was kept.
+- **Retry of read-only calls** on rate limiting, timeouts and network errors (max 3 attempts, bounded by the call timeout). Mutating and transfer commands are never retried.
+- **CI**: Ubuntu and macOS × Node 22/24, non-blocking Windows probe; publish workflow is ready for npm Trusted Publishing (the `NPM_TOKEN` fallback stays until one OIDC publish has succeeded).
+
+### Fixed
+- An empty `PROTON_DRIVE_BIN` (some clients pass `""` for an optional setting) is now treated as unset.
+- The README Claude Desktop snippets use the same server key as `setup-claude-desktop` (`proton-drive-mcp`), so `doctor` finds it.
+- Local-path guard: an unreadable ancestor directory (such as `/var/root` for a non-root user) no longer aborts the denylist check with a raw `EACCES`.
+
+### Known limitations
+- Windows is not supported (tests never passed there; only probed in CI).
+- `drive_share_leave`, `drive_invitation_accept` and `drive_invitation_reject` have never been tested live (no second Proton account).
+- The MCPB bundle and the npm OIDC publish path have not been exercised against the real Claude Desktop / npm yet.
+
 ## 1.1.0 — 2026-09-28
 
 A "test it like Mail Bridge" round: 6 agents live-tested every tool group against a real account for the first time at scale — full-byte round trips up to 200 MB, the real Proton Drive sync folder, real photo uploads/albums, three MCP servers sharing one CLI session concurrently, official MCP clients (SDK, Inspector, Node 20/22/24, a packed-and-installed tarball), and adversarial edge cases. 3 high-severity and 7 medium-severity bugs were found, fixed by 5 agents working in parallel on separate branches, then the merged result was re-verified live by another 5 agents (one an independent code review) before anything shipped. Every fix below was reproduced from the original bug, not assumed from a commit message.

package/README.md

@@ -12,12 +12,12 @@
 [![npm version](https://img.shields.io/npm/v/proton-drive-mcp?color=%236d4aff&label=npm)](https://www.npmjs.com/package/proton-drive-mcp)
 [![CI](https://github.com/googlarz/proton-drive-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/googlarz/proton-drive-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet)](https://modelcontextprotocol.io)
 [![GitHub stars](https://img.shields.io/github/stars/googlarz/proton-drive-mcp?style=social)](https://github.com/googlarz/proton-drive-mcp)
 [![Last commit](https://img.shields.io/github/last-commit/googlarz/proton-drive-mcp?color=brightgreen&label=last%20commit)](https://github.com/googlarz/proton-drive-mcp/commits/main)
-[![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](https://github.com/googlarz/proton-drive-mcp)
+[![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)](https://github.com/googlarz/proton-drive-mcp)
 [![proton-drive-mcp MCP server](https://glama.ai/mcp/servers/googlarz/proton-drive-mcp/badges/score.svg)](https://glama.ai/mcp/servers/googlarz/proton-drive-mcp)
 
 </div>
@@ -30,8 +30,8 @@ Give Claude Desktop (or any MCP client) full access to your Proton Drive and Pro
 
 - **Claude manages your Proton Drive** — list, upload, download, move, share, trash, restore
 - **Proton Photos album management** — list albums, create/delete albums, add and remove photos
-- **Full CLI** — same 38 operations, scriptable and pipeable, works in cron and shell scripts
-- **100% CLI coverage** — every scriptable Proton Drive CLI command has a matching tool (verified against the CLI's own source; `auth login` is the one command excluded, since it's an interactive browser flow)
+- **Companion CLI** — 44 of the 46 operations, scriptable and pipeable, works in cron and shell scripts (the two sync-folder tools, `drive_read_file` and `drive_write_file`, are MCP-only)
+- **Full Proton Drive CLI coverage** — every scriptable Proton Drive CLI command has a matching tool (verified against the CLI's own source; `auth login` is the one command excluded, since it's an interactive browser flow)
 - **Zero credential exposure** — auth is handled entirely by the official Proton Drive CLI; this MCP never touches your password or session token
 - **Shell injection safe** — all CLI calls use `execFile` with discrete argument arrays, never string interpolation
 - **Privacy-native** — end-to-end encryption is handled by Proton's own CLI; this server is just a thin MCP wrapper
@@ -60,7 +60,7 @@ proton-drive auth login
 
 This opens a browser for Proton's standard sign-in flow. Credentials are stored in your OS keychain — not on disk, not in config files.
 
-**3. Node.js 20 or later** — `node --version` to check.
+**3. Node.js 22 or later** — `node --version` to check.
 
 ---
 
@@ -91,7 +91,7 @@ Add to your `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
-    "proton-drive": {
+    "proton-drive-mcp": {
       "command": "npx",
       "args": ["-y", "proton-drive-mcp"],
       "env": { "PROTON_DRIVE_BIN": "/absolute/path/to/proton-drive" }
@@ -102,16 +102,20 @@ Add to your `claude_desktop_config.json`:
 
 Claude Desktop starts servers with a minimal `PATH`, so a `proton-drive` in `~/.local/bin` is usually not found. Set `PROTON_DRIVE_BIN` to the output of `which proton-drive` (the default install location is `~/.local/bin/proton-drive`, written out in full, e.g. `/Users/you/.local/bin/proton-drive`). If `npx` itself is not found, use its absolute path as `command` (`which npx`).
 
-Restart Claude Desktop. Check **`+` → Connectors → proton-drive** to confirm the server is connected.
+Restart Claude Desktop. Check **`+` → Connectors → proton-drive-mcp** to confirm the server is connected.
 
 > **Tip:** Make sure `proton-drive auth login` has been run at least once before starting Claude Desktop.
 
+### One-click install (MCPB bundle)
+
+Instead of editing JSON, download `proton-drive-mcp-<version>.mcpb` from the [latest GitHub release](https://github.com/googlarz/proton-drive-mcp/releases/latest) and open it (or drag it into **Settings → Extensions** in Claude Desktop). In the extension settings, set **proton-drive CLI path** to the output of `which proton-drive` (usually `~/.local/bin/proton-drive`); optionally set the **Proton Drive sync folder** to enable `drive_read_file` / `drive_write_file`. You still need the official `proton-drive` CLI installed and `proton-drive auth login` done once.
+
 ### If installed globally
 
 ```json
 {
   "mcpServers": {
-    "proton-drive": {
+    "proton-drive-mcp": {
       "command": "proton-drive-mcp"
     }
   }
@@ -120,6 +124,29 @@ Restart Claude Desktop. Check **`+` → Connectors → proton-drive** to confirm
 
 ---
 
+## Setup and diagnostics
+
+Two commands of the companion CLI help when Claude Desktop reports "proton-drive CLI not found" (it starts servers with a minimal `PATH`):
+
+```bash
+# Read-only checks: Node >= 22, proton-drive CLI + version, auth, PROTON_DRIVE_SYNC_PATH, your Claude Desktop entry
+proton-drive-cli doctor [--json] [--config <path>]
+
+# Dry run: prints the entry it would add and the target file, changes nothing
+proton-drive-cli setup-claude-desktop [--config <path>] [--sync-path <dir>]
+
+# Apply it (timestamped backup first; only mcpServers["proton-drive-mcp"] is touched)
+proton-drive-cli setup-claude-desktop --sync-path "$HOME/Proton Drive" --write
+```
+
+`doctor` exits 1 if any check fails (warnings do not fail). It only ever reports on the `proton-drive-mcp` entry of the config, never on other servers. `setup-claude-desktop` writes the absolute path of the running `node`, of this package's `dist/index.js`, and of the resolved `proton-drive` binary (`PROTON_DRIVE_BIN`). It refuses to run if the CLI cannot be found, the config file is not valid JSON, or the package is running from a temporary `npx` cache (install it first with `npm install -g proton-drive-mcp`). The entry pins the current `node` binary, so re-run it after switching Node versions (e.g. with nvm). Re-running with unchanged settings leaves the file alone; otherwise the file is replaced atomically and a timestamped `.bak-…` copy is kept.
+
+The default config location is per OS (macOS `~/Library/Application Support/Claude/`, Windows `%APPDATA%\Claude\`, Linux `$XDG_CONFIG_HOME` or `~/.config/Claude/`); use `--config` or the `CLAUDE_DESKTOP_CONFIG` environment variable to point elsewhere. On Windows the CLI lookup honours `PATHEXT`.
+
+**Claude Desktop only reads its config at startup: fully quit and restart it afterwards** (closing the window is not enough).
+
+---
+
 ## Try it: example Claude prompts
 
 **Backup a build artifact**
@@ -202,6 +229,28 @@ proton-drive-cli restore /my-files/old-draft.pdf       # restore from trash
 proton-drive-cli trash empty --confirm                  # permanently delete all trashed items
 ```
 
+### Search, analytics and cleanup
+`drive_search` · `drive_tree` · `drive_usage` · `drive_find_duplicates` · `drive_sharing_audit` · `drive_sync_plan` · `drive_bulk_move` · `drive_bulk_trash`
+
+```bash
+proton-drive-cli tree /my-files --depth 2
+proton-drive-cli search /my-files --ext pdf --min-size 1000000
+proton-drive-cli usage /my-files --top 20 --older-than 365
+proton-drive-cli duplicates /my-files --min-size 1000000 [--verify]
+proton-drive-cli share audit /my-files
+proton-drive-cli sync-plan ./local /my-files/backup --direction up
+proton-drive-cli bulk-move /my-files/Archive /my-files/a.pdf /my-files/b.pdf          # plan only
+proton-drive-cli bulk-trash /my-files/old1.txt /my-files/old2.txt --confirm           # apply
+```
+
+- The first walk of a large drive can take minutes (measured ~25 s per 1,200 files at concurrency 8). Later calls reuse a 5-minute cache; `refresh` bypasses it.
+- Walks skip `.git` and `node_modules` by default.
+- Read-only tools (`drive_search`, `drive_tree`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `drive_sync_plan`) change nothing. `drive_bulk_move` and `drive_bulk_trash` are two-step: call without `confirmed` for the plan, then with `confirmed: true` to apply. Bulk trash is reversible with `drive_restore`.
+- Duplicate detection uses the sha1 the uploader claimed, which is unverified. `verify: true` downloads the candidates and hashes them.
+- The sharing audit flags an invitee as external when the address is outside Proton domains, so Proton users on a custom domain are over-flagged.
+- Sizes are sums of file sizes, not your account quota.
+- `drive_usage` trash stats always make one uncached `/trash` listing (~2.5 s), even when the walk is cached.
+
 ### Photos
 
 ```bash
@@ -233,13 +282,19 @@ proton-drive-cli share status /my-files/Projects
 
 ---
 
+## Prompts
+
+The server offers four MCP prompts (also declared in the MCPB manifest): `organise-folder` (`path`), `find-files` (`description`), `storage-audit` and `sharing-audit`. In Claude Code they are listed as `/servername:promptname (MCP)`, and `/mcp__servername__promptname` also runs them. Other clients show them as prompts. A prompt is hidden when a tool it needs is outside the active tool tier: with `PROTON_DRIVE_TOOL_TIER=core` only `find-files` is offered.
+
+---
+
 ## Tool surface
 
 ### Auth
 `drive_auth_status` · `drive_auth_logout` · `drive_version`
 
 ### Filesystem
-`drive_list` · `drive_info` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
+`drive_list` · `drive_info` · `drive_tree` · `drive_search` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
 
 ### Sharing
 `drive_share_status` · `drive_share_invite` · `drive_share_revoke` · `drive_share_remove_all` · `drive_share_set_url` · `drive_share_remove_url`
@@ -253,6 +308,9 @@ proton-drive-cli share status /my-files/Projects
 ### Copy
 `drive_copy`
 
+### Plan & bulk
+`drive_sync_plan` · `drive_bulk_move` · `drive_bulk_trash`
+
 ### Invitations
 `drive_list_invitations` · `drive_invitation_accept` · `drive_invitation_reject` · `drive_share_leave`
 
@@ -270,6 +328,8 @@ proton-drive-cli share status /my-files/Projects
 | `drive_version` | CLI and SDK version info | — |
 | `drive_list` | List files and folders at a path (paginated, default 200; `/` lists the roots) | `path`, `limit?`, `offset?` |
 | `drive_info` | Get metadata for one file/folder, including revision details (noise trimmed) | `path`, `verbose?` (raw CLI node) |
+| `drive_tree` | Folder overview: per-folder file counts and size totals (largest first), depth-limited, cached 5 min | `path?`, `depth?` (default 2, max 10), `limit?`, `foldersOnly?`, `refresh?` |
+| `drive_search` | Find files/folders under a path in one cached walk: name (substring/glob; a glob containing `/` matches the path relative to `path`), type, extension, MIME prefix, size, modified date; sortable, paginated. Reports `walk.complete` — false means the walk was cut short and matches may be missing | `query?`, `glob?`, `path?`, `type?`, `mediaType?`, `extensions?`, `minSize?`, `maxSize?`, `modifiedAfter?`, `modifiedBefore?`, `sort?`, `limit?` (default 50, max 500), `offset?`, `refresh?` |
 | `drive_mkdir` | Create a new empty folder | `path` |
 | `drive_upload` | Upload local file or folder | `localPath`, `remotePath`, `fileConflictStrategy?` (skip/create-new-revision/rename/replace), `folderConflictStrategy?` (skip/merge/rename/replace), `confirmed?` (**required for `replace`** — it trashes the existing remote item) |
 | `drive_download` | Download to local path | `remotePath`, `localPath`, `fileConflictStrategy?` (skip/rename/remove), `folderConflictStrategy?` (skip/merge/rename/remove), `confirmed?` (**required for `remove`** — it deletes the existing local item) |
@@ -279,12 +339,18 @@ proton-drive-cli share status /my-files/Projects
 | `drive_delete` | Permanently delete an item already in trash ⚠️ | `path`, `confirmed: true` |
 | `drive_list_trash` | List items currently in trash (paginated, default 100; includes `uid` — names are not unique in trash) | `limit?`, `offset?` |
 | `drive_share_status` | Get sharing members and URL | `path` |
+| `drive_usage` | Storage analytics for a subtree: totals, largest files/folders, extension and media-type breakdown, old files, trash stats (sum of file sizes, not the account quota) | `path?`, `top?`, `olderThanDays?`, `refresh?` |
+| `drive_find_duplicates` | Likely duplicate groups (claimed sha1 / same size; `verify` downloads and sha256s candidates), wasted bytes, suggested keeper — never deletes | `path?`, `minSize?`, `verify?`, `maxVerifyBytes?`, `maxVerifyTotalBytes?` (default 500 MB, max 2 GB), `limit?`, `refresh?` |
+| `drive_sharing_audit` | Public links (no URL), invitees, pending invitations and risk flags for shared items (max 100) | `path?`, `refresh?` |
 | `drive_share_invite` | Invite a user (sends an email) ⚠️ | `path`, `email`, `role` (viewer/editor/admin), `message?`, `confirmed: true` |
 | `drive_share_revoke` | Revoke one person's access (fails if not a member) ⚠️ | `path`, `email`, `confirmed: true` |
 | `drive_share_remove_all` | Remove every member + pending invitation at once ⚠️ | `path`, `confirmed: true` |
 | `drive_share_set_url` | Create/replace a public share link ⚠️ (re-running without `password`/`expiration` removes them; expiry max ~90 days) | `path`, `role?` (viewer/editor), `password?`, `expiration?`, `confirmed: true` |
 | `drive_share_remove_url` | Remove the public share link ⚠️ | `path`, `confirmed: true` |
 | `drive_trash` | Move to trash | `path` |
+| `drive_sync_plan` | Read-only diff of a local folder vs a Drive folder (nothing transferred) | `localPath`, `drivePath`, `direction?` (up/down/both), `ignore?`, `compare?` (size-mtime/sha1), `limit?` |
+| `drive_bulk_move` | Move up to 200 items into an existing folder; without `confirmed` returns the plan and problems only | `sources`, `destinationFolder`, `confirmed?` (**required to apply**) |
+| `drive_bulk_trash` | Trash up to 200 items (recoverable); without `confirmed` returns the plan and problems only | `paths`, `confirmed?` (**required to apply**) |
 | `drive_restore` | Restore from trash | `path` |
 | `drive_empty_trash` | Permanently delete all trash ⚠️ | `confirmed: true` |
 | `drive_read_file` | Read text file from local sync folder | `path` |
@@ -329,10 +395,20 @@ proton-drive-cli share status /my-files/Projects
 - Error messages come from the CLI's own output; the command line (and therefore any `--password`) is never echoed back.
 - `drive_move` accepts a full destination path (parent + new name) for a familiar interface, but the underlying CLI only has separate `move` (change parent) and `rename` (change name) commands — this MCP translates automatically, issuing one or both as needed.
 - `drive_delete` only works on items already in `/trash` or `/photos-trash` — the CLI rejects live paths. Trash an item first with `drive_trash`, or use `drive_empty_trash` to clear everything at once.
+- If the client declares MCP elicitation (form mode), a refused `confirmed` gate is put to the human instead, and `drive_bulk_move` / `drive_bulk_trash` ask before applying a `confirmed: true` call. Only an explicit approval runs the call; decline, cancel, timeout or error keep the refusal, and after 5 declined prompts in a minute the server stops prompting. This only upgrades refusals and bulk applies: a compromised model that supplies `confirmed: true` on any other tool is **not** stopped by it. Clients without elicitation behave as before. Confirmation prompts need a client that supports elicitation (Claude Code CLI today; Claude Desktop is unverified).
+- Walk-based tools (`drive_tree`, `drive_search`, `drive_usage`, `drive_find_duplicates`) read from a cache up to 5 minutes old; changes made by other clients or processes are not seen until it expires or you pass `refresh: true`. The first walk of a large drive can take minutes (measured about 25 s per 1200 files at concurrency 8).
 - `drive_auth_status` has no native CLI equivalent — it probes by resolving `/my-files` and reports authenticated based on whether that succeeds.
 - Paths are always Drive-absolute: `/my-files/folder/file.pdf`. Relative paths are not supported.
 - All calls include `--json` automatically, except `drive_version`, whose underlying CLI command ignores `--json` and always prints plain text — this MCP parses it directly.
 
+### Token cost
+
+`tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 39.0 KB (46 tools), `core` 16.8 KB (18 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
+
+`drive_auth_status`, `drive_version`, `drive_list`, `drive_info`, `drive_list_trash`, `drive_search`, `drive_tree`, `drive_mkdir`, `drive_upload`, `drive_download`, `drive_rename`, `drive_move`, `drive_copy`, `drive_trash`, `drive_restore`, `drive_share_status`, `photos_list_timeline`, `photos_download`.
+
+Left out of `core` (use `full`): permanent deletion (`drive_delete`, `drive_empty_trash`), `drive_auth_logout`, public links, invitations and invites, album management, `photos_upload` and the sync-file tools. A call to a hidden tool returns an error asking for `PROTON_DRIVE_TOOL_TIER=full`; no CLI command runs.
+
 ## Known limitations
 
 These come from the upstream `proton-drive` CLI (v0.8.0), not from this server:
@@ -347,7 +423,11 @@ These come from the upstream `proton-drive` CLI (v0.8.0), not from this server:
 - `/albums/...` paths cannot be downloaded — download a photo via `/photos/<name>`.
 - A name ending in a backslash (e.g. `tail\`, created by another client) cannot be used as a parent in a path: the CLI reads `tail\/child` as an escaped `/`, and has no escape for a literal backslash (`\\` does not work either). The folder itself is reachable; its children are not reachable by path.
 - Trashed items are addressed by name only. When two items in `/trash` or `/photos-trash` share a name, `drive_restore` and `drive_delete` refuse (listing the uids) instead of acting on an arbitrary one — restore or delete that item in the Proton Drive web or desktop app.
-- When several programs use the CLI at the same moment (e.g. Claude Desktop and Claude Code), its local cache can briefly report `database is locked`. Read-only calls are retried automatically; writes are not (a retry could repeat the change), so just run the write again.
+- When several programs use the CLI at the same moment (e.g. Claude Desktop and Claude Code), its local cache can briefly report `database is locked`. Read-only calls are retried automatically; writes are not (a retry could repeat the change), so just run the write again. The same read-only retry (up to two more attempts, short jittered backoff, honoring a `Retry-After` of at most 5 s and the call's overall timeout) also covers rate limiting (HTTP 429), single-request timeouts (`Request timed out`) and transient network resets; auth and not-found errors are never retried.
+
+## Platform support
+
+Developed and live-tested on **macOS**. CI runs the test suite on Ubuntu and macOS (Node 22 and 24). **Windows is not supported yet**: the test suite has never passed there and CI does not run it, and the Windows paths in `doctor` / `setup-claude-desktop` (`%APPDATA%`, `PATHEXT` lookup) are untested. The system-PATH warning in `doctor` only knows POSIX directories. Linux is covered by CI with the fake CLI but has not been live-tested against a real Proton account.
 
 ## Testing status
 
@@ -360,9 +440,13 @@ Every tool group was live-tested on 2026-09-28 against a real Proton account, **
 | Variable | Required | Description |
 |---|---|---|
 | `PROTON_DRIVE_SYNC_PATH` | Optional | Absolute path to your local Proton Drive sync folder root (e.g. `/Users/you/Proton Drive`). Required only for `drive_read_file` and `drive_write_file`. The Proton Drive desktop app must be running to sync written files to the cloud. |
-| `PROTON_DRIVE_BIN` | Optional | Override the `proton-drive` binary name or path (default: `proton-drive`). Useful for non-standard installations. |
+| `PROTON_DRIVE_BIN` | Optional | Override the `proton-drive` binary name or path (default: `proton-drive`; an empty value counts as unset). Useful for non-standard installations. |
 | `PROTON_DRIVE_LOCAL_ROOT` | Optional | Path-delimiter-separated list of local directories that upload/download/photos tools may touch. Unset = any path except the built-in credential denylist. |
 | `PROTON_DRIVE_ALLOW_SENSITIVE_PATHS` | Optional | Set to `1` to disable the built-in credential-location denylist (not recommended). |
+| `CLAUDE_DESKTOP_CONFIG` | Optional | Path of the Claude Desktop config that `doctor` and `setup-claude-desktop` read/write instead of the per-OS default. |
+| `PROTON_DRIVE_RETRY_BASE_MS` | Optional | Test hook: base backoff in ms for retrying read-only calls (default 250). |
+| `PROTON_DRIVE_WALK_TTL_MS` | Optional | How long `drive_tree`/`drive_search` reuse a cached folder walk, in ms (default 300000; 0 disables the cache). Results can be up to this old, and changes made by other clients or processes are not seen until it expires or `refresh: true`. The first walk of a large drive can take minutes. The cache is dropped for any path this server writes to. |
+| `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all 46 tools) or `core` (18 everyday tools; see [Token cost](#token-cost)). Tools outside the active tier are hidden from `tools/list` and refused at call time. Read once at startup; an unknown value falls back to `full` with a warning on stderr. |
 
 ---
 
@@ -378,7 +462,7 @@ Download from [proton.me/download/drive/cli](https://proton.me/download/drive/cl
 Run `proton-drive auth login` in your terminal. Auth state is stored in your OS keychain and persists across sessions.
 
 **Claude can't see the connector**  
-Restart Claude Desktop fully after changing the MCP config. Check **`+` → Connectors → proton-drive**. The Proton Drive CLI must be in the `PATH` that Claude Desktop inherits (on macOS this may differ from your shell PATH — use the full binary path in config if needed).
+Restart Claude Desktop fully after changing the MCP config. Check **`+` → Connectors → proton-drive-mcp**. The Proton Drive CLI must be in the `PATH` that Claude Desktop inherits (on macOS this may differ from your shell PATH — use the full binary path in config if needed).
 
 **Upload fails on image files**  
 The CLI generates WebP thumbnails by default using Bun's image API. If Bun isn't installed or doesn't support thumbnails on your platform, the MCP passes `--skip-thumbnails` to bypass this. No action needed.
@@ -392,7 +476,7 @@ Or in Claude Desktop config:
 ```json
 {
   "mcpServers": {
-    "proton-drive": {
+    "proton-drive-mcp": {
       "command": "npx",
       "args": ["-y", "proton-drive-mcp"],
       "env": { "PROTON_DRIVE_BIN": "/usr/local/bin/proton-drive" }
@@ -406,7 +490,7 @@ Use the full path to the `proton-drive.exe` binary in your Claude Desktop config
 ```json
 {
   "mcpServers": {
-    "proton-drive": {
+    "proton-drive-mcp": {
       "command": "C:\\path\\to\\proton-drive-mcp.cmd"
     }
   }

package/dist/cli.js

@@ -9,7 +9,14 @@
 import { DriveService, } from "./services/drive.js";
 import { DriveCliError, DriveCliNotFoundError, DriveNotAuthenticatedError, DriveParseError } from "./utils/errors.js";
 import { checkCliAvailable } from "./utils/subprocess.js";
-import { validateRemotePath, validateLocalPath, validateEmail, validateMessage, validateName, validateFlagValue } from "./utils/validation.js";
+import { runDoctor, formatDoctor } from "./utils/doctor.js";
+import { buildEntry, defaultConfigPath, isDirectory, resolveDriveCli, writeEntry, SERVER_KEY } from "./utils/claudeConfig.js";
+import { syncPlan, planBulkMove, planBulkTrash, loadListing, foldersToList } from "./services/plan.js";
+import { invalidatePath } from "./services/walk.js";
+import { resolve } from "node:path";
+import { driveSearch, driveTree } from "./services/find.js";
+import { driveUsage, driveFindDuplicates, driveSharingAudit } from "./services/analytics.js";
+import { validateRemotePath, validateRemotePathList, validateLocalPath, validateEmail, validateMessage, validateName, validateFlagValue } from "./utils/validation.js";
 const drive = new DriveService();
 const args = process.argv.slice(2);
 const jsonMode = args.includes("--json");
@@ -23,6 +30,12 @@ Commands:
   version                                  Show CLI/SDK version
   list <path>                              List files at path
   info <path> [--verbose]                  Show node metadata (--verbose = raw CLI node)
+  tree [path] [--depth N] [--limit N] [--folders-only] [--refresh]
+                                           Folder overview with per-folder counts and sizes (default /my-files, depth 2)
+  search [path] [--query S] [--glob G] [--type file|folder] [--media-type P] [--ext pdf,docx]
+         [--min-size B] [--max-size B] [--after DATE] [--before DATE] [--sort name|size|mtime]
+         [--limit N] [--offset N] [--refresh]
+                                           Find files/folders under path (default /my-files) in one walk
   mkdir <path>                             Create a new folder
   upload <local> <remote> [--file-conflict X] [--folder-conflict X] [--confirm]
                                            Upload file/folder (files: skip/create-new-revision/rename/replace; folders: skip/merge/rename/replace;
@@ -34,6 +47,7 @@ Commands:
   move <src> <dst>                         Move and/or rename
   delete <path>|--uid <uid> --confirm      Delete a file/folder already in trash, permanently
   share status <path>                      Show sharing info
+  share audit [path] [--refresh]           Audit public links, invitees and risk flags under a path (default /my-files)
   share invite <path> <email> <role>       Invite user (viewer/editor/admin)
   share revoke <path> <email>              Revoke one user's access
   share remove-all <path> --confirm        Remove everyone's access + pending invitations
@@ -42,7 +56,15 @@ Commands:
   share leave <path>                       Leave a folder shared with you
   copy <src> <dst-parent-folder> [--name N]  Copy file/folder into a folder (optionally under a new name)
   trash <path>                             Move to trash
+  sync-plan <local> <remote> [--direction up|down|both] [--compare size-mtime|sha1] [--ignore g1,g2] [--limit N]
+                                           Read-only diff of a local folder vs a Drive folder (nothing transferred)
+  bulk-move <dst-folder> <src>... [--confirm]  Move many items into an existing folder; without --confirm prints the plan only
+  bulk-trash <path>... [--confirm]         Trash many items; without --confirm prints the plan only
   trash list                               List trash contents
+  usage [path] [--top N] [--older-than DAYS] [--refresh]
+                                           Storage analytics: totals, largest files/folders, breakdowns, trash (sum of file sizes, not the quota)
+  duplicates [path] [--min-size B] [--verify] [--max-verify-bytes B] [--max-verify-total-bytes B] [--limit N] [--refresh]
+                                           Likely duplicate files; --verify downloads and hashes candidates. Never deletes.
   trash empty --confirm                    Permanently delete all trash
   restore <path>|--uid <uid>               Restore from trash (uid from 'trash list')
   invitation list                          List pending invitations
@@ -59,6 +81,12 @@ Commands:
   photo download <photo>... <local> [--conflict X] [--confirm]  Download photos (skip/rename/remove; 'remove' needs --confirm)
   photo upload <local>... [--conflict X]   Upload photos to your library (skip/rename)
 
+  doctor [--config <path>]                 Read-only diagnostics: Node, proton-drive CLI, auth, sync path, Claude Desktop config
+                                           (exit 1 if any check fails)
+  setup-claude-desktop [--config <path>] [--sync-path <dir>] [--write]
+                                           Print the Claude Desktop entry for this server (dry run); --write adds it to the
+                                           config (timestamped backup first). Restart Claude Desktop afterwards.
+
 Flags:
   --json                                   Machine-readable JSON output (one line)
 `);
@@ -77,6 +105,19 @@ function requirePath(value, usage) {
     }
     return ""; // unreachable; process.exit(1) above always terminates
 }
+function pathOrRoot(value) {
+    return value && !value.startsWith("--") ? requirePath(value, "<command> [path]") : "/my-files";
+}
+function intFlag(flag) {
+    const v = getFlag(flag);
+    if (v === undefined)
+        return undefined;
+    if (!/^\d+$/.test(v)) {
+        console.error(`${flag} must be a non-negative integer`);
+        process.exit(1);
+    }
+    return Number(v);
+}
 function requireEmail(value) {
     try {
         return validateEmail(value);
@@ -97,9 +138,44 @@ function getFlag(flag) {
     }
     return args[idx + 1];
 }
+function numFlag(flag) {
+    const v = getFlag(flag);
+    if (v === undefined)
+        return undefined;
+    if (!/^\d+$/.test(v)) {
+        console.error(`${flag} must be a non-negative integer`);
+        process.exit(1);
+    }
+    return Number(v);
+}
+function numFlags(...names) {
+    return Object.fromEntries(names.map((n) => [n, numFlag(`--${n}`)]));
+}
 function print(data) {
     console.log(jsonMode ? JSON.stringify(data) : JSON.stringify(data, null, 2));
 }
+function setupClaudeDesktop() {
+    const configPath = resolve(getFlag("--config") ?? defaultConfigPath());
+    const rawSync = getFlag("--sync-path");
+    const cliPath = resolveDriveCli();
+    if (!cliPath) {
+        console.error("Error: proton-drive CLI not found. Install it from https://proton.me/download/drive/cli/index.html, or set PROTON_DRIVE_BIN to its absolute path (`which proton-drive`).");
+        process.exit(1);
+    }
+    const syncPath = rawSync !== undefined ? resolve(rawSync) : undefined;
+    if (syncPath && !isDirectory(syncPath)) {
+        console.error(`Error: --sync-path ${syncPath} is not an existing directory.`);
+        process.exit(1);
+    }
+    const entry = buildEntry(cliPath, syncPath);
+    const shown = JSON.stringify({ mcpServers: { [SERVER_KEY]: entry } }, null, 2);
+    if (!args.includes("--write")) {
+        console.log(`Dry run: nothing changed. Would set this entry in ${configPath}:\n${shown}\nRe-run with --write to apply.`);
+        return;
+    }
+    const backup = writeEntry(configPath, entry);
+    console.log(`Wrote ${SERVER_KEY} to ${configPath}${backup ? ` (backup: ${backup})` : ""}.\n${shown}\nFully quit and restart Claude Desktop for the change to take effect.`);
+}
 async function run() {
     // Strip --json from positional parsing
     const positional = args.filter((a) => a !== "--json");
@@ -115,6 +191,16 @@ async function run() {
         usage();
         return;
     }
+    if (cmd === "doctor") {
+        const result = await runDoctor(getFlag("--config"));
+        console.log(jsonMode ? JSON.stringify(result) : formatDoctor(result));
+        process.exitCode = result.ok ? 0 : 1;
+        return;
+    }
+    if (cmd === "setup-claude-desktop") {
+        setupClaudeDesktop();
+        return;
+    }
     const cliCheck = await checkCliAvailable();
     if (!cliCheck.available) {
         const msg = cliCheck.reason === "not_executable"
@@ -143,6 +229,21 @@ async function run() {
         case "list":
             print(await drive.list(requirePath(sub, "list <path>")));
             break;
+        case "tree":
+            print(await driveTree(drive, { path: sub && !sub.startsWith("--") ? sub : undefined, ...numFlags("depth", "limit"), foldersOnly: args.includes("--folders-only") || undefined, refresh: args.includes("--refresh") || undefined }));
+            break;
+        case "search":
+            print(await driveSearch(drive, {
+                path: sub && !sub.startsWith("--") ? sub : undefined,
+                query: getFlag("--query"), glob: getFlag("--glob"),
+                type: getFlag("--type"), mediaType: getFlag("--media-type"),
+                extensions: getFlag("--ext")?.split(","),
+                ...numFlags("limit", "offset"),
+                minSize: numFlag("--min-size"), maxSize: numFlag("--max-size"),
+                modifiedAfter: getFlag("--after"), modifiedBefore: getFlag("--before"),
+                sort: getFlag("--sort"), refresh: args.includes("--refresh") || undefined,
+            }));
+            break;
         case "info":
             print(await drive.info(requirePath(sub, "info <path> [--verbose]"), args.includes("--verbose")));
             break;
@@ -154,7 +255,7 @@ async function run() {
             }
             let local;
             try {
-                local = validateLocalPath(rawLocal);
+                local = validateLocalPath(rawLocal, { scan: true });
             }
             catch (e) {
                 console.error(e instanceof Error ? e.message : String(e));
@@ -256,6 +357,9 @@ async function run() {
             if (sub === "status") {
                 print(await drive.shareStatus(requirePath(rest[0], "share status <path>")));
             }
+            else if (sub === "audit") {
+                print(await driveSharingAudit(drive, { path: pathOrRoot(rest[0]), refresh: args.includes("--refresh") }));
+            }
             else if (sub === "invite") {
                 const [rawPath, rawEmail, role] = rest;
                 if (!rawPath || !rawEmail || !role) {
@@ -324,6 +428,25 @@ async function run() {
                 process.exit(1);
             }
             break;
+        case "usage":
+            print(await driveUsage(drive, {
+                path: pathOrRoot(sub),
+                top: intFlag("--top"),
+                olderThanDays: intFlag("--older-than"),
+                refresh: args.includes("--refresh"),
+            }));
+            break;
+        case "duplicates":
+            print(await driveFindDuplicates(drive, {
+                path: pathOrRoot(sub),
+                minSize: intFlag("--min-size"),
+                verify: args.includes("--verify"),
+                maxVerifyBytes: intFlag("--max-verify-bytes"),
+                maxVerifyTotalBytes: intFlag("--max-verify-total-bytes"),
+                limit: intFlag("--limit"),
+                refresh: args.includes("--refresh"),
+            }));
+            break;
         case "trash":
             if (sub === "empty") {
                 if (!args.includes("--confirm")) {
@@ -345,6 +468,66 @@ async function run() {
                 process.exit(1);
             }
             break;
+        case "sync-plan": {
+            const direction = getFlag("--direction"), compare = getFlag("--compare"), ignore = getFlag("--ignore"), limit = getFlag("--limit");
+            if (direction !== undefined && !["up", "down", "both"].includes(direction)) {
+                console.error("--direction must be up, down or both");
+                process.exit(1);
+            }
+            if (compare !== undefined && !["size-mtime", "sha1"].includes(compare)) {
+                console.error("--compare must be size-mtime or sha1");
+                process.exit(1);
+            }
+            if (!sub || !rest[0]) {
+                console.error("Usage: sync-plan <local> <remote> [--direction X] [--compare X] [--ignore g1,g2] [--limit N]");
+                process.exit(1);
+            }
+            print(await syncPlan(drive, {
+                localPath: sub, drivePath: rest[0], direction: direction, compare: compare,
+                ignore: ignore?.split(","), limit: limit !== undefined ? Number(limit) : undefined,
+            }));
+            break;
+        }
+        case "bulk-move": {
+            const dst = requirePath(sub, "bulk-move <dst-folder> <src>... [--confirm]");
+            const srcs = validateRemotePathList(rest.filter((r) => !r.startsWith("--")), "sources");
+            const plan = planBulkMove(srcs, dst, await loadListing(drive, foldersToList(srcs, dst)));
+            if (!args.includes("--confirm") || plan.problems.length) {
+                print({ applied: false, ...plan });
+                if (plan.problems.length)
+                    process.exit(1);
+                console.error("Plan only. Pass --confirm to apply.");
+                break;
+            }
+            try {
+                await drive.bulkMove(srcs, dst);
+            }
+            finally {
+                invalidatePath(dst);
+                srcs.forEach(invalidatePath);
+            }
+            console.log(`Moved ${srcs.length} item(s) to ${dst}.`);
+            break;
+        }
+        case "bulk-trash": {
+            const paths = validateRemotePathList([sub, ...rest].filter((r) => r !== undefined && !r.startsWith("--")), "paths");
+            const plan = planBulkTrash(paths, await loadListing(drive, foldersToList(paths)));
+            if (!args.includes("--confirm") || plan.problems.length) {
+                print({ applied: false, ...plan });
+                if (plan.problems.length)
+                    process.exit(1);
+                console.error("Plan only. Pass --confirm to apply.");
+                break;
+            }
+            try {
+                await drive.bulkTrash(paths);
+            }
+            finally {
+                paths.forEach(invalidatePath);
+            }
+            console.log(`Moved ${paths.length} item(s) to trash.`);
+            break;
+        }
         case "restore": {
             const restoreUid = getFlag("--uid");
             const restorePath = restoreUid && (!sub || sub.startsWith("--")) ? undefined : requirePath(sub, "restore <path>|--uid <uid>");
@@ -536,7 +719,7 @@ async function run() {
                 const localPaths = [];
                 for (const p of positionals) {
                     try {
-                        localPaths.push(validateLocalPath(p));
+                        localPaths.push(validateLocalPath(p, { scan: true }));
                     }
                     catch (e) {
                         console.error(e instanceof Error ? e.message : String(e));