proton-drive-mcp 1.0.39 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 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.
+
+**Behavior changes:** `drive_list`/`drive_list_trash`/`photos_list_timeline`/`photos_list_album_photos` now return items in a stable sorted order; `drive_list`'s `size` is the real file size (the old value is `storageSize`); `drive_restore`/`drive_delete` accept an optional `uid`; `drive_read_file`/`drive_write_file` interpret a `/my-files/...` path as documented.
+
+### Fixed — high severity
+- **`drive_list` pagination lost and duplicated items.** Each page re-ran the CLI, whose item order isn't stable, so a page slice could return the same item twice or skip one entirely while `total` still looked correct. Confirmed live: walking a 1,000-file folder returned 998 of 1,000 unique items. `drive_list`, `drive_list_trash`, `photos_list_timeline` and `photos_list_album_photos` now sort deterministically before paginating (name, then trash time, then capture time — each with a uid tie-break) and their descriptions say each page is a fresh read.
+- **`drive_restore`/`drive_delete` could act on the wrong item when a trash name repeated.** `drive_list_trash` documents using `uid` to tell duplicates apart, but neither tool accepted one. Confirmed live: restoring/deleting `/trash/x.txt` with two items named `x.txt` picked an arbitrary one — the delete case is irreversible. Both tools now accept `uid`, refuse an ambiguous path (listing every matching uid and trash time instead of guessing), and the same check now also covers `/photos-trash`. The underlying CLI can only address a trashed item by name, so a genuinely ambiguous duplicate still can't be targeted — resolve it in the Proton Drive web or desktop app.
+- **`drive_read_file`/`drive_write_file` didn't map the documented `/my-files/...` path.** Following the example in the tool description created a local folder literally named `my-files`, which then synced to Drive as `/my-files/my-files/...`. `/my-files/<rest>` now maps to the sync root correctly; every other Drive root (`/photos`, `/trash`, ...) is rejected with a clear message, since only `/my-files` is synced locally.
+
+### Fixed — medium severity
+- **`photos_delete_album` deleted non-empty albums** despite its description promising a refusal without `force` — the check never existed. Now enforced, and fails closed (refuses) if the album's photo count can't be looked up at all, rather than assuming empty.
+- **`photos_download` advertised `/albums/<album>/<photo>` paths that the CLI can't resolve.** Now rejected up front with a message pointing at the `/photos/<name>` form.
+- **`drive_list`'s `size` was the encrypted storage size summed across every revision**, not the file's real size (a 1-byte file showed 79; it doubled after a new revision). Real size is now `size`; the old value is `storageSize`.
+- **`drive_move` misreported a missing source as "Destination already exists"**, because the destination was checked before the source. Now reports "Source not found" correctly, and hints at the fix when the "existing destination" is actually the target folder itself (a path/parent mix-up seen in live testing).
+- **`drive_share_status` on a Drive root (`/my-files`, etc.) failed with a raw CLI decryption error**, which also broke this project's own live smoke test. Roots now get a clear "cannot be shared" error without calling the CLI.
+- **A folder name ending in a backslash made its children unaddressable** (`tail\` + child `\/` is read as an escaped slash by the CLI, which has no way to escape a literal backslash). No fix exists upstream; documented as a known limitation.
+- **The Claude Desktop config example didn't set `PROTON_DRIVE_BIN`**, and Claude Desktop launches servers with a minimal `PATH` that usually can't find `proton-drive`. The example now sets it, and the "CLI not found" error mentions the variable.
+
+### Also fixed
+- Non-UTF-8 text read through the sync folder was silently corrupted (replacement characters, no warning) — now a clear error.
+- The invite-message limit was 2000 characters; the CLI enforces 500 — now matched.
+- `drive_mkdir` accepted a spaces-only name while `drive_rename` rejected one — now consistent.
+- `drive_share_remove_all` said "Removed all access" while an active public link stayed live — now says so, and how to remove it.
+- Raw upstream error codes (`InvalidRequirementsAPIError` 2000, `APICodeError` 2511/2500) are now mapped to a readable sentence, with the code kept in parentheses; bundled CLI source lines and bare `Error details: {}` are stripped from error text.
+- Read-only CLI calls now retry (up to twice) on the CLI's own `database is locked` error, seen live when multiple MCP clients share one CLI session concurrently; writes are never retried.
+- `photos_list_album_photos` without `loadDetails` has no `captureTime`, so its description now says the order is by `nodeUid`, not capture time.
+
+### Verified with no changes needed
+Data integrity (sha256 round-trips up to 200 MB, 500+ file trees, every upload/download conflict strategy, `drive_copy`), the real sync folder end to end, 3 concurrent MCP server processes sharing one CLI session, a 20+ minute long-running session (no memory or process leaks), server-kill-mid-upload recovery, the official MCP SDK client and MCP Inspector, Node 20/22/24, a packed-and-installed npm tarball launched via its real `.bin` symlink, and dozens of adversarial edge cases (special Drive roots, Unicode name tricks, 40-level nesting, etc.).
+
+### Known, not fixed (upstream CLI limitations, now documented in README)
+Big folders can't be copied; a `"` in a name becomes `_` on local download; a public link's expiration caps at ~90 days; sharing inherited from a parent folder isn't reported by `drive_share_status`; upload/download counts include folders.
+
+### Testing status
+`drive_share_leave`, `drive_invitation_accept` and `drive_invitation_reject` have never been tested against a real account — they need a second Proton account, which the maintainer doesn't have. Only unit-tested against a fake CLI. Documented in README.
+
 ## 1.0.39 — 2026-09-26
 
 Test-suite hardening only — no `src/` changes, no behavior change.

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>
@@ -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,24 +91,31 @@ Add to your `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
-    "proton-drive": {
+    "proton-drive-mcp": {
       "command": "npx",
-      "args": ["-y", "proton-drive-mcp"]
+      "args": ["-y", "proton-drive-mcp"],
+      "env": { "PROTON_DRIVE_BIN": "/absolute/path/to/proton-drive" }
     }
   }
 }
 ```
 
-Restart Claude Desktop. Check **`+` → Connectors → proton-drive** to confirm the server is connected.
+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-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"
     }
   }
@@ -117,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**
@@ -330,6 +360,38 @@ proton-drive-cli share status /my-files/Projects
 - 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` 29.5 KB (38 tools; 39.5 KB before description trimming), `core` 13.3 KB (16 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
+
+`drive_auth_status`, `drive_version`, `drive_list`, `drive_info`, `drive_list_trash`, `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:
+
+- Big folders cannot be copied yet (`drive_copy` fails with `InvalidRequirementsAPIError` code 2000).
+- A `"` in a name becomes `_` when the item is downloaded locally.
+- Public-link expiration can be at most ~90 days ahead, to the minute.
+- `drive_share_status` only reports sharing set directly on the item — access inherited from a shared parent folder is not shown.
+- Roots (`/my-files`, `/photos`, …) cannot be shared; `drive_share_status` on a root returns an error.
+- `photos_list_timeline` pages are not a snapshot: photos added or removed between calls shift later pages.
+- Upload/download counts include folders, not only files.
+- `/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. 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 (CI runs it only as a non-blocking probe), 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
+
+Every tool group was live-tested on 2026-09-28 against a real Proton account, **except** `drive_share_leave`, `drive_invitation_accept` and `drive_invitation_reject`. Those three have never been tested against a real account, because the maintainer has no second Proton account to share from; they are only unit-tested against a fake CLI.
+
 ---
 
 ## Environment variables
@@ -337,9 +399,12 @@ proton-drive-cli share status /my-files/Projects
 | 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_TOOL_TIER` | Optional | `full` (default, all 38 tools) or `core` (16 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. |
 
 ---
 
@@ -355,7 +420,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.
@@ -369,7 +434,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" }
@@ -383,7 +448,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,6 +9,9 @@
 import { DriveService, } from "./services/drive.js";
 import { DriveCliError, DriveCliNotFoundError, DriveNotAuthenticatedError, DriveParseError } from "./utils/errors.js";
 import { checkCliAvailable } from "./utils/subprocess.js";
+import { runDoctor, formatDoctor } from "./utils/doctor.js";
+import { buildEntry, defaultConfigPath, isDirectory, resolveDriveCli, writeEntry, SERVER_KEY } from "./utils/claudeConfig.js";
+import { resolve } from "node:path";
 import { validateRemotePath, validateLocalPath, validateEmail, validateMessage, validateName, validateFlagValue } from "./utils/validation.js";
 const drive = new DriveService();
 const args = process.argv.slice(2);
@@ -32,7 +35,7 @@ Commands:
                                            'remove' deletes the existing LOCAL item and needs --confirm)
   rename <path> <new-name>                 Rename in place, no move
   move <src> <dst>                         Move and/or rename
-  delete <path> --confirm                  Delete a file/folder already in trash, permanently
+  delete <path>|--uid <uid> --confirm      Delete a file/folder already in trash, permanently
   share status <path>                      Show sharing info
   share invite <path> <email> <role>       Invite user (viewer/editor/admin)
   share revoke <path> <email>              Revoke one user's access
@@ -44,7 +47,7 @@ Commands:
   trash <path>                             Move to trash
   trash list                               List trash contents
   trash empty --confirm                    Permanently delete all trash
-  restore <path>                           Restore from trash
+  restore <path>|--uid <uid>               Restore from trash (uid from 'trash list')
   invitation list                          List pending invitations
   invitation accept <uid>                  Accept an invitation
   invitation reject <uid>                  Reject an invitation
@@ -59,6 +62,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)
 `);
@@ -100,6 +109,28 @@ function getFlag(flag) {
 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,11 +146,21 @@ 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"
             ? "Error: proton-drive CLI found but not executable.\nRun: chmod +x $(which proton-drive)"
-            : "Error: proton-drive CLI not found in PATH.\nDownload from https://proton.me/download/drive/cli/index.html";
+            : "Error: proton-drive CLI not found in PATH.\nDownload from https://proton.me/download/drive/cli/index.html, or set PROTON_DRIVE_BIN to its absolute path (find it with `which proton-drive`).";
         console.error(msg);
         process.exit(1);
     }
@@ -241,13 +282,15 @@ async function run() {
             console.log("Folder created.");
             break;
         case "delete": {
-            const delPath = requirePath(sub, "delete <path> --confirm");
+            const delUid = getFlag("--uid");
+            const delPath = delUid && (!sub || sub.startsWith("--")) ? undefined : requirePath(sub, "delete <path>|--uid <uid> --confirm");
+            const delLabel = delPath ?? `uid ${delUid}`;
             if (!args.includes("--confirm")) {
-                console.error(`This permanently deletes an item already in trash: ${delPath}\nPass --confirm to proceed.`);
+                console.error(`This permanently deletes an item already in trash: ${delLabel}\nPass --confirm to proceed.`);
                 process.exit(1);
             }
-            await drive.delete(delPath);
-            console.log(`Deleted: ${delPath}`);
+            await drive.delete(delPath, delUid);
+            console.log(`Deleted: ${delLabel}`);
             break;
         }
         case "share":
@@ -288,10 +331,11 @@ async function run() {
                     console.error(`This removes everyone's access to: ${removeAllPath}\nPass --confirm to proceed.`);
                     process.exit(1);
                 }
-                const removedCount = await drive.shareRemoveAll(removeAllPath);
-                console.log(removedCount === 0
+                const removeAll = await drive.shareRemoveAll(removeAllPath);
+                console.log((removeAll.removed === 0
                     ? `Nothing to remove: ${removeAllPath} has no members or pending invitations.`
-                    : `Removed all access (${removedCount} member/invitation(s)) to: ${removeAllPath}`);
+                    : `Removed all members and invitations (${removeAll.removed}) from: ${removeAllPath}`) +
+                    (removeAll.publicLink ? " A public link is still active — remove it with: share remove-url <path>" : ""));
             }
             else if (sub === "set-url") {
                 const setUrlPath = requirePath(rest[0], "share set-url <path> [--role] [--password] [--expiration]");
@@ -342,10 +386,13 @@ async function run() {
                 process.exit(1);
             }
             break;
-        case "restore":
-            await drive.restore(requirePath(sub, "restore <path>"));
+        case "restore": {
+            const restoreUid = getFlag("--uid");
+            const restorePath = restoreUid && (!sub || sub.startsWith("--")) ? undefined : requirePath(sub, "restore <path>|--uid <uid>");
+            await drive.restore(restorePath, restoreUid);
             console.log("Restored.");
             break;
+        }
         case "copy": {
             const copySrc = requirePath(sub, "copy <src> <dst>");
             const copyDst = requirePath(rest[0], "copy <src> <dst>");
@@ -452,7 +499,7 @@ async function run() {
                     return;
                 }
                 await drive.updateAlbum(albumPath, newName, coverPhotoUid);
-                console.log(`Album updated: ${albumPath}`);
+                console.log(`Album updated: ${newName ? `/albums/${newName}` : albumPath}`);
             }
             else if (sub === "delete") {
                 const albumPath = requirePath(rest[0], "album delete <path> [--force] [--save] --confirm");