apple-notes-mcp 2.6.3 → 2.6.5

package/README.md

@@ -362,6 +362,8 @@ Updates an existing note's content and/or title.
 
 **Note:** Either `id` or `title` must be provided. Using `id` is recommended.
 
+**Returns:** Confirmation with the note's visible title and, for ID-based updates, its ID. For HTML updates, the title comes from the first rendered line of `newContent`, matching Notes.app. The response also warns if the note is shared.
+
 **Example - Using ID (recommended):**
 ```json
 {
@@ -1017,8 +1019,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}":`,
@@ -41030,7 +41037,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 +41171,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 +41281,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(
@@ -41766,6 +41773,40 @@ function strippedImagesWarning(stripped) {
   )} decoded) exceeded the per-image inline cap and ${stripped.strippedCount === 1 ? "was" : "were"} replaced with placeholders so the response stays within MCP message limits. The images are still in the note: use list-attachments with save-attachment or fetch-attachment to export them, or raise APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES.`;
 }
 
+// src/utils/updateResponseTitle.ts
+var BLOCK_END_RE = /<\/(?:div|h[1-6]|p|li)>/gi;
+var BREAK_RE = /<br\s*\/?\s*>/gi;
+var TAG_RE = /<[^>]*>/g;
+var NON_RENDERED_BLOCK_RE = /<(script|style)\b[^>]*>[\s\S]*?(?:<\/\1>|$)/gi;
+function decodeHtmlEntities(text) {
+  const decodeCodePoint = (match, value, radix) => {
+    const codePoint = Number.parseInt(value, radix);
+    if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 1114111 || codePoint >= 55296 && codePoint <= 57343) {
+      return match;
+    }
+    return String.fromCodePoint(codePoint);
+  };
+  return text.replace(/&#x([0-9a-f]+);?/gi, (match, hex) => decodeCodePoint(match, hex, 16)).replace(/&#([0-9]+);?/g, (match, decimal) => decodeCodePoint(match, decimal, 10)).replace(/&nbsp(?:;|(?![0-9a-z]))/gi, " ").replace(/&quot(?:;|(?![0-9a-z]))/gi, '"').replace(/&apos(?:;|(?![0-9a-z]))/gi, "'").replace(/&lt(?:;|(?![0-9a-z]))/gi, "<").replace(/&gt(?:;|(?![0-9a-z]))/gi, ">").replace(/&amp(?:;|(?![0-9a-z]))/gi, "&");
+}
+function firstVisibleHtmlLine(html) {
+  let text = html;
+  let previous;
+  do {
+    previous = text;
+    text = text.replace(NON_RENDERED_BLOCK_RE, "");
+  } while (text !== previous);
+  text = text.replace(BREAK_RE, "\n").replace(BLOCK_END_RE, "\n");
+  do {
+    previous = text;
+    text = text.replace(TAG_RE, "");
+  } while (text !== previous);
+  return decodeHtmlEntities(text).split(/[\r\n\u2028\u2029]+/).map((line) => line.replace(/\s+/g, " ").trim()).find(Boolean);
+}
+function resolveUpdateResponseTitle(currentTitle, newTitle, format, newContent) {
+  if (format === "html") return firstVisibleHtmlLine(newContent) ?? currentTitle;
+  return newTitle || currentTitle;
+}
+
 // src/tools/doctor.ts
 import { spawnSync } from "child_process";
 function runDoctor(manager) {
@@ -42401,7 +42442,9 @@ server.registerTool(
     inputSchema: {
       id: external_exports.string().max(MAX.ID).optional().describe("Note ID (preferred - more reliable than title)"),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Current note title (use id instead when available)"),
-      newTitle: external_exports.string().max(MAX.TITLE).optional().describe("New title for the note"),
+      newTitle: external_exports.string().max(MAX.TITLE).optional().describe(
+        "New title for plaintext updates. Ignored when format is 'html'; include the visible title as the first line of newContent instead."
+      ),
       newContent: external_exports.string().min(1, "New content is required").max(MAX.CONTENT).describe(
         "New note body. AppleScript cannot produce true Apple Notes checklists; checkbox inputs and `- [ ]` markdown do not render as checkable items. Use a plain list and convert in Notes.app with \u21E7\u2318L."
       ),
@@ -42430,7 +42473,7 @@ server.registerTool(
       if (!success2) {
         return errorResponse(`Failed to update note "${note2.title}"`);
       }
-      const displayTitle = newTitle || note2.title;
+      const displayTitle = resolveUpdateResponseTitle(note2.title, newTitle, format, newContent);
       const sharedWarning2 = note2.shared ? "\n\n\u26A0\uFE0F This note is shared with collaborators. Your changes will be visible to them." : "";
       const checklistWarning2 = detectChecklistAttempt(newContent) ?? "";
       return successResponse(`Note updated: "${displayTitle}"${sharedWarning2}${checklistWarning2}`, {
@@ -42458,7 +42501,7 @@ server.registerTool(
     if (!success) {
       return errorResponse(`Failed to update note "${title}"`);
     }
-    const finalTitle = newTitle || title;
+    const finalTitle = resolveUpdateResponseTitle(note.title, newTitle, format, newContent);
     const sharedWarning = note.shared ? "\n\n\u26A0\uFE0F This note is shared with collaborators. Your changes will be visible to them." : "";
     const checklistWarning = detectChecklistAttempt(newContent) ?? "";
     return successResponse(`Note updated: "${finalTitle}"${sharedWarning}${checklistWarning}`, {

package/package.json

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