apple-notes-mcp 2.5.12 → 2.6.1

package/README.md

@@ -469,6 +469,71 @@ Moves a note to a different folder. The note is relocated in place via Notes.app
 
 ---
 
+#### `append-to-note`
+
+Appends or prepends content to an existing note without replacing it. Always reads and writes as HTML, preserving all existing rich formatting.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | No | Note ID (preferred - more reliable than title) |
+| `title` | string | No | Note title (use `id` instead when available) |
+| `content` | string | Yes | Text to append to the note body |
+| `position` | string | No | `"after"` (default) appends to the end; `"before"` prepends to the start |
+| `separator` | string | No | String placed between existing content and new content (default: two newlines → `<div><br></div>` in HTML) |
+| `format` | string | No | Format of the content being appended: `"plaintext"` (default) or `"html"` |
+| `account` | string | No | Account containing the note (defaults to iCloud, ignored if `id` is provided) |
+
+**Note:** Either `id` or `title` must be provided. Using `id` is recommended.
+
+**Example - Append plaintext:**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456",
+  "content": "New item added today"
+}
+```
+
+**Example - Prepend HTML:**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456",
+  "content": "<div><b>Status:</b> done</div>",
+  "format": "html",
+  "position": "before"
+}
+```
+
+**Returns:** Confirmation with note id and title. Warns when the note is shared with collaborators.
+
+**⚠️ Safety:** Reads the existing body first, concatenates, then writes back. Run `list-attachments` first if the note may hold embedded files — a full-body rewrite can drop attachments.
+
+---
+
+#### `get-note-link`
+
+Returns the `notes://showNote?identifier=<uuid>` deep-link URL for a note. The URL opens the note in Notes.app on iOS and macOS and can be stored in Reminders tasks or shared links.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | No | Note ID (preferred - more reliable than title) |
+| `title` | string | No | Note title (use `id` instead when available) |
+| `account` | string | No | Account containing the note (defaults to iCloud, ignored if `id` is provided) |
+
+**Note:** Either `id` or `title` must be provided. Using `id` is recommended. Password-protected notes cannot be linked.
+
+**Example:**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456"
+}
+```
+
+**Returns:** `notes://showNote?identifier=<uuid>` URL string, plus the note id and title.
+
+**Note:** Requires Full Disk Access for the app that launches the server so the Notes SQLite database is readable. On macOS 12–15 the tool also falls back to the AppleScript `note link` property. Run the `doctor` tool to verify access.
+
+---
+
 #### `list-notes`
 
 Lists all notes, optionally filtered by folder, date, and limit.

package/build/index.js

@@ -6,7 +6,13 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function __require() {
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
   try {
     return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
   } catch (e) {
@@ -24161,14 +24167,14 @@ var require_turndown_cjs = __commonJS({
         } else if (node.nodeType === 1) {
           replacement = replacementForNode.call(self, node);
         }
-        return join5(output, replacement);
+        return join6(output, replacement);
       }, "");
     }
     function postProcess(output) {
       var self = this;
       this.rules.forEach(function(rule) {
         if (typeof rule.append === "function") {
-          output = join5(output, rule.append(self.options));
+          output = join6(output, rule.append(self.options));
         }
       });
       return output.replace(/^[\t\r\n]+/, "").replace(/[\t\r\n\s]+$/, "");
@@ -24180,7 +24186,7 @@ var require_turndown_cjs = __commonJS({
       if (whitespace.leading || whitespace.trailing) content = content.trim();
       return whitespace.leading + rule.replacement(content, node, this.options) + whitespace.trailing;
     }
-    function join5(output, replacement) {
+    function join6(output, replacement) {
       var s1 = trimTrailingNewlines(output);
       var s2 = trimLeadingNewlines(replacement);
       var nls = Math.max(output.length - s1.length, replacement.length - s2.length);
@@ -38700,12 +38706,14 @@ function isTimeoutError(error2) {
   }
   return false;
 }
+var BULK_LIST_MUTATION_ERROR = "Notes changed during listing";
 var RETRYABLE_ERROR_PATTERNS = [
   /timed? out/i,
   /not responding/i,
   /connection.*invalid/i,
   /lost connection/i,
-  /busy/i
+  /busy/i,
+  /changed during listing/i
 ];
 function isRetryableError(errorMessage) {
   return RETRYABLE_ERROR_PATTERNS.some((pattern) => pattern.test(errorMessage));
@@ -38764,6 +38772,13 @@ var ERROR_MAPPINGS = [
     pattern: /password protected|locked note/i,
     message: "Note is password-protected. Unlock it in Notes.app first."
   },
+  // Mid-listing library mutation detected by a bulk-list count guard (#86).
+  // The message must keep the phrase "changed during listing" so
+  // RETRYABLE_ERROR_PATTERNS still matches it after this mapping.
+  {
+    pattern: /changed during listing/i,
+    message: "Notes changed during listing (an iCloud sync may have landed mid-read). The operation is retried automatically; run it again if this persists."
+  },
   // Syntax/script errors (usually programming bugs)
   {
     pattern: /syntax error|expected/i,
@@ -39200,6 +39215,8 @@ function cleanupTempDir(dir) {
 // src/services/appleNotesManager.ts
 var import_turndown = __toESM(require_turndown_cjs(), 1);
 import { existsSync as existsSync3 } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join2 } from "path";
 var FIELD_SEP = "";
 var RECORD_SEP = "";
 var AS_FIELD_SEP = "(ASCII character 31)";
@@ -39276,6 +39293,12 @@ function buildAppleScriptDateVar(date3, varName = "thresholdDate") {
   const timeInSeconds = date3.getHours() * 3600 + date3.getMinutes() * 60 + date3.getSeconds();
   return [
     `set ${varName} to current date`,
+    // Reset day to 1 BEFORE assigning month: AppleScript date components roll
+    // over, so setting month to (say) June while the variable still holds the
+    // 31st inherited from `current date` produces July 1 (June 31 doesn't
+    // exist), and the day assignment below then lands in the wrong month.
+    // Day 1 exists in every month, so year/month can never roll over. (#86)
+    `set day of ${varName} to 1`,
     `set year of ${varName} to ${year}`,
     `set month of ${varName} to ${month}`,
     `set day of ${varName} to ${day}`,
@@ -39342,6 +39365,27 @@ function buildAppLevelScript(command) {
     end tell
   `;
 }
+function getNoteLinkFromDB(coreDataId) {
+  const match = coreDataId.match(/\/p(\d+)$/);
+  if (!match) return null;
+  const pk = parseInt(match[1], 10);
+  const dbPath = join2(homedir3(), "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite");
+  if (!existsSync3(dbPath)) return null;
+  try {
+    const { DatabaseSync } = __require("node:sqlite");
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    try {
+      const row = db.prepare("SELECT ZIDENTIFIER FROM ZICCLOUDSYNCINGOBJECT WHERE Z_PK = ?").get(pk);
+      const identifier = row?.ZIDENTIFIER;
+      return identifier ? `notes://showNote?identifier=${identifier}` : null;
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    console.error("getNoteLinkFromDB: failed to query Notes database:", err);
+    return null;
+  }
+}
 function extractCoreDataId(output, prefix) {
   const pattern = new RegExp(`${prefix} id ([^\\s]+)`);
   const match = output.match(pattern);
@@ -39888,6 +39932,101 @@ var AppleNotesManager = class {
     }
     return true;
   }
+  /**
+   * Builds the AppleScript body for a bulk note listing.
+   *
+   * Names, ids, and (when date-filtering) modification dates are fetched as
+   * whole-list Apple Events instead of two events per note; per-note round
+   * trips scale linearly and push large libraries past client tool timeouts
+   * (#86). The lists are separate snapshots of a live, syncing collection, so
+   * every script guards that they are the same length before zipping them by
+   * index — a mid-listing mutation would otherwise silently mispair names and
+   * ids (grow) or read past the end of a list (shrink). On mismatch the
+   * script raises BULK_LIST_MUTATION_ERROR, which executeAppleScript treats
+   * as retryable, re-running the whole script on a fresh snapshot. A length
+   * check cannot see an exactly-offsetting delete+create landing in the
+   * milliseconds between two fetches; that residual window is accepted —
+   * closing it would cost an extra whole-list fetch per listing.
+   *
+   * @param folderRef - Optional AppleScript folder reference to scope to
+   * @param dateSetup - AppleScript defining thresholdDate; enables date filtering
+   * @param sliceLimit - Fetch only the first N notes (mutually exclusive with
+   *   dateSetup: a date filter must scan every note's date). The script then
+   *   returns the total note count as a leading record so the caller can
+   *   detect a dedup shortfall and fall back to a full fetch.
+   */
+  buildBulkListCommand(opts) {
+    const { folderRef, dateSetup, sliceLimit } = opts;
+    const fullSource = folderRef ? `notes of ${folderRef}` : "notes";
+    const countGuard = (listVar) => `if (count of ${listVar}) is not (count of noteNames) then error "${BULK_LIST_MUTATION_ERROR}"`;
+    if (sliceLimit !== void 0) {
+      const slicedSource = folderRef ? `(notes 1 thru fetchCount of ${folderRef})` : `(notes 1 thru fetchCount)`;
+      return `
+        set totalCount to count of ${fullSource}
+        set fetchCount to ${sliceLimit}
+        if fetchCount > totalCount then set fetchCount to totalCount
+        set resultList to {}
+        if fetchCount > 0 then
+          try
+            set noteNames to name of ${slicedSource}
+            set noteIds to id of ${slicedSource}
+          on error errMsg number errNum
+            if errNum is -1719 or errNum is -1728 then
+              error "${BULK_LIST_MUTATION_ERROR}"
+            else
+              error errMsg number errNum
+            end if
+          end try
+          ${countGuard("noteIds")}
+          repeat with i from 1 to count of noteNames
+            set end of resultList to (item i of noteNames) & ${AS_FIELD_SEP} & (item i of noteIds)
+          end repeat
+        end if
+        set AppleScript's text item delimiters to ${AS_RECORD_SEP}
+        return (totalCount as text) & ${AS_RECORD_SEP} & (resultList as text)
+      `;
+    }
+    const dateFetch = dateSetup ? `set noteDates to modification date of ${fullSource}
+        ` : "";
+    const dateCountGuard = dateSetup ? `${countGuard("noteDates")}
+        ` : "";
+    const dateGuardOpen = dateSetup ? `if (item i of noteDates) >= thresholdDate then
+            ` : "";
+    const dateGuardClose = dateSetup ? `
+          end if` : "";
+    return `
+        ${dateSetup ?? ""}set noteNames to name of ${fullSource}
+        set noteIds to id of ${fullSource}
+        ${dateFetch}${countGuard("noteIds")}
+        ${dateCountGuard}set resultList to {}
+        repeat with i from 1 to count of noteNames
+          ${dateGuardOpen}set end of resultList to (item i of noteNames) & ${AS_FIELD_SEP} & (item i of noteIds)${dateGuardClose}
+        end repeat
+        set AppleScript's text item delimiters to ${AS_RECORD_SEP}
+        return resultList as text
+      `;
+  }
+  /**
+   * Parses bulk listing output into deduplicated note titles.
+   *
+   * Duplicate CoreData references are deduped by id; the limit is applied
+   * after dedup so duplicates never count against it.
+   */
+  parseBulkListOutput(output, safeLimit) {
+    if (!output.trim()) return [];
+    const seenIds = /* @__PURE__ */ new Set();
+    const titles = [];
+    for (const item of output.split(RECORD_SEP)) {
+      const [title, id] = item.split(FIELD_SEP);
+      if (!title?.trim()) continue;
+      const noteId = id?.trim() || generateFallbackId();
+      if (seenIds.has(noteId)) continue;
+      seenIds.add(noteId);
+      titles.push(title.trim());
+      if (safeLimit !== void 0 && titles.length >= safeLimit) break;
+    }
+    return titles;
+  }
   /**
    * Lists all notes in an account, optionally filtered by folder, date, and limit.
    *
@@ -39900,89 +40039,41 @@ var AppleNotesManager = class {
   listNotes(account, folder, modifiedSince, limit) {
     const targetAccount = this.resolveAccount(account);
     const safeLimit = limit !== void 0 && limit > 0 ? Math.floor(limit) : void 0;
-    if (modifiedSince || safeLimit !== void 0) {
-      const baseNotesSource = folder ? `notes of ${buildFolderReference(folder)}` : "notes";
-      let dateSetup = "";
-      let notesSource = baseNotesSource;
-      if (modifiedSince) {
-        const date3 = new Date(modifiedSince);
-        if (!isNaN(date3.getTime())) {
-          dateSetup = buildAppleScriptDateVar(date3) + "\n";
-          notesSource = `(${baseNotesSource} whose modification date >= thresholdDate)`;
-        }
-      }
-      const limitCheck = safeLimit !== void 0 ? `
-            if (count of resultList) >= ${safeLimit} then exit repeat` : "";
-      const listCommand2 = `
-        ${dateSetup}set resultList to {}
-        set seenIds to {}
-        repeat with n in ${notesSource}
-          try
-            set noteName to name of n
-            set noteId to id of n
-            if seenIds does not contain noteId then
-              set end of seenIds to noteId
-              set end of resultList to noteName & ${AS_FIELD_SEP} & noteId${limitCheck}
-            end if
-          end try
-        end repeat
-        set AppleScript's text item delimiters to ${AS_RECORD_SEP}
-        return resultList as text
-      `;
-      const script2 = buildAccountScopedScript({ account: targetAccount }, listCommand2);
+    const folderRef = folder ? buildFolderReference(folder) : void 0;
+    let dateSetup;
+    if (modifiedSince) {
+      const date3 = new Date(modifiedSince);
+      if (!isNaN(date3.getTime())) {
+        dateSetup = buildAppleScriptDateVar(date3) + "\n";
+      }
+    }
+    if (safeLimit !== void 0 && !dateSetup) {
+      const script2 = buildAccountScopedScript(
+        { account: targetAccount },
+        this.buildBulkListCommand({ folderRef, sliceLimit: safeLimit })
+      );
       const result2 = executeAppleScript(script2);
       if (!result2.success) {
         throw new Error(`Failed to list notes: ${result2.error ?? "unknown error"}`);
       }
-      if (!result2.output.trim()) {
-        return [];
+      const sepIdx = result2.output.indexOf(RECORD_SEP);
+      const header = sepIdx === -1 ? result2.output : result2.output.slice(0, sepIdx);
+      const totalCount = Number.parseInt(header.trim(), 10);
+      const records = sepIdx === -1 ? "" : result2.output.slice(sepIdx + 1);
+      const titles = this.parseBulkListOutput(records, safeLimit);
+      if (!Number.isNaN(totalCount) && (titles.length >= safeLimit || totalCount <= safeLimit)) {
+        return titles;
       }
-      const seenIds2 = /* @__PURE__ */ new Set();
-      const titles2 = [];
-      for (const item of result2.output.split(RECORD_SEP)) {
-        const [title, id] = item.split(FIELD_SEP);
-        if (!title?.trim()) continue;
-        const noteId = id?.trim() || generateFallbackId();
-        if (seenIds2.has(noteId)) continue;
-        seenIds2.add(noteId);
-        titles2.push(title.trim());
-      }
-      return titles2;
     }
-    const notesRef = folder ? `notes of ${buildFolderReference(folder)}` : `notes`;
-    const listCommand = `
-      set resultList to {}
-      set seenIds to {}
-      repeat with n in ${notesRef}
-        try
-          set noteName to name of n
-          set noteId to id of n
-          if seenIds does not contain noteId then
-            set end of seenIds to noteId
-            set end of resultList to noteName & ${AS_FIELD_SEP} & noteId
-          end if
-        end try
-      end repeat
-      set AppleScript's text item delimiters to ${AS_RECORD_SEP}
-      return resultList as text
-    `;
-    const script = buildAccountScopedScript({ account: targetAccount }, listCommand);
+    const script = buildAccountScopedScript(
+      { account: targetAccount },
+      this.buildBulkListCommand({ folderRef, dateSetup })
+    );
     const result = executeAppleScript(script);
     if (!result.success) {
       throw new Error(`Failed to list notes: ${result.error ?? "unknown error"}`);
     }
-    if (!result.output.trim()) return [];
-    const seenIds = /* @__PURE__ */ new Set();
-    const titles = [];
-    for (const item of result.output.split(RECORD_SEP)) {
-      const [title, id] = item.split(FIELD_SEP);
-      if (!title?.trim()) continue;
-      const noteId = id?.trim() || generateFallbackId();
-      if (seenIds.has(noteId)) continue;
-      seenIds.add(noteId);
-      titles.push(title.trim());
-    }
-    return titles;
+    return this.parseBulkListOutput(result.output, safeLimit);
   }
   /**
    * Lists all shared (collaborative) notes across all accounts.
@@ -40406,6 +40497,47 @@ var AppleNotesManager = class {
     }
     return true;
   }
+  /**
+   * Returns the notes:// deep-link URL for a note by its CoreData ID.
+   *
+   * Primary path: queries the Notes SQLite database for ZIDENTIFIER, which
+   * is the UUID used in the notes://showNote?identifier= URL scheme. This
+   * is more reliable than the AppleScript `note link` property, which is
+   * absent from the Notes SDEF on macOS 26+.
+   *
+   * Fallback: AppleScript `note link` property (macOS 12–15).
+   *
+   * @param id - CoreData URL identifier for the note
+   * @returns notes://showNote?identifier=<uuid> string, or null on failure
+   */
+  getNoteLinkById(id) {
+    const note = this.getNoteById(id);
+    if (!note) return null;
+    if (note.passwordProtected) return null;
+    const sqliteLink = getNoteLinkFromDB(id);
+    if (sqliteLink) return sqliteLink;
+    const safeId = sanitizeId(id);
+    const result = executeAppleScript(
+      buildAppLevelScript(`return note link of (note id "${safeId}")`)
+    );
+    if (result.success && result.output.trim()) {
+      return result.output.trim();
+    }
+    console.error(`Failed to get note link for ID "${id}":`, result.error);
+    return null;
+  }
+  /**
+   * Returns the notes:// deep-link URL for a note by title.
+   *
+   * @param title - Exact note title
+   * @param account - Account to search in (defaults to iCloud)
+   * @returns notes://showNote?identifier=<uuid> string, or null on failure
+   */
+  getNoteLink(title, account) {
+    const note = this.getNoteDetails(title, account);
+    if (!note) return null;
+    return this.getNoteLinkById(note.id);
+  }
   /**
    * Reveals a folder in the Notes.app UI by its id.
    *
@@ -41697,12 +41829,12 @@ function formatDoctorReport(r) {
 
 // src/services/fileConfig.ts
 import { existsSync as existsSync6, readFileSync as readFileSync2 } from "fs";
-import { join as join4 } from "path";
-import { homedir as homedir5 } from "os";
+import { join as join5 } from "path";
+import { homedir as homedir6 } from "os";
 function fileConfigPath(env = process.env) {
   const override = env.APPLE_NOTES_MCP_CONFIG_FILE;
   if (override && override.trim()) return override.trim();
-  return join4(homedir5(), "Library", "Application Support", "apple-notes-mcp", "config.json");
+  return join5(homedir6(), "Library", "Application Support", "apple-notes-mcp", "config.json");
 }
 function loadFileConfig(env = process.env, path4 = fileConfigPath(env)) {
   const applied = [];
@@ -42153,6 +42285,61 @@ server.registerTool(
     return successResponse(`Shown note with ID "${id}" in Notes.app`, { id, separately });
   }, "Error showing note")
 );
+server.registerTool(
+  "get-note-link",
+  {
+    description: "Use when: you need the notes:// deep-link URL for a note so it can be stored in a Reminders task, shared, or opened directly.\nReturns: a notes://showNote?identifier=<uuid> URL that opens the note in Notes.app on iOS and macOS.\nDo not use when: you only need the note's CoreData id (get-note-by-id) or want to reveal the note on screen (show-note).\nNote: requires macOS 12+; returns an error on older systems.",
+    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("Note title (use id instead when available)"),
+      account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account containing the note (ignored if id is provided)")
+    },
+    outputSchema: {
+      id: external_exports.string().optional(),
+      title: external_exports.string().optional(),
+      url: external_exports.string().optional()
+    }
+  },
+  withErrorHandling(({ id, title, account }) => {
+    if (id) {
+      const note2 = notesManager.getNoteById(id);
+      if (!note2) {
+        return errorResponse(`Note with ID "${id}" not found`);
+      }
+      if (note2.passwordProtected) {
+        return errorResponse(
+          `Note "${note2.title}" is password-protected. Unlock it in Notes.app first.`
+        );
+      }
+      const url2 = notesManager.getNoteLinkById(id);
+      if (!url2) {
+        return errorResponse(
+          `Failed to get note link for "${note2.title}". The Notes database may not be accessible \u2014 grant Full Disk Access to the app that launches the server, fully quit and relaunch, then run the doctor tool. See: ${FULL_DISK_ACCESS_GUIDE_URL}. (On macOS 12\u201315 this also falls back to the AppleScript note link property.)`
+        );
+      }
+      return successResponse(`Note link: ${url2}`, { id, title: note2.title, url: url2 });
+    }
+    if (!title) {
+      return errorResponse("Either 'id' or 'title' is required");
+    }
+    const note = notesManager.getNoteDetails(title, account);
+    if (!note) {
+      return errorResponse(
+        `Note "${title}" not found. Use search-notes to find notes, then use the note's ID for reliable operations.`
+      );
+    }
+    if (note.passwordProtected) {
+      return errorResponse(`Note "${title}" is password-protected. Unlock it in Notes.app first.`);
+    }
+    const url = notesManager.getNoteLink(title, account);
+    if (!url) {
+      return errorResponse(
+        `Failed to get note link for "${title}". The Notes database may not be accessible \u2014 grant Full Disk Access to the app that launches the server, fully quit and relaunch, then run the doctor tool. See: ${FULL_DISK_ACCESS_GUIDE_URL}. (On macOS 12\u201315 this also falls back to the AppleScript note link property.)`
+      );
+    }
+    return successResponse(`Note link: ${url}`, { title, url });
+  }, "Error getting note link")
+);
 server.registerTool(
   "show-folder",
   {
@@ -42269,6 +42456,121 @@ server.registerTool(
     });
   }, "Error updating note")
 );
+server.registerTool(
+  "append-to-note",
+  {
+    description: "Use when: adding content to an existing note without replacing it, by id (preferred) or title.\nReturns: confirmation with the note id and title.\nDo not use when: creating a new note (create-note) or replacing the entire body (update-note).\nSafety: reads the existing body first, concatenates, then writes back. Run list-attachments first if the note may hold embedded files \u2014 a full-body rewrite can drop attachments.",
+    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("Note title (use id instead when available)"),
+      content: external_exports.string().min(1, "Content to append is required").max(MAX.CONTENT).describe("Text to append to the note body"),
+      position: external_exports.enum(["after", "before"]).optional().default("after").describe(
+        "Where to insert: 'after' appends to the end (default), 'before' prepends to the start"
+      ),
+      separator: external_exports.string().max(20).optional().default("\n\n").describe("String placed between existing content and new content (default: two newlines)"),
+      format: external_exports.enum(["plaintext", "html"]).optional().default("plaintext").describe("Format of the content being appended: 'plaintext' (default) or 'html'"),
+      account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account containing the note (ignored if id is provided)")
+    },
+    outputSchema: {
+      ok: external_exports.boolean().optional(),
+      id: external_exports.string().optional(),
+      title: external_exports.string().optional(),
+      shared: external_exports.boolean().optional()
+    }
+  },
+  withErrorHandling(
+    ({
+      id,
+      title,
+      content,
+      position = "after",
+      separator = "\n\n",
+      format = "plaintext",
+      account
+    }) => {
+      const contentToHtml = (text) => {
+        if (format === "html") return text;
+        return text.split("\n").map((line) => {
+          const escaped = line.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+          return `<div>${escaped || "<br>"}</div>`;
+        }).join("");
+      };
+      const separatorToHtml = (sep2) => {
+        if (format === "html") return sep2;
+        if (sep2 === "\n\n") return "<div><br></div>";
+        const escaped = sep2.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+        return `<div>${escaped}</div>`;
+      };
+      if (id) {
+        const note2 = notesManager.getNoteById(id);
+        if (!note2) {
+          return errorResponse(`Note with ID "${id}" not found`);
+        }
+        if (note2.passwordProtected) {
+          return errorResponse(
+            `Note "${note2.title}" is password-protected and cannot be updated. Unlock it in Notes.app first.`
+          );
+        }
+        const existingHtml2 = notesManager.getNoteContentById(id);
+        if (existingHtml2 === null || existingHtml2 === void 0) {
+          return errorResponse(`Failed to read content of note "${note2.title}"`);
+        }
+        const firstDivEnd2 = existingHtml2.indexOf("</div>");
+        const titleDiv2 = firstDivEnd2 !== -1 ? existingHtml2.slice(0, firstDivEnd2 + 6) : "";
+        const bodyHtml2 = firstDivEnd2 !== -1 ? existingHtml2.slice(firstDivEnd2 + 6) : existingHtml2;
+        const newBlock2 = contentToHtml(content);
+        const sepHtml2 = separatorToHtml(separator);
+        const combinedBody2 = position === "before" ? titleDiv2 + newBlock2 + sepHtml2 + bodyHtml2 : titleDiv2 + bodyHtml2 + sepHtml2 + newBlock2;
+        const success2 = notesManager.updateNoteById(id, void 0, combinedBody2, "html");
+        if (!success2) {
+          return errorResponse(`Failed to append to note "${note2.title}"`);
+        }
+        const sharedWarning2 = note2.shared ? "\n\n\u26A0\uFE0F This note is shared with collaborators. Your changes will be visible to them." : "";
+        return successResponse(`Note appended: "${note2.title}"${sharedWarning2}`, {
+          ok: true,
+          id,
+          title: note2.title,
+          shared: note2.shared ?? false
+        });
+      }
+      if (!title) {
+        return errorResponse("Either 'id' or 'title' is required");
+      }
+      const note = notesManager.getNoteDetails(title, account);
+      if (!note) {
+        return errorResponse(
+          `Note "${title}" not found. Use search-notes to find notes, then use the note's ID for reliable operations.`
+        );
+      }
+      if (note.passwordProtected) {
+        return errorResponse(
+          `Note "${title}" is password-protected and cannot be updated. Unlock it in Notes.app first.`
+        );
+      }
+      const existingHtml = notesManager.getNoteContent(title, account);
+      if (existingHtml === null || existingHtml === void 0) {
+        return errorResponse(`Failed to read content of note "${title}"`);
+      }
+      const firstDivEnd = existingHtml.indexOf("</div>");
+      const titleDiv = firstDivEnd !== -1 ? existingHtml.slice(0, firstDivEnd + 6) : "";
+      const bodyHtml = firstDivEnd !== -1 ? existingHtml.slice(firstDivEnd + 6) : existingHtml;
+      const newBlock = contentToHtml(content);
+      const sepHtml = separatorToHtml(separator);
+      const combinedBody = position === "before" ? titleDiv + newBlock + sepHtml + bodyHtml : titleDiv + bodyHtml + sepHtml + newBlock;
+      const success = notesManager.updateNote(title, void 0, combinedBody, account, "html");
+      if (!success) {
+        return errorResponse(`Failed to append to note "${title}"`);
+      }
+      const sharedWarning = note.shared ? "\n\n\u26A0\uFE0F This note is shared with collaborators. Your changes will be visible to them." : "";
+      return successResponse(`Note appended: "${title}"${sharedWarning}`, {
+        ok: true,
+        title,
+        shared: note.shared ?? false
+      });
+    },
+    "Error appending to note"
+  )
+);
 server.registerTool(
   "delete-note",
   {

package/package.json

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