apple-notes-mcp 2.15.2 → 2.15.3

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

@@ -60365,7 +60365,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 +60482,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 +60522,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 +60546,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 +60679,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 +60710,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 +60753,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 +61938,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 +61996,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 +62021,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 +62040,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.3",
   "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",