airmail-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Airmail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# Airmail MCP
+
+MCP server for [Airmail](https://airmailapp.com) — manage emails, calendars, contacts, and more from Claude.
+
+This is a lightweight bridge that connects Claude Desktop and Claude Code to Airmail's built-in MCP server. The bridge connects locally to Airmail on your Mac. Data retrieved by AI tools is processed by your chosen AI provider.
+
+## Requirements
+
+- macOS 13+
+- [Airmail](https://airmailapp.com) installed with MCP enabled (Preferences → MCP)
+- Node.js 18+
+
+## Installation
+
+### 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"]
+    }
+  }
+}
+```
+
+The auth token is read automatically from the macOS Keychain. If you set `AIRMAIL_MCP_TOKEN`, the Keychain is not accessed:
+
+```json
+{
+  "mcpServers": {
+    "airmail": {
+      "command": "npx",
+      "args": ["-y", "airmail-mcp"],
+      "env": {
+        "AIRMAIL_MCP_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio airmail -- npx -y airmail-mcp
+```
+
+## 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"
+```
+
+To find your token: open Airmail → **Preferences → MCP** → copy the **Auth Token**.
+
+## Tools (89)
+
+### 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`
+
+### Actions
+`mark_messages` · `archive_messages` · `trash_messages` · `move_messages` · `copy_messages` · `snooze_messages` · `add_to_list` · `delete_messages` · `empty_folder` · `refresh_inbox` · `enable_disable_account` · `share_icloud`
+
+### Compose
+`compose_email` · `reply_to_message` · `forward_message` · `quick_reply` · `send_email` · `save_as_draft` · `list_drafts`
+
+### Folders
+`create_folder` · `rename_folder` · `delete_folder`
+
+### Semantic Search
+`semantic_search` · `semantic_index_status`
+
+### Profile & Triage
+`analyze_email_history` · `batch_triage_inbox` · `get_user_profile` · `update_user_profile` · `suggest_folder` · `get_behavior_stats`
+
+### Calendar & Reminders
+`list_calendars` · `list_events` · `get_event` · `create_event` · `update_event` · `delete_event` · `list_reminders` · `create_reminder` · `complete_reminder` · `delete_reminder`
+
+### Contacts
+`list_contacts_book` · `get_contact` · `search_contacts_book` · `create_contact` · `update_contact` · `delete_contact` · `list_contact_groups`
+
+### VIP & Blocked Lists
+`list_vips` · `add_vip` · `remove_vip` · `list_blocked` · `add_blocked` · `remove_blocked`
+
+### Rules
+`list_rules` · `get_rule` · `create_rule` · `delete_rule` · `toggle_rule`
+
+### Signatures
+`list_signatures` · `create_signature` · `update_signature` · `delete_signature`
+
+### Smart Folders
+`list_smart_folders` · `create_smart_folder` · `update_smart_folder` · `delete_smart_folder`
+
+### Preferences
+`get_preferences` · `set_preferences`
+
+### Meta
+`manage_capabilities` — enable/disable tool groups to reduce context usage
+
+## How it works
+
+```
+Claude ←stdio→ airmail-mcp (Node.js) ←HTTP→ Airmail.app (localhost:9876)
+```
+
+This package is a thin transport bridge. All tool logic runs inside Airmail's native Swift MCP server. The bridge:
+
+1. Reads JSON-RPC messages from stdin
+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.
+
+## Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AIRMAIL_MCP_TOKEN` | Auth token (optional — automatically read from macOS Keychain if not set) | — |
+| `AIRMAIL_MCP_PORT` | MCP server port | `9876` |
+
+## Development
+
+```bash
+git clone https://github.com/Airmail/airmail-mcp.git
+cd airmail-mcp
+npm install
+npm run build
+```
+
+### Sync tools from Airmail source
+
+```bash
+npm run sync-tools          # reads Swift source, updates manifest.json
+```
+
+### Build .mcpb extension
+
+```bash
+npx @anthropic-ai/mcpb pack .
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Airmail MCP — Desktop Extension
+ *
+ * stdio↔HTTP bridge connecting Claude Desktop / Claude Code to Airmail's
+ * built-in MCP server on localhost.
+ *
+ * Uses raw TCP sockets instead of Node.js http module because Airmail's
+ * NWListener closes the connection immediately after sending — the http
+ * module can miss the response body ("socket hang up"). Raw sockets
+ * collect all data before the FIN arrives.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+/**
+ * Airmail MCP — Desktop Extension
+ *
+ * stdio↔HTTP bridge connecting Claude Desktop / Claude Code to Airmail's
+ * built-in MCP server on localhost.
+ *
+ * Uses raw TCP sockets instead of Node.js http module because Airmail's
+ * NWListener closes the connection immediately after sending — the http
+ * module can miss the response body ("socket hang up"). Raw sockets
+ * collect all data before the FIN arrives.
+ */
+import { execFileSync, spawnSync } from "child_process";
+import { writeSync } from "fs";
+import * as net from "net";
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const AIRMAIL_HOST = "127.0.0.1";
+const AIRMAIL_PORT = (() => {
+    const p = parseInt(process.env.AIRMAIL_MCP_PORT ?? "9876", 10);
+    if (isNaN(p) || p < 1 || p > 65535) {
+        try {
+            writeSync(2, `[airmail-mcp] Invalid AIRMAIL_MCP_PORT: "${process.env.AIRMAIL_MCP_PORT}". Must be 1-65535.\n`);
+        }
+        catch { /* fd closed */ }
+        process.exit(1);
+    }
+    return p;
+})();
+const AIRMAIL_PATH = "/mcp";
+const VERSION = "1.0.0";
+let currentToken = "";
+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
+/** Resolve parent process code signing Team ID (macOS only). */
+let parentCodeSignTeamID = null;
+function resolveParentCodeSign() {
+    try {
+        const ppid = process.ppid;
+        // Get parent executable path — ppid is always numeric, safe for arg
+        const parentPath = execFileSync("ps", ["-p", String(ppid), "-o", "comm="], { encoding: "utf-8" }).trim();
+        if (!parentPath)
+            return;
+        // Walk up to find .app bundle (if any)
+        let appPath = parentPath;
+        const appIdx = parentPath.indexOf(".app/");
+        if (appIdx !== -1) {
+            appPath = parentPath.slice(0, appIdx + 4);
+        }
+        // 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 match = output.match(/TeamIdentifier=(\S+)/);
+        if (match && match[1] !== "not" && match[1] !== "not set") {
+            parentCodeSignTeamID = match[1];
+            log(`Parent code sign: Team ID ${parentCodeSignTeamID}`);
+        }
+    }
+    catch {
+        // Not code-signed or codesign not available — leave as null
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function log(msg) {
+    const line = `${new Date().toISOString()} [airmail-mcp] ${msg}\n`;
+    try {
+        writeSync(2, line);
+    }
+    catch { /* fd closed or unavailable */ }
+}
+/** Sanitize a string for use in an HTTP header value (strip CR/LF). */
+function sanitizeHeaderValue(value) {
+    return value.replace(/[\r\n]/g, "");
+}
+function readTokenFromKeychain() {
+    try {
+        const token = execFileSync("security", [
+            "find-generic-password",
+            "-s", "com.airmail.mcp",
+            "-a", "com.airmail.mcp.token",
+            "-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 sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function ping() {
+    return new Promise((resolve) => {
+        let settled = false;
+        function settle(v) { if (!settled) {
+            settled = true;
+            resolve(v);
+        } }
+        const sock = net.createConnection({ host: AIRMAIL_HOST, port: AIRMAIL_PORT }, () => {
+            sock.destroy();
+            settle(true);
+        });
+        sock.setTimeout(3000);
+        sock.on("error", () => settle(false));
+        sock.on("timeout", () => { sock.destroy(); settle(false); });
+    });
+}
+async function ensureAirmailRunning() {
+    if (await ping())
+        return;
+    log("Airmail MCP server not reachable, launching Airmail...");
+    try {
+        execFileSync("open", ["-a", "Airmail"], { stdio: "ignore" });
+    }
+    catch {
+        log("Could not launch Airmail. Is it installed?");
+        process.exit(1);
+    }
+    for (let i = 0; i < MAX_LAUNCH_RETRIES; i++) {
+        await sleep(RETRY_DELAY_MS);
+        if (await ping()) {
+            log("Airmail MCP server is ready.");
+            return;
+        }
+    }
+    log("Airmail launched but MCP server not available. Enable MCP in Airmail Preferences.");
+    process.exit(1);
+}
+const HEADER_SEPARATOR = Buffer.from("\r\n\r\n");
+const CRLF = Buffer.from("\r\n");
+/** Parse raw HTTP response bytes into status, headers, and body. Handles chunked TE. */
+function parseHttpResponse(raw) {
+    const headerEnd = raw.indexOf(HEADER_SEPARATOR);
+    if (headerEnd === -1)
+        return null;
+    // Headers are always ASCII-safe
+    const headerPart = raw.subarray(0, headerEnd).toString("utf-8");
+    let bodyBuf = raw.subarray(headerEnd + 4);
+    // Status line
+    const statusMatch = headerPart.match(/^HTTP\/\d\.\d\s+(\d+)/);
+    const statusCode = statusMatch ? parseInt(statusMatch[1], 10) : 0;
+    // Parse headers
+    const headers = {};
+    for (const line of headerPart.split("\r\n").slice(1)) {
+        const colon = line.indexOf(":");
+        if (colon !== -1) {
+            headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+        }
+    }
+    // Decode chunked transfer encoding (byte-level)
+    if (headers["transfer-encoding"]?.toLowerCase() === "chunked") {
+        bodyBuf = decodeChunked(bodyBuf);
+    }
+    // Validate Content-Length if present
+    const contentLength = headers["content-length"];
+    if (contentLength && !headers["transfer-encoding"]) {
+        const expected = parseInt(contentLength, 10);
+        if (!isNaN(expected) && bodyBuf.length < expected) {
+            return null; // Incomplete response
+        }
+    }
+    return { statusCode, headers, body: bodyBuf.toString("utf-8").trim() };
+}
+/** Decode a chunked HTTP body. Operates on Buffer for byte-correct slicing. */
+function decodeChunked(raw) {
+    const parts = [];
+    let pos = 0;
+    while (pos < raw.length) {
+        const lineEnd = raw.indexOf(CRLF, pos);
+        if (lineEnd === -1)
+            break;
+        // Chunk size line — parseInt stops at non-hex chars (handles chunk extensions per RFC 7230)
+        const sizeStr = raw.subarray(pos, lineEnd).toString("ascii").trim();
+        const size = parseInt(sizeStr, 16);
+        if (isNaN(size) || size === 0)
+            break;
+        const chunkStart = lineEnd + 2;
+        if (chunkStart + size > raw.length)
+            break; // Incomplete chunk
+        parts.push(raw.subarray(chunkStart, chunkStart + size));
+        pos = chunkStart + size + 2; // skip chunk data + \r\n
+    }
+    return Buffer.concat(parts);
+}
+/** Settle a forward() promise from parsed HTTP response or raw chunks. */
+function settleFromChunks(chunks, hasId, resolve, reject) {
+    if (chunks.length === 0) {
+        if (hasId) {
+            reject(new Error("Empty response from Airmail"));
+        }
+        else {
+            resolve("");
+        }
+        return;
+    }
+    const raw = Buffer.concat(chunks);
+    const parsed = parseHttpResponse(raw);
+    if (!parsed) {
+        if (hasId) {
+            reject(new Error("Incomplete or malformed HTTP response from Airmail"));
+        }
+        else {
+            resolve("");
+        }
+        return;
+    }
+    if (parsed.statusCode === 202) {
+        resolve("");
+        return;
+    }
+    if (parsed.statusCode >= 400) {
+        // Truncate body in error message to avoid leaking sensitive data
+        const safeBody = parsed.body.length > 200 ? parsed.body.slice(0, 200) + "..." : parsed.body;
+        reject(new Error(`Airmail HTTP ${parsed.statusCode}: ${safeBody}`));
+        return;
+    }
+    resolve(parsed.body);
+}
+// ---------------------------------------------------------------------------
+// Raw TCP HTTP forwarding
+// ---------------------------------------------------------------------------
+/**
+ * Send an HTTP POST via raw TCP socket and return the response body.
+ *
+ * Airmail's NWListener calls connection.cancel() in the send completion handler,
+ * which means the TCP FIN can arrive before Node.js http module finishes parsing.
+ * Using raw sockets, we collect all data until the connection closes, then parse
+ * the HTTP response ourselves.
+ */
+function forward(body, clientName, token, hasId) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                sock.destroy();
+                reject(new Error("Request timed out"));
+            }
+        }, REQUEST_TIMEOUT_MS);
+        function finish(err) {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            settled = true;
+            if (err && chunks.length === 0) {
+                reject(err);
+                return;
+            }
+            // If we have an error but also data, the connection may have closed
+            // after sending a complete response (expected with NWListener).
+            // Only trust the data if it parses as valid HTTP.
+            if (err && chunks.length > 0) {
+                const raw = Buffer.concat(chunks);
+                const parsed = parseHttpResponse(raw);
+                if (!parsed) {
+                    reject(new Error(`Connection error with partial response: ${err.message}`));
+                    return;
+                }
+            }
+            settleFromChunks(chunks, hasId, resolve, reject);
+        }
+        const sock = net.createConnection({ host: AIRMAIL_HOST, port: AIRMAIL_PORT }, () => {
+            // Build and send raw HTTP request as a single write
+            const bodyBuf = Buffer.from(body, "utf-8");
+            const safeClient = sanitizeHeaderValue(clientName);
+            let reqHeaders = `POST ${AIRMAIL_PATH} 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/1.0\r\n`;
+            if (token) {
+                reqHeaders += `Authorization: Bearer ${token}\r\n`;
+            }
+            reqHeaders += `X-MCP-Client: ${safeClient}\r\n`;
+            if (parentCodeSignTeamID) {
+                reqHeaders += `X-MCP-CodeSign: ${sanitizeHeaderValue(parentCodeSignTeamID)}\r\n`;
+            }
+            reqHeaders += `\r\n`;
+            // Single atomic write to avoid backpressure issues
+            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());
+    });
+}
+// ---------------------------------------------------------------------------
+// stdio ↔ HTTP bridge
+// ---------------------------------------------------------------------------
+/** Client identity for X-MCP-Client header. Updated from initialize clientInfo. */
+let resolvedClientName = "airmail-mcp/1.0";
+/** Whether initialize has been sent and completed. */
+let initialized = false;
+/** Queue of messages waiting for initialize to complete. */
+let pendingAfterInit = [];
+async function processMessage(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        log(`Invalid JSON: ${line.slice(0, 200)}`);
+        return;
+    }
+    const hasId = parsed.id !== undefined;
+    // Extract client identity from initialize for X-MCP-Client header
+    if (parsed.method === "initialize" && parsed.params) {
+        const ci = parsed.params.clientInfo;
+        if (ci?.name) {
+            resolvedClientName = ci.version ? `${ci.name}/${ci.version}` : ci.name;
+        }
+    }
+    try {
+        const response = await forward(line, resolvedClientName, currentToken, hasId);
+        if (response) {
+            process.stdout.write(response + "\n");
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Re-read token from Keychain on 401 and retry 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
+                    }
+                }
+            }
+            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.");
+        }
+        if (hasId) {
+            // Sanitize error message — don't forward raw server responses that may contain tokens
+            const safeMsg = msg.length > 300 ? msg.slice(0, 300) + "..." : msg;
+            process.stdout.write(JSON.stringify({
+                jsonrpc: "2.0", id: parsed.id,
+                error: { code: -32000, message: safeMsg },
+            }) + "\n");
+        }
+        else {
+            log(`Notification error: ${msg}`);
+        }
+    }
+}
+async function main() {
+    log(`airmail-mcp v${VERSION} starting (Node.js ${process.version}, pid ${process.pid})`);
+    if (process.platform !== "darwin") {
+        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();
+    await ensureAirmailRunning();
+    log(`Bridge ready \u2014 Airmail MCP at ${AIRMAIL_HOST}:${AIRMAIL_PORT} (token: ${currentToken ? "present" : "MISSING"})`);
+    // Handle stdout errors (broken pipe)
+    process.stdout.on("error", (err) => {
+        if (err.code === "EPIPE") {
+            process.exit(0);
+        }
+        log(`stdout error: ${err.message}`);
+        process.exit(1);
+    });
+    // Graceful shutdown — drain inflight requests before exiting
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        if (inflight.size === 0) {
+            process.exit(0);
+        }
+        log(`Shutting down, waiting for ${inflight.size} inflight request(s)...`);
+        // Force exit after 5 seconds if inflight requests don't complete
+        setTimeout(() => { process.exit(0); }, 5000).unref();
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    process.on("SIGHUP", shutdown);
+    let buffer = "";
+    let stdinClosed = false;
+    const inflight = new Set();
+    function enqueue(line) {
+        const p = processMessage(line).catch((err) => log(`Error: ${err}`));
+        inflight.add(p);
+        p.finally(() => {
+            inflight.delete(p);
+            if ((stdinClosed || shuttingDown) && inflight.size === 0)
+                process.exit(0);
+        });
+    }
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => {
+        if (shuttingDown)
+            return;
+        buffer += chunk;
+        // Protect against unbounded memory growth — drop only the oversized portion,
+        // preserving any trailing partial line for framing continuity
+        if (buffer.length > MAX_STDIN_BUFFER) {
+            log("stdin buffer exceeded 10 MB, dropping accumulated data.");
+            const lastNewline = buffer.lastIndexOf("\n");
+            if (lastNewline !== -1) {
+                // Keep the trailing partial line so framing stays aligned
+                buffer = buffer.slice(lastNewline + 1);
+            }
+            else {
+                buffer = "";
+            }
+            return;
+        }
+        let idx;
+        while ((idx = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, idx).trim();
+            buffer = buffer.slice(idx + 1);
+            if (!line)
+                continue;
+            // Serialize initialize — queue other messages until it completes
+            if (!initialized) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed.method === "initialize") {
+                    const p = processMessage(line)
+                        .then(() => {
+                        initialized = true;
+                        // Flush queued messages
+                        for (const queued of pendingAfterInit) {
+                            enqueue(queued);
+                        }
+                        pendingAfterInit = [];
+                    })
+                        .catch((err) => log(`Initialize error: ${err}`));
+                    inflight.add(p);
+                    p.finally(() => {
+                        inflight.delete(p);
+                        if ((stdinClosed || shuttingDown) && inflight.size === 0)
+                            process.exit(0);
+                    });
+                }
+                else {
+                    // Queue until initialize completes (notifications/initialized are fine to queue)
+                    pendingAfterInit.push(line);
+                }
+            }
+            else {
+                enqueue(line);
+            }
+        }
+    });
+    process.stdin.on("end", () => {
+        stdinClosed = true;
+        if (inflight.size === 0) {
+            log("stdin closed, exiting.");
+            process.exit(0);
+        }
+    });
+}
+main().catch((err) => { log(`Fatal: ${err}`); process.exit(1); });

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/manifest.json

@@ -0,0 +1,432 @@
+{
+  "manifest_version": "0.3",
+  "name": "airmail-mcp",
+  "display_name": "Airmail",
+  "version": "1.0.0",
+  "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": {
+    "name": "Airmail",
+    "email": "contact@airmailapp.com",
+    "url": "https://airmailapp.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Airmail/airmail-mcp.git"
+  },
+  "homepage": "https://airmailapp.com",
+  "documentation": "https://github.com/Airmail/airmail-mcp#readme",
+  "support": "https://github.com/Airmail/airmail-mcp/issues",
+  "icon": "logo.png",
+  "server": {
+    "type": "node",
+    "entry_point": "dist/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/dist/index.js"
+      ],
+      "env": {
+        "AIRMAIL_MCP_TOKEN": "${user_config.auth_token}",
+        "AIRMAIL_MCP_PORT": "${user_config.port}"
+      }
+    }
+  },
+  "tools_generated": true,
+  "tools": [
+    {
+      "name": "manage_capabilities",
+      "description": "Enable/disable tool groups to manage context."
+    },
+    {
+      "name": "list_accounts",
+      "description": "List email accounts."
+    },
+    {
+      "name": "list_folders",
+      "description": "List folders for an account."
+    },
+    {
+      "name": "list_messages",
+      "description": "List messages in a folder (date desc)."
+    },
+    {
+      "name": "get_message",
+      "description": "Get full message: body (plain text), recipients, attachments, subject, date, labels."
+    },
+    {
+      "name": "list_inbox",
+      "description": "List inbox messages (date desc)."
+    },
+    {
+      "name": "list_starred",
+      "description": "List starred/flagged messages."
+    },
+    {
+      "name": "list_sent",
+      "description": "List sent messages."
+    },
+    {
+      "name": "list_trash",
+      "description": "List trash messages."
+    },
+    {
+      "name": "list_spam",
+      "description": "List spam/junk messages."
+    },
+    {
+      "name": "search_messages",
+      "description": "Search emails with hybrid FTS + semantic engine."
+    },
+    {
+      "name": "fetch_message_body",
+      "description": "Trigger server body download."
+    },
+    {
+      "name": "list_attachments",
+      "description": "List message attachments."
+    },
+    {
+      "name": "get_unread_counts",
+      "description": "Unread count per account inbox."
+    },
+    {
+      "name": "search_contacts",
+      "description": "Search contacts/recent senders by name or email."
+    },
+    {
+      "name": "get_draft",
+      "description": "Get draft content: body, recipients, attachments."
+    },
+    {
+      "name": "delete_draft",
+      "description": "Permanently delete a draft."
+    },
+    {
+      "name": "get_message_thread",
+      "description": "Get all messages in a conversation thread (date asc)."
+    },
+    {
+      "name": "get_attachment",
+      "description": "Get the content of a specific attachment."
+    },
+    {
+      "name": "list_windows",
+      "description": "List open Airmail windows (composers, readers)."
+    },
+    {
+      "name": "export_eml",
+      "description": "Export message as .eml (RFC 822) file saved to disk (returns file_path)."
+    },
+    {
+      "name": "semantic_search",
+      "description": "Search by meaning via vector embeddings (macOS 14+)."
+    },
+    {
+      "name": "semantic_index_status",
+      "description": "Check/trigger semantic index."
+    },
+    {
+      "name": "mark_messages",
+      "description": "Apply flags."
+    },
+    {
+      "name": "archive_messages",
+      "description": "Move messages to archive."
+    },
+    {
+      "name": "trash_messages",
+      "description": "Move messages to trash."
+    },
+    {
+      "name": "move_messages",
+      "description": "Move messages to a folder."
+    },
+    {
+      "name": "copy_messages",
+      "description": "Copy messages to a folder (originals stay)."
+    },
+    {
+      "name": "snooze_messages",
+      "description": "Snooze messages."
+    },
+    {
+      "name": "add_to_list",
+      "description": "Add messages to Todo, Memo, or Done list."
+    },
+    {
+      "name": "delete_messages",
+      "description": "Permanently delete."
+    },
+    {
+      "name": "empty_folder",
+      "description": "Empty trash or spam across all accounts."
+    },
+    {
+      "name": "refresh_inbox",
+      "description": "Fetch new emails from server."
+    },
+    {
+      "name": "enable_disable_account",
+      "description": "Enable or disable an email account."
+    },
+    {
+      "name": "share_icloud",
+      "description": "Upload a file to iCloud Drive and return a public share link."
+    },
+    {
+      "name": "compose_email",
+      "description": "Open compose window pre-filled."
+    },
+    {
+      "name": "reply_to_message",
+      "description": "Open reply window."
+    },
+    {
+      "name": "forward_message",
+      "description": "Open forward window."
+    },
+    {
+      "name": "quick_reply",
+      "description": "SENDS IMMEDIATELY."
+    },
+    {
+      "name": "send_email",
+      "description": "SENDS IMMEDIATELY without compose window."
+    },
+    {
+      "name": "save_as_draft",
+      "description": "Save email as draft without opening compose window."
+    },
+    {
+      "name": "list_drafts",
+      "description": "List drafts."
+    },
+    {
+      "name": "create_folder",
+      "description": "Create a new folder."
+    },
+    {
+      "name": "rename_folder",
+      "description": "Rename a folder."
+    },
+    {
+      "name": "delete_folder",
+      "description": "Delete a custom folder."
+    },
+    {
+      "name": "analyze_email_history",
+      "description": "Scan sent folder to build behavior profile (tone, contacts, topics)."
+    },
+    {
+      "name": "batch_triage_inbox",
+      "description": "Inbox messages with suggested actions (reply/archive/star/defer) and priority scores."
+    },
+    {
+      "name": "get_user_profile",
+      "description": "Get user behavior profile: reply patterns, contacts, templates."
+    },
+    {
+      "name": "update_user_profile",
+      "description": "Update profile: custom instructions, reply tone/length, add/remove templates."
+    },
+    {
+      "name": "suggest_folder",
+      "description": "Suggest folder for a message based on learned move patterns."
+    },
+    {
+      "name": "get_behavior_stats",
+      "description": "Behavior tracker stats: total actions, top sender→folder and domain rules."
+    },
+    {
+      "name": "list_calendars",
+      "description": "List calendars (IDs, titles, types)."
+    },
+    {
+      "name": "list_events",
+      "description": "List events in date range (default next 7 days)."
+    },
+    {
+      "name": "get_event",
+      "description": "Get event details: attendees, alarms, recurrence, notes."
+    },
+    {
+      "name": "create_event",
+      "description": "Create calendar event."
+    },
+    {
+      "name": "update_event",
+      "description": "Update event."
+    },
+    {
+      "name": "delete_event",
+      "description": "Delete event."
+    },
+    {
+      "name": "list_reminders",
+      "description": "List reminders."
+    },
+    {
+      "name": "create_reminder",
+      "description": "Create reminder."
+    },
+    {
+      "name": "complete_reminder",
+      "description": "Mark reminder completed/uncompleted."
+    },
+    {
+      "name": "delete_reminder",
+      "description": "Delete reminder."
+    },
+    {
+      "name": "list_contacts_book",
+      "description": "List address book contacts."
+    },
+    {
+      "name": "get_contact",
+      "description": "Get full contact details."
+    },
+    {
+      "name": "search_contacts_book",
+      "description": "Search contacts by name or email."
+    },
+    {
+      "name": "create_contact",
+      "description": "Create a contact."
+    },
+    {
+      "name": "update_contact",
+      "description": "Update contact."
+    },
+    {
+      "name": "delete_contact",
+      "description": "Delete a contact."
+    },
+    {
+      "name": "list_contact_groups",
+      "description": "List contact groups."
+    },
+    {
+      "name": "list_vips",
+      "description": "List VIP senders."
+    },
+    {
+      "name": "add_vip",
+      "description": "Add a sender to VIP list."
+    },
+    {
+      "name": "remove_vip",
+      "description": "Remove a sender from VIP list."
+    },
+    {
+      "name": "list_blocked",
+      "description": "List blocked senders."
+    },
+    {
+      "name": "add_blocked",
+      "description": "Block a sender."
+    },
+    {
+      "name": "remove_blocked",
+      "description": "Unblock a sender."
+    },
+    {
+      "name": "get_preferences",
+      "description": "Read app preferences."
+    },
+    {
+      "name": "set_preferences",
+      "description": "Modify app preferences."
+    },
+    {
+      "name": "list_rules",
+      "description": "List all email rules with name, guid, enabled, conditions/actions summary, direction."
+    },
+    {
+      "name": "get_rule",
+      "description": "Get full details of a rule: conditions, actions, shortcut, order."
+    },
+    {
+      "name": "create_rule",
+      "description": "Create a new email rule."
+    },
+    {
+      "name": "delete_rule",
+      "description": "Delete a rule by GUID."
+    },
+    {
+      "name": "toggle_rule",
+      "description": "Enable or disable a rule."
+    },
+    {
+      "name": "list_signatures",
+      "description": "List email signatures."
+    },
+    {
+      "name": "create_signature",
+      "description": "Create a new email signature for an account."
+    },
+    {
+      "name": "update_signature",
+      "description": "Update a signature name, HTML body, or default status."
+    },
+    {
+      "name": "delete_signature",
+      "description": "Delete a signature."
+    },
+    {
+      "name": "list_smart_folders",
+      "description": "List smart folders with uuid, name, search query."
+    },
+    {
+      "name": "create_smart_folder",
+      "description": "Create a smart folder with a search query (same syntax as search_messages)."
+    },
+    {
+      "name": "update_smart_folder",
+      "description": "Update a smart folder name and/or search query."
+    },
+    {
+      "name": "delete_smart_folder",
+      "description": "Delete a smart folder."
+    }
+  ],
+  "keywords": [
+    "email",
+    "mail",
+    "calendar",
+    "contacts",
+    "airmail",
+    "macos",
+    "productivity"
+  ],
+  "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"
+    }
+  },
+  "compatibility": {
+    "claude_desktop": ">=0.10.0",
+    "platforms": [
+      "darwin"
+    ],
+    "runtimes": {
+      "node": ">=18.0.0"
+    }
+  },
+  "privacy_policies": [
+    "https://airmailapp.com/privacy"
+  ]
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "airmail-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.airmail/airmail-mcp",
+  "description": "Manage emails, calendars, contacts, and more from Claude using Airmail's MCP server.",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "airmail-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "manifest.json",
+    "logo.png",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "sync-tools": "node scripts/sync-tools.mjs",
+    "prepublishOnly": "npm run sync-tools && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "airmail",
+    "email",
+    "calendar",
+    "contacts",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "macos"
+  ],
+  "author": "Airmail <support@airmailapp.com>",
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Airmail/airmail-mcp.git"
+  },
+  "homepage": "https://airmailapp.com",
+  "bugs": {
+    "url": "https://github.com/Airmail/airmail-mcp/issues"
+  }
+}