imsg-mcp 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and follows [Semantic Versioning](https://semver.org/).
 
+# [1.16.0](https://github.com/george43g/imsg-mcp/compare/v1.15.1...v1.16.0) (2026-07-25)
+
+
+### Features
+
+* **contacts:** rank search_contacts by relevance with matchedField ([352ccd2](https://github.com/george43g/imsg-mcp/commit/352ccd2da1263f26baa31ef38737a9d52bdf3aa0))
+
+## [1.15.1](https://github.com/george43g/imsg-mcp/compare/v1.15.0...v1.15.1) (2026-07-25)
+
+
+### Bug Fixes
+
+* **tui:** refresh sidebar after in-thread send + navigable filter results ([f6552be](https://github.com/george43g/imsg-mcp/commit/f6552be71a6c11abb240d38c853d0dadefcb25a9))
+* **tui:** show identity-canonical service on conversation badges ([0b05827](https://github.com/george43g/imsg-mcp/commit/0b05827eb48b2d217b0d56c6af6b0dbe66e7829b))
+
 # [1.15.0](https://github.com/george43g/imsg-mcp/compare/v1.14.0...v1.15.0) (2026-07-23)
 
 

package/README.md

@@ -5,7 +5,7 @@
 [![Release](https://github.com/george43g/imsg-mcp/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/george43g/imsg-mcp/actions/workflows/release.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**MCP server, CLI, and terminal UI for iMessage on macOS.** Let AI agents read your iMessage / SMS, search history, send messages, and export conversations — without ever leaving your machine. Includes a self-healing watchdog so a wedged query can't take your agent down.
+**MCP server, CLI, and terminal UI for iMessage on macOS.** Let AI agents read your iMessage / SMS, search history, send messages, export conversations, and *understand* media — transcribe voice notes, caption images & video — without ever leaving your machine by default. Includes a self-healing watchdog so a wedged query can't take your agent down.
 
 ![TUI overview](docs/screenshots/tui-overview.png)
 
@@ -41,6 +41,7 @@ Prefer the canonical `npx -y` config above. If you'd rather install the MCPB ext
 ```bash
 npx -y imsg-mcp setup --write claude   # or --write cursor
 npx -y imsg-mcp doctor                  # verify Full Disk Access + DB
+npx -y imsg-mcp setup --interactive     # (optional) configure media interpretation
 ```
 
 ---
@@ -85,7 +86,7 @@ Full walkthrough with screenshots: [**docs/WORKFLOWS.md**](docs/WORKFLOWS.md).
 | `wait_for_reply` | Poll for the next reply — includes the user's own interjections from other devices. |
 | `export_messages` | Stream a chat to file (md/csv/json/ndjson). |
 | `search_attachments` | Find attachments by mime/date/chat. |
-| `get_attachment` | Fetch attachment bytes (inline or path). |
+| `get_attachment` | Fetch an attachment (image block / poster / audio) + optional AI interpretation (`interpret`). |
 | `check_imessage_availability` | Pre-flight iMessage vs SMS reachability. |
 | `chat_analytics` | Pre-aggregated stats (heatmaps, leaderboards, etc). |
 | `list_contacts` / `search_contacts` | Browse/search contacts (name, phone, email). |
@@ -108,18 +109,47 @@ Full reference (CLI subcommands + MCP tools + every flag): [**docs/TOOLS.md**](d
 imsg tui
 ```
 
-Vim-style: `j/k` move, `gg/G` jump, `Enter` drawer, `i` per-thread info + attachment browser, `o` Quick Look an attachment, `:` jump to date, `V` visual select, `e` export, `S` send via other app, `y` copy slug, `c` compose in current thread, `N` compose to new recipient (phone / email / contact name), `q` quit.
+Vim-style: `j/k` move, `gg/G` jump, `Enter` drawer, `i` per-thread info + attachment browser, `o` Quick Look an attachment, `f` reveal in Finder, `R` run/retry media interpretation, `:` jump to date, `V` visual select, `e` export, `S` send via other app, `y` copy slug, `c` compose in current thread, `N` compose to new recipient (phone / email / contact name), `,` settings panel, `q` quit.
 
 Themes (`safe` / `powerline`) and a single accent color drive the whole palette. See [docs/TOOLS.md#tui-configuration](docs/TOOLS.md#tui-configuration).
 
 ---
 
+## Media interpretation
+
+imsg-mcp reads what Apple already computed **for free, on-device**: iPhone-synced voice-note
+transcripts and Genmoji descriptions surface automatically with zero setup and zero network. For
+everything else it runs a configurable **chain** per media type:
+
+```
+apple  →  local (hear / yap / whisper-cli)  →  provider:<cloud>
+```
+
+- **Free-first & opt-in.** `interpret.auto` defaults to `free`, so only Apple + local legs run
+  unless you deliberately add a cloud provider. **Audio and images leave your device only when a
+  cloud leg you configured actually fires** — never by default.
+- **Local tools** (optional, free): `brew install sveinbjornt/hear/hear` · `brew install yap` ·
+  `brew install whisper-cpp`. Optional `brew install ffmpeg mpv` improves video framing/playback.
+- **Cloud providers** (optional): presets for `openai`, `groq`, `openrouter`, `cloudflare`,
+  `huggingface`, `ollama` (local, no key), or a custom OpenAI-compatible base URL. Configure with
+  `imsg setup --interactive`; keys are stored in `~/.imsg-mcp/credentials.json` (chmod 600), never
+  in the shared config.
+- **Cached forever.** Every result is cached in `~/.imsg-mcp/media-intel.db` — the same attachment
+  is never interpreted (or paid for) twice. Bulk exports confirm before making more than
+  `exportConfirmThreshold` (default 25) uncached cloud calls.
+
+Trigger it via `get_attachment` (`interpret`), `export_messages` (`interpret`), `imsg interpret
+<rowId>`, or the TUI (`R`). Full config reference: [docs/TOOLS.md](docs/TOOLS.md).
+
+---
+
 ## Permissions
 
 - **Full Disk Access** — required to read `chat.db` and Address Book. System Settings → Privacy & Security → Full Disk Access → add the terminal/IDE you actually run from.
-- **Automation** — required only for sending. macOS prompts on first send.
+- **Automation** — required only for sending, and for the attachment **sync nudge** (opening a conversation so Messages downloads its media). macOS prompts on first use.
+- **Accessibility** *(opt-in, off by default)* — only if you enable the Tier-2 "Sync Now" nudge (`interpret.nudge.tier2SyncNow`), which UI-scripts the Messages ▸ Settings ▸ Sync Now button. Leave it off unless you need it. System Settings → Privacy & Security → Accessibility.
 
-Privacy: only ever reads your **local** `~/Library/Messages/chat.db`. Nothing is uploaded. The connected MCP host (Claude / Cursor / Warp / …) sees whatever messages the agent fetches — treat those hosts the same way you treat any app with Full Disk Access.
+Privacy: reads only your **local** `~/Library/Messages/chat.db` — nothing is uploaded by default. Cloud media interpretation is strictly opt-in (see above) and only sends the specific attachment you interpret to the provider you configured. The connected MCP host (Claude / Cursor / Warp / …) sees whatever messages the agent fetches — treat those hosts the same way you treat any app with Full Disk Access.
 
 ---
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { createInterface } from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command } from "commander";
 import { d as checkLocalAccess, f as formatAccessReport, I as IMPLEMENTED_TYPES, A as ANALYTIC_INFO, i as installShutdownHandlers, r as registerCleanup, l as looksLikeThreadSlug } from "./shutdown-0TCv4XJB.js";
-import { A as APP_VERSION, t as toYaml } from "./meta-ByD-lGq7.js";
+import { A as APP_VERSION, t as toYaml } from "./meta-DcLrk46N.js";
 import { spawn } from "node:child_process";
 import { join, dirname } from "node:path";
 function distRoot() {
@@ -447,7 +447,7 @@ async function runExportCommand(target, opts) {
   const { homedir } = await import("node:os");
   const { dirname: dirname2, join: join2, isAbsolute, resolve } = await import("node:path");
   const { getContactsDbPaths, getImsgDbPath, getSlugsDbPath } = await import("./shutdown-0TCv4XJB.js").then((n) => n.a2);
-  const { IMessageDB } = await import("./imessage-db-C1owvGNS.js").then((n) => n.i);
+  const { IMessageDB } = await import("./imessage-db-DXFIm7is.js").then((n) => n.i);
   const { streamExport } = await import("./exportStream-BFxilSlL.js");
   const { parseUserDate } = await import("./date-parse-DJXMfq3a.js");
   const format = normalizeFormat(opts.format ?? "md");
@@ -719,7 +719,7 @@ program.command("interpret <rowId>").description("Interpret one attachment (tran
     return;
   }
   const { getContactsDbPaths, getImsgDbPath, getSlugsDbPath } = await import("./shutdown-0TCv4XJB.js").then((n) => n.a2);
-  const { IMessageDB } = await import("./imessage-db-C1owvGNS.js").then((n) => n.i);
+  const { IMessageDB } = await import("./imessage-db-DXFIm7is.js").then((n) => n.i);
   const { getInterpretRuntime, refForAttachment } = await import("./media-intel-runtime-BkxG4bmW.js").then((n) => n.c);
   const { deleteMediaIntel } = await import("./media-intel-cache-mCgH4z9P.js");
   const db = new IMessageDB(getImsgDbPath(), getContactsDbPaths(), getSlugsDbPath());

package/dist/{imessage-db-C1owvGNS.js → imessage-db-DXFIm7is.js}

@@ -6,6 +6,144 @@ import { fileURLToPath } from "node:url";
 import { existsSync, readdirSync, mkdirSync } from "node:fs";
 import { O as OBJECT_REPLACEMENT_CHAR, p as perf, m as isGroupGuid, n as isGroupChatIdentifier, q as generateThreadSlug, T as Tables, t as AssociatedMessageType, u as macAutoTimestampToDate, v as isReactionType, M as MAC_EPOCH_OFFSET, N as NANOS_PER_SECOND, x as macTimestampToDate$1, y as parseAssociatedMessageGuid$1 } from "./shutdown-0TCv4XJB.js";
 import bplist, { parseBuffer } from "bplist-parser";
+const EMOJI_REGEX = /[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}\u{1F1E6}-\u{1F1FF}]/gu;
+const WHITESPACE_REGEX = /\s+/g;
+function cleanText(s) {
+  return s.toLowerCase().replace(EMOJI_REGEX, " ").replace(WHITESPACE_REGEX, " ").trim();
+}
+function tokenSet(s) {
+  if (!s) return /* @__PURE__ */ new Set();
+  return new Set(s.split(" ").filter(Boolean));
+}
+function levenshtein(a, b, maxLen = 200) {
+  if (a === b) return 0;
+  const aLen = Math.min(a.length, maxLen);
+  const bLen = Math.min(b.length, maxLen);
+  if (aLen === 0) return bLen;
+  if (bLen === 0) return aLen;
+  let prev = new Array(bLen + 1);
+  let curr = new Array(bLen + 1);
+  for (let j = 0; j <= bLen; j++) prev[j] = j;
+  for (let i = 1; i <= aLen; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= bLen; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const del = (prev[j] ?? 0) + 1;
+      const ins = (curr[j - 1] ?? 0) + 1;
+      const sub = (prev[j - 1] ?? 0) + cost;
+      curr[j] = Math.min(del, ins, sub);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[bLen] ?? Math.max(aLen, bLen);
+}
+function levenshteinRatio(a, b) {
+  if (a === b) return 1;
+  const aLen = Math.min(a.length, 200);
+  const bLen = Math.min(b.length, 200);
+  const maxLen = Math.max(aLen, bLen);
+  if (maxLen === 0) return 1;
+  return 1 - levenshtein(a, b) / maxLen;
+}
+function fuzzyScore(query, candidate) {
+  if (query && candidate && candidate.toLowerCase().includes(query.toLowerCase())) {
+    return 0.95;
+  }
+  const q = cleanText(query);
+  const c = cleanText(candidate);
+  if (!q || !c) return 0;
+  if (c.includes(q)) return 0.95;
+  if (q.includes(c)) return 0.9;
+  const qTokens = tokenSet(q);
+  const cTokens = tokenSet(c);
+  let intersection = 0;
+  for (const tok of qTokens) {
+    if (cTokens.has(tok)) intersection++;
+  }
+  const dice = 2 * intersection / (qTokens.size + cTokens.size || 1);
+  let bestTokenLev = 0;
+  if (qTokens.size === 1) {
+    for (const tok of cTokens) {
+      const r = levenshteinRatio(q, tok);
+      if (r > bestTokenLev) bestTokenLev = r;
+    }
+  }
+  const levRatio = Math.max(levenshteinRatio(q, c), bestTokenLev);
+  const blend = qTokens.size <= 1 ? 0.1 * dice + 0.9 * levRatio : 0.7 * dice + 0.3 * levRatio;
+  return Math.max(0, Math.min(1, blend));
+}
+function rankFuzzy(query, candidates, getText, minScore = 0.6) {
+  const out = [];
+  for (const c of candidates) {
+    const score = fuzzyScore(query, getText(c));
+    if (score >= minScore) out.push({ item: c, score });
+  }
+  out.sort((a, b) => b.score - a.score);
+  return out;
+}
+function scoreTextField(query, value) {
+  if (!value) return 0;
+  const v = value.toLowerCase();
+  const q = query.toLowerCase().trim();
+  if (!q) return 0;
+  if (v === q) return 1;
+  if (v.startsWith(q)) return 0.9;
+  if (v.includes(q)) return 0.7;
+  return fuzzyScore(q, v);
+}
+function scorePhoneField(query, phone) {
+  const qd = query.replace(/\D/g, "");
+  const pd = phone.replace(/\D/g, "");
+  if (!qd || !pd) return 0;
+  if (pd === qd) return 1;
+  if (pd.includes(qd)) return 0.8;
+  return 0;
+}
+const NAME_FIELDS = [
+  ["displayName", (c) => c.displayName],
+  ["firstName", (c) => c.firstName],
+  ["lastName", (c) => c.lastName],
+  ["nickname", (c) => c.nickname],
+  ["organization", (c) => c.organization]
+];
+function scoreContactMatch(query, contact, floor = 0.6) {
+  let best = 0;
+  let field = "displayName";
+  for (const [name, get] of NAME_FIELDS) {
+    const s = scoreTextField(query, get(contact));
+    if (s > best) {
+      best = s;
+      field = name;
+    }
+  }
+  for (const phone of contact.phoneNumbers) {
+    const s = scorePhoneField(query, phone);
+    if (s > best) {
+      best = s;
+      field = "phone";
+    }
+  }
+  for (const email of contact.emails) {
+    const s = scoreTextField(query, email);
+    if (s > best) {
+      best = s;
+      field = "email";
+    }
+  }
+  if (best < floor) return null;
+  return { contact, score: Math.round(best * 1e3) / 1e3, matchedField: field };
+}
+function rankContacts(query, contacts, floor = 0.6) {
+  const out = [];
+  for (const c of contacts) {
+    const m = scoreContactMatch(query, c, floor);
+    if (m) out.push(m);
+  }
+  out.sort(
+    (a, b) => b.score - a.score || a.contact.displayName.localeCompare(b.contact.displayName)
+  );
+  return out;
+}
 function normalizePhoneNumber(phone) {
   const digits = phone.replace(/\D/g, "");
   if (digits.length === 11 && digits.startsWith("1")) {
@@ -319,6 +457,18 @@ class ContactsDB {
       (c) => c.displayName.toLowerCase().includes(lowerQuery) || c.phoneNumbers.some((p) => p.includes(query)) || c.emails.some((e) => e.toLowerCase().includes(lowerQuery))
     );
   }
+  /**
+   * Search contacts, ranked by relevance with the matched field annotated.
+   * Preserves the substring recall of searchContacts (a substring match scores
+   * 0.7, above the inclusion floor) while ordering best-first so callers can
+   * disambiguate close matches instead of eyeballing an unordered list.
+   */
+  searchContactsRanked(query) {
+    if (!this.initialized) {
+      this.initialize();
+    }
+    return rankContacts(query, Array.from(this.contactCache.values()));
+  }
   /**
    * Build display name from contact fields
    */
@@ -373,81 +523,6 @@ class ContactsDB {
     };
   }
 }
-const EMOJI_REGEX = /[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}\u{1F1E6}-\u{1F1FF}]/gu;
-const WHITESPACE_REGEX = /\s+/g;
-function cleanText(s) {
-  return s.toLowerCase().replace(EMOJI_REGEX, " ").replace(WHITESPACE_REGEX, " ").trim();
-}
-function tokenSet(s) {
-  if (!s) return /* @__PURE__ */ new Set();
-  return new Set(s.split(" ").filter(Boolean));
-}
-function levenshtein(a, b, maxLen = 200) {
-  if (a === b) return 0;
-  const aLen = Math.min(a.length, maxLen);
-  const bLen = Math.min(b.length, maxLen);
-  if (aLen === 0) return bLen;
-  if (bLen === 0) return aLen;
-  let prev = new Array(bLen + 1);
-  let curr = new Array(bLen + 1);
-  for (let j = 0; j <= bLen; j++) prev[j] = j;
-  for (let i = 1; i <= aLen; i++) {
-    curr[0] = i;
-    for (let j = 1; j <= bLen; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      const del = (prev[j] ?? 0) + 1;
-      const ins = (curr[j - 1] ?? 0) + 1;
-      const sub = (prev[j - 1] ?? 0) + cost;
-      curr[j] = Math.min(del, ins, sub);
-    }
-    [prev, curr] = [curr, prev];
-  }
-  return prev[bLen] ?? Math.max(aLen, bLen);
-}
-function levenshteinRatio(a, b) {
-  if (a === b) return 1;
-  const aLen = Math.min(a.length, 200);
-  const bLen = Math.min(b.length, 200);
-  const maxLen = Math.max(aLen, bLen);
-  if (maxLen === 0) return 1;
-  return 1 - levenshtein(a, b) / maxLen;
-}
-function fuzzyScore(query, candidate) {
-  if (query && candidate && candidate.toLowerCase().includes(query.toLowerCase())) {
-    return 0.95;
-  }
-  const q = cleanText(query);
-  const c = cleanText(candidate);
-  if (!q || !c) return 0;
-  if (c.includes(q)) return 0.95;
-  if (q.includes(c)) return 0.9;
-  const qTokens = tokenSet(q);
-  const cTokens = tokenSet(c);
-  let intersection = 0;
-  for (const tok of qTokens) {
-    if (cTokens.has(tok)) intersection++;
-  }
-  const dice = 2 * intersection / (qTokens.size + cTokens.size || 1);
-  let bestTokenLev = 0;
-  if (qTokens.size === 1) {
-    for (const tok of cTokens) {
-      const r = levenshteinRatio(q, tok);
-      if (r > bestTokenLev) bestTokenLev = r;
-    }
-  }
-  const levRatio = Math.max(levenshteinRatio(q, c), bestTokenLev);
-  const blend = qTokens.size <= 1 ? 0.1 * dice + 0.9 * levRatio : 0.7 * dice + 0.3 * levRatio;
-  return Math.max(0, Math.min(1, blend));
-}
-function rankFuzzy(query, candidates, getText, minScore = 0.6) {
-  const out = [];
-  for (const c of candidates) {
-    const score = fuzzyScore(query, getText(c));
-    if (score >= minScore) out.push({ item: c, score });
-  }
-  out.sort((a, b) => b.score - a.score);
-  return out;
-}
 const __dirname$1 = dirname(fileURLToPath(import.meta.url));
 let _native;
 function tryLoadNative() {
@@ -1532,6 +1607,24 @@ class IMessageDB {
     }
     return "iMessage";
   }
+  /**
+   * Identity-canonical service for a conversation's badge (prefer iMessage).
+   * Unlike detectServiceForChat (one leg's service), this reflects the whole
+   * identity: if ANY leg is iMessage the thread is iMessage. It matches the
+   * ~imsg~/~sms~ slug segment (computeSlugForChat) and the slug-store send
+   * route, so the badge can't disagree with them. Without this, a single newer
+   * SMS leg of a fundamentally-iMessage thread wins the merge cascade and flips
+   * the badge to "SMS" while the slug stays ~imsg~. Groups have no cross-service
+   * identity, so fall back to the chat's own service.
+   */
+  canonicalServiceForChat(chat) {
+    if (isGroupGuid(chat.guid) || isGroupChatIdentifier(chat.chat_identifier)) {
+      return this.detectServiceForChat(chat);
+    }
+    this.ensureIdentityServiceMap();
+    const mergeKey = this.getConversationMergeKey(chat.chat_identifier, chat.guid, false);
+    return this.identityServiceMap?.get(mergeKey) ?? this.detectServiceForChat(chat);
+  }
   /**
    * Get the N most recent messages across all conversations
    * By default excludes reactions (tapbacks) for cleaner output
@@ -1900,8 +1993,7 @@ class IMessageDB {
       const participants = isGroup ? this.fetchChatParticipants(chat.ROWID) : [rawIdentifier];
       const mergeKey = this.getConversationMergeKey(rawIdentifier, chat.guid, isGroup);
       const slug = this.getSlugForChatGuid(chat.guid) ?? this.syncSlugForChat(chat);
-      const chatData = this.slugMap.get(slug);
-      const serviceType = chatData ? this.detectServiceForChat(chatData) : this.detectServiceForChat(chat);
+      const serviceType = this.canonicalServiceForChat(chat);
       return {
         last,
         mergeKey,
@@ -1965,8 +2057,7 @@ class IMessageDB {
       displayName = resolved !== rawIdentifier ? resolved : null;
     }
     const slug = this.getSlugForChatGuid(found.guid) ?? this.syncSlugForChat(found);
-    const chatData = this.slugMap.get(slug);
-    const serviceType = chatData ? this.detectServiceForChat(chatData) : this.detectServiceForChat(found);
+    const serviceType = this.canonicalServiceForChat(found);
     return {
       chatId: found.guid,
       chatIdentifier: rawIdentifier,
@@ -3205,4 +3296,4 @@ export {
   normalizedPhoneVariants as n,
   rankFuzzy as r
 };
-//# sourceMappingURL=imessage-db-C1owvGNS.js.map
+//# sourceMappingURL=imessage-db-DXFIm7is.js.map