proton-mail-bridge-client 2.11.0 → 2.12.0

package/README.md

@@ -695,6 +695,7 @@ To check a real Bridge yourself, run the read-only smoke test: `PROTONMAIL_USERN
 - `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.
+- **Several clients at once.** Every MCP client starts its own server. Per data directory, only one of them runs the background sync and the IDLE watch (it holds `background-sync.lock`); the others serve tools from the index and take over when it exits. `get_runtime_status` shows `backgroundSync.leader`. A manual `sync_emails` / `run_background_sync` always runs.
 - Filters on the local index ignore case and accents, and match spelling variants: `Müller` finds `Mueller`, `lodz` finds `Łódź`, `strasse` finds `Straße`. Live `search_emails` and `count_messages` go through Bridge: a query with umlauts or other non-ASCII letters also matches the spelled-out form (`Müller` finds `Mueller`), but a plain ASCII query is sent as typed, so `Mueller` does not find `Müller` there. Use `search_indexed_emails` for that.
 - 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.

package/dist/cli.d.ts

@@ -24,6 +24,10 @@ export declare function completionCommands(): Array<{
 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;
+export declare function diagnoseConnectionFailure(reason: unknown): {
+    cause: string;
+    suggestion: string;
+} | undefined;
 interface ToolOnlyCommand {
     command: string;
     tool: string;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8BA,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,CAoErD,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;AAo0CD,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,CAqO1C;AA4ED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGzD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8BA,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,CAoErD,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;AAiND,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAiB5G;AAupCD,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,CAqO1C;AA4ED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGzD"}

package/dist/cli.js

@@ -8,7 +8,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { buildConfigFromEnv, createServer, withAudit } from "./index.js";
 import { isMainModule } from "./is-main.js";
-import { SimpleIMAPService } from "./services/simple-imap-service.js";
+import { isLikelyAuthenticationError, isLikelyConnectionError, isLikelyTlsMismatchError, SimpleIMAPService } from "./services/simple-imap-service.js";
 import { ensureDestructiveConfirmed, ensureEmailActionAllowed, ensureMailboxWriteAllowed, sanitizeRuntimeConfig } from "./utils/runtime-policy.js";
 import { isValidEmail, parseEmails } from "./utils/helpers.js";
 import { buildSchedule, defaultSchedulerSystem, findStableAlias, parseTimeOfDay, SCHEDULER_SYSTEMS } from "./utils/schedule-templates.js";
@@ -235,9 +235,9 @@ export const COMMAND_SPECS = {
     "setup-claude-desktop": { usage: "setup-claude-desktop", description: "Run the Claude Desktop setup wizard (works from any install)", flags: [] },
     claude: { usage: "claude <setup|install|check|update|doctor>", description: "Claude Desktop integration: setup wizard, install or update the runtime, check status (update is an alias for install, doctor for check)", flags: [] },
     status: { usage: "status", description: "Show local config, index, runtime, and Claude Desktop status", flags: [] },
-    doctor: { usage: "doctor", description: "Verify IMAP, SMTP, and Claude Desktop wiring (exits 1 when the check fails)", flags: [] },
+    doctor: { usage: "doctor [--account <slug|address>]", description: "Verify IMAP, SMTP, and Claude Desktop wiring for every account, or one (exits 1 when the check fails)", flags: ["account"] },
     "connection-status": { usage: "connection-status", description: "Show live IMAP/SMTP connectivity state (exits 1 when either is unreachable)", flags: [] },
-    "runtime-status": { usage: "runtime-status", description: "Show runtime policy and background sync state", flags: [] },
+    "runtime-status": { usage: "runtime-status [--account <slug|address>]", description: "Show runtime policy and background sync state, per account", flags: ["account"] },
     sync: { usage: "sync [--folder <name>] [--limit <n>] [--full]", description: "Refresh the local index from Proton Bridge", flags: ["folder", "limit", "full", "no-attachment-text"] },
     "index-status": { usage: "index-status", description: "Show local index health and freshness", flags: [] },
     folders: { usage: "folders", description: "List available folders from Proton Bridge", flags: [] },
@@ -655,9 +655,22 @@ async function withServices(run) {
         return await run({ config, ...services });
     }
     finally {
-        services.backgroundSyncService.stop();
-        await Promise.allSettled([services.imapService.disconnect(), services.smtpService.close()]);
+        for (const bundle of services.accountManager.all()) {
+            bundle.backgroundSyncService.stop();
+            await Promise.allSettled([bundle.imapService.disconnect(), bundle.smtpService.close()]);
+        }
+    }
+}
+// --account picks one account (slug or address); without it, every configured account.
+function selectAccountBundles(accountManager, parsed) {
+    const wanted = getStringFlag(parsed.flags, "account");
+    if (!wanted)
+        return accountManager.all();
+    const bundle = accountManager.byAddress(wanted) ?? accountManager.all().find((entry) => entry.account.slug === wanted);
+    if (!bundle) {
+        throw new CliUsageError(`Unknown account "${wanted}". Configured: ${accountManager.all().map((entry) => entry.account.slug).join(", ")}`);
     }
+    return [bundle];
 }
 async function syncIndex(context, input) {
     const snapshot = await context.imapService.collectEmailsForIndex({
@@ -740,41 +753,71 @@ async function runStatus(parsed) {
         process.stdout.write(wantJson ? json(result) : renderStatus(result));
     });
 }
+// Same classification as the run_doctor tool, so the CLI explains a failure instead of printing the raw error.
+export function diagnoseConnectionFailure(reason) {
+    if (isLikelyAuthenticationError(reason)) {
+        return {
+            cause: "authentication_failed",
+            suggestion: "PROTONMAIL_PASSWORD must be the Bridge password (Bridge app -> account -> Mailbox details), not your Proton account password.",
+        };
+    }
+    if (isLikelyTlsMismatchError(reason)) {
+        return {
+            cause: "tls_mismatch",
+            suggestion: "TLS handshake failed: PROTONMAIL_IMAP_SECURE / PROTONMAIL_SMTP_SECURE probably does not match the connection mode of that port in Bridge (implicit TLS vs STARTTLS).",
+        };
+    }
+    if (isLikelyConnectionError(reason)) {
+        return { cause: "bridge_unreachable", suggestion: "Bridge is not reachable: check that it is running and that the host and ports match Bridge's Mailbox details." };
+    }
+    return undefined;
+}
 async function runDoctor(parsed) {
     const wantJson = isTruthyFlag(parsed.flags.json);
-    await withServices(async ({ config, smtpService, imapService, localIndexService }) => {
-        const [claudeDesktop, index] = await Promise.all([
-            getClaudeDesktopInstallStatus(),
-            localIndexService.getStatus(),
-        ]);
-        let imapOk = false;
-        let smtpOk = false;
-        let folderCount = 0;
-        let error;
-        try {
-            await imapService.ping();
-            imapOk = true;
-            folderCount = (await imapService.getFolders(true)).length;
-            await smtpService.verifyConnection();
-            smtpOk = true;
-        }
-        catch (err) {
-            error = err instanceof Error ? err.message : String(err);
-        }
+    await withServices(async ({ accountManager }) => {
+        const bundles = selectAccountBundles(accountManager, parsed);
+        const checked = await Promise.all(bundles.map(async (bundle) => {
+            let imapOk = false;
+            let smtpOk = false;
+            let folderCount = 0;
+            let error;
+            let diagnosis;
+            try {
+                await bundle.imapService.ping();
+                imapOk = true;
+                folderCount = (await bundle.imapService.getFolders(true)).length;
+                await bundle.smtpService.verifyConnection();
+                smtpOk = true;
+            }
+            catch (err) {
+                error = err instanceof Error ? err.message : String(err);
+                diagnosis = diagnoseConnectionFailure(err);
+            }
+            return {
+                slug: bundle.account.slug,
+                account: bundle.config.smtp.username,
+                ok: imapOk && smtpOk,
+                imapOk,
+                smtpOk,
+                folderCount,
+                indexUpdatedAt: (await bundle.localIndexService.getStatus()).updatedAt,
+                error,
+                ...(diagnosis ? { cause: diagnosis.cause, suggestion: diagnosis.suggestion } : {}),
+            };
+        }));
+        const claudeDesktop = await getClaudeDesktopInstallStatus();
+        const { slug: _slug, ...firstFields } = checked[0];
         const result = {
-            ok: imapOk && smtpOk,
             // A stale/orphaned install elsewhere on disk (wrong path, old
             // version) looks identical to a fresh one on every other field
             // above — this is the field that actually distinguishes them.
             version: await getPkgVersion(),
             entrypoint: cliEntryPath(),
-            account: config.smtp.username,
-            imapOk,
-            smtpOk,
-            folderCount,
-            indexUpdatedAt: index.updatedAt,
+            ...firstFields,
+            // Top-level fields describe the first account shown; ok covers all of them.
+            ok: checked.every((entry) => entry.ok),
             claudeDesktopInstalled: claudeDesktop.installed,
-            error,
+            ...(checked.length > 1 ? { accounts: checked } : {}),
         };
         process.stdout.write(wantJson ? json(result) : `${result.ok ? "Doctor OK" : "Doctor failed"}\n${json(result)}`);
         if (!result.ok)
@@ -818,16 +861,23 @@ async function runConnectionStatus(parsed) {
 }
 async function runRuntimeStatus(parsed) {
     const wantJson = isTruthyFlag(parsed.flags.json);
-    await withServices(async ({ config, backgroundSyncService, draftStore, localIndexService }) => {
-        const result = {
-            account: config.smtp.username,
-            runtime: sanitizeRuntimeConfig(config.runtime),
-            backgroundSync: backgroundSyncService.getStatus(),
-            localIndex: await localIndexService.getStatus(),
+    await withServices(async ({ accountManager }) => {
+        const bundles = selectAccountBundles(accountManager, parsed);
+        const perAccount = await Promise.all(bundles.map(async (bundle) => ({
+            slug: bundle.account.slug,
+            account: bundle.config.smtp.username,
+            runtime: sanitizeRuntimeConfig(bundle.config.runtime),
+            backgroundSync: bundle.backgroundSyncService.getStatus(),
+            localIndex: await bundle.localIndexService.getStatus(),
             drafts: {
-                total: (await draftStore.listDrafts(true)).length,
-                active: (await draftStore.listDrafts(false)).length,
+                total: (await bundle.draftStore.listDrafts(true)).length,
+                active: (await bundle.draftStore.listDrafts(false)).length,
             },
+        })));
+        const { slug: _slug, ...firstFields } = perAccount[0];
+        const result = {
+            ...firstFields,
+            ...(perAccount.length > 1 ? { accounts: perAccount } : {}),
         };
         process.stdout.write(wantJson ? json(result) : `${JSON.stringify(result, null, 2)}\n`);
     });