apple-mail-mcp 2.20.9 → 2.20.10

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,8 +58326,25 @@ 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;
+    Object.assign(c, flagColorSearchTerm(a.flagColorIndex));
+  }
   return c;
 }
+function flagColorSearchTerm(colorIndex) {
+  const { set, clear } = mailFlagBitsFor(colorIndex);
+  const terms = [
+    ...set.map((kw) => ({ keyword: kw })),
+    ...clear.map((kw) => ({ unKeyword: kw }))
+  ];
+  if (terms.length === 0) return {};
+  if (terms.length === 1) return terms[0];
+  const negated = terms.map(
+    (t) => "keyword" in t ? { unKeyword: t.keyword } : { keyword: t.unKeyword }
+  );
+  return { not: { or: negated } };
+}
 function validDate(d) {
   if (!d) return void 0;
   const parsed = d instanceof Date ? d : new Date(d);
@@ -58366,6 +58385,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 +58402,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.
@@ -59427,6 +59459,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 +59975,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 +60078,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";