apple-tools-mcp 3.0.8 → 3.1.0

package/README.md

@@ -259,6 +259,7 @@ Your client can also call `audit_index`.
 | `mail_senders` | Most frequent senders. |
 | `mail_thread` | Every email in a conversation. |
 | `mail_find` | Exact lookup in Mail's own database by subject prefix or text, sender, recipient, mailbox, and date. Returns every copy with its Message-ID. Does not wait on the index. |
+| `mail_links` | The links in one email (by its `mail_find` id), decoded, with each link's visible text. Use it for the URL behind a button, such as a sign-in link; `mail_read` drops link targets. Does not wait on the index. |
 
 ### Messages
 

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

@@ -41,6 +41,7 @@ import { startWriteBridgeServer, defaultSocketPath } from "./lib/writeBridge.js"
 import { closeEventKitSession, ensureEventKitSession } from "./lib/eventKitSession.js";
 import { EVENTKIT_JXA_HELPERS } from "./lib/calendarWrite.js";
 import { mailFind, MAILBOX_KINDS, MAIL_FIND_MAX_LIMIT } from "./lib/mailFind.js";
+import { mailLinks } from "./lib/mailLinks.js";
 
 const PACKAGE_VERSION = JSON.parse(
   fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")
@@ -1174,6 +1175,17 @@ function createServer() {
           },
         },
       },
+      {
+        name: "mail_links",
+        description: "Links in one email, decoded: each http(s) link with its visible text, from the HTML anchors (quoted-printable and base64 decoded, & unescaped) and bare URLs in the plain-text part. Use the id from mail_find. mail_read strips HTML, so it loses link targets; use this when you need the URL behind a button such as a sign-in or confirm link. Reads Mail's message file directly and never waits on the index. downloaded:false means Mail has not saved the file yet.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "number", description: "Message id from mail_find (Mail's Envelope Index id)" }
+          },
+          required: ["id"],
+        },
+      },
 
       // ============ MESSAGES TOOLS ============
       {
@@ -1185,7 +1197,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 +1208,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 +1223,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"],
@@ -1480,6 +1492,10 @@ function createServer() {
           result = mailFind(args || {});
           break;
 
+        case "mail_links":
+          result = mailLinks(args || {});
+          break;
+
         // Messages tools
         case "messages_search":
           result = await messagesSearch(args.query, {

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/mailLinks.js

@@ -0,0 +1,294 @@
+/**
+ * mail_links: the links in one message, decoded, by its Envelope Index id.
+ *
+ * mail_read strips HTML, which drops every link target, and it reads the
+ * .emlx without MIME decoding, so a quoted-printable URL comes back broken
+ * across soft line breaks. Sign-in emails (magic links, confirm links) put
+ * the one thing a caller needs behind an <a href>. This reads the message
+ * file Mail keeps for the id mail_find returns, decodes its MIME parts
+ * (multipart, quoted-printable, base64, charset), and returns each http(s)
+ * link with its visible text.
+ *
+ * Read-only. Needs the same Full Disk Access as mail_find and the indexer.
+ */
+
+import fs from "fs";
+import path from "path";
+import { envelopeIndexPath, parseMailboxUrl, ENVELOPE_INDEX_ACCESS_GUIDANCE } from "./mailFind.js";
+import { safeSqlite3Json } from "./shell.js";
+import { stripHtmlTags } from "./validators.js";
+
+export const MAIL_LINKS_MAX = 200;
+const MAX_MESSAGE_BYTES = 20 * 1024 * 1024;
+const MAX_HTML_CHARS = 2_000_000;
+const MAX_MIME_DEPTH = 8;
+
+/** The RFC822 bytes inside an .emlx (first line is the byte count; a plist trails the message). */
+export function emlxMessageBytes(buf) {
+  const nl = buf.indexOf(0x0a);
+  const count = nl > 0 ? Number.parseInt(buf.subarray(0, nl).toString("ascii").trim(), 10) : NaN;
+  if (!Number.isFinite(count) || count <= 0) return buf;
+  return buf.subarray(nl + 1, Math.min(buf.length, nl + 1 + count));
+}
+
+function splitHeaderBody(buf) {
+  const crlf = buf.indexOf("\r\n\r\n");
+  const lf = buf.indexOf("\n\n");
+  if (crlf >= 0 && (lf < 0 || crlf < lf)) return [buf.subarray(0, crlf).toString("latin1"), buf.subarray(crlf + 4)];
+  if (lf >= 0) return [buf.subarray(0, lf).toString("latin1"), buf.subarray(lf + 2)];
+  return [buf.toString("latin1"), Buffer.alloc(0)];
+}
+
+function parseHeaders(text) {
+  const headers = new Map();
+  for (const line of text.replace(/\r?\n[ \t]+/g, " ").split(/\r?\n/)) {
+    const i = line.indexOf(":");
+    if (i > 0) headers.set(line.slice(0, i).trim().toLowerCase(), line.slice(i + 1).trim());
+  }
+  return headers;
+}
+
+/** `text/html; charset="utf-8"` → { type: "text/html", params: { charset: "utf-8" } } */
+export function parseContentType(value) {
+  const [type, ...rest] = String(value || "text/plain").split(";");
+  const params = {};
+  for (const p of rest) {
+    const i = p.indexOf("=");
+    if (i > 0) params[p.slice(0, i).trim().toLowerCase()] = p.slice(i + 1).trim().replace(/^"(.*)"$/, "$1");
+  }
+  return { type: type.trim().toLowerCase(), params };
+}
+
+export function decodeQuotedPrintable(buf) {
+  const s = buf.toString("latin1").replace(/=\r?\n/g, "");
+  const out = Buffer.alloc(s.length);
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "=" && /^[0-9A-Fa-f]{2}$/.test(s.slice(i + 1, i + 3))) {
+      out[n++] = Number.parseInt(s.slice(i + 1, i + 3), 16);
+      i += 2;
+    } else {
+      out[n++] = s.charCodeAt(i) & 0xff;
+    }
+  }
+  return out.subarray(0, n);
+}
+
+function decodeText(buf, encoding, charset) {
+  const enc = String(encoding || "").toLowerCase();
+  const bytes =
+    enc === "quoted-printable"
+      ? decodeQuotedPrintable(buf)
+      : enc === "base64"
+        ? Buffer.from(buf.toString("latin1").replace(/[^A-Za-z0-9+/=]/g, ""), "base64")
+        : buf;
+  try {
+    return new TextDecoder(charset || "utf-8").decode(bytes);
+  } catch {
+    return new TextDecoder("utf-8").decode(bytes);
+  }
+}
+
+/** Text leaves of a MIME message: [{ type, text }] for text/html and text/plain parts. */
+export function mimeTextParts(buf, depth = 0) {
+  const [headerText, body] = splitHeaderBody(buf);
+  const headers = parseHeaders(headerText);
+  const { type, params } = parseContentType(headers.get("content-type"));
+  if (type.startsWith("multipart/") && params.boundary && depth < MAX_MIME_DEPTH) {
+    const marker = Buffer.from(`--${params.boundary}`, "latin1");
+    const parts = [];
+    let start = body.indexOf(marker);
+    while (start >= 0) {
+      const afterMarker = start + marker.length;
+      if (body.subarray(afterMarker, afterMarker + 2).toString("latin1") === "--") break;
+      const next = body.indexOf(marker, afterMarker);
+      let chunk = body.subarray(afterMarker, next >= 0 ? next : body.length);
+      chunk = chunk.subarray(chunk[0] === 0x0d && chunk[1] === 0x0a ? 2 : chunk[0] === 0x0a ? 1 : 0);
+      parts.push(...mimeTextParts(chunk, depth + 1));
+      start = next;
+    }
+    return parts;
+  }
+  if (type !== "text/html" && type !== "text/plain") return [];
+  return [{ type, text: decodeText(body, headers.get("content-transfer-encoding"), params.charset) }];
+}
+
+export function decodeHtmlEntities(s) {
+  return String(s)
+    .replace(/&#x([0-9a-f]{1,6});/gi, (_, h) => safeCodePoint(Number.parseInt(h, 16)))
+    .replace(/&#([0-9]{1,7});/g, (_, d) => safeCodePoint(Number.parseInt(d, 10)))
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;|&apos;/gi, "'")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&");
+}
+
+function safeCodePoint(n) {
+  return Number.isInteger(n) && n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : "";
+}
+
+function isHttpUrl(url) {
+  return /^https?:\/\/[^\s]+$/i.test(url);
+}
+
+function attrValue(tag, name) {
+  const lower = tag.toLowerCase();
+  let from = 0;
+  for (;;) {
+    const i = lower.indexOf(name, from);
+    if (i < 0) return null;
+    from = i + name.length;
+    if (i > 0 && !/\s/.test(tag[i - 1])) continue;
+    let j = from;
+    while (j < tag.length && /\s/.test(tag[j])) j++;
+    if (tag[j] !== "=") continue;
+    j++;
+    while (j < tag.length && /\s/.test(tag[j])) j++;
+    const q = tag[j];
+    if (q === '"' || q === "'") {
+      const end = tag.indexOf(q, j + 1);
+      return end < 0 ? null : tag.slice(j + 1, end);
+    }
+    let end = j;
+    while (end < tag.length && !/[\s>]/.test(tag[end])) end++;
+    return tag.slice(j, end);
+  }
+}
+
+/** <a href> links in HTML as { text, url }, scanned without regex backtracking. */
+export function htmlLinks(html) {
+  const s = String(html || "").slice(0, MAX_HTML_CHARS);
+  const lower = s.toLowerCase();
+  const links = [];
+  let pos = 0;
+  while (links.length < MAIL_LINKS_MAX) {
+    const open = lower.indexOf("<a", pos);
+    if (open < 0) break;
+    pos = open + 2;
+    if (!/[\s>]/.test(s[open + 2] || "")) continue;
+    let tagEnd = open + 2;
+    let quote = null;
+    for (; tagEnd < s.length; tagEnd++) {
+      const c = s[tagEnd];
+      if (quote) {
+        if (c === quote) quote = null;
+      } else if (c === '"' || c === "'") {
+        quote = c;
+      } else if (c === ">") {
+        break;
+      }
+    }
+    if (tagEnd >= s.length) break;
+    const close = lower.indexOf("</a", tagEnd);
+    const nextOpen = lower.indexOf("<a", tagEnd);
+    // An unclosed anchor's text runs to the next anchor (or the end).
+    const textEnd = close >= 0 && (nextOpen < 0 || close < nextOpen) ? close : nextOpen >= 0 ? nextOpen : s.length;
+    const inner = s.slice(tagEnd + 1, textEnd);
+    pos = textEnd === close ? close + 3 : textEnd;
+    const href = attrValue(s.slice(open, tagEnd), "href");
+    const url = href == null ? "" : decodeHtmlEntities(href.trim());
+    if (!isHttpUrl(url)) continue;
+    links.push({ text: decodeHtmlEntities(stripHtmlTags(inner)).replace(/\s+/g, " ").trim(), url });
+  }
+  return links;
+}
+
+/** Bare http(s) URLs in plain text. */
+export function textLinks(text) {
+  const found = String(text || "").slice(0, MAX_HTML_CHARS).match(/https?:\/\/[^\s<>"'`)\]]+/g) || [];
+  return found.slice(0, MAIL_LINKS_MAX).map((url) => ({ text: "", url: url.replace(/[.,;:!?]+$/, "") }));
+}
+
+/** Links from a decoded message: HTML anchors first, then plain-text URLs not already listed. */
+export function messageLinks(rfc822) {
+  const parts = mimeTextParts(rfc822);
+  const links = [];
+  const seen = new Set();
+  const add = (l) => {
+    if (links.length >= MAIL_LINKS_MAX || seen.has(`${l.text}\n${l.url}`)) return;
+    seen.add(`${l.text}\n${l.url}`);
+    links.push(l);
+  };
+  for (const p of parts) if (p.type === "text/html") htmlLinks(p.text).forEach(add);
+  const urls = new Set(links.map((l) => l.url));
+  for (const p of parts) if (p.type === "text/plain") textLinks(p.text).filter((l) => !urls.has(l.url)).forEach(add);
+  return links;
+}
+
+/** Mail's sharded folder for a message id: 73690 → Data/3/7/Messages (digits of id/1000, reversed). */
+export function messageDataDir(id) {
+  const thousands = Math.floor(id / 1000);
+  const shards = thousands > 0 ? String(thousands).split("").reverse() : [];
+  return path.join("Data", ...shards, "Messages");
+}
+
+/**
+ * Where Mail keeps `id`'s message file for mailbox `mailboxUrl`.
+ * `file` is the .emlx (or .partial.emlx) path, or null. `mailboxFound` says
+ * whether the mailbox folder itself was found, so a caller can tell "not
+ * saved yet" (worth retrying) from "cannot locate this mailbox" (not).
+ * Account mailboxes live under V<n>/<account id>/; On My Mac mailboxes
+ * without an account id live under V<n>/Mailboxes/.
+ */
+export function locateEmlx(id, mailboxUrl, { indexPath } = {}) {
+  const box = parseMailboxUrl(mailboxUrl);
+  const db = indexPath || envelopeIndexPath();
+  if (!box || !db) return { file: null, mailboxFound: false };
+  const versionDir = path.dirname(path.dirname(db));
+  const base = box.accountId ? path.join(versionDir, box.accountId) : path.join(versionDir, "Mailboxes");
+  const segments = box.mailboxPath.split("/").filter(Boolean);
+  if (!segments.length || segments.some((p) => p === "." || p === "..")) return { file: null, mailboxFound: false };
+  const mboxDir = path.join(base, ...segments.map((p) => `${p}.mbox`));
+  let stores;
+  try {
+    stores = fs.readdirSync(mboxDir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.endsWith(".mbox"));
+  } catch {
+    return { file: null, mailboxFound: false };
+  }
+  const rel = messageDataDir(id);
+  for (const store of stores) {
+    for (const name of [`${id}.emlx`, `${id}.partial.emlx`]) {
+      const file = path.join(mboxDir, store.name, rel, name);
+      if (fs.existsSync(file)) return { file, mailboxFound: true };
+    }
+  }
+  return { file: null, mailboxFound: true };
+}
+
+export function validateLinksArgs(args = {}) {
+  const id = Number(args.id);
+  if (!Number.isInteger(id) || id <= 0 || id > 1e12) return { error: "id must be a positive integer (the id from mail_find)" };
+  return { id };
+}
+
+/** mail_links tool entry point. Returns JSON text; throws on invalid args or an unreadable index. */
+export function mailLinks(args = {}, { query = safeSqlite3Json, indexPath, readFile = fs.readFileSync, locate = locateEmlx } = {}) {
+  const { id, error } = validateLinksArgs(args);
+  if (error) throw new Error(`mail_links: ${error}`);
+  const db = indexPath || envelopeIndexPath();
+  if (!db) throw new Error(ENVELOPE_INDEX_ACCESS_GUIDANCE);
+  let rows;
+  try {
+    rows = query(db, `SELECT m.ROWID AS id, mb.url AS mailbox_url FROM messages m JOIN mailboxes mb ON mb.ROWID = m.mailbox WHERE m.ROWID = ${id}`, {
+      readonly: true,
+      timeout: 20000
+    });
+  } catch (e) {
+    if (/unable to open|authoriz|not permitted|denied/i.test(String((e && e.message) || e))) throw new Error(ENVELOPE_INDEX_ACCESS_GUIDANCE);
+    throw e;
+  }
+  if (!rows.length) return JSON.stringify({ id, found: false, note: "No message with that id in Mail's database." }, null, 2);
+  const { file, mailboxFound } = locate(id, rows[0].mailbox_url, { indexPath: db });
+  if (!file && !mailboxFound) {
+    return JSON.stringify({ id, found: true, located: false, note: "Could not find this message's mailbox folder in Mail's data; retrying will not help." }, null, 2);
+  }
+  if (!file) {
+    return JSON.stringify({ id, found: true, downloaded: false, note: "Mail has not saved this message's file yet; try again shortly." }, null, 2);
+  }
+  const buf = readFile(file);
+  if (buf.length > MAX_MESSAGE_BYTES) throw new Error("mail_links: message file is too large to read");
+  const links = messageLinks(emlxMessageBytes(buf));
+  return JSON.stringify({ id, found: true, downloaded: true, count: links.length, links }, null, 2);
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-tools-mcp",
-  "version": "3.0.8",
+  "version": "3.1.0",
   "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");