imsg-mcp 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.19.0](https://github.com/george43g/imsg-mcp/compare/v1.18.0...v1.19.0) (2026-07-25)
+
+
+### Features
+
+* **contacts:** attach a normalized identity block to get_contact + resolve_handle ([99dfc72](https://github.com/george43g/imsg-mcp/commit/99dfc723e2a5bf8508f1b3940a63a0aeb684d120))
+
+# [1.18.0](https://github.com/george43g/imsg-mcp/compare/v1.17.0...v1.18.0) (2026-07-25)
+
+
+### Features
+
+* **tools:** uniform completeness metadata across list responses ([d8fd930](https://github.com/george43g/imsg-mcp/commit/d8fd930dfd28f28ac677ec4ffefd1addb39afbf5))
+
 # [1.17.0](https://github.com/george43g/imsg-mcp/compare/v1.16.0...v1.17.0) (2026-07-25)
 
 

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-B5cdb7uT.js";
+import { A as APP_VERSION, t as toYaml } from "./meta-CD2uvSHu.js";
 import { spawn } from "node:child_process";
 import { join, dirname } from "node:path";
 function distRoot() {

package/dist/index.js

@@ -14,11 +14,11 @@ import { ensureAttachmentDownloaded } from "./attachment-sync-DMvlT8Zk.js";
 import { n as normalizedPhoneVariants, h as hasNativeModule, I as IMessageDB, r as rankFuzzy } from "./imessage-db-CHbdUXk3.js";
 import { parseUserDate } from "./date-parse-DJXMfq3a.js";
 import { streamExport, ExportInterpretGuardError } from "./exportStream-BFxilSlL.js";
-import { r as renderAnalyticText, A as APP_VERSION, a as APP_NAME } from "./meta-B5cdb7uT.js";
+import { n as normalizePhoneToE164, m as minMessageId, a as resolveRecipient, d as defaultCountryFromEnv, i as installWatchdog, b as noteActivity, r as readWatchdogState } from "./watchdog-D54vuRzh.js";
+import { r as renderAnalyticText, A as APP_VERSION, a as APP_NAME } from "./meta-CD2uvSHu.js";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { a as applyInlineInterpretations, i as imageBlockFromFile, v as videoPosterFrame, m as mediaMetadata, b as refForAttachment, T as TRANSCRIBE_MAX_BYTES, g as getInterpretRuntime, t as transcriptSourceEnum, d as detectTranscriber } from "./media-intel-runtime-BkxG4bmW.js";
-import { m as minMessageId, a as resolveRecipient, d as defaultCountryFromEnv, i as installWatchdog, n as noteActivity, r as readWatchdogState } from "./watchdog-CW2SEAmu.js";
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
 let dbPath = join(homedir(), ".imsg-mcp", "analytics-cache.db");
 let db = null;
@@ -323,6 +323,37 @@ function humansHintText(hint) {
 _Relationship file(s): ${list}_
 _${hint.guidance}_`;
 }
+function dedupe(items) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const item of items) {
+    if (item && !seen.has(item)) {
+      seen.add(item);
+      out.push(item);
+    }
+  }
+  return out;
+}
+function normalizeEmail(email) {
+  return email.trim().toLowerCase();
+}
+function e164OrOriginal(phone, country) {
+  return normalizePhoneToE164(phone, country) ?? phone.trim();
+}
+function buildIdentity(canonicalName, phoneNumbers, emails, country) {
+  const phones = dedupe(phoneNumbers.map((p) => e164OrOriginal(p, country)));
+  const mails = dedupe(emails.map(normalizeEmail));
+  return {
+    canonicalName,
+    phones,
+    emails: mails,
+    handles: dedupe([...phones, ...mails])
+  };
+}
+function buildIdentityFromHandle(handle, name, country) {
+  const isEmail = handle.includes("@");
+  return buildIdentity(name ?? handle, isEmail ? [] : [handle], isEmail ? [handle] : [], country);
+}
 const INSTRUCTIONS_UUID = randomUUID();
 function wrapUntrusted(text) {
   if (text == null || text === "") return "";
@@ -1826,7 +1857,9 @@ const GetUnreadMessagesOutputSchema = z.object({
   messages: z.array(MessageSchema),
   count: z.number().int(),
   hasMore: z.boolean(),
-  nextOffset: z.number().int().nullable()
+  truncated: z.boolean().describe(
+    "True if more unread messages exist than were returned — raise `limit` to get the rest."
+  )
 });
 const SendMessageSchema = z.object({
   recipient: nonEmptyString("Phone number or email address to send to").optional(),
@@ -1886,6 +1919,9 @@ const ListConversationsOutputSchema = z.object({
   conversations: z.array(ConversationSchema),
   count: z.number().int(),
   hasMore: z.boolean(),
+  truncated: z.boolean().describe(
+    "True if more conversations exist beyond this page — page on with `offset` + `nextOffset`."
+  ),
   nextOffset: z.number().int().nullable()
 });
 const SearchMessagesSchema = z.object({
@@ -1904,7 +1940,7 @@ const SearchMessagesOutputSchema = z.object({
   messages: z.array(MessageSchema),
   count: z.number().int(),
   hasMore: z.boolean(),
-  nextOffset: z.number().int().nullable(),
+  truncated: z.boolean().describe("True if more matches exist than were returned — raise `limit` or narrow the query."),
   softCapWarning: z.string().optional()
 });
 const GetLogsSchema = z.object({
@@ -1971,7 +2007,9 @@ const ListContactsOutputSchema = z.object({
   contacts: z.array(ContactSchema),
   count: z.number().int(),
   hasMore: z.boolean(),
-  totalCount: z.number().int()
+  truncated: z.boolean().describe("True if more contacts exist beyond this page — page on with `offset`."),
+  totalAvailable: z.number().int().describe("Total contacts available across all pages."),
+  totalCount: z.number().int().describe("Alias of `totalAvailable` (kept for back-compat).")
 });
 const RankedContactSchema = ContactSchema.extend({
   score: z.number().describe("Relevance in [0,1]; higher = better. Results are sorted best-first."),
@@ -1984,7 +2022,9 @@ const SearchContactsSchema = z.object({
 const SearchContactsOutputSchema = z.object({
   query: z.string(),
   contacts: z.array(RankedContactSchema),
-  count: z.number().int()
+  count: z.number().int(),
+  truncated: z.boolean().describe("True if more contacts matched than were returned — raise `limit`."),
+  totalAvailable: z.number().int().describe("Total contacts that matched the query.")
 });
 const GetContactSchema = z.object({
   handle: z.string().optional().describe("Phone number or email to look up."),
@@ -1992,8 +2032,16 @@ const GetContactSchema = z.object({
 }).refine((v) => v.handle !== void 0 || v.id !== void 0, {
   message: "Provide either `handle` or `id`."
 });
+const IdentitySchema = z.object({
+  canonicalName: z.string().describe("Best display name for this person (or the handle itself)."),
+  phones: z.array(z.string()).describe("Phone handles, E.164-normalized where derivable."),
+  emails: z.array(z.string()).describe("Email handles, trimmed + lowercased."),
+  handles: z.array(z.string()).describe("Every reachable handle, deduped — phones first, then emails.")
+});
 const GetContactOutputSchema = z.object({
   contact: ContactSchema.nullable(),
+  /** Normalized cross-tool handle view (E.164 phones, lowercased emails). */
+  identity: IdentitySchema.optional(),
   /** Per-handle conversation mapping: which thread slug each handle chats under. */
   threads: z.array(
     z.object({
@@ -2032,7 +2080,9 @@ const ResolveHandleOutputSchema = z.object({
   displayName: z.string(),
   contactId: z.number().int().nullable(),
   label: z.string().nullable(),
-  resolved: z.boolean()
+  resolved: z.boolean(),
+  /** Normalized cross-tool handle view — populated even when unresolved. */
+  identity: IdentitySchema.optional()
 });
 const CheckImessageAvailabilitySchema = z.object({
   handle: nonEmptyString("Phone number or email to preflight-check for reachability.")
@@ -2057,11 +2107,12 @@ const SearchAttachmentsSchema = z.object({
   chatIdentifier: z.string().optional().describe("Restrict to a single chat (use chat_identifier from list_conversations)."),
   since: z.string().optional().describe("ISO date or relative ('1 week ago'). Lower bound on attachment creation."),
   until: z.string().optional().describe("ISO date or relative. Upper bound on creation."),
-  limit: z.number().int().min(0).default(20).describe("Max results. 0 = unlimited (capped at 1000).")
+  limit: z.number().int().min(0).default(20).describe("Max results. 0 = unlimited.")
 });
 const SearchAttachmentsOutputSchema = z.object({
   attachments: z.array(AttachmentRecordSchema),
-  count: z.number().int()
+  count: z.number().int(),
+  truncated: z.boolean().describe("True if more attachments matched than were returned — raise `limit`.")
 });
 const InitHumanSchema = z.object({
   contact: nonEmptyString(
@@ -2415,7 +2466,7 @@ const TOOLS = [
   },
   {
     name: "search_contacts",
-    description: "Substring-match contacts by display name, phone number, or email.",
+    description: "Substring-match contacts by display name, phone number, or email, ranked best-first (score + matchedField). Response reports `truncated` and `totalAvailable` so you know when more matched than were returned — raise `limit` to widen.",
     annotations: annotations.read,
     inputSchema: {
       type: "object",
@@ -2429,7 +2480,7 @@ const TOOLS = [
   },
   {
     name: "get_contact",
-    description: "Fetch a single contact by handle (phone/email) or by numeric id, including each handle's thread slug (for send_message/get_messages). Returns null if not found. Includes `humansFile` — the path to this person's humans/v1 relationship file if one exists (read it for relationship context; init_human scaffolds one otherwise).",
+    description: "Fetch a single contact by handle (phone/email) or by numeric id, including each handle's thread slug (for send_message/get_messages) and an `identity` block (canonicalName + E.164-normalized phones + lowercased emails + deduped handles). Returns null if not found. Includes `humansFile` — the path to this person's humans/v1 relationship file if one exists (read it for relationship context; init_human scaffolds one otherwise).",
     annotations: annotations.read,
     inputSchema: {
       type: "object",
@@ -2459,7 +2510,7 @@ const TOOLS = [
   },
   {
     name: "resolve_handle",
-    description: "Resolve a phone number or email to its contact display name. Pass-through if unknown.",
+    description: "Resolve a phone number or email to its contact display name. Pass-through if unknown. Always returns an `identity` block (canonicalName + E.164-normalized phones + lowercased emails + deduped handles) — even for an unknown handle, so you get it in canonical form.",
     annotations: annotations.read,
     inputSchema: {
       type: "object",
@@ -2488,7 +2539,7 @@ const TOOLS = [
   },
   {
     name: "search_attachments",
-    description: "Search attachments (images, videos, files) by MIME type prefix, date range, and/or chat. Returns metadata only — use get_attachment to fetch bytes. Excludes stickers and Apple plugin payloads.",
+    description: "Search attachments (images, videos, files) by MIME type prefix, date range, and/or chat. Returns metadata only — use get_attachment to fetch bytes. Excludes stickers and Apple plugin payloads. Response reports `truncated` (more matched than returned — raise `limit`).",
     annotations: annotations.read,
     inputSchema: {
       type: "object",
@@ -3181,7 +3232,7 @@ ${formatted}${paginationLine}${perfLine}${humansLine}`,
         messages: [],
         count: 0,
         hasMore: false,
-        nextOffset: null
+        truncated: false
       });
     }
     const formatted = results.map((msg) => {
@@ -3195,7 +3246,7 @@ ${formatted}`, {
       messages: results.map(messageToStructured),
       count: results.length,
       hasMore,
-      nextOffset: null
+      truncated: hasMore
     });
   }
   async handleSendMessage(args) {
@@ -3462,6 +3513,7 @@ ${formatted}${humansLine}`, {
         conversations: [],
         count: 0,
         hasMore: false,
+        truncated: false,
         nextOffset: null
       });
     }
@@ -3501,6 +3553,7 @@ ${formatted}`, {
       }),
       count: results.length,
       hasMore,
+      truncated: hasMore,
       nextOffset: hasMore ? startAfter : null
     });
   }
@@ -3529,7 +3582,7 @@ ${formatted}`, {
         messages: [],
         count: 0,
         hasMore: false,
-        nextOffset: null,
+        truncated: false,
         softCapWarning
       });
     }
@@ -3546,7 +3599,7 @@ ${formatted}`, {
       messages: results.map(messageToStructured),
       count: results.length,
       hasMore,
-      nextOffset: null,
+      truncated: hasMore,
       softCapWarning
     });
   }
@@ -3563,6 +3616,8 @@ ${formatted}`, {
         contacts: [],
         count: 0,
         hasMore: false,
+        truncated: false,
+        totalAvailable: total,
         totalCount: total
       });
     }
@@ -3577,6 +3632,8 @@ ${formatted}`, {
       contacts,
       count: contacts.length,
       hasMore,
+      truncated: hasMore,
+      totalAvailable: total,
       totalCount: total
     });
   }
@@ -3590,7 +3647,9 @@ ${formatted}`, {
       return toolText(`No contacts match "${query}".`, {
         query,
         contacts: [],
-        count: 0
+        count: 0,
+        truncated: false,
+        totalAvailable: 0
       });
     }
     rememberSearch(
@@ -3621,7 +3680,9 @@ ${formatted}${hint}`,
           score: m.score,
           matchedField: m.matchedField
         })),
-        count: results.length
+        count: results.length,
+        truncated: ranked.length > results.length,
+        totalAvailable: ranked.length
       }
     );
   }
@@ -3668,10 +3729,17 @@ ${withThreads.map((t) => `  ${t.handle} → ${t.threadSlug}`).join("\n")}` : "";
     const humansLine = humansHint ? humansHintText(humansHint) : `
 
 _${HUMANS_INIT_HINT}_`;
+    const identity = buildIdentity(
+      contact.displayName,
+      contact.phoneNumbers,
+      contact.emails,
+      defaultCountryFromEnv()
+    );
     return toolText(
       `${sanitizeUserText(contact.displayName)} (id ${contact.id})${phones}${emails}${org}${threadLines}${humansLine}`,
       {
         contact,
+        identity,
         threads,
         humansFile,
         humansGuidance: humansHint?.guidance ?? HUMANS_INIT_HINT
@@ -3729,13 +3797,17 @@ ${lines}${hint}`,
     const selectorHit = resolveContactSelector(handle);
     const effectiveHandle = selectorHit?.handle ?? handle;
     const lookup = this.db.contacts.lookupContact(effectiveHandle);
+    const country = defaultCountryFromEnv();
     if (lookup) {
+      const contact = this.db.contacts.getContact(lookup.contactId);
+      const identity = contact ? buildIdentity(contact.displayName, contact.phoneNumbers, contact.emails, country) : buildIdentityFromHandle(effectiveHandle, lookup.displayName, country);
       return toolText(`${handle} → ${sanitizeUserText(lookup.displayName)}`, {
         handle,
         displayName: lookup.displayName,
         contactId: lookup.contactId,
         label: lookup.label ?? null,
-        resolved: true
+        resolved: true,
+        identity
       });
     }
     return toolText(`No contact for ${handle}.`, {
@@ -3743,7 +3815,8 @@ ${lines}${hint}`,
       displayName: handle,
       contactId: null,
       label: null,
-      resolved: false
+      resolved: false,
+      identity: buildIdentityFromHandle(effectiveHandle, null, country)
     });
   }
   async handleCheckImessageAvailability(args) {
@@ -3774,14 +3847,17 @@ ${lines}${hint}`,
     const sinceMs = since ? parseUserDate(since)?.getTime() : void 0;
     const untilMs = until ? parseUserDate(until)?.getTime() : void 0;
     const resolvedLimit = resolveLimit(limit);
+    const bounded = resolvedLimit < Number.MAX_SAFE_INTEGER;
     const opts = {
-      limit: resolvedLimit
+      limit: bounded ? resolvedLimit + 1 : resolvedLimit
     };
     if (mimePrefix !== void 0) opts.mimePrefix = mimePrefix;
     if (chatIdentifier !== void 0) opts.chatIdentifier = chatIdentifier;
     if (sinceMs !== void 0) opts.sinceMs = sinceMs;
     if (untilMs !== void 0) opts.untilMs = untilMs;
-    const results = this.db.searchAttachments(opts);
+    const raw = this.db.searchAttachments(opts);
+    const truncated = raw.length > resolvedLimit;
+    const results = raw.slice(0, resolvedLimit);
     const formatted = results.map(
       (a) => `[${a.rowId}] ${a.mimeType ?? "?"} · ${a.totalBytes}B · ${a.createdDate.toISOString().slice(0, 10)} · ${a.transferName ?? a.filename}`
     ).join("\n");
@@ -3797,7 +3873,8 @@ ${formatted}`, {
         createdDate: a.createdDate.toISOString(),
         chatId: a.chatId
       })),
-      count: results.length
+      count: results.length,
+      truncated
     });
   }
   async handleGetAttachment(args) {