proton-mail-bridge-client 2.7.3 → 2.8.1

package/README.md

@@ -24,7 +24,7 @@
 
 ---
 
-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 — 96 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.
+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 — 100 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.
 
 > **Using Proton Drive too?** See [**proton-drive-mcp**](https://github.com/googlarz/proton-drive-mcp), the companion MCP server and CLI for Proton Drive (upload, download, share and manage your encrypted files from Claude). Run both side by side to handle mail and files in one conversation, for example save an attachment from here, then upload it to Drive. More in [Related projects](#related-projects).
 
@@ -42,14 +42,14 @@ Give Claude Desktop (or Cline, or any MCP client) full access to your Proton Mai
    - "Find the last email from `alice@example.com` and draft a reply for me to review." (nothing is sent until you say so)
    - "Which of my emails have attachments from this month?"
    - "Show me my drafts and tighten the oldest one."
-5. **Optional:** `PROTONMAIL_READ_ONLY=true` to browse without being able to change anything, `PROTONMAIL_TOOL_TIER=core` for a smaller tool set (25 instead of 96), and more accounts under [Multi-account support](#multi-account-support-v210). More recipes below in [Try it](#try-it-example-claude-prompts).
+5. **Optional:** `PROTONMAIL_READ_ONLY=true` to browse without being able to change anything, `PROTONMAIL_TOOL_TIER=core` for a smaller tool set (25 instead of 100), and more accounts under [Multi-account support](#multi-account-support-v210). More recipes below in [Try it](#try-it-example-claude-prompts).
 
 ---
 
 ## What you get
 
 - **Claude reads and manages your Proton Mail** — triage, reply, draft, archive, search, move, batch-act on threads, pull attachments
-- **Full CLI** — a dedicated command for every one of the 96 tools (plus a generic `tool <name>` passthrough), scriptable and pipeable, works in cron and shell scripts
+- **Full CLI** — a dedicated command for every one of the 100 tools (plus a generic `tool <name>` passthrough), 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
@@ -326,6 +326,7 @@ First, enable **Split Addresses** in Proton Bridge and configure each address as
 - **Additional accounts:** each has an auto-generated slug (e.g., `alias`, `business`). Email IDs carry an account prefix: `alias::message-id`, `business::message-id`.
 - **Sending:** `send_email`, `reply_to_email`, etc. route through the account matching the `from` address. If no account matches, the primary connection is used with a header override (for non-configured aliases).
 - **Search and read:** all read tools (search, threads, analytics, digest) automatically fan out across all configured accounts and merge results, preserving the account prefix in returned IDs.
+- **One account only:** the triage, statistics, draft and folder tools (`get_threads`, `get_inbox_digest`, `get_follow_up_candidates`, `get_labels`, `list_drafts`, `get_folders`, `top_senders`, ...) take an optional `account` (address or slug) to look at a single account instead of all of them; an unknown value is an error.
 
 ### Tools across accounts
 
@@ -381,6 +382,12 @@ Output:
 **Draft review**
 > "Show me my drafts, pick the oldest one, and suggest a better subject line and closing paragraph."
 
+**Calendar invitations**
+> "Do I have any unanswered meeting invitations this week? Accept the ones that don't clash with each other and show me the rest."
+
+**Follow-up**
+> "I just sent the proposal to Ann. If she hasn't answered in five days, remind me."
+
 > **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/).
@@ -421,7 +428,7 @@ All commands support `--json` for machine-readable output, and any MCP tool is d
 
 `<command> --help` prints that command's usage without running it. Flags accept `--flag value` or `--flag=value` (a value starting with `--` needs the `=` form, or must come after a bare `--`); unknown flags are an error. Exit codes: `0` success, `1` failure (including a failed `doctor` or `connection-status` check, or a failed item in a `batch`/`bulk-*` run), `2` usage error.
 
-**Full command reference: [docs/cli.md](docs/cli.md)** (a named command for every one of the 96 tools, across read, triage, compose, mailbox actions, folders, drafts, templates, analytics, and diagnostics).
+**Full command reference: [docs/cli.md](docs/cli.md)** (a named command for every one of the 100 tools, across read, triage, compose, mailbox actions, folders, drafts, templates, analytics, and diagnostics).
 
 ---
 
@@ -430,7 +437,7 @@ All commands support `--json` for machine-readable output, and any MCP tool is d
 All flags work in both the MCP server and CLI:
 
 ```bash
-PROTONMAIL_TOOL_TIER=core            # expose 25 core tools instead of all 96 — saves context window
+PROTONMAIL_TOOL_TIER=core            # expose 25 core tools instead of all 100 — saves context window
 PROTONMAIL_READ_ONLY=true            # disable all write operations
 PROTONMAIL_ALLOW_SEND=false          # disable SMTP sends only (other writes still work)
 PROTONMAIL_CONFIRM_DESTRUCTIVE=true  # require confirmed:true on send, reply, forward, delete
@@ -474,7 +481,7 @@ PROTONMAIL_PASSWORD_COMMAND='pass proton/password'
 PROTONMAIL_DATA_DIR="$HOME/.proton-mail-bridge-client"
 
 # Tools
-PROTONMAIL_TOOL_TIER='full'          # 'core' exposes 25 essential tools, incl. draft review/edit and list_accounts (saves context window); 'full' exposes all 96
+PROTONMAIL_TOOL_TIER='full'          # 'core' exposes 25 essential tools, incl. draft review/edit and list_accounts (saves context window); 'full' exposes all 100
 
 # Safety
 PROTONMAIL_READ_ONLY='false'
@@ -535,7 +542,7 @@ With several accounts or a signature, the server sends from whichever `from` the
 ## Tool surface
 
 ### Send
-`send_email` · `send_test_email` · `reply_to_email` · `reply_all_email` · `forward_email`
+`send_email` · `send_test_email` · `reply_to_email` · `reply_all_email` · `forward_email` · `respond_to_invite` (answer a calendar invitation)
 
 ### Drafts
 `create_draft` · `create_reply_draft` · `create_forward_draft` · `create_thread_reply_draft` · `list_drafts` · `list_remote_drafts` · `get_draft` · `update_draft` · `sync_draft_to_remote` · `send_draft` · `delete_draft`
@@ -544,7 +551,7 @@ With several accounts or a signature, the server sends from whichever `from` the
 `get_emails` · `get_email_by_id` · `count_messages` · `search_emails` · `search_indexed_emails` · `list_attachments` · `get_attachment_content` · `save_attachment` · `save_attachments`
 
 ### Triage
-`get_folders` · `sync_folders` · `get_labels` · `get_threads` · `get_thread_by_id` · `get_thread_brief` · `get_actionable_threads` · `get_inbox_digest` · `get_follow_up_candidates` · `find_document_threads` · `prepare_meeting_context` · `delete_thread` · `flag_thread` · `move_thread`
+`get_folders` · `sync_folders` · `get_labels` · `get_threads` · `get_thread_by_id` · `get_thread_brief` · `get_actionable_threads` · `get_inbox_digest` · `get_follow_up_candidates` · `set_reply_reminder` · `list_reply_reminders` · `cancel_reply_reminder` · `find_document_threads` · `prepare_meeting_context` · `delete_thread` · `flag_thread` · `move_thread`
 
 ### Actions
 `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`
@@ -643,7 +650,7 @@ Measured in October 2026 (v2.7.0) on a copy of the same ~57,000-message index. "
 - Defaults are bounded: `search_emails`/`search_indexed_emails` return 50 (pass `limit` for more), `list_drafts` 20, `list_scheduled_sends` 50 newest first. Each reports `hasMore`; page with `offset`.
 - Draft and queued-message bodies are shortened to a preview in list and update responses (`bodyTruncated`, `bodyLength`); use `get_draft` for one full draft. Attachment content is never inlined in a listing.
 - Large attachments: set `PROTONMAIL_ALLOW_FILE_DOWNLOAD_DIR` and pass `saveTo`, rather than raising `PROTONMAIL_MAX_INLINE_BYTES`.
-- **`PROTONMAIL_TOOL_TIER=core`** exposes 25 tools instead of 96: about 7k tokens of tool definitions instead of about 20k (roughly 65% less, reference tokenizer), paid on every conversation that loads the server.
+- **`PROTONMAIL_TOOL_TIER=core`** exposes 25 tools instead of 100: about 7k tokens of tool definitions instead of about 21k (roughly 67% less; the earlier measurement with a reference tokenizer, 7k against 20k for 96 tools, scaled by the 3.7% the four newest tool definitions add), paid on every conversation that loads the server.
 - Repeating an `update_draft` that changes nothing on a draft whose remote copy is already in sync does no store write and no IMAP upload. (A draft whose last sync failed, or that was edited with `syncToRemote:false`, still syncs.)
 
 **Working with drafts**

package/dist/cli.d.ts

@@ -15,6 +15,13 @@ interface CommandSpec {
     flags: string[];
 }
 export declare const COMMAND_SPECS: Record<string, CommandSpec>;
+export declare const COMPLETION_SHELLS: readonly ["zsh", "bash", "fish"];
+export declare function completionCommands(): Array<{
+    name: string;
+    description: string;
+    flags: string[];
+}>;
+export declare function completionScript(shell: string): string;
 export declare function commandHelpText(command: string): string | undefined;
 export declare function toolResultExitCode(toolName: string, result: Record<string, unknown>): number;
 interface ToolOnlyCommand {

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA4BA,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAiBD,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAM3C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAuD1D;AA0ID,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAOD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAkErD,CAAC;AAkBF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcnE;AAyKD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAY5F;AAk0CD,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IAIb,SAAS,CAAC,EAAE,MAAM,CAAC;IAMnB,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,eAAO,MAAM,kBAAkB,EAAE,eAAe,EA+D/C,CAAC;AA2EF,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA+N1C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA4BA,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAiBD,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAM3C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAuD1D;AA0ID,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAOD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAmErD,CAAC;AAoBF,eAAO,MAAM,iBAAiB,YAAI,KAAK,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC;AAGlE,wBAAgB,kBAAkB,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAQlG;AAID,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA+DtD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcnE;AAyKD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAY5F;AAk0CD,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IAIb,SAAS,CAAC,EAAE,MAAM,CAAC;IAMnB,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,eAAO,MAAM,kBAAkB,EAAE,eAAe,EAmE/C,CAAC;AA2EF,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAkO1C"}

package/dist/cli.js

@@ -226,6 +226,7 @@ const SEARCH_FLAGS = ["folder", "limit", "live", "sync", "label", "from", "to",
 const DRAFT_COPY_FLAGS = ["cc", "bcc", "notes"];
 const BULK_FILTER_FLAGS = ["from", "subject", "since", "before"];
 export const COMMAND_SPECS = {
+    completion: { usage: "completion <zsh|bash|fish>", description: "Print a shell completion script for the commands and their flags", flags: [] },
     help: { usage: "help [command]", description: "Show the command list, or the help for one command", flags: [] },
     version: { usage: "version", description: "Print the version and exit", flags: [] },
     "setup-claude-desktop": { usage: "setup-claude-desktop", description: "Run the Claude Desktop setup wizard (works from any install)", flags: [] },
@@ -308,6 +309,85 @@ function specForCommand(command) {
         flags: ["args", "args-file", ...fileFlag, ...(entry.boolFlags ?? [])],
     };
 }
+// Tab completion for the commands and flags above. The scripts are generated from the same tables the parser and
+// `--help` use, so they cannot drift from what the CLI accepts.
+export const COMPLETION_SHELLS = ["zsh", "bash", "fish"];
+const CLI_BINARIES = ["proton-mail-bridge-client", "proton-mail-bridge"];
+export function completionCommands() {
+    const names = [...new Set([...Object.keys(COMMAND_SPECS), ...TOOL_ONLY_COMMANDS.map((entry) => entry.command)])].sort();
+    return names.flatMap((name) => {
+        const spec = specForCommand(name);
+        if (!spec)
+            return [];
+        const description = spec.description.replace(/\s*\(MCP tool [a-z_]+\)\s*$/, "").replace(/\s+/g, " ").trim();
+        return [{ name, description, flags: [...new Set([...spec.flags, "json", "help"])].sort() }];
+    });
+}
+const shellQuote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+export function completionScript(shell) {
+    const commands = completionCommands();
+    if (shell === "bash") {
+        const cases = commands
+            .map((command) => `    ${command.name}) COMPREPLY=( $(compgen -W ${shellQuote(command.flags.map((flag) => `--${flag}`).join(" "))} -- "$cur") ) ;;`)
+            .join("\n");
+        return [
+            "# bash completion for proton-mail-bridge-client. Load it with:",
+            "#   source <(proton-mail-bridge-client completion bash)",
+            "_proton_mail_bridge_client() {",
+            '  local cur="${COMP_WORDS[COMP_CWORD]}"',
+            "  if [ \"$COMP_CWORD\" -eq 1 ]; then",
+            `    COMPREPLY=( $(compgen -W ${shellQuote(commands.map((command) => command.name).join(" "))} -- "$cur") )`,
+            "    return",
+            "  fi",
+            '  case "${COMP_WORDS[1]}" in',
+            cases,
+            "  esac",
+            "}",
+            ...CLI_BINARIES.map((binary) => `complete -F _proton_mail_bridge_client ${binary}`),
+            "",
+        ].join("\n");
+    }
+    if (shell === "zsh") {
+        const list = commands.map((command) => `    ${shellQuote(`${command.name}:${command.description.replace(/:/g, " -")}`)}`).join("\n");
+        const cases = commands
+            .map((command) => `    ${command.name}) _arguments ${command.flags.map((flag) => shellQuote(`--${flag}`)).join(" ")} ;;`)
+            .join("\n");
+        return [
+            `#compdef ${CLI_BINARIES.join(" ")}`,
+            "# zsh completion for proton-mail-bridge-client. Load it with:",
+            "#   source <(proton-mail-bridge-client completion zsh)   (after compinit)",
+            "_proton_mail_bridge_client() {",
+            "  local -a commands",
+            "  commands=(",
+            list,
+            "  )",
+            "  if (( CURRENT == 2 )); then",
+            "    _describe -t commands 'command' commands",
+            "    return",
+            "  fi",
+            '  case "$words[2]" in',
+            cases,
+            "  esac",
+            "}",
+            `compdef _proton_mail_bridge_client ${CLI_BINARIES.join(" ")}`,
+            "",
+        ].join("\n");
+    }
+    if (shell === "fish") {
+        const lines = [];
+        for (const binary of CLI_BINARIES) {
+            lines.push(`complete -c ${binary} -f`);
+            for (const command of commands) {
+                lines.push(`complete -c ${binary} -n '__fish_use_subcommand' -a ${command.name} -d ${shellQuote(command.description)}`);
+                for (const flag of command.flags) {
+                    lines.push(`complete -c ${binary} -n '__fish_seen_subcommand_from ${command.name}' -l ${flag}`);
+                }
+            }
+        }
+        return ["# fish completion for proton-mail-bridge-client. Load it with:", "#   proton-mail-bridge-client completion fish | source", ...lines, ""].join("\n");
+    }
+    throw new CliUsageError(`completion needs a shell: ${COMPLETION_SHELLS.join(", ")}.`);
+}
 export function commandHelpText(command) {
     const spec = specForCommand(command);
     if (!spec)
@@ -1733,6 +1813,10 @@ export const TOOL_ONLY_COMMANDS = [
     { command: "unsubscribe-info", tool: "get_unsubscribe_info", positionals: ["emailId"], help: "Read List-Unsubscribe details for a message" },
     { command: "unsubscribe-sender", tool: "unsubscribe_sender", positionals: ["emailId"], help: "Execute a mailto unsubscribe (--args '{\"confirmed\":true}' if required)" },
     { command: "reply-to-email", tool: "reply_to_email", positionals: ["emailId", "body"], help: "Immediately send a reply (full tool: attachments/dryRun via --args)" },
+    { command: "set-reply-reminder", tool: "set_reply_reminder", positionals: ["emailId"], help: "Remind me if nobody answers this message (--args '{\"afterDays\":5}')" },
+    { command: "list-reply-reminders", tool: "list_reply_reminders", positionals: [], help: "List reply reminders: waiting, due, answered" },
+    { command: "cancel-reply-reminder", tool: "cancel_reply_reminder", positionals: ["id"], help: "Delete a reply reminder" },
+    { command: "respond-to-invite", tool: "respond_to_invite", positionals: ["emailId", "response"], help: "Accept / decline / tentative a calendar invitation (--args '{\"dryRun\":true}' to preview)" },
     { command: "reply-all-email", tool: "reply_all_email", positionals: ["emailId", "body"], help: "Immediately reply to all recipients" },
     { command: "forward-email", tool: "forward_email", positionals: ["emailId", "to"], help: "Immediately forward a message, preserving attachments" },
     { command: "list-drafts", tool: "list_drafts", positionals: [], help: "List local drafts (tool form; see also `drafts`)" },
@@ -1875,6 +1959,9 @@ export async function main() {
         case "help":
             printCommandHelp(parsed.positionals[0]);
             return;
+        case "completion":
+            process.stdout.write(completionScript(parsed.positionals[0] ?? ""));
+            return;
         case "-v":
         case "version":
             process.stdout.write(`proton-mail-bridge-client ${await getPkgVersion()}\n`);