proton-mail-bridge-client 1.14.0 → 1.16.0

package/README.md

@@ -24,12 +24,12 @@
 
 ---
 
-Give Claude Desktop (or Cline, or any MCP client) full access to your Proton Mail inbox: read, search, send, draft, triage threads, manage folders, save attachments, and more. The same 40+ capabilities are also available as a full CLI for scripting, cron, and piped automation — no Claude required.
+Give Claude Desktop (or Cline, or any MCP client) full access to your Proton Mail inbox: read, search, send, draft, triage threads, manage folders, save attachments, and more — 78 MCP tools in total. Most of the same capabilities are also available as a full CLI for scripting, cron, and piped automation — no Claude required.
 
 ## What you get
 
 - **Claude reads and manages your Proton Mail** — triage, reply, draft, archive, search, move, batch-act on threads, pull attachments
-- **Full CLI** — same 40+ commands, scriptable and pipeable, works in cron and shell scripts
+- **Full CLI** — 73 commands covering nearly all of the same capabilities, scriptable and pipeable, works in cron and shell scripts
 - **Fast local search** — full-text search across your inbox without hitting IMAP on every query
 - **Safety controls** — read-only mode, send gate, destructive-action confirmation, per-action allowlist
 - **Privacy-native** — no third-party email service involved; your mail stays on your machine
@@ -194,6 +194,40 @@ The wizard handles config automatically. If you need to set it up by hand, three
 
 ---
 
+## Connect to Claude Code
+
+Install globally, then register the server with one command:
+
+```bash
+npm install -g proton-mail-bridge-client
+
+claude mcp add proton-mail-bridge \
+  -e PROTONMAIL_USERNAME=you@proton.me \
+  -e PROTONMAIL_PASSWORD=your-bridge-password \
+  -- proton-mail-bridge-mcp
+```
+
+`your-bridge-password` is the Bridge app's own password (**Bridge → account → Mailbox details**), not your Proton account password — see the note under [Prerequisites](#prerequisites).
+
+By default this registers the server for the current project only. Add `-s user` to make it available in every project:
+
+```bash
+claude mcp add proton-mail-bridge -s user \
+  -e PROTONMAIL_USERNAME=you@proton.me \
+  -e PROTONMAIL_PASSWORD=your-bridge-password \
+  -- proton-mail-bridge-mcp
+```
+
+Verify it's connected:
+
+```bash
+claude mcp list
+```
+
+For file-based or command-based credentials instead of plaintext env vars, add `-e PROTONMAIL_USERNAME_FILE=/path/to/file` (or `_COMMAND`) the same way — see the credential methods under [Manual config](#connect-to-claude-desktop) above.
+
+---
+
 ## Connect to Cline (VS Code)
 
 Install globally (`npm install -g proton-mail-bridge-client`), then open Cline's MCP settings:
@@ -247,6 +281,8 @@ Reload the Cline extension after saving. Proton Mail tools will appear in Cline'
 
 > **Tip:** When creating folders, use `Folders/Name` (not just `Name`) — that's the Proton Bridge namespace for real folders vs. labels.
 
+More recipes — expanded triage prompts, cron scripts for scheduled digests, and a Claude Code `/mail-triage` slash command — are in [examples/](examples/).
+
 ---
 
 ## Recommended System Prompt
@@ -268,144 +304,18 @@ Rules:
 
 ## CLI
 
-```bash
-proton-mail-bridge-client <command> [options]
-```
-
-All commands support `--json` for machine-readable output.
-
-### Read
-
-```bash
-proton-mail-bridge-client emails --folder INBOX --limit 25
-proton-mail-bridge-client read INBOX::25642
-proton-mail-bridge-client search "invoice" --limit 10
-proton-mail-bridge-client search --live --from openai.com
-proton-mail-bridge-client attachments INBOX::25642
-```
-
-### Triage
-
-```bash
-proton-mail-bridge-client digest
-proton-mail-bridge-client threads "quarterly review"
-proton-mail-bridge-client actionable
-proton-mail-bridge-client followups
-proton-mail-bridge-client thread-brief <threadId>
-proton-mail-bridge-client document-threads --category invoice
-proton-mail-bridge-client meeting-context alice@example.com
-```
-
-### Compose & send
-
-```bash
-proton-mail-bridge-client send --to bob@example.com --subject "Hey" --body "Hello"
-echo "Hello" | proton-mail-bridge-client send --to bob@example.com --subject "Hey"
-proton-mail-bridge-client reply INBOX::25642 --body "On it."
-proton-mail-bridge-client reply INBOX::25642 --reply-all --body "On it."
-proton-mail-bridge-client forward INBOX::25642 --to carol@example.com
-```
-
-### Mailbox actions
-
-```bash
-proton-mail-bridge-client move INBOX::25642 Folders/Archive
-proton-mail-bridge-client archive INBOX::25642
-proton-mail-bridge-client trash INBOX::25642
-proton-mail-bridge-client restore Trash::25642
-proton-mail-bridge-client mark-read INBOX::25642
-proton-mail-bridge-client mark-read INBOX::25642 --unread
-proton-mail-bridge-client star INBOX::25642
-proton-mail-bridge-client delete INBOX::25642
-proton-mail-bridge-client batch archive INBOX::100,INBOX::101,INBOX::102
-proton-mail-bridge-client thread-action <threadId> archive
-```
-
-### Folders
-
-```bash
-proton-mail-bridge-client folders
-proton-mail-bridge-client create-folder Folders/Receipts
-proton-mail-bridge-client rename-folder Folders/Receipts Folders/Bills
-proton-mail-bridge-client delete-folder Folders/Bills
-```
-
-### Drafts
-
-```bash
-proton-mail-bridge-client drafts
-proton-mail-bridge-client draft-create --to bob@example.com --subject "Draft" --body "..."
-proton-mail-bridge-client draft-read <id>
-proton-mail-bridge-client draft-update <id> --subject "Updated subject"
-proton-mail-bridge-client draft-reply INBOX::25642 --body "Will do."
-proton-mail-bridge-client draft-forward INBOX::25642 --to carol@example.com
-proton-mail-bridge-client draft-sync <id>
-proton-mail-bridge-client draft-send <id>
-proton-mail-bridge-client draft-delete <id>
-proton-mail-bridge-client remote-drafts
-```
-
-### Analytics & diagnostics
-
-```bash
-proton-mail-bridge-client stats
-proton-mail-bridge-client analytics
-proton-mail-bridge-client contacts
-proton-mail-bridge-client volume-trends --days 14
-proton-mail-bridge-client watch --timeout 30
-proton-mail-bridge-client test-email you@example.com
-proton-mail-bridge-client doctor
-proton-mail-bridge-client status
-proton-mail-bridge-client sync --folder INBOX --limit 150
-```
-
-### Ambient notifications
-
-Run as a background daemon — sends a system notification (macOS / Linux) whenever new mail arrives:
-
-```bash
-proton-mail-bridge-client notify                              # foreground (Ctrl+C to stop)
-proton-mail-bridge-client notify &                            # background
-proton-mail-bridge-client notify --folder INBOX --timeout 60  # custom folder and idle timeout
-```
-
-Each event is also written as a JSON line to stdout:
-
-```json
-{"event":"new_mail","folder":"INBOX","count":2,"at":"2026-05-18T14:32:01.000Z"}
-```
-
-Uses IMAP IDLE — no polling between events. Reconnects automatically on transient errors.
-
-### MCP tool passthrough
-
-Any MCP tool is also callable directly from the CLI:
+Every capability is also a scriptable terminal command — no Claude required:
 
 ```bash
-proton-mail-bridge-client tools
-proton-mail-bridge-client tool get_connection_status --json
-proton-mail-bridge-client tool search_indexed_emails --args '{"query":"invoice","limit":3}'
+proton-mail-bridge-client digest                                    # morning triage summary
+proton-mail-bridge-client search --from stripe.com --json | jq .    # scriptable search
+echo "Deploy done" | proton-mail-bridge-client send --to you@x.com --subject "Deploy"
+proton-mail-bridge-client notify &                                  # background new-mail alerts
 ```
 
-### Pipe and script
-
-```bash
-# Morning digest to a file
-proton-mail-bridge-client digest --json > ~/morning-mail.json
+All commands support `--json` for machine-readable output, and any MCP tool is directly callable via `proton-mail-bridge-client tool <name> --args '{...}'`.
 
-# Pull every email from a domain
-proton-mail-bridge-client search --from stripe.com --json | jq '.[].subject'
-
-# Pipe a script's output directly into an email
-echo "Deploy complete on $(hostname) at $(date)" \
-  | proton-mail-bridge-client send --to alerts@example.com --subject "Deploy done"
-
-# Scheduled digest every weekday at 8am (cron)
-0 8 * * 1-5 proton-mail-bridge-client digest >> ~/mail-log.txt
-
-# Count unread in INBOX
-proton-mail-bridge-client emails --folder INBOX --json | jq '[.[] | select(.isRead == false)] | length'
-```
+**Full command reference: [docs/cli.md](docs/cli.md)** (73 commands across read, triage, compose, mailbox actions, folders, drafts, analytics, and diagnostics).
 
 ---
 
@@ -500,7 +410,7 @@ PROTONMAIL_IDLE_MAX_SECONDS='30'
 `mark_email_read` · `star_email` · `move_email` · `archive_email` · `trash_email` · `restore_email` · `delete_email` · `batch_email_action` · `apply_thread_action` · `empty_folder` · `bulk_delete` · `bulk_move` · `bulk_update_flags` · `bulk_update_labels` · `update_message_flags` · `update_message_labels`
 
 ### Folder management
-`create_folder` · `rename_folder` · `delete_folder` · `create_label`
+`create_folder` · `rename_folder` · `delete_folder` · `create_label` · `rename_label` · `delete_label`
 
 ### Analytics
 `get_email_stats` · `get_email_analytics` · `get_contacts` · `get_volume_trends` · `folder_stats` · `top_senders`

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAOA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAYnE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAYV,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAq/E1B,wBAAgB,kBAAkB,IAAI,gBAAgB,CAuFrD;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE;IACP,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4yEP;AAED,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAmD1C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAOA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAYnE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAwD,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC5H,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAYV,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAq/E1B,wBAAgB,kBAAkB,IAAI,gBAAgB,CA0FrD;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE;IACP,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAq2EP;AAED,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAmD1C"}

package/dist/index.js

@@ -13,7 +13,7 @@ import { AuditService } from "./services/audit-service.js";
 import { BackgroundSyncService } from "./services/background-sync-service.js";
 import { DraftStoreService } from "./services/draft-store-service.js";
 import { LocalIndexService } from "./services/local-index-service.js";
-import { SimpleIMAPService } from "./services/simple-imap-service.js";
+import { isLikelyAuthenticationError, isLikelyConnectionError, SimpleIMAPService } from "./services/simple-imap-service.js";
 import { SMTPService } from "./services/smtp-service.js";
 import { ensureValidEmails, isTextLikeMimeType, isValidEmail, lowerCaseAddress, normalizeBoolean, normalizeLimit, normalizeJsonValue, parseEmails, renderMarkdown, stringifyForJson, } from "./utils/helpers.js";
 import { logger } from "./utils/logger.js";
@@ -1043,7 +1043,7 @@ const TOOLS = [
     },
     {
         name: "run_doctor",
-        description: "Run a comprehensive production health check covering SMTP auth, IMAP auth, optional IMAP IDLE probe, SQLite index integrity, and runtime policy validation. Use to fully diagnose or validate the setup. Prefer get_connection_status for a quick protocol-only reachability check.",
+        description: "Run a comprehensive production health check covering SMTP auth, IMAP auth, optional IMAP IDLE probe, SQLite index integrity, sync-failed drafts, runtime policy validation, and what this server can/cannot do (capabilities). Connection failures include a classified diagnosis (authentication_failed vs bridge_unreachable) with a specific fix. Use to fully diagnose or validate the setup. Prefer get_connection_status for a quick protocol-only reachability check.",
         annotations: { readOnlyHint: true },
         inputSchema: {
             type: "object",
@@ -2355,7 +2355,10 @@ export function buildConfigFromEnv() {
             allowRemoteDraftSync,
             allowedActions: parseAllowedActionsEnv("PROTONMAIL_ALLOWED_ACTIONS"),
             startupSync: parseBooleanEnv("PROTONMAIL_STARTUP_SYNC", autoSync),
-            autoSyncFolder: process.env.PROTONMAIL_AUTO_SYNC_FOLDER?.trim() || "INBOX",
+            // Comma-separated; Sent is included by default so pendingOn/digest/follow-up
+            // candidates don't misreport threads that were already answered — IDLE still
+            // only watches the first folder (see BackgroundSyncService.primaryIdleFolder).
+            autoSyncFolder: process.env.PROTONMAIL_AUTO_SYNC_FOLDER?.trim() || "INBOX,Sent",
             autoSyncFull: parseBooleanEnv("PROTONMAIL_AUTO_SYNC_FULL", false),
             autoSyncLimitPerFolder: parseIntegerEnv("PROTONMAIL_AUTO_SYNC_LIMIT_PER_FOLDER", 100, 1, 500),
             idleWatchEnabled,
@@ -3730,7 +3733,7 @@ export function createServer(config, options = {}) {
                     const includeImap = normalizeBoolean(args.includeImap, true);
                     const includeIdleProbe = normalizeBoolean(args.includeIdleProbe, false);
                     const idleTimeoutSeconds = normalizeLimit(args.idleTimeoutSeconds, 5, 1, 60);
-                    const [smtpStatus, imapStatus, indexStatus, integrity] = await Promise.all([
+                    const [smtpStatus, imapStatus, indexStatus, integrity, drafts] = await Promise.all([
                         includeSmtp
                             ? Promise.allSettled([smtpService.verifyConnection()]).then(([result]) => result)
                             : Promise.resolve({ status: "fulfilled", value: undefined }),
@@ -3739,6 +3742,7 @@ export function createServer(config, options = {}) {
                             : Promise.resolve({ status: "fulfilled", value: undefined }),
                         localIndexService.getStatus(),
                         localIndexService.runIntegrityCheck(),
+                        draftStore.listDrafts(true),
                     ]);
                     const idleProbe = includeIdleProbe
                         ? await Promise.allSettled([
@@ -3748,6 +3752,24 @@ export function createServer(config, options = {}) {
                             }),
                         ]).then(([result]) => result)
                         : undefined;
+                    // Classifies the connection failure into a specific, actionable cause —
+                    // without PROTONMAIL_DEBUG this used to just say "connection failed" for
+                    // both a wrong password and Bridge not being open at all.
+                    const diagnoseFailure = (reason) => {
+                        if (isLikelyAuthenticationError(reason)) {
+                            return {
+                                cause: "authentication_failed",
+                                suggestion: "PROTONMAIL_PASSWORD must be the Proton Bridge password (Bridge app -> account -> Mailbox details), not your Proton account password. Confirm you're signed in inside the Bridge app.",
+                            };
+                        }
+                        if (isLikelyConnectionError(reason)) {
+                            return {
+                                cause: "bridge_unreachable",
+                                suggestion: "Proton Bridge isn't reachable on the configured host/port. Make sure the Bridge app is running, and that PROTONMAIL_IMAP_HOST/PORT and PROTONMAIL_SMTP_HOST/PORT match Bridge's Mailbox details.",
+                            };
+                        }
+                        return undefined;
+                    };
                     return createTextResult({
                         checkedAt: new Date().toISOString(),
                         runtime: sanitizeRuntimeConfig(config.runtime),
@@ -3761,6 +3783,7 @@ export function createServer(config, options = {}) {
                                         ? smtpStatus.reason.message
                                         : String(smtpStatus.reason)
                                     : "SMTP connection failed.",
+                            ...(smtpStatus.status === "rejected" ? { diagnosis: diagnoseFailure(smtpStatus.reason) } : {}),
                         },
                         imap: {
                             ok: imapStatus.status === "fulfilled",
@@ -3773,6 +3796,7 @@ export function createServer(config, options = {}) {
                                         ? imapStatus.reason.message
                                         : String(imapStatus.reason)
                                     : "IMAP connection failed.",
+                            ...(imapStatus.status === "rejected" ? { diagnosis: diagnoseFailure(imapStatus.reason) } : {}),
                         },
                         idleProbe: idleProbe === undefined
                             ? { skipped: true }
@@ -3789,9 +3813,28 @@ export function createServer(config, options = {}) {
                         backgroundSync: backgroundSyncService.getStatus(),
                         index: indexStatus,
                         integrity,
+                        drafts: {
+                            total: drafts.length,
+                            syncFailed: drafts.filter((draft) => draft.remoteSyncState === "sync_failed").length,
+                            syncFailedIds: drafts
+                                .filter((draft) => draft.remoteSyncState === "sync_failed")
+                                .map((draft) => draft.id),
+                        },
                         audit: {
                             path: auditService.getPath(),
                         },
+                        // What this server can and cannot do, given Proton Bridge only proxies
+                        // local IMAP/SMTP — prevents an agent from attempting an impossible
+                        // operation (e.g. server-side filters) and getting a confusing failure.
+                        capabilities: {
+                            supported: ["mail read/search/send", "folders", "labels (IMAP folders under Labels/)", "drafts", "local full-text index"],
+                            notSupported: [
+                                "server-side filters/rules (no ManageSieve access through Bridge)",
+                                "real contacts / address book (no CardDAV access through Bridge)",
+                                "calendar (no CalDAV access through Bridge)",
+                                "vacation responder (Proton account API only, not exposed via Bridge)",
+                            ],
+                        },
                     });
                 }
                 case "get_runtime_status": {
@@ -4286,7 +4329,13 @@ export function createServer(config, options = {}) {
                 throw error;
             }
             logger.error("Tool call failed", "MCPServer", { name, error });
-            throw new McpError(ErrorCode.InternalError, "An internal error occurred. Check get_logs for details.");
+            if (isLikelyAuthenticationError(error)) {
+                throw new McpError(ErrorCode.InternalError, "IMAP authentication failed. Check that PROTONMAIL_PASSWORD is your Proton Bridge password (not your Proton account password) and that you're signed in inside the Bridge app. Run run_doctor for a full connectivity check.");
+            }
+            if (isLikelyConnectionError(error)) {
+                throw new McpError(ErrorCode.InternalError, "Could not connect to Proton Bridge. Make sure the Bridge app is running, and that PROTONMAIL_IMAP_HOST/PORT and PROTONMAIL_SMTP_HOST/PORT match the ports shown in Bridge's settings. Run run_doctor for a full connectivity check.");
+            }
+            throw new McpError(ErrorCode.InternalError, "An internal error occurred. Check get_logs for details, or run run_doctor for a full connectivity check.");
         }
     });
     return {