apple-mail-mcp 2.20.9 → 2.20.11

package/README.md

@@ -237,12 +237,29 @@ Search for messages matching criteria. Searches all accounts by default.
 | `account`   | string  | No       | Account to search in (omit to search all accounts)                                                                                        |
 | `isRead`    | boolean | No       | Filter by read status                                                                                                                     |
 | `isFlagged` | boolean | No       | Filter by flagged status                                                                                                                  |
+| `flagColor` | string  | No       | Filter to messages flagged with exactly this color — see [`flag-message`](#flag-message--unflag-message) for the palette. Implies `isFlagged: true`; pairing this with `isFlagged: false` is rejected. See the flag-color note below. |
 | `dateFrom`  | string  | No       | Start date filter (e.g., "January 1, 2026")                                                                                               |
 | `dateTo`    | string  | No       | End date filter (e.g., "March 1, 2026")                                                                                                   |
 | `limit`     | number  | No       | Max results, 1–500 (default: 50)                                                                                                          |
 | `offset`    | number  | No       | Newest matches to skip, ≥ 0 (for pagination). IMAP accounts only; without a `mailbox`, `offset` + `limit` may not exceed 5,000            |
 
-**Returns:** List of matching messages with ID, date, subject, sender, and read state.
+**Returns:** List of matching messages with ID, date, subject, sender, read state,
+and `flagColor` when flagged with an explicit color.
+
+**Flag color as a label (#286).** Every row from both backends carries
+`flagColor` (the palette name — `red`, `orange`, `yellow`, `green`, `blue`,
+`purple`, `gray`) whenever the message is flagged with an explicit color;
+omitted for an unflagged message or one flagged with Mail's plain default (no
+color chosen). Combined with the `flagColor` filter above, a colored flag
+works as a label across mailboxes: flag a set of messages with
+`flag-message`/`batch-flag-messages`, then find exactly that set later with
+`search-messages`, without moving anything into a dedicated folder. **Known
+limitation, inherent to Apple's `$MailFlagBit0/1/2` IMAP wire encoding, not
+specific to this server:** `red` (palette index 0) sets no keyword bits, so
+over IMAP it is indistinguishable from a plain colorless flag, both when
+reading `flagColor` back and when filtering on it. AppleScript-backed
+accounts are unaffected (Mail's own `flag index` property is `0` for red, `-1`
+for none).
 
 ⚠️ **Row dates.** Since 2.19.7 every row — on both the IMAP and AppleScript
 backends — carries both `dateSent` (the message's `Date:` header) and
@@ -392,7 +409,9 @@ List messages in a mailbox.
 | `from`       | string  | No       | Filter by sender email address or name           |
 | `unreadOnly` | boolean | No       | Only show unread messages                        |
 
-**Returns:** List of messages with ID, date, subject, and sender.
+**Returns:** List of messages with ID, date, subject, sender, and `flagColor`
+when flagged with an explicit color (see the flag-color note under
+[`search-messages`](#search-messages), which also supports filtering by it).
 
 ⚠️ **Row dates.** Since 2.19.7 every row — on both the **IMAP** and
 **AppleScript** backends — carries both `dateSent` (the message's `Date:`
@@ -995,7 +1014,12 @@ Flag or unflag a message. `flag-message` optionally takes a flag **color**; `unf
 
 **Flag colors** are an Apple Mail feature — the message's `flag index` (0 red, 1 orange, 2 yellow, 3 green, 4 blue, 5 purple, 6 gray), which is the property a Mail smart mailbox can match on. **The color is applied on both routes** (since 2.10.0): AppleScript sets the flag index directly, and for an **IMAP-routed** id (`imap:…`) the color is written as Mail.app's `$MailFlagBit0/1/2` keywords — a 3-bit field holding the same palette index. `\Flagged` on its own really is colorless, but those keywords ride alongside it in an ordinary `UID STORE`, so a smart mailbox keyed on flag color matches an IMAP-flagged message too. You do **not** need to resolve to a numeric id just to color a flag.
 
-To **read** a color, the IMAP read path returns `flagColorIndex` in `structuredContent` — the same 0-6 palette index, omitted when the message carries no color bits. The AppleScript read path does not populate it.
+To **read** a color back, or **find** messages by color, use
+[`search-messages`](#search-messages) (or [`list-messages`](#list-messages) for
+read-back only) — both routes now return `flagColor` (the palette name) on
+every flagged-with-a-color row, and `search-messages` takes a `flagColor`
+filter using this same palette (#286). The IMAP route additionally still
+carries the raw 0-6 `flagColorIndex` for back-compat.
 
 ---
 

package/build/cli.js

@@ -58021,6 +58021,7 @@ var init_auditLog = __esm({
 // src/services/imapClient.ts
 var imapClient_exports = {};
 __export(imapClient_exports, {
+  FLAG_COLOR_NAMES: () => FLAG_COLOR_NAMES,
   HEADER_WINDOW_BYTES: () => HEADER_WINDOW_BYTES,
   IMAP_ENV: () => IMAP_ENV,
   LARGE_MAILBOX_MESSAGES: () => LARGE_MAILBOX_MESSAGES,
@@ -58038,6 +58039,7 @@ __export(imapClient_exports, {
   decodedSizeWithoutBody: () => decodedSizeWithoutBody,
   dropAllPools: () => dropAllPools,
   encodeImapId: () => encodeImapId,
+  flagColorName: () => flagColorName,
   imapAppendDraft: () => imapAppendDraft,
   imapAppendSentCopy: () => imapAppendSentCopy,
   imapBatchDelete: () => imapBatchDelete,
@@ -58324,6 +58326,9 @@ function buildCriteria(a, listMode) {
   if (a.isFlagged === false) c.unflagged = true;
   if (a.dateFrom) c.since = new Date(a.dateFrom);
   if (a.dateTo) c.before = new Date(a.dateTo);
+  if (a.flagColorIndex !== void 0) {
+    c.flagged = true;
+  }
   return c;
 }
 function validDate(d) {
@@ -58366,6 +58371,7 @@ function isoOrEmpty(d) {
 }
 function structuredRow(m, account, path3) {
   const env = m.envelope ?? {};
+  const flagColorIndex = mailFlagColorIndex(m.flags);
   return {
     id: encodeImapId(account, path3, m.uid),
     subject: env.subject || "(no subject)",
@@ -58382,7 +58388,19 @@ function structuredRow(m, account, path3) {
     dateReceived: isoOrEmpty(validDate(m.internalDate) ?? headerDate(m)),
     isRead: m.flags?.has("\\Seen") ?? false,
     isFlagged: m.flags?.has("\\Flagged") ?? false,
-    flagColorIndex: mailFlagColorIndex(m.flags),
+    // flagColorIndex has been computed here since 2.19.x but never reached a
+    // caller in friendly form (#286, @j5pu) — flagColor is the palette name
+    // (e.g. "orange"), omitted whenever the index is (unflagged, or flagged
+    // with Mail's plain default and no explicit color). flagColorIndex stays
+    // for back-compat.
+    // ⚠️ "red" (index 0) sets no $MailFlagBit keyword — it is wire-identical to
+    // a plain colorless flag over IMAP, so a red-flagged message reads back
+    // here with no flagColor (and flagColor: "red" in search-messages also
+    // matches a plain flag). Inherent to Apple's bitfield encoding, not
+    // fixable from the client side; the AppleScript route is unaffected (Mail's
+    // own `flag index` is 0 for red, -1 for none).
+    flagColorIndex,
+    flagColor: flagColorName(flagColorIndex),
     mailbox: path3,
     account,
     // Derived from BODYSTRUCTURE, which the list/search fetch now requests.
@@ -58461,6 +58479,16 @@ async function searchUids(client, path3, criteria, size) {
     `IMAP SEARCH on "${path3}"${sized} failed: ` + (cause ? errText(cause) : "the server rejected it or the connection dropped before it answered (on a mailbox this size, usually a server-side timeout)")
   );
 }
+async function filterUidsByColor(client, uids, colorIndex) {
+  if (uids.length === 0) return uids;
+  const keep = /* @__PURE__ */ new Set();
+  for await (const msg of client.fetch(uids.join(","), { uid: true, flags: true }, { uid: true })) {
+    if (typeof msg?.uid !== "number") continue;
+    const idx = mailFlagColorIndex(msg.flags);
+    if (colorIndex === 0 ? idx === void 0 : idx === colorIndex) keep.add(msg.uid);
+  }
+  return uids.filter((uid) => keep.has(uid));
+}
 function mergeFetched(into, msg) {
   const prev = into.get(msg.uid);
   if (!prev) {
@@ -58616,14 +58644,15 @@ async function listLargeMailbox(client, exists, page) {
     totalExact: true
   };
 }
-async function searchLargeMailbox(client, path3, criteria, exists, page) {
+async function searchLargeMailbox(client, path3, criteria, exists, page, colorIndex) {
   const walk = await walkWindows(exists, page, FIRST_SEARCH_WINDOW, async (lo, hi, width) => {
-    const found = await searchUids(client, path3, { ...criteria, seq: `${lo}:${hi}` }, exists);
+    let found = await searchUids(client, path3, { ...criteria, seq: `${lo}:${hi}` }, exists);
     if (found.length > width) {
       throw new Error(
         `IMAP SEARCH on "${path3}" reported ${found.length} matches in a ${width}-message window \u2014 discarding as corrupted rather than trusting it (see #246).`
       );
     }
+    if (colorIndex !== void 0) found = await filterUidsByColor(client, found, colorIndex);
     return found;
   });
   return {
@@ -58632,14 +58661,14 @@ async function searchLargeMailbox(client, path3, criteria, exists, page) {
     totalExact: walk.exhausted
   };
 }
-async function fetchMailboxMatches(client, path3, criteria, page) {
+async function fetchMailboxMatches(client, path3, criteria, page, colorIndex) {
   const lock = await client.getMailboxLock(path3);
   try {
     const exists = await statusMessageCount(client, path3);
     if (exists === 0) return { messages: [], omitted: [], total: 0, totalExact: true };
     if (exists !== void 0 && exists > LARGE_MAILBOX_MESSAGES) {
       try {
-        return isUnfiltered(criteria) ? await listLargeMailbox(client, exists, page) : await searchLargeMailbox(client, path3, criteria, exists, page);
+        return isUnfiltered(criteria) ? await listLargeMailbox(client, exists, page) : await searchLargeMailbox(client, path3, criteria, exists, page, colorIndex);
       } catch (error2) {
         const detail = errText(error2);
         throw new Error(
@@ -58647,16 +58676,20 @@ async function fetchMailboxMatches(client, path3, criteria, page) {
         );
       }
     }
-    const uids = await searchUids(client, path3, criteria, exists);
-    if (uids.length === 0 || page.take === 0) {
-      return { messages: [], omitted: [], total: uids.length, totalExact: true };
+    const rawUids = await searchUids(client, path3, criteria, exists);
+    if (rawUids.length === 0) {
+      return { messages: [], omitted: [], total: 0, totalExact: true };
     }
     const messages = exists ?? (await client.status(path3, { messages: true })).messages ?? void 0;
-    if (typeof messages === "number" && uids.length > messages) {
+    if (typeof messages === "number" && rawUids.length > messages) {
       throw new Error(
-        `IMAP SEARCH on "${path3}" reported ${uids.length} matches, more than the mailbox's own ${messages} messages \u2014 discarding as corrupted rather than trusting it (see #246).`
+        `IMAP SEARCH on "${path3}" reported ${rawUids.length} matches, more than the mailbox's own ${messages} messages \u2014 discarding as corrupted rather than trusting it (see #246).`
       );
     }
+    const uids = colorIndex !== void 0 ? await filterUidsByColor(client, rawUids, colorIndex) : rawUids;
+    if (uids.length === 0 || page.take === 0) {
+      return { messages: [], omitted: [], total: uids.length, totalExact: true };
+    }
     const newest = uids.slice().reverse().slice(page.skip, page.skip + page.take);
     return { ...pageRows(await fetchRows(client, newest)), total: uids.length, totalExact: true };
   } finally {
@@ -58706,7 +58739,7 @@ async function run(args, listMode, deps) {
         }
         try {
           const outcome = await raceStop(
-            fetchMailboxMatches(client, path3, criteria, page),
+            fetchMailboxMatches(client, path3, criteria, page, args.flagColorIndex),
             deps.signal
           );
           if (outcome === STOPPED) {
@@ -59427,6 +59460,9 @@ function mailFlagColorIndex(flags) {
   }
   return any ? idx : void 0;
 }
+function flagColorName(index) {
+  return index === void 0 ? void 0 : FLAG_COLOR_NAMES[index];
+}
 function flagOp(id, flag, add, deps) {
   const ref = decodeImapId(id);
   if (!ref) return Promise.resolve({ success: false, error: `Not an IMAP message id: "${id}".` });
@@ -59940,7 +59976,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, MAX_UNSCOPED_SEARCH_DEPTH, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, DELETED_MARGIN, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, BASE64_TAIL_WINDOW, QP_EXACT_MAX_BYTES, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
+var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, MAX_UNSCOPED_SEARCH_DEPTH, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, DELETED_MARGIN, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, FLAG_COLOR_NAMES, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, BASE64_TAIL_WINDOW, QP_EXACT_MAX_BYTES, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
@@ -60043,6 +60079,15 @@ var init_imapClient = __esm({
     MAX_RFC822_FILE_BYTES = MAX_COMPOSE_SOURCE_BYTES;
     HEADER_WINDOW_BYTES = 64 * 1024;
     MAIL_FLAG_BITS = ["$MailFlagBit0", "$MailFlagBit1", "$MailFlagBit2"];
+    FLAG_COLOR_NAMES = [
+      "red",
+      "orange",
+      "yellow",
+      "green",
+      "blue",
+      "purple",
+      "gray"
+    ];
     imapMarkRead = (id, deps = {}) => flagOp(id, "\\Seen", true, deps);
     imapMarkUnread = (id, deps = {}) => flagOp(id, "\\Seen", false, deps);
     FALLBACK_TRASH_PATH = "Trash";