apple-tools-mcp 3.0.8 → 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/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.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");