apple-tools-mcp 3.0.5 → 3.0.6

package/README.md

@@ -103,6 +103,16 @@ Claude Desktop keeps this in `~/Library/Application Support/Claude/claude_deskto
 
 The MCP process is short-lived: it exits when the client disconnects. Ongoing indexing belongs on the indexer, not on a wrapper that holds this process open.
 
+When stdin closes, requests already received still get their replies before the process exits (up to two minutes). A script can pipe a whole session in one go:
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"script","version":"0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"mail_search","arguments":{"query":"invoice","limit":5}}}' \
+| apple-tools-mcp
+```
+
 ### 4. Indexer
 
 On first use the server builds a search index of your mail, messages, and calendar events. That can take a while if you have a lot of mail. The index is stored in `~/.apple-tools-mcp/vector-index/`.
@@ -248,6 +258,7 @@ Your client can also call `audit_index`.
 | `mail_read` | Full email content by file path. |
 | `mail_senders` | Most frequent senders. |
 | `mail_thread` | Every email in a conversation. |
+| `mail_find` | Exact lookup in Mail's own database by subject prefix or text, sender, recipient, mailbox, and date. Returns every copy with its Message-ID. Does not wait on the index. |
 
 ### Messages
 
@@ -294,7 +305,7 @@ Every write tool accepts:
 | `dry_run` | Preview only. Nothing is sent or changed. This wins even if `confirm` is also set. |
 | `confirm` | Approves an action that is otherwise blocked. |
 
-Deletes need `confirm: true`: `mail_trash`, `calendar_remove`, `contacts_remove`, and `contacts_edit` when it clears every email or phone. One id per call. There is no bulk delete.
+Deletes need `confirm: true`: `mail_trash`, `calendar_remove`, `contacts_remove`, and `contacts_edit` when it clears every email or phone. These take one id per call, except `mail_trash`, which also takes a list (`message_ids`).
 
 Sends to more than one person need `confirm: true`: `mail_send` and `mail_forward` when To, Cc, and Bcc add up to more than one address, `mail_reply` with `reply_all: true`, and `messages_send` to several people or to a group chat. A single recipient sends on the first call. `mail_draft` never sends, so it does not need that confirm.
 
@@ -314,10 +325,12 @@ A missing or malformed id or recipient is refused. Calendar times are local date
 | `mail_forward` | `message_id` or `file_path`, `to[]` (required), `body`, `save_as_draft` | when recipients > 1 |
 | `mail_mark` | `message_id` or `file_path`, `status` (`read` or `unread`, default `read`) | no |
 | `mail_archive` | `message_id` or `file_path` | no |
-| `mail_trash` | `message_id` or `file_path` | yes |
+| `mail_trash` | `message_id` or `file_path`, or `message_ids[]` (up to 500) | yes |
 
 Pass the RFC822 Message-ID, or the `file_path` from `mail_search` or `mail_recent` and the server reads the Message-ID from the file. `mail_archive` moves the message to that account's Archive (or All Mail). `mail_trash` moves it to Trash.
 
+`mail_trash` with `message_ids` moves every copy of each message, for example the INBOX copy and the Sent copy of a mail you sent yourself, to that account's Trash. It finds each copy through Mail's database (`mail_find` uses the same lookup) and checks its Message-ID again before it moves it. One call stops starting new moves after about 35 seconds and reports `remaining`. Run it again for the rest. Copies that are already in Trash are left alone. Nothing is deleted for good. Mail empties Trash on its own schedule.
+
 `body_format: "html"` pastes the text into Mail's compose window. Mail may still create its own HTML version. New mail is a new message, not a quoted reply. Reply and forward still include the original.
 
 A send is successful only after the message is in **Sent** or still in **Outbox**. If the call times out, check Sent before you try again. Retrying a message that already went out sends a second copy. A timeout is not the same thing as a denied Automation prompt.

package/index.js

@@ -21,6 +21,8 @@ import { createIndexerLock, DEFAULT_LOCK_HEARTBEAT_MS } from "./lib/indexerLock.
 import {
   shouldConnectMcpStdio,
   bindStdinCloseExit,
+  trackInFlightRequests,
+  drainInFlightThenExit,
   beginIndexCycle,
   applyIndexerCycleEnd,
   mcpIndexingStartup,
@@ -38,6 +40,7 @@ import {
 import { startWriteBridgeServer, defaultSocketPath } from "./lib/writeBridge.js";
 import { closeEventKitSession, ensureEventKitSession } from "./lib/eventKitSession.js";
 import { EVENTKIT_JXA_HELPERS } from "./lib/calendarWrite.js";
+import { mailFind, MAILBOX_KINDS, MAIL_FIND_MAX_LIMIT } from "./lib/mailFind.js";
 
 const PACKAGE_VERSION = JSON.parse(
   fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")
@@ -166,9 +169,17 @@ process.on("unhandledRejection", (reason, promise) => {
 // MCP stdio clients exit when the host closes stdin. The indexer daemon,
 // HTTP server, and short-lived CLIs must not — LaunchAgent / KeepAlive
 // often attaches stdin to /dev/null, and the CLIs exit on their own.
+// A caller that pipes a batch and closes stdin still gets every reply:
+// in-flight requests finish (up to STDIN_CLOSE_DRAIN_MS) before exit.
+const STDIN_CLOSE_DRAIN_MS = 120000;
+let stdioInFlight = null;
 bindStdinCloseExit(process.stdin, INDEXER_MODE || PERMISSIONS_MODE || HTTP_MODE || HTTP_TOKEN_MODE, () => {
   console.error("Client disconnected. Exiting.");
-  shutdownIndexing(0);
+  drainInFlightThenExit({
+    inFlight: stdioInFlight,
+    timeoutMs: STDIN_CLOSE_DRAIN_MS,
+    exit: () => shutdownIndexing(0)
+  });
 });
 
 // Vector search imports
@@ -1141,6 +1152,28 @@ function createServer() {
           required: ["file_path"],
         },
       },
+      {
+        name: "mail_find",
+        description: "Exact email lookup in Mail's own database (not the semantic index, so it never waits on indexing and matches filters exactly). Returns JSON: one row per copy (the same Message-ID in INBOX and Sent is two rows) with message_id, subject, from, to, received, mailbox, account_id. Needs at least one of subject_prefix, subject_contains, from, to, message_ids. Trash is excluded unless include_trash or mailboxes asks for it. Pair with mail_trash message_ids to clear what it finds.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            subject_prefix: { type: "string", description: "Subject starts with this text (case-insensitive), e.g. '[Network] '" },
+            subject_contains: { type: "string", description: "Subject contains this text (case-insensitive)" },
+            from: { type: "string", description: "Exact sender address" },
+            from_me: { type: "boolean", description: "Only messages sent from one of your own addresses (any address that appears as a sender in a Sent mailbox)" },
+            to: { type: "string", description: "Exact recipient address (To or Cc)" },
+            to_only: { type: "boolean", description: "With to: that address is the only recipient" },
+            message_ids: { type: "array", items: { type: "string" }, description: "RFC822 Message-IDs (finds every copy)" },
+            mailboxes: { type: "array", items: { type: "string", enum: MAILBOX_KINDS }, description: "Only these mailbox kinds (default: every mailbox except trash)" },
+            include_trash: { type: "boolean", description: "Also return copies already in Trash (default false)" },
+            older_than_hours: { type: "number", description: "Only messages received more than this many hours ago" },
+            received_after: { type: "string", description: "ISO 8601 date/time; only messages received at or after it" },
+            received_before: { type: "string", description: "ISO 8601 date/time; only messages received before it" },
+            limit: { type: "number", description: `Maximum rows (default 50, max ${MAIL_FIND_MAX_LIMIT}); 'truncated' says when more matched` }
+          },
+        },
+      },
 
       // ============ MESSAGES TOOLS ============
       {
@@ -1443,6 +1476,10 @@ function createServer() {
           result = readFullEmail(args.file_path);
           break;
 
+        case "mail_find":
+          result = mailFind(args || {});
+          break;
+
         // Messages tools
         case "messages_search":
           result = await messagesSearch(args.query, {
@@ -1624,6 +1661,7 @@ const server = createServer();
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  stdioInFlight = trackInFlightRequests(transport);
   console.error(`Apple Tools MCP server running (v${PACKAGE_VERSION})`);
   // Background indexing: indexer daemon when --mode=indexer; otherwise local
   // fallback on this stdio process only if indexer.lock is free.

package/lib/indexerRuntime.js

@@ -37,6 +37,95 @@ export function bindStdinCloseExit(stdin, indexerMode, onClose) {
   return { bound: true };
 }
 
+/**
+ * Track JSON-RPC requests the server has received but not yet answered.
+ * A caller that pipes a batch and closes stdin (`printf ... | apple-tools-mcp`)
+ * fires stdin `close` right after the last line is read, while tools/call is
+ * still running; without this the close handler exits mid-call.
+ * Call after server.connect(transport) — Protocol sets onmessage there.
+ *
+ * @param {{ onmessage?: (message: any, extra?: any) => void, send: (message: any, options?: any) => Promise<void> }} transport
+ * @returns {{ readonly size: number, whenIdle: () => Promise<void> }}
+ */
+export function trackInFlightRequests(transport) {
+  const pending = new Set();
+  let idleWaiters = [];
+  const settle = () => {
+    if (pending.size > 0) return;
+    const waiters = idleWaiters;
+    idleWaiters = [];
+    for (const resolve of waiters) resolve();
+  };
+
+  const onmessage = transport.onmessage;
+  transport.onmessage = (message, extra) => {
+    if (message?.method === "notifications/cancelled") {
+      // The SDK sends no response for a cancelled request.
+      pending.delete(message.params?.requestId);
+      settle();
+    } else if (message?.method && message.id !== undefined) {
+      pending.add(message.id);
+    }
+    onmessage?.(message, extra);
+  };
+
+  const send = transport.send.bind(transport);
+  transport.send = async (message, options) => {
+    try {
+      return await send(message, options);
+    } finally {
+      if (!message?.method && message?.id !== undefined && pending.delete(message.id)) {
+        settle();
+      }
+    }
+  };
+
+  return {
+    get size() {
+      return pending.size;
+    },
+    whenIdle() {
+      if (pending.size === 0) return Promise.resolve();
+      return new Promise((resolve) => idleWaiters.push(resolve));
+    }
+  };
+}
+
+/**
+ * On stdin close: let in-flight requests answer (up to timeoutMs), then exit.
+ * Exiting synchronously drops the last tools/call. The SDK's send() resolves
+ * only once stdout has drained, so an answered request is fully written.
+ *
+ * @param {{
+ *   inFlight: { size: number, whenIdle: () => Promise<void> } | null,
+ *   timeoutMs: number,
+ *   exit: () => void,
+ *   log?: (msg: string) => void
+ * }} options
+ * @returns {Promise<{ drained: boolean, pending: number }>}
+ */
+export async function drainInFlightThenExit(options) {
+  const { inFlight, timeoutMs, exit } = options;
+  const log = options.log || ((msg) => console.error(msg));
+
+  const pending = inFlight ? inFlight.size : 0;
+  let drained = true;
+  if (pending > 0) {
+    log(`Waiting for ${pending} in-flight request(s) before exit...`);
+    let timer;
+    const timedOut = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(true), timeoutMs);
+    });
+    drained = !(await Promise.race([inFlight.whenIdle().then(() => false), timedOut]));
+    clearTimeout(timer);
+    if (!drained) {
+      log(`Gave up on ${inFlight.size} in-flight request(s) after ${timeoutMs}ms.`);
+    }
+  }
+  exit();
+  return { drained, pending };
+}
+
 /**
  * Start one index cycle, or skip if a cycle is already running.
  *

package/lib/mailFind.js

@@ -0,0 +1,323 @@
+/**
+ * Exact mail lookup against Mail's own Envelope Index (no vector index).
+ *
+ * mail_find answers "which messages match these exact facts" (subject
+ * prefix, sender, recipient, mailbox, date) and bulk mail_trash uses
+ * locateMessageCopies() to address every copy of a Message-ID by Mail's
+ * internal id. A message's AppleScript `id` is its Envelope Index ROWID, so
+ * `messages of <one mailbox> whose id is N` resolves in about 2s even on a
+ * 60k-message INBOX, where `whose message id is X` across every mailbox
+ * takes 30-38s (see MAIL_FIND_TIMEOUT_MS in mailWrite.js).
+ *
+ * Read-only: sqlite3 opens the database with -readonly and Mail stays its
+ * only writer. Needs the same Full Disk Access as the .emlx indexer.
+ */
+
+import fs from "fs";
+import path from "path";
+import { safeSqlite3Json } from "./shell.js";
+import { normalizeList, validateMessageId } from "./writeGuards.js";
+
+const MAIL_DIR = path.join(process.env.HOME || "", "Library", "Mail");
+
+export const MAIL_FIND_DEFAULT_LIMIT = 50;
+export const MAIL_FIND_MAX_LIMIT = 500;
+export const MAIL_FIND_MAX_IDS = 500;
+const MAX_TEXT_FILTER = 300;
+const MAX_COPIES = 5000;
+
+/** Mailbox leaf names per kind, as Mail names them across iCloud, IMAP, Exchange and Gmail. */
+export const MAILBOX_KIND_LEAVES = {
+  inbox: ["INBOX"],
+  sent: ["Sent Messages", "Sent", "Sent Items", "Sent Mail"],
+  trash: ["Deleted Messages", "Trash", "Bin", "Deleted Items"],
+  junk: ["Junk", "Junk E-mail", "Spam"],
+  drafts: ["Drafts"],
+  archive: ["Archive", "All Mail"]
+};
+export const MAILBOX_KINDS = Object.keys(MAILBOX_KIND_LEAVES);
+export const TRASH_MAILBOX_NAMES = MAILBOX_KIND_LEAVES.trash;
+
+const ACCOUNT_ID_RE = /^[0-9A-Fa-f-]{8,64}$/;
+const ADDRESS_RE = /^[^\s@'"]{1,200}@[^\s@'"]{1,200}$/;
+
+export const ENVELOPE_INDEX_ACCESS_GUIDANCE =
+  "Mail's Envelope Index could not be read. Give the node binary that runs Apple Tools Full Disk Access " +
+  "(System Settings → Privacy & Security → Full Disk Access), and make sure Mail has been set up on this Mac.";
+
+/**
+ * Newest `~/Library/Mail/V<n>/MailData/Envelope Index`, or null.
+ */
+export function envelopeIndexPath(mailDir = MAIL_DIR) {
+  let entries;
+  try {
+    entries = fs.readdirSync(mailDir);
+  } catch {
+    return null;
+  }
+  const versions = entries
+    .map((name) => /^V(\d+)$/.exec(name))
+    .filter(Boolean)
+    .map((m) => Number(m[1]))
+    .sort((a, b) => b - a);
+  for (const v of versions) {
+    const candidate = path.join(mailDir, `V${v}`, "MailData", "Envelope Index");
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * `imap://<account uuid>/Sent%20Messages` → account id + decoded mailbox path.
+ * Local ("On My Mac") mailboxes have no account id and cannot be addressed
+ * by `account id` in AppleScript.
+ */
+export function parseMailboxUrl(url) {
+  const m = /^([a-z][a-z0-9+.-]*):\/\/([^/]*)\/(.+)$/i.exec(String(url || ""));
+  if (!m) return null;
+  let mailboxPath;
+  try {
+    mailboxPath = m[3].split("/").map((part) => decodeURIComponent(part)).join("/");
+  } catch {
+    return null;
+  }
+  const accountId = ACCOUNT_ID_RE.test(m[2]) ? m[2] : null;
+  return { scheme: m[1].toLowerCase(), accountId, mailboxPath };
+}
+
+export function mailboxKind(mailboxPath) {
+  const leaf = String(mailboxPath || "").split("/").pop().toLowerCase();
+  for (const [kind, leaves] of Object.entries(MAILBOX_KIND_LEAVES)) {
+    if (leaves.some((name) => name.toLowerCase() === leaf)) return kind;
+  }
+  return "other";
+}
+
+function sqlLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function likeEscape(value) {
+  return String(value).replace(/[\\%_]/g, (c) => `\\${c}`);
+}
+
+function likeClause(expr, pattern) {
+  return `${expr} LIKE ${sqlLiteral(pattern)} ESCAPE '\\'`;
+}
+
+/** SQL condition: mailbox URL `column` ends in one of `kind`'s leaf names. */
+export function mailboxKindCondition(kind, column = "mb.url") {
+  const leaves = MAILBOX_KIND_LEAVES[kind] || [];
+  return `(${leaves.map((leaf) => likeClause(column, `%/${likeEscape(encodeURIComponent(leaf))}`)).join(" OR ")})`;
+}
+
+function cleanText(value, field) {
+  if (value === undefined || value === null || value === "") return { value: null };
+  if (typeof value !== "string") return { error: `${field} must be a string` };
+  const trimmed = value.replace(/\s+/g, " ").trim();
+  if (!trimmed) return { value: null };
+  if (trimmed.length > MAX_TEXT_FILTER) return { error: `${field} is longer than ${MAX_TEXT_FILTER} characters` };
+  return { value: trimmed };
+}
+
+function cleanAddress(value, field) {
+  const text = cleanText(value, field);
+  if (text.error || !text.value) return text;
+  if (!ADDRESS_RE.test(text.value)) return { error: `${field} must be one email address` };
+  return { value: text.value.toLowerCase() };
+}
+
+function parseTime(value, field) {
+  if (value === undefined || value === null || value === "") return { value: null };
+  const ms = typeof value === "number" ? value * 1000 : Date.parse(String(value));
+  if (!Number.isFinite(ms)) return { error: `${field} must be an ISO 8601 date/time` };
+  return { value: Math.floor(ms / 1000) };
+}
+
+/**
+ * Validate mail_find arguments into SQL-ready filters.
+ * @returns {{ filters?: object, error?: string }}
+ */
+export function validateFindArgs(args = {}, { now = Date.now() } = {}) {
+  const f = {};
+  for (const [key, field] of [["subjectPrefix", "subject_prefix"], ["subjectContains", "subject_contains"]]) {
+    const r = cleanText(args[field], field);
+    if (r.error) return { error: r.error };
+    f[key] = r.value;
+  }
+  for (const [key, field] of [["from", "from"], ["to", "to"]]) {
+    const r = cleanAddress(args[field], field);
+    if (r.error) return { error: r.error };
+    f[key] = r.value;
+  }
+  f.toOnly = args.to_only === true || args.to_only === "true";
+  if (f.toOnly && !f.to) return { error: "to_only needs to" };
+  f.fromMe = args.from_me === true || args.from_me === "true";
+
+  const ids = normalizeList(args.message_ids);
+  if (ids.length > MAIL_FIND_MAX_IDS) return { error: `message_ids accepts at most ${MAIL_FIND_MAX_IDS} ids` };
+  f.messageIds = [];
+  for (const raw of ids) {
+    const id = validateMessageId(raw);
+    if (!id) return { error: "message_ids contains an invalid RFC822 Message-ID" };
+    f.messageIds.push(id);
+  }
+
+  const mailboxes = normalizeList(args.mailboxes).map((m) => m.toLowerCase());
+  const unknown = mailboxes.filter((m) => !MAILBOX_KINDS.includes(m));
+  if (unknown.length) return { error: `mailboxes must be from: ${MAILBOX_KINDS.join(", ")}` };
+  f.mailboxes = mailboxes;
+  f.includeTrash = args.include_trash === true || args.include_trash === "true";
+
+  const after = parseTime(args.received_after, "received_after");
+  if (after.error) return { error: after.error };
+  const before = parseTime(args.received_before, "received_before");
+  if (before.error) return { error: before.error };
+  f.receivedAfter = after.value;
+  f.receivedBefore = before.value;
+  if (args.older_than_hours !== undefined && args.older_than_hours !== null && args.older_than_hours !== "") {
+    const hours = Number(args.older_than_hours);
+    if (!Number.isFinite(hours) || hours < 0 || hours > 24 * 365 * 20) {
+      return { error: "older_than_hours must be a number of hours (0 or more)" };
+    }
+    const cutoff = Math.floor(now / 1000 - hours * 3600);
+    f.receivedBefore = f.receivedBefore === null ? cutoff : Math.min(f.receivedBefore, cutoff);
+  }
+
+  if (!f.subjectPrefix && !f.subjectContains && !f.from && !f.to && f.messageIds.length === 0) {
+    return { error: "add at least one of subject_prefix, subject_contains, from, to, or message_ids" };
+  }
+
+  const limit = args.limit === undefined || args.limit === null ? MAIL_FIND_DEFAULT_LIMIT : Number(args.limit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAIL_FIND_MAX_LIMIT) {
+    return { error: `limit must be an integer from 1 to ${MAIL_FIND_MAX_LIMIT}` };
+  }
+  f.limit = limit;
+  return { filters: f };
+}
+
+const SUBJECT_EXPR = "(coalesce(m.subject_prefix, '') || s.subject)";
+
+/** Build the Envelope Index query for validated filters. Selects limit+1 rows to detect truncation. */
+export function buildFindQuery(f) {
+  const where = ["m.deleted = 0"];
+  if (f.subjectPrefix) where.push(likeClause(SUBJECT_EXPR, `${likeEscape(f.subjectPrefix)}%`));
+  if (f.subjectContains) where.push(likeClause(SUBJECT_EXPR, `%${likeEscape(f.subjectContains)}%`));
+  if (f.from) where.push(`lower(a.address) = ${sqlLiteral(f.from)}`);
+  if (f.to) {
+    where.push(
+      `EXISTS (SELECT 1 FROM recipients r JOIN addresses ra ON ra.ROWID = r.address WHERE r.message = m.ROWID AND lower(ra.address) = ${sqlLiteral(f.to)})`
+    );
+    if (f.toOnly) where.push("(SELECT count(*) FROM recipients r WHERE r.message = m.ROWID) = 1");
+  }
+  if (f.fromMe) {
+    // "Me" = any address that appears as the sender of a message in a Sent mailbox.
+    where.push(
+      `m.sender IN (SELECT DISTINCT m2.sender FROM messages m2 JOIN mailboxes mb2 ON mb2.ROWID = m2.mailbox WHERE m2.sender IS NOT NULL AND ${mailboxKindCondition("sent", "mb2.url")})`
+    );
+  }
+  if (f.messageIds.length) {
+    where.push(`g.message_id_header IN (${f.messageIds.map((id) => sqlLiteral(`<${id}>`)).join(", ")})`);
+  }
+  if (f.receivedAfter !== null) where.push(`m.date_received >= ${Math.floor(f.receivedAfter)}`);
+  if (f.receivedBefore !== null) where.push(`m.date_received < ${Math.floor(f.receivedBefore)}`);
+  if (f.mailboxes.length) {
+    where.push(`(${f.mailboxes.map((kind) => mailboxKindCondition(kind)).join(" OR ")})`);
+  } else if (!f.includeTrash) {
+    where.push(`NOT ${mailboxKindCondition("trash")}`);
+  }
+
+  return `SELECT m.ROWID AS id, g.message_id_header AS message_id, ${SUBJECT_EXPR} AS subject,
+    a.address AS sender, m.date_received AS received, mb.url AS mailbox_url,
+    (SELECT group_concat(ra.address, ',') FROM recipients r JOIN addresses ra ON ra.ROWID = r.address WHERE r.message = m.ROWID) AS recipients
+  FROM messages m
+  JOIN subjects s ON s.ROWID = m.subject
+  JOIN mailboxes mb ON mb.ROWID = m.mailbox
+  LEFT JOIN addresses a ON a.ROWID = m.sender
+  LEFT JOIN message_global_data g ON g.ROWID = m.global_message_id
+  WHERE ${where.join("\n    AND ")}
+  ORDER BY m.date_received DESC, m.ROWID DESC
+  LIMIT ${f.limit + 1}`;
+}
+
+function mapRow(row) {
+  const box = parseMailboxUrl(row.mailbox_url) || { accountId: null, mailboxPath: String(row.mailbox_url || "") };
+  return {
+    id: row.id,
+    message_id: row.message_id ? String(row.message_id).replace(/^</, "").replace(/>$/, "") : null,
+    subject: row.subject || "",
+    from: row.sender || null,
+    to: row.recipients ? String(row.recipients).split(",") : [],
+    received: Number.isFinite(row.received) ? new Date(row.received * 1000).toISOString() : null,
+    mailbox: mailboxKind(box.mailboxPath),
+    mailbox_path: box.mailboxPath,
+    account_id: box.accountId
+  };
+}
+
+function runQuery(sql, { dbPath, query = safeSqlite3Json } = {}) {
+  const db = dbPath || envelopeIndexPath();
+  if (!db) throw new Error(ENVELOPE_INDEX_ACCESS_GUIDANCE);
+  try {
+    return query(db, sql, { readonly: true, timeout: 20000 });
+  } catch (e) {
+    const msg = String((e && e.message) || e);
+    if (/unable to open|authoriz|not permitted|denied/i.test(msg)) throw new Error(ENVELOPE_INDEX_ACCESS_GUIDANCE);
+    throw e;
+  }
+}
+
+/**
+ * Exact lookup. Every copy is its own row (the same Message-ID in INBOX and
+ * Sent shows twice).
+ * @returns {{ messages: object[], truncated: boolean }}
+ */
+export function findMail(filters, options = {}) {
+  const rows = runQuery(buildFindQuery(filters), options);
+  const truncated = rows.length > filters.limit;
+  return { messages: rows.slice(0, filters.limit).map(mapRow), truncated };
+}
+
+/**
+ * Every live copy of each Message-ID, split into copies outside Trash (to
+ * move) and the ids that have no such copy (already trashed or not in Mail).
+ */
+export function locateMessageCopies(messageIds, options = {}) {
+  const filters = {
+    subjectPrefix: null,
+    subjectContains: null,
+    from: null,
+    to: null,
+    toOnly: false,
+    fromMe: false,
+    messageIds,
+    mailboxes: [],
+    includeTrash: false,
+    receivedAfter: null,
+    receivedBefore: null,
+    limit: MAX_COPIES
+  };
+  const { messages } = findMail(filters, options);
+  const found = new Set(messages.map((m) => m.message_id));
+  return { copies: messages, missingIds: messageIds.filter((id) => !found.has(id)) };
+}
+
+export function formatFindResult({ messages, truncated }) {
+  return JSON.stringify(
+    {
+      count: messages.length,
+      truncated,
+      note: truncated ? "More messages match; raise limit or narrow the filters." : undefined,
+      messages
+    },
+    null,
+    2
+  );
+}
+
+/** mail_find tool entry point. Returns text; throws on invalid args or an unreadable index. */
+export function mailFind(args = {}, options = {}) {
+  const { filters, error } = validateFindArgs(args, options);
+  if (error) throw new Error(`mail_find: ${error}`);
+  return formatFindResult(findMail(filters, options));
+}

package/lib/mailWrite.js

@@ -42,8 +42,10 @@ import {
   writeErrorMessage,
   writeSuccessMessage,
   isFlagTrue,
+  normalizeList,
   truncate
 } from "./writeGuards.js";
+import { locateMessageCopies, TRASH_MAILBOX_NAMES, MAIL_FIND_MAX_IDS } from "./mailFind.js";
 
 const MAIL_DIR = path.join(process.env.HOME || "", "Library", "Mail");
 
@@ -1785,8 +1787,174 @@ export function mailArchive(args = {}) {
   return { ok: true, message: writeSuccessMessage(action, "moved to Archive", { message_id: resolved.messageId }) };
 }
 
+// Bulk mail_trash stops starting new moves after this many seconds so the
+// call answers inside MCP_CALL_DEADLINE_MS. Each copy takes ~2s (one
+// `whose id is` lookup in its own mailbox, then the move); callers re-run
+// for whatever is left.
+export const MAIL_BULK_TRASH_BUDGET_SEC = 35;
+export const MAIL_TRASH_MAX_IDS = MAIL_FIND_MAX_IDS;
+
+/**
+ * One osascript for every copy. Each copy is found by Mail's internal id in
+ * its own mailbox (fast) and moved only if its Message-ID still matches, so
+ * a stale Envelope Index row can never move the wrong message.
+ * Output: one `<id>\t<status>` line per copy; status is moved, missing,
+ * mismatch, no_account, no_trash, skipped (time budget) or `error <n>`.
+ */
+export function buildBulkTrashScript(copies, { budgetSec = MAIL_BULK_TRASH_BUDGET_SEC } = {}) {
+  const items = copies
+    .map((c) => `{${asString(c.account_id)}, ${asString(c.mailbox_path)}, ${asInteger(c.id, { min: 1, field: "id" })}, ${asString(c.message_id)}}`)
+    .join(", ");
+  const trashNames = TRASH_MAILBOX_NAMES.map((name) => asString(name)).join(", ");
+  return `on atmTrashBox(acct)
+  tell application "Mail"
+    repeat with nm in {${trashNames}}
+      if (exists mailbox (contents of nm) of acct) then return mailbox (contents of nm) of acct
+    end repeat
+  end tell
+  return missing value
+end atmTrashBox
+
+on atmTrashCopy(acctId, boxPath, rid, mid)
+  tell application "Mail"
+    try
+      set acct to account id acctId
+      -- An account specifier resolves lazily; reading a property proves it exists.
+      set acctName to name of acct
+    on error
+      return "no_account"
+    end try
+    try
+      set hits to (messages of (mailbox boxPath of acct) whose id is rid)
+    on error errMsg number errNum
+      return "error " & errNum
+    end try
+    if (count of hits) is 0 then return "missing"
+    set msg to item 1 of hits
+    if (message id of msg) is not mid then return "mismatch"
+    set trashBox to my atmTrashBox(acct)
+    if trashBox is missing value then return "no_trash"
+    try
+      set mailbox of msg to trashBox
+    on error errMsg number errNum
+      return "error " & errNum
+    end try
+    return "moved"
+  end tell
+end atmTrashCopy
+
+set atmStart to current date
+set atmOut to ""
+repeat with atmItem in {${items}}
+  if ((current date) - atmStart) > ${asInteger(budgetSec, { min: 1, max: 600, field: "budgetSec" })} then
+    set atmStatus to "skipped"
+  else
+    set atmStatus to atmTrashCopy(item 1 of atmItem, item 2 of atmItem, item 3 of atmItem, item 4 of atmItem)
+  end if
+  set atmOut to atmOut & (item 3 of atmItem) & tab & atmStatus & linefeed
+end repeat
+return atmOut`;
+}
+
+export function parseBulkTrashOutput(output) {
+  const statuses = new Map();
+  for (const line of String(output || "").split(/\r?\n|\r/)) {
+    const m = /^(\d+)\t(.+)$/.exec(line.trim());
+    if (m) statuses.set(Number(m[1]), m[2].trim());
+  }
+  return statuses;
+}
+
+function plural(n, word, many = `${word}s`) {
+  return `${n} ${n === 1 ? word : many}`;
+}
+
+/**
+ * mail_trash with message_ids: move every copy (INBOX, Sent, Archive, ...)
+ * of each message to its account's Trash.
+ */
+export function mailTrashMany(args = {}, { locate = locateMessageCopies, budgetSec = MAIL_BULK_TRASH_BUDGET_SEC } = {}) {
+  const action = "mail_trash";
+  if (args.message_id || args.file_path) {
+    return { ok: false, message: `${action} refused: pass message_ids, or message_id / file_path — not both.` };
+  }
+  const raw = normalizeList(args.message_ids);
+  if (raw.length === 0) return { ok: false, message: `${action} refused: message_ids is empty.` };
+  if (raw.length > MAIL_TRASH_MAX_IDS) {
+    return { ok: false, message: `${action} refused: message_ids accepts at most ${MAIL_TRASH_MAX_IDS} ids per call.` };
+  }
+  const ids = [];
+  for (const value of raw) {
+    const id = validateMessageId(value);
+    if (!id) return { ok: false, message: `${action} refused: message_ids contains an invalid RFC822 Message-ID.` };
+    if (!ids.includes(id)) ids.push(id);
+  }
+
+  let located;
+  try {
+    located = locate(ids);
+  } catch (e) {
+    return { ok: false, message: `${action} failed — could not look the messages up. ${e.message}` };
+  }
+  const live = located.copies.filter((c) => c.mailbox !== "trash");
+  const movable = live.filter((c) => c.account_id);
+  const unaddressable = live.length - movable.length;
+  const summary = `move ${plural(movable.length, "copy", "copies")} of ${plural(ids.length - located.missingIds.length, "message")} to Trash` +
+    (located.missingIds.length ? ` (${located.missingIds.length} not found outside Trash)` : "");
+
+  const plan = planWrite({
+    action,
+    summary,
+    destructive: true,
+    dryRun: isFlagTrue(args.dry_run),
+    confirm: isFlagTrue(args.confirm)
+  });
+  if (!plan.proceed) return plannedWriteResult(plan);
+
+  if (movable.length === 0) {
+    return {
+      ok: true,
+      message: writeSuccessMessage(action, "nothing to move", { not_found: located.missingIds.length, unaddressable: unaddressable || undefined })
+    };
+  }
+
+  const result = runAppleScript(buildBulkTrashScript(movable, { budgetSec }), {
+    timeout: MCP_CALL_DEADLINE_MS,
+    appName: "Mail"
+  });
+  if (!result.ok) return { ok: false, message: failure(action, summary, result, []) };
+
+  const statuses = parseBulkTrashOutput(result.output);
+  const counts = { moved: 0, stale: 0, remaining: 0, failed: 0 };
+  const failures = new Set();
+  for (const copy of movable) {
+    const status = statuses.get(copy.id) || "skipped";
+    if (status === "moved") counts.moved += 1;
+    else if (status === "missing" || status === "mismatch") counts.stale += 1;
+    else if (status === "skipped") counts.remaining += 1;
+    else {
+      counts.failed += 1;
+      failures.add(status);
+    }
+  }
+  const details = {
+    moved: counts.moved,
+    copies: movable.length,
+    not_found: located.missingIds.length,
+    stale: counts.stale || undefined,
+    remaining: counts.remaining || undefined,
+    failed: counts.failed || undefined,
+    failure_reasons: failures.size ? [...failures].join(", ") : undefined,
+    unaddressable: unaddressable || undefined
+  };
+  const tail = counts.remaining ? " Time budget reached; run again for the rest." : "";
+  const message = writeSuccessMessage(action, `moved ${counts.moved} of ${plural(movable.length, "copy", "copies")} to Trash`, details) + tail;
+  return { ok: counts.failed === 0, message };
+}
+
 export function mailTrash(args = {}) {
   const action = "mail_trash";
+  if (args.message_ids !== undefined && args.message_ids !== null) return mailTrashMany(args);
   const resolved = resolveMailMessageId({ messageId: args.message_id, filePath: args.file_path });
   if (resolved.error) return { ok: false, message: `${action} refused: ${resolved.error}` };
 

package/lib/shell.js

@@ -22,6 +22,7 @@ import { escapeSQL } from "./validators.js";
  * @param {string} query - SQL query to execute
  * @param {object} options - Additional options
  * @param {boolean} options.json - Return JSON output (default: true)
+ * @param {boolean} options.readonly - Open the database read-only (default: false)
  * @param {number} options.timeout - Timeout in ms (default: 30000)
  * @param {number} options.maxBuffer - Max buffer size (default: 50MB)
  * @returns {string} Raw output from sqlite3
@@ -30,6 +31,7 @@ import { escapeSQL } from "./validators.js";
 export function safeSqlite3(dbPath, query, options = {}) {
   const {
     json = true,
+    readonly = false,
     timeout = 30000,
     maxBuffer = 50 * 1024 * 1024
   } = options;
@@ -52,6 +54,9 @@ export function safeSqlite3(dbPath, query, options = {}) {
   if (json) {
     args.push('-json');
   }
+  if (readonly) {
+    args.push('-readonly');
+  }
   args.push(dbPath);
   args.push(query.replace(/\n/g, ' ')); // Normalize whitespace
 

package/lib/writeTools.js

@@ -137,11 +137,12 @@ export const WRITE_TOOL_DEFINITIONS = [
   },
   {
     name: "mail_trash",
-    description: "Move an email to Trash. Destructive: requires confirm=true, otherwise the call only reports what would be trashed.",
+    description: "Move email to Trash. Destructive: requires confirm=true, otherwise the call only reports what would be trashed. One message: message_id or file_path. Many: message_ids (up to 500, e.g. from mail_find) moves every copy of each (INBOX, Sent, Archive...) to that account's Trash; each copy's Message-ID is re-checked before it moves. A bulk call stops starting new moves after ~35s and reports 'remaining'; run it again for the rest.",
     inputSchema: {
       type: "object",
       properties: {
         ...MESSAGE_TARGET_PROPS,
+        message_ids: { type: "array", items: { type: "string" }, description: "Bulk: RFC822 Message-IDs (from mail_find). Every copy outside Trash is moved. Do not combine with message_id / file_path." },
         ...CONFIRM_PROPS
       },
       required: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-tools-mcp",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "description": "MCP server for semantic search and write actions across Apple Mail, Messages, Calendar, and Contacts. Speaks stdio (local) or bearer-token-authenticated Streamable HTTP (LAN / Tailscale).",
   "type": "module",
   "main": "index.js",