airmail-mcp 1.0.13 → 1.0.19

package/README.md

@@ -12,41 +12,100 @@ This is a lightweight bridge that connects AI clients to Airmail's built-in MCP
 
 ## Installation
 
-### Claude Desktop (MCPB extension)
+### Published npm package
 
-Install from the [Claude MCP Directory](https://claude.ai/mcp) or download the latest `.mcpb` file from [Releases](https://github.com/Airmail/airmail-mcp/releases) and double-click to install.
+`npx` installs and runs the published package automatically. Users do not need to clone this repository or run `npm install`.
 
-### Claude Desktop (manual)
+```bash
+codex mcp remove airmail
+codex mcp add airmail -- npx -y airmail-mcp
+```
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Use this for normal installs after the desired version has been published to npm.
+
+### Local development build
+
+Use this when testing changes from a local checkout before publishing a new npm version.
+
+```bash
+git clone https://github.com/Airmail/airmail-mcp.git
+cd airmail-mcp
+npm install
+npm run build
+```
+
+Then point your MCP client at the compiled local bridge. Do not commit a machine-specific path in shared docs or config examples; use your own checkout path.
+
+**Codex CLI / Codex Desktop**:
+
+```bash
+codex mcp remove airmail
+codex mcp add airmail -- node "$(pwd)/dist/index.js"
+```
+
+**Claude Desktop JSON only**:
 
 ```json
 {
   "mcpServers": {
     "airmail": {
-      "command": "npx",
-      "args": ["-y", "airmail-mcp"]
+      "command": "node",
+      "args": ["/absolute/path/to/airmail-mcp/dist/index.js"]
     }
   }
 }
 ```
 
-The auth token is read automatically from the macOS Keychain. If you set `AIRMAIL_MCP_TOKEN`, the Keychain is not accessed:
+You can also smoke-test the local stdio bridge without installing it into a client:
+
+```bash
+printf '%s\n' \
+'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-05","capabilities":{},"clientInfo":{"name":"Airmail MCP Local Test","version":"1.0"}}}' \
+'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_inbox","arguments":{"limit":3}}}' \
+| node dist/index.js
+```
+
+Restart the MCP client after changing its config. On first connection, Airmail shows an authorization prompt; click **Allow**.
+
+Important: `npx -y airmail-mcp` installs the published npm package, not this local checkout. Use the local `node "$(pwd)/dist/index.js"` command until the package is published.
+
+### GitHub development install
+
+Use this when you want the MCP client to install from GitHub instead of a local checkout. This tests pushed GitHub code, not uncommitted local edits.
+
+```bash
+codex mcp remove airmail
+codex mcp add airmail -- npx -y github:Airmail/airmail-mcp#main
+```
+
+Replace `main` with a branch name, tag, or commit SHA when testing a specific version:
+
+```bash
+codex mcp add airmail -- npx -y github:Airmail/airmail-mcp#branch-name
+```
+
+### Claude Desktop (MCPB extension)
+
+Install from the [Claude MCP Directory](https://claude.ai/mcp) or download the latest `.mcpb` file from [Releases](https://github.com/Airmail/airmail-mcp/releases) and double-click to install.
+
+### Claude Desktop (manual)
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "airmail": {
       "command": "npx",
-      "args": ["-y", "airmail-mcp"],
-      "env": {
-        "AIRMAIL_MCP_TOKEN": "your-token-here"
-      }
+      "args": ["-y", "airmail-mcp"]
     }
   }
 }
 ```
 
+On first use, Airmail shows a pairing prompt and issues a per-client token for this bridge. By default that token stays only in bridge memory for the current session.
+
 ### Claude Code
 
 ```bash
@@ -112,17 +171,11 @@ Add to `.vscode/mcp.json` in your project:
 
 ## Authentication
 
-The bridge reads the auth token automatically from the macOS Keychain — no configuration needed. When macOS prompts for Keychain access, click **Always Allow** so it won't ask again.
-
-If you set `AIRMAIL_MCP_TOKEN`, the Keychain is skipped entirely:
-
-```bash
-export AIRMAIL_MCP_TOKEN="your-token-here"
-```
+On first use, the bridge asks Airmail to pair this MCP client. Airmail shows an authorization prompt, then returns a per-client token. By default, the bridge keeps that token only in memory for the current process.
 
-To find your token: open Airmail → **Preferences → MCP** → copy the **Auth Token**.
+Airmail MCP does not use a global auth token. Access is pairing-only and can be revoked per client in Airmail's MCP Permissions tab.
 
-## Tools (97)
+## Tools (101)
 
 ### Email (core)
 `list_accounts` · `list_folders` · `list_messages` · `get_message` · `list_inbox` · `list_starred` · `list_sent` · `list_trash` · `list_spam` · `search_messages` · `fetch_message_body` · `list_attachments` · `get_attachment` · `get_unread_counts` · `search_contacts` · `get_draft` · `delete_draft` · `get_message_thread` · `list_windows` · `export_eml`
@@ -178,38 +231,37 @@ Tools are organized into capability groups that can be enabled or disabled at ru
 
 | Group | Tools | Default |
 |-------|-------|---------|
-| mail | Email read, actions, compose | Always on |
-| profile | User profile, triage, behavior stats | On |
-| folders | Folder CRUD | On |
-| semantic | Semantic search, index status | On |
-| calendar | Calendar events, reminders | On |
-| contacts | Address book | On |
-| preferences | App preferences | On |
-| rules | Email rules | On |
-| lists | VIP & blocked senders | On |
-| smartfolders | Smart folder CRUD | On |
-| signatures | Email signatures | On |
-| aliases | Email aliases | On |
-| accountsettings | Per-account settings, vacation | On |
-
+| mail | read, action, compose | Always on |
+| profile | user profile & behavior | On |
+| folders | folder create/rename/delete | On |
+| semantic | semantic search & index | On |
+| calendar | calendar & reminder | On |
+| contacts | address book | On |
+| preferences | app preferences read/write | On |
+| rules | email rules CRUD | On |
+| lists | VIP & blocked sender lists | On |
+| smartfolders | smart folder CRUD | On |
+| signatures | email signature CRUD | On |
+| aliases | email alias CRUD | On |
+| accountsettings | per-account settings & vacation | On |
 To enable all groups, ask the AI to call `manage_capabilities` with `enable: ["preferences", "rules", "lists", "smartfolders", "signatures", "aliases", "accountsettings"]`.
 
 ## Deep links
 
-MCP tool responses include `airmail://` deep links that open Airmail directly to the relevant content.
+MCP tool responses include `airmailmcp://` deep links that open Airmail directly to the relevant content.
 
 | Command | URL | Description |
 |---------|-----|-------------|
-| `message` | `airmail://message?mail=...&messageid=...` | Select message in main window |
-| `open` | `airmail://open?mail=...&messageid=...` | Open message in reader window |
-| `compose` | `airmail://compose?to=...&subject=...` | Open composer with pre-filled content |
-| `reply` | `airmail://reply?mail=...&messageid=...` | Reply to a message |
-| `draft` | `airmail://draft?mail=...&messageid=...` | Open draft in composer |
-| `archive` | `airmail://archive?mail=...&messageid=...` | Archive a message |
-| `delete` | `airmail://delete?mail=...&messageid=...` | Move message to trash |
-| `view` | `airmail://view?mail=...&folder=...` | Navigate to account/folder |
-| `attachment` | `airmail://attachment?mail=...&messageid=...&index=0` | Open an attachment |
-| `settings` | `airmail://settings?pref=mcp_server` | Open Preferences pane |
+| `message` | `airmailmcp://message?mail=...&messageid=...` | Select message in main window |
+| `open` | `airmailmcp://open?mail=...&messageid=...` | Open message in reader window |
+| `compose` | `airmailmcp://compose?to=...&subject=...` | Open composer with pre-filled content |
+| `reply` | `airmailmcp://reply?mail=...&messageid=...` | Reply to a message |
+| `draft` | `airmailmcp://draft?mail=...&messageid=...` | Open draft in composer |
+| `archive` | `airmailmcp://archive?mail=...&messageid=...` | Archive a message |
+| `delete` | `airmailmcp://delete?mail=...&messageid=...` | Move message to trash |
+| `view` | `airmailmcp://view?mail=...&folder=...` | Navigate to account/folder |
+| `attachment` | `airmailmcp://attachment?mail=...&messageid=...&index=0` | Open an attachment |
+| `settings` | `airmailmcp://settings?pref=mcp_server` | Open Preferences pane |
 
 ## How it works
 
@@ -223,14 +275,16 @@ This package is a thin transport bridge. All tool logic runs inside Airmail's na
 2. Forwards them via HTTP POST to Airmail's local MCP server
 3. Writes responses back to stdout
 
-If Airmail is not running, the bridge will attempt to launch it automatically.
+If Airmail is not running, the bridge exits with a clear error by default. Set
+`AIRMAIL_MCP_AUTO_LAUNCH=1` if you want the bridge to open Airmail automatically.
 
 ## Environment variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `AIRMAIL_MCP_TOKEN` | Auth token (optional — automatically read from macOS Keychain if not set) | — |
+| `AIRMAIL_MCP_REMEMBER_CLIENT_TOKEN` | Set to `1` to persist the bridge's per-client token in Keychain service `com.airmail.mcp.client`. | — |
 | `AIRMAIL_MCP_PORT` | MCP server port | `9876` |
+| `AIRMAIL_MCP_AUTO_LAUNCH` | Set to `1`/`true` to launch Airmail when the local MCP server is not reachable | `0` |
 
 ## Development
 

package/dist/index.js

@@ -11,6 +11,7 @@
  * collect all data before the FIN arrives.
  */
 import { execFileSync, spawnSync } from "child_process";
+import { createHash } from "crypto";
 import { readFileSync, writeSync } from "fs";
 import * as net from "net";
 import { dirname, join } from "path";
@@ -19,6 +20,10 @@ import { fileURLToPath } from "url";
 // Configuration
 // ---------------------------------------------------------------------------
 const AIRMAIL_HOST = "127.0.0.1";
+function envFlag(name) {
+    const value = (process.env[name] ?? "").trim().toLowerCase();
+    return value === "1" || value === "true" || value === "yes" || value === "on";
+}
 const AIRMAIL_PORT = (() => {
     const p = parseInt(process.env.AIRMAIL_MCP_PORT ?? "9876", 10);
     if (isNaN(p) || p < 1 || p > 65535) {
@@ -41,12 +46,17 @@ const VERSION = (() => {
     }
 })();
 let currentToken = "";
+let clientTokenPromise = null;
 const RETRY_DELAY_MS = 2000;
 const MAX_LAUNCH_RETRIES = 5;
 const REQUEST_TIMEOUT_MS = 120_000;
 const MAX_STDIN_BUFFER = 10 * 1024 * 1024; // 10 MB — matches server limit
+const REMEMBER_CLIENT_TOKEN = /^(1|true|yes)$/i.test(process.env.AIRMAIL_MCP_REMEMBER_CLIENT_TOKEN ?? "");
+const AUTO_LAUNCH_AIRMAIL = envFlag("AIRMAIL_MCP_AUTO_LAUNCH");
 /** Resolve parent process code signing Team ID (macOS only). */
 let parentCodeSignTeamID = null;
+let parentPhysicalIdentity = null;
+let parentBundleIdentifier = null;
 function resolveParentCodeSign() {
     try {
         const ppid = process.ppid;
@@ -60,12 +70,18 @@ function resolveParentCodeSign() {
         if (appIdx !== -1) {
             appPath = parentPath.slice(0, appIdx + 4);
         }
+        parentPhysicalIdentity = appIdx !== -1 ? `app:${appPath}` : `path:${parentPath}`;
         // codesign writes everything to stderr — use spawnSync to capture it
         const result = spawnSync("codesign", ["-dv", "--verbose=2", appPath], {
             encoding: "utf-8",
             stdio: ["pipe", "pipe", "pipe"],
         });
         const output = (result.stdout || "") + (result.stderr || "");
+        const identifierMatch = output.match(/Identifier=(\S+)/);
+        if (identifierMatch) {
+            parentBundleIdentifier = identifierMatch[1];
+            log(`Parent identity: ${parentBundleIdentifier} (${parentPhysicalIdentity})`);
+        }
         const match = output.match(/TeamIdentifier=(\S+)/);
         if (match && match[1] !== "not" && match[1] !== "not set") {
             parentCodeSignTeamID = match[1];
@@ -90,26 +106,57 @@ function log(msg) {
 function sanitizeHeaderValue(value) {
     return value.replace(/[\r\n]/g, "");
 }
-function readTokenFromKeychain() {
+function splitClientIdentity(clientName) {
+    const idx = clientName.indexOf("/");
+    if (idx === -1) {
+        return { name: clientName || "airmail-mcp", version: VERSION };
+    }
+    const name = clientName.slice(0, idx) || "airmail-mcp";
+    const version = clientName.slice(idx + 1) || VERSION;
+    return { name, version };
+}
+function canonicalClientName(clientName) {
+    return splitClientIdentity(clientName).name;
+}
+function clientTokenAccount(clientName) {
+    const identity = parentPhysicalIdentity ?? "unknown";
+    const hash = createHash("sha256").update(`${canonicalClientName(clientName)}|${identity}`).digest("hex").slice(0, 24);
+    return `airmail-mcp:${hash}`;
+}
+function readClientToken(clientName) {
     try {
-        const token = execFileSync("security", [
+        return execFileSync("security", [
             "find-generic-password",
-            "-s", "com.airmail.mcp",
-            "-a", "com.airmail.mcp.token",
+            "-s", "com.airmail.mcp.client",
+            "-a", clientTokenAccount(clientName),
             "-w",
         ], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-        if (token) {
-            log("Auth token read from macOS Keychain.");
-        }
-        return token;
     }
     catch {
-        log("Could not read auth token from macOS Keychain. " +
-            "macOS may prompt you to approve Keychain access — click \"Always Allow\" to avoid this next time. " +
-            "Alternatively, set the AIRMAIL_MCP_TOKEN environment variable.");
         return "";
     }
 }
+function saveClientToken(clientName, token) {
+    execFileSync("security", [
+        "add-generic-password",
+        "-U",
+        "-s", "com.airmail.mcp.client",
+        "-a", clientTokenAccount(clientName),
+        "-w", token,
+    ], { stdio: ["pipe", "pipe", "pipe"] });
+}
+function deleteClientToken(clientName) {
+    try {
+        execFileSync("security", [
+            "delete-generic-password",
+            "-s", "com.airmail.mcp.client",
+            "-a", clientTokenAccount(clientName),
+        ], { stdio: ["pipe", "pipe", "pipe"] });
+    }
+    catch {
+        // Missing token is fine.
+    }
+}
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
@@ -132,7 +179,12 @@ function ping() {
 async function ensureAirmailRunning() {
     if (await ping())
         return;
-    log("Airmail MCP server not reachable, launching Airmail...");
+    if (!AUTO_LAUNCH_AIRMAIL) {
+        log("Airmail MCP server is not reachable. Open Airmail and enable MCP in Preferences, " +
+            "or set AIRMAIL_MCP_AUTO_LAUNCH=1 to let the bridge launch Airmail.");
+        process.exit(1);
+    }
+    log("Airmail MCP server not reachable, launching Airmail because AIRMAIL_MCP_AUTO_LAUNCH=1...");
     try {
         execFileSync("open", ["-a", "Airmail"], { stdio: "ignore" });
     }
@@ -299,6 +351,12 @@ function forward(body, clientName, token, hasId) {
                 reqHeaders += `Authorization: Bearer ${sanitizeHeaderValue(token)}\r\n`;
             }
             reqHeaders += `X-MCP-Client: ${safeClient}\r\n`;
+            if (parentPhysicalIdentity) {
+                reqHeaders += `X-MCP-Physical-Identity: ${sanitizeHeaderValue(parentPhysicalIdentity)}\r\n`;
+            }
+            if (parentBundleIdentifier) {
+                reqHeaders += `X-MCP-Bundle-ID: ${sanitizeHeaderValue(parentBundleIdentifier)}\r\n`;
+            }
             if (parentCodeSignTeamID) {
                 reqHeaders += `X-MCP-CodeSign: ${sanitizeHeaderValue(parentCodeSignTeamID)}\r\n`;
             }
@@ -312,6 +370,114 @@ function forward(body, clientName, token, hasId) {
         sock.on("close", () => finish());
     });
 }
+async function pairClient(clientName) {
+    if (!parentPhysicalIdentity) {
+        throw new Error("Cannot pair without a stable parent process identity.");
+    }
+    const client = splitClientIdentity(clientName);
+    const body = JSON.stringify({
+        client_name: client.name,
+        client_version: client.version,
+        physical_identity: parentPhysicalIdentity,
+        team_id: parentCodeSignTeamID ?? "",
+    });
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                sock.destroy();
+                reject(new Error("Pairing timed out"));
+            }
+        }, REQUEST_TIMEOUT_MS);
+        function finish(err) {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            settled = true;
+            if (err && chunks.length === 0) {
+                reject(err);
+                return;
+            }
+            const parsed = parseHttpResponse(Buffer.concat(chunks));
+            if (!parsed) {
+                reject(new Error("Malformed pairing response from Airmail"));
+                return;
+            }
+            if (parsed.statusCode >= 400) {
+                reject(new Error(`Pairing failed (HTTP ${parsed.statusCode}): ${parsed.body.slice(0, 200)}`));
+                return;
+            }
+            try {
+                const json = JSON.parse(parsed.body);
+                if (!json.client_token) {
+                    reject(new Error("Pairing response did not include a client token"));
+                    return;
+                }
+                resolve(json.client_token);
+            }
+            catch {
+                reject(new Error("Pairing response was not JSON"));
+            }
+        }
+        const sock = net.createConnection({ host: AIRMAIL_HOST, port: AIRMAIL_PORT }, () => {
+            const bodyBuf = Buffer.from(body, "utf-8");
+            let reqHeaders = `POST /mcp/pair HTTP/1.1\r\n`;
+            reqHeaders += `Host: ${AIRMAIL_HOST}:${AIRMAIL_PORT}\r\n`;
+            reqHeaders += `Content-Type: application/json\r\n`;
+            reqHeaders += `Content-Length: ${bodyBuf.length}\r\n`;
+            reqHeaders += `Accept: application/json\r\n`;
+            reqHeaders += `Connection: close\r\n`;
+            reqHeaders += `User-Agent: airmail-mcp/${VERSION}\r\n`;
+            reqHeaders += `X-MCP-Client: ${sanitizeHeaderValue(client.name)}\r\n`;
+            reqHeaders += `X-MCP-Physical-Identity: ${sanitizeHeaderValue(parentPhysicalIdentity ?? "")}\r\n`;
+            if (parentCodeSignTeamID) {
+                reqHeaders += `X-MCP-CodeSign: ${sanitizeHeaderValue(parentCodeSignTeamID)}\r\n`;
+            }
+            reqHeaders += `\r\n`;
+            sock.write(Buffer.concat([Buffer.from(reqHeaders), bodyBuf]));
+        });
+        sock.on("data", (chunk) => chunks.push(chunk));
+        sock.on("end", () => finish());
+        sock.on("error", (err) => finish(err));
+        sock.on("close", () => finish());
+    });
+}
+async function ensureClientToken(clientName) {
+    if (currentToken)
+        return;
+    if (clientTokenPromise) {
+        await clientTokenPromise;
+        return;
+    }
+    clientTokenPromise = (async () => {
+        if (REMEMBER_CLIENT_TOKEN) {
+            const storedToken = readClientToken(clientName);
+            if (storedToken) {
+                currentToken = storedToken;
+                log("Client token loaded from bridge Keychain.");
+                return;
+            }
+        }
+        log("No client token found; requesting pairing approval from Airmail.");
+        const token = await pairClient(clientName);
+        currentToken = token;
+        if (REMEMBER_CLIENT_TOKEN) {
+            saveClientToken(clientName, token);
+            log("Client token saved to bridge Keychain.");
+        }
+        else {
+            log("Client token kept in memory for this bridge session.");
+        }
+    })();
+    try {
+        await clientTokenPromise;
+    }
+    finally {
+        clientTokenPromise = null;
+    }
+}
 // ---------------------------------------------------------------------------
 // stdio ↔ HTTP bridge
 // ---------------------------------------------------------------------------
@@ -328,7 +494,7 @@ async function processMessage(line) {
     }
     catch {
         log(`Invalid JSON: ${line.slice(0, 200)}`);
-        return;
+        return false;
     }
     const hasId = parsed.id !== undefined;
     // Extract client identity from initialize for X-MCP-Client header
@@ -339,36 +505,36 @@ async function processMessage(line) {
         }
     }
     try {
-        const response = await forward(line, resolvedClientName, currentToken, hasId);
+        const authClientName = canonicalClientName(resolvedClientName);
+        await ensureClientToken(authClientName);
+        const response = await forward(line, authClientName, currentToken, hasId);
         if (response) {
             process.stdout.write(response + "\n");
         }
+        return true;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        // Re-read token from Keychain on 401 and retry once
+        // Client token may have been revoked or bound to an old identity; re-pair once.
         if (msg.includes("HTTP 401")) {
-            if (!process.env.AIRMAIL_MCP_TOKEN) {
-                const newToken = readTokenFromKeychain();
-                if (newToken && newToken !== currentToken) {
-                    log("Token rotated in Keychain, retrying with new token.");
-                    currentToken = newToken;
-                    try {
-                        const response = await forward(line, resolvedClientName, currentToken, hasId);
-                        if (response) {
-                            process.stdout.write(response + "\n");
-                        }
-                        return;
-                    }
-                    catch {
-                        // Fall through to error handling
-                    }
+            const authClientName = canonicalClientName(resolvedClientName);
+            if (REMEMBER_CLIENT_TOKEN) {
+                deleteClientToken(authClientName);
+            }
+            currentToken = "";
+            try {
+                await ensureClientToken(authClientName);
+                const response = await forward(line, authClientName, currentToken, hasId);
+                if (response) {
+                    process.stdout.write(response + "\n");
                 }
+                return true;
             }
-            log("Authentication failed (HTTP 401). The auth token is missing or invalid.\n" +
-                "  \u2192 Open Airmail \u2192 Preferences \u2192 MCP and copy the current Auth Token\n" +
-                "  \u2192 Set it as: export AIRMAIL_MCP_TOKEN=\"your-token-here\"\n" +
-                "  \u2192 Or approve the macOS Keychain access prompt if it appears.");
+            catch {
+                // Fall through to error handling
+            }
+            log("Authentication failed (HTTP 401). The client pairing token is missing, invalid, or revoked.\n" +
+                "  \u2192 Approve the Airmail pairing prompt, or revoke the client in Airmail Preferences > MCP > Permissions and pair again.");
         }
         if (hasId) {
             // Sanitize error message — don't forward raw server responses that may contain tokens
@@ -381,6 +547,7 @@ async function processMessage(line) {
         else {
             log(`Notification error: ${msg}`);
         }
+        return false;
     }
 }
 async function main() {
@@ -389,32 +556,10 @@ async function main() {
         log("Airmail MCP is macOS-only.");
         process.exit(1);
     }
-    // Resolve auth token — done inside main() so logs are captured
-    const envToken = (process.env.AIRMAIL_MCP_TOKEN ?? "").trim();
-    // Skip env var if empty or unresolved template placeholder
-    const isValidEnvToken = envToken.length > 0
-        && !envToken.startsWith("${")
-        && envToken !== "undefined"
-        && envToken !== "null";
-    if (isValidEnvToken) {
-        currentToken = envToken;
-        log(`Auth token provided via AIRMAIL_MCP_TOKEN (${envToken.length} chars).`);
-    }
-    else {
-        if (envToken)
-            log(`AIRMAIL_MCP_TOKEN ignored (placeholder: "${envToken.slice(0, 20)}...").`);
-        log("Trying macOS Keychain...");
-        currentToken = readTokenFromKeychain();
-    }
-    if (!currentToken) {
-        log("WARNING: no auth token found. Requests will fail with 401.\n" +
-            "  1. Open Airmail \u2192 Preferences \u2192 MCP and copy the Auth Token\n" +
-            "  2. Set it as: export AIRMAIL_MCP_TOKEN=\"your-token-here\"\n" +
-            "  Or approve the macOS Keychain prompt when it appears.");
-    }
     resolveParentCodeSign();
+    log(`Bridge will use per-client pairing (${REMEMBER_CLIENT_TOKEN ? "remembered Keychain token" : "memory-only token"}).`);
     await ensureAirmailRunning();
-    log(`Bridge ready \u2014 Airmail MCP at ${AIRMAIL_HOST}:${AIRMAIL_PORT} (token: ${currentToken ? "present" : "MISSING"})`);
+    log(`Bridge ready \u2014 Airmail MCP at ${AIRMAIL_HOST}:${AIRMAIL_PORT} (pairing mode)`);
     // Handle stdout errors (broken pipe)
     process.stdout.on("error", (err) => {
         if (err.code === "EPIPE") {
@@ -487,7 +632,9 @@ async function main() {
                 }
                 if (parsed.method === "initialize") {
                     const p = processMessage(line)
-                        .then(() => {
+                        .then((ok) => {
+                        if (!ok)
+                            throw new Error("initialize failed");
                         initialized = true;
                         // Flush queued messages
                         for (const queued of pendingAfterInit) {

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "airmail-mcp",
   "display_name": "Airmail",
-  "version": "1.0.0",
+  "version": "1.0.16",
   "description": "Manage emails, calendars, contacts, and more from Claude using Airmail's MCP server.",
   "long_description": "Airmail MCP connects Claude to the Airmail email client for macOS. Read, search, compose, and organize emails. Manage calendars and reminders. Search contacts. The bridge connects locally to Airmail on your Mac. Data retrieved by AI tools is processed by your chosen AI provider.",
   "author": {
@@ -27,8 +27,9 @@
         "${__dirname}/dist/index.js"
       ],
       "env": {
-        "AIRMAIL_MCP_TOKEN": "${user_config.auth_token}",
-        "AIRMAIL_MCP_PORT": "${user_config.port}"
+        "AIRMAIL_MCP_PORT": "${user_config.port}",
+        "AIRMAIL_MCP_REMEMBER_CLIENT_TOKEN": "${user_config.remember_client_token}",
+        "AIRMAIL_MCP_AUTO_LAUNCH": "${user_config.auto_launch}"
       }
     }
   },
@@ -38,6 +39,10 @@
       "name": "manage_capabilities",
       "description": "Enable/disable tool groups to manage context."
     },
+    {
+      "name": "start_convo",
+      "description": "Start a new conversation session and get a convo_id for request correlation."
+    },
     {
       "name": "get_account_settings",
       "description": "Get per-account settings."
@@ -362,6 +367,14 @@
       "name": "export_eml",
       "description": "Export message as .eml (RFC 822) file saved to disk (returns file_path)."
     },
+    {
+      "name": "list_operations",
+      "description": "List current email operations (move, copy, delete, send, etc.) with their status (planned, executing, executed, failed, canceled, reverted)."
+    },
+    {
+      "name": "list_activity",
+      "description": "List current email connections and sync activity."
+    },
     {
       "name": "semantic_search",
       "description": "Search by meaning via vector embeddings (macOS 14+)."
@@ -370,6 +383,10 @@
       "name": "semantic_index_status",
       "description": "Check/trigger semantic index."
     },
+    {
+      "name": "get_navigation_link",
+      "description": "Get an airmailmcp:// deep link to navigate the user to a specific part of Airmail."
+    },
     {
       "name": "list_rules",
       "description": "List all email rules with name, guid, enabled, conditions/actions summary, direction."
@@ -434,19 +451,25 @@
   ],
   "license": "MIT",
   "user_config": {
-    "auth_token": {
-      "type": "string",
-      "title": "Auth Token",
-      "description": "Bearer token from Airmail Preferences > MCP. If not set, the bridge will try to read it from the macOS Keychain (requires user approval).",
-      "sensitive": true,
-      "required": false
-    },
     "port": {
       "type": "string",
       "title": "MCP Server Port",
       "description": "Port number for Airmail's local MCP server. Only change if you modified the default port in Airmail.",
       "required": false,
       "default": "9876"
+    },
+    "remember_client_token": {
+      "type": "string",
+      "title": "Remember Client Token",
+      "description": "Set to 1 to persist the bridge's per-client pairing token in Keychain. Leave empty for memory-only tokens.",
+      "required": false
+    },
+    "auto_launch": {
+      "type": "string",
+      "title": "Auto-launch Airmail",
+      "description": "Set to 1 to let the bridge open Airmail when the local MCP server is not reachable.",
+      "required": false,
+      "default": "0"
     }
   },
   "compatibility": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airmail-mcp",
-  "version": "1.0.13",
+  "version": "1.0.19",
   "mcpName": "io.github.airmail/airmail-mcp",
   "description": "Manage emails, calendars, contacts, and more from Claude using Airmail's MCP server.",
   "main": "dist/index.js",
@@ -18,6 +18,7 @@
     "build": "tsc",
     "watch": "tsc --watch",
     "sync-tools": "node scripts/sync-tools.mjs",
+    "prepare": "npm run build",
     "prepublishOnly": "npm run sync-tools && npm run build"
   },
   "keywords": [