apple-mail-mcp 2.9.1 → 2.10.1

package/README.md

@@ -78,9 +78,24 @@ The Codex package registers the same `apple-mail` MCP server through `npx -y app
 
 ### Other Hosts (Hermes, Antigravity)
 
-Configuration for two more hosts is included — each registers the same `apple-mail` MCP server (`npx -y apple-mail-mcp`):
+Two more hosts can run the same `apple-mail` MCP server (`npx -y apple-mail-mcp`):
 
-- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with `hermes mcp add apple-mail --command npx --args -y apple-mail-mcp`, or merge [`.hermes-plugin/config.yaml`](https://github.com/sweetrb/apple-mail-mcp/blob/main/.hermes-plugin/config.yaml) into `~/.hermes/config.yaml`. Details: [`.hermes-plugin/README.md`](https://github.com/sweetrb/apple-mail-mcp/blob/main/.hermes-plugin/README.md).
+- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in, so there is nothing in this repo to install from. Register the server with the CLI:
+
+  ```bash
+  hermes mcp add apple-mail --command npx --args -y apple-mail-mcp
+  ```
+
+  Or add it to `~/.hermes/config.yaml` by hand:
+
+  ```yaml
+  mcp_servers:
+    apple-mail:
+      command: npx
+      args: ["-y", "apple-mail-mcp"]
+  ```
+
+  Restart your Hermes session afterward so the tools load.
 - **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](https://github.com/sweetrb/apple-mail-mcp/blob/main/.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
 
 ### Manual Installation
@@ -731,7 +746,7 @@ Flag or unflag a message. `flag-message` optionally takes a flag **color**; `unf
 | `id` | string | Yes | Message ID |
 | `color` | string | No | (`flag-message` only) Flag color: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `gray` (`grey` accepted). Omit for Mail's default flag. |
 
-**Flag colors** are an Apple Mail feature, applied via AppleScript as the message's `flag index` (0 red, 1 orange, 2 yellow, 3 green, 4 blue, 5 purple, 6 gray) — the same property a Mail smart mailbox can match on. For an **IMAP-routed** message id (`imap:…`) the flag is still set, but the color is **not** applied, because IMAP's `\Flagged` flag is colorless. To color a flag, use the message's AppleScript (numeric) id.
+**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.
 
 ---
 
@@ -814,7 +829,7 @@ All batch operations accept an array of message IDs (max 100 per batch) and retu
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `ids` | string[] | Yes | Message IDs (max 100) |
-| `color` | string | No | (`batch-flag-messages` only) Flag color applied to AppleScript (numeric) ids — see [`flag-message`](#flag-message--unflag-message). Any `imap:` ids in the batch are flagged but not colored. |
+| `color` | string | No | (`batch-flag-messages` only) Flag color — see [`flag-message`](#flag-message--unflag-message). Applied on both routes, so a mixed batch of numeric and `imap:` ids all end up colored. |
 
 ---
 

package/build/index.js

@@ -78120,9 +78120,13 @@ var AppleMailManager = class {
   /**
    * Resolve a message's numeric Mail.app id from its RFC822 Message-ID (the
    * backend-independent join key). This bridges an `imap:` id to the numeric id
-   * required to apply a flag *color* — IMAP flags are colorless, so a smart
-   * mailbox keyed on flag color can only ever match a message flagged via the
-   * AppleScript numeric-id path.
+   * required by the AppleScript-only tools — `reply-to-message` and
+   * `forward-message`.
+   *
+   * Note: flag *color* no longer needs this (since 2.10.0). Mail.app stores the
+   * color as the `$MailFlagBit0/1/2` keywords, which ride alongside `\Flagged`
+   * in an ordinary `UID STORE`, so flag-message/batch-flag-messages color an
+   * `imap:` id directly and a smart mailbox keyed on flag color matches it.
    *
    * The Message-ID is matched both bracketless and `<bracketed>` (Mail returns
    * it bracketless; IMAP envelopes carry the brackets). When `accountName` is
@@ -80234,6 +80238,7 @@ function structuredRow(m, account, path) {
     dateReceived: env.date ? new Date(env.date).toISOString() : "",
     isRead: m.flags?.has("\\Seen") ?? false,
     isFlagged: m.flags?.has("\\Flagged") ?? false,
+    flagColorIndex: mailFlagColorIndex(m.flags),
     mailbox: path,
     account,
     hasAttachments: false,
@@ -80594,6 +80599,28 @@ async function imapFetchMessageId(id, deps = {}) {
     return null;
   }
 }
+var MAIL_FLAG_BITS = ["$MailFlagBit0", "$MailFlagBit1", "$MailFlagBit2"];
+function mailFlagBitsFor(colorIndex) {
+  const set = [];
+  const clear = [];
+  for (let b = 0; b < MAIL_FLAG_BITS.length; b++) {
+    (colorIndex >> b & 1 ? set : clear).push(MAIL_FLAG_BITS[b]);
+  }
+  return { set, clear };
+}
+function mailFlagColorIndex(flags) {
+  if (!flags) return void 0;
+  const have = new Set(flags);
+  let idx = 0;
+  let any = false;
+  for (let b = 0; b < MAIL_FLAG_BITS.length; b++) {
+    if (have.has(MAIL_FLAG_BITS[b])) {
+      idx |= 1 << b;
+      any = true;
+    }
+  }
+  return any ? idx : void 0;
+}
 function flagOp(id, flag, add, deps) {
   const ref = decodeImapId(id);
   if (!ref) return Promise.resolve({ success: false, error: `Not an IMAP message id: "${id}".` });
@@ -80613,8 +80640,38 @@ function flagOp(id, flag, add, deps) {
 }
 var imapMarkRead = (id, deps = {}) => flagOp(id, "\\Seen", true, deps);
 var imapMarkUnread = (id, deps = {}) => flagOp(id, "\\Seen", false, deps);
-var imapFlagMessage = (id, deps = {}) => flagOp(id, "\\Flagged", true, deps);
-var imapUnflagMessage = (id, deps = {}) => flagOp(id, "\\Flagged", false, deps);
+function imapFlagMessage(id, colorIndex, deps = {}) {
+  if (colorIndex === void 0) return flagOp(id, "\\Flagged", true, deps);
+  const ref = decodeImapId(id);
+  if (!ref) return Promise.resolve({ success: false, error: `Not an IMAP message id: "${id}".` });
+  const { set, clear } = mailFlagBitsFor(colorIndex);
+  return withMailbox(ref.path, depsForMessageRef(ref, deps), async (client) => {
+    try {
+      const ok = await client.messageFlagsAdd([ref.uid], ["\\Flagged", ...set], { uid: true });
+      if (!ok)
+        return { success: false, error: `IMAP flag update returned false for UID ${ref.uid}.` };
+      if (clear.length) await client.messageFlagsRemove([ref.uid], clear, { uid: true });
+      return { success: true };
+    } catch (e) {
+      return { success: false, error: `IMAP flag update failed for UID ${ref.uid}: ${errText(e)}` };
+    }
+  });
+}
+function imapUnflagMessage(id, deps = {}) {
+  const ref = decodeImapId(id);
+  if (!ref) return Promise.resolve({ success: false, error: `Not an IMAP message id: "${id}".` });
+  return withMailbox(ref.path, depsForMessageRef(ref, deps), async (client) => {
+    try {
+      const ok = await client.messageFlagsRemove([ref.uid], ["\\Flagged", ...MAIL_FLAG_BITS], {
+        uid: true
+      });
+      if (!ok) return { success: false, error: `IMAP unflag returned false for UID ${ref.uid}.` };
+      return { success: true };
+    } catch (e) {
+      return { success: false, error: `IMAP unflag failed for UID ${ref.uid}: ${errText(e)}` };
+    }
+  });
+}
 async function imapMoveMessageById(id, destMailbox, deps = {}) {
   const ref = decodeImapId(id);
   if (!ref) return { success: false, error: `Not an IMAP message id: "${id}".` };
@@ -80777,11 +80834,17 @@ var imapBatchMarkRead = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids)
 var imapBatchMarkUnread = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
   await c.messageFlagsRemove(uids, ["\\Seen"], { uid: true });
 });
-var imapBatchFlag = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
-  await c.messageFlagsAdd(uids, ["\\Flagged"], { uid: true });
+var imapBatchFlag = (ids, colorIndex, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
+  if (colorIndex === void 0) {
+    await c.messageFlagsAdd(uids, ["\\Flagged"], { uid: true });
+    return;
+  }
+  const { set, clear } = mailFlagBitsFor(colorIndex);
+  await c.messageFlagsAdd(uids, ["\\Flagged", ...set], { uid: true });
+  if (clear.length) await c.messageFlagsRemove(uids, clear, { uid: true });
 });
 var imapBatchUnflag = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
-  await c.messageFlagsRemove(uids, ["\\Flagged"], { uid: true });
+  await c.messageFlagsRemove(uids, ["\\Flagged", ...MAIL_FLAG_BITS], { uid: true });
 });
 var imapBatchDelete = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids, path) => {
   await trashUids(c, uids, path);
@@ -81431,7 +81494,7 @@ var FLAG_COLOR_INDEX = {
   grey: 6
 };
 var FLAG_COLOR_SCHEMA = external_exports.enum(["red", "orange", "yellow", "green", "blue", "purple", "gray", "grey"]).optional().describe(
-  "Optional flag color (Apple Mail palette: red, orange, yellow, green, blue, purple, gray \u2014 'grey' accepted). Omit for Mail's default flag. Colors are applied via Mail.app (AppleScript); for an IMAP-routed message id the flag is set but the color is not applied (IMAP flags are colorless)."
+  "Optional flag color (Apple Mail palette: red, orange, yellow, green, blue, purple, gray \u2014 'grey' accepted). Omit for Mail's default flag. The color is applied on both routes: AppleScript sets the flag index, and IMAP writes the equivalent $MailFlagBit0/1/2 keywords Mail.app reads \u2014 so a smart mailbox keyed on flag color matches either way."
 );
 var DATE_FILTER_SCHEMA = external_exports.string().regex(
   /^[a-zA-Z0-9 ,/\-:]+$/,
@@ -82235,7 +82298,7 @@ server.registerTool(
 server.registerTool(
   "flag-message",
   {
-    description: "Use when: flagging a single message (by id), optionally with a color (red/orange/yellow/green/blue/purple/gray).\nReturns: a confirmation that the message was flagged (and the color, when applied).\nDo not use when: flagging several at once (use batch-flag-messages) or removing a flag (use unflag-message). Get the id from search-messages or list-messages first.\nNote: flag colors are a Mail.app feature applied via AppleScript; for an IMAP-routed id the flag is set but the color is not applied (IMAP flags are colorless).",
+    description: "Use when: flagging a single message (by id), optionally with a color (red/orange/yellow/green/blue/purple/gray).\nReturns: a confirmation that the message was flagged (and the color, when applied).\nDo not use when: flagging several at once (use batch-flag-messages) or removing a flag (use unflag-message). Get the id from search-messages or list-messages first.\nNote: the color is applied on both routes \u2014 AppleScript sets the flag index, IMAP writes the equivalent $MailFlagBit0/1/2 keywords Mail.app reads.",
     inputSchema: {
       id: MESSAGE_ID_SCHEMA,
       color: FLAG_COLOR_SCHEMA
@@ -82250,16 +82313,17 @@ server.registerTool(
   withErrorHandling(({ id, color }) => {
     const colorIndex = color ? FLAG_COLOR_INDEX[color] : void 0;
     return routeMessage(id, {
-      imap: () => imapFlagMessage(id),
+      imap: () => imapFlagMessage(id, colorIndex),
       apple: () => mailManager.flagMessage(id, colorIndex) ? successResponse(color ? `Message flagged (${color})` : "Message flagged", {
         ok: true,
         id,
         ...color ? { color, colorApplied: true } : {}
       }) : errorResponse(`Failed to flag message "${id}"`),
-      // IMAP path: the flag is set, but flag colors are a Mail.app-only feature.
-      ok: color ? `Message flagged. Note: the "${color}" color was not applied \u2014 this is an IMAP-routed message and IMAP flags are colorless.` : "Message flagged",
+      // IMAP path: imapFlagMessage writes the color as $MailFlagBit0/1/2 keywords,
+      // so the outcome matches the AppleScript route above.
+      ok: color ? `Message flagged (${color})` : "Message flagged",
       fail: `Failed to flag message "${id}"`,
-      structured: color ? { ok: true, id, color, colorApplied: false } : { ok: true, id }
+      structured: color ? { ok: true, id, color, colorApplied: true } : { ok: true, id }
     });
   }, "Error flagging message")
 );
@@ -82455,7 +82519,7 @@ server.registerTool(
 server.registerTool(
   "batch-flag-messages",
   {
-    description: "Use when: flagging multiple messages (1\u2013100 ids) in one call, optionally with a color (red/orange/yellow/green/blue/purple/gray).\nReturns: counts of how many were flagged and how many failed.\nDo not use when: flagging just one (use flag-message) or removing flags (use batch-unflag-messages). Get the ids from search-messages or list-messages first.\nNote: flag colors are applied via Mail.app (AppleScript); any IMAP-routed ids in the batch are flagged but not colored (IMAP flags are colorless).",
+    description: "Use when: flagging multiple messages (1\u2013100 ids) in one call, optionally with a color (red/orange/yellow/green/blue/purple/gray).\nReturns: counts of how many were flagged and how many failed.\nDo not use when: flagging just one (use flag-message) or removing flags (use batch-unflag-messages). Get the ids from search-messages or list-messages first.\nNote: the color is applied on both routes \u2014 AppleScript sets the flag index, IMAP writes the equivalent $MailFlagBit0/1/2 keywords Mail.app reads \u2014 so a mixed batch of numeric and `imap:` ids all end up colored.",
     inputSchema: {
       ids: BATCH_IDS_SCHEMA,
       color: FLAG_COLOR_SCHEMA
@@ -82467,7 +82531,7 @@ server.registerTool(
     const { success: successCount, fail: failCount } = await hybridBatchCounts(
       ids,
       (n) => mailManager.batchFlagMessages(n, colorIndex),
-      (im) => imapBatchFlag(im)
+      (im) => imapBatchFlag(im, colorIndex)
     );
     const structured = { ok: failCount === 0, success: successCount, failed: failCount };
     if (failCount === 0) {
@@ -82510,7 +82574,7 @@ server.registerTool(
 server.registerTool(
   "resolve-message-id",
   {
-    description: "Use when: you have `imap:` message id(s) and need the numeric Mail.app id(s) \u2014 most importantly to apply a flag COLOR, which only sticks on the AppleScript numeric-id path (IMAP `\\Flagged` is colorless, so a smart mailbox keyed on flag color never matches an IMAP-flagged message). Each imap: id is resolved via its RFC822 Message-ID.\nReturns: for each input id, its `numericId` (the AppleScript id) or null when it can't be resolved, plus the `messageId` used; and a `resolvedCount`.\nDo not use when: your ids are already numeric (they pass straight through), or you don't need a color \u2014 flag/move/mark tools operate on `imap:` ids directly.",
+    description: "Use when: you have `imap:` message id(s) and genuinely need the numeric Mail.app id(s) \u2014 e.g. for reply-to-message/forward-message, which are numeric-id only. NOTE: as of 2.10.0 you no longer need this to apply a flag COLOR \u2014 flag-message/batch-flag-messages write the color over IMAP directly via Mail.app's $MailFlagBit0/1/2 keywords, so a smart mailbox keyed on flag color matches an IMAP-flagged message. Each imap: id is resolved via its RFC822 Message-ID.\nReturns: for each input id, its `numericId` (the AppleScript id) or null when it can't be resolved, plus the `messageId` used; and a `resolvedCount`.\nDo not use when: your ids are already numeric (they pass straight through), or you don't need a color \u2014 flag/move/mark tools operate on `imap:` ids directly.",
     inputSchema: {
       ids: BATCH_IDS_SCHEMA
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.9.1",
+  "version": "2.10.1",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",
@@ -91,6 +91,6 @@
     "format:check": "prettier --check src",
     "typecheck": "tsc --noEmit",
     "sync:skills": "node scripts/sync-skills.mjs",
-    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .hermes-plugin .antigravity-plugin"
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .antigravity-plugin"
   }
 }