@motionsmith/apple-messages-mcp 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this package are documented here.
 
+## 0.1.1 — 2026-07-23
+
+- Normalize formatted phone numbers when resolving Apple Messages conversations through Contacts.
+- Match both chat identifiers and participant handles, then rank matching chats by recent activity.
+
 ## 0.1.0 — 2026-07-23
 
 - First public release of the Apple Messages MCP protocol library and reusable local macOS helper source.

package/README.md

@@ -1,17 +1,27 @@
 # Apple Messages MCP
 
-`@motionsmith/apple-messages-mcp` is a library-first MCP protocol and reusable local macOS helper
-toolkit for Apple Messages. It is for any consumer that can host a stdio MCP server and provide its
-own status, watch setup, and optional bounded context callbacks. It is not a configuration store,
-approval system, transcript database, or Sugar integration.
+`@motionsmith/apple-messages-mcp` helps a local app or agent read selected Apple Messages
+conversations through MCP. It provides the MCP tools and a small macOS helper; your application
+decides which conversations to watch, how they are configured, and what to do with the results.
 
 Apple Messages data stays on the local Mac. The helper reads the local `chat.db`; the app that
 compiles and runs it needs macOS Full Disk Access. This package never bypasses macOS privacy.
 
+## Is this for me?
+
+This package is a good fit if you are building a local macOS assistant, automation, or MCP host and
+want bounded, read-only access to chosen Messages conversations. It is especially useful when your
+application already has its own configuration and can provide the callbacks shown below.
+
+It is not a ready-to-use Messages app, a hosted service, or a no-code MCP server. It does not send
+messages, sync conversations to the cloud, maintain a transcript archive, choose conversations for
+the user, or avoid the Full Disk Access requirement. Live message reading works only on the Mac
+where the Messages database exists.
+
 ## Install
 
 ```sh
-corepack pnpm add @motionsmith/apple-messages-mcp@0.1.0
+corepack pnpm add @motionsmith/apple-messages-mcp@0.1.1
 ```
 
 The package supports Node 20 or newer and is useful for live helper work only on macOS. The

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const APPLE_MESSAGES_PROVIDER_VERSION = "0.1.0";
+export declare const APPLE_MESSAGES_PROVIDER_VERSION = "0.1.1";
 export declare const MAX_APPLE_MESSAGES_CANDIDATES = 5;
 export type AppleMessagesReadStatus = 'ready' | 'unsupported' | 'missing_config' | 'missing_permission' | 'failed';
 export type AppleMessagesDirection = 'inbound' | 'outbound';

package/dist/index.js

@@ -21,7 +21,7 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const readline_1 = require("readline");
 const process_1 = require("process");
-exports.APPLE_MESSAGES_PROVIDER_VERSION = '0.1.0';
+exports.APPLE_MESSAGES_PROVIDER_VERSION = '0.1.1';
 exports.MAX_APPLE_MESSAGES_CANDIDATES = 5;
 function isAppleMessagesConversationRef(value) {
     return /^apple_messages_conversation_[a-f0-9]{32,64}$/.test(value);

package/helper/apple-messages-helper.swift

@@ -85,11 +85,76 @@ func contactIdentifiers(_ query: String) -> [String] {
   return Array(identifiers).sorted().prefix(10).map { $0 }
 }
 
+struct PhoneLookup {
+  let digits: String
+  let allowsCountryPrefix: Bool
+}
+
+func phoneLookup(_ value: String) -> PhoneLookup? {
+  let punctuation = CharacterSet(charactersIn: "+()- .")
+  guard value.unicodeScalars.allSatisfy({ CharacterSet.decimalDigits.contains($0) || punctuation.contains($0) }) else { return nil }
+  let digits = value.filter(\.isNumber)
+  guard digits.count >= 10 else { return nil }
+  return PhoneLookup(digits: digits, allowsCountryPrefix: !value.trimmingCharacters(in: .whitespacesAndNewlines).hasPrefix("+"))
+}
+
+func normalizedIdentifierPredicate(_ expression: String, _ identifiers: [String]) -> String {
+  let emails = Set(identifiers.map { $0.lowercased() }.filter { $0.contains("@") }).sorted()
+  var phones: [String: Bool] = [:]
+  identifiers.compactMap(phoneLookup).forEach { phone in
+    phones[phone.digits] = (phones[phone.digits] ?? false) || phone.allowsCountryPrefix
+  }
+  var predicates = emails.map { "lower(\(expression)) = \(sqlQuote($0))" }
+  if !phones.isEmpty {
+    let normalized = "replace(replace(replace(replace(replace(replace(lower(\(expression)), '+', ''), '(', ''), ')', ''), '-', ''), ' ', ''), '.', '')"
+    predicates.append("\(normalized) IN (\(phones.keys.sorted().map(sqlQuote).joined(separator: ", ")))")
+    phones.filter(\.value).keys.sorted().forEach { digits in
+      predicates.append("(length(\(normalized)) > \(digits.count) AND length(\(normalized)) <= \(digits.count + 3) AND substr(\(normalized), -\(digits.count)) = \(sqlQuote(digits)))")
+    }
+  }
+  return predicates.joined(separator: " OR ")
+}
+
+func candidateMatchSelect(from: String, chatId: String, exact: String, contact: String, query: String) -> String {
+  let conditions = [exact, contact, query].filter { !$0.isEmpty }
+  var rank = "CASE WHEN (\(exact)) THEN 1"
+  if !contact.isEmpty { rank += " WHEN (\(contact)) THEN 2" }
+  rank += " ELSE 3 END"
+  return "SELECT \(chatId) AS chatId, \(rank) AS matchRank FROM \(from) WHERE \(conditions.map { "(\($0))" }.joined(separator: " OR "))"
+}
+
 func candidatesSql(_ query: String, identifiers: [String], limit: Int) -> String {
-  let value = sqlQuote(query); let contact = identifiers.map { "c.chat_identifier = \(sqlQuote($0))" }.joined(separator: " OR ")
-  let contactCase = contact.isEmpty ? "" : " WHEN \(contact) THEN 'contact_match'"
-  let contactWhere = contact.isEmpty ? "" : " OR \(contact)"
-  return "SELECT DISTINCT c.guid AS chatGuid, CASE WHEN c.display_name = \(value) OR c.chat_identifier = \(value) THEN 'exact_label'\(contactCase) ELSE 'query_match' END AS matchKind FROM chat c WHERE instr(c.display_name, \(value)) > 0 OR instr(c.chat_identifier, \(value)) > 0\(contactWhere) ORDER BY c.ROWID DESC LIMIT \(min(max(limit, 1), 5));"
+  let value = sqlQuote(query)
+  let lookupIdentifiers = [query] + identifiers
+  let chatQuery = ["instr(lower(COALESCE(c.display_name, '')), lower(\(value))) > 0", "instr(lower(COALESCE(c.chat_identifier, '')), lower(\(value))) > 0", normalizedIdentifierPredicate("c.chat_identifier", lookupIdentifiers)].filter { !$0.isEmpty }.joined(separator: " OR ")
+  let participantQuery = ["instr(lower(h.id), lower(\(value))) > 0", normalizedIdentifierPredicate("h.id", lookupIdentifiers)].filter { !$0.isEmpty }.joined(separator: " OR ")
+  let messageQuery = ["instr(lower(mh.id), lower(\(value))) > 0", normalizedIdentifierPredicate("mh.id", lookupIdentifiers)].filter { !$0.isEmpty }.joined(separator: " OR ")
+  let chatSelect = candidateMatchSelect(
+    from: "chat c",
+    chatId: "c.ROWID",
+    exact: "lower(c.display_name) = lower(\(value)) OR lower(c.chat_identifier) = lower(\(value))",
+    contact: normalizedIdentifierPredicate("c.chat_identifier", identifiers),
+    query: chatQuery
+  )
+  let participantSelect = candidateMatchSelect(
+    from: "chat_handle_join chj JOIN handle h ON h.ROWID = chj.handle_id",
+    chatId: "chj.chat_id",
+    exact: "lower(h.id) = lower(\(value))",
+    contact: normalizedIdentifierPredicate("h.id", identifiers),
+    query: participantQuery
+  )
+  let messageSelect = candidateMatchSelect(
+    from: "message m JOIN handle mh ON mh.ROWID = m.handle_id JOIN chat_message_join cmj ON cmj.message_id = m.ROWID",
+    chatId: "cmj.chat_id",
+    exact: "lower(mh.id) = lower(\(value))",
+    contact: normalizedIdentifierPredicate("mh.id", identifiers),
+    query: messageQuery
+  )
+  return "WITH matches AS (\(chatSelect) UNION ALL \(participantSelect) UNION ALL \(messageSelect)), ranked AS (SELECT chatId, MIN(matchRank) AS matchRank FROM matches GROUP BY chatId) SELECT c.guid AS chatGuid, CASE ranked.matchRank WHEN 1 THEN 'exact_label' WHEN 2 THEN 'contact_match' ELSE 'query_match' END AS matchKind FROM ranked JOIN chat c ON c.ROWID = ranked.chatId ORDER BY COALESCE((SELECT MAX(m.date) FROM chat_message_join cmj JOIN message m ON m.ROWID = cmj.message_id WHERE cmj.chat_id = c.ROWID), 0) DESC, c.ROWID DESC LIMIT \(min(max(limit, 1), 5));"
+}
+
+func shouldResolveContacts(_ query: String) -> Bool {
+  return !query.contains("@") && query.contains(where: \.isLetter)
 }
 
 func readSql(_ conversation: String, _ maxMessages: Int) -> String {
@@ -107,7 +172,8 @@ do {
   if command == "messages-candidates" {
     let query = ((request["query"] as? String) ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
     guard query.count >= 2 else { result(candidateKind, status: "failed", findings: ["Apple Messages candidate lookup requires a query of at least two characters."]); exit(64) }
-    let response = try sqlite(path, candidatesSql(query, identifiers: contactIdentifiers(query), limit: (request["limit"] as? Int) ?? 5))
+    let identifiers = shouldResolveContacts(query) ? contactIdentifiers(query) : []
+    let response = try sqlite(path, candidatesSql(query, identifiers: identifiers, limit: (request["limit"] as? Int) ?? 5))
     guard response.status == 0 else { let status = failureStatus(response.stderr); result(candidateKind, status: status, findings: [failureFinding(status)]); exit(status == "missing_permission" ? 3 : 2) }
     let rows = ((try? JSONSerialization.jsonObject(with: Data(response.stdout.utf8))) as? [[String: Any]]) ?? []
     let candidates = rows.enumerated().compactMap { index, row -> [String: Any]? in guard let guid = row["chatGuid"] as? String, let kind = row["matchKind"] as? String else { return nil }; return ["candidateRef": opaqueConversationRef(guid), "label": "Conversation \(index + 1)", "matchKind": kind == "exact_label" ? "exact_label" : kind == "contact_match" ? "contact_match" : "query_match"] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionsmith/apple-messages-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Library-first MCP protocol and local macOS helper toolkit for Apple Messages.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -31,6 +31,13 @@
     "url": "https://github.com/motionsmith/apple-messages-mcp/issues"
   },
   "homepage": "https://github.com/motionsmith/apple-messages-mcp#readme",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "lint": "eslint . --ext .ts",
+    "helper:build": "scripts/build-apple-messages-helper.sh",
+    "pack:check": "pnpm pack --pack-destination /tmp/apple-messages-mcp-pack"
+  },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@types/node": "^22.15.0",
@@ -40,11 +47,5 @@
     "typescript-eslint": "^8.59.4",
     "vitest": "^4.1.6"
   },
-  "scripts": {
-    "build": "tsc -b",
-    "test": "vitest run",
-    "lint": "eslint . --ext .ts",
-    "helper:build": "scripts/build-apple-messages-helper.sh",
-    "pack:check": "pnpm pack --pack-destination /tmp/apple-messages-mcp-pack"
-  }
-}
+  "packageManager": "pnpm@11.1.2"
+}

package/scripts/apple-messages-helper.Info.plist

@@ -13,7 +13,7 @@
   <key>CFBundlePackageType</key>
   <string>APPL</string>
   <key>CFBundleShortVersionString</key>
-  <string>0.1.0</string>
+  <string>0.1.1</string>
   <key>LSUIElement</key>
   <true/>
 </dict>