imsg-mcp 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 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.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-CZmUZHTh.js";
 import { spawn } from "node:child_process";
 import { join, dirname } from "node:path";
 function distRoot() {

package/dist/index.js

@@ -14,7 +14,7 @@ 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 { r as renderAnalyticText, A as APP_VERSION, a as APP_NAME } from "./meta-CZmUZHTh.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";
@@ -1826,7 +1826,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 +1888,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 +1909,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 +1976,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 +1991,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."),
@@ -2057,11 +2066,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 +2425,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",
@@ -2488,7 +2498,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 +3191,7 @@ ${formatted}${paginationLine}${perfLine}${humansLine}`,
         messages: [],
         count: 0,
         hasMore: false,
-        nextOffset: null
+        truncated: false
       });
     }
     const formatted = results.map((msg) => {
@@ -3195,7 +3205,7 @@ ${formatted}`, {
       messages: results.map(messageToStructured),
       count: results.length,
       hasMore,
-      nextOffset: null
+      truncated: hasMore
     });
   }
   async handleSendMessage(args) {
@@ -3462,6 +3472,7 @@ ${formatted}${humansLine}`, {
         conversations: [],
         count: 0,
         hasMore: false,
+        truncated: false,
         nextOffset: null
       });
     }
@@ -3501,6 +3512,7 @@ ${formatted}`, {
       }),
       count: results.length,
       hasMore,
+      truncated: hasMore,
       nextOffset: hasMore ? startAfter : null
     });
   }
@@ -3529,7 +3541,7 @@ ${formatted}`, {
         messages: [],
         count: 0,
         hasMore: false,
-        nextOffset: null,
+        truncated: false,
         softCapWarning
       });
     }
@@ -3546,7 +3558,7 @@ ${formatted}`, {
       messages: results.map(messageToStructured),
       count: results.length,
       hasMore,
-      nextOffset: null,
+      truncated: hasMore,
       softCapWarning
     });
   }
@@ -3563,6 +3575,8 @@ ${formatted}`, {
         contacts: [],
         count: 0,
         hasMore: false,
+        truncated: false,
+        totalAvailable: total,
         totalCount: total
       });
     }
@@ -3577,6 +3591,8 @@ ${formatted}`, {
       contacts,
       count: contacts.length,
       hasMore,
+      truncated: hasMore,
+      totalAvailable: total,
       totalCount: total
     });
   }
@@ -3590,7 +3606,9 @@ ${formatted}`, {
       return toolText(`No contacts match "${query}".`, {
         query,
         contacts: [],
-        count: 0
+        count: 0,
+        truncated: false,
+        totalAvailable: 0
       });
     }
     rememberSearch(
@@ -3621,7 +3639,9 @@ ${formatted}${hint}`,
           score: m.score,
           matchedField: m.matchedField
         })),
-        count: results.length
+        count: results.length,
+        truncated: ranked.length > results.length,
+        totalAvailable: ranked.length
       }
     );
   }
@@ -3774,14 +3794,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 +3820,8 @@ ${formatted}`, {
         createdDate: a.createdDate.toISOString(),
         chatId: a.chatId
       })),
-      count: results.length
+      count: results.length,
+      truncated
     });
   }
   async handleGetAttachment(args) {