apple-tools-mcp 3.0.7 → 3.0.9

package/contacts.js

@@ -104,7 +104,7 @@ function findContactsDatabase() {
  * Normalize phone number for consistent matching
  * Strips all non-digit characters except leading +
  */
-function normalizePhone(phone) {
+export function normalizePhone(phone) {
   if (!phone) return "";
   // Keep leading + for international, then only digits
   const hasPlus = phone.startsWith("+");
@@ -373,6 +373,18 @@ export function resolveByName(name) {
   return matches;
 }
 
+/**
+ * Resolve a name to contacts by exact full name, first name, or nickname
+ * (case-insensitive). No partial matching.
+ * @param {string} name - Name to look up
+ * @returns {object[]} Matching contacts (may be empty)
+ */
+export function resolveByExactName(name) {
+  if (!name) return [];
+  loadContacts();  // Ensure contacts are loaded
+  return nameToContact.get(name.toLowerCase().trim()) || [];
+}
+
 /**
  * Get all identifiers (emails and phones) for a contact
  * @param {number} contactId - Contact ID

package/index.js

@@ -1185,7 +1185,7 @@ function createServer() {
             query: { type: "string", description: "Natural language search (e.g., 'dinner plans', 'about the trip', 'address')" },
             limit: { type: "number", description: "Maximum results (default 30)" },
             days_back: { type: "number", description: "Only messages from last N days (0 = all time)" },
-            contact: { type: "string", description: "Filter by contact name or phone number" },
+            contact: { type: "string", description: "Filter by contact: exact Contacts name (full name, first name, or nickname, e.g. 'Dad'), phone number in any format, or email. Includes my replies in that 1:1 chat." },
             group_chat_only: { type: "boolean", description: "Only show messages from group chats" },
             group_chat_name: { type: "string", description: "Filter by specific group chat name" },
             has_attachment: { type: "boolean", description: "Filter to messages with attachments (photos, files)" },
@@ -1196,7 +1196,7 @@ function createServer() {
       },
       {
         name: "messages_recent",
-        description: "Get most recent messages without semantic search. Use this when the user asks for 'recent messages', 'latest texts', or 'what messages did I get'.",
+        description: "Get most recent messages without semantic search. Use this when the user asks for 'recent messages', 'latest texts', or 'what messages did I get'. My own messages show a To: line naming the contact or group chat they were sent to.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1211,7 +1211,7 @@ function createServer() {
         inputSchema: {
           type: "object",
           properties: {
-            contact: { type: "string", description: "Contact name or phone number" },
+            contact: { type: "string", description: "Exact Contacts name (full name, first name, or nickname, e.g. 'Dad'), phone number in any format, or email. Returns both sides of the 1:1 thread, including my replies." },
             limit: { type: "number", description: "Maximum messages to return (default 50)" }
           },
           required: ["contact"],

package/indexer.js

@@ -16,6 +16,8 @@ import {
 import { safeSqlite3Json, safeOsascript, safeFind } from "./lib/shell.js";
 import { indexUnavailableMessage } from "./lib/indexGate.js";
 import { createLanceTableCache, LANCE_CONNECT_OPTIONS } from "./lib/lancedbTables.js";
+import { createMessageContactMatcher } from "./lib/messageContact.js";
+import { resolveByExactName, normalizePhone } from "./contacts.js";
 
 // Re-export contact functions for use by other modules
 export {
@@ -23,6 +25,8 @@ export {
   resolveEmail,
   resolvePhone,
   resolveByName,
+  resolveByExactName,
+  normalizePhone,
   lookupContact,
   searchContacts,
   getContactIdentifiers,
@@ -1538,7 +1542,7 @@ export async function getRecentMessages(limit = 10, daysBack = 1) {
   try {
     const cutoff = Date.now() - (daysBack * 24 * 60 * 60 * 1000);
     const results = await tables.messages.query()
-      .select(["id", "date", "dateTimestamp", "sender", "text", "chatId", "isGroupChat"])
+      .select(["id", "date", "dateTimestamp", "sender", "text", "chatId", "chatIdentifier", "chatName", "isGroupChat"])
       .toArray();
 
     const filtered = results
@@ -1559,17 +1563,15 @@ export async function getConversation(contact, limit = 50) {
   if (!tables.messages) return [];
 
   try {
-    const contactLower = contact.toLowerCase();
+    const matcher = createMessageContactMatcher(contact, { resolveExactName: resolveByExactName, normalizePhone });
+    if (!matcher) return [];
     const results = await tables.messages.query()
       .select(["id", "date", "dateTimestamp", "sender", "text", "chatId", "chatIdentifier"])
       .toArray();
 
-    // Find messages where sender or chatIdentifier contains the contact
-    const filtered = results.filter(r => {
-      const sender = (r.sender || "").toLowerCase();
-      const chatId = (r.chatIdentifier || "").toLowerCase();
-      return sender.includes(contactLower) || chatId.includes(contactLower);
-    });
+    // Sender or chat handle matches the contact (name resolved to its handles);
+    // from-me rows match through the 1:1 chat's handle
+    const filtered = results.filter(r => matcher.matches(r));
 
     // Sort chronologically (oldest first for conversation view)
     return filtered

package/lib/appleScript.js

@@ -340,7 +340,7 @@ export const MAIL_TCC_GUIDANCE =
  */
 export const MAIL_ACCESSIBILITY_GUIDANCE =
   "macOS denied Accessibility (System Events could not drive Mail's compose window). " +
-  "mail_send / mail_draft fill the body via AX hit-test so Mail does not cite-wrap it (FB11734014); Mail's mailto command does not return an outgoing message on current Mini/MacBook Mail (-2753). " +
+  "mail_send / mail_draft / mail_reply / mail_forward fill the body via System Events so Mail does not cite-wrap it (FB11734014); Mail's mailto command does not return an outgoing message on current Mini/MacBook Mail (-2753). " +
   "Allow node in System Settings → Privacy & Security → Accessibility, and keep Automation → Mail allowed. " +
   "This is not a Mail Automation deny (-1743 / -10004).";
 
@@ -355,7 +355,7 @@ export const SYSTEM_EVENTS_STICKY_DENY_GUIDANCE =
 /** System Events GUI scripting missing — not a Mail send hang. */
 export const MAIL_GUI_SCRIPTING_GUIDANCE =
   "System Events GUI scripting is unavailable for this process, so the body cannot be typed into Mail. " +
-  "mail_send / mail_draft locate the compose body via System Events (title-marker + AX hit-test) so Mail does not cite-wrap the Sent body (FB11734014). " +
+  "mail_send / mail_draft / mail_reply / mail_forward locate the compose body via System Events (title-marker + AX hit-test) so Mail does not cite-wrap the Sent body (FB11734014). " +
   "Allow node → System Events in System Settings → Privacy & Security → Automation (run apple-tools-mcp permissions after install/upgrade) in addition to node → Mail, and keep Accessibility allowed. " +
   SYSTEM_EVENTS_STICKY_DENY_GUIDANCE + " " +
   "This is not a Mail send timeout and not a Mail Automation deny (-1743 / -10004).";

package/lib/mailWrite.js

@@ -22,6 +22,7 @@ import {
   runAppleScript,
   asString,
   asInteger,
+  asBoolean,
   MAIL_TCC_GUIDANCE,
   MAIL_SEND_TIMEOUT_GUIDANCE,
   MAIL_ACCESSIBILITY_GUIDANCE,
@@ -197,6 +198,8 @@ export const SYSTEM_EVENTS_AUTOMATION_PROBE_MARKER = "ATM_SYSTEM_EVENTS_AUTOMATI
 export const MAIL_BODY_MIN_AX_HEIGHT = 50;
 /** Historical Mini Tab count. 2.1.3 finds the body via title-marker + AX hit-test, not Tab. */
 export const MAIL_BODY_TAB_MAX = 6;
+/** Command-Up in the compose body (start of document). Reply/forward prepend uses this instead of Cmd-A. */
+export const MAIL_BODY_START_KEY_CODE = 126;
 /** Mail window titles may truncate; match this many leading subject characters. */
 export const MAIL_COMPOSE_TITLE_MARKER_MAX = 60;
 /** Top-level `UI elements` of process Mail only — never a deep tree walk. */
@@ -507,7 +510,9 @@ function systemEventsGrantKind(result) {
  * — not `set value`, not `AXUIElementSetAttributeValue`. Re-read process
  * `AXFocusedUIElement` and require role `AXWebArea` plus the same position
  * and size. Mismatch is `BODY_FOCUS_UNPROVEN` (draft deleted, nothing sent).
- * Deliver with Cmd-A and clipboard paste. No coordinate click. No Mail
+ * Deliver with clipboard paste. Compose passes replaceBody=true (Cmd-A then
+ * paste). Reply/forward pass false: Command-Up to the top of the body, then
+ * paste, so the quoted original stays. No coordinate click. No Mail
  * `content` / `html content`. AXTitle reads in the title helpers stay inside
  * `tell application "System Events"` (2.1.4 osacompile -2741).
  */
@@ -515,6 +520,7 @@ export function buildMailBodyPasteHandler() {
   const seSecs = asInteger(MAIL_SE_APPLEEVENT_TIMEOUT_SEC, { min: 1, max: 30, field: "seTimeout" });
   const topMax = asInteger(MAIL_COMPOSE_TOP_UI_MAX, { min: 1, max: 64, field: "topUiMax" });
   const tokenId = asInteger(MAIL_RECIPIENT_TOKEN_CHAR_ID, { min: 1, max: 1114111, field: "tokenCharId" });
+  const startKey = asInteger(MAIL_BODY_START_KEY_CODE, { min: 1, max: 127, field: "bodyStartKey" });
   return `property atmProvenBx : -1
 property atmProvenBy : -1
 property atmProvenBw : -1
@@ -561,6 +567,13 @@ on atmTitleMatches(atmTitle, atmMarker)
   return false
 end atmTitleMatches
 
+on atmComposeTitleMarker(atmSubject)
+  set atmText to atmSubject as string
+  if atmText is "" then return "New Message"
+  if (length of atmText) > ${MAIL_COMPOSE_TITLE_MARKER_MAX} then return text 1 thru ${MAIL_COMPOSE_TITLE_MARKER_MAX} of atmText
+  return atmText
+end atmComposeTitleMarker
+
 on atmTopElemExactTitle(atmEl, atmMarker)
   try
     if my atmTitleMatches(name of atmEl as string, atmMarker) then return true
@@ -655,7 +668,7 @@ on atmStopScreenSaver()
   end try
 end atmStopScreenSaver
 
-on atmFillMailBody(bodyText, needle, titleMarker, msg)
+on atmFillMailBody(bodyText, needle, titleMarker, msg, replaceBody)
   try
     tell application "Mail" to activate
     delay 0.25
@@ -767,8 +780,13 @@ on atmFillMailBody(bodyText, needle, titleMarker, msg)
             set hadClip to true
           end try
           try
-            keystroke "a" using command down
-            delay 0.2
+            if replaceBody then
+              keystroke "a" using command down
+              delay 0.2
+            else
+              key code ${startKey} using command down
+              delay 0.2
+            end if
             set the clipboard to bodyText
             delay 0.2
             keystroke "v" using command down
@@ -845,8 +863,9 @@ ${bodyCheck}`;
  * is filled by Probe 3: exact subject title, first AXWebArea under that
  * window (`entire contents`), `set focused of` that element, prove focus
  * (role + position + size) via a fresh AXFocusedUIElement read, then Cmd-A
- * and clipboard paste. No coordinate click. No AXValue write. No Mail
- * `content of` oracle (Mail 16 / macOS 26 stays empty). Missing window or
+ * (`replaceBody` true) and clipboard paste. No coordinate click. No AXValue
+ * write. No Mail `content of` oracle (Mail 16 / macOS 26 stays empty). Missing
+ * window or
  * body is BODY_FOCUS_FAILED; a focus-proof mismatch is BODY_FOCUS_UNPROVEN.
  * Either deletes the draft and sends nothing. Header checks stay. The body
  * needle runs only when the focused element is still that proven body, so a
@@ -865,7 +884,7 @@ export function buildComposeScript({ to, cc, bcc, subject, body, send, html = fa
   const needle = composeBodyNeedle(plainBody);
   const titleMarker = composeTitleMarker(subject);
   const pasteAndVerify = plainBody
-    ? `  atmFillMailBody(${asString(plainBody)}, ${asString(needle)}, ${asString(titleMarker)}, newMessage)
+    ? `  atmFillMailBody(${asString(plainBody)}, ${asString(needle)}, ${asString(titleMarker)}, newMessage, ${asBoolean(true)})
   tell application "Mail"
 ${composeMisdirectChecks({ to, cc, bcc, subject, body: plainBody })}
   end tell`
@@ -1558,35 +1577,110 @@ export function mailCompose(args = {}, { draft = false, indexerMode = isIndexerM
   });
 }
 
+/**
+ * Intro text pasted above a reply/forward quote. Trailing newline keeps the
+ * note from gluing to "On … wrote:". Needle still comes from composeBodyNeedle.
+ */
+export function quoteIntroPasteText(body) {
+  const text = composeNativeBody(body);
+  if (!text) return "";
+  return text.endsWith("\n") ? text : `${text}\n`;
+}
+
+function quoteBodyNeedleCheck(body) {
+  const needle = composeBodyNeedle(body);
+  if (!needle) return "";
+  return `    if my atmFocusedIsProvenBody() then
+      set atmAxVal to my atmAxFocusedValue()
+      if atmAxVal is not "" then
+        if my atmAxValueIsRecipientToken(atmAxVal) is false then
+          if atmAxVal does not contain ${asString(needle)} then error "${BODY_PASTE_MISDIRECTED_SENTINEL}"
+        end if
+      end if
+    end if`;
+}
+
+/**
+ * Probe 3 prepend: visible window title from the live subject, no Cmd-A, no
+ * AppleScript `content`. Mail 16 / macOS 26 leaves `set content` empty, which
+ * is why reply/forward used to send a blank intro.
+ */
+function quoteBodyPasteAndVerify(outgoingVar, body) {
+  const intro = quoteIntroPasteText(body);
+  if (!intro) return "";
+  const bodyCheck = quoteBodyNeedleCheck(intro);
+  return `  tell application "Mail"
+    set atmTitleMarker to my atmComposeTitleMarker(subject of ${outgoingVar} as string)
+  end tell
+  atmFillMailBody(${asString(intro)}, ${asString(composeBodyNeedle(intro))}, atmTitleMarker, ${outgoingVar}, ${asBoolean(false)})
+  tell application "Mail"
+${bodyCheck}
+  end tell`;
+}
+
+function quotePasteGuard(outgoingVar, fillBlock) {
+  if (!fillBlock) return "";
+  return `try
+${fillBlock}
+on error errMsg number errNum
+  try
+    tell application "Mail" to delete ${outgoingVar}
+  end try
+  error errMsg number errNum
+end try
+`;
+}
+
+function finishMailGuiWrite({ action, summary, result, indexerMode, finalize }) {
+  if (
+    !result.ok &&
+    indexerMode &&
+    (isMailGuiScriptingUnavailable(result) || isMailAccessibilityDenial(result))
+  ) {
+    return guiScriptingUnavailableResult(action, summary, result, { indexerMode });
+  }
+  return finalize();
+}
+
 export function buildReplyScript({ messageId, body, replyAll, sendNow }) {
-  return `${findMessageHandler()}
+  const mailSecs = asInteger(MAIL_APPLEEVENT_TIMEOUT_SEC, { min: 1, max: 60, field: "mailTimeout" });
+  const fillBlock = quoteBodyPasteAndVerify("theReply", body);
+  const pasteAndVerify = quotePasteGuard("theReply", fillBlock);
+  const replyAllClause = replyAll ? "with reply to all" : "without reply to all";
+
+  return `${buildMailBodyPasteHandler()}
+${findMessageHandler()}
 
 set theMessage to atmFindMessage(${asString(messageId)})
 tell application "Mail"
-  set theReply to missing value
-  try
-    set theReply to reply theMessage without opening window ${replyAll ? "with reply to all" : "without reply to all"}
-  end try
-  if theReply is missing value then
-    -- Some Mail versions do not return the outgoing message from a reply.
-    -- Fall back to a new message addressed to the original sender.
-    set origSubject to subject of theMessage
-    set origSender to extract address from (sender of theMessage)
-    set theReply to make new outgoing message with properties {subject:("Re: " & origSubject), content:${asString(body)}, visible:false}
-    tell theReply
-      make new to recipient at end of to recipients with properties {address:origSender}
-    end tell
-  else
-    tell theReply
-      set content to ${asString(body)} & return & content
-    end tell
-  end if
-  ${sendNow ? "send theReply" : "save theReply"}
+  with timeout of ${mailSecs} seconds
+    set theReply to missing value
+    try
+      set theReply to reply theMessage with opening window ${replyAllClause}
+    end try
+    if theReply is missing value then
+      -- Some Mail versions do not return the outgoing message from a reply.
+      -- Fall back to a new visible message addressed to the original sender.
+      -- Never set AppleScript content (Mail 16 / macOS 26 stays empty).
+      set origSubject to subject of theMessage
+      set origSender to extract address from (sender of theMessage)
+      set theReply to make new outgoing message with properties {subject:("Re: " & origSubject), visible:true}
+      tell theReply
+        make new to recipient at end of to recipients with properties {address:origSender}
+      end tell
+    end if
+    activate
+  end timeout
+end tell
+${pasteAndVerify}tell application "Mail"
+  with timeout of ${mailSecs} seconds
+    ${sendNow ? "send theReply" : "save theReply"}
+  end timeout
 end tell
 return "OK"`;
 }
 
-export function mailReply(args = {}) {
+export function mailReply(args = {}, { indexerMode = isIndexerMode() } = {}) {
   const action = "mail_reply";
   const resolved = resolveMailMessageId({ messageId: args.message_id, filePath: args.file_path });
   if (resolved.error) return { ok: false, message: `${action} refused: ${resolved.error}` };
@@ -1609,47 +1703,72 @@ export function mailReply(args = {}) {
   });
   if (!plan.proceed) return plannedWriteResult(plan);
 
+  if (quoteIntroPasteText(body.text)) {
+    const se = probeSystemEventsGui();
+    if (!se.ok) {
+      return guiScriptingUnavailableResult(action, summary, se, { indexerMode });
+    }
+  }
+
   const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
+  wakeDisplay();
   const result = runAppleScript(
     buildReplyScript({ messageId: resolved.messageId, body: body.text, replyAll, sendNow }),
     { timeout: MAIL_FIND_AND_SEND_TIMEOUT_MS, appName: "Mail" }
   );
-  return finalizeMailWrite({
+  return finishMailGuiWrite({
     action,
     summary,
     result,
-    secrets: [body.text],
-    sendNow,
-    inReplyTo: sendNow ? resolved.messageId : null,
-    successSummary: sendNow ? "reply sent" : "reply saved to Drafts",
-    details: {
-      message_id: resolved.messageId,
-      reply_all: String(replyAll)
-    },
-    deadlineMs
+    indexerMode,
+    finalize: () => finalizeMailWrite({
+      action,
+      summary,
+      result,
+      secrets: [body.text],
+      sendNow,
+      inReplyTo: sendNow ? resolved.messageId : null,
+      successSummary: sendNow ? "reply sent" : "reply saved to Drafts",
+      details: {
+        message_id: resolved.messageId,
+        reply_all: String(replyAll)
+      },
+      deadlineMs
+    })
   });
 }
 
 export function buildForwardScript({ messageId, to, body, sendNow }) {
-  return `${findMessageHandler()}
+  const mailSecs = asInteger(MAIL_APPLEEVENT_TIMEOUT_SEC, { min: 1, max: 60, field: "mailTimeout" });
+  const fillBlock = quoteBodyPasteAndVerify("theForward", body);
+  const pasteAndVerify = quotePasteGuard("theForward", fillBlock);
+  const handlers = fillBlock ? `${buildMailBodyPasteHandler()}\n` : "";
+
+  return `${handlers}${findMessageHandler()}
 
 set theMessage to atmFindMessage(${asString(messageId)})
 tell application "Mail"
-  set theForward to missing value
-  try
-    set theForward to forward theMessage without opening window
-  end try
-  if theForward is missing value then error "FORWARD_UNSUPPORTED"
-  tell theForward
-    set content to ${asString(body)} & return & content
+  with timeout of ${mailSecs} seconds
+    set theForward to missing value
+    try
+      set theForward to forward theMessage with opening window
+    end try
+    if theForward is missing value then error "FORWARD_UNSUPPORTED"
+    tell theForward
 ${to.map((address) => `    make new to recipient at end of to recipients with properties {address:${asString(address)}}`).join("\n")}
-  end tell
-  ${sendNow ? "send theForward" : "save theForward"}
+    end tell
+    activate
+  end timeout
+end tell
+${pasteAndVerify}tell application "Mail"
+  with timeout of ${mailSecs} seconds
+    ${sendNow ? "send theForward" : "save theForward"}
+  end timeout
 end tell
 return "OK"`;
 }
 
-export function mailForward(args = {}) {
+export function mailForward(args = {}, { indexerMode = isIndexerMode() } = {}) {
   const action = "mail_forward";
   const resolved = resolveMailMessageId({ messageId: args.message_id, filePath: args.file_path });
   if (resolved.error) return { ok: false, message: `${action} refused: ${resolved.error}` };
@@ -1674,25 +1793,39 @@ export function mailForward(args = {}) {
   });
   if (!plan.proceed) return plannedWriteResult(plan);
 
+  if (quoteIntroPasteText(body.text)) {
+    const se = probeSystemEventsGui();
+    if (!se.ok) {
+      return guiScriptingUnavailableResult(action, summary, se, { indexerMode });
+    }
+  }
+
   const deadlineMs = sentVerifyClock.now() + MCP_CALL_DEADLINE_MS;
+  wakeDisplay();
   const result = runAppleScript(
     buildForwardScript({ messageId: resolved.messageId, to: to.addresses, body: body.text, sendNow }),
     { timeout: MAIL_FIND_AND_SEND_TIMEOUT_MS, appName: "Mail" }
   );
-  return finalizeMailWrite({
+  return finishMailGuiWrite({
     action,
     summary,
     result,
-    secrets: [body.text],
-    sendNow,
-    inReplyTo: sendNow ? resolved.messageId : null,
-    forwardTo: sendNow ? to.addresses : null,
-    successSummary: sendNow ? "forwarded" : "forward saved to Drafts",
-    details: {
-      message_id: resolved.messageId,
-      to: to.addresses.join(", ")
-    },
-    deadlineMs
+    indexerMode,
+    finalize: () => finalizeMailWrite({
+      action,
+      summary,
+      result,
+      secrets: [body.text],
+      sendNow,
+      inReplyTo: sendNow ? resolved.messageId : null,
+      forwardTo: sendNow ? to.addresses : null,
+      successSummary: sendNow ? "forwarded" : "forward saved to Drafts",
+      details: {
+        message_id: resolved.messageId,
+        to: to.addresses.join(", ")
+      },
+      deadlineMs
+    })
   });
 }
 

package/lib/messageContact.js

@@ -0,0 +1,106 @@
+/**
+ * Contact matching and peer naming for indexed Messages rows.
+ *
+ * Rows carry raw handles (`sender` is a phone/email or "Me"; `chatIdentifier`
+ * is the other party's handle in a 1:1 chat, or "chatNNN" for a group). Tool
+ * output shows contact names, so callers pass names back ("Dad"). These helpers
+ * map that name to handles and tell a reader who a from-me row was sent to.
+ *
+ * Lookups are injected so the logic is testable without the AddressBook.
+ */
+
+const MIN_PHONE_DIGITS = 7;
+
+function looksLikeEmail(value) {
+  return value.includes("@");
+}
+
+function looksLikePhone(value) {
+  return value.replace(/\D/g, "").length >= MIN_PHONE_DIGITS;
+}
+
+/**
+ * Build a predicate that matches message rows to a caller-supplied contact.
+ *
+ * Keeps the old raw substring match on sender / chatIdentifier, and adds:
+ * - phone input matched on normalized digits (605-360-2675 == +16053602675)
+ * - email input matched exactly (case-insensitive)
+ * - a name matched exactly (full name, first name, or nickname) against
+ *   Contacts, then every phone and email on those contacts. No fuzzy name
+ *   matching: a short name must not pull in other people's threads.
+ *
+ * @param {string} contact - Name, phone, or email
+ * @param {object} deps
+ * @param {(name: string) => object[]} deps.resolveExactName - contacts with that exact name
+ * @param {(phone: string) => string} deps.normalizePhone
+ * @returns {{ matches: (row: object) => boolean, isName: boolean, resolvedCount: number } | null}
+ */
+export function createMessageContactMatcher(contact, { resolveExactName, normalizePhone }) {
+  const raw = String(contact || "").trim().toLowerCase();
+  if (!raw) return null;
+
+  const phones = new Set();
+  const emails = new Set();
+  const isName = !looksLikeEmail(raw) && !looksLikePhone(raw);
+  let resolvedCount = 0;
+
+  if (looksLikeEmail(raw)) {
+    emails.add(raw);
+  } else if (looksLikePhone(raw)) {
+    const normalized = normalizePhone(raw);
+    if (normalized) phones.add(normalized);
+  } else {
+    const people = resolveExactName(raw) || [];
+    resolvedCount = people.length;
+    for (const person of people) {
+      for (const p of person.phones || []) {
+        const normalized = p.normalized || normalizePhone(p.phone || "");
+        if (normalized) phones.add(normalized);
+      }
+      for (const e of person.emails || []) {
+        if (e.email) emails.add(e.email.toLowerCase());
+      }
+    }
+  }
+
+  const fieldMatches = (value) => {
+    const lower = String(value || "").toLowerCase();
+    if (!lower || lower === "me" || lower === "unknown") return false;
+    if (lower.includes(raw)) return true;
+    if (emails.has(lower)) return true;
+    if (phones.size > 0 && !looksLikeEmail(lower)) {
+      const normalized = normalizePhone(lower);
+      if (normalized && phones.has(normalized)) return true;
+    }
+    return false;
+  };
+
+  return {
+    matches: (row) => fieldMatches(row.sender) || fieldMatches(row.chatIdentifier),
+    isName,
+    resolvedCount
+  };
+}
+
+/**
+ * Name the other side of a from-me row, so "Me" lines say who they went to.
+ *
+ * @param {object} row - Indexed message row (chatIdentifier, chatName, isGroupChat)
+ * @param {object} deps
+ * @param {(phone: string) => object|null} deps.resolvePhone
+ * @param {(email: string) => object|null} deps.resolveEmail
+ * @param {(contact: object) => string} deps.formatContact
+ * @returns {string|null} e.g. "Dad (+16053602675)", "group chat \"Family\"", or null
+ */
+export function describeMessagePeer(row, { resolvePhone, resolveEmail, formatContact }) {
+  const chatIdentifier = row.chatIdentifier || "";
+  if (row.isGroupChat) {
+    if (row.chatName) return `group chat "${row.chatName}"`;
+    return chatIdentifier ? `group chat ${chatIdentifier}` : "group chat";
+  }
+  if (!chatIdentifier) return null;
+  const person = looksLikeEmail(chatIdentifier)
+    ? resolveEmail(chatIdentifier)
+    : resolvePhone(chatIdentifier);
+  return person ? `${formatContact(person)} (${chatIdentifier})` : chatIdentifier;
+}

package/lib/writeTools.js

@@ -82,12 +82,12 @@ export const WRITE_TOOL_DEFINITIONS = [
   },
   {
     name: "mail_reply",
-    description: "Reply to an existing email. reply_all=true fans out to every original recipient and requires confirm=true. A real send is verified in Sent/Outbox before success. A send hang is a timeout, not TCC, unless Mail reports -1743/-10004; hang recover uses In-Reply-To. Clients must Sent-check before retrying a timed-out send.",
+    description: "Reply to an existing email. The reply text is pasted above the quoted original in a visible Mail window (System Events focus on the message body, then Command-Up and clipboard paste — not Cmd-A, which would replace the quote; AppleScript content is not set because Mail 16 leaves it empty). reply_all=true fans out to every original recipient and requires confirm=true. A real send is verified in Sent/Outbox before success. A send hang is a timeout, not TCC, unless Mail reports -1743/-10004; hang recover uses In-Reply-To. Clients must Sent-check before retrying a timed-out send.",
     inputSchema: {
       type: "object",
       properties: {
         ...MESSAGE_TARGET_PROPS,
-        body: { type: "string", description: "Reply text, prepended above the quoted original (required)" },
+        body: { type: "string", description: "Reply text, prepended above the quoted original via System Events paste (required). AppleScript content is not set." },
         reply_all: { type: "boolean", description: "Reply to all original recipients (default false)" },
         save_as_draft: { type: "boolean", description: "Save the reply to Drafts instead of sending (default false)" },
         ...CONFIRM_PROPS
@@ -97,13 +97,13 @@ export const WRITE_TOOL_DEFINITIONS = [
   },
   {
     name: "mail_forward",
-    description: "Forward an existing email to new recipients. More than one recipient requires confirm=true. A real send is verified in Sent/Outbox before success. A send hang is a timeout, not TCC, unless Mail reports -1743/-10004; hang recover matches intended To plus Fwd: subject or original Message-ID. Clients must Sent-check before retrying a timed-out send.",
+    description: "Forward an existing email to new recipients. An optional note is pasted above the forwarded original in a visible Mail window (same System Events prepend as mail_reply; AppleScript content is not set). More than one recipient requires confirm=true. A real send is verified in Sent/Outbox before success. A send hang is a timeout, not TCC, unless Mail reports -1743/-10004; hang recover matches intended To plus Fwd: subject or original Message-ID. Clients must Sent-check before retrying a timed-out send.",
     inputSchema: {
       type: "object",
       properties: {
         ...MESSAGE_TARGET_PROPS,
         to: { type: "array", items: { type: "string" }, description: "Forward recipients (required, at least one)" },
-        body: { type: "string", description: "Optional note added above the forwarded message" },
+        body: { type: "string", description: "Optional note pasted above the forwarded message (System Events prepend; omitted note skips paste)" },
         save_as_draft: { type: "boolean", description: "Save the forward to Drafts instead of sending (default false)" },
         ...CONFIRM_PROPS
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-tools-mcp",
-  "version": "3.0.7",
+  "version": "3.0.9",
   "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",

package/search.js

@@ -1,7 +1,8 @@
 import * as chrono from "chrono-node";
 import { safeOsascript } from "./lib/shell.js";
 import { safeMatch, validateSearchQuery, toUnixMillis } from "./lib/validators.js";
-import { embed, getOpenTable, getRecentEmails, getEmailsByDateRange, getRecentMessages, getConversation, getEventsOnDate, resolveEmail, resolvePhone, formatContact } from "./indexer.js";
+import { embed, getOpenTable, getRecentEmails, getEmailsByDateRange, getRecentMessages, getConversation, getEventsOnDate, resolveEmail, resolvePhone, resolveByExactName, normalizePhone, formatContact } from "./indexer.js";
+import { createMessageContactMatcher, describeMessagePeer } from "./lib/messageContact.js";
 import { indexUnavailableMessage } from "./lib/indexGate.js";
 
 // ============ CACHING ============
@@ -1024,12 +1025,8 @@ export async function searchMessages(query, options = {}) {
     }
 
     if (contact) {
-      const contactLower = contact.toLowerCase();
-      results = results.filter(r => {
-        const sender = (r.sender || "").toLowerCase();
-        const chatId = (r.chatIdentifier || "").toLowerCase();
-        return sender.includes(contactLower) || chatId.includes(contactLower);
-      });
+      const matcher = createMessageContactMatcher(contact, { resolveExactName: resolveByExactName, normalizePhone });
+      if (matcher) results = results.filter(r => matcher.matches(r));
     }
 
     if (groupChatOnly) {
@@ -1057,7 +1054,11 @@ export async function searchMessages(query, options = {}) {
     if (results.length === 0) {
       let filterMsg = "";
       if (daysBack > 0) filterMsg += ` in the last ${daysBack} days`;
-      if (contact) filterMsg += ` with ${contact}`;
+      if (contact) {
+        filterMsg += ` with ${contact}`;
+        const matcher = createMessageContactMatcher(contact, { resolveExactName: resolveByExactName, normalizePhone });
+        if (matcher?.isName && matcher.resolvedCount === 0) filterMsg += ` (no contact named "${contact}")`;
+      }
       if (groupChatOnly) filterMsg += " in group chats";
       if (groupChatName) filterMsg += ` in "${groupChatName}"`;
       if (hasAttachment) filterMsg += " with attachments";
@@ -1082,6 +1083,7 @@ export async function searchMessages(query, options = {}) {
         dateTimestamp: toUnixMillis(row.dateTimestamp) || null,
         sender: sender,
         senderContact: senderContact,  // Resolved contact name (if found)
+        to: sender === "Me" ? messagePeer(row) : null,
         text: row.text || "",
         chatName: row.chatName || "",
         isGroupChat: row.isGroupChat || false,
@@ -1105,6 +1107,11 @@ export async function searchMessages(query, options = {}) {
   }
 }
 
+// Who a from-me message was sent to (contact name + handle, or the group chat)
+function messagePeer(row) {
+  return describeMessagePeer(row, { resolvePhone, resolveEmail, formatContact });
+}
+
 // Get recent messages without semantic search
 export async function getRecentMessageResults(limit = 10, daysBack = 1) {
   try {
@@ -1125,6 +1132,7 @@ export async function getRecentMessageResults(limit = 10, daysBack = 1) {
         dateTimestamp: toUnixMillis(row.dateTimestamp) || null,
         sender: sender,
         senderContact: senderContact,
+        to: sender === "Me" ? messagePeer(row) : null,
         text: row.text || "",
         isGroupChat: row.isGroupChat || false
       };
@@ -1153,7 +1161,11 @@ export async function getConversationResults(contact, limit = 50) {
     }));
 
     if (formattedResults.length === 0) {
-      return { success: true, results: [], message: `No conversation found with ${contact}` };
+      const matcher = createMessageContactMatcher(contact, { resolveExactName: resolveByExactName, normalizePhone });
+      const hint = matcher?.isName && matcher.resolvedCount === 0
+        ? ` (no contact named "${contact}"; try a phone number or email)`
+        : "";
+      return { success: true, results: [], message: `No conversation found with ${contact}${hint}` };
     }
 
     return { success: true, results: formattedResults, contact };
@@ -1173,6 +1185,7 @@ export function formatMessageResults(searchResult) {
     const senderDisplay = r.senderContact ? `${r.senderContact} (${r.sender})` : r.sender;
     result += `\nDate: ${r.date}\nFrom: ${senderDisplay}`;
     if (r.isGroupChat) result += " (Group)";
+    if (r.to) result += `\nTo: ${r.to}`;
     result += `\nMessage: ${r.text}`;
     return result + "\n---";
   }).join("\n");