proton-drive-mcp 1.8.0 → 1.10.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 +22 -1
- package/README.md +69 -11
- package/dist/cli.js +10 -0
- package/dist/index.js +24 -4
- package/dist/services/drive.js +14 -1
- package/dist/utils/claudeConfig.js +66 -1
- package/dist/utils/cliVersion.js +6 -5
- package/dist/utils/doctor.js +4 -7
- package/dist/utils/init.js +145 -0
- package/glama.json +4 -0
- package/package.json +3 -2
- package/smithery.yaml +1 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,26 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.10.0 — 2026-11-18
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
- **`drive_size` tool** (read-only, allowed in readonly mode, in the full tier only): size of one file or folder from the official CLI command `proton-drive filesystem size <path>`, which exists from CLI 0.9.0. The path honours `PROTON_DRIVE_REMOTE_ROOTS`. On CLI 0.8.x the command is unknown and the tool fails with "drive_size needs Proton Drive CLI 0.9.0 or newer". Now 55 tools; `drive_size` is MCP-only in the companion CLI. Not live-tested against a real account (output shape follows the CLI as-is, passed through the same noise trimming as `drive_info`).
|
|
7
|
+
|
|
8
|
+
### Changed
|
|
9
|
+
- Documentation: new safe-use guide for non-developers (`docs/GUIDE.md`): read-only setup, what the model provider sees, copy-paste prompts, and a checklist before allowing writes.
|
|
10
|
+
- Dependencies: `hono` 4.13.18, `@hono/node-server` 2.1.8; CI uses `codeql-action` 4.39.3.
|
|
11
|
+
|
|
12
|
+
## 1.9.0 — 2026-11-06
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
- **`init` subcommand** (`npx -y proton-drive-mcp init`, also `proton-drive-cli init`): finds the `proton-drive` CLI (`PROTON_DRIVE_BIN`, `PATH`, then `~/.local/bin` and the Homebrew dirs), runs the `doctor` checks, and on a failure prints the exact next step (for example `proton-drive auth login`). When the CLI is found it prints the Claude Desktop entry in the `npx -y proton-drive-mcp` form with `PROTON_DRIVE_BIN` set to the absolute path, and the `claude mcp add --env PROTON_DRIVE_BIN=... proton-drive -- npx -y proton-drive-mcp` line. `--write` adds the Desktop entry through the same writer as `setup-claude-desktop` (dry run by default, timestamped backup first, only `mcpServers["proton-drive-mcp"]` is touched, re-running with the same result changes nothing) and works from a temporary `npx` cache. Replacing an existing entry overrides only `command`, `args` and `PROTON_DRIVE_BIN`: every other env key (`PROTON_DRIVE_MODE`, `PROTON_DRIVE_REMOTE_ROOTS`, `PROTON_DRIVE_AUDIT_LOG`, `PROTON_DRIVE_SYNC_PATH`, ...) is kept, and the output names the kept keys (never their values) and says when a pinned install (the `setup-claude-desktop` form) changes to the npx form, which runs the latest published version. An absolute path to an existing `npx` in the entry is kept. The output says when a version pin (`proton-drive-mcp@1.8.0`) is dropped in favor of the latest and notes `"disabled": true` or a `cwd` in the entry (kept; values not shown). If the server is already registered under another key (including the README global-install form `{"command": "proton-drive-mcp"}`), `--write` refuses (a second copy would double the tools), the dry run warns, and both exit 1 with a matching summary. A stale entry does not block `init` (shown as a warning). Env values of the existing entry never appear in the output, including `--json`. The printed `claude mcp add` line single-quotes the CLI path. `init` states that the npx entry uses the Node on Claude Desktop's PATH, which `doctor` cannot check, and refuses on Windows. `--json` is supported. It is a subcommand, not an MCP tool (still 54 tools), reads no session data, and does not change what happens when the server is started without arguments.
|
|
16
|
+
- Official MCP Registry metadata: `mcpName` in `package.json` and a root `server.json` (`io.github.googlarz/proton-drive-mcp`, npm package, stdio). Its versions are bumped by hand with `package.json`; a test and the publish workflow check them against each other and the tag.
|
|
17
|
+
- Release workflow: a CycloneDX SBOM of the production dependencies (`npm sbom --sbom-format cyclonedx --omit dev`) is attached to each GitHub release next to the `.mcpb` bundle.
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
- `doctor` recognises the server under another key exactly (command `proton-drive-mcp`, an argument `proton-drive-mcp` or `proton-drive-mcp@<version>`, or a `/proton-drive-mcp/dist/` path) instead of by substring, so a directory like `proton-drive-mcp-notes` no longer matches and the README global-install form now does.
|
|
21
|
+
- `@modelcontextprotocol/sdk` is pinned to an exact version (1.32.2, no caret); updates go through a deliberate bump.
|
|
22
|
+
- Proton Drive CLI **0.9.0** (SDK js 0.22.2) no longer triggers the version warning in `doctor` and at startup (0.8.x and 0.9.x are both accepted). Live-tested on 0.9.0 against a real account: `doctor`, list, info, tree, search, read (text layer and OCR), download, upload, mkdir, rename, move, trash, sharing status and audit, album list and photo timeline. Not tested on 0.9.0: sharing changes (invite, links, revoke), album and photo writes, restore and permanent delete. The new CLI command `filesystem size` is not used yet.
|
|
23
|
+
|
|
3
24
|
## 1.8.0 — 2026-11-01
|
|
4
25
|
|
|
5
26
|
### Added
|
|
@@ -26,7 +47,7 @@
|
|
|
26
47
|
- **Run one version at a time:** the index file format is version 2. A 1.7.0 server running next to 1.8.0 does not understand it: it reads the file as no index, its own invalidation after a write does nothing to it, and it may overwrite the saved progress. 1.8.0 still reads 1.7.0's version 1 files.
|
|
27
48
|
- The first read after the helper is built took about 25 s in testing (macOS prepares Vision for each new binary); later reads are fast. That preparation now happens in the background after server start and does not count against the per-file limit.
|
|
28
49
|
- OCR text is imperfect and handwriting is not supported; check numbers against the original. Images and scanned PDFs have their own download cap, `PROTON_DRIVE_OCR_MAX_MB` (30 MB); the 10 MB `PROTON_DRIVE_READ_MAX_BYTES` cap still applies to text, `.docx` and text-layer PDFs.
|
|
29
|
-
- Known limits: one OCR at a time, so large scan folders index slowly over several calls; an OCR timeout is recorded as a skip for that file version until `PROTON_DRIVE_OCR_TIMEOUT_MS` changes; pdftoppm renders at most 4000 pixels per side (larger pages are scaled down); `.gif` is not read.
|
|
50
|
+
- Known limits: one OCR at a time, so large scan folders index slowly over several calls; an OCR timeout is recorded as a skip for that file version until `PROTON_DRIVE_OCR_TIMEOUT_MS` changes; pdftoppm renders at most 4000 pixels per side (larger pages are scaled down); `.gif` is not read; tesseract does not auto-rotate, so an upside-down scan or a PDF page rotated 180° reads as garbage there (Vision copes; verified on synthetic samples, 2026-11-02, tesseract 5.5.4).
|
|
30
51
|
|
|
31
52
|
## 1.7.0 — 2026-11-01
|
|
32
53
|
|
package/README.md
CHANGED
|
@@ -24,21 +24,74 @@
|
|
|
24
24
|
|
|
25
25
|
---
|
|
26
26
|
|
|
27
|
+
> **Unofficial community project, not affiliated with or endorsed by Proton AG.** Proton and Proton Drive are trademarks of Proton AG. This server only drives the official Proton Drive CLI and never handles your password or session. See the [threat model](THREAT_MODEL.md) for what it protects and what reaches your AI provider.
|
|
28
|
+
|
|
27
29
|
Give Claude Desktop (or any MCP client) full access to your Proton Drive and Proton Photos: list folders, upload and download files, invite collaborators, manage sharing, handle trash, and manage photo albums — all with end-to-end encryption intact. The same capabilities are available as a full CLI for scripting, backups, and cron.
|
|
28
30
|
|
|
31
|
+
**Related projects:** the same author's [Proton Mail Bridge MCP server](https://github.com/googlarz/proton-mail-bridge-client) handles Proton Mail. It is a separate server on purpose: mail and Drive need different permissions, so you can grant a model one without the other.
|
|
32
|
+
|
|
29
33
|
## Quick start (60 seconds)
|
|
30
34
|
|
|
31
35
|
1. Install the official [Proton Drive CLI](https://proton.me/download/drive/cli/index.html), then sign in once: `proton-drive auth login`.
|
|
32
|
-
2.
|
|
36
|
+
2. Not sure about the details? Run `npx -y proton-drive-mcp init`. It finds the `proton-drive` CLI, runs the same checks as `doctor`, tells you the exact next step if something is wrong (for example `proton-drive auth login`), and prints the ready-to-paste Claude Desktop config and `claude mcp add` line. Add `--write` to put the Claude Desktop entry in place (dry run by default, timestamped backup first, other servers untouched). Or connect manually, either way:
|
|
33
37
|
- **Bundle:** install `proton-drive-mcp-<version>.mcpb` from the [latest release](https://github.com/googlarz/proton-drive-mcp/releases/latest) and set **proton-drive CLI path** to the output of `which proton-drive`.
|
|
34
38
|
- **Global install:** `npm install -g proton-drive-mcp`, then `proton-drive-cli doctor`, then `proton-drive-cli setup-claude-desktop --write`. (`setup-claude-desktop` refuses to run from a temporary `npx` cache, so install globally first.) Fully quit and restart Claude Desktop afterwards.
|
|
39
|
+
- **Claude Code:** `claude mcp add --env PROTON_DRIVE_BIN="$(which proton-drive)" proton-drive -- npx -y proton-drive-mcp`
|
|
35
40
|
3. Try these prompts:
|
|
36
41
|
- "Find files named *invoice* in my Drive." (`drive_search`)
|
|
37
42
|
- "What is using my Drive space?" (`drive_usage`)
|
|
38
43
|
- "Find duplicate files in my Drive." (`drive_find_duplicates`)
|
|
39
44
|
- "Who has access to my shared folders?" (`drive_sharing_audit`)
|
|
40
45
|
- "Tidy up /Downloads, show me a plan first." (`drive_bulk_move` / `drive_bulk_trash` preview first, nothing changes until you confirm)
|
|
41
|
-
4.
|
|
46
|
+
4. Sensitive files? Start read-only and confined: `PROTON_DRIVE_MODE=readonly` and `PROTON_DRIVE_REMOTE_ROOTS=/my-files/<folder>`, plus an audit log ([guard layer](#guard-layer-opt-in), [secure setup](SECURITY.md#secure-deployment-profile)).
|
|
47
|
+
5. Optional: `PROTON_DRIVE_INDEX=1` keeps a plaintext local copy of file names so searches are instant after a restart ([details](#persistent-index-opt-in)); `PROTON_DRIVE_TOOL_TIER=core` exposes a smaller tool set.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Compatibility
|
|
52
|
+
|
|
53
|
+
| | Status |
|
|
54
|
+
|---|---|
|
|
55
|
+
| Proton Drive CLI | Built against **0.8.0** (all 32 scriptable commands covered). **0.9.0** (SDK js 0.22.2) was live-tested for file operations (list, info, tree, search, read, download, upload, mkdir, rename, move, trash), sharing reads and the audit, and photo and album reads; sharing changes, album and photo writes, and other versions are untested. Run `proton-drive-cli doctor` after upgrading the CLI. |
|
|
56
|
+
| Node.js | 22 or newer |
|
|
57
|
+
| macOS | Live-tested. Built-in Vision OCR. |
|
|
58
|
+
| Linux | The test suite runs on Ubuntu in CI; not live-tested against a real account. |
|
|
59
|
+
| Windows | Not supported |
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Recipes
|
|
64
|
+
|
|
65
|
+
### Find my scanned documents
|
|
66
|
+
|
|
67
|
+
Searching by name (`drive_search`) will not find a scan called `IMG_0042.jpg`. Search by content instead:
|
|
68
|
+
|
|
69
|
+
1. Set `PROTON_DRIVE_OCR=1` and `PROTON_DRIVE_CONTENT_INDEX=1` in the server's environment and restart it. Both are off by default.
|
|
70
|
+
2. Ask: "Index my /my-files/Scans folder." Claude calls `drive_content_index` with that `path`. If the result says `partial: true`, it calls again to continue.
|
|
71
|
+
3. Ask: "Find the scan that mentions my 2023 tax return." Claude calls `drive_search_content`.
|
|
72
|
+
|
|
73
|
+
Honest limits: on macOS the OCR helper is compiled the first time it is needed, a one-time wait of about 30 s (the server warms it in the background shortly after start). OCR makes mistakes, especially on handwriting, low-resolution photos and unusual layouts, so a document can be missed or matched on a wrong word; open the file to check. OCR runs one file at a time, so a big folder of scans takes a while. The index covers only the folders you indexed and reflects the last update. Details: [OCR for scans](#ocr-for-scans-opt-in), [Content search](#content-search-opt-in).
|
|
74
|
+
|
|
75
|
+
### Audit who can see my files
|
|
76
|
+
|
|
77
|
+
Ask: "Who has access to my shared folders?" and then "Which public links expire soon or never expire?"
|
|
78
|
+
|
|
79
|
+
- `drive_sharing_audit` lists public links (role, expiry, password), invitees and pending invitations, with risk flags such as `public-link-no-expiry`, `public-link-editor` and `external-invitee`.
|
|
80
|
+
- `drive_share_expiry_report` lists public links with the time left, soonest first (`withinDays` sets what counts as soon).
|
|
81
|
+
|
|
82
|
+
Both only read; they change nothing, and link URLs are left out of the results. Each checks at most 100 shared items, so on a big drive point it at one folder at a time. To act on a finding, `drive_share_remove_url` or `drive_share_revoke` change sharing; they ask for confirmation.
|
|
83
|
+
|
|
84
|
+
### Tidy a folder safely
|
|
85
|
+
|
|
86
|
+
Ask: "Move all the PDFs in /Downloads into /Documents/Inbox. Show me the plan first."
|
|
87
|
+
|
|
88
|
+
1. `drive_bulk_move` (or `drive_bulk_trash` for clean-up) without `confirmed` returns a plan and any problems and changes nothing.
|
|
89
|
+
2. Read the plan. If it is right, say so, and Claude repeats the call with `confirmed=true`. It applies only if there are no problems.
|
|
90
|
+
3. Trash is reversible: `drive_restore` brings an item back (`drive_list_trash` shows what is there). `drive_empty_trash` and `drive_delete` are permanent, so do not ask for those during a tidy-up.
|
|
91
|
+
|
|
92
|
+
Each call handles up to 200 items. For a first attempt on important data, use the [guard layer](#guard-layer-opt-in) (`PROTON_DRIVE_REMOTE_ROOTS` limits the folders Claude can touch).
|
|
93
|
+
|
|
94
|
+
New to this and want to stay cautious? See the [safe-use guide](docs/GUIDE.md).
|
|
42
95
|
|
|
43
96
|
---
|
|
44
97
|
|
|
@@ -58,10 +111,10 @@ What to expect: search matches names, sizes and dates, not the text of every fil
|
|
|
58
111
|
|
|
59
112
|
- **Claude manages your Proton Drive** — list, upload, download, move, share, trash, restore
|
|
60
113
|
- **Proton Photos album management** — list albums, create/delete albums, add and remove photos
|
|
61
|
-
- **Companion CLI** — 45 of the
|
|
114
|
+
- **Companion CLI** — 45 of the 55 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`, `drive_size` and the newer `drive_read_many`, `drive_share_expiry_report`, `drive_recent_changes`, `drive_content_index`, `drive_search_content` and `drive_refresh_index` are MCP-only)
|
|
62
115
|
- **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
116
|
- **Zero credential exposure** — auth is handled entirely by the official Proton Drive CLI; this MCP never touches your password or session token
|
|
64
|
-
- **Shell injection safe** — all CLI calls
|
|
117
|
+
- **Shell injection safe** — all CLI calls pass discrete argument arrays to `spawn` (no shell), never string interpolation
|
|
65
118
|
- **Privacy-native** — end-to-end encryption is handled by Proton's own CLI; this server is just a thin MCP wrapper
|
|
66
119
|
|
|
67
120
|
---
|
|
@@ -154,9 +207,12 @@ Instead of editing JSON, download `proton-drive-mcp-<version>.mcpb` from the [la
|
|
|
154
207
|
|
|
155
208
|
## Setup and diagnostics
|
|
156
209
|
|
|
157
|
-
|
|
210
|
+
Three commands of the companion CLI help when Claude Desktop reports "proton-drive CLI not found" (it starts servers with a minimal `PATH`). `init` combines the first two for a first run (it also works as `npx -y proton-drive-mcp init`, writing the `npx` form of the entry so no package path is pinned):
|
|
158
211
|
|
|
159
212
|
```bash
|
|
213
|
+
# First run: doctor checks + ready-to-paste Claude Desktop and Claude Code config; --write adds the Desktop entry
|
|
214
|
+
proton-drive-cli init [--json] [--config <path>] [--write]
|
|
215
|
+
|
|
160
216
|
# Read-only checks: Node >= 22, proton-drive CLI + version, auth, PROTON_DRIVE_SYNC_PATH, your Claude Desktop entry
|
|
161
217
|
proton-drive-cli doctor [--json] [--config <path>]
|
|
162
218
|
|
|
@@ -356,7 +412,7 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
|
|
|
356
412
|
`drive_auth_status` · `drive_auth_logout` · `drive_version`
|
|
357
413
|
|
|
358
414
|
### Filesystem
|
|
359
|
-
`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`
|
|
415
|
+
`drive_list` · `drive_info` · `drive_size` · `drive_read_content` · `drive_read_many` · `drive_tree` · `drive_search` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
|
|
360
416
|
|
|
361
417
|
### Sharing
|
|
362
418
|
`drive_share_status` · `drive_share_invite` · `drive_share_revoke` · `drive_share_remove_all` · `drive_share_set_url` · `drive_share_remove_url`
|
|
@@ -402,6 +458,7 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
|
|
|
402
458
|
| `drive_version` | CLI and SDK version info | — |
|
|
403
459
|
| `drive_list` | List files and folders at a path (paginated, default 200; `/` lists the roots) | `path`, `limit?`, `offset?` |
|
|
404
460
|
| `drive_info` | Get metadata for one file/folder, including revision details (noise trimmed) | `path`, `verbose?` (raw CLI node) |
|
|
461
|
+
| `drive_size` | Size of one file or folder as reported by the CLI (`filesystem size`; needs Proton Drive CLI 0.9.0 or newer, read-only) | `path` |
|
|
405
462
|
| `drive_read_content` | Read the text of a file stored in Drive (no sync folder needed): text/code, `.docx`, text-layer `.pdf`; scans and images with opt-in local [OCR](#ocr-for-scans-opt-in). Paged; content is untrusted data. See [Reading file contents](#reading-file-contents) | `path`, `maxChars?` (default 20000, max 100000), `offset?` |
|
|
406
463
|
| `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) |
|
|
407
464
|
| `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?` |
|
|
@@ -465,7 +522,7 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
|
|
|
465
522
|
| Sharing & invitations | Rarely | Full (invite, revoke, status) |
|
|
466
523
|
| Trash & restore | Rarely | Full |
|
|
467
524
|
| CLI parity | No | The CLI mirrors every MCP tool except `drive_read_file` / `drive_write_file` |
|
|
468
|
-
| Shell injection safe | Varies | Yes — `
|
|
525
|
+
| Shell injection safe | Varies | Yes — `spawn` with argument arrays, no shell |
|
|
469
526
|
|
|
470
527
|
---
|
|
471
528
|
|
|
@@ -485,7 +542,7 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
|
|
|
485
542
|
|
|
486
543
|
### Token cost
|
|
487
544
|
|
|
488
|
-
`tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 48.
|
|
545
|
+
`tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 48.5 KB (55 tools), `core` 17.9 KB (19 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
|
|
489
546
|
|
|
490
547
|
`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`.
|
|
491
548
|
|
|
@@ -526,6 +583,7 @@ Scanned PDFs (no text layer) and images normally come back empty or as "unsuppor
|
|
|
526
583
|
- **Limits:** `PROTON_DRIVE_OCR_MAX_PAGES` (default 30, max 200; later pages are not read and the note says so), `PROTON_DRIVE_OCR_MAX_MB` (largest image or scanned PDF to download and OCR, default 30 MB, max 50; independent of the 10 MB `PROTON_DRIVE_READ_MAX_BYTES` cap, which keeps applying to text, `.docx` and text-layer PDFs), `PROTON_DRIVE_OCR_MAX_PIXELS` (images above this many pixels, width x height, default 100 million, are refused before any engine sees them: the size is read from the file header, an image whose size cannot be read is refused too, and the Vision helper applies the same limit to the decoded image; HEIC is checked by Vision only), `PROTON_DRIVE_OCR_TIMEOUT_MS` (per file, all steps together, counted from when the engine is ready; default 90000, max 600000), and the usual 2,000,000-character text cap. A scanned PDF over the OCR size limit is returned as before with a note; an image over it is refused. If OCR fails on a PDF that has a thin text layer, the read still succeeds with the text layer and a note `OCR unavailable/failed: ...`; the longer of text layer and OCR text is kept.
|
|
527
584
|
- **Accuracy:** OCR makes mistakes: wrong digits, dropped diacritics, scrambled tables and columns. Results carry `ocr: true`, `engine` and `pagesOcrd` and a note saying so; `drive_read_many` items and `drive_search_content` results carry `ocr: true`. **Check amounts, dates and IBANs against the original before relying on them.** Handwriting is not supported and usually comes out as noise. Photos at an angle, very small text and low-contrast scans read poorly.
|
|
528
585
|
- **Content index:** scans and images in an indexed folder are OCR'd one at a time (the OCR slot is shared by everything in the process), so a folder of scans takes many calls; the time budget and `partial`/`remaining` work as before. A file whose OCR could not start before the budget ran out is not recorded half-way and is simply tried again by the next call. Files recorded as unreadable while OCR was off (images, textless PDFs) are tried once more after you enable it; files OCR found no text in are not retried until they change. An OCR timeout is recorded as a skip for that version of the file and tried again when `PROTON_DRIVE_OCR_TIMEOUT_MS` changes. A missing engine or an invalid `PROTON_DRIVE_OCR_LANGS` fails the update at once with one clear error, before any image is downloaded. The indexed documents carry `ocr: true` (a search result shows it, because the snippet may be imperfect). Credential-looking names are skipped for images too.
|
|
586
|
+
- **Known limit (tesseract only):** it does not rotate pages. A scan that is upside down (or a PDF page rotated 180°) comes back as garbage text on the tesseract path, while macOS Vision handles it. Checked on small synthetic samples only; orientation detection on full-size real scans is untested. Rotate such scans before uploading.
|
|
529
587
|
- **Doctor:** `proton-drive-cli doctor` reports whether OCR is off or on, which engine was found, the tesseract version and installed languages, and what is missing (for example `pdftoppm`).
|
|
530
588
|
- **Guards:** `drive_read_content`, `drive_read_many` and the index tools stay read tools: available in `PROTON_DRIVE_MODE=readonly`, confined by `PROTON_DRIVE_REMOTE_ROOTS`.
|
|
531
589
|
|
|
@@ -571,12 +629,12 @@ These come from the upstream `proton-drive` CLI (v0.8.0), not from this server:
|
|
|
571
629
|
|
|
572
630
|
| Component | Tested with |
|
|
573
631
|
|---|---|
|
|
574
|
-
| Proton Drive CLI | 0.8.x (SDK js 0.21) |
|
|
632
|
+
| Proton Drive CLI | 0.8.x (SDK js 0.21) and 0.9.x (SDK js 0.22; photo and album writes and sharing changes only on 0.8.x) |
|
|
575
633
|
| macOS | Live-tested against a real account |
|
|
576
634
|
| Linux | CI with a fake CLI only |
|
|
577
635
|
| Windows | Not supported (see [Platform support](#platform-support)) |
|
|
578
636
|
|
|
579
|
-
`proton-drive-cli doctor` warns when the installed CLI is
|
|
637
|
+
`proton-drive-cli doctor` warns when the installed CLI is neither 0.8.x nor 0.9.x, and the server logs one warning line to stderr at startup. Other versions may work but are unverified. If something breaks, open an issue at [github.com/googlarz/proton-drive-mcp/issues](https://github.com/googlarz/proton-drive-mcp/issues) with the output of `proton-drive version` and `proton-drive-cli doctor`.
|
|
580
638
|
|
|
581
639
|
## Platform support
|
|
582
640
|
|
|
@@ -620,7 +678,7 @@ Every tool group was live-tested on 2026-09-28 against a real Proton account, **
|
|
|
620
678
|
| `PROTON_DRIVE_OCR_TIMEOUT_MS` | Optional | Time limit for OCR of one file, in milliseconds (default 90000, max 600000); the engine process group is killed on expiry. |
|
|
621
679
|
| `PROTON_DRIVE_DEBUG` | Optional | Set to `1` to log debug lines (for example a failed background OCR warm-up) to stderr. |
|
|
622
680
|
| `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. |
|
|
623
|
-
| `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all
|
|
681
|
+
| `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all 55 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. |
|
|
624
682
|
| `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). |
|
|
625
683
|
| `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). |
|
|
626
684
|
| `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). |
|
package/dist/cli.js
CHANGED
|
@@ -10,6 +10,7 @@ import { DriveService, } from "./services/drive.js";
|
|
|
10
10
|
import { DriveCliError, DriveCliNotFoundError, DriveNotAuthenticatedError, DriveParseError } from "./utils/errors.js";
|
|
11
11
|
import { checkCliAvailable } from "./utils/subprocess.js";
|
|
12
12
|
import { runDoctor, formatDoctor } from "./utils/doctor.js";
|
|
13
|
+
import { runInit } from "./utils/init.js";
|
|
13
14
|
import { buildEntry, defaultConfigPath, isDirectory, resolveDriveCli, writeEntry, SERVER_KEY } from "./utils/claudeConfig.js";
|
|
14
15
|
import { syncPlan, planBulkMove, planBulkTrash, loadListing, foldersToList } from "./services/plan.js";
|
|
15
16
|
import { invalidatePath } from "./services/walk.js";
|
|
@@ -91,6 +92,9 @@ Commands:
|
|
|
91
92
|
|
|
92
93
|
doctor [--config <path>] Read-only diagnostics: Node, proton-drive CLI, auth, sync path, Claude Desktop config
|
|
93
94
|
(exit 1 if any check fails)
|
|
95
|
+
init [--config <path>] [--write] First-run helper (also: npx -y proton-drive-mcp init): runs the doctor checks, prints the Claude
|
|
96
|
+
Desktop and Claude Code config; --write adds the npx entry to the Desktop config (timestamped
|
|
97
|
+
backup first, dry run by default, other servers untouched)
|
|
94
98
|
setup-claude-desktop [--config <path>] [--sync-path <dir>] [--write]
|
|
95
99
|
Print the Claude Desktop entry for this server (dry run); --write adds it to the
|
|
96
100
|
config (timestamped backup first). Restart Claude Desktop afterwards.
|
|
@@ -209,6 +213,12 @@ async function run() {
|
|
|
209
213
|
setupClaudeDesktop();
|
|
210
214
|
return;
|
|
211
215
|
}
|
|
216
|
+
if (cmd === "init") {
|
|
217
|
+
const result = await runInit({ configPath: resolve(getFlag("--config") ?? defaultConfigPath()), write: args.includes("--write") });
|
|
218
|
+
console.log(jsonMode ? JSON.stringify({ ...result.json, ok: result.ok }) : result.text);
|
|
219
|
+
process.exitCode = result.ok ? 0 : 1;
|
|
220
|
+
return;
|
|
221
|
+
}
|
|
212
222
|
// Local file only: no account, no CLI binary needed.
|
|
213
223
|
if (cmd === "index") {
|
|
214
224
|
if (sub === "status")
|
package/dist/index.js
CHANGED
|
@@ -200,6 +200,22 @@ const TOOLS = [
|
|
|
200
200
|
additionalProperties: false,
|
|
201
201
|
},
|
|
202
202
|
},
|
|
203
|
+
{
|
|
204
|
+
name: "drive_size",
|
|
205
|
+
description: "Get the size of one Proton Drive file or folder as reported by the CLI (`filesystem size`; folders are totalled by the CLI). Read-only. Needs Proton Drive CLI 0.9.0 or newer. For per-folder breakdowns use drive_tree.",
|
|
206
|
+
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
207
|
+
inputSchema: {
|
|
208
|
+
type: "object",
|
|
209
|
+
properties: {
|
|
210
|
+
path: {
|
|
211
|
+
type: "string",
|
|
212
|
+
description: "Absolute remote path, e.g. /my-files/Projects.",
|
|
213
|
+
},
|
|
214
|
+
},
|
|
215
|
+
required: ["path"],
|
|
216
|
+
additionalProperties: false,
|
|
217
|
+
},
|
|
218
|
+
},
|
|
203
219
|
{
|
|
204
220
|
name: "drive_tree",
|
|
205
221
|
description: "Folder overview with per-folder file counts and size totals, largest first. Returns {files, folders, size, complete, unexpanded?, skipped?, tree}. Totals cover opened folders only; 'unexpanded' counts folders not opened (depth limit, .git/node_modules, failures). complete=false: part of the tree failed to load. Cached 5 min; refresh=true re-reads.",
|
|
@@ -1143,7 +1159,7 @@ const TOOL_TITLES = {
|
|
|
1143
1159
|
drive_find_duplicates: "Find duplicate files", drive_sharing_audit: "Audit sharing",
|
|
1144
1160
|
drive_sync_plan: "Plan local/Drive sync", drive_bulk_move: "Move many items", drive_bulk_trash: "Trash many items",
|
|
1145
1161
|
drive_auth_status: "Check sign-in status", drive_auth_logout: "Sign out", drive_version: "CLI version",
|
|
1146
|
-
drive_list: "List folder", drive_info: "Get item info", drive_upload: "Upload to Drive", drive_download: "Download from Drive",
|
|
1162
|
+
drive_list: "List folder", drive_info: "Get item info", drive_size: "Get item size", drive_upload: "Upload to Drive", drive_download: "Download from Drive",
|
|
1147
1163
|
drive_mkdir: "Create folder", drive_rename: "Rename item", drive_move: "Move item", drive_delete: "Delete permanently",
|
|
1148
1164
|
drive_share_status: "Show sharing status", drive_list_trash: "List trash", drive_share_invite: "Invite to share",
|
|
1149
1165
|
drive_share_revoke: "Revoke member access", drive_trash: "Move to trash", drive_restore: "Restore from trash",
|
|
@@ -1221,7 +1237,7 @@ export const MUTATING_TOOL_NAMES = new Set([
|
|
|
1221
1237
|
]);
|
|
1222
1238
|
/** Reads and analytics. Downloads only write to the local disk; so does the content index (an encrypted local file). */
|
|
1223
1239
|
export const READ_TOOL_NAMES = new Set([
|
|
1224
|
-
"drive_auth_status", "drive_version", "drive_list", "drive_info", "drive_tree", "drive_search", "drive_download",
|
|
1240
|
+
"drive_auth_status", "drive_version", "drive_list", "drive_info", "drive_size", "drive_tree", "drive_search", "drive_download",
|
|
1225
1241
|
"drive_list_trash", "drive_share_status", "drive_list_invitations", "drive_read_content", "drive_read_file",
|
|
1226
1242
|
"drive_sync_plan", "drive_usage", "drive_find_duplicates", "drive_sharing_audit", "drive_audit_log",
|
|
1227
1243
|
"drive_read_many", "drive_share_expiry_report", "drive_recent_changes", "drive_content_index", "drive_search_content", "drive_refresh_index",
|
|
@@ -1239,7 +1255,7 @@ export function resolveMode(raw) {
|
|
|
1239
1255
|
const walkRoot = [{ arg: "path", dflt: "/my-files" }];
|
|
1240
1256
|
const sharePath = [{ arg: "path" }];
|
|
1241
1257
|
export const REMOTE_PATH_ARGS = {
|
|
1242
|
-
drive_list: [{ arg: "path" }], drive_info: [{ arg: "path" }], drive_read_content: [{ arg: "path" }],
|
|
1258
|
+
drive_list: [{ arg: "path" }], drive_info: [{ arg: "path" }], drive_size: [{ arg: "path" }], drive_read_content: [{ arg: "path" }],
|
|
1243
1259
|
drive_read_file: [{ arg: "path" }], drive_write_file: [{ arg: "path" }], drive_mkdir: [{ arg: "path" }],
|
|
1244
1260
|
drive_tree: walkRoot, drive_search: walkRoot, drive_usage: walkRoot, drive_find_duplicates: walkRoot, drive_sharing_audit: walkRoot,
|
|
1245
1261
|
drive_share_expiry_report: walkRoot, drive_recent_changes: walkRoot, drive_refresh_index: walkRoot, drive_read_many: [{ arg: "paths", list: true }],
|
|
@@ -1436,6 +1452,8 @@ export async function main() {
|
|
|
1436
1452
|
}
|
|
1437
1453
|
case "drive_info":
|
|
1438
1454
|
return ok(await drive.info(validateRemotePath(a.path), a.verbose === true));
|
|
1455
|
+
case "drive_size":
|
|
1456
|
+
return ok(await drive.size(validateRemotePath(a.path)));
|
|
1439
1457
|
case "drive_tree":
|
|
1440
1458
|
return ok(await driveTree(drive, a));
|
|
1441
1459
|
case "drive_search":
|
|
@@ -1990,7 +2008,9 @@ export async function main() {
|
|
|
1990
2008
|
});
|
|
1991
2009
|
}
|
|
1992
2010
|
if (isMainModule(import.meta.url)) {
|
|
1993
|
-
|
|
2011
|
+
// `npx -y proton-drive-mcp init` reaches this bin; the setup command lives in the companion CLI.
|
|
2012
|
+
// Only the literal first argument "init" is diverted: an MCP client starting the server passes none.
|
|
2013
|
+
(process.argv[2] === "init" ? import("./cli.js") : main()).catch((err) => {
|
|
1994
2014
|
logger.error("Fatal:", err);
|
|
1995
2015
|
process.exit(1);
|
|
1996
2016
|
});
|
package/dist/services/drive.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { runDrive as defaultRunDrive, runDriveRaw as defaultRunDriveRaw } from "../utils/subprocess.js";
|
|
2
|
-
import { DriveNotAuthenticatedError, DriveParseError } from "../utils/errors.js";
|
|
2
|
+
import { DriveCliError, DriveNotAuthenticatedError, DriveParseError } from "../utils/errors.js";
|
|
3
3
|
import { validateName } from "../utils/validation.js";
|
|
4
4
|
import { invalidatePath } from "./walk.js";
|
|
5
5
|
// A trashed item shows up in the trash listings, so cached trash walks go stale too.
|
|
@@ -333,6 +333,19 @@ export class DriveService {
|
|
|
333
333
|
return trimmed;
|
|
334
334
|
return { ...trimmed, ...revisionMeta(raw) };
|
|
335
335
|
}
|
|
336
|
+
// `filesystem size` exists from CLI 0.9.0. Older CLIs print usage or "unknown command"
|
|
337
|
+
// for it; that is mapped to a clear message instead of leaking the usage text.
|
|
338
|
+
async size(remotePath) {
|
|
339
|
+
try {
|
|
340
|
+
return trimNode(await this.run(["filesystem", "size", remotePath]));
|
|
341
|
+
}
|
|
342
|
+
catch (err) {
|
|
343
|
+
if (err instanceof DriveCliError && /unknown (sub)?command|command not found|^\s*usage:/im.test(err.message)) {
|
|
344
|
+
throw new Error("drive_size needs Proton Drive CLI 0.9.0 or newer");
|
|
345
|
+
}
|
|
346
|
+
throw err;
|
|
347
|
+
}
|
|
348
|
+
}
|
|
336
349
|
// Renames in place — does not move to a different folder. Returns the
|
|
337
350
|
// renamed node (raw pass-through).
|
|
338
351
|
async rename(remotePath, newName) {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
|
|
2
2
|
import { homedir } from "node:os";
|
|
3
|
-
import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
|
|
3
|
+
import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
|
|
4
4
|
import { fileURLToPath } from "node:url";
|
|
5
5
|
export const SERVER_KEY = "proton-drive-mcp";
|
|
6
6
|
/** Default Claude Desktop config location; CLAUDE_DESKTOP_CONFIG overrides it. */
|
|
@@ -67,6 +67,10 @@ export function buildEntry(cliPath, syncPath) {
|
|
|
67
67
|
env["PROTON_DRIVE_SYNC_PATH"] = syncPath;
|
|
68
68
|
return { command: process.execPath, args: [entryPath], env };
|
|
69
69
|
}
|
|
70
|
+
/** Entry for the `npx -y proton-drive-mcp` form: nothing is pinned to an install or cache path, except the CLI. */
|
|
71
|
+
export function buildNpxEntry(cliPath) {
|
|
72
|
+
return { command: "npx", args: ["-y", "proton-drive-mcp"], env: { PROTON_DRIVE_BIN: cliPath } };
|
|
73
|
+
}
|
|
70
74
|
export function isDirectory(p) {
|
|
71
75
|
try {
|
|
72
76
|
return statSync(p).isDirectory();
|
|
@@ -92,6 +96,67 @@ function parseConfig(file) {
|
|
|
92
96
|
}
|
|
93
97
|
return parsed;
|
|
94
98
|
}
|
|
99
|
+
// `proton-drive-mcp` or `proton-drive-mcp@<version>` as one argument (npx form), or a package directory in a path (global install).
|
|
100
|
+
const PACKAGE_SPEC = /^proton-drive-mcp(@\S+)?$/;
|
|
101
|
+
const PACKAGE_DIR = /(^|[\\/])proton-drive-mcp[\\/]dist[\\/]/;
|
|
102
|
+
/** True for a server entry that starts this package: command `proton-drive-mcp`, or an argument naming it exactly (not a substring such as `proton-drive-mcp-notes`). */
|
|
103
|
+
export function looksLikeOurServer(entry) {
|
|
104
|
+
const e = entry;
|
|
105
|
+
if (typeof e?.command === "string" && basename(e.command) === SERVER_KEY)
|
|
106
|
+
return true;
|
|
107
|
+
return Array.isArray(e?.args) && e.args.some((x) => typeof x === "string" && (PACKAGE_SPEC.test(x) || PACKAGE_DIR.test(x)));
|
|
108
|
+
}
|
|
109
|
+
/** The key our server is registered under: "proton-drive-mcp" if present, else the first entry that looks like it. */
|
|
110
|
+
export function findOwnServerKey(servers) {
|
|
111
|
+
return SERVER_KEY in servers ? SERVER_KEY : Object.keys(servers).find((k) => looksLikeOurServer(servers[k]));
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* What `init` would do to the config at `file`. An existing entry is compared on command, args and PROTON_DRIVE_BIN only
|
|
115
|
+
* (an absolute path to an existing `npx` is a valid command and is kept), and replacing it overrides just those:
|
|
116
|
+
* all other env keys (mode, roots, audit log, sync path, ...) and fields survive. Throws like writeEntry on an unusable file.
|
|
117
|
+
*/
|
|
118
|
+
export function planNpxEntry(file, cliPath) {
|
|
119
|
+
const fresh = buildNpxEntry(cliPath);
|
|
120
|
+
const base = { entry: fresh, preservedEnvKeys: [], fromPinned: false, notes: [], otherKeys: [], hasOwnKey: false };
|
|
121
|
+
if (!existsSync(file))
|
|
122
|
+
return { ...base, state: "no-file" };
|
|
123
|
+
const servers = parseConfig(file)["mcpServers"];
|
|
124
|
+
if (servers !== undefined && (!servers || typeof servers !== "object" || Array.isArray(servers))) {
|
|
125
|
+
throw new Error(`"mcpServers" in ${file} is not an object; refusing to modify it.`);
|
|
126
|
+
}
|
|
127
|
+
const all = (servers ?? {});
|
|
128
|
+
const otherKeys = Object.keys(all).filter((k) => k !== SERVER_KEY && looksLikeOurServer(all[k]));
|
|
129
|
+
const current = all[SERVER_KEY];
|
|
130
|
+
if (current === undefined)
|
|
131
|
+
return { ...base, state: otherKeys.length ? "other-key" : "absent", otherKeys };
|
|
132
|
+
if (!current || typeof current !== "object" || Array.isArray(current)) {
|
|
133
|
+
throw new Error(`mcpServers["${SERVER_KEY}"] in ${file} is not an object; refusing to modify it.`);
|
|
134
|
+
}
|
|
135
|
+
const cur = current;
|
|
136
|
+
const curEnv = cur["env"] && typeof cur["env"] === "object" && !Array.isArray(cur["env"]) ? cur["env"] : {};
|
|
137
|
+
const curCommand = typeof cur["command"] === "string" ? cur["command"] : "";
|
|
138
|
+
const keepCommand = curCommand !== "npx" && basename(curCommand) === "npx" && resolveBinary(curCommand) !== undefined;
|
|
139
|
+
const command = keepCommand ? curCommand : fresh.command;
|
|
140
|
+
const curArgs = Array.isArray(cur["args"]) ? cur["args"] : [];
|
|
141
|
+
const entry = { ...cur, command, args: fresh.args, env: { ...curEnv, PROTON_DRIVE_BIN: cliPath } };
|
|
142
|
+
const same = (keepCommand || curCommand === fresh.command) && JSON.stringify(cur["args"]) === JSON.stringify(fresh.args) && curEnv["PROTON_DRIVE_BIN"] === cliPath;
|
|
143
|
+
const pin = curArgs.find((x) => typeof x === "string" && /^proton-drive-mcp@\S+$/.test(x) && x !== "proton-drive-mcp@latest");
|
|
144
|
+
const notes = [];
|
|
145
|
+
if (cur["disabled"] === true)
|
|
146
|
+
notes.push('the existing entry has "disabled": true (kept), so Claude Desktop will not start it until you enable it');
|
|
147
|
+
if ("cwd" in cur)
|
|
148
|
+
notes.push('the existing entry has a "cwd" field (kept); the npx form does not need one');
|
|
149
|
+
return {
|
|
150
|
+
state: otherKeys.length ? "other-key" : same ? "same" : "different",
|
|
151
|
+
entry,
|
|
152
|
+
preservedEnvKeys: Object.keys(curEnv).filter((k) => k !== "PROTON_DRIVE_BIN"),
|
|
153
|
+
fromPinned: !keepCommand && curCommand !== fresh.command && curArgs.some((x) => typeof x === "string" && /[\\/]dist[\\/]index\.js$/.test(x)),
|
|
154
|
+
...(pin ? { droppedVersionPin: pin } : {}),
|
|
155
|
+
notes,
|
|
156
|
+
otherKeys,
|
|
157
|
+
hasOwnKey: true,
|
|
158
|
+
};
|
|
159
|
+
}
|
|
95
160
|
/**
|
|
96
161
|
* Adds/replaces only mcpServers["proton-drive-mcp"], keeping everything else.
|
|
97
162
|
* Returns the backup path (undefined when the file did not exist yet).
|
package/dist/utils/cliVersion.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
/** CLI major.minor this server is tested against (live-tested: CLI 0.8.0
|
|
2
|
-
export const
|
|
1
|
+
/** CLI major.minor versions this server is tested against (live-tested: CLI 0.8.0 with SDK js 0.21.0, and 0.9.0 with SDK js 0.22.2 for files, sharing reads and photo reads). */
|
|
2
|
+
export const TESTED_CLIS = ["0.8", "0.9"];
|
|
3
|
+
const TESTED_LABEL = TESTED_CLIS.map((v) => `${v}.x`).join(" and ");
|
|
3
4
|
export const ISSUES_URL = "https://github.com/googlarz/proton-drive-mcp/issues";
|
|
4
5
|
/** Extracts the CLI's "major.minor" from `proton-drive version` output ("Proton Drive CLI cli-drive@0.8.0+abc"), or undefined. */
|
|
5
6
|
export function parseCliMajorMinor(text) {
|
|
@@ -10,8 +11,8 @@ export function parseCliMajorMinor(text) {
|
|
|
10
11
|
export function cliCompatWarning(text) {
|
|
11
12
|
const mm = parseCliMajorMinor(text);
|
|
12
13
|
if (!mm)
|
|
13
|
-
return `Could not read the proton-drive CLI version. Tested with ${
|
|
14
|
-
if (mm
|
|
15
|
-
return `proton-drive CLI ${mm}.x found. Tested with ${
|
|
14
|
+
return `Could not read the proton-drive CLI version. Tested with ${TESTED_LABEL}; behaviour of other versions is unverified — report issues at ${ISSUES_URL}`;
|
|
15
|
+
if (!TESTED_CLIS.includes(mm))
|
|
16
|
+
return `proton-drive CLI ${mm}.x found. Tested with ${TESTED_LABEL}; behaviour of other versions is unverified — report issues at ${ISSUES_URL}`;
|
|
16
17
|
return undefined;
|
|
17
18
|
}
|
package/dist/utils/doctor.js
CHANGED
|
@@ -2,9 +2,9 @@ import { accessSync, constants, existsSync, readFileSync } from "node:fs";
|
|
|
2
2
|
import { resolve } from "node:path";
|
|
3
3
|
import { DriveService } from "../services/drive.js";
|
|
4
4
|
import { runDriveRaw } from "./subprocess.js";
|
|
5
|
-
import { cliCompatWarning,
|
|
5
|
+
import { cliCompatWarning, TESTED_CLIS } from "./cliVersion.js";
|
|
6
6
|
import { chooseEngines, ocrEnabled, ocrLanguages, resolveTool, runOcrTool } from "../services/ocr.js";
|
|
7
|
-
import { defaultConfigPath, isDirectory, isExecutableFile, resolveBinary, resolveDriveCli
|
|
7
|
+
import { defaultConfigPath, findOwnServerKey, isDirectory, isExecutableFile, resolveBinary, resolveDriveCli } from "./claudeConfig.js";
|
|
8
8
|
const SYSTEM_PATH_DIRS = ["/usr/bin", "/bin", "/usr/local/bin", "/opt/homebrew/bin"];
|
|
9
9
|
const SETUP_HINT = "Run `proton-drive-cli setup-claude-desktop --write`, then fully restart Claude Desktop.";
|
|
10
10
|
function nodeCheck() {
|
|
@@ -41,7 +41,7 @@ async function cliChecks() {
|
|
|
41
41
|
const warning = cliCompatWarning(versionText);
|
|
42
42
|
checks.push(warning
|
|
43
43
|
? { id: "cli-version", status: "warn", message: version, hint: warning }
|
|
44
|
-
: { id: "cli-version", status: "ok", message: `matches tested ${
|
|
44
|
+
: { id: "cli-version", status: "ok", message: `matches tested ${TESTED_CLIS.map((v) => `${v}.x`).join(" and ")}` });
|
|
45
45
|
}
|
|
46
46
|
try {
|
|
47
47
|
const auth = await new DriveService().authStatus();
|
|
@@ -86,10 +86,7 @@ function configCheck(configPath, cliPath) {
|
|
|
86
86
|
return { id, status: "fail", message: `${configPath} is not valid JSON`, hint: "Fix the JSON syntax; Claude Desktop ignores an unparsable config." };
|
|
87
87
|
}
|
|
88
88
|
// Only our own entry is ever inspected or reported: other servers' entries hold secrets.
|
|
89
|
-
const key =
|
|
90
|
-
const a = servers[k]?.args;
|
|
91
|
-
return Array.isArray(a) && a.some((x) => typeof x === "string" && x.includes(SERVER_KEY));
|
|
92
|
-
});
|
|
89
|
+
const key = findOwnServerKey(servers);
|
|
93
90
|
if (!key) {
|
|
94
91
|
return { id, status: "warn", message: `No proton-drive-mcp entry in ${configPath}`, hint: SETUP_HINT };
|
|
95
92
|
}
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import { execFile } from "node:child_process";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { dirname, join, resolve } from "node:path";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
import { buildNpxEntry, isExecutableFile, planNpxEntry, resolveBinary, resolveDriveCli, writeEntry, SERVER_KEY } from "./claudeConfig.js";
|
|
6
|
+
import { formatDoctor } from "./doctor.js";
|
|
7
|
+
const DOWNLOAD_URL = "https://proton.me/download/drive/cli/index.html";
|
|
8
|
+
// Probed when the CLI is not on PATH (a minimal shell, or a fresh install not yet on PATH).
|
|
9
|
+
const FALLBACK_DIRS = [join(homedir(), ".local", "bin"), "/opt/homebrew/bin", "/usr/local/bin"];
|
|
10
|
+
// Directories Claude Desktop (a GUI app) can be expected to find `npx` in.
|
|
11
|
+
const GUI_PATH_DIRS = ["/usr/bin", "/bin", "/usr/local/bin", "/opt/homebrew/bin"];
|
|
12
|
+
/** PROTON_DRIVE_BIN or PATH (the server's own resolver), then the usual install dirs. */
|
|
13
|
+
export function locateDriveCli() {
|
|
14
|
+
const direct = resolveDriveCli();
|
|
15
|
+
if (direct)
|
|
16
|
+
return { path: direct, viaFallback: false };
|
|
17
|
+
if (process.env["PROTON_DRIVE_BIN"])
|
|
18
|
+
return { viaFallback: false }; // an explicit setting is never second-guessed
|
|
19
|
+
for (const dir of FALLBACK_DIRS) {
|
|
20
|
+
const candidate = join(dir, "proton-drive");
|
|
21
|
+
if (isExecutableFile(candidate))
|
|
22
|
+
return { path: candidate, viaFallback: true };
|
|
23
|
+
}
|
|
24
|
+
return { viaFallback: false };
|
|
25
|
+
}
|
|
26
|
+
/** Single-quotes for a POSIX shell: nothing inside expands (not `$`, backticks or history `!`); a literal `'` becomes '\''. */
|
|
27
|
+
export function shellQuote(s) {
|
|
28
|
+
return `'${s.replace(/'/g, `'\\''`)}'`;
|
|
29
|
+
}
|
|
30
|
+
/** Runs `doctor --json` in a child so PROTON_DRIVE_BIN can be set before the CLI path is read at import time. */
|
|
31
|
+
function runDoctorChild(configPath, cliPath, viaFallback) {
|
|
32
|
+
const cliJs = resolve(dirname(fileURLToPath(import.meta.url)), "..", "cli.js");
|
|
33
|
+
const env = { ...process.env, ...(viaFallback && cliPath ? { PROTON_DRIVE_BIN: cliPath } : {}) };
|
|
34
|
+
return new Promise((res, rej) => {
|
|
35
|
+
// doctor exits 1 when a check fails but still prints its result, so the error is only used if stdout is unusable.
|
|
36
|
+
execFile(process.execPath, [cliJs, "doctor", "--json", "--config", configPath], { env, timeout: 60_000 }, (err, stdout, stderr) => {
|
|
37
|
+
try {
|
|
38
|
+
res(JSON.parse(stdout));
|
|
39
|
+
}
|
|
40
|
+
catch {
|
|
41
|
+
rej(new Error(`doctor produced no result${err ? `: ${err.message.split("\n")[0]}` : ""}${stderr ? `\n${stderr.trim()}` : ""}`));
|
|
42
|
+
}
|
|
43
|
+
});
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
function nextStep(checks) {
|
|
47
|
+
const failed = checks.filter((c) => c.status === "fail");
|
|
48
|
+
const first = failed.find((c) => c.id === "cli") ?? failed[0];
|
|
49
|
+
const again = "then re-run `npx -y proton-drive-mcp init`";
|
|
50
|
+
if (first.id === "cli")
|
|
51
|
+
return `Install the official Proton Drive CLI from ${DOWNLOAD_URL} (or set PROTON_DRIVE_BIN to its absolute path), run \`proton-drive auth login\`, ${again}.`;
|
|
52
|
+
if (first.id === "auth")
|
|
53
|
+
return `Run \`proton-drive auth login\`, ${again}.`;
|
|
54
|
+
return `${first.hint ?? first.message} (${first.id}), ${again}.`;
|
|
55
|
+
}
|
|
56
|
+
/** Doctor's claude-desktop line echoes the values of the existing entry's PROTON_DRIVE_* env; init never prints env values. */
|
|
57
|
+
function redact(c) {
|
|
58
|
+
if (c.id !== "claude-desktop")
|
|
59
|
+
return c;
|
|
60
|
+
const message = c.message
|
|
61
|
+
.replace(/ \(PROTON_DRIVE_BIN=.*\)$/, " (env values not shown)")
|
|
62
|
+
.replace(/PROTON_DRIVE_BIN=.* is not an executable file$/, "PROTON_DRIVE_BIN in the entry is not an executable file");
|
|
63
|
+
return { ...c, message };
|
|
64
|
+
}
|
|
65
|
+
const verdict = (ok) => (ok ? "No problems found." : "Problems found.");
|
|
66
|
+
export async function runInit(opts) {
|
|
67
|
+
const { configPath, write } = opts;
|
|
68
|
+
if (process.platform === "win32") {
|
|
69
|
+
const text = "init is not supported on Windows (see \"Platform support\" in the README).";
|
|
70
|
+
return { ok: false, text, json: { ok: false, error: text } };
|
|
71
|
+
}
|
|
72
|
+
const located = locateDriveCli();
|
|
73
|
+
const doctor = await runDoctorChild(configPath, located.path, located.viaFallback);
|
|
74
|
+
// init is what fixes the Claude Desktop entry, so a stale or missing one is shown as a warning, must not block it,
|
|
75
|
+
// and doctor's "run setup-claude-desktop" hint would point the wrong way. Other failures still block.
|
|
76
|
+
const checks = doctor.checks.map((c) => {
|
|
77
|
+
const r = redact(c);
|
|
78
|
+
if (r.id !== "claude-desktop" || r.status === "ok")
|
|
79
|
+
return r;
|
|
80
|
+
return { ...r, status: "warn", ...(r.hint?.includes("setup-claude-desktop") ? { hint: undefined } : {}) };
|
|
81
|
+
});
|
|
82
|
+
const doctorOk = !checks.some((c) => c.status === "fail");
|
|
83
|
+
// formatDoctor ends with a blank line and its own verdict; init prints one verdict at the very end instead.
|
|
84
|
+
const lines = ["proton-drive-mcp init", "", ...formatDoctor({ ok: true, checks }).split("\n").slice(0, -2)];
|
|
85
|
+
const json = { ok: doctorOk, cliPath: located.path ?? null, checks };
|
|
86
|
+
if (!doctorOk) {
|
|
87
|
+
const step = nextStep(checks);
|
|
88
|
+
lines.push("", `Next step: ${step}`);
|
|
89
|
+
json["nextStep"] = step;
|
|
90
|
+
}
|
|
91
|
+
if (!located.path) {
|
|
92
|
+
lines.push("", ...(write ? ["Nothing was written to your Claude Desktop config.", ""] : []), verdict(false));
|
|
93
|
+
return { ok: false, text: lines.join("\n"), json };
|
|
94
|
+
}
|
|
95
|
+
const shown = JSON.stringify({ mcpServers: { [SERVER_KEY]: buildNpxEntry(located.path) } }, null, 2);
|
|
96
|
+
const claudeCode = `claude mcp add --env PROTON_DRIVE_BIN=${shellQuote(located.path)} proton-drive -- npx -y proton-drive-mcp`;
|
|
97
|
+
json["claudeCode"] = claudeCode;
|
|
98
|
+
let ok = doctorOk;
|
|
99
|
+
let bareNpx = true;
|
|
100
|
+
lines.push("", `Claude Desktop (${configPath}):`, shown);
|
|
101
|
+
try {
|
|
102
|
+
const plan = planNpxEntry(configPath, located.path);
|
|
103
|
+
bareNpx = plan.entry.command === "npx";
|
|
104
|
+
const kept = plan.preservedEnvKeys.length ? ` Kept as they are in the existing entry: env ${plan.preservedEnvKeys.join(", ")} (values not shown).` : "";
|
|
105
|
+
const extra = [
|
|
106
|
+
...(plan.fromPinned ? ["The existing entry runs a pinned install (setup-claude-desktop form); the npx form runs the latest published version instead."] : []),
|
|
107
|
+
...(plan.droppedVersionPin ? [`The version pin ${plan.droppedVersionPin} is dropped in favor of the latest published version.`] : []),
|
|
108
|
+
...plan.notes.map((n) => `Note: ${n}.`),
|
|
109
|
+
].map((t) => ` ${t}`).join("");
|
|
110
|
+
json["claudeDesktop"] = {
|
|
111
|
+
configPath, entry: buildNpxEntry(located.path), preservedEnvKeys: plan.preservedEnvKeys, fromPinned: plan.fromPinned,
|
|
112
|
+
droppedVersionPin: plan.droppedVersionPin ?? null, notes: plan.notes,
|
|
113
|
+
};
|
|
114
|
+
if (plan.state === "other-key") {
|
|
115
|
+
ok = false;
|
|
116
|
+
const names = plan.otherKeys.map((k) => `"${k}"`).join(", ");
|
|
117
|
+
lines.push(`Not changed: this server is already registered under ${names} in ${configPath}, and a second entry would start a second copy and double the tools. To proceed, remove ${plan.otherKeys.length > 1 ? "those entries" : "that entry"}${plan.hasOwnKey ? "" : ` (or rename it to "${SERVER_KEY}" so init can update it)`}, then re-run \`npx -y proton-drive-mcp init${write ? " --write" : ""}\`.`);
|
|
118
|
+
json["claudeDesktop"] = { ...json["claudeDesktop"], action: "refused", otherKeys: plan.otherKeys };
|
|
119
|
+
}
|
|
120
|
+
else if (plan.state === "same") {
|
|
121
|
+
lines.push(`Already up to date; nothing changed.${kept}${extra}`);
|
|
122
|
+
json["claudeDesktop"] = { ...json["claudeDesktop"], action: "none" };
|
|
123
|
+
}
|
|
124
|
+
else if (!write) {
|
|
125
|
+
lines.push(`Dry run: nothing changed.${plan.state === "different" ? " An existing proton-drive-mcp entry would be replaced." : ""}${kept}${extra} Re-run with --write to apply (timestamped backup first; other servers are never touched).`);
|
|
126
|
+
json["claudeDesktop"] = { ...json["claudeDesktop"], action: "dry-run" };
|
|
127
|
+
}
|
|
128
|
+
else {
|
|
129
|
+
const backup = writeEntry(configPath, plan.entry);
|
|
130
|
+
lines.push(`Wrote ${SERVER_KEY} to ${configPath}${backup ? ` (backup: ${backup})` : ""}.${kept}${extra}`, "Fully quit and restart Claude Desktop for the change to take effect.");
|
|
131
|
+
json["claudeDesktop"] = { ...json["claudeDesktop"], action: "written", backup: backup ?? null };
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
catch (e) {
|
|
135
|
+
ok = false;
|
|
136
|
+
lines.push(`Error: ${e instanceof Error ? e.message : String(e)}`);
|
|
137
|
+
}
|
|
138
|
+
lines.push("Note: the npx entry runs with the Node that Claude Desktop finds on its own PATH (it needs Node 22 or newer); doctor cannot check that.");
|
|
139
|
+
const npx = resolveBinary("npx");
|
|
140
|
+
if (bareNpx && npx && !GUI_PATH_DIRS.some((d) => npx.startsWith(d + "/"))) {
|
|
141
|
+
lines.push(`Note: npx is at ${npx}, outside the PATH Claude Desktop is likely to use. If it cannot start the server, put that absolute path in "command" and add "PATH" (the directory of node) to env.`);
|
|
142
|
+
}
|
|
143
|
+
lines.push("", "Claude Code:", claudeCode, "", verdict(ok));
|
|
144
|
+
return { ok, text: lines.join("\n"), json };
|
|
145
|
+
}
|
package/glama.json
CHANGED
|
@@ -170,6 +170,10 @@
|
|
|
170
170
|
"name": "photos_upload",
|
|
171
171
|
"description": "Upload local photos or videos directly into your Proton Photos library."
|
|
172
172
|
},
|
|
173
|
+
{
|
|
174
|
+
"name": "drive_size",
|
|
175
|
+
"description": "Get the size of one Proton Drive file or folder (needs Proton Drive CLI 0.9.0 or newer)."
|
|
176
|
+
},
|
|
173
177
|
{
|
|
174
178
|
"name": "drive_tree",
|
|
175
179
|
"description": "Show a Proton Drive folder as a tree with per-folder file counts and size totals."
|
package/package.json
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "proton-drive-mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.10.0",
|
|
4
|
+
"mcpName": "io.github.googlarz/proton-drive-mcp",
|
|
4
5
|
"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.",
|
|
5
6
|
"type": "module",
|
|
6
7
|
"main": "dist/index.js",
|
|
@@ -54,7 +55,7 @@
|
|
|
54
55
|
"node": ">=22.0.0"
|
|
55
56
|
},
|
|
56
57
|
"dependencies": {
|
|
57
|
-
"@modelcontextprotocol/sdk": "
|
|
58
|
+
"@modelcontextprotocol/sdk": "1.32.2"
|
|
58
59
|
},
|
|
59
60
|
"devDependencies": {
|
|
60
61
|
"@types/node": "^22.10.2",
|