proton-mail-bridge-client 1.11.1 → 1.14.0

package/README.md

@@ -7,104 +7,265 @@
   Bridge Client  ·  CLI + Claude Desktop MCP for Proton Mail
 ```
 
-# Proton Mail Bridge Client
+<div align="center">
 
-[![proton-mail-bridge-client MCP server](https://glama.ai/mcp/servers/googlarz/proton-mail-bridge-client/badges/card.svg)](https://glama.ai/mcp/servers/googlarz/proton-mail-bridge-client)
+[![npm version](https://img.shields.io/npm/v/proton-mail-bridge-client?color=%236d4aff&label=npm)](https://www.npmjs.com/package/proton-mail-bridge-client)
+[![CI](https://github.com/googlarz/proton-mail-bridge-client/actions/workflows/ci.yml/badge.svg)](https://github.com/googlarz/proton-mail-bridge-client/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet)](https://modelcontextprotocol.io)
+[![GitHub stars](https://img.shields.io/github/stars/googlarz/proton-mail-bridge-client?style=social)](https://github.com/googlarz/proton-mail-bridge-client)
+[![Last commit](https://img.shields.io/github/last-commit/googlarz/proton-mail-bridge-client?color=brightgreen&label=last%20commit)](https://github.com/googlarz/proton-mail-bridge-client/commits/main)
+[![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](https://github.com/googlarz/proton-mail-bridge-client)
+[![proton-mail-bridge-client MCP server](https://glama.ai/mcp/servers/googlarz/proton-mail-bridge-client/badges/score.svg)](https://glama.ai/mcp/servers/googlarz/proton-mail-bridge-client)
 
-A full-featured CLI and Claude Desktop MCP for Proton Mail, built on top of Proton Bridge.
+</div>
 
-## About
+---
 
-Proton Mail Bridge Client gives you two ways to use Proton Mail programmatically:
+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.
 
-**CLI** — a terminal client with complete parity to the MCP surface. Read, search, send, draft, archive, manage folders, triage threads, and run diagnostics — all from the command line. Body can be piped via stdin. Output is either human-readable or `--json`.
+## What you get
 
-**MCP server** — the same capabilities exposed as a Model Context Protocol server so Claude Desktop can read and manage your Proton Mail in any chat, on the same machine where Proton Bridge is running.
+- **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
+- **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
 
-Both surfaces share the same backend: Proton Bridge IMAP and SMTP, a local SQLite index, and an audit log. No hosted relay, no remote URL, no cloud dependency beyond your own Proton account.
+---
 
-## Why CLI?
+## Privacy model
 
-Most Proton Mail MCPs are MCP-only. This one ships a full CLI — the same 40+ commands, all in the terminal, no Claude required.
+Your emails travel: **Proton Mail → Proton Bridge (local) → this server (local) → your AI client**.
 
-**Pipe and script:**
+Nothing goes through a third-party email relay. Proton Bridge decrypts your mail locally; this server reads it over a local IMAP connection on `127.0.0.1`. The AI model (Claude Desktop, Cline, etc.) sees the email content you ask it to act on — that's the whole point — but no email leaves your machine except through your own Proton account when you send.
 
-```bash
-# Morning digest to a file
-proton-mail-bridge-client digest --json > ~/morning-mail.json
+If you use Claude Desktop with the default Anthropic API, conversation content (including email snippets) is sent to Anthropic per their [privacy policy](https://www.anthropic.com/privacy). If you self-host an LLM or use a local-only Claude setup, nothing leaves your machine at all.
 
-# Finance automation — pull every Stripe subject in seconds
-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"
-```
+## Prerequisites
+
+**1. Proton Bridge** — must be installed, signed in, and running.
+Download: [proton.me/mail/bridge](https://proton.me/mail/bridge)
 
-**Cron:**
+> **Bridge password vs Proton password:** Proton Bridge generates a separate local password that is *not* your Proton account password. Find it inside the Bridge app under **Account → Copy password** (or similar — exact label varies by Bridge version). You'll need this for setup.
+
+**2. Node.js 18 or later** — `node --version` to check.
+
+**3. Your Bridge credentials** — from the Bridge app:
+- IMAP host/port (default: `127.0.0.1:1143`)
+- SMTP host/port (default: `127.0.0.1:1025`)
+- Username (your Proton email address)
+- Bridge password (see note above)
+
+---
+
+## Install
+
+**npm (recommended):**
 
 ```bash
-# Scheduled digest every weekday at 8am
-0 8 * * 1-5 proton-mail-bridge-client digest >> ~/mail-log.txt
+npm install -g proton-mail-bridge-client
 ```
 
-**One-liners:**
+**Homebrew:**
 
 ```bash
-# Live watch: notify on any new mail from your bank
-proton-mail-bridge-client search --live --from bank.com
-
-# Count unread in INBOX
-proton-mail-bridge-client emails --folder INBOX --json | jq '[.[] | select(.isRead == false)] | length'
+brew tap googlarz/tap
+brew install proton-mail-bridge-client
 ```
 
-No other Proton Mail MCP has a CLI. If you want to automate mail outside of Claude, this is the only option.
+<details>
+<summary>Source install (development)</summary>
 
-## Prerequisites
+```bash
+git clone https://github.com/googlarz/proton-mail-bridge-client.git
+cd proton-mail-bridge-client
+npm install
+npm run build
+```
 
-- Node.js 18+
-- [Proton Bridge](https://proton.me/mail/bridge) installed and signed in
-- From Bridge: IMAP host/port, SMTP host/port, username, Bridge password
+The `proton-mail-bridge-client` binary is available inside the repo after build.
 
-Default local Bridge addresses: IMAP `127.0.0.1:1143`, SMTP `127.0.0.1:1025`
+</details>
 
-## Install
+---
+
+## Connect to Claude Desktop
 
-**From npm (recommended):**
+Run the guided setup wizard:
 
 ```bash
-npm install -g proton-mail-bridge-client
+proton-mail-bridge-client setup-claude-desktop
 ```
 
-**From Homebrew:**
+The wizard:
+- checks your local Bridge ports
+- asks for your Bridge username and Bridge password
+- writes the Claude Desktop MCP config entry
 
-```bash
-brew tap googlarz/tap
-brew install proton-mail-bridge-client
-```
+**After setup:** restart Claude Desktop, make sure Proton Bridge is open, then check **`+` → Connectors → proton-mail-bridge**.
 
-**Set up Claude Desktop** (interactive wizard, works from any install):
+### Updating
 
 ```bash
+npm update -g proton-mail-bridge-client
 proton-mail-bridge-client setup-claude-desktop
 ```
 
+### Manual config
+
+The wizard handles config automatically. If you need to set it up by hand, three credential methods are supported:
+
 <details>
-<summary>Development / source install</summary>
+<summary>Option 1 — Environment variables (simplest)</summary>
 
-> **Before running `npm run build`:** configure your credentials first — see [Environment](#environment) below.
+```json
+{
+  "mcpServers": {
+    "proton-mail-bridge": {
+      "command": "proton-mail-bridge-mcp",
+      "env": {
+        "PROTONMAIL_USERNAME": "you@proton.me",
+        "PROTONMAIL_PASSWORD": "your-bridge-password",
+        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
+        "PROTONMAIL_IMAP_PORT": "1143",
+        "PROTONMAIL_IMAP_SECURE": "false",
+        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
+        "PROTONMAIL_SMTP_PORT": "1025"
+      }
+    }
+  }
+}
+```
 
-```bash
-git clone https://github.com/googlarz/proton-mail-bridge-client.git
-cd proton-mail-bridge-client
-npm install
-npm run build
+</details>
+
+<details>
+<summary>Option 2 — File-based secrets (credentials in files, not config)</summary>
+
+```json
+{
+  "mcpServers": {
+    "proton-mail-bridge": {
+      "command": "proton-mail-bridge-mcp",
+      "env": {
+        "PROTONMAIL_USERNAME_FILE": "/path/to/username.txt",
+        "PROTONMAIL_PASSWORD_FILE": "/path/to/password.txt",
+        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
+        "PROTONMAIL_IMAP_PORT": "1143",
+        "PROTONMAIL_IMAP_SECURE": "false",
+        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
+        "PROTONMAIL_SMTP_PORT": "1025"
+      }
+    }
+  }
+}
 ```
 
-After install, the `proton-mail-bridge-client` (and `proton-mail-bridge`) binary is available from the repo.
+</details>
+
+<details>
+<summary>Option 3 — Command-based secrets (pass, gopass, or any secret manager)</summary>
+
+```json
+{
+  "mcpServers": {
+    "proton-mail-bridge": {
+      "command": "proton-mail-bridge-mcp",
+      "env": {
+        "PROTONMAIL_USERNAME_COMMAND": "pass proton/username",
+        "PROTONMAIL_PASSWORD_COMMAND": "pass proton/password",
+        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
+        "PROTONMAIL_IMAP_PORT": "1143",
+        "PROTONMAIL_IMAP_SECURE": "false",
+        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
+        "PROTONMAIL_SMTP_PORT": "1025"
+      }
+    }
+  }
+}
+```
 
 </details>
 
+---
+
+## Connect to Cline (VS Code)
+
+Install globally (`npm install -g proton-mail-bridge-client`), then open Cline's MCP settings:
+
+- VS Code → Cline extension panel → MCP servers icon → **Edit MCP Settings**
+- Or edit directly: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` (macOS)
+
+Add the server:
+
+```json
+{
+  "mcpServers": {
+    "proton-mail-bridge": {
+      "command": "proton-mail-bridge-mcp",
+      "env": {
+        "PROTONMAIL_USERNAME": "you@proton.me",
+        "PROTONMAIL_PASSWORD": "your-bridge-password",
+        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
+        "PROTONMAIL_IMAP_PORT": "1143",
+        "PROTONMAIL_IMAP_SECURE": "false",
+        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
+        "PROTONMAIL_SMTP_PORT": "1025"
+      }
+    }
+  }
+}
+```
+
+For file-based or command-based credentials, use the same `PROTONMAIL_USERNAME_FILE` / `PROTONMAIL_PASSWORD_COMMAND` pattern from the Claude Desktop manual config above.
+
+Reload the Cline extension after saving. Proton Mail tools will appear in Cline's tool list.
+
+---
+
+## Try it: example Claude prompts
+
+**Morning triage**
+> "Give me a digest of my inbox. Flag anything that needs a reply today and anything that looks like a bill or invoice."
+
+**Inbox zero**
+> "Go through my unread emails from the past 3 days. Archive newsletters, trash anything promotional, and tell me what's left that needs action."
+
+**Folder filing**
+> "Find all emails from stripe.com and move them to Folders/Receipts. Create the folder if it doesn't exist."
+
+**Meeting prep**
+> "I have a call with alice@example.com in an hour. Pull up our last 5 email threads and summarise the open items."
+
+**Draft review**
+> "Show me my drafts, pick the oldest one, and suggest a better subject line and closing paragraph."
+
+> **Tip:** When creating folders, use `Folders/Name` (not just `Name`) — that's the Proton Bridge namespace for real folders vs. labels.
+
+---
+
+## Recommended System Prompt
+
+Add this to Claude Desktop's system prompt (Settings → Claude Desktop → System Prompt) for safer defaults:
+
+```
+You have access to my Proton Mail inbox via the proton-mail-bridge tool.
+
+Rules:
+- Always use dryRun: true before any batch operation (batch_email_action, apply_thread_action).
+- Before calling send_email, reply_to_email, or forward_email, summarise what you are about to send and ask me to confirm.
+- Before calling delete_email, confirm with me — deletion is permanent.
+- Prefer create_draft over send_email when composing from scratch.
+- Use get_inbox_digest or get_actionable_threads as your starting point for triage sessions.
+```
+
+---
+
 ## CLI
 
 ```bash
@@ -203,23 +364,18 @@ proton-mail-bridge-client sync --folder INBOX --limit 150
 Run as a background daemon — sends a system notification (macOS / Linux) whenever new mail arrives:
 
 ```bash
-# Foreground (Ctrl+C to stop)
-proton-mail-bridge-client notify
-
-# Background (macOS / Linux)
-proton-mail-bridge-client notify &
-
-# Custom folder and idle timeout
-proton-mail-bridge-client notify --folder INBOX --timeout 60
+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 notification event is also written as a JSON line to stdout:
+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, no extra network requests between events. Reconnects automatically on transient errors.
+Uses IMAP IDLE — no polling between events. Reconnects automatically on transient errors.
 
 ### MCP tool passthrough
 
@@ -231,167 +387,86 @@ proton-mail-bridge-client tool get_connection_status --json
 proton-mail-bridge-client tool search_indexed_emails --args '{"query":"invoice","limit":3}'
 ```
 
-## Environment
-
-The CLI and MCP server both read the same environment variables:
-
-```bash
-export PROTONMAIL_USERNAME='you@proton.me'
-export PROTONMAIL_PASSWORD='your-bridge-password'
-export PROTONMAIL_IMAP_HOST='127.0.0.1'
-export PROTONMAIL_IMAP_PORT='1143'
-export PROTONMAIL_IMAP_SECURE='false'
-export PROTONMAIL_SMTP_HOST='127.0.0.1'
-export PROTONMAIL_SMTP_PORT='1025'
-export PROTONMAIL_DATA_DIR="$HOME/.proton-mail-bridge-client"
-```
-
-Optional secrets via file or command (avoids raw credentials in shell):
+### Pipe and script
 
 ```bash
-export PROTONMAIL_USERNAME_FILE='/path/to/user.txt'
-export PROTONMAIL_PASSWORD_FILE='/path/to/pass.txt'
-# or
-export PROTONMAIL_USERNAME_COMMAND='pass proton/username'
-export PROTONMAIL_PASSWORD_COMMAND='pass proton/password'
-```
-
-Full runtime flags:
+# Morning digest to a file
+proton-mail-bridge-client digest --json > ~/morning-mail.json
 
-```bash
-export PROTONMAIL_READ_ONLY='false'
-export PROTONMAIL_ALLOW_SEND='true'
-export PROTONMAIL_ALLOW_REMOTE_DRAFT_SYNC='true'
-export PROTONMAIL_ALLOWED_ACTIONS='mark_read,mark_unread,star,unstar,archive,trash,restore'
-export PROTONMAIL_CONFIRM_DESTRUCTIVE='false'
-export PROTONMAIL_AUTO_SYNC='true'
-export PROTONMAIL_STARTUP_SYNC='true'
-export PROTONMAIL_SYNC_INTERVAL_MINUTES='5'
-export PROTONMAIL_IDLE_WATCH='true'
-export PROTONMAIL_IDLE_MAX_SECONDS='30'
-```
+# Pull every email from a domain
+proton-mail-bridge-client search --from stripe.com --json | jq '.[].subject'
 
-## Claude Desktop Setup
+# 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"
 
-To use Proton Mail Bridge Client with Claude Desktop, run the guided wizard:
+# Scheduled digest every weekday at 8am (cron)
+0 8 * * 1-5 proton-mail-bridge-client digest >> ~/mail-log.txt
 
-```bash
-npm run setup:claude-desktop
+# Count unread in INBOX
+proton-mail-bridge-client emails --folder INBOX --json | jq '[.[] | select(.isRead == false)] | length'
 ```
 
-This will:
-
-- check your local Bridge ports
-- ask for your Bridge username and password
-- build the project
-- install a stable machine-wide runtime
-- write the Claude Desktop MCP config entry
+---
 
-After setup: restart Claude Desktop, keep Proton Bridge open, then check `+` → `Connectors` → `proton-mail-bridge`.
+## Safety controls
 
-The runtime is installed at:
-
-- macOS: `~/Library/Application Support/Proton Mail Bridge Client`
-- Linux: `~/.local/share/proton-mail-bridge-client`
-- Windows: `%APPDATA%\Proton Mail Bridge Client`
-
-### Updating
+All flags work in both the MCP server and CLI:
 
 ```bash
-git pull
-npm run update:claude-desktop
+PROTONMAIL_TOOL_TIER=core            # expose 20 core tools instead of all 76 — 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
+PROTONMAIL_ALLOWED_ACTIONS='mark_read,archive,trash'  # per-action allowlist
 ```
 
-### Manual Claude Desktop config
-
-Three credential methods are supported. Use whichever fits your setup:
+`batch_email_action` and `apply_thread_action` both support `dryRun: true` regardless of the above flags.
 
-**Option 1 — Environment variables (simplest):**
+---
 
-```json
-{
-  "mcpServers": {
-    "proton-mail-bridge": {
-      "command": "node",
-      "args": ["/path/to/runtime/dist/index.js"],
-      "cwd": "/path/to/runtime",
-      "env": {
-        "PROTONMAIL_USERNAME": "you@proton.me",
-        "PROTONMAIL_PASSWORD": "your-bridge-password",
-        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
-        "PROTONMAIL_IMAP_PORT": "1143",
-        "PROTONMAIL_IMAP_SECURE": "false",
-        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
-        "PROTONMAIL_SMTP_PORT": "1025"
-      }
-    }
-  }
-}
-```
+## Environment reference
 
-**Option 2 — File-based secrets (credentials in files, not config):**
-
-```json
-{
-  "mcpServers": {
-    "proton-mail-bridge": {
-      "command": "node",
-      "args": ["/path/to/runtime/dist/index.js"],
-      "cwd": "/path/to/runtime",
-      "env": {
-        "PROTONMAIL_USERNAME_FILE": "/path/to/username.txt",
-        "PROTONMAIL_PASSWORD_FILE": "/path/to/password.txt",
-        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
-        "PROTONMAIL_IMAP_PORT": "1143",
-        "PROTONMAIL_IMAP_SECURE": "false",
-        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
-        "PROTONMAIL_SMTP_PORT": "1025"
-      }
-    }
-  }
-}
-```
-
-**Option 3 — Command-based secrets (recommended for `pass`, `gopass`, or any secret manager):**
-
-```json
-{
-  "mcpServers": {
-    "proton-mail-bridge": {
-      "command": "node",
-      "args": ["/path/to/runtime/dist/index.js"],
-      "cwd": "/path/to/runtime",
-      "env": {
-        "PROTONMAIL_USERNAME_COMMAND": "pass proton/username",
-        "PROTONMAIL_PASSWORD_COMMAND": "pass proton/password",
-        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
-        "PROTONMAIL_IMAP_PORT": "1143",
-        "PROTONMAIL_IMAP_SECURE": "false",
-        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
-        "PROTONMAIL_SMTP_PORT": "1025"
-      }
-    }
-  }
-}
+```bash
+# Credentials (required)
+PROTONMAIL_USERNAME='you@proton.me'
+PROTONMAIL_PASSWORD='your-bridge-password'   # Bridge password, not Proton account password
+PROTONMAIL_IMAP_HOST='127.0.0.1'
+PROTONMAIL_IMAP_PORT='1143'
+PROTONMAIL_IMAP_SECURE='false'
+PROTONMAIL_SMTP_HOST='127.0.0.1'
+PROTONMAIL_SMTP_PORT='1025'
+
+# Secrets via file or command (avoids raw credentials in config)
+PROTONMAIL_USERNAME_FILE='/path/to/user.txt'
+PROTONMAIL_PASSWORD_FILE='/path/to/pass.txt'
+PROTONMAIL_USERNAME_COMMAND='pass proton/username'
+PROTONMAIL_PASSWORD_COMMAND='pass proton/password'
+
+# Storage
+PROTONMAIL_DATA_DIR="$HOME/.proton-mail-bridge-client"
+
+# Tools
+PROTONMAIL_TOOL_TIER='full'          # 'core' exposes 20 essential tools (saves context window); 'full' exposes all 76
+
+# Safety
+PROTONMAIL_READ_ONLY='false'
+PROTONMAIL_ALLOW_SEND='true'
+PROTONMAIL_ALLOW_REMOTE_DRAFT_SYNC='true'
+PROTONMAIL_ALLOWED_ACTIONS='mark_read,mark_unread,star,unstar,archive,trash,restore'
+PROTONMAIL_CONFIRM_DESTRUCTIVE='false'
+
+# Sync
+PROTONMAIL_AUTO_SYNC='true'
+PROTONMAIL_STARTUP_SYNC='true'
+PROTONMAIL_SYNC_INTERVAL_MINUTES='5'
+PROTONMAIL_IDLE_WATCH='true'
+PROTONMAIL_IDLE_MAX_SECONDS='30'
 ```
 
-### macOS note
+---
 
-On macOS, `better-sqlite3` must be a native binary built for the current machine. The installer handles this automatically. If you restore from another environment or see a native-module crash, run `npm run update:claude-desktop`.
-
-## Trust & Safety
-
-- Runs entirely locally — no hosted relay, no remote URL.
-- Talks to Proton Mail only through Proton Bridge on your own machine.
-- `PROTONMAIL_READ_ONLY=true` disables all write operations.
-- `PROTONMAIL_ALLOW_SEND=false` disables SMTP sends without affecting other writes.
-- `PROTONMAIL_ALLOWED_ACTIONS` controls which mailbox mutations are permitted.
-- `PROTONMAIL_CONFIRM_DESTRUCTIVE=true` requires `confirmed: true` on `send_email`, `reply_to_email`, `forward_email`, `send_draft`, and `delete_email` — Claude will pause and ask before executing irreversible operations.
-- `batch_email_action` and `apply_thread_action` both support `dryRun: true`.
-- Supports `*_FILE` and `*_COMMAND` secrets so raw credentials never appear in config or shell history.
-- System folders (INBOX, Sent, Trash, Spam, Archive, All Mail) are guarded against accidental deletion.
-
-## Compared With Claude's Native Gmail Connector
+## Compared with Claude's native Gmail connector
 
 | Capability | Gmail connector | Proton Mail Bridge Client |
 |---|---|---|
@@ -399,88 +474,99 @@ On macOS, `better-sqlite3` must be a native binary built for the current machine
 | Search and read | Native Claude UX | IMAP + local index |
 | Send email | No | Yes |
 | Draft workflows | Better first-party UX | Full control incl. remote draft sync |
-| Attachment content | Limited | Fetch and save |
+| Attachment content | Limited | Fetch and save to disk |
 | Mailbox actions | Limited | Full (star, move, archive, trash, restore, delete, batch) |
 | Folder management | No | Yes (create, rename, delete) |
 | CLI access | No | Full parity with MCP |
-| Original message links | Better | MCP resource links only |
-| Native threads/labels | Gmail-native | Reconstructed from IMAP |
+| Privacy | Google-hosted | Proton E2E encryption, local Bridge |
 
-## Recommended System Prompt
+---
 
-Add this to Claude Desktop's system prompt (Settings → Claude Desktop → System Prompt) for safer default behaviour:
+## Tool surface
 
-```
-You have access to my Proton Mail inbox via the proton-mail-bridge tool.
+### Send
+`send_email` · `send_test_email` · `reply_to_email` · `reply_all_email` · `forward_email`
 
-Rules:
-- Always use dryRun: true before any batch operation (batch_email_action, apply_thread_action).
-- Before calling send_email, reply_to_email, or forward_email, summarise what you are about to send and ask me to confirm.
-- Before calling delete_email, confirm with me — deletion is permanent.
-- Prefer create_draft over send_email when composing from scratch.
-- Use get_inbox_digest or get_actionable_threads as your starting point for triage sessions.
-```
+### 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`
+
+### Read
+`get_emails` · `get_email_by_id` · `count_messages` · `search_emails` · `search_indexed_emails` · `list_attachments` · `get_attachment_content` · `save_attachment` · `save_attachments`
 
-## Example Claude Workflows
+### 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`
 
-Once connected, ask Claude anything. Some prompts that work well:
+### 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`
 
-**Morning triage**
-> "Give me a digest of my inbox. Flag anything that needs a reply today and anything that looks like a bill or invoice."
+### Folder management
+`create_folder` · `rename_folder` · `delete_folder` · `create_label`
 
-**Inbox zero session**
-> "Go through my unread emails from the past 3 days. Archive newsletters, trash anything promotional, and tell me what's left that needs action."
+### Analytics
+`get_email_stats` · `get_email_analytics` · `get_contacts` · `get_volume_trends` · `folder_stats` · `top_senders`
 
-**Folder filing**
-> "Find all emails from stripe.com and move them to Folders/Receipts. Create the folder if it doesn't exist."
+### Diagnostics
+`get_connection_status` · `get_runtime_status` · `run_doctor` · `get_audit_logs` · `run_background_sync` · `wait_for_mailbox_changes` · `sync_emails` · `get_index_status` · `clear_cache` · `clear_index` · `get_logs`
 
-**Meeting prep**
-> "I have a call with alice@example.com in an hour. Pull up our last 5 email threads and summarise the open items."
+---
 
-**Draft review**
-> "Show me my drafts, pick the oldest one, and suggest a better subject line and closing paragraph."
+## Using it as a library
 
-> **Tip:** If Claude needs to create a folder before moving emails, remind it to use `Folders/Name` (not just `Name`) — that's the Proton Bridge namespace for real folders vs. labels.
+Beyond the CLI and MCP server, the underlying service classes are importable directly:
 
-## Tool Surface
+```ts
+import { SimpleIMAPService, SMTPService } from "proton-mail-bridge-client/services";
 
-### Send
-`send_email` · `send_test_email` · `reply_to_email` · `forward_email`
+const imapService = new SimpleIMAPService(config, logger);
+const smtpService = new SMTPService(config);
+```
 
-### 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`
+`proton-mail-bridge-client/services` has no side effects on import — unlike the package's
+main entry point, which also self-starts the MCP server when run directly. Also exported:
+all shared types (`ProtonMailConfig`, `EmailSummary`, `EmailDetail`, …), `planFolderSync`,
+`isLikelyAuthenticationError`, and `sanitizeHeader`.
 
-### Read
-`get_emails` · `get_email_by_id` · `search_emails` · `list_attachments` · `get_attachment_content` · `save_attachments` · `save_attachment`
+---
 
-### 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`
+## Operational notes
 
-### Actions
-`mark_email_read` · `star_email` · `move_email` · `archive_email` · `trash_email` · `restore_email` · `delete_email` · `batch_email_action` · `apply_thread_action`
+- `get_emails` and `search_emails` return a composite `emailId` — use it for all subsequent reads and actions.
+- `search_indexed_emails` supports `from:`, `to:`, `subject:`, `label:`, `domain:` shortcuts.
+- The local index lives at `PROTONMAIL_DATA_DIR/mail-index.sqlite`. Background sync and IMAP IDLE keep it warm.
+- Audit logs live at `PROTONMAIL_DATA_DIR/audit.log`.
+- Draft sync is best-effort — the local draft is always preserved even if remote sync fails.
+- System folders (INBOX, Sent, Trash, Spam, Archive, All Mail) are guarded against accidental deletion.
 
-### Folder management
-`create_folder` · `rename_folder` · `delete_folder`
+---
 
-### Analytics
-`get_email_stats` · `get_email_analytics` · `get_contacts` · `get_volume_trends`
+## Troubleshooting
 
-### Diagnostics
-`get_connection_status` · `get_runtime_status` · `run_doctor` · `get_audit_logs` · `run_background_sync` · `wait_for_mailbox_changes` · `sync_emails` · `get_index_status` · `search_indexed_emails` · `clear_cache` · `clear_index` · `get_logs`
+**"Wrong password" or connection refused**
+Make sure you're using the **Bridge password**, not your Proton account password. Find it in the Bridge app under Account → Copy password. Bridge must be running before the MCP server or CLI can connect.
 
-## Operational Notes
+**macOS native module crash after update**
+`better-sqlite3` is a native binary built for your machine. After a major Node.js upgrade or environment change, rebuild it:
+```bash
+proton-mail-bridge-client setup-claude-desktop
+```
+This reinstalls the runtime and rebuilds native modules in place.
 
-- `get_emails` and `search_emails` return a composite `emailId` — use it for reads and actions.
-- The local index lives at `PROTONMAIL_DATA_DIR/mail-index.sqlite`.
-- Audit logs live at `PROTONMAIL_DATA_DIR/audit.log`.
-- Background sync and IMAP IDLE keep the index warm but depend on Bridge staying up.
-- `search_indexed_emails` supports `from:`, `to:`, `subject:`, `label:`, `domain:` shortcuts.
-- Draft sync is best-effort — local draft is always preserved even if remote sync fails.
+**Claude can't see the connector**
+After changing the MCP config, restart Claude Desktop fully (not just reload). Then check **`+` → Connectors → proton-mail-bridge**. If it's not there, run `proton-mail-bridge-client doctor` to validate the connection.
+
+**Folder not found when moving email**
+Use `Folders/Name` for real folders (e.g., `Folders/Receipts`), not just `Name`. Labels and folders share the same namespace in Proton Bridge but are structurally different.
+
+---
 
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
+## Contributing
+
+Bug reports and pull requests welcome: [github.com/googlarz/proton-mail-bridge-client/issues](https://github.com/googlarz/proton-mail-bridge-client/issues)
+
 ## License
 
 MIT