apple-mail-mcp 2.10.12 → 2.10.14

package/README.md

@@ -579,7 +579,7 @@ Dropped connections reconnect with backoff, and the watchers shut down cleanly o
 
 Enable it in your MCP client config alongside the IMAP settings:
 
-```jsonc
+```json
 {
   "mcpServers": {
     "apple-mail": {
@@ -680,6 +680,20 @@ Return an attachment's bytes as base64 (the read counterpart to inline-base64 se
 
 ---
 
+#### `resolve-message-id`
+
+Map `imap:` message IDs to their numeric Mail.app IDs, via each message's RFC 5322 `Message-ID` (the join key both backends share). Needed only for the two tools that are numeric-ID-only — `reply-to-message` and `forward-message`. Numeric IDs pass through unchanged.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ids` | string[] | Yes | 1–100 message IDs, each numeric or `imap:…` |
+
+**Returns:** For each input ID, its `numericId` (or `null` when it can't be resolved) and the `messageId` used, plus `count` and `resolvedCount`. The lookup scopes to the message's account and checks its INBOX first, to avoid scanning a large All Mail/Archive mailbox.
+
+> **You do not need this for flag colors (v2.10.0+).** Colors used to require the numeric-ID path, and older docs and tool descriptions said so. `flag-message` and `batch-flag-messages` now write the color over IMAP directly, as Mail.app's `$MailFlagBit0/1/2` keywords, so a smart mailbox keyed on flag color matches an IMAP-flagged message. Resolving IDs just to apply a color reintroduces the AppleScript/TCC dependency 2.10.0 removed. Flag, move, mark, and delete all accept `imap:` IDs as-is.
+
+---
+
 #### `reply-to-message`
 
 Reply to an existing message.
@@ -1309,7 +1323,7 @@ This repo ships a `.mcp.json` at its root so that, when you run `claude` from in
 
 The entrypoint is written as:
 
-```json
+```text
 "args": ["${CLAUDE_PROJECT_DIR:-.}/build/index.js"]
 ```
 
@@ -1375,21 +1389,33 @@ When sending content containing backslashes (`\`) to this MCP server, **you must
 
 **Why:** The MCP protocol uses JSON for parameter passing. In JSON, a single backslash is an escape character. To include a literal backslash in content, it must be escaped as `\\`.
 
-**Example - Email with file path:**
+**Correct — email containing a shell path with an escaped space:**
+
 ```json
 {
   "to": ["colleague@company.com"],
   "subject": "File Location",
-  "body": "The file is at C:\\\\Users\\\\Documents\\\\report.pdf"
+  "body": "Run: cp ~/Library/Mobile\\ Documents/report.pdf ~/Desktop/"
 }
 ```
 
-The `\\\\` in JSON becomes `\\` in the actual string, which represents a single `\` in the email.
+→ arrives as: `Run: cp ~/Library/Mobile\ Documents/report.pdf ~/Desktop/`
+
+In a JSON string literal, `\\` — two characters — denotes **one** literal backslash. Four backslashes (`\\\\`) denote **two** literal backslashes, so send those only when the text genuinely contains `\\`.
+
+**Incorrect — the unescaped backslash makes this invalid JSON:**
+
+```text
+"body": "Run: cp ~/Library/Mobile\ Documents/report.pdf ~/Desktop/"
+```
+
+`\ ` (backslash-space) is not a valid JSON escape sequence, so the call is rejected — or, with a laxer parser, the backslash is silently dropped.
 
 **Common patterns requiring escaping:**
-- Windows paths: `C:\Users\` → `C:\\\\Users\\\\` in JSON
-- Shell escaped spaces: `Mobile\ Documents` → `Mobile\\\\ Documents` in JSON
-- Regex patterns: `\d+` → `\\\\d+` in JSON
+
+- Shell escaped spaces: `Mobile\ Documents` → `Mobile\\ Documents` in JSON
+- Regex patterns: `\d+` → `\\d+` in JSON
+- A literal double backslash: `\\` → `\\\\` in JSON
 
 **If you see errors** when sending emails with backslashes, double-check that backslashes are properly escaped in the JSON payload.
 

package/docs/IMAP-SETUP.md

@@ -111,7 +111,7 @@ The server reads `APPLE_MAIL_MCP_*` settings. There are two ways to supply them;
 Works with clients that pass an `env` block through to the server (e.g. **Claude
 Code** via `~/.claude.json`, and most standard `mcpServers` configs).
 
-```jsonc
+```json
 {
   "mcpServers": {
     "apple-mail": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.10.12",
+  "version": "2.10.14",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",
@@ -54,6 +54,7 @@
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "@vitest/coverage-v8": "^4.1.9",
+    "ajv": "^8.17.1",
     "esbuild": "^0.28.1",
     "eslint": "^9.0.0",
     "globals": "^17.0.0",