apple-notes-mcp 2.15.2 → 2.15.4

package/README.md

@@ -2899,6 +2899,35 @@ title, modification date, folder identifier, lock/trash/shared/editable
 flags, iCloud version counters, and a `revision` change token (compare two
 reads to detect a change). Opens the store with Core Data's read-only option.
 
+#### `native-checklist-state`
+
+Reads one note's native checklist by Notes UUID (`identifier`) or x-coredata
+`id`; pass exactly one. The `id` is resolved through an exact read-only database
+lookup after checking the opt-in and installed hashes. Requires the same opt-in, current helper, and Full Disk
+Access as `native-note-state`. Check `native-helper-status`'s `readChecklist`
+feature first: its probe checks the checklist getters separately. Locked notes
+or unavailable native bodies are refused. Ordinary `☐` glyphs and Markdown
+task text do not count as native checklist items.
+
+Returns `identifier`, `revision`, `items`, `total`, `checked`, and
+`syncHostRunning`. Each item has its exact native `todoIdentifier` (32 lowercase
+hex digits), `uuid`, `index`, `done`, and `text`. Items follow the first occurrence
+of each native todo identity, which can cover multiple style runs. `text` is the
+line containing its first visible styled character, or the first styled line
+when it has only line terminators. `lineStart`, `lineLengthUTF16`, `styledStart`,
+and `styledLengthUTF16` are UTF-16 offsets and lengths; line text excludes the
+terminator. The styled range is an envelope, including intervening characters
+when the identity occurs in separated runs.
+
+Read the ambiguity flags before treating an entry as a single checklist row:
+`contiguous: false` means separated runs share the identity; `consistent: false`
+means their done bits disagree; `spansLines: true` means its styled envelope
+contains multiple lines after leading/trailing terminators are removed. `done`
+comes from the first visible styled character, falling back to the first run.
+Totals count native identities, including ambiguous ones. The `revision` is an
+informational change token. This tool opens the store read-only and cannot
+toggle, create, or repair checklist items.
+
 ## Usage Patterns
 
 ### Basic Workflow

package/build/index.js

@@ -40498,6 +40498,87 @@ function styleValue(field) {
   }
   return Buffer.from(field.value).toString("hex");
 }
+function storedStyleSignature(data) {
+  return JSON.stringify(
+    decodeWireFields(data).filter((field) => field.fieldNumber !== 1).map((field) => [
+      field.fieldNumber,
+      field.wireType,
+      field.bytes ? styleValue({
+        fieldNumber: field.fieldNumber,
+        wireType: field.wireType,
+        value: field.bytes
+      }) : field.varint.toString()
+    ])
+  );
+}
+function nativeRunSemantics(data) {
+  const result = {
+    complete: true,
+    unknown: false,
+    structuredParagraph: false,
+    links: false,
+    objects: []
+  };
+  const check2 = (fields, schema) => {
+    const seen = /* @__PURE__ */ new Set();
+    for (const field of fields) {
+      if (!Object.hasOwn(schema, field.fieldNumber)) result.unknown = true;
+      else if (seen.has(field.fieldNumber) || field.wireType !== schema[field.fieldNumber])
+        result.complete = false;
+      seen.add(field.fieldNumber);
+    }
+  };
+  const nested = (field) => {
+    if (field.wireType !== 2 || !field.bytes) {
+      result.complete = false;
+      return [];
+    }
+    return decodeWireFields(field.bytes);
+  };
+  try {
+    const fields = decodeWireFields(data);
+    check2(fields, { 1: 0, 2: 2, 3: 2, 5: 0, 6: 0, 7: 0, 8: 0, 9: 2, 10: 2, 12: 2, 14: 0 });
+    if (fields.filter((f) => f.fieldNumber === 1).length !== 1) result.complete = false;
+    result.links = fields.some((f) => f.fieldNumber === 9);
+    for (const field of fields) {
+      if (field.fieldNumber === 2) {
+        const paragraph = nested(field);
+        check2(paragraph, { 1: 0, 2: 0, 4: 0, 5: 2, 8: 0, 9: 2 });
+        for (const style of paragraph.filter((f) => f.fieldNumber === 1)) {
+          const type = style.varint === void 0 ? void 0 : Number(BigInt.asIntN(64, style.varint));
+          if (type !== void 0 && type >= 100 && type <= 103) result.structuredParagraph = true;
+          else if (type === void 0 || ![-1, 0, 1, 2, 3, 4].includes(type)) result.unknown = true;
+        }
+        for (const uuid2 of paragraph.filter((f) => f.fieldNumber === 9))
+          if (uuid2.bytes?.length !== 16) result.complete = false;
+        for (const todo of paragraph.filter((f) => f.fieldNumber === 5)) {
+          result.structuredParagraph = true;
+          const item = nested(todo);
+          check2(item, { 1: 2, 2: 0 });
+          const id2 = item.filter((f) => f.fieldNumber === 1);
+          if (id2.length !== 1 || id2[0].bytes?.length !== 16) result.complete = false;
+        }
+      } else if (field.fieldNumber === 3) check2(nested(field), { 1: 2, 2: 5, 3: 0 });
+      else if (field.fieldNumber === 10) check2(nested(field), { 1: 5, 2: 5, 3: 5, 4: 5 });
+      else if (field.fieldNumber === 12) {
+        const attachment = nested(field);
+        check2(attachment, { 1: 2, 2: 2 });
+        const ids = attachment.filter((f) => f.fieldNumber === 1), types = attachment.filter((f) => f.fieldNumber === 2);
+        if (ids.length !== 1 || types.length !== 1 || !ids[0].bytes || !types[0].bytes) {
+          result.complete = false;
+          continue;
+        }
+        const utf82 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+        const id2 = utf82.decode(ids[0].bytes), type = utf82.decode(types[0].bytes);
+        if (!id2 || !type) result.complete = false;
+        result.objects.push({ id: id2, type });
+      }
+    }
+  } catch {
+    result.complete = false;
+  }
+  return result;
+}
 function parseRichNote(data, nativeTags = [], options = {}) {
   const doc = decodeMessage(data);
   const wrapper = embeddedMessage(getField(doc, 2));
@@ -40526,9 +40607,8 @@ function parseRichNote(data, nativeTags = [], options = {}) {
       highlight: Boolean(varintValue(getField(fields, 14))),
       start: position,
       length,
-      signature: JSON.stringify(
-        fields.filter((f) => f.fieldNumber >= 2 && f.fieldNumber <= 12 || f.fieldNumber === 14).map((f) => [f.fieldNumber, styleValue(f)])
-      )
+      signature: storedStyleSignature(run.value),
+      nativeSemantics: nativeRunSemantics(run.value)
     });
     if (/[^\s\ufffc]/u.test(text2.slice(position, position + length))) {
       const baseline = varintValue(getField(fields, 8)) ?? 0;
@@ -40596,7 +40676,7 @@ function parseRichNote(data, nativeTags = [], options = {}) {
 function readRichNote(id2, options = {}) {
   const pk = /^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p([0-9]+)$/i.exec(id2)?.[1];
   if (!pk) throw new Error("Invalid exact note ID");
-  const sql = `BEGIN; SELECT hex(ZDATA) FROM ZICNOTEDATA WHERE ZNOTE=${pk}; SELECT json_group_object(ZIDENTIFIER,ZALTTEXT) FROM ZICCLOUDSYNCINGOBJECT WHERE ZNOTE1=${pk} AND ZTYPEUTI1='com.apple.notes.inlinetextattachment.hashtag'; SELECT json_group_array(json_object('id',ZIDENTIFIER,'pk',Z_PK,'type',COALESCE(ZTYPEUTI1,ZTYPEUTI),'mergeable',hex(COALESCE(ZMERGEABLEDATA1,ZMERGEABLEDATA)),'view',ZATTACHMENTVIEWTYPE)) FROM ZICCLOUDSYNCINGOBJECT WHERE ZNOTE1=${pk} OR ZNOTE=${pk}; COMMIT;`;
+  const sql = `BEGIN; SELECT hex(ZDATA) FROM ZICNOTEDATA WHERE ZNOTE=${pk}; SELECT json_group_object(ZIDENTIFIER,ZALTTEXT) FROM ZICCLOUDSYNCINGOBJECT WHERE ZNOTE1=${pk} AND ZTYPEUTI1='com.apple.notes.inlinetextattachment.hashtag'; SELECT json_group_array(json_object('id',ZIDENTIFIER,'pk',Z_PK,'type',COALESCE(ZTYPEUTI1,ZTYPEUTI),'mergeable',hex(COALESCE(ZMERGEABLEDATA1,ZMERGEABLEDATA)),'view',ZATTACHMENTVIEWTYPE,'altText',ZALTTEXT)) FROM ZICCLOUDSYNCINGOBJECT WHERE ZNOTE1=${pk} OR ZNOTE=${pk}; COMMIT;`;
   const rows = execFileSync4("/usr/bin/sqlite3", ["-readonly", dbPath, sql], {
     encoding: "utf8",
     timeout: 5e3,
@@ -40615,14 +40695,21 @@ function readRichNote(id2, options = {}) {
   const tagMap = tags;
   const objectData = JSON.parse(rows[2] || "[]");
   if (!Array.isArray(objectData) || objectData.some(
-    (row) => !row || typeof row.id !== "string" || !Number.isInteger(row.pk) || typeof row.mergeable !== "string" || !/^[0-9a-f]*$/i.test(row.mergeable)
+    (row) => !row || typeof row.id !== "string" || !Number.isInteger(row.pk) || typeof row.mergeable !== "string" || !/^[0-9a-f]*$/i.test(row.mergeable) || row.altText !== void 0 && row.altText !== null && typeof row.altText !== "string"
   ))
     throw new Error("Invalid native object metadata");
   rich.objectData = uniqueById(
     objectData.filter((row) => rich.nativeObjectIds.includes(row.id)).sort((a, b) => a.id.localeCompare(b.id))
   );
-  rich.revision = createHash("sha256").update(rich.revision).update(JSON.stringify(rich.objectData)).digest("hex");
-  rich.nativeTagObjectIds = {};
+  const selectedRows = new Map(rich.objectData.map((row) => [row.id, row]));
+  rich.nativeObjectDataComplete = objectData.every((candidate) => {
+    const row = selectedRows.get(candidate.id);
+    return !row || ["pk", "type", "mergeable", "view", "altText"].every(
+      (key) => candidate[key] === row[key]
+    );
+  });
+  rich.revision = createHash("sha256").update(rich.revision).update(JSON.stringify(rich.objectData)).update(JSON.stringify(rich.nativeObjectDataComplete)).digest("hex");
+  rich.nativeTagObjectIds = /* @__PURE__ */ Object.create(null);
   for (const id3 of rich.nativeObjectIds)
     if (tagMap[id3]) {
       const tag = tagMap[id3].replace(/^#/, "");
@@ -48649,6 +48736,176 @@ function normalizeNativeTags(tags) {
     )
   ];
 }
+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 { objects, objectData, checklistItems, styleRuns, nativeTagObjectIds } = rich;
+  if (!objects || !objectData || !checklistItems || !styleRuns || !nativeTagObjectIds || rich.nativeObjectDataComplete !== true)
+    return unavailable();
+  const ids = new Set(rich.nativeObjectIds);
+  if (ids.size !== rich.nativeObjectIds.length || objects.length !== ids.size || objectData.length !== ids.size || new Set(objects.map((o) => o.id)).size !== ids.size || new Set(objectData.map((o) => o.id)).size !== ids.size || rich.hasNativeObjects !== Boolean(ids.size) || rich.hasChecklist !== Boolean(checklistItems.length))
+    return unavailable();
+  let objectEnd = 0;
+  for (const object3 of objects) {
+    const data = objectData.find((row) => row.id === object3.id);
+    if (!ids.has(object3.id) || !Number.isInteger(object3.start) || !Number.isInteger(object3.length) || object3.start < objectEnd || object3.length < 1 || object3.start + object3.length > rich.text.length || !data || data.type !== object3.type || !Number.isInteger(data.pk) || !/^[0-9a-f]*$/iu.test(data.mergeable) || data.view !== null && !Number.isInteger(data.view) || !Object.hasOwn(data, "altText") || data.altText !== null && typeof data.altText !== "string")
+      return unavailable();
+    objectEnd = object3.start + object3.length;
+  }
+  const mappedIds = /* @__PURE__ */ new Set();
+  if (new Set(rich.nativeTags).size !== rich.nativeTags.length || Object.keys(nativeTagObjectIds).length !== rich.nativeTags.length)
+    return unavailable();
+  for (const [tag, tagIds] of Object.entries(nativeTagObjectIds)) {
+    if (!rich.nativeTags.includes(tag) || !tagIds.length) return unavailable();
+    for (const id2 of tagIds) {
+      if (mappedIds.has(id2) || !objects.some((o) => o.id === id2 && o.type === TAG_OBJECT_TYPE) || objectData.find((o) => o.id === id2)?.altText?.replace(/^#/, "") !== tag)
+        return unavailable();
+      mappedIds.add(id2);
+    }
+  }
+  if (objects.some((o) => o.type === TAG_OBJECT_TYPE && !mappedIds.has(o.id))) return unavailable();
+  if (new Set(checklistItems.map((item) => item.id)).size !== checklistItems.length)
+    return unavailable();
+  for (const item of checklistItems) {
+    const end = item.start + item.text.length;
+    if (!item.id || !Number.isInteger(item.start) || item.start < 0 || end > rich.text.length || rich.text.slice(item.start, end) !== item.text || end < rich.text.length && rich.text[end] !== "\n")
+      return unavailable();
+  }
+  let position = 0;
+  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();
+    position += run.length;
+  }
+  if (position !== rich.text.length) return 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 plainNativeRange(rich, start, length) {
+  return rich.styleRuns.every((run) => {
+    if (run.start >= start + length || run.start + run.length <= start) return true;
+    const metadata = run.nativeSemantics;
+    return metadata.complete && !metadata.unknown && !metadata.structuredParagraph && !metadata.links && !metadata.objects.length;
+  });
+}
+function preservedTextSpans(before, after, missing) {
+  const oldIds = new Set(before.nativeObjectIds);
+  const added = after.objects.filter((o) => !oldIds.has(o.id));
+  const tagsById = new Map(
+    Object.entries(after.nativeTagObjectIds).flatMap(
+      ([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)))
+    return void 0;
+  const spans = [];
+  let oldPosition = 0, newPosition = 0, appended = false;
+  for (const object3 of added) {
+    const prefix = after.text.slice(newPosition, object3.start);
+    const remaining2 = before.text.slice(oldPosition);
+    const length = Math.min(prefix.length, remaining2.length);
+    if (prefix.slice(0, length) !== remaining2.slice(0, length) || prefix.length > length && !/^[ \n]*$/u.test(prefix.slice(length)))
+      return void 0;
+    if (length) spans.push({ before: oldPosition, after: newPosition, length });
+    oldPosition += length;
+    const literal2 = `#${tagsById.get(object3.id)}`;
+    const rendered = after.text.slice(object3.start, object3.start + object3.length);
+    if (rendered !== "\uFFFC" && rendered !== literal2) return void 0;
+    const previous = [...before.text.slice(Math.max(0, oldPosition - 2), oldPosition)].at(-1) || "";
+    const next = String.fromCodePoint(before.text.codePointAt(oldPosition + literal2.length) ?? 0);
+    if (oldPosition === before.text.length) appended = true;
+    else if (before.text.startsWith(literal2, oldPosition) && !/[\p{L}\p{M}\p{N}_#-]/u.test(previous) && !/[\p{L}\p{M}\p{N}_-]/u.test(next) && plainNativeRange(before, oldPosition, literal2.length))
+      oldPosition += literal2.length;
+    else return void 0;
+    newPosition = object3.start + object3.length;
+  }
+  const remaining = before.text.slice(oldPosition);
+  const suffix = after.text.slice(newPosition);
+  if (suffix !== remaining && !(appended && !remaining && /^[ \n]*$/u.test(suffix)))
+    return void 0;
+  if (remaining.length)
+    spans.push({ before: oldPosition, after: newPosition, length: remaining.length });
+  return spans;
+}
+function preservesAddedSemantics(before, after, spans) {
+  const oldIds = new Set(before.nativeObjectIds);
+  const added = after.objects.filter((o) => !oldIds.has(o.id));
+  const changed = [];
+  let end = 0;
+  for (const span of spans) {
+    if (end < span.after) changed.push({ start: end, end: span.after });
+    end = span.after + span.length;
+  }
+  if (end < after.text.length) changed.push({ start: end, end: after.text.length });
+  for (const run of after.styleRuns) {
+    if (!changed.some((range) => run.start < range.end && run.start + run.length > range.start))
+      continue;
+    const metadata = run.nativeSemantics;
+    if (!metadata.complete || metadata.unknown || metadata.structuredParagraph || metadata.links)
+      return false;
+    const object3 = added.find((o) => run.start === o.start && run.length === o.length);
+    if (object3) {
+      if (metadata.objects.length !== 1 || metadata.objects[0].id !== object3.id || metadata.objects[0].type !== object3.type)
+        return false;
+    } else if (metadata.objects.length || added.some((o) => run.start < o.start + o.length && run.start + run.length > o.start))
+      return false;
+  }
+  return true;
+}
+function preservesNativeContent(before, after, spans) {
+  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;
+  };
+  for (const object3 of before.objects) {
+    const actual = after.objects.find((o) => o.id === object3.id);
+    if (!actual || actual.type !== object3.type || actual.length !== object3.length || actual.start !== rangeStart(object3.start, object3.length))
+      return false;
+  }
+  for (const object3 of before.objectData) {
+    const actual = after.objectData.find((o) => o.id === object3.id);
+    if (!actual || actual.pk !== object3.pk || actual.type !== object3.type || actual.mergeable !== object3.mergeable || actual.view !== object3.view || actual.altText !== object3.altText)
+      return false;
+  }
+  for (const tag of before.nativeTags)
+    if (JSON.stringify(before.nativeTagObjectIds[tag]) !== JSON.stringify(after.nativeTagObjectIds[tag]))
+      return false;
+  if (before.checklistItems.length !== after.checklistItems.length) return false;
+  for (const [index, item] of before.checklistItems.entries()) {
+    const actual = after.checklistItems[index];
+    if (actual.id !== item.id || actual.text !== item.text || actual.done !== item.done || actual.start !== rangeStart(item.start, item.text.length))
+      return false;
+  }
+  if (before.links.length !== after.links.length) return false;
+  for (const [index, link] of before.links.entries()) {
+    const actual = after.links[index];
+    if (actual.text !== link.text || actual.url !== link.url || actual.length !== link.length || actual.start !== rangeStart(link.start, link.length))
+      return false;
+  }
+  let oldIndex = 0, newIndex = 0;
+  for (const span of spans) {
+    let offset = 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)
+        return false;
+      offset += Math.min(
+        span.length - offset,
+        oldRun.start + oldRun.length - oldPosition,
+        newRun.start + newRun.length - newPosition
+      );
+    }
+  }
+  return true;
+}
 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");
@@ -48663,32 +48920,37 @@ function addNativeTags(request, deps) {
   const missing = tags.filter((tag) => !before.rich.nativeTags.includes(tag));
   if (!missing.length)
     return { nativeTags: before.rich.nativeTags, added: [], contentHash: before.contentHash };
+  requirePreservationMetadata(before.rich);
   const candidates = deps.candidates(request.title, request.scopeText);
   if (candidates.length !== 1 || candidates[0] !== request.id)
     throw new Error(
       "Shortcuts selection is ambiguous or points to a different note; nothing was changed"
     );
-  if (deps.read(request.id).contentHash !== request.expectedContentHash)
+  const current = deps.read(request.id);
+  if (current.contentHash !== request.expectedContentHash)
     throw new Error("Note revision changed during preflight; nothing was changed");
+  requirePreservationMetadata(current.rich);
   let transportWarning;
   try {
     deps.run({ title: request.title, scopeText: request.scopeText, tags: missing });
   } catch (error2) {
     transportWarning = error2 instanceof Error ? error2.message : "Shortcuts completion was uncertain";
   }
-  const after = deps.read(request.id);
+  const verificationFailure = (detail) => new CodedError(
+    (transportWarning ? "Shortcuts did not complete cleanly, and exact-ID tags/text/links/native-content readback was not verified." : "Shortcuts ran, but exact-ID tags/text/links/native-content readback was not verified.") + " Read the note before any retry." + (detail ? ` ${detail}` : "") + (transportWarning ? ` ${transportWarning}` : ""),
+    { code: "verification_failed", indeterminate: true }
+  );
+  let after;
+  try {
+    after = deps.read(request.id);
+    requirePreservationMetadata(after.rich);
+  } catch (error2) {
+    throw verificationFailure(error2 instanceof Error ? error2.message : String(error2));
+  }
   const allTags = [.../* @__PURE__ */ new Set([...before.rich.nativeTags, ...tags])];
-  const textWithoutTags = (text2) => {
-    for (const tag of [...allTags].sort((a, b) => b.length - a.length)) {
-      const escaped = tag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      text2 = text2.replace(new RegExp(`#${escaped}(?![\\p{L}\\p{N}_-])`, "gu"), "");
-    }
-    return text2.replace(/[\s\ufffc]/gu, "");
-  };
-  if (after.title !== before.title || allTags.some((tag) => !after.rich.nativeTags.includes(tag)) || textWithoutTags(before.rich.text) !== textWithoutTags(after.rich.text) || linkSignature(before.rich.links) !== linkSignature(after.rich.links) || before.rich.nativeObjectIds.some((id2) => !after.rich.nativeObjectIds.includes(id2)) || before.rich.hasChecklist !== after.rich.hasChecklist) {
-    throw new Error(
-      transportWarning ? `Shortcuts did not complete cleanly, and exact-ID tags/text/links readback was not verified. Read the note before any retry. ${transportWarning}` : "Shortcuts ran, but exact-ID tags/text/links readback was not verified. Read the note before any retry"
-    );
+  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)) {
+    throw verificationFailure();
   }
   return {
     nativeTags: after.rich.nativeTags,
@@ -58520,7 +58782,7 @@ function registerSvgAnalysis(server2) {
 // src/tools/nativeTagsBridge.ts
 var noteId2 = exactIdInput(
   "ICNote",
-  /^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i,
+  /^x-coredata:\/\/[0-9a-fA-F-]+\/ICNote\/p\d+$/i,
   NOTE_ID_MESSAGE
 );
 var revision2 = external_exports.string().regex(/^sha256:[a-f0-9]{64}$/);
@@ -58554,8 +58816,9 @@ function registerNativeTagsBridge(server2, manager) {
     if (!body) throw new Error("Note content is unavailable");
     const enriched = enrichNoteRead(id2, body);
     const rich = readRichNote(id2);
-    if (!enriched.complete || enriched.revision !== rich.revision)
+    if (enriched.revision !== rich.revision)
       throw new Error("Native metadata changed during read; read the note again");
+    restoreNoteLinks(body, rich);
     return {
       contentHash: richContentHash(body, enriched),
       title: note.title,
@@ -60365,7 +60628,8 @@ var TIMEOUT_ENV = "APPLE_NOTES_MCP_PRIVATE_HELPER_TIMEOUT_MS";
 var READ_ONLY_ACTIONS = /* @__PURE__ */ new Set([
   "hello",
   "probe",
-  "read_note_state"
+  "read_note_state",
+  "read_checklist"
 ]);
 var HELPER_BINARY_NAME = "apple-notes-private-helper";
 var HELPER_SOURCE_RELATIVE = "native/private-helper/apple-notes-private-helper.m";
@@ -60481,6 +60745,16 @@ var PrivateHelperError = class extends Error {
   code;
   details;
 };
+function assertPrivateHelperReady(deps = defaultDeps2()) {
+  if (!privateHelperEnabled(deps.env))
+    throw new PrivateHelperError(
+      "disabled",
+      `The private helper is off. Set ${ENABLE_ENV}=1 to opt in.`
+    );
+  const install = inspectInstallation(deps);
+  if (!install.ready)
+    throw new PrivateHelperError(install.reason || "helper_not_installed", install.detail || "");
+}
 var errorSchema2 = external_exports.object({
   status: external_exports.literal("error"),
   code: external_exports.string(),
@@ -60511,7 +60785,7 @@ var probeSchema = external_exports.object({
     noteRows: external_exports.number().int().nullable()
   }).passthrough(),
   syncHostRunning: external_exports.boolean(),
-  features: external_exports.object({ readNoteState: featureSchema }).passthrough()
+  features: external_exports.object({ readNoteState: featureSchema, readChecklist: featureSchema }).passthrough()
 }).passthrough();
 var cloudSyncSchema = external_exports.object({
   available: external_exports.boolean(),
@@ -60535,12 +60809,53 @@ var noteStateSchema = external_exports.object({
   cloudSync: cloudSyncSchema,
   syncHostRunning: external_exports.boolean()
 }).passthrough();
+var checklistItemSchema = external_exports.object({
+  todoIdentifier: external_exports.string().regex(/^[a-f0-9]{32}$/),
+  uuid: external_exports.string().uuid(),
+  index: external_exports.number().int().nonnegative(),
+  done: external_exports.boolean(),
+  text: external_exports.string(),
+  lineStart: external_exports.number().int().nonnegative(),
+  lineLengthUTF16: external_exports.number().int().nonnegative(),
+  styledStart: external_exports.number().int().nonnegative(),
+  styledLengthUTF16: external_exports.number().int().positive(),
+  contiguous: external_exports.boolean(),
+  consistent: external_exports.boolean(),
+  spansLines: external_exports.boolean()
+});
+var checklistStateSchema = external_exports.object({
+  status: external_exports.literal("ok"),
+  identifier: external_exports.string().uuid(),
+  revision: external_exports.string().regex(/^r1:[a-f0-9]{64}$/),
+  items: external_exports.array(checklistItemSchema),
+  total: external_exports.number().int().nonnegative(),
+  checked: external_exports.number().int().nonnegative(),
+  syncHostRunning: external_exports.boolean()
+}).passthrough().superRefine((state, ctx) => {
+  const identities = /* @__PURE__ */ new Set();
+  if (state.total !== state.items.length || state.checked !== state.items.filter((item) => item.done).length)
+    ctx.addIssue({ code: "custom", message: "Checklist totals disagree with items" });
+  state.items.forEach((item, index) => {
+    if (item.index !== index || identities.has(item.todoIdentifier) || item.uuid.replaceAll("-", "").toLowerCase() !== item.todoIdentifier || item.text.length !== item.lineLengthUTF16)
+      ctx.addIssue({
+        code: "custom",
+        path: ["items", index],
+        message: "Invalid checklist identity or line"
+      });
+    identities.add(item.todoIdentifier);
+  });
+});
 function callPrivateHelper(action, fields = {}, deps = defaultDeps2(), options = {}) {
   if (!READ_ONLY_ACTIONS.has(action))
     throw new PrivateHelperError(
       "unknown_action",
       `The private helper is read-only; "${action}" is not a supported action.`
     );
+  if (Object.hasOwn(fields, "action") || Object.hasOwn(fields, "protocol"))
+    throw new PrivateHelperError(
+      "invalid_request",
+      "Request fields cannot override action or protocol"
+    );
   if (!options.allowDisabled && !privateHelperEnabled(deps.env))
     throw new PrivateHelperError(
       "disabled",
@@ -60627,6 +60942,19 @@ function readNoteState(identifier, deps = defaultDeps2()) {
   assertNoteIdentifier(identifier);
   return parseOrThrow(noteStateSchema, callPrivateHelper("read_note_state", { identifier }, deps));
 }
+function readChecklistState(identifier, deps = defaultDeps2()) {
+  assertNoteIdentifier(identifier);
+  const state = parseOrThrow(
+    checklistStateSchema,
+    callPrivateHelper("read_checklist", { identifier }, deps)
+  );
+  if (state.identifier.toLowerCase() !== identifier.toLowerCase())
+    throw new PrivateHelperError(
+      "invalid_response",
+      "The helper returned a different note identifier"
+    );
+  return state;
+}
 function featureFromProbe(feature) {
   if (!feature) return { available: false, reason: "private_api_unavailable", detail: null };
   if (feature.available) return { available: true, reason: null, detail: null };
@@ -60645,7 +60973,7 @@ function privateHelperCapabilities(deps = defaultDeps2()) {
     reason,
     detail
   });
-  const both = (status) => ({ readNoteState: status });
+  const both = (status) => ({ readNoteState: status, readChecklist: status });
   if (installation.reason === "unsupported_platform")
     return {
       enabled,
@@ -60688,7 +61016,10 @@ function privateHelperCapabilities(deps = defaultDeps2()) {
     readOnly: true,
     installation,
     probe,
-    features: { readNoteState: featureFromProbe(probe.features.readNoteState) }
+    features: {
+      readNoteState: featureFromProbe(probe.features.readNoteState),
+      readChecklist: featureFromProbe(probe.features.readChecklist)
+    }
   };
 }
 
@@ -61870,19 +62201,19 @@ function relayBroker(socket, leftover, deps) {
 // src/tools/privateHelperTools.ts
 var coreDataId2 = external_exports.string().regex(/^x-coredata:\/\/[0-9A-F-]+\/ICNote\/p\d+$/i);
 var notesUuid = external_exports.string().regex(UUID_PATTERN);
-function resolveIdentifier(manager, args) {
+function resolveIdentifier(deps, args) {
   if (args.identifier && args.id)
     throw new PrivateHelperError("invalid_request", "Pass identifier or id, not both");
   if (args.identifier) return args.identifier;
   if (!args.id) throw new PrivateHelperError("invalid_request", "identifier or id is required");
-  const link = manager.getNoteLinkById(args.id);
-  const match = link?.match(/identifier=([0-9A-F-]{36})$/i);
-  if (!match)
+  assertPrivateHelperReady(deps);
+  const identifier = lookupStableIdentifiers([args.id], "ICNote").get(args.id)?.identifier;
+  if (!identifier || !UUID_PATTERN.test(identifier))
     throw new PrivateHelperError(
       "not_found",
       "Could not resolve that id to a Notes UUID (needs Full Disk Access); pass identifier instead"
     );
-  return match[1];
+  return identifier;
 }
 function envelopeCode(helperCode, message) {
   switch (helperCode) {
@@ -61928,7 +62259,7 @@ function helperErrorResult(error2) {
     })
   );
 }
-function registerPrivateHelperTools(server2, manager, depsFactory = () => defaultDeps2()) {
+function registerPrivateHelperTools(server2, _manager, depsFactory = () => defaultDeps2()) {
   function tool(name, description, inputSchema, annotations, handler) {
     server2.registerTool(
       name,
@@ -61953,7 +62284,7 @@ function registerPrivateHelperTools(server2, manager, depsFactory = () => defaul
   }
   tool(
     "native-helper-status",
-    "Use when: checking whether the opt-in, read-only native private helper is enabled, built, current, and working on this macOS before calling native-note-state.\nReturns: enabled flag, installation state (path, manifest, stale/modified checks), the live probe (macOS and Notes versions, framework, store access), and per-feature availability with a machine reason.\nDo not use when: checking the Shortcuts bridges (native-tags-status, get-capabilities).\nSafety: read-only. The helper is read-only by design (write support was deliberately deferred by the maintainer); the probe opens the Notes store read-only and only when the helper is enabled and installed.",
+    "Use when: checking whether the opt-in, read-only native private helper is enabled, built, current, and working on this macOS before calling native-note-state or native-checklist-state.\nReturns: enabled flag, installation state (path, manifest, stale/modified checks), the live probe (macOS and Notes versions, framework, store access), and per-feature availability with a machine reason.\nDo not use when: checking the Shortcuts bridges (native-tags-status, get-capabilities).\nSafety: read-only. The helper is read-only by design (write support was deliberately deferred by the maintainer); the probe opens the Notes store read-only and only when the helper is enabled and installed.",
     {},
     { readOnlyHint: true, openWorldHint: false },
     (_args, deps) => {
@@ -61972,7 +62303,17 @@ function registerPrivateHelperTools(server2, manager, depsFactory = () => defaul
       id: coreDataId2.optional().describe("x-coredata note id; resolved to a UUID via the database")
     },
     { readOnlyHint: true, openWorldHint: false },
-    (args, deps) => ({ ...readNoteState(resolveIdentifier(manager, args), deps) })
+    (args, deps) => ({ ...readNoteState(resolveIdentifier(deps, args), deps) })
+  );
+  tool(
+    "native-checklist-state",
+    "Use when: reading a note's exact native checklist todo identifiers and done state, including ambiguous style runs.\nReturns: identifier, revision change token, items in first native-style occurrence order, total, checked, and syncHostRunning. Each item has todoIdentifier (32 lowercase hex digits), uuid, index, text and done; line and styled offsets use UTF-16. contiguous=false means the styled envelope includes gaps, consistent=false means runs disagree on done, and spansLines=true means the identity spans multiple lines.\nDo not use when: reading ordinary checkbox-like text (get-note-content) or changing checklist items. Flags describe native identity ambiguity; text is the first visible styled character's line.\nSafety: read-only; requires APPLE_NOTES_MCP_ENABLE_PRIVATE=1, Full Disk Access, and a current built helper. Locked or unavailable native bodies are refused. The helper has no write action.",
+    {
+      identifier: notesUuid.optional().describe("Notes UUID (the notes://showNote identifier)"),
+      id: coreDataId2.optional().describe("x-coredata note id; resolved to a UUID via the database")
+    },
+    { readOnlyHint: true, openWorldHint: false },
+    (args, deps) => ({ ...readChecklistState(resolveIdentifier(deps, args), deps) })
   );
 }
 

package/docs/FULL-DISK-ACCESS.md

@@ -23,7 +23,7 @@ These groups use protected Notes data:
 | Portable exports | `export-notes-markdown`, `export-notes-html`, and attachment/media exports that read the Notes store |
 | Attachments and drawings | `list-attachments` with `includePaths` or `firstImage`, `export-attachments`, `list-paper-attachments`, `export-paper-image`, `get-note-drawings`, and `transcribe-note-audio` |
 | Guarded operations and identifiers | `delete-folder-by-id`; database-backed copy/active-note deletion guards; UUID or numeric note/folder selectors; native preservation/readback and Smart Folder destination detection |
-| Optional private helper | `native-note-state`; the helper is read-only and requires its separate opt-in and build |
+| Optional private helper | `native-note-state`, `native-checklist-state`; the helper is read-only and requires its separate opt-in and build |
 
 `get-note-link` needs FDA on macOS 26 and later. On macOS 12–15 it can fall back to Notes' AppleScript link property. `get-note-markdown` can still return Markdown without FDA, but native checklist done/undone annotations are unavailable.
 

package/native/private-helper/apple-notes-private-helper.m

@@ -134,6 +134,14 @@ static const APIRequirement kReadAPI[] = {
     {"ICTTMergeableString", "attributedString", NO},
 };
 
+// Checklist inspection needs only getters; no editing or todo constructors.
+static const APIRequirement kChecklistReadAPI[] = {
+    {"ICTTParagraphStyle", "style", NO},
+    {"ICTTParagraphStyle", "todo", NO},
+    {"ICTTTodo", "uuid", NO},
+    {"ICTTTodo", "done", NO},
+};
+
 // Core Data properties are @dynamic: their accessors do not exist until Core
 // Data generates them, so they are checked against the managed object model
 // (entity name, then property names) rather than with respondsToSelector:.
@@ -207,7 +215,7 @@ static NSArray<NSString *> *MissingModelProperties(void) {
   return missing;
 }
 
-typedef NS_ENUM(NSInteger, Feature) { FeatureModel, FeatureRead };
+typedef NS_ENUM(NSInteger, Feature) { FeatureModel, FeatureRead, FeatureChecklistRead };
 
 static NSArray<NSString *> *MissingForFeature(Feature feature) {
   LoadFramework();
@@ -219,6 +227,8 @@ static NSArray<NSString *> *MissingForFeature(Feature feature) {
     [missing addObjectsFromArray:MissingModelProperties()];
     [missing addObjectsFromArray:MissingAPI(kReadAPI, COUNT(kReadAPI))];
   }
+  if (feature == FeatureChecklistRead)
+    [missing addObjectsFromArray:MissingAPI(kChecklistReadAPI, COUNT(kChecklistReadAPI))];
   return missing;
 }
 
@@ -401,6 +411,97 @@ static NSString *BodyText(id mergeableString) {
   return [attributed isKindOfClass:[NSAttributedString class]] ? [attributed string] : nil;
 }
 
+// TTStyle runs can include the previous line's terminator. Group by native
+// todo identity, not by a visible line or a checkbox-like text prefix.
+// This operates only on an attributed-string snapshot, never the store.
+static NSArray<NSDictionary *> *ChecklistItems(NSAttributedString *body) {
+  NSString *text = body.string;
+  NSCharacterSet *newlines = NSCharacterSet.newlineCharacterSet;
+  NSMutableArray<NSString *> *order = [NSMutableArray array];
+  NSMutableDictionary<NSString *, NSMutableDictionary *> *groups = [NSMutableDictionary dictionary];
+  [body enumerateAttribute:@"TTStyle"
+                   inRange:NSMakeRange(0, body.length)
+                   options:0
+                usingBlock:^(id style, NSRange run, BOOL *stop) {
+                  (void)stop;
+                  if (!style) return;
+                  if (![style respondsToSelector:sel_registerName("style")])
+                    Fail(@"private_api_unavailable", @"A native paragraph style has no style getter", nil);
+                  unsigned int kind =
+                      ((unsigned int (*)(id, SEL))objc_msgSend)(style, sel_registerName("style"));
+                  if (kind != 103) return; // Notes' native checklist paragraph style.
+                  if (![style respondsToSelector:sel_registerName("todo")])
+                    Fail(@"private_api_unavailable", @"A native checklist style has no todo getter", nil);
+                  id todo = Send(style, "todo");
+                  if (!todo || ![todo respondsToSelector:sel_registerName("uuid")] ||
+                      ![todo respondsToSelector:sel_registerName("done")])
+                    Fail(@"private_api_unavailable", @"A native checklist todo cannot be read", nil);
+                  id uuid = Send(todo, "uuid");
+                  if (![uuid isKindOfClass:[NSUUID class]])
+                    Fail(@"unsupported_note", @"A native checklist todo has no valid UUID", nil);
+                  NSString *hex = [[[uuid UUIDString] stringByReplacingOccurrencesOfString:@"-"
+                                                                                withString:@""] lowercaseString];
+                  NSMutableDictionary *group = groups[hex];
+                  if (!group) {
+                    group = [@{@"uuid" : [uuid UUIDString],
+                               @"ranges" : [NSMutableArray array],
+                               @"states" : [NSMutableSet set]} mutableCopy];
+                    groups[hex] = group;
+                    [order addObject:hex];
+                  }
+                  NSNumber *done = @(SendBool(todo, "done"));
+                  [group[@"ranges"] addObject:[NSValue valueWithRange:run]];
+                  [group[@"states"] addObject:done];
+                  if (!group[@"fallbackDone"]) group[@"fallbackDone"] = done;
+                  // Prefer the first styled visible character over a leading
+                  // newline, whose done bit can differ in malformed content.
+                  for (NSUInteger i = run.location; i < NSMaxRange(run); i++) {
+                    if (![newlines characterIsMember:[text characterAtIndex:i]]) {
+                      if (!group[@"anchor"]) {
+                        group[@"anchor"] = @(i);
+                        group[@"done"] = done;
+                      }
+                      break;
+                    }
+                  }
+                }];
+  NSMutableArray *items = [NSMutableArray array];
+  for (NSString *hex in order) {
+    NSDictionary *group = groups[hex];
+    NSArray<NSValue *> *ranges = group[@"ranges"];
+    NSRange first = ranges.firstObject.rangeValue, last = ranges.lastObject.rangeValue;
+    NSUInteger start = first.location, end = NSMaxRange(last), covered = 0;
+    for (NSValue *range in ranges) covered += range.rangeValue.length;
+    NSUInteger anchor = group[@"anchor"] ? [group[@"anchor"] unsignedIntegerValue] : start;
+    NSUInteger lineStart = 0, lineEnd = 0;
+    [text getLineStart:&lineStart end:NULL contentsEnd:&lineEnd forRange:NSMakeRange(anchor, 0)];
+    NSUInteger visibleStart = start, visibleEnd = end;
+    while (visibleStart < visibleEnd && [newlines characterIsMember:[text characterAtIndex:visibleStart]])
+      visibleStart++;
+    while (visibleEnd > visibleStart && [newlines characterIsMember:[text characterAtIndex:visibleEnd - 1]])
+      visibleEnd--;
+    BOOL spansLines = [text rangeOfCharacterFromSet:newlines
+                                           options:0
+                                             range:NSMakeRange(visibleStart, visibleEnd - visibleStart)].location != NSNotFound;
+    [items addObject:@{
+      @"todoIdentifier" : hex,
+      @"uuid" : group[@"uuid"],
+      @"index" : @(items.count),
+      @"done" : group[@"done"] ?: group[@"fallbackDone"],
+      @"text" : [text substringWithRange:NSMakeRange(lineStart, lineEnd - lineStart)],
+      @"lineStart" : @(lineStart),
+      @"lineLengthUTF16" : @(lineEnd - lineStart),
+      // The envelope includes gaps when contiguous is false.
+      @"styledStart" : @(start),
+      @"styledLengthUTF16" : @(end - start),
+      @"contiguous" : @((BOOL)(covered == end - start)),
+      @"consistent" : @((BOOL)([group[@"states"] count] == 1)),
+      @"spansLines" : @(spansLines),
+    }];
+  }
+  return items;
+}
+
 static BOOL NotesAppRunning(void) {
   return [NSRunningApplication runningApplicationsWithBundleIdentifier:@"com.apple.Notes"].count > 0;
 }
@@ -472,6 +573,7 @@ static NSString *RequireIdentifier(NSDictionary *request) {
 static NSDictionary *HandleHello(NSDictionary *request);
 static NSDictionary *HandleProbe(NSDictionary *request);
 static NSDictionary *HandleReadNoteState(NSDictionary *request);
+static NSDictionary *HandleReadChecklist(NSDictionary *request);
 
 typedef struct {
   const char *name;
@@ -485,6 +587,7 @@ static const ActionSpec kActions[] = {
     {"hello", "", HandleHello},
     {"probe", "", HandleProbe},
     {"read_note_state", "identifier", HandleReadNoteState},
+    {"read_checklist", "identifier", HandleReadChecklist},
 };
 
 static NSArray<NSString *> *ActionNames(void) {
@@ -562,6 +665,7 @@ static NSDictionary *HandleProbe(NSDictionary *request) {
     @"syncHostRunning" : @(NotesAppRunning()),
     @"features" : @{
       @"readNoteState" : FeatureReport(FeatureRead, contextOK, contextReason),
+      @"readChecklist" : FeatureReport(FeatureChecklistRead, contextOK, contextReason),
     },
   };
 }
@@ -577,6 +681,33 @@ static NSDictionary *HandleReadNoteState(NSDictionary *request) {
   return result;
 }
 
+static NSDictionary *HandleReadChecklist(NSDictionary *request) {
+  NSString *identifier = RequireIdentifier(request);
+  RequireFeature(FeatureChecklistRead);
+  NSManagedObjectContext *context = OpenReadOnlyContext(ResolveStore());
+  NSManagedObject *note = FetchNote(context, identifier);
+  if (SendBool(note, "isPasswordProtected"))
+    Fail(@"unsupported_note", @"Locked notes are not supported", nil);
+  id mergeable = Send(note, "mergeableString");
+  if (!mergeable || ![mergeable respondsToSelector:sel_registerName("attributedString")])
+    Fail(@"unsupported_note", @"The note's native body is unavailable", nil);
+  id body = Send(mergeable, "attributedString");
+  if (![body isKindOfClass:[NSAttributedString class]])
+    Fail(@"unsupported_note", @"The note's native body is unavailable", nil);
+  NSArray<NSDictionary *> *items = ChecklistItems(body);
+  NSUInteger checked = 0;
+  for (NSDictionary *item in items) if ([item[@"done"] boolValue]) checked++;
+  return @{
+    @"status" : @"ok",
+    @"identifier" : identifier,
+    @"revision" : RevisionToken(note),
+    @"items" : items,
+    @"total" : @(items.count),
+    @"checked" : @(checked),
+    @"syncHostRunning" : @(NotesAppRunning()),
+  };
+}
+
 #pragma mark - Main
 
 static NSData *ReadStdin(void) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.15.2",
+  "version": "2.15.4",
   "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",