apple-notes-mcp 2.6.4 → 2.6.6

package/README.md

@@ -807,6 +807,8 @@ Lists attachments in a note.
 
 **Returns:** List of attachments with IDs, names, content identifiers, URLs when available, created/modified dates, and shared state.
 
+**⚠️ Safety:** A lookup failure is reported as an error, never as an empty list — so an empty result reliably means the note has no attachments and is safe to replace wholesale. Treat an error as "unknown", not "none".
+
 ---
 
 #### `save-attachment`
@@ -1019,8 +1021,8 @@ All configuration is optional — the server works out of the box. Override beha
 | `APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES` | `26214400` (25 MB) | Max size of an attachment that [`fetch-attachment`](#fetch-attachment) will base64-encode inline. Larger attachments are rejected with an error pointing at [`save-attachment`](#save-attachment) (which streams to disk and has no such limit). Raise it to fetch bigger attachments inline; lower it to cap memory. |
 | `APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES` | `262144` (256 KB) | Per-image cap on the base64 payload kept inline in a [`get-note-content`](#get-note-content) response. Inline images over the cap are replaced with placeholders (with a warning appended) so an image-heavy note cannot exceed the MCP client's message limit and drop the connection; export the real files with [`save-attachment`](#save-attachment) or [`fetch-attachment`](#fetch-attachment). Raise it to keep bigger images inline. |
 | `APPLE_NOTES_MCP_CONFIG_FILE` | `~/Library/Application Support/apple-notes-mcp/config.json` | Path to the JSON config file (see below). |
-| `APPLE_NOTES_MCP_TIMEOUT_MS` | `30000` (30 s) | Per-call AppleScript timeout. Raise it if full-library operations (large searches, exports) time out on a big Notes library. Per-call `timeoutMs` options still win. |
-| `APPLE_NOTES_MCP_MAX_RETRIES` | `2` | Total attempts for an AppleScript call that fails with a **transient** error (Notes.app busy / not responding / lost connection / timeout). `2` means one retry; set `1` to fail fast with no retries. Non-transient errors (e.g. "note not found") never retry. |
+| `APPLE_NOTES_MCP_TIMEOUT_MS` | `30000` (30 s) | Total AppleScript operation timeout, including retry attempts and delays. Raise it if full-library operations (large searches, exports) time out on a big Notes library. Per-call `timeoutMs` options still win. |
+| `APPLE_NOTES_MCP_MAX_RETRIES` | `2` | Maximum attempts for a read-only AppleScript call that fails with a **transient** error (Notes.app busy / not responding / lost connection). `2` means one retry; set `1` to fail fast with no retries. Retries share the single `APPLE_NOTES_MCP_TIMEOUT_MS` budget rather than each getting a fresh one, and a retry is skipped when under a second of that budget remains — so this is a ceiling, not a guarantee. In particular a call that exhausts the budget with a **timeout** has no time left to retry by construction. Mutating operations run once because a timeout can occur after Notes.app applied the change. Non-transient errors (e.g. "note not found") never retry. |
 | `APPLE_NOTES_MCP_RETRY_DELAY_MS` | `1000` (1 s) | Base delay before the first retry; subsequent retries back off exponentially (1s, 2s, 4s, ...). |
 | `DEBUG` / `VERBOSE` | unset | Set either to enable verbose diagnostic logging to stderr. |
 

package/build/index.js

@@ -38677,6 +38677,7 @@ function getMaxBuffer() {
   return envPositiveNumber("APPLE_NOTES_MCP_MAX_BUFFER") ?? DEFAULT_MAX_BUFFER_BYTES;
 }
 var SCRIPT_TIMEOUT_HEADROOM_MS = 5e3;
+var MIN_ATTEMPT_BUDGET_MS = 1e3;
 function wrapWithTimeout(script, processTimeoutMs) {
   const seconds = Math.max(1, Math.ceil((processTimeoutMs - SCRIPT_TIMEOUT_HEADROOM_MS) / 1e3));
   return `with timeout of ${seconds} seconds
@@ -38818,7 +38819,6 @@ function executeAppleScript(script, options = {}) {
       error: "Cannot execute empty AppleScript"
     };
   }
-  const preparedScript = wrapWithTimeout(script.trim(), timeoutMs);
   debugLog("Executing AppleScript", {
     scriptPreview: script.trim().substring(0, 200) + (script.length > 200 ? "..." : ""),
     timeout: timeoutMs,
@@ -38826,13 +38826,16 @@ function executeAppleScript(script, options = {}) {
   });
   let lastError = null;
   const startTime = Date.now();
+  const deadline = startTime + timeoutMs;
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const attemptTimeoutMs = Math.max(1, deadline - Date.now());
+    const preparedScript = wrapWithTimeout(script.trim(), attemptTimeoutMs);
     const attemptStart = Date.now();
     try {
       const output = execFileSync("osascript", ["-"], {
         input: preparedScript,
         encoding: "utf8",
-        timeout: timeoutMs,
+        timeout: attemptTimeoutMs,
         // SIGKILL (not the default SIGTERM): a wedged osascript blocked on an
         // unresponsive Notes.app can ignore SIGTERM and leak, piling up and
         // worsening contention. SIGKILL guarantees reaping on timeout. (#17)
@@ -38885,8 +38888,9 @@ function executeAppleScript(script, options = {}) {
       };
       const canRetry = isTimeout || isRetryableError(errorMessage);
       const hasAttemptsLeft = attempt < maxRetries;
-      if (canRetry && hasAttemptsLeft) {
-        const delayMs = retryDelayMs * Math.pow(2, attempt - 1);
+      const delayMs = retryDelayMs * Math.pow(2, attempt - 1);
+      const hasTimeForRetry = Date.now() + delayMs + MIN_ATTEMPT_BUDGET_MS < deadline;
+      if (canRetry && hasAttemptsLeft && hasTimeForRetry) {
         console.error(
           `AppleScript retry: Attempt ${attempt}/${maxRetries} failed with "${errorMessage}". Retrying in ${delayMs}ms...`
         );
@@ -39221,6 +39225,9 @@ var FIELD_SEP = "";
 var RECORD_SEP = "";
 var AS_FIELD_SEP = "(ASCII character 31)";
 var AS_RECORD_SEP = "(ASCII character 30)";
+function executeMutationAppleScript(script) {
+  return executeAppleScript(script, { maxRetries: 1 });
+}
 function escapeForAppleScript(text) {
   if (!text) {
     return "";
@@ -39481,7 +39488,7 @@ var AppleNotesManager = class {
       `;
     }
     const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
-    const result = executeAppleScript(script);
+    const result = executeMutationAppleScript(script);
     if (!result.success) {
       console.error(`Failed to create note "${title}":`, result.error);
       return null;
@@ -39824,7 +39831,7 @@ var AppleNotesManager = class {
     const safeTitle = escapePlainStringForAppleScript(title);
     const deleteCommand = `delete note "${safeTitle}"`;
     const script = buildAccountScopedScript({ account: targetAccount }, deleteCommand);
-    const result = executeAppleScript(script);
+    const result = executeMutationAppleScript(script);
     if (!result.success) {
       console.error(`Failed to delete note "${title}":`, result.error);
       return false;
@@ -39844,7 +39851,7 @@ var AppleNotesManager = class {
     const safeId = sanitizeId(id);
     const deleteCommand = `delete note id "${safeId}"`;
     const script = buildAppLevelScript(deleteCommand);
-    const result = executeAppleScript(script);
+    const result = executeMutationAppleScript(script);
     if (!result.success) {
       console.error(`Failed to delete note with ID "${id}":`, result.error);
       return false;
@@ -39888,7 +39895,7 @@ var AppleNotesManager = class {
     }
     const updateCommand = `set body of note "${safeCurrentTitle}" to "${fullBody}"`;
     const script = buildAccountScopedScript({ account: targetAccount }, updateCommand);
-    const result = executeAppleScript(script);
+    const result = executeMutationAppleScript(script);
     if (!result.success) {
       console.error(`Failed to update note "${title}":`, result.error);
       return false;
@@ -39937,7 +39944,7 @@ var AppleNotesManager = class {
     const safeId = sanitizeId(id);
     const updateCommand = `set body of note id "${safeId}" to "${fullBody}"`;
     const script = buildAppLevelScript(updateCommand);
-    const result = executeAppleScript(script);
+    const result = executeMutationAppleScript(script);
     if (!result.success) {
       console.error(`Failed to update note with ID "${id}":`, result.error);
       return false;
@@ -40256,7 +40263,7 @@ var AppleNotesManager = class {
         createCommand = `make new folder at ${parentRef} with properties {name:"${segmentName}"}`;
       }
       const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
-      const result = executeAppleScript(script);
+      const result = executeMutationAppleScript(script);
       if (!result.success) {
         console.error(`Failed to create folder "${name}":`, result.error);
         return null;
@@ -40288,7 +40295,7 @@ var AppleNotesManager = class {
     const targetAccount = this.resolveAccount(account);
     const deleteCommand = `delete ${buildFolderReference(name)}`;
     const script = buildAccountScopedScript({ account: targetAccount }, deleteCommand);
-    const result = executeAppleScript(script);
+    const result = executeMutationAppleScript(script);
     if (!result.success) {
       console.error(`Failed to delete folder "${name}":`, result.error);
       return false;
@@ -40345,7 +40352,7 @@ var AppleNotesManager = class {
       move noteRef to destFolder
     `;
     const script = buildAppLevelScript(moveCommand);
-    const result = executeAppleScript(script);
+    const result = executeMutationAppleScript(script);
     if (!result.success) {
       console.error(
         `Cannot move note to "${destinationFolder}" (folder may not exist):`,
@@ -40500,7 +40507,7 @@ var AppleNotesManager = class {
   showNoteById(id, separately = false) {
     const safeId = sanitizeId(id);
     const separatelyClause = separately ? " separately true" : "";
-    const result = executeAppleScript(
+    const result = executeMutationAppleScript(
       buildAppLevelScript(`show note id "${safeId}"${separatelyClause}`)
     );
     if (!result.success) {
@@ -40563,7 +40570,7 @@ var AppleNotesManager = class {
   showFolderById(id, separately = false) {
     const safeId = sanitizeId(id);
     const separatelyClause = separately ? " separately true" : "";
-    const result = executeAppleScript(
+    const result = executeMutationAppleScript(
       buildAppLevelScript(`show folder id "${safeId}"${separatelyClause}`)
     );
     if (!result.success) {
@@ -40585,7 +40592,7 @@ var AppleNotesManager = class {
   showAccountById(id, separately = false) {
     const safeId = sanitizeId(id);
     const separatelyClause = separately ? " separately true" : "";
-    const result = executeAppleScript(
+    const result = executeMutationAppleScript(
       buildAppLevelScript(`show account id "${safeId}"${separatelyClause}`)
     );
     if (!result.success) {
@@ -40628,7 +40635,7 @@ var AppleNotesManager = class {
         return "OK"
       end tell
     `;
-    const result = executeAppleScript(script);
+    const result = executeMutationAppleScript(script);
     if (!result.success) {
       console.error(
         `Failed to show attachment "${attachmentId}" on note "${noteId}":`,
@@ -40858,7 +40865,9 @@ var AppleNotesManager = class {
    * Note: The position within the note cannot be determined via AppleScript.
    *
    * @param id - CoreData URL identifier for the note
-   * @returns Array of Attachment objects, or empty array if none found
+   * @returns Array of Attachment objects, or empty array if the note genuinely has none
+   * @throws If the AppleScript call fails, so a lookup failure is never mistaken for
+   *   an attachment-free note (callers gate destructive full-body updates on this)
    *
    * @example
    * ```typescript
@@ -40872,19 +40881,34 @@ var AppleNotesManager = class {
       tell application "Notes"
         set theNote to note id "${safeId}"
         set attachmentList to {}
-        repeat with a in attachments of theNote
-          set attachId to id of a
-          set attachName to name of a
-          set attachContentId to content identifier of a
-          set attachUrl to ""
-          try
-            set attachUrl to URL of a as text
-          end try
-          set createdDate to creation date of a
-          set modifiedDate to modification date of a
+        set attachmentIds to id of every attachment of theNote
+        set attachmentNames to name of every attachment of theNote
+        set attachmentContentIds to content identifier of every attachment of theNote
+        set attachmentUrls to URL of every attachment of theNote
+        set attachmentCreatedDates to creation date of every attachment of theNote
+        set attachmentModifiedDates to modification date of every attachment of theNote
+        set attachmentSharedFlags to shared of every attachment of theNote
+        set attachmentIdsAfter to id of every attachment of theNote
+        if (count of attachmentNames) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentContentIds) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentUrls) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentCreatedDates) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentModifiedDates) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentSharedFlags) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentIdsAfter) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        repeat with i from 1 to count of attachmentIds
+          if (item i of attachmentIdsAfter) is not (item i of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        end repeat
+        repeat with i from 1 to count of attachmentIds
+          set attachId to item i of attachmentIds
+          set attachName to item i of attachmentNames
+          set attachContentId to item i of attachmentContentIds
+          set attachUrl to item i of attachmentUrls as text
+          set createdDate to item i of attachmentCreatedDates
+          set modifiedDate to item i of attachmentModifiedDates
           set createdParts to ${asDatePartsExpr("createdDate")}
           set modifiedParts to ${asDatePartsExpr("modifiedDate")}
-          set sharedFlag to shared of a as text
+          set sharedFlag to item i of attachmentSharedFlags as text
           set end of attachmentList to attachId & ${AS_FIELD_SEP} & attachName & ${AS_FIELD_SEP} & attachContentId & ${AS_FIELD_SEP} & attachUrl & ${AS_FIELD_SEP} & createdParts & ${AS_FIELD_SEP} & modifiedParts & ${AS_FIELD_SEP} & sharedFlag
         end repeat
         set output to ""
@@ -40895,10 +40919,12 @@ var AppleNotesManager = class {
       end tell
     `;
     const result = executeAppleScript(script);
-    if (!result.success || !result.output) {
-      if (result.error) {
-        console.error(`Failed to list attachments for note ID "${id}":`, result.error);
-      }
+    if (!result.success) {
+      throw new Error(
+        `Failed to list attachments for note ID "${id}": ${result.error ?? "unknown AppleScript error"}`
+      );
+    }
+    if (!result.output) {
       return [];
     }
     const attachments = [];
@@ -40925,7 +40951,9 @@ var AppleNotesManager = class {
    *
    * @param title - Title of the note
    * @param account - Account containing the note (defaults to iCloud)
-   * @returns Array of Attachment objects, or empty array if none found
+   * @returns Array of Attachment objects, or empty array if the note genuinely has none
+   * @throws If the AppleScript call fails, so a lookup failure is never mistaken for
+   *   an attachment-free note (callers gate destructive full-body updates on this)
    */
   listAttachments(title, account) {
     const targetAccount = this.resolveAccount(account);
@@ -40936,19 +40964,34 @@ var AppleNotesManager = class {
         tell account "${safeAccount}"
           set theNote to note "${safeTitle}"
         set attachmentList to {}
-        repeat with a in attachments of theNote
-          set attachId to id of a
-          set attachName to name of a
-          set attachContentId to content identifier of a
-          set attachUrl to ""
-          try
-            set attachUrl to URL of a as text
-          end try
-          set createdDate to creation date of a
-          set modifiedDate to modification date of a
+        set attachmentIds to id of every attachment of theNote
+        set attachmentNames to name of every attachment of theNote
+        set attachmentContentIds to content identifier of every attachment of theNote
+        set attachmentUrls to URL of every attachment of theNote
+        set attachmentCreatedDates to creation date of every attachment of theNote
+        set attachmentModifiedDates to modification date of every attachment of theNote
+        set attachmentSharedFlags to shared of every attachment of theNote
+        set attachmentIdsAfter to id of every attachment of theNote
+        if (count of attachmentNames) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentContentIds) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentUrls) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentCreatedDates) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentModifiedDates) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentSharedFlags) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        if (count of attachmentIdsAfter) is not (count of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        repeat with i from 1 to count of attachmentIds
+          if (item i of attachmentIdsAfter) is not (item i of attachmentIds) then error "${BULK_LIST_MUTATION_ERROR}"
+        end repeat
+        repeat with i from 1 to count of attachmentIds
+          set attachId to item i of attachmentIds
+          set attachName to item i of attachmentNames
+          set attachContentId to item i of attachmentContentIds
+          set attachUrl to item i of attachmentUrls as text
+          set createdDate to item i of attachmentCreatedDates
+          set modifiedDate to item i of attachmentModifiedDates
           set createdParts to ${asDatePartsExpr("createdDate")}
           set modifiedParts to ${asDatePartsExpr("modifiedDate")}
-          set sharedFlag to shared of a as text
+          set sharedFlag to item i of attachmentSharedFlags as text
           set end of attachmentList to attachId & ${AS_FIELD_SEP} & attachName & ${AS_FIELD_SEP} & attachContentId & ${AS_FIELD_SEP} & attachUrl & ${AS_FIELD_SEP} & createdParts & ${AS_FIELD_SEP} & modifiedParts & ${AS_FIELD_SEP} & sharedFlag
         end repeat
           set output to ""
@@ -40960,10 +41003,12 @@ var AppleNotesManager = class {
       end tell
     `;
     const result = executeAppleScript(script);
-    if (!result.success || !result.output) {
-      if (result.error) {
-        console.error(`Failed to list attachments for note "${title}":`, result.error);
-      }
+    if (!result.success) {
+      throw new Error(
+        `Failed to list attachments for note "${title}": ${result.error ?? "unknown AppleScript error"}`
+      );
+    }
+    if (!result.output) {
       return [];
     }
     const attachments = [];
@@ -41030,7 +41075,7 @@ var AppleNotesManager = class {
         return "OK" & ${AS_FIELD_SEP} & (name of theAttachment) & ${AS_FIELD_SEP} & (content identifier of theAttachment)
       end tell
     `;
-    const result = executeAppleScript(script);
+    const result = executeMutationAppleScript(script);
     if (!result.success) {
       return { success: false, error: result.error ?? "unknown error" };
     }
@@ -41164,7 +41209,7 @@ var AppleNotesManager = class {
         end repeat
         return out
       `);
-      const res = executeAppleScript(script);
+      const res = executeMutationAppleScript(script);
       if (!res.success) {
         for (const r of runnable) {
           results[r.index] = this.createBatchResult(
@@ -41274,7 +41319,7 @@ var AppleNotesManager = class {
         end repeat
         return out
       `);
-      const res = executeAppleScript(script);
+      const res = executeMutationAppleScript(script);
       if (!res.success) {
         for (const r of runnable) {
           results[r.index] = this.createBatchResult(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.6.4",
+  "version": "2.6.6",
   "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",