proton-drive-mcp 1.5.3 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +32 -0
- package/README.md +62 -8
- package/dist/cli.js +7 -3
- package/dist/index.js +363 -19
- package/dist/services/analytics.js +56 -7
- package/dist/services/changes.js +156 -0
- package/dist/services/content.js +16 -11
- package/dist/services/contentIndex.js +395 -0
- package/dist/services/contentSeal.js +168 -0
- package/dist/services/contentSearch.js +254 -0
- package/dist/services/readMany.js +50 -0
- package/dist/services/snapshot.js +62 -0
- package/dist/services/walk.js +5 -0
- package/dist/services/walkIndex.js +101 -37
- package/dist/utils/audit.js +248 -0
- package/dist/utils/contentKey.js +160 -0
- package/dist/utils/remoteroots.js +44 -0
- package/dist/utils/syncfs.js +15 -1
- package/glama.json +24 -0
- package/package.json +1 -1
- package/smithery.yaml +6 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,37 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.7.0 — 2026-11-01
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
- **Content search (opt-in, off by default)**: `PROTON_DRIVE_CONTENT_INDEX=1` enables two new MCP tools. **`drive_content_index`** (`path` required, `action`: `update` (default), `status`, `clear`; `maxFiles`, `maxFileMB`, `timeBudgetMs`) builds an incremental full-text index of the text of files under the folder you name (text/markdown/code, `.docx`, text-layer `.pdf`), two files at a time; secret-looking names are never read; changed files only are re-read; vanished files are dropped; `partial: true` with `remaining` means call again. **`drive_search_content`** (`query`, `path?`, `limit?`) returns ranked (BM25, all words must match, trailing `*` for a prefix) paths with snippets and `indexedAt`; it never re-lists Drive (`stale: true`).
|
|
7
|
+
- The index is one local file, `content-index.enc`, encrypted with AES-256-GCM in authenticated 1 MB chunks (wrong key, any changed, reordered, removed or appended byte, or another account's file fails closed), in the same private directory as the walk index, capped at 200 MB by default (`PROTON_DRIVE_CONTENT_INDEX_MAX_MB`; each search decrypts and loads the whole file, about 1 s and 600 MB near 500 MB). The key is generated on first use and kept in the macOS Keychain or the Linux Secret Service, passed over stdin so it never appears in a process listing; without a keychain it needs `PROTON_DRIVE_CONTENT_INDEX_KEY` (64 hex characters). `PROTON_DRIVE_KEYCHAIN_SERVICE` renames the keychain entry. No new dependencies, no native modules.
|
|
8
|
+
- Hardening of the index: credential-looking names are skipped much more broadly (`*.env`, `.npmrc`, `.netrc`, `.pgpass`, `id_dsa`/`id_ecdsa`, `*.kdbx`, `*.jks`, `*.asc`, `*.gpg`, names with `passw`, `hasło`, `token`, `api-key`, `service-account`, `kubeconfig`, ...). A key is never regenerated behind an existing index file (`update` stops with a clear message when the keychain no longer has it); keychain lookups count as "not found" only for macOS exit 44 and Linux exit 1 with empty stderr and no kill or timeout, so a transient D-Bus failure can no longer produce a new key. The size estimate counts every term (it undercounted about 5.7x); if a save would pass the cap the newest documents are dropped and the result says `partial: true`, `droppedForSize` instead of discarding the update. `clear` runs in the same queue as `update`, deletes the keychain item too (`keyRemoved`; rotating the key makes old backup copies unreadable) and says when a `PROTON_DRIVE_CONTENT_INDEX_KEY` key must be removed by hand. `status` checks the account before decrypting. Files with no size, time or hash are re-read; a cached listing older than 60 s is replaced by a fresh walk, and `listingAgeMs`/`fromCache` are reported.
|
|
9
|
+
- Both tools are read tools: available in `PROTON_DRIVE_MODE=readonly`, confined by `PROTON_DRIVE_REMOTE_ROOTS` (result paths outside the roots are dropped). The audit log records a search query as its length only. `proton-drive-cli index clear` also deletes `content-index.enc`. `clear` and `update` stay available in readonly mode because they change only the local index file.
|
|
10
|
+
|
|
11
|
+
### Notes
|
|
12
|
+
- The MCP server now lists 53 tools (51 in 1.6.0); the two new tools are MCP-only (the companion CLI still mirrors 45). The `tools/list` size budget in the tests rose from 45 KB to 48 KB (full tier is now about 46.9 KB).
|
|
13
|
+
- Threat model: protects against disk theft, backup leakage and other local users; not against a process running as you that can read your keychain. See the README section "Content search (opt-in)".
|
|
14
|
+
- Known limits: no rollback detection (an attacker who can write the index directory can swap in an older valid file: integrity, not freshness); no OCR; two server processes updating at once keep the last writer's file; the whole index is loaded into memory per search.
|
|
15
|
+
|
|
16
|
+
## 1.6.0 — 2026-11-01
|
|
17
|
+
|
|
18
|
+
### Added
|
|
19
|
+
- **Guard layer** (all opt-in, off by default; they apply to the MCP server only, so the companion `proton-drive-cli` bypasses them):
|
|
20
|
+
- `PROTON_DRIVE_MODE=readonly` hides and refuses every tool that changes Drive or the account (an invalid value fails closed to readonly). Every tool is classified as reading or mutating, and a test fails if a new tool is not.
|
|
21
|
+
- `PROTON_DRIVE_REMOTE_ROOTS` confines every Drive path argument to the listed folders; tools that cannot be limited to a folder (trash, invitations, photos, sign-out) are refused while it is set.
|
|
22
|
+
- `PROTON_DRIVE_AUDIT_LOG` appends a hash-chained JSON line per tool call, refused calls included, with passwords and file text redacted (only the byte length of written content is kept); appends from several server processes are serialized with a lock file, and the server refuses to start when the log lies inside `PROTON_DRIVE_SYNC_PATH`; if the log cannot be written, tools that change Drive are refused. New tool **`drive_audit_log`** returns the newest entries and checks the chain.
|
|
23
|
+
- `PROTON_DRIVE_SNAPSHOT_BEFORE_OVERWRITE=1` keeps the previous version as `.versions/<name>.<timestamp>` before an overwrite: `drive_write_file` copies the existing local sync file (inside the sync folder), `drive_upload` (`replace`) copies the remote file. The overwrite is refused if the copy fails, if the remote state cannot be determined (e.g. CLI missing), or when a folder would be replaced.
|
|
24
|
+
- **`drive_recent_changes`**: files added or modified since a date (`7d`, `12h`, `2w` or an ISO date). With `snapshot: "diff" | "save"` and `PROTON_DRIVE_INDEX=1` it compares against a saved per-path snapshot and reports added, removed, modified and moved files. An incomplete walk never overwrites a snapshot. `proton-drive-cli index clear` also removes the snapshot file.
|
|
25
|
+
- **`drive_share_expiry_report`**: public links with `expiresAt`, `daysLeft` and the flags `expired`, `expiringSoon`, `noExpiry`, `hasPassword`. Built on the sharing audit, so it keeps its limit of 100 shared items and reports `capped`.
|
|
26
|
+
- **`drive_read_many`**: reads the text of up to 10 files in one call, two at a time, with per-file and total character caps. One failing file does not fail the batch.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
- `drive_share_set_url` now refuses, before changing anything, to replace a link whose password and/or expiration the call omits (set-url replaces all link settings), naming what would be lost. Pass them again, or pass the new `resetSettings: true` to drop them on purpose. It also refuses when the existing settings cannot be read. Previously this only produced a warning after the fact.
|
|
30
|
+
|
|
31
|
+
### Notes
|
|
32
|
+
- Known limits: audit entries are written after the change; the audit-log lock can fork the chain only if a crashed holder and contention coincide; a contended append blocks the server for up to ~4 s; the local `.versions` copy has no size cap. The `drive_share_set_url` link check was confirmed against the live CLI (`urlAccess.customPassword`, `expirationTime`).
|
|
33
|
+
- The MCP server now lists 51 tools (47 in 1.5.3). The three new tools are MCP-only; the companion CLI still mirrors 45.
|
|
34
|
+
|
|
3
35
|
## 1.5.3 — 2026-10-31
|
|
4
36
|
|
|
5
37
|
### Security
|
package/README.md
CHANGED
|
@@ -58,7 +58,7 @@ What to expect: search matches names, sizes and dates, not the text of every fil
|
|
|
58
58
|
|
|
59
59
|
- **Claude manages your Proton Drive** — list, upload, download, move, share, trash, restore
|
|
60
60
|
- **Proton Photos album management** — list albums, create/delete albums, add and remove photos
|
|
61
|
-
- **Companion CLI** — 45 of the
|
|
61
|
+
- **Companion CLI** — 45 of the 53 operations, scriptable and pipeable, works in cron and shell scripts (the two sync-folder tools, `drive_read_file` and `drive_write_file`, `drive_audit_log` and the newer `drive_read_many`, `drive_share_expiry_report`, `drive_recent_changes`, `drive_content_index` and `drive_search_content` are MCP-only)
|
|
62
62
|
- **Full Proton Drive CLI command coverage** — all 32 scriptable commands of CLI 0.8.0 have a matching tool (checked against the CLI's own help; `auth login` is the one command excluded, since it's an interactive browser flow). Not every optional flag is exposed: `sharing invite --include-node-name` is deliberately off (it would put the file name in the invitation email in clear text) and the `inherited` invite role is not offered; commands that accept several paths run one path per call except bulk move and bulk trash
|
|
63
63
|
- **Zero credential exposure** — auth is handled entirely by the official Proton Drive CLI; this MCP never touches your password or session token
|
|
64
64
|
- **Shell injection safe** — all CLI calls use `execFile` with discrete argument arrays, never string interpolation
|
|
@@ -277,7 +277,7 @@ proton-drive-cli index clear
|
|
|
277
277
|
- The first walk of a large drive can take minutes (measured about 21 s per 1,200 files at the default concurrency (12); about 25 s at concurrency 8). `drive_search`, `drive_tree` and `drive_usage` stop waiting after 25 s (`PROTON_DRIVE_WALK_BUDGET_MS`, 0 = never) and return what was listed so far with `partial: true`, `continuing: true` (the walk is still running) and a `note`; the same walk keeps running in the background, so repeating the call returns the full result from cache. `drive_find_duplicates`, `drive_sharing_audit` and `drive_sync_plan` always wait for the complete walk. Later calls reuse a 5-minute in-memory cache; `refresh` bypasses it. With the opt-in persistent index, a saved copy up to 24 h old can answer first (marked `stale: true`).
|
|
278
278
|
- Walks skip `.git` and `node_modules` by default.
|
|
279
279
|
- With `PROTON_DRIVE_INDEX=1`, results may come from a saved index (`stale: true` = served from the saved index, not a walk made now) while a refresh runs; repeat the call or pass `refresh: true` for a fresh read. Off by default, see [Persistent index](#persistent-index-opt-in).
|
|
280
|
-
- Read-only tools (`drive_search`, `drive_tree`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `drive_sync_plan`) change nothing. `drive_bulk_move` and `drive_bulk_trash` are two-step: call without `confirmed` for the plan, then with `confirmed: true` to apply. Bulk trash is reversible with `drive_restore`.
|
|
280
|
+
- Read-only tools (`drive_search`, `drive_tree`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `drive_share_expiry_report`, `drive_recent_changes`, `drive_sync_plan`) change nothing. `drive_bulk_move` and `drive_bulk_trash` are two-step: call without `confirmed` for the plan, then with `confirmed: true` to apply. Bulk trash is reversible with `drive_restore`.
|
|
281
281
|
- Duplicate detection uses the sha1 the uploader claimed, which is unverified. `verify: true` downloads the candidates and hashes them.
|
|
282
282
|
- The sharing audit flags an invitee as external when the address is outside Proton domains, so Proton users on a custom domain are over-flagged.
|
|
283
283
|
- Sizes are sums of file sizes, not your account quota.
|
|
@@ -292,7 +292,8 @@ By default every new server process (each Claude Desktop session) walks the driv
|
|
|
292
292
|
- **What is stored:** the node list of up to 8 recent complete walks under `/my-files` (partial or failed walks are never saved, so a `drive_tree` that stops at its depth limit is not stored), plus a fingerprint of your account's Drive root. No file contents, no credentials, no tokens.
|
|
293
293
|
- **Where:** `PROTON_DRIVE_INDEX_DIR` if set; otherwise `~/Library/Caches/proton-drive-mcp` (macOS) or `$XDG_CACHE_HOME/proton-drive-mcp` / `~/.cache/proton-drive-mcp` (Linux). One file, `walk-index.json`, mode `0600` in a `0700` directory, written atomically. Use a dedicated directory: a pre-existing directory with group/other access (or owned by someone else) is refused with one warning and never chmodded; a missing one is created `0700`. A symlinked directory or file is refused. A saved file with loose permissions, another owner, a future timestamp, or above 200 MB is ignored. Not written above 200 MB.
|
|
294
294
|
- **Account check:** before any saved data is served, one `list /my-files` (~2 s) confirms it belongs to the account that is logged in now; if the check fails (network, rate limit) nothing is served from disk for that call and the file is kept; a proven account mismatch deletes it. Either way the drive is walked fresh.
|
|
295
|
-
- **Freshness:** data up to `PROTON_DRIVE_INDEX_MAX_AGE_H` hours old (default 24; `0` = never use saved data) is returned immediately with `stale: true` (and `refreshing: true` while one background walk replaces it); a repeated call then returns the fresh walk. A failed or incomplete background walk is not retried for 5 minutes within the same server process (`PROTON_DRIVE_INDEX_REFRESH_COOLDOWN_MS`); a new process tries once again. The saved data is account-checked first (see above). `drive_sync_plan`, `drive_find_duplicates
|
|
295
|
+
- **Freshness:** data up to `PROTON_DRIVE_INDEX_MAX_AGE_H` hours old (default 24; `0` = never use saved data) is returned immediately with `stale: true` (and `refreshing: true` while one background walk replaces it); a repeated call then returns the fresh walk. A failed or incomplete background walk is not retried for 5 minutes within the same server process (`PROTON_DRIVE_INDEX_REFRESH_COOLDOWN_MS`); a new process tries once again. The saved data is account-checked first (see above). `drive_sync_plan`, `drive_find_duplicates`, the sharing audit and `drive_recent_changes` never use saved data. `refresh: true` always does a blocking fresh walk. Writes made through this server drop the affected entries from memory and disk.
|
|
296
|
+
- **Change snapshots:** `drive_recent_changes` with `snapshot` stores a second plaintext file, `changes-snapshot.json`, in the same directory under the same rules (see [Recent changes](#recent-changes)); it is only written when you ask for `snapshot: "save"`, and `index clear` removes it as well.
|
|
296
297
|
- **Read-only directory:** an index in a directory (or file) you cannot write to is ignored, because it could not be kept current after the server's own writes.
|
|
297
298
|
- **Limits:** `drive_tree` with a depth limit is not answered from the saved full walk (it walks live); changes made by other clients or processes are not seen until the data is refreshed.
|
|
298
299
|
- **Check or remove it:** `proton-drive-cli index status` and `proton-drive-cli index clear` (or just delete the file). In the MCPB bundle, the **Persistent search index** setting is the opt-in.
|
|
@@ -340,7 +341,7 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
|
|
|
340
341
|
`drive_auth_status` · `drive_auth_logout` · `drive_version`
|
|
341
342
|
|
|
342
343
|
### Filesystem
|
|
343
|
-
`drive_list` · `drive_info` · `drive_read_content` · `drive_tree` · `drive_search` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
|
|
344
|
+
`drive_list` · `drive_info` · `drive_read_content` · `drive_read_many` · `drive_tree` · `drive_search` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
|
|
344
345
|
|
|
345
346
|
### Sharing
|
|
346
347
|
`drive_share_status` · `drive_share_invite` · `drive_share_revoke` · `drive_share_remove_all` · `drive_share_set_url` · `drive_share_remove_url`
|
|
@@ -361,7 +362,13 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
|
|
|
361
362
|
`drive_list_invitations` · `drive_invitation_accept` · `drive_invitation_reject` · `drive_share_leave`
|
|
362
363
|
|
|
363
364
|
### Analytics
|
|
364
|
-
`drive_usage` · `drive_find_duplicates` · `drive_sharing_audit`
|
|
365
|
+
`drive_usage` · `drive_find_duplicates` · `drive_sharing_audit` · `drive_share_expiry_report` · `drive_recent_changes`
|
|
366
|
+
|
|
367
|
+
### Content search (opt-in, see [Content search](#content-search-opt-in))
|
|
368
|
+
`drive_content_index` · `drive_search_content`
|
|
369
|
+
|
|
370
|
+
### Audit (see [Guard layer](#guard-layer-opt-in))
|
|
371
|
+
`drive_audit_log`
|
|
365
372
|
|
|
366
373
|
### Photos
|
|
367
374
|
`photos_list_albums` · `photos_create_album` · `photos_update_album` · `photos_delete_album` · `photos_list_album_photos` · `photos_add_to_album` · `photos_remove_from_album` · `photos_list_timeline` · `photos_download` · `photos_upload`
|
|
@@ -378,6 +385,7 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
|
|
|
378
385
|
| `drive_list` | List files and folders at a path (paginated, default 200; `/` lists the roots) | `path`, `limit?`, `offset?` |
|
|
379
386
|
| `drive_info` | Get metadata for one file/folder, including revision details (noise trimmed) | `path`, `verbose?` (raw CLI node) |
|
|
380
387
|
| `drive_read_content` | Read the text of a file stored in Drive (no sync folder needed): text/code, `.docx`, text-layer `.pdf`. Paged; content is untrusted data. See [Reading file contents](#reading-file-contents) | `path`, `maxChars?` (default 20000, max 100000), `offset?` |
|
|
388
|
+
| `drive_read_many` | Read the text of up to 10 Drive files in one call, two at a time; per-file and total character caps; one failing file does not fail the rest. Content is untrusted data. See [Reading file contents](#reading-file-contents) | `paths` (max 10), `maxCharsPerFile?` (default 4000, max 20000), `maxTotalChars?` (default 40000, max 100000) |
|
|
381
389
|
| `drive_tree` | Folder overview: per-folder file counts and size totals (largest first), depth-limited, cached 5 min | `path?`, `depth?` (default 2, max 10), `limit?`, `foldersOnly?`, `refresh?` |
|
|
382
390
|
| `drive_search` | Find files/folders under a path in one cached walk: name (substring/glob; a glob containing `/` matches the path relative to `path`), type, extension, MIME prefix, size, modified date; sortable, paginated. Reports `walk.complete` — false means the walk was cut short and matches may be missing | `query?`, `glob?`, `path?`, `type?`, `mediaType?`, `extensions?`, `minSize?`, `maxSize?`, `modifiedAfter?`, `modifiedBefore?`, `sort?`, `limit?` (default 50, max 500), `offset?`, `refresh?` |
|
|
383
391
|
| `drive_mkdir` | Create a new empty folder | `path` |
|
|
@@ -392,10 +400,15 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
|
|
|
392
400
|
| `drive_usage` | Storage analytics for a subtree: totals, largest files/folders, extension and media-type breakdown, old files, trash stats (sum of file sizes, not the account quota) | `path?`, `top?`, `olderThanDays?`, `refresh?` |
|
|
393
401
|
| `drive_find_duplicates` | Likely duplicate groups (claimed sha1 / same size; `verify` downloads and sha256s candidates), wasted bytes, suggested keeper — never deletes | `path?`, `minSize?`, `verify?`, `maxVerifyBytes?`, `maxVerifyTotalBytes?` (default 500 MB, max 2 GB), `limit?`, `refresh?` |
|
|
394
402
|
| `drive_sharing_audit` | Public links (no URL), invitees, pending invitations and risk flags for shared items (max 100) | `path?`, `refresh?` |
|
|
403
|
+
| `drive_share_expiry_report` | Public links under a path with `expiresAt`, `daysLeft` and flags `expired`, `expiringSoon`, `noExpiry`, `hasPassword`, soonest first. Uses the sharing audit walk (max 100 shared items; `capped` says when more exist). Lists only links set directly on items below `path`: a link on the folder passed as `path` itself is not listed, so pass its parent. Changes nothing | `path?`, `withinDays?` (default 14), `refresh?` |
|
|
404
|
+
| `drive_recent_changes` | Files added or modified since a date (`since`: ISO date or `7d`/`12h`/`2w`, default 7d), from one complete walk. With `snapshot: "diff"` or `"save"` (needs `PROTON_DRIVE_INDEX=1`): added, removed, modified and moved files against the previous snapshot of that path. See [Recent changes](#recent-changes) | `path?`, `since?`, `limit?` (default 50, max 500), `snapshot?`, `refresh?` |
|
|
405
|
+
| `drive_content_index` | Opt-in (`PROTON_DRIVE_CONTENT_INDEX=1`): build or refresh an **encrypted local** full-text index of the files under one folder you name (text, markdown, `.docx`, text-layer `.pdf`); `status` and `clear` actions. Secret-looking names are skipped. Changes nothing on Drive, writes one local file (also in readonly mode). See [Content search](#content-search-opt-in) | `path` (required for `update`), `action?` (`update` default, `status`, `clear`), `maxFiles?` (default 200), `maxFileMB?` (default 20), `timeBudgetMs?` (default 25000) |
|
|
406
|
+
| `drive_search_content` | Search the indexed file text: all words must match, BM25 ranking, trailing `*` = prefix on the last word. Returns path, score, snippet, `indexedAt`; results reflect the last index update (`stale: true`). Snippets are untrusted file content. See [Content search](#content-search-opt-in) | `query` (max 200 characters), `path?`, `limit?` (default 10, max 50) |
|
|
407
|
+
| `drive_audit_log` | Newest audit-log entries plus a hash-chain check (needs `PROTON_DRIVE_AUDIT_LOG`; works in readonly mode) | `limit?` (default 50) |
|
|
395
408
|
| `drive_share_invite` | Invite a user (sends an email) ⚠️ | `path`, `email`, `role` (viewer/editor/admin), `message?`, `confirmed: true` |
|
|
396
409
|
| `drive_share_revoke` | Revoke one person's access (fails if not a member) ⚠️ | `path`, `email`, `confirmed: true` |
|
|
397
410
|
| `drive_share_remove_all` | Remove every member + pending invitation at once ⚠️ | `path`, `confirmed: true` |
|
|
398
|
-
| `drive_share_set_url` | Create/replace a public share link ⚠️ (
|
|
411
|
+
| `drive_share_set_url` | Create/replace a public share link ⚠️ (set-url replaces all link settings; if the path already has a link with a password and/or expiration that the call omits, it is refused before any change unless `resetSettings: true`; expiry max ~90 days) | `path`, `role?` (viewer/editor), `password?`, `expiration?`, `resetSettings?`, `confirmed: true` |
|
|
399
412
|
| `drive_share_remove_url` | Remove the public share link ⚠️ | `path`, `confirmed: true` |
|
|
400
413
|
| `drive_trash` | Move to trash | `path` |
|
|
401
414
|
| `drive_sync_plan` | Read-only diff of a local folder vs a Drive folder (nothing transferred) | `localPath`, `drivePath`, `direction?` (up/down/both), `ignore?`, `compare?` (size-mtime/sha1), `limit?` |
|
|
@@ -453,12 +466,21 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
|
|
|
453
466
|
|
|
454
467
|
### Token cost
|
|
455
468
|
|
|
456
|
-
`tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full`
|
|
469
|
+
`tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 46.9 KB (53 tools), `core` 17.9 KB (19 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
|
|
457
470
|
|
|
458
471
|
`drive_auth_status`, `drive_version`, `drive_list`, `drive_info`, `drive_read_content`, `drive_list_trash`, `drive_search`, `drive_tree`, `drive_mkdir`, `drive_upload`, `drive_download`, `drive_rename`, `drive_move`, `drive_copy`, `drive_trash`, `drive_restore`, `drive_share_status`, `photos_list_timeline`, `photos_download`.
|
|
459
472
|
|
|
460
473
|
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.
|
|
461
474
|
|
|
475
|
+
### Guard layer (opt-in)
|
|
476
|
+
|
|
477
|
+
Four environment variables limit what a model (or a prompt-injected one) can do with your Drive. All are read once at startup and are off by default. They apply to the MCP server only: the companion CLI (`proton-drive-cli`) is a tool you run yourself and is not restricted by them.
|
|
478
|
+
|
|
479
|
+
- **`PROTON_DRIVE_MODE=readonly`** hides every tool that changes Drive or the account from `tools/list` and refuses it at call time (no CLI command runs). Hidden: `drive_upload`, `drive_mkdir`, `drive_rename`, `drive_move`, `drive_copy`, `drive_trash`, `drive_restore`, `drive_delete`, `drive_empty_trash`, `drive_bulk_move`, `drive_bulk_trash`, `drive_write_file`, `drive_auth_logout`, every `drive_share_*` that changes sharing (`invite`, `revoke`, `set_url`, `remove_url`, `remove_all`, `leave`), `drive_invitation_accept`/`reject`, and `photos_create_album`, `photos_update_album`, `photos_delete_album`, `photos_add_to_album`, `photos_remove_from_album`, `photos_upload`. Reads, analytics and downloads to local disk stay. An invalid value is treated as `readonly`. Prompts that name a hidden tool are not offered.
|
|
480
|
+
- **`PROTON_DRIVE_REMOTE_ROOTS`** (list separated by `:` on macOS/Linux, `;` on Windows, e.g. `/my-files/Projects/X`) confines every Drive path argument to those folders. Paths are matched by whole segment and case-sensitively (`/my-files/AB` is not inside `/my-files/A`); `..` and empty (`//`) segments are refused. Paths include sources, destinations, bulk lists, walk roots (`drive_tree`, `drive_search`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `drive_share_expiry_report`, `drive_recent_changes`, `drive_sync_plan`, and the optional `path` of `drive_content_index` and `drive_search_content`, whose results outside the roots are dropped; their default `/my-files` is refused, so pass a `path`) and the sync-file tools. The root folder itself cannot be renamed, moved, trashed or left (`drive_share_leave`). `drive_usage` leaves out the account-wide trash summary. An entry that is not a clean absolute path is dropped with a warning; if none is left everything is refused. **These tools cannot be limited to a folder and are refused while roots are set:** `drive_auth_logout`, `drive_delete`, `drive_restore`, `drive_empty_trash`, `drive_list_trash` (trash is account-wide and addressed by name or UID), `drive_audit_log`, `drive_list_invitations`, `drive_invitation_accept`, `drive_invitation_reject`, and all ten `photos_*` tools. `drive_audit_log` is refused too, because its entries name paths outside the roots (read the file directly). `drive_auth_status` and `drive_version` touch no Drive content and keep working.
|
|
481
|
+
- **`PROTON_DRIVE_AUDIT_LOG=/absolute/path/audit.jsonl`** appends one JSON line per tool call, refused calls included: `ts`, `seq`, `tool`, redacted `args`, `outcome` (`ok`, `error` or `refused`), a short `code` (`roots`, `readonly`, `tier`, `confirm`, `audit`, `snapshot`, `invalid`, `cli_error`, ...), `durationMs`, and `prev`/`hash`, a SHA-256 chain over the previous hash and the record. The file is created `0600` (its folder `0700` if missing). Passwords and message bodies are never written; for `drive_write_file` only the byte length of the content is, and arguments a tool does not declare are recorded as present, never by value. If the log cannot be written, tools that change Drive are refused (reads continue, with a warning on stderr). `drive_audit_log` returns the newest entries (default 50, full tier only, not available while roots are set) and `verification`: `{ok: true, entries, head}` or the first broken `seq`. The chain detects edited, inserted, reordered and mid-file removed lines, not removal of the newest lines: keep `head` somewhere else if you need that. Several servers can share one file (appends are serialized with a `<log>.lock` file; if it cannot be taken within a few seconds the write counts as failed). The server refuses to start when the log lies inside `PROTON_DRIVE_SYNC_PATH`. **An entry is written after the call finishes, so a crash or kill in the middle of an operation can leave a change that was never recorded.** The hash chain is only as trustworthy as the account that can write the file.
|
|
482
|
+
- **`PROTON_DRIVE_SNAPSHOT_BEFORE_OVERWRITE=1`** keeps the previous version before an overwrite (the result carries `snapshot`), as `<same folder>/.versions/<name>.<UTC timestamp>`. `drive_write_file` overwrites the local sync copy, so it copies the existing **local** file inside the sync folder (the sync client uploads the copy; unsynced local edits and files never uploaded are preserved). `drive_upload` with `fileConflictStrategy: replace` copies the existing **remote** file. If the copy fails, or the remote state cannot be determined (for example the CLI is missing), the overwrite is refused. Replacing a folder is not versioned and is refused too: `drive_upload` of a folder with a `replace` strategy, or onto a remote folder, while snapshots are on. A file that does not exist yet has nothing to preserve. Snapshots are never pruned.
|
|
483
|
+
|
|
462
484
|
### Reading file contents
|
|
463
485
|
|
|
464
486
|
`drive_read_content` returns the text of a file stored in Drive, without a sync folder: it downloads the file into a private temp directory (mode 0700, always removed afterwards), extracts the text and returns it in pages (`offset` / `maxChars`, default 20000, max 100000 characters; the reply carries `nextOffset` while more remains). Expect 2-4 s per read.
|
|
@@ -469,6 +491,30 @@ Left out of `core` (use `full`): permanent deletion (`drive_delete`, `drive_empt
|
|
|
469
491
|
- **Untrusted content:** file text comes from your drive and may contain instructions aimed at the model (prompt injection). The tool returns it as data, nothing is executed, and its description tells the model to treat it as data, never as instructions.
|
|
470
492
|
- **Optional packages:** `.docx` needs `fflate` and `.pdf` needs `unpdf`; both are optional dependencies of this package, installed by default (and included in the MCPB bundle). If they were omitted (`npm install --omit=optional`), PDF/DOCX reading returns a clear error naming the package to install (`npm install fflate unpdf`); text formats work without them. The test suite skips the PDF/DOCX groups with a reason when the packages are missing (never on CI, where they fail instead).
|
|
471
493
|
|
|
494
|
+
`drive_read_many` takes up to 10 paths and applies the same rules to each file (formats, size cap, isolated parsing, untrusted content). Files are read two at a time, because the CLI fails with "database is locked" under heavier parallelism. Each result is `{path, ok, text?, truncated?, nextOffset?, error?}`, so one unreadable file does not fail the others. Text is capped per file (`maxCharsPerFile`, default 4000, max 20000) and over the whole call (`maxTotalChars`, default 40000); once the total is used up, remaining files report `skipped`. Continue a truncated file with `drive_read_content` and `offset = nextOffset`. With `PROTON_DRIVE_REMOTE_ROOTS` set, every path must be inside a root or the whole call is refused.
|
|
495
|
+
|
|
496
|
+
### Recent changes
|
|
497
|
+
|
|
498
|
+
`drive_recent_changes` answers "what changed in this folder?" in two ways.
|
|
499
|
+
|
|
500
|
+
- **Since a date** (default): files whose original modification time or upload time is at or after `since` (an ISO date, or a relative age such as `7d`, `12h`, `2w`; default `7d`), newest first, from one complete walk that never reads the saved index. It cannot tell "added" from "modified" and sees only what the walk data shows: a file changed in place with an old claimed modification time and no re-upload is missed.
|
|
501
|
+
- **Against a snapshot** (`snapshot: "diff"` or `"save"`): only with `PROTON_DRIVE_INDEX=1`, because it keeps a plaintext list of file paths, sizes, modification times and claimed sha1 hashes (the same privacy trade-off as the [persistent index](#persistent-index-opt-in)); otherwise the call returns an error saying so. The list is stored per walked path in `changes-snapshot.json` next to `walk-index.json` (same private `0700` directory, `0600` file, atomic write, tied to the account fingerprint, not written above 50 MB, up to 8 paths kept; `proton-drive-cli index clear` removes it too). `diff` compares the current drive with the previous snapshot of that path and reports `added`, `removed`, `modified` and `moved` (a removed and an added file with the same size and the same non-empty claimed sha1; files without a sha1 show up as removed plus added). `save` does the same comparison and then stores the current state as the new baseline. If the walk was incomplete, nothing is saved (a partial list would later look like mass deletions) and `removed`/`moved` are left out of the answer.
|
|
502
|
+
|
|
503
|
+
### Content search (opt-in)
|
|
504
|
+
|
|
505
|
+
`drive_content_index` and `drive_search_content` let Claude find files by what is *inside* them (the built-in `drive_search` only matches names). Because Proton Drive is end-to-end encrypted, this works by keeping a searchable copy of the text on your machine, so it is **off by default** and you choose the folders: set `PROTON_DRIVE_CONTENT_INDEX=1`, then ask Claude to index a folder (for example `/my-files/Documents`). Nothing is indexed without an explicit `path`.
|
|
506
|
+
|
|
507
|
+
- **What is stored** (one file, `content-index.enc`, in the same private directory as the [walk index](#persistent-index-opt-in): mode `0600` in a `0700` directory, `PROTON_DRIVE_INDEX_DIR` to move it): the paths and sizes of the indexed files, the words each file contains with how often (a full-text index), and the first 64 KB of each file's text, compressed, for result snippets. All of it is encrypted. **Not stored:** the raw files, any encryption key, or text beyond the first 64 KB (words further in are searchable but have no snippet).
|
|
508
|
+
- **Encryption:** AES-256-GCM in 1 MB chunks, each with its own random nonce, authenticated together with the file header, the chunk position and an end-of-file flag, so a wrong key, a changed byte, reordered, removed or appended chunks and a file from another account are all refused with an error; nothing is returned from a file that did not verify, and there is no plaintext fallback. The 32-byte key is generated on first use and kept in the **macOS Keychain** (service `proton-drive-mcp-content-index`) or the Linux Secret Service (`secret-tool`, if installed). It is handed over on standard input, never as a command-line argument, so it does not appear in `ps`. Where there is no keychain (Windows, or Linux without `secret-tool`) the tools refuse unless you set `PROTON_DRIVE_CONTENT_INDEX_KEY` yourself. The index is bound to the signed-in Proton account and is refused if another account signs in.
|
|
509
|
+
- **Threat model:** protects the text of your drive against theft of the disk or laptop, backups and cloud sync of your home folder, and other local users. It does **not** protect against a process running as you that can read your keychain (it can read the key and the file), against malware on the machine, or against what you do with the results: snippets that Claude receives are sent to the model provider like any other file content.
|
|
510
|
+
- **Usage:** `drive_content_index` with `path` indexes up to `maxFiles` (default 200) changed files per call, two at a time, for at most `timeBudgetMs` (default 25 s); when the result says `partial: true` with `remaining`, call it again with the same path to continue. Unchanged files (same size, modification time and claimed hash) are not read again, files that disappeared from the folder are dropped, and one unreadable file never fails the call. Names that look like credentials are never read (checked on every path segment, case-insensitive): `.env*`, `*.env`, `*.env.*`, `.npmrc`, `.netrc`, `.pgpass`, `.htpasswd`, `.git-credentials`, `.pypirc`, `.dockercfg`, `id_rsa*`, `id_dsa*`, `id_ecdsa*`, `id_ed25519*`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.kdbx`, `*.keystore`, `*.jks`, `*.asc`, `*.gpg`, `*.keychain*`, and anything containing `passw` (also `Passwort`), `hasło`/`haslo`, `token`, `api-key`/`apikey`, `secret`, `credential`, `service-account`, `kubeconfig` or `private-key`. The check is by name only: a secret in a file with an ordinary name is indexed, so index the folders you mean to. A file whose listing gives no size, time or hash is always re-read. `drive_search_content` takes `query` (all words must match, ranked by BM25; end the last word with `*` for a prefix, `invoi*`), an optional `path` filter and `limit`. It does not re-list Drive: results are as of the last update (`indexedAt`, `stale: true`). `status` shows counts, size, covered folders and the key backend; it never shows the key.
|
|
511
|
+
- **Limits:** plain text/markdown/code, `.docx` and `.pdf` with a text layer only (no OCR; scanned PDFs are recorded as having no text), files up to `maxFileMB` and `PROTON_DRIVE_READ_MAX_BYTES` (10 MB by default). Expect about 2 to 4 s per file, two at a time: a first index of N files takes roughly N × 2 s ÷ 2 (1,000 files is about 20 to 30 minutes, over several calls). Words are runs of letters and digits of 2 to 40 characters; scripts written without spaces (Chinese, Japanese) are indexed as long runs and match poorly. A cached folder listing older than 60 seconds is not used by an update (it walks again); the result reports `listingAgeMs` and `fromCache`. The index file is capped (200 MB by default, `PROTON_DRIVE_CONTENT_INDEX_MAX_MB`). **Each search decrypts and loads the whole index**: roughly 1 s and 600 MB of memory near the old 500 MB size, hence the 200 MB default; keep the index to the folders you need. If an update would pass the cap, the newest documents are left out so the rest is saved, and the result says `partial: true` with `droppedForSize`.
|
|
512
|
+
- **Guards:** both tools are read tools (they never change Drive), so they stay available in `PROTON_DRIVE_MODE=readonly`; note that they write the local encrypted file. With `PROTON_DRIVE_REMOTE_ROOTS` the `path` must be inside a root and results outside the roots are dropped. The audit log records the folder and the numeric arguments of an update, but for a search only the length of the query, never the words or the snippets.
|
|
513
|
+
- **Clear it:** `drive_content_index` with `action: "clear"`, or `proton-drive-cli index clear` (which also removes the walk index and change snapshots), or delete `content-index.enc`. `clear` also deletes the key from the macOS Keychain or Secret Service (`keyRemoved` in the result; a missing item is fine), so the next update generates a new key and **old copies of the index file, for example in a backup, become unreadable**. A key you supplied in `PROTON_DRIVE_CONTENT_INDEX_KEY` cannot be rotated from here: remove or change it yourself. `proton-drive-cli index clear` does the same for the file and key it can find from the file header. If an index file exists but its key is gone, `update` refuses (it never makes a new key behind an existing file) and `search` fails: clear it and index again.
|
|
514
|
+
- **No rollback detection:** the file is authenticated (a changed, reordered, truncated or foreign file is refused) but not versioned, so someone with write access to the index directory can swap in an older valid copy of it and it will be accepted. This protects integrity of each version, not freshness; the encryption protects confidentiality against reading, not against replacing.
|
|
515
|
+
- **Read-only mode:** `drive_content_index` (`update`, `clear`) and `drive_search_content` stay available with `PROTON_DRIVE_MODE=readonly`, because they change only the local index file and never Drive.
|
|
516
|
+
- **Untrusted content:** snippets come from your files and may contain instructions aimed at the model; the tool says so in every result and nothing in them is executed.
|
|
517
|
+
|
|
472
518
|
## Known limitations
|
|
473
519
|
|
|
474
520
|
These come from the upstream `proton-drive` CLI (v0.8.0), not from this server:
|
|
@@ -522,9 +568,17 @@ Every tool group was live-tested on 2026-09-28 against a real Proton account, **
|
|
|
522
568
|
| `PROTON_DRIVE_INDEX` | Optional | Set to `1` (or `true`) to keep completed folder walks in a **plaintext** on-disk index so searches are fast after a restart. Off by default. See [Persistent index](#persistent-index-opt-in). |
|
|
523
569
|
| `PROTON_DRIVE_INDEX_DIR` | Optional | Directory for the index file (default: `~/Library/Caches/proton-drive-mcp` on macOS, `$XDG_CACHE_HOME` or `~/.cache/proton-drive-mcp` elsewhere). Use a dedicated directory: if it exists it must be yours with mode `0700` (group/other access is refused); a missing one is created `0700`. The file is `0600`. |
|
|
524
570
|
| `PROTON_DRIVE_INDEX_MAX_AGE_H` | Optional | Oldest saved index data that may be served, in hours (default 24; 0 = never serve saved data). Served data is marked `stale: true` and refreshed in the background (`drive_sync_plan`, `drive_find_duplicates` and the sharing audit never use it). |
|
|
571
|
+
| `PROTON_DRIVE_CONTENT_INDEX` | Optional | Set to `1` (or `true`) to enable the **encrypted** local content index behind `drive_content_index` and `drive_search_content`. Off by default; the two tools then answer with how to turn it on. Stored in the same private directory as the walk index (`PROTON_DRIVE_INDEX_DIR`). See [Content search](#content-search-opt-in). |
|
|
572
|
+
| `PROTON_DRIVE_CONTENT_INDEX_MAX_MB` | Optional | Hard size cap of the content index file in MB (default 200). An update that would exceed it stops indexing or leaves out the newest documents and says so; each search loads the whole file into memory. |
|
|
573
|
+
| `PROTON_DRIVE_CONTENT_INDEX_KEY` | Optional | 64 hex characters (`openssl rand -hex 32`): use this key instead of the OS keychain. For systems without a keychain (Windows, headless Linux without `secret-tool`). It then sits in the server's environment (for example in your MCP client config), which is weaker than the keychain. If set it is always used and the keychain is not touched. |
|
|
574
|
+
| `PROTON_DRIVE_KEYCHAIN_SERVICE` | Optional | Keychain service name for the content index key (default `proton-drive-mcp-content-index`; letters, digits, `.`, `_`, `-` only). Mainly for tests. |
|
|
525
575
|
| `PROTON_DRIVE_READ_MAX_BYTES` | Optional | Largest file `drive_read_content` will download, in bytes (default 10485760 = 10 MB; values above 52428800 = 50 MB are clamped). Larger files are refused before any download. |
|
|
526
576
|
| `PROTON_DRIVE_READ_TIMEOUT_MS` | Optional | Hard time limit for parsing one `.pdf`/`.docx` in `drive_read_content`, in milliseconds (default 20000; clamped to 1-120000). On expiry the parsing worker is terminated and the call returns an error. |
|
|
527
|
-
| `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all
|
|
577
|
+
| `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all 53 tools) or `core` (19 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. |
|
|
578
|
+
| `PROTON_DRIVE_MODE` | Optional | `full` (default) or `readonly`: hide and refuse every tool that changes Drive or the account. An unknown value is treated as `readonly`, with a warning. See [Guard layer](#guard-layer-opt-in). |
|
|
579
|
+
| `PROTON_DRIVE_REMOTE_ROOTS` | Optional | Drive folders (separated by `:`, or `;` on Windows) that every remote path argument must stay inside, e.g. `/my-files/Projects/X`. Tools that cannot be limited to a folder are refused while it is set. See [Guard layer](#guard-layer-opt-in). |
|
|
580
|
+
| `PROTON_DRIVE_AUDIT_LOG` | Optional | Absolute path of an append-only, hash-chained JSONL audit log (`0600`). If it cannot be written, tools that change Drive are refused. Read it with `drive_audit_log`. See [Guard layer](#guard-layer-opt-in). |
|
|
581
|
+
| `PROTON_DRIVE_SNAPSHOT_BEFORE_OVERWRITE` | Optional | `1` to copy the existing file to `.versions/<name>.<timestamp>` in its folder before `drive_write_file` (local sync copy) or `drive_upload` (`replace`, remote copy) overwrites it; the overwrite is refused if the copy fails. Replacing a folder is refused. Off by default. See [Guard layer](#guard-layer-opt-in). |
|
|
528
582
|
|
|
529
583
|
---
|
|
530
584
|
|
package/dist/cli.js
CHANGED
|
@@ -14,6 +14,8 @@ import { buildEntry, defaultConfigPath, isDirectory, resolveDriveCli, writeEntry
|
|
|
14
14
|
import { syncPlan, planBulkMove, planBulkTrash, loadListing, foldersToList } from "./services/plan.js";
|
|
15
15
|
import { invalidatePath } from "./services/walk.js";
|
|
16
16
|
import { indexStatus, deleteIndex } from "./services/walkIndex.js";
|
|
17
|
+
import { deleteChangeSnapshots } from "./services/changes.js";
|
|
18
|
+
import { clearContentIndex } from "./services/contentIndex.js";
|
|
17
19
|
import { resolve } from "node:path";
|
|
18
20
|
import { driveSearch, driveTree } from "./services/find.js";
|
|
19
21
|
import { readDriveContent } from "./services/content.js";
|
|
@@ -85,7 +87,7 @@ Commands:
|
|
|
85
87
|
photo upload <local>... [--conflict X] Upload photos to your library (skip/rename)
|
|
86
88
|
|
|
87
89
|
index status Persistent walk index (PROTON_DRIVE_INDEX=1): enabled?, path, size, age, entries
|
|
88
|
-
index clear Delete the saved index file (
|
|
90
|
+
index clear Delete the saved index file (plaintext names/paths of your drive), the change snapshots and the encrypted content index
|
|
89
91
|
|
|
90
92
|
doctor [--config <path>] Read-only diagnostics: Node, proton-drive CLI, auth, sync path, Claude Desktop config
|
|
91
93
|
(exit 1 if any check fails)
|
|
@@ -211,8 +213,10 @@ async function run() {
|
|
|
211
213
|
if (cmd === "index") {
|
|
212
214
|
if (sub === "status")
|
|
213
215
|
print(indexStatus());
|
|
214
|
-
else if (sub === "clear")
|
|
215
|
-
|
|
216
|
+
else if (sub === "clear") {
|
|
217
|
+
const c = await clearContentIndex();
|
|
218
|
+
print({ ...deleteIndex(), changeSnapshotsDeleted: deleteChangeSnapshots(), contentIndexDeleted: c.deleted, contentKeyRemoved: c.keyRemoved, contentIndexNote: c.note });
|
|
219
|
+
}
|
|
216
220
|
else {
|
|
217
221
|
console.error("Usage: index status|clear");
|
|
218
222
|
process.exit(1);
|