proton-drive-mcp 1.0.39 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 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

@@ -93,12 +93,15 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "proton-drive": {
       "command": "npx",
-      "args": ["-y", "proton-drive-mcp"]
+      "args": ["-y", "proton-drive-mcp"],
+      "env": { "PROTON_DRIVE_BIN": "/absolute/path/to/proton-drive" }
     }
   }
 }
 ```
 
+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.
 
 > **Tip:** Make sure `proton-drive auth login` has been run at least once before starting Claude Desktop.
@@ -330,6 +333,26 @@ 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.
 
+## 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.
+
+## 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

package/dist/cli.js

@@ -32,7 +32,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 +44,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
@@ -119,7 +119,7 @@ async function run() {
     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 +241,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 +290,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 +345,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 +458,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");

package/dist/index.js

@@ -55,6 +55,18 @@ function paginate(all, a, defaultLimit) {
     const items = all.slice(offset, offset + limit);
     return { total: all.length, offset, limit, hasMore: offset + items.length < all.length, items };
 }
+// Every page re-runs the CLI, whose order is not stable, so paginated lists
+// must be put in a total order before slicing or pages lose/duplicate items.
+function byTimeDescThenId(time, id) {
+    return (x, y) => {
+        const t = (time(y) ?? "").localeCompare(time(x) ?? "");
+        if (t)
+            return t;
+        const a = id(x) ?? "", b = id(y) ?? "";
+        return a < b ? -1 : a > b ? 1 : 0;
+    };
+}
+const photoOrder = byTimeDescThenId((p) => p.captureTime, (p) => p.nodeUid);
 // The schemas advertise additionalProperties:false, but nothing enforced it, and
 // String() coercion let e.g. an array pass as a path. Enforce the declared schema.
 function checkArgs(def, a) {
@@ -127,7 +139,7 @@ const TOOLS = [
     {
         name: "drive_list",
         description: "List the immediate children of a Proton Drive folder. Requires authentication. " +
-            "Returns {items, total, offset, limit, hasMore} (default limit 200); items are [{name, path, type ('file'|'folder'), size?, modifiedAt?, mimeType?}]. Listing '/' returns the top-level roots. " +
+            "Returns {items, total, offset, limit, hasMore} (default limit 200, sorted by name); items are [{name, path, type ('file'|'folder'), size? (real file size in bytes), storageSize? (encrypted storage used by all revisions), modifiedAt?, mimeType?}]. Items come in a stable sorted order; each page is a fresh read, so changes made between page calls can still shift items. Listing '/' returns the top-level roots. " +
             "Not recursive — one directory level only. " +
             "Use before drive_upload to confirm the destination exists, or before drive_download to verify the remote path. " +
             "Do not use to list trash — use drive_list_trash instead.",
@@ -207,11 +219,10 @@ const TOOLS = [
     {
         name: "drive_download",
         description: "Download a file or folder from Proton Drive to the local filesystem. Requires authentication. " +
-            "localPath is a destination FOLDER, not the file's exact final path — the CLI creates it automatically if missing and places the downloaded item inside it under its original remote name. " +
-            "E.g. downloading /my-files/report.pdf with localPath '/tmp/out' produces /tmp/out/report.pdf, not /tmp/out itself as a file — confirmed live against the real CLI (v0.8.0). " +
-            "For folders, downloads recursively. " +
-            "Conflict strategies are set separately for files and folders (CLI v0.8.0+) — both default to 'skip'. " +
-            "Returns {downloaded, skipped, failed} counts — not the actual local path; construct it as localPath + the remote item's basename if you need it. Fails the call if any file failed to download. " +
+            "localPath is a destination FOLDER, not the file's final path — created if missing; the item is placed inside it under its remote name. " +
+            "E.g. /my-files/report.pdf with localPath '/tmp/out' produces /tmp/out/report.pdf. " +
+            "Folders download recursively. File and folder conflict strategies are separate; both default to 'skip'. " +
+            "Returns {downloaded, skipped, failed} counts (folders count as items), not the local path — it is localPath + the remote basename. Fails the call if any file failed. " +
             "Do not use to move files within Drive (use drive_move) or to read a small text file's contents (use drive_read_file if PROTON_DRIVE_SYNC_PATH is set).",
         annotations: { openWorldHint: true },
         inputSchema: {
@@ -314,7 +325,8 @@ const TOOLS = [
         name: "drive_delete",
         description: "Permanently delete a file or folder that is already in the Proton Drive trash — irreversible. Requires authentication. " +
             "The underlying CLI only allows permanent deletion of items already inside /trash or /photos-trash; it rejects live paths. " +
-            "Use drive_trash first to move a live item into trash, then pass its trash path here — or drive_empty_trash to clear everything at once. " +
+            "Use drive_trash first to move a live item into trash, then pass its trash path (or its uid from drive_list_trash) here — or drive_empty_trash to clear everything at once. " +
+            "If several trashed items share the name, this refuses and lists their uids: the CLI can only address trashed items by name, so it cannot pick one of them (even by uid) — use the Proton Drive web or desktop app for that. " +
             "Requires confirmed=true; always show the exact path to the user and get explicit confirmation before calling.",
         annotations: { destructiveHint: true },
         inputSchema: {
@@ -322,14 +334,18 @@ const TOOLS = [
             properties: {
                 path: {
                     type: "string",
-                    description: "Absolute remote Drive path to permanently delete (must start with '/').",
+                    description: "Absolute remote Drive path to permanently delete (must start with '/'). Give path or uid (or both).",
+                },
+                uid: {
+                    type: "string",
+                    description: "Trash uid from drive_list_trash. Pins the exact item you listed; if both path and uid are given they must refer to the same item.",
                 },
                 confirmed: {
                     type: "boolean",
                     description: "Must be true. Confirms the user has acknowledged this deletion is permanent and cannot be undone.",
                 },
             },
-            required: ["path", "confirmed"],
+            required: ["confirmed"],
             additionalProperties: false,
         },
     },
@@ -357,7 +373,8 @@ const TOOLS = [
     {
         name: "drive_list_trash",
         description: "List all files and folders currently in the Proton Drive trash. Requires authentication. " +
-            "Returns {items, total, offset, limit, hasMore} (default limit 100, newest first when the CLI reports trash times); items are [{name, path, type, size?, modifiedAt?, uid, trashedAt?}]. Names are NOT unique in trash — two items can share one path; use uid to tell them apart. " +
+            "Returns {items, total, offset, limit, hasMore} (default limit 100, newest first, ties by uid); items are [{name, path, type, size?, storageSize?, modifiedAt?, uid, trashedAt?}]. Items come in a stable sorted order; each page is a fresh read, so changes made between page calls can still shift items. Names are NOT unique in trash — two items can share one path; uid and trashedAt tell them apart. " +
+            "drive_restore/drive_delete accept the uid to pin the exact item, but refuse when its name is shared (the CLI cannot target one duplicate). " +
             "Use before drive_restore to find a trashed item's exact path, or before drive_empty_trash to show the user what will be permanently deleted. " +
             "Do not use to list active (non-trashed) files — use drive_list instead.",
         annotations: { readOnlyHint: true, idempotentHint: true },
@@ -389,7 +406,7 @@ const TOOLS = [
                 },
                 message: {
                     type: "string",
-                    description: "Optional message included in the invitation email (max 2000 characters).",
+                    description: "Optional message included in the invitation email (max 500 characters — Proton rejects longer ones).",
                 },
             },
             required: ["path", "email", "role"],
@@ -443,7 +460,8 @@ const TOOLS = [
     {
         name: "drive_restore",
         description: "Restore a trashed file or folder back to its original Proton Drive path. Requires authentication. " +
-            "Use drive_list_trash first to find the item's current path in trash. " +
+            "Use drive_list_trash first to find the item's path (or uid) in trash. " +
+            "If several trashed items share the name, this refuses and lists their uids: the CLI can only address trashed items by name, so it cannot pick one of them (even by uid) — use the Proton Drive web or desktop app for that. " +
             "Fails if the original parent folder no longer exists or if a new item with the same name was created at that path since it was trashed. " +
             "Do not use for items not currently in trash — it will return an error.",
         annotations: { destructiveHint: false },
@@ -452,10 +470,14 @@ const TOOLS = [
             properties: {
                 path: {
                     type: "string",
-                    description: "Absolute remote Drive path of the item to restore, as shown in drive_list_trash output (must start with '/').",
+                    description: "Absolute remote Drive path of the item to restore, as shown in drive_list_trash output (must start with '/'). Give path or uid (or both).",
+                },
+                uid: {
+                    type: "string",
+                    description: "Trash uid from drive_list_trash. Pins the exact item you listed; if both path and uid are given they must refer to the same item.",
                 },
             },
-            required: ["path"],
+            required: [],
             additionalProperties: false,
         },
     },
@@ -626,6 +648,7 @@ const TOOLS = [
         name: "drive_share_remove_all",
         description: "Remove access for every member and every pending invitation (Proton and non-Proton) on a shared Proton Drive path, in a single call. Requires authentication and confirmed=true. " +
             "Use drive_share_status first to show the user who currently has access. " +
+            "Does NOT remove a public link — the result says if one is still active; remove it with drive_share_remove_url. " +
             "For removing one specific person, use drive_share_revoke instead — it is cheaper and less error-prone.",
         annotations: { destructiveHint: true },
         inputSchema: {
@@ -701,8 +724,8 @@ const TOOLS = [
     {
         name: "photos_delete_album",
         description: "Delete a Proton Photos album. Requires authentication and confirmed=true. " +
-            "By default refuses to delete an album that still contains photos — pass force=true to override. " +
-            "Photos live in your timeline independently of albums. save maps to the CLI's --save option (its exact effect is undocumented upstream) — leave it off unless the user asks. " +
+            "Refuses to delete an album that still contains photos unless force=true. " +
+            "Deleting an album never deletes your own photos — they stay in your timeline. save maps to the CLI's --save option (undocumented upstream; live testing showed no observable difference for your own photos) — leave it off unless the user asks. " +
             "albumPath must start with /albums/. " +
             "Always show the user the album name and photo count (from photos_list_albums) before calling.",
         annotations: { destructiveHint: true },
@@ -723,7 +746,7 @@ const TOOLS = [
                 },
                 save: {
                     type: "boolean",
-                    description: "If true, save album photos to your timeline before deleting. Default false.",
+                    description: "Passes the CLI's --save option (undocumented; no observable effect for your own photos, which always stay in the timeline). Default false.",
                 },
             },
             required: ["albumPath", "confirmed"],
@@ -733,7 +756,7 @@ const TOOLS = [
     {
         name: "photos_list_album_photos",
         description: "List the photos in a Proton Photos album. Requires authentication. " +
-            "Returns {items, total, offset, limit, hasMore} (default limit 100); items are [{nodeUid}], or with loadDetails=true also name, mediaType, sizes, captureTime and tags. " +
+            "Returns {items, total, offset, limit, hasMore} (default limit 100, newest capture first, ties by nodeUid — without loadDetails there is no captureTime, so the order is by nodeUid); items are [{nodeUid}], or with loadDetails=true also name, mediaType, sizes, captureTime and tags. Items come in a stable sorted order; each page is a fresh read, so changes made between page calls can still shift items. " +
             "albumPath must start with /albums/. " +
             "To add or remove photos, use their Drive path under /photos/ (not the nodeUid).",
         annotations: { readOnlyHint: true, idempotentHint: true },
@@ -797,7 +820,7 @@ const TOOLS = [
     {
         name: "photos_list_timeline",
         description: "List photos in your Proton Photos timeline (your full photo library, not scoped to an album). Requires authentication. " +
-            "Returns {items, total, offset, limit, hasMore} (default limit 50, newest first); items are [{nodeUid, captureTime, tags}], or with loadDetails=true also {name, mediaType, creationTime, totalStorageSize} (about 50% more tokens). " +
+            "Returns {items, total, offset, limit, hasMore} (default limit 50, newest first, ties by nodeUid; each page is a fresh read, so changes between page calls can still shift items); items are [{nodeUid, captureTime, tags}], or with loadDetails=true also {name, mediaType, creationTime, totalStorageSize} (about 50% more tokens). " +
             "Use photos_download to download items by path, or photos_add_to_album to add them to an album.",
         annotations: { readOnlyHint: true, idempotentHint: true },
         inputSchema: {
@@ -814,7 +837,8 @@ const TOOLS = [
     },
     {
         name: "photos_download",
-        description: "Download one or more photos from Proton Photos (timeline, an album, or shared-with-me) to a local folder. Requires authentication. " +
+        description: "Download one or more photos from your Proton Photos timeline to a local folder by their /photos/<name> path. Requires authentication. " +
+            "/albums/<album>/<photo> paths are not supported (the CLI rejects them) — download an album's photos via their /photos/<name> paths. " +
             "Multiple timeline photos can share the same filename — with conflictStrategy 'remove' or 'skip' only one copy survives locally; use 'rename' to keep all. " +
             "Fails if any item fails to download. " +
             "Do not use for regular Drive files — use drive_download instead.",
@@ -846,7 +870,7 @@ const TOOLS = [
     {
         name: "photos_upload",
         description: "Upload one or more local photo or video files directly into your Proton Photos library (My Photos timeline). Requires authentication. " +
-            "Non-photo/video files are silently skipped. Folders are recursed but flattened into My Photos — folder structure is not preserved. " +
+            "Non-photo/video files are skipped and counted in skippedItems (alongside duplicate skips). Folders are recursed but flattened into My Photos — folder structure is not preserved. " +
             "Never overwrites — duplicates (matched by name + content hash) resolve to 'rename' or 'skip' only. " +
             "Do not use for regular Drive files — use drive_upload instead.",
         annotations: { openWorldHint: true },
@@ -874,7 +898,7 @@ const TOOLS = [
         description: "Read the text contents of a file from the local Proton Drive sync folder. " +
             "Requires the PROTON_DRIVE_SYNC_PATH environment variable to point to the root of the synced folder (e.g. /Users/alice/Proton Drive). " +
             "The Proton Drive desktop app must be running and the file must be synced locally. " +
-            "Limited to text files up to 1 MB — returns an error for binary files or larger files (use drive_download instead). " +
+            "Limited to UTF-8 text files up to 1 MB — returns an error for binary, non-UTF-8 or larger files (use drive_download instead). " +
             "Do not use for files not yet synced locally, binary files, or files over 1 MB — use drive_download instead.",
         annotations: { readOnlyHint: true },
         inputSchema: {
@@ -882,7 +906,7 @@ const TOOLS = [
             properties: {
                 path: {
                     type: "string",
-                    description: "Absolute remote Drive path of the file to read (must start with '/'). Mapped to the local sync folder. E.g. /my-files/notes.txt",
+                    description: "Absolute remote Drive path of the file to read (must start with '/'). /my-files/<rest> maps to <PROTON_DRIVE_SYNC_PATH>/<rest> (the sync folder's top level is /my-files). Other Drive roots (/photos, /albums, /trash, /photos-trash, /shared-with-me, /shared-by-me, /devices) are rejected — only /my-files is synced. Legacy: a path not starting with a Drive root is taken relative to the sync folder. E.g. /my-files/notes.txt",
                 },
             },
             required: ["path"],
@@ -903,7 +927,7 @@ const TOOLS = [
             properties: {
                 path: {
                     type: "string",
-                    description: "Absolute remote Drive path of the file to write (must start with '/'). Mapped to the local sync folder. E.g. /my-files/notes.txt",
+                    description: "Absolute remote Drive path of the file to write (must start with '/'). /my-files/<rest> maps to <PROTON_DRIVE_SYNC_PATH>/<rest> (the sync folder's top level is /my-files). Other Drive roots (/photos, /albums, /trash, /photos-trash, /shared-with-me, /shared-by-me, /devices) are rejected — only /my-files is synced. Legacy: a path not starting with a Drive root is taken relative to the sync folder. E.g. /my-files/notes.txt",
                 },
                 content: {
                     type: "string",
@@ -1059,14 +1083,14 @@ export async function main() {
                     if (a.confirmed !== true) {
                         return fail("drive_delete requires confirmed=true. Ask the user to confirm before deleting.");
                     }
-                    const deletePath = validateRemotePath(a.path);
-                    await drive.delete(deletePath);
-                    return ok({ message: `Deleted: ${deletePath}` });
+                    const deletePath = a.path === undefined ? undefined : validateRemotePath(a.path);
+                    const deleteUid = a.uid ? validateFlagValue(a.uid, "uid") : undefined;
+                    await drive.delete(deletePath, deleteUid);
+                    return ok({ message: `Deleted: ${deletePath ?? `uid ${deleteUid}`}` });
                 }
                 case "drive_list_trash": {
                     const trashed = await drive.listTrash();
-                    if (trashed.some((f) => f.trashedAt))
-                        trashed.sort((x, y) => (y.trashedAt ?? "").localeCompare(x.trashedAt ?? ""));
+                    trashed.sort(byTimeDescThenId((f) => f.trashedAt, (f) => f.uid));
                     return ok(paginate(trashed, a, PAGE_DEFAULTS.drive_list_trash));
                 }
                 case "drive_share_status":
@@ -1102,9 +1126,10 @@ export async function main() {
                     return ok({ message: `Moved to trash: ${trashPath}` });
                 }
                 case "drive_restore": {
-                    const restorePath = validateRemotePath(a.path);
-                    await drive.restore(restorePath);
-                    return ok({ message: `Restored from trash: ${restorePath}` });
+                    const restorePath = a.path === undefined ? undefined : validateRemotePath(a.path);
+                    const restoreUid = a.uid ? validateFlagValue(a.uid, "uid") : undefined;
+                    await drive.restore(restorePath, restoreUid);
+                    return ok({ message: `Restored from trash: ${restorePath ?? `uid ${restoreUid}`}` });
                 }
                 case "drive_empty_trash":
                     if (a.confirmed !== true) {
@@ -1173,8 +1198,9 @@ export async function main() {
                         return fail("drive_share_remove_all requires confirmed=true. Use drive_share_status first to show the user who has access.");
                     }
                     const removeAllPath = validateRemotePath(a.path);
-                    const removedCount = await drive.shareRemoveAll(removeAllPath);
-                    return ok({ message: removedCount === 0 ? `Nothing to remove: ${removeAllPath} has no members or pending invitations.` : `Removed all access (${removedCount} member/invitation(s)) to: ${removeAllPath}` });
+                    const removeAll = await drive.shareRemoveAll(removeAllPath);
+                    const linkNote = removeAll.publicLink ? " A public link is still active — anyone with it keeps access; remove it with drive_share_remove_url." : "";
+                    return ok({ message: (removeAll.removed === 0 ? `Nothing to remove: ${removeAllPath} has no members or pending invitations.` : `Removed all members and invitations (${removeAll.removed}) from: ${removeAllPath}.`) + linkNote });
                 }
                 case "photos_list_albums":
                     return ok(await drive.listAlbums());
@@ -1194,7 +1220,7 @@ export async function main() {
                     if (!newName && !coverPhotoUid)
                         return fail("At least one of name or coverPhotoUid must be provided");
                     await drive.updateAlbum(updateAlbumPath, newName, coverPhotoUid);
-                    return ok({ message: `Album updated: ${updateAlbumPath}` });
+                    return ok({ message: `Album updated: ${newName ? `/albums/${newName}` : updateAlbumPath}` });
                 }
                 case "photos_delete_album": {
                     if (a.confirmed !== true)
@@ -1209,7 +1235,7 @@ export async function main() {
                     const albumListPath = validateRemotePath(a.albumPath);
                     if (!albumListPath.startsWith("/albums/"))
                         return fail("albumPath must start with /albums/");
-                    return ok(paginate(await drive.listAlbumPhotos(albumListPath, a.loadDetails === true), a, PAGE_DEFAULTS.photos_list_album_photos));
+                    return ok(paginate((await drive.listAlbumPhotos(albumListPath, a.loadDetails === true)).sort(photoOrder), a, PAGE_DEFAULTS.photos_list_album_photos));
                 }
                 case "photos_add_to_album": {
                     const addAlbumPath = validateRemotePath(a.albumPath);
@@ -1235,7 +1261,7 @@ export async function main() {
                     return ok({ message: `Removed ${remPhotoPath} from ${remAlbumPath}` });
                 }
                 case "photos_list_timeline":
-                    return ok(paginate(await drive.photoTimeline(a.loadDetails === true), a, PAGE_DEFAULTS.photos_list_timeline));
+                    return ok(paginate((await drive.photoTimeline(a.loadDetails === true)).sort(photoOrder), a, PAGE_DEFAULTS.photos_list_timeline));
                 case "photos_download": {
                     if (!Array.isArray(a.photoPaths) || a.photoPaths.length === 0)
                         return fail("photoPaths must be a non-empty array of strings");
@@ -1336,7 +1362,7 @@ export async function main() {
         if (!cliCheck.available) {
             logger.error(cliCheck.reason === "not_executable"
                 ? "proton-drive CLI found but not executable. Run: chmod +x $(which proton-drive)"
-                : "proton-drive CLI not found. Download from https://proton.me/download/drive/cli/index.html");
+                : "proton-drive CLI not found. Download from https://proton.me/download/drive/cli/index.html, or set PROTON_DRIVE_BIN to its absolute path (find it with `which proton-drive`).");
         }
     });
 }

package/dist/services/drive.js

@@ -1,5 +1,6 @@
 import { runDrive as defaultRunDrive, runDriveRaw as defaultRunDriveRaw } from "../utils/subprocess.js";
 import { DriveNotAuthenticatedError, DriveParseError } from "../utils/errors.js";
+import { validateName } from "../utils/validation.js";
 // The SDK verifies the author of every name (and several other fields)
 // cryptographically and returns a `Result<string, Error>`-shaped object —
 // {ok:true, value:"name"} on success, {ok:false, error:{...}} if the
@@ -54,6 +55,14 @@ function joinRemote(parent, escapedName) {
 // went on to rename whatever OTHER item happened to already be sitting at the
 // computed destination path — silently renaming an unrelated file while the
 // real source never moved.
+// The API's bare codes are opaque; these meanings were confirmed live
+// (2026-09-28) for the action they are keyed by.
+const READABLE_ERRORS = {
+    "Copy|InvalidRequirementsAPIError|2000": "Proton cannot copy this item: big folders cannot be copied yet (CLI limitation)",
+    "Move|InvalidRequirementsAPIError|2000": "the destination is inside the source, or the source no longer exists",
+    "Restore|APICodeError|2511": "its original parent folder is still in the trash — restore the parent first",
+    "Add to album|APICodeError|2500": "that photo is already in the album",
+};
 function assertItemsOk(result, action) {
     if (!Array.isArray(result))
         return;
@@ -63,6 +72,9 @@ function assertItemsOk(result, action) {
             const name = String(err.name ?? "unknown error");
             const code = typeof err.code !== "undefined" ? ` (code ${err.code})` : "";
             const message = typeof err.message === "string" && err.message ? `: ${err.message}` : "";
+            const readable = READABLE_ERRORS[`${action}|${name}|${err.code}`];
+            if (readable)
+                throw new Error(`${action} failed: ${readable} (${name}${code}${message})`);
             // Only a real collision deserves the collision hint — the same wrapper also
             // reports move-into-itself, restore-with-trashed-parent, etc.
             const hint = name === "NodeWithSameNameExistsValidationError"
@@ -72,6 +84,9 @@ function assertItemsOk(result, action) {
         }
     }
 }
+// Confirmed live: `sharing status /my-files` fails with "Error decrypting
+// session keys" — roots are not shareable nodes.
+const ROOT_PATHS = new Set(["/my-files", "/photos", "/albums", "/trash", "/photos-trash", "/shared-with-me", "/shared-by-me", "/devices"]);
 // Strips "<package-name>@" and "+<hash>" from a version token like
 // "cli-drive@0.8.0+06e8c605", leaving "0.8.0". Falls back to the raw
 // token if it doesn't match, so an unexpected future format still shows
@@ -181,26 +196,34 @@ export class DriveService {
             return [];
         if (!Array.isArray(result))
             throw new DriveParseError(`Expected array from list, got: ${JSON.stringify(result).slice(0, 100)}`);
-        return result.map((item) => {
-            if (item.name === undefined && typeof item.path === "string") {
-                return { name: item.path.replace(/^\//, ""), path: item.path, type: "folder" };
-            }
-            const name = unwrapResult(item.name, "[unnamed]");
-            const file = {
-                name,
-                path: joinRemote(remotePath, escapeNameForPath(name)),
-                type: item.type === "folder" || item.type === "album" ? "folder" : "file",
-                size: typeof item.totalStorageSize === "number" ? item.totalStorageSize : undefined,
-                modifiedAt: typeof item.modificationTime === "string" ? item.modificationTime : undefined,
-                mimeType: typeof item.mediaType === "string" ? item.mediaType : undefined,
-            };
-            if (opts.includeUid) {
-                file.uid = typeof item.uid === "string" ? item.uid : undefined;
-                const trashed = item.trashTime ?? item.trashedTime;
-                file.trashedAt = typeof trashed === "string" ? trashed : undefined;
-            }
-            return file;
-        });
+        // The CLI's order changes between calls and callers page by re-listing, so
+        // impose a total order: name, then uid (names are not unique).
+        const uidOf = (item) => (typeof item.uid === "string" ? item.uid : "");
+        const entries = result.map((item) => ({ item, file: this.mapListItem(item, remotePath, opts) }));
+        entries.sort((x, y) => x.file.name.localeCompare(y.file.name) || (uidOf(x.item) < uidOf(y.item) ? -1 : uidOf(x.item) > uidOf(y.item) ? 1 : 0));
+        return entries.map((e) => e.file);
+    }
+    mapListItem(item, remotePath, opts) {
+        if (item.name === undefined && typeof item.path === "string") {
+            return { name: item.path.replace(/^\//, ""), path: item.path, type: "folder" };
+        }
+        const name = unwrapResult(item.name, "[unnamed]");
+        const rev = (item.activeRevision ?? {});
+        const file = {
+            name,
+            path: joinRemote(remotePath, escapeNameForPath(name)),
+            type: item.type === "folder" || item.type === "album" ? "folder" : "file",
+            size: typeof rev.claimedSize === "number" ? rev.claimedSize : undefined,
+            storageSize: typeof item.totalStorageSize === "number" ? item.totalStorageSize : undefined,
+            modifiedAt: typeof item.modificationTime === "string" ? item.modificationTime : undefined,
+            mimeType: typeof item.mediaType === "string" ? item.mediaType : undefined,
+        };
+        if (opts.includeUid) {
+            file.uid = typeof item.uid === "string" ? item.uid : undefined;
+            const trashed = item.trashTime ?? item.trashedTime;
+            file.trashedAt = typeof trashed === "string" ? trashed : undefined;
+        }
+        return file;
     }
     async upload(localPath, remotePath, fileConflictStrategy = "skip", folderConflictStrategy = "skip") {
         const result = await this.run([
@@ -253,6 +276,7 @@ export class DriveService {
         if (name.includes("\\/")) {
             throw new Error(`folder name must not contain '/': ${remotePath}`);
         }
+        validateName(name);
         await this.run(["filesystem", "create-folder", parent, name]);
     }
     // Returns metadata (including latest revision details) for a single file or
@@ -297,9 +321,24 @@ export class DriveService {
             assertItemsOk(await this.run(["filesystem", "move", sourcePath, dst.parent]), "Move");
             return;
         }
-        const dstNames = new Set((await this.list(dst.parent)).map((f) => f.name));
+        const dstItems = await this.list(dst.parent);
+        const dstNames = new Set(dstItems.map((f) => f.name));
         if (dstNames.has(dst.name)) {
-            throw new Error(`Destination already exists: ${destinationPath}`);
+            // Only checked on this error path (costs a call): a missing source was
+            // otherwise misreported as "Destination already exists".
+            try {
+                await this.info(sourcePath);
+            }
+            catch (err) {
+                if (err instanceof Error && /not found/i.test(err.message)) {
+                    throw new Error(`Source not found: ${sourcePath}`);
+                }
+                throw err;
+            }
+            // Seen in live testing: passing the target folder itself as destinationPath is an easy mistake.
+            const isFolder = dstItems.find((f) => f.name === dst.name)?.type === "folder";
+            const hint = isFolder ? ` — it is a folder; to move into it, pass the full new path, e.g. ${joinRemote(destinationPath, src.name)}` : "";
+            throw new Error(`Destination already exists: ${destinationPath}${hint}`);
         }
         if (!dstNames.has(unescapeName(src.name))) {
             assertItemsOk(await this.run(["filesystem", "move", sourcePath, dst.parent]), "Move");
@@ -330,8 +369,9 @@ export class DriveService {
     // `filesystem delete` permanently deletes — but only items already inside
     // /trash or /photos-trash (the CLI rejects live paths). No --confirm flag
     // exists on the CLI side; our own confirmed-gate lives in the MCP layer.
-    async delete(remotePath) {
-        assertItemsOk(await this.run(["filesystem", "delete", remotePath]), "Delete");
+    async delete(remotePath, uid) {
+        const target = await this.resolveTrashTarget(remotePath, uid);
+        assertItemsOk(await this.run(["filesystem", "delete", target]), "Delete");
     }
     // Sharing
     //
@@ -347,6 +387,9 @@ export class DriveService {
     // nonProtonInvitations, not members — reading only `members` made a real,
     // successfully-sent invite completely invisible from this tool.
     async shareStatus(remotePath) {
+        if (ROOT_PATHS.has(remotePath)) {
+            throw new Error(`Roots cannot be shared — pass a file or folder inside it: ${remotePath}`);
+        }
         const result = await this.run(["sharing", "status", remotePath]);
         const r = (result ?? {});
         const VALID_ROLES = new Set(["viewer", "editor", "admin"]);
@@ -396,14 +439,16 @@ export class DriveService {
         }
         await this.shareRemove(remotePath, [match.email], false);
     }
-    // Removes every member and pending invitation. Returns how many there were —
-    // 0 means the item wasn't shared and nothing was sent to the CLI.
+    // Removes every member and pending invitation. `removed` is how many there
+    // were — 0 means nothing was sent to the CLI. `--everyone` does not touch the
+    // public link, so `publicLink` reports whether one is still active.
     async shareRemoveAll(remotePath) {
         const status = await this.shareStatus(remotePath);
+        const publicLink = Boolean(status.shareUrl);
         if (status.members.length === 0)
-            return 0;
+            return { removed: 0, publicLink };
         await this.shareRemove(remotePath, [], true);
-        return status.members.length;
+        return { removed: status.members.length, publicLink };
     }
     // General form of remove: specific emails, or --everyone to strip all
     // members and pending invitations (Proton and non-Proton) in one call.
@@ -418,12 +463,13 @@ export class DriveService {
     }
     // NOTE: set-url REPLACES the link's settings. Confirmed live: re-running it
     // without a password/expiration silently turned a password-protected link
-    // into an open one (same URL). When that is about to happen, say so.
+    // into an open one (same URL), and setting only a password cleared an
+    // existing expiration. When that is about to happen, say so.
     async shareSetUrl(remotePath, role = "viewer", password, expiration) {
         let droppedProtection = false;
-        if (!password && !expiration) {
+        if (!password || !expiration) {
             const before = await this.shareStatus(remotePath).catch(() => undefined);
-            droppedProtection = Boolean(before?.sharePasswordProtected || before?.shareUrlExpiresAt);
+            droppedProtection = Boolean((!password && before?.sharePasswordProtected) || (!expiration && before?.shareUrlExpiresAt));
         }
         const args = ["sharing", "set-url", remotePath, "--role", role];
         if (password)
@@ -433,7 +479,7 @@ export class DriveService {
         const result = await this.run(args);
         const link = this.parsePublicLink(result);
         if (droppedProtection) {
-            link.warning = "This link previously had a password and/or expiration; set_url replaces link settings, so they were removed. Pass password/expiration again to keep them.";
+            link.warning = "This link previously had a password and/or expiration; set_url replaces link settings, so whichever of them you did not pass again was removed. Pass both password and expiration to keep them.";
         }
         return link;
     }
@@ -463,8 +509,46 @@ export class DriveService {
     async trash(remotePath) {
         assertItemsOk(await this.run(["filesystem", "trash", remotePath]), "Trash");
     }
-    async restore(remotePath) {
-        assertItemsOk(await this.run(["filesystem", "restore", remotePath]), "Restore");
+    async restore(remotePath, uid) {
+        const target = await this.resolveTrashTarget(remotePath, uid);
+        assertItemsOk(await this.run(["filesystem", "restore", target]), "Restore");
+    }
+    // Confirmed live against CLI v0.8.0: restore/delete accept only /trash
+    // paths, and the CLI resolves /trash/<x> by decrypted NAME, taking the
+    // first match — "/trash/<uid>", a bare uid and "/my-files/<uid>" are all
+    // rejected, and renaming a trashed node fails. So a specific item among
+    // same-named duplicates cannot be addressed at all; the only safe move is
+    // to refuse. The uid pins the exact item the caller saw in drive_list_trash
+    // and is translated to its /trash/<name> path once that name is unique.
+    // /photos-trash gets the same duplicate check: it holds the user's trashed
+    // photos, where a same-named pair is easy to end up with.
+    // The lookup and the CLI call are two steps, so an item trashed under the
+    // same name in between is not detected.
+    async resolveTrashTarget(remotePath, uid) {
+        if (!remotePath && !uid)
+            throw new Error("Provide path or uid (from drive_list_trash).");
+        const root = remotePath?.match(/^\/(trash|photos-trash)\/(?:[^/\\]|\\.)+$/)?.[1];
+        if (!uid && !root)
+            return remotePath;
+        const trashed = await this.list(`/${root ?? "trash"}`, { includeUid: true });
+        let target = remotePath;
+        if (uid) {
+            const item = trashed.find((f) => f.uid === uid);
+            if (!item)
+                throw new Error(`No item with uid ${uid} in trash. Call drive_list_trash for current uids.`);
+            if (remotePath !== undefined && remotePath !== item.path) {
+                throw new Error(`path ${remotePath} does not match uid ${uid} (which is ${item.path} in trash).`);
+            }
+            target = item.path;
+        }
+        const matches = trashed.filter((f) => f.path === target);
+        if (matches.length > 1) {
+            const list = matches.map((f) => `uid ${f.uid ?? "?"} (trashed ${f.trashedAt ?? "unknown"})`).join("; ");
+            throw new Error(`${matches.length} trashed items share the path ${target}: ${list}. ` +
+                "The proton-drive CLI can only address trashed items by name, so it would act on an arbitrary one — refusing. " +
+                "Restore or delete the intended item in the Proton Drive web or desktop app instead.");
+        }
+        return target;
     }
     async emptyTrash() {
         await this.run(["filesystem", "empty-trash"]);
@@ -558,6 +642,18 @@ export class DriveService {
     }
     async deleteAlbum(albumPath, force, save) {
         await this.assertAlbumUnambiguous(albumPath);
+        // CLI 0.8.0 deletes a non-empty album even without --force (confirmed live).
+        if (!force) {
+            const name = unescapeName(albumPath.replace(/^\/albums\//, ""));
+            const album = (await this.listAlbums()).find((a) => a.name === name);
+            // Fail closed: if the album can't be matched, emptiness can't be checked.
+            if (!album) {
+                throw new Error(`Could not find album ${albumPath} in the album list to check that it is empty. Check the name with photos_list_albums, or pass force to delete it anyway.`);
+            }
+            if (album.photoCount > 0) {
+                throw new Error(`Album ${albumPath} still contains ${album.photoCount} photo(s). Pass force to delete it anyway (the photos stay in your timeline).`);
+            }
+        }
         const args = ["album", "delete", albumPath];
         if (force)
             args.push("--force");
@@ -603,6 +699,12 @@ export class DriveService {
         return result.map((item) => mapPhoto(item));
     }
     async photoDownload(remotePaths, localFolder, conflictStrategy = "skip") {
+        // CLI 0.8.0 treats everything after /albums/ as the album name
+        // ("Album not found: <album>/<photo>"), so album paths never work.
+        const albumPath = remotePaths.find((p) => p.startsWith("/albums/"));
+        if (albumPath) {
+            throw new Error(`Cannot download ${albumPath}: album paths are not supported by photo download. Use the photo's /photos/<name> path instead.`);
+        }
         const result = await this.run([
             "photo", "download", ...remotePaths, localFolder,
             "--conflict-strategy", conflictStrategy,

package/dist/utils/errors.js

@@ -1,7 +1,9 @@
 export class DriveCliNotFoundError extends Error {
     constructor() {
         super("proton-drive CLI not found in PATH. " +
-            "Download it from https://proton.me/download/drive/cli/index.html and ensure it is in your PATH.");
+            "Download it from https://proton.me/download/drive/cli/index.html and ensure it is in your PATH, " +
+            "or set PROTON_DRIVE_BIN to its absolute path (e.g. ~/.local/bin/proton-drive; find it with `which proton-drive`). " +
+            "Claude Desktop starts servers with a minimal PATH, so PROTON_DRIVE_BIN is usually needed there.");
         this.name = "DriveCliNotFoundError";
     }
 }

package/dist/utils/subprocess.js

@@ -176,6 +176,12 @@ function describeFailure(e) {
                 continue; // banner rules
             if (/^at\s/.test(line))
                 continue; // stack frames
+            // Bundled CLI source excerpts ("20075 |   code…" plus a "^" marker line)
+            // and an empty "Error details: {}" say nothing about what went wrong.
+            if (/^\d+\s*\|/.test(line) || /^\^+$/.test(line))
+                continue;
+            if (/^Error details:\s*(\{\})?$/.test(line) || line === "{}")
+                continue;
             if (!lines.includes(line))
                 lines.push(line);
         }
@@ -263,9 +269,32 @@ function parseJsonLoose(raw) {
     }
     throw new Error("no JSON found");
 }
+// Seen live with several clients using the CLI at once: its local SQLite cache
+// briefly fails with "database is locked" (SQLITE_BUSY). Read-only commands are
+// safe to re-run; writes are not retried, since a retry could repeat a mutation.
+const READ_ONLY_COMMANDS = new Set([
+    "filesystem list", "filesystem info", "sharing status", "invitation list",
+    "album list", "album photos", "photo timeline", "version",
+]);
+const LOCKED_RE = /database is locked|SQLITE_BUSY/i;
+async function execCliWithRetry(args, cliArgs) {
+    const readOnly = READ_ONLY_COMMANDS.has(args.slice(0, 2).join(" "));
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await execCli(cliArgs, timeoutFor(args));
+        }
+        catch (err) {
+            const e = err;
+            const locked = LOCKED_RE.test(`${e.stderr ?? ""}\n${e.stdout ?? ""}`);
+            if (!readOnly || !locked || e.cancelled || attempt >= 2)
+                throw err;
+            await new Promise((resolve) => setTimeout(resolve, 250 * (attempt + 1) + Math.random() * 250));
+        }
+    }
+}
 export async function runDrive(args) {
     try {
-        const { stdout, stderr } = await execCli([...args, "--json"], timeoutFor(args));
+        const { stdout, stderr } = await execCliWithRetry(args, [...args, "--json"]);
         const raw = stdout.trim();
         // Only check stderr for auth errors when stdout is empty. If the CLI wrote
         // valid JSON, we honour it even when warnings appear on stderr.
@@ -304,7 +333,7 @@ export async function runDrive(args) {
 // print plain text. This runs without appending --json and returns raw stdout.
 export async function runDriveRaw(args) {
     try {
-        const { stdout, stderr } = await execCli(args, timeoutFor(args));
+        const { stdout, stderr } = await execCliWithRetry(args, args);
         if (!stdout.trim() && stderr && stderr.trim() && isAuthError(stderr)) {
             throw new DriveNotAuthenticatedError();
         }

package/dist/utils/syncfs.js

@@ -15,9 +15,20 @@ function isInside(root, target) {
         return false;
     return rel !== ".." && !rel.startsWith(".." + sep);
 }
-/** Map a remote Drive path to an absolute local path inside syncRoot. Lexical only; rejects traversal. */
+// Drive roots other than /my-files are not part of the desktop sync folder.
+const UNSYNCED_ROOTS = ["photos", "albums", "trash", "photos-trash", "shared-with-me", "shared-by-me", "devices"];
+/**
+ * Map a remote Drive path to an absolute local path inside syncRoot. Lexical only; rejects traversal.
+ * The sync folder's top level is Drive's /my-files, so `/my-files/<rest>` maps to `<syncRoot>/<rest>`.
+ * Paths not under a known Drive root are (legacy) relative to the sync root.
+ */
 export function resolveSyncPath(syncRoot, remotePath) {
-    const rel = remotePath.replace(/^\//, "");
+    const trimmed = remotePath.replace(/^\//, "");
+    const first = trimmed.split("/", 1)[0];
+    if (UNSYNCED_ROOTS.includes(first)) {
+        throw new Error(`only /my-files is synced to the local folder; /${first} is not: ${remotePath}`);
+    }
+    const rel = first === "my-files" ? trimmed.slice("my-files".length).replace(/^\//, "") : trimmed;
     const resolved = resolve(join(syncRoot, rel));
     const root = resolve(syncRoot);
     if (!isInside(root, resolved)) {
@@ -116,7 +127,12 @@ export async function readSyncFile(syncRoot, remotePath) {
         if (data.includes(0)) {
             throw new Error(`${remotePath} appears to be a binary file. Use drive_download instead.`);
         }
-        return data.toString("utf8");
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(data);
+        }
+        catch {
+            throw new Error(`${remotePath} is not valid UTF-8 text. Use drive_download instead.`);
+        }
     }
     finally {
         await fh.close();

package/dist/utils/validation.js

@@ -42,8 +42,10 @@ export function validateMessage(message) {
         throw new Error(`message must not start with '-': ${m}`);
     if (CONTROL_RE.test(m))
         throw new Error("message contains control characters");
-    if (m.length > 2000)
-        throw new Error("message must be 2000 characters or fewer");
+    // Proton rejects invitation messages over 500 characters (confirmed live);
+    // count code points, not UTF-16 units, so emoji count once.
+    if ([...m].length > 500)
+        throw new Error("message must be 500 characters or fewer");
     return m;
 }
 // For bare filename/name arguments passed as a positional CLI arg (not a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proton-drive-mcp",
-  "version": "1.0.39",
+  "version": "1.1.0",
   "description": "MCP server and CLI that gives Claude full access to Proton Drive — upload, download, share, and manage your end-to-end encrypted files without leaving the conversation.",
   "type": "module",
   "main": "dist/index.js",