apple-notes-mcp 2.15.4 → 2.15.5

package/build/index.js

@@ -48713,33 +48713,11 @@ import { mkdtempSync as mkdtempSync3, writeFileSync as writeFileSync2, rmSync as
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join17 } from "node:path";
 
-// src/services/shortcutConsent.ts
-function shortcutConsentHint(shortcut) {
-  const target = shortcut ? `"${shortcut}"` : "the bridge Shortcut";
-  return `This may be an unanswered first-run Shortcuts consent prompt, which a background run cannot display: run ${target} once in the foreground in Shortcuts.app and choose Always Allow.`;
-}
-
-// src/services/nativeTags.ts
-var NATIVE_TAGS_SHORTCUT = "Apple Notes MCP - Native Tags";
-function normalizeNativeTags(tags) {
-  if (!tags.length || tags.length > 100) throw new Error("Provide between 1 and 100 tags");
-  return [
-    ...new Set(
-      tags.map((value) => {
-        const tag = value.normalize("NFC").replace(/^#/, "");
-        if (tag.length > 100 || !new RegExp("^(?=.*\\p{L})[\\p{L}\\p{N}_-]+$", "u").test(tag))
-          throw new Error(
-            "Tags must contain a letter and only letters, digits, hyphens or underscores"
-          );
-        return tag;
-      })
-    )
-  ];
-}
+// src/utils/richContentPreservation.ts
 var TAG_OBJECT_TYPE = "com.apple.notes.inlinetextattachment.hashtag";
 function requirePreservationMetadata(rich) {
-  const unavailable = () => {
-    throw new Error("Native object, checklist or formatting preservation metadata is unavailable");
+  const unavailable = (message = "Native object, checklist or formatting preservation metadata is unavailable") => {
+    throw new Error(message);
   };
   const { objects, objectData, checklistItems, styleRuns, nativeTagObjectIds } = rich;
   if (!objects || !objectData || !checklistItems || !styleRuns || !nativeTagObjectIds || rich.nativeObjectDataComplete !== true)
@@ -48774,16 +48752,173 @@ function requirePreservationMetadata(rich) {
       return unavailable();
   }
   let position = 0;
+  const firstReferences = /* @__PURE__ */ new Map();
   for (const run of styleRuns) {
     if (run.start !== position || !Number.isInteger(run.length) || run.length < 0 || typeof run.signature !== "string" || run.nativeSemantics?.complete !== true || run.length === 0 && (run.nativeSemantics.unknown || run.nativeSemantics.structuredParagraph || run.nativeSemantics.links || run.nativeSemantics.objects.length > 0))
       return unavailable();
+    const references = run.nativeSemantics.objects;
+    if (references.length > 1 || rich.text.slice(run.start, run.start + run.length).includes("\uFFFC") && references.length !== 1)
+      return unavailable("Native object placement preservation metadata is unavailable");
+    for (const reference of references) {
+      if (!objectData.some((data) => data.id === reference.id && data.type === reference.type))
+        return unavailable("Native object placement preservation metadata is unavailable");
+      if (!firstReferences.has(reference.id))
+        firstReferences.set(reference.id, {
+          start: run.start,
+          length: run.length,
+          type: reference.type
+        });
+    }
     position += run.length;
   }
   if (position !== rich.text.length) return unavailable();
+  if (objects.some((object3) => {
+    const reference = firstReferences.get(object3.id);
+    return !reference || reference.start !== object3.start || reference.length !== object3.length || reference.type !== object3.type;
+  }))
+    return unavailable("Native object placement preservation metadata is unavailable");
   for (const link of rich.links)
     if (!Number.isInteger(link.start) || !Number.isInteger(link.length) || link.start < 0 || link.length < 1 || link.start + link.length > rich.text.length || rich.text.slice(link.start, link.start + link.length) !== link.text)
       return unavailable();
 }
+function assertZeroLengthFormatting(before, after, spans) {
+  const oldEmpty = before.styleRuns.filter((run) => run.length === 0).map((run) => {
+    const span = spans.find(
+      (span2) => run.start >= span2.before && run.start <= span2.before + span2.length
+    );
+    if (!span) throw new Error("Zero-length formatting falls inside the requested removal");
+    return { ...run, start: span.after + run.start - span.before };
+  });
+  const newEmpty = after.styleRuns.filter(
+    (run) => run.length === 0 && spans.some((span) => run.start >= span.after && run.start <= span.after + span.length)
+  );
+  if (JSON.stringify(oldEmpty) !== JSON.stringify(newEmpty))
+    throw new Error("Existing zero-length formatting metadata changed");
+}
+function retainedSpans(before, after, change) {
+  if (change.kind !== "remove-tag") {
+    if (change.kind === "append" ? !after.text.startsWith(before.text) : after.text !== before.text)
+      throw new Error("Existing note text or whitespace was not preserved");
+    return {
+      spans: [{ before: 0, after: 0, length: before.text.length }],
+      removed: /* @__PURE__ */ new Set()
+    };
+  }
+  const removed = new Set(before.nativeTagObjectIds[change.tag]);
+  if (!removed.size || after.nativeTags.includes(change.tag))
+    throw new Error("Native tag removal was not verified");
+  const spans = [];
+  let position = 0, output = "";
+  for (const object3 of before.objects.filter((object4) => removed.has(object4.id))) {
+    const text2 = before.text.slice(object3.start, object3.start + object3.length);
+    if (text2 !== "\uFFFC" && text2 !== `#${change.tag}`)
+      throw new Error("Native tag removal range is unsupported");
+    const prefix = before.text.slice(position, object3.start);
+    spans.push({ before: position, after: output.length, length: prefix.length });
+    output += prefix;
+    position = object3.start + object3.length;
+  }
+  spans.push({ before: position, after: output.length, length: before.text.length - position });
+  output += before.text.slice(position);
+  if (after.text !== output)
+    throw new Error("Existing note text or whitespace was not preserved around the removed tag");
+  return { spans, removed };
+}
+function assertRetainedRichContent(before, after, change = { kind: "unchanged" }) {
+  requirePreservationMetadata(before);
+  requirePreservationMetadata(after);
+  const { spans, removed } = retainedSpans(before, after, change);
+  const rangeStart = (start, length) => {
+    const span = spans.find(
+      (span2) => start >= span2.before && start + length <= span2.before + span2.length
+    );
+    return span && span.after + start - span.before;
+  };
+  const retainedIds = before.nativeObjectIds.filter((id2) => !removed.has(id2));
+  if (retainedIds.some((id2) => !after.nativeObjectIds.includes(id2)) || [...removed].some((id2) => after.nativeObjectIds.includes(id2)) || change.kind !== "append" && after.nativeObjectIds.length !== retainedIds.length || change.kind === "append" && after.objects.some(
+    (object3) => !retainedIds.includes(object3.id) && object3.start < before.text.length
+  ))
+    throw new Error("Existing native object identity or placement changed");
+  for (const object3 of before.objects.filter((object4) => !removed.has(object4.id))) {
+    const actual = after.objects.find((current) => current.id === object3.id);
+    if (actual.type !== object3.type || actual.length !== object3.length || actual.start !== rangeStart(object3.start, object3.length))
+      throw new Error("Existing native object range changed");
+    const oldData = before.objectData.find((row) => row.id === object3.id), newData = after.objectData.find((row) => row.id === object3.id);
+    if (oldData.pk !== newData.pk || oldData.type !== newData.type || oldData.mergeable !== newData.mergeable || oldData.view !== newData.view || oldData.altText !== newData.altText)
+      throw new Error("Existing native object payload changed");
+  }
+  const tags = before.nativeTags.filter(
+    (tag) => change.kind !== "remove-tag" || tag !== change.tag
+  );
+  if (tags.some(
+    (tag) => JSON.stringify(before.nativeTagObjectIds[tag]) !== JSON.stringify(after.nativeTagObjectIds[tag])
+  ) || change.kind !== "append" && after.nativeTags.length !== tags.length)
+    throw new Error("Existing native tag identities changed");
+  const links = change.kind === "append" ? after.links.filter((link) => link.start < before.text.length) : after.links;
+  if (links.length !== before.links.length || before.links.some((link, index) => {
+    const actual = links[index];
+    return actual.text !== link.text || actual.url !== link.url || actual.length !== link.length || actual.start !== rangeStart(link.start, link.length);
+  }))
+    throw new Error("Existing links or their ranges were not preserved");
+  const items = change.kind === "append" ? after.checklistItems.filter((item) => item.start < before.text.length) : after.checklistItems;
+  if (items.length !== before.checklistItems.length || before.checklistItems.some((item, index) => {
+    const actual = items[index];
+    const retained = spans.flatMap((span) => {
+      const start2 = Math.max(item.start, span.before), end = Math.min(item.start + item.text.length, span.before + span.length);
+      return start2 < end ? [before.text.slice(start2, end)] : [];
+    }).join("");
+    const startSpan = spans.find(
+      (span) => item.start >= span.before && item.start <= span.before + span.length
+    );
+    const start = startSpan && startSpan.after + item.start - startSpan.before;
+    return actual.id !== item.id || actual.text !== retained || actual.done !== item.done || actual.start !== start;
+  }))
+    throw new Error("Existing checklist item identity, state or range changed");
+  for (const span of spans) {
+    let offset = 0, oldIndex = 0, newIndex = 0;
+    while (offset < span.length) {
+      const oldPosition = span.before + offset, newPosition = span.after + offset;
+      while (before.styleRuns[oldIndex].start + before.styleRuns[oldIndex].length <= oldPosition)
+        oldIndex++;
+      while (after.styleRuns[newIndex].start + after.styleRuns[newIndex].length <= newPosition)
+        newIndex++;
+      const oldRun = before.styleRuns[oldIndex], newRun = after.styleRuns[newIndex];
+      if (oldRun.signature !== newRun.signature || oldRun.paragraphStyle !== newRun.paragraphStyle || oldRun.blockQuote !== newRun.blockQuote || oldRun.highlight !== newRun.highlight)
+        throw new Error("Existing rich formatting changed");
+      offset += Math.min(
+        span.length - offset,
+        oldRun.start + oldRun.length - oldPosition,
+        newRun.start + newRun.length - newPosition
+      );
+    }
+  }
+  assertZeroLengthFormatting(before, after, spans);
+}
+
+// src/services/shortcutConsent.ts
+function shortcutConsentHint(shortcut) {
+  const target = shortcut ? `"${shortcut}"` : "the bridge Shortcut";
+  return `This may be an unanswered first-run Shortcuts consent prompt, which a background run cannot display: run ${target} once in the foreground in Shortcuts.app and choose Always Allow.`;
+}
+
+// src/services/nativeTags.ts
+var NATIVE_TAGS_SHORTCUT = "Apple Notes MCP - Native Tags";
+function normalizeNativeTags(tags) {
+  if (!tags.length || tags.length > 100) throw new Error("Provide between 1 and 100 tags");
+  return [
+    ...new Set(
+      tags.map((value) => {
+        const tag = value.normalize("NFC").replace(/^#/, "");
+        if (tag.length > 100 || !new RegExp("^(?=.*\\p{L})[\\p{L}\\p{N}_-]+$", "u").test(tag))
+          throw new Error(
+            "Tags must contain a letter and only letters, digits, hyphens or underscores"
+          );
+        return tag;
+      })
+    )
+  ];
+}
+var TAG_OBJECT_TYPE2 = "com.apple.notes.inlinetextattachment.hashtag";
 function plainNativeRange(rich, start, length) {
   return rich.styleRuns.every((run) => {
     if (run.start >= start + length || run.start + run.length <= start) return true;
@@ -48799,7 +48934,7 @@ function preservedTextSpans(before, after, missing) {
       ([tag, ids]) => ids.map((id2) => [id2, tag])
     )
   );
-  if (!added.length || added.some((o) => o.type !== TAG_OBJECT_TYPE || !missing.includes(tagsById.get(o.id))) || missing.some((tag) => !added.some((o) => tagsById.get(o.id) === tag)))
+  if (!added.length || added.some((o) => o.type !== TAG_OBJECT_TYPE2 || !missing.includes(tagsById.get(o.id))) || missing.some((tag) => !added.some((o) => tagsById.get(o.id) === tag)))
     return void 0;
   const spans = [];
   let oldPosition = 0, newPosition = 0, appended = false;
@@ -48856,6 +48991,11 @@ function preservesAddedSemantics(before, after, spans) {
   return true;
 }
 function preservesNativeContent(before, after, spans) {
+  try {
+    assertZeroLengthFormatting(before, after, spans);
+  } catch {
+    return false;
+  }
   const rangeStart = (start, length) => {
     const span = spans.find((s) => start >= s.before && start + length <= s.before + s.length);
     return span && span.after + start - span.before;
@@ -48906,6 +49046,16 @@ function preservesNativeContent(before, after, spans) {
   }
   return true;
 }
+function nativeTagAdditionPreserved(before, after, tags) {
+  requirePreservationMetadata(before);
+  requirePreservationMetadata(after);
+  const missing = tags.filter((tag) => !before.nativeTags.includes(tag));
+  const allTags = [.../* @__PURE__ */ new Set([...before.nativeTags, ...tags])];
+  const spans = preservedTextSpans(before, after, missing);
+  return after.nativeTags.length === allTags.length && allTags.every((tag) => after.nativeTags.includes(tag)) && before.nativeObjectIds.every((id2) => after.nativeObjectIds.includes(id2)) && before.hasChecklist === after.hasChecklist && Boolean(
+    spans && preservesAddedSemantics(before, after, spans) && preservesNativeContent(before, after, spans)
+  );
+}
 function addNativeTags(request, deps) {
   if (!/^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i.test(request.id))
     throw new Error("An exact CoreData note ID is required");
@@ -48947,9 +49097,7 @@ function addNativeTags(request, deps) {
   } catch (error2) {
     throw verificationFailure(error2 instanceof Error ? error2.message : String(error2));
   }
-  const allTags = [.../* @__PURE__ */ new Set([...before.rich.nativeTags, ...tags])];
-  const spans = preservedTextSpans(before.rich, after.rich, missing);
-  if (after.title !== before.title || after.rich.nativeTags.length !== allTags.length || allTags.some((tag) => !after.rich.nativeTags.includes(tag)) || before.rich.nativeObjectIds.some((id2) => !after.rich.nativeObjectIds.includes(id2)) || before.rich.hasChecklist !== after.rich.hasChecklist || !spans || !preservesAddedSemantics(before.rich, after.rich, spans) || !preservesNativeContent(before.rich, after.rich, spans)) {
+  if (after.title !== before.title || !nativeTagAdditionPreserved(before.rich, after.rich, tags)) {
     throw verificationFailure();
   }
   return {
@@ -49389,53 +49537,25 @@ function backgroundDependencies(manager) {
 function assertPreserved(before, after, options = {}) {
   if (before.id !== after.id || before.title !== after.title)
     throw new Error("Note identity changed");
-  const tidy = (s) => s.replace(/\r\n/g, "\n").replace(/[\s\ufffc]+$/gu, "");
-  let oldText = tidy(before.rich.text), newText = tidy(after.rich.text);
-  if (options.tagChange) {
-    const escaped = options.tagChange.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const strip = (s) => s.replace(new RegExp(`#${escaped}(?![\\p{L}\\p{N}_-])`, "gu"), "").replace(/[\s\ufffc]/gu, "");
-    oldText = strip(oldText);
-    newText = strip(newText);
-  }
-  if (options.append ? !newText.startsWith(oldText) : newText !== oldText)
-    throw new Error("Existing note text was not preserved");
-  const links = options.append ? after.rich.links.slice(0, before.rich.links.length) : after.rich.links;
-  if (linkSignature(before.rich.links) !== linkSignature(links))
-    throw new Error("Existing links were not preserved");
-  if (!options.tagChange && before.rich.nativeObjectIds.some((id2) => !after.rich.nativeObjectIds.includes(id2)))
-    throw new Error("Existing native object was lost");
-  if (JSON.stringify(before.checklist) !== JSON.stringify(
-    options.append ? after.checklist.slice(0, before.checklist.length) : after.checklist
-  ))
-    throw new Error("Existing checklist items changed");
-  for (const item of before.rich.checklistItems || []) {
-    const actual = after.rich.checklistItems?.find((current) => current.id === item.id);
-    if (!actual || actual.text !== item.text || actual.done !== item.done)
-      throw new Error("Existing checklist item identity or state changed");
-  }
-  if (before.rich.nativeTags.filter((t) => t !== options.tagChange).some((t) => !after.rich.nativeTags.includes(t)))
-    throw new Error("Existing native tag was lost");
-  const allowedRemoved = options.tagChange ? before.rich.nativeTagObjectIds?.[options.tagChange] || [] : [];
-  for (const object3 of before.rich.objectData || []) {
-    if (allowedRemoved.includes(object3.id)) continue;
-    const actual = after.rich.objectData?.find((o) => o.id === object3.id);
-    if (!actual || actual.mergeable !== object3.mergeable || actual.view !== object3.view)
-      throw new Error("Existing native object content or presentation changed");
-  }
-  if (!options.tagChange && before.rich.styleRuns && after.rich.styleRuns) {
-    const end = before.rich.text.trimEnd().length;
-    for (const oldRun of before.rich.styleRuns)
-      for (const newRun of after.rich.styleRuns) {
-        const overlapStart = Math.max(oldRun.start, newRun.start);
-        const overlapEnd = Math.min(
-          end,
-          oldRun.start + oldRun.length,
-          newRun.start + newRun.length
-        );
-        if (overlapStart < overlapEnd && /[^\s\ufffc]/u.test(before.rich.text.slice(overlapStart, overlapEnd)) && oldRun.signature !== newRun.signature)
-          throw new Error("Existing rich formatting changed");
-      }
+  if (options.tagChange && !options.removeTag) {
+    if (!nativeTagAdditionPreserved(before.rich, after.rich, [options.tagChange]))
+      throw new Error("Native tag addition or retained content was not verified");
+  } else {
+    try {
+      assertRetainedRichContent(
+        before.rich,
+        after.rich,
+        options.tagChange ? { kind: "remove-tag", tag: options.tagChange } : options.append ? { kind: "append" } : { kind: "unchanged" }
+      );
+    } catch (error2) {
+      if (error2 instanceof Error && error2.message === "Existing note text or whitespace was not preserved")
+        throw new Error("Existing note text was not preserved", { cause: error2 });
+      throw error2;
+    }
   }
+  for (const snapshot of [before, after])
+    if (JSON.stringify(snapshot.checklist) !== JSON.stringify(snapshot.rich.checklistItems.map(({ text: text2, done }) => ({ text: text2, done }))))
+      throw new Error("Native checklist readers disagree about item text or state");
 }
 function describeTransportFailure(error2) {
   const detail = error2;
@@ -49449,12 +49569,37 @@ function textBelowTitle(text2, title) {
   if (firstLine.trim() !== title.trim()) return text2;
   return lineEnd < 0 ? "" : text2.slice(lineEnd + 1);
 }
+function assertChecklistEndAppendAvailable(rich) {
+  requirePreservationMetadata(rich);
+  const items = [...rich.checklistItems].sort((a, b) => a.start - b.start);
+  if (!items.length) return;
+  const last = items.at(-1);
+  if (items.some(
+    (item, index) => item.start > 0 && rich.text[item.start - 1] !== "\n" || index > 0 && item.start !== items[index - 1].start + items[index - 1].text.length + 1
+  ) || !/^\n?$/u.test(rich.text.slice(last.start + last.text.length)))
+    throw new CodedError(
+      "Checklist end-append requires one existing checklist group at the end of the note. Notes may insert into an earlier group when text or native objects follow it, or when groups are separate. Nothing changed",
+      { code: "validation_error", committed: false, indeterminate: false }
+    );
+}
+function requireBackgroundPreflightMetadata(rich) {
+  try {
+    requirePreservationMetadata(rich);
+  } catch (error2) {
+    throw new CodedError(error2 instanceof Error ? error2.message : String(error2), {
+      code: "validation_error",
+      committed: false,
+      indeterminate: false
+    });
+  }
+}
 function mutateBackground(request, operation, data, verify, deps) {
   if (request.scopeText.length < 12 || request.scopeText.length > 500 || /[\r\n\0]/u.test(request.scopeText))
     throw new Error("Use a distinctive existing single-line scope of 12\u2013500 characters");
   const before = deps.read(request.id);
   if (before.hash !== request.expectedContentHash)
     throw new Error("Note revision changed; read it again");
+  requireBackgroundPreflightMetadata(before.rich);
   if (!before.rich.text.includes(request.scopeText))
     throw new Error("Scope is absent from exact note");
   if (!textBelowTitle(before.rich.text, before.title).includes(request.scopeText))
@@ -49465,8 +49610,10 @@ function mutateBackground(request, operation, data, verify, deps) {
   const candidates = deps.candidates(before.title, request.scopeText);
   if (candidates.length !== 1 || candidates[0] !== request.id)
     throw new Error("Ambiguous note selection; nothing changed");
-  if (deps.read(request.id).hash !== before.hash)
-    throw new Error("Note revision changed during preflight");
+  const current = deps.read(request.id);
+  if (current.hash !== before.hash) throw new Error("Note revision changed during preflight");
+  requireBackgroundPreflightMetadata(current.rich);
+  if (operation === "create-checklist-item") assertChecklistEndAppendAvailable(current.rich);
   let transportUncertain = false;
   let transportMessage = "";
   let transportError;
@@ -49570,7 +49717,7 @@ function setNativeTag(manager, request) {
     request.present ? "add-tag" : "remove-tag",
     { tag },
     (before, after) => {
-      assertPreserved(before, after, { tagChange: tag });
+      assertPreserved(before, after, { tagChange: tag, removeTag: !request.present });
       if (after.rich.nativeTags.includes(tag) !== request.present)
         throw new Error("Native tag state not verified");
       const removed = before.rich.nativeObjectIds.filter(
@@ -55509,30 +55656,13 @@ function readSnapshot(manager, id2) {
   const rich = readRichNote(id2);
   if (enriched.revision !== rich.revision)
     throw new Error("Native metadata changed during read; read the note again");
+  requirePreservationMetadata(rich);
   return { id: id2, title: note.title, body, rich, hash: richContentHash(body, enriched) };
 }
 function assertExistingContentPreserved(before, after) {
   if (before.id !== after.id || before.title !== after.title)
     throw new Error("Note identity changed");
-  const tidy = (text2) => text2.replace(/\r\n/g, "\n").replace(/[\s\ufffc]+$/gu, "");
-  if (!tidy(after.rich.text).startsWith(tidy(before.rich.text)))
-    throw new Error("Existing note text was not preserved");
-  if (linkSignature(before.rich.links) !== linkSignature(after.rich.links.slice(0, before.rich.links.length)))
-    throw new Error("Existing links were not preserved");
-  if (before.rich.nativeObjectIds.some((id2) => !after.rich.nativeObjectIds.includes(id2)))
-    throw new Error("Existing native object was lost");
-  if (before.rich.nativeTags.some((tag) => !after.rich.nativeTags.includes(tag)))
-    throw new Error("Existing native tag was lost");
-  for (const item of before.rich.checklistItems || []) {
-    const actual = after.rich.checklistItems?.find((current) => current.id === item.id);
-    if (!actual || actual.text !== item.text || actual.done !== item.done)
-      throw new Error("Existing checklist item identity or state changed");
-  }
-  for (const object3 of before.rich.objectData || []) {
-    const actual = after.rich.objectData?.find((current) => current.id === object3.id);
-    if (!actual || actual.mergeable !== object3.mergeable || actual.view !== object3.view)
-      throw new Error("Existing native object content or presentation changed");
-  }
+  assertRetainedRichContent(before.rich, after.rich, { kind: "append" });
 }
 function localAttachment(path10) {
   if (!isAbsolute4(path10)) throw new Error("An absolute local file path is required");
@@ -55909,8 +56039,19 @@ function attachFile(manager, args, checked, progress = { insertionStarted: false
         transportWarning: "Transport was uncertain; exact bytes and prior content were verified"
       } : {}
     };
+  } catch (error2) {
+    if (progress.insertionStarted)
+      throw new CodedError(
+        `Attachment outcome uncertain; read the exact note before any retry: ${error2 instanceof Error ? error2.message : String(error2)}`,
+        { code: "verification_failed", indeterminate: true }
+      );
+    throw error2;
   } finally {
-    rmSync7(directory, { recursive: true, force: true });
+    try {
+      rmSync7(directory, { recursive: true, force: true });
+    } catch {
+      console.error("Could not remove private temporary attachment files");
+    }
   }
 }
 
@@ -59994,7 +60135,7 @@ function registerNativeOperations(server2, manager) {
   );
   tool(
     "create-checklist-item",
-    "Use when: appending one real unchecked Notes checklist item.\nReturns: the created checklist identity after exact-note readback.\nDo not use when: plain text is sufficient or more than one item is requested.\nSafety: preserves existing text, links, native objects, checklist identities, and formatting.",
+    "Use when: appending one real unchecked Notes checklist item.\nReturns: the created checklist identity after exact-note readback.\nDo not use when: plain text is sufficient or more than one item is requested.\nSafety: preserves existing text, links, native objects, checklist identities, and formatting. If a checklist already exists, requires one contiguous group at the end of the note; otherwise refuses before running the bridge.",
     {
       ...common,
       text: external_exports.string().min(1).max(1e4).refine((s) => !/[\r\n\0]/u.test(s), "One line per checklist item")
@@ -60018,7 +60159,7 @@ function registerNativeOperations(server2, manager) {
   );
   tool(
     "create-checklist-items",
-    "Use when: appending several real unchecked Notes checklist items to one note, in order.\nReturns: each landed item's native identity and text, the final order check, and the new revision; on a stop, which items landed, the item whose outcome is uncertain, and the items not attempted.\nDo not use when: one item is enough (create-checklist-item) or plain text is sufficient.\nSafety: runs the verified single-item bridge once per item, chaining each verified revision into the next; checks after every item that exactly one new unchecked item with that text and a new identity appeared and that earlier items kept theirs, and stops at the first uncertain result without retrying. Each item takes a few seconds, so a full batch can run about a minute; if the call times out on the client side, read the note before retrying and send only items that are not present.",
+    "Use when: appending several real unchecked Notes checklist items to one note, in order.\nReturns: each landed item's native identity and text, the final order check, and the new revision; on a stop, which items landed, the item whose outcome is uncertain, and the items not attempted.\nDo not use when: one item is enough (create-checklist-item) or plain text is sufficient.\nSafety: runs the verified single-item bridge once per item, chaining each verified revision into the next; requires any existing checklist to be one contiguous group at the end of the note before dispatch. Checks after every item that exactly one new unchecked item with that text and a new identity appeared and that earlier items kept theirs, and stops at the first uncertain result without retrying. Each item takes a few seconds, so a full batch can run about a minute; if the call times out on the client side, read the note before retrying and send only items that are not present.",
     {
       ...common,
       items: external_exports.array(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.15.4",
+  "version": "2.15.5",
   "description": "MCP server for Apple Notes - read, search, create, edit, organize, and export notes on macOS via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",