apple-notes-mcp 2.15.4 → 2.15.6

package/README.md

@@ -761,7 +761,7 @@ Disk Access.
 
 #### `get-note-tables`
 
-Reads every native table in one exact note, in body order, from the NoteStore
+Reads a page of native tables in one exact note, in body order, from the NoteStore
 database. Each table is returned as GitHub-flavored Markdown and as JSON `rows`
 with stable `rowIds` and `columnIds`. Notes tables have no header row, so the
 Markdown uses the first row as the header. Pipes are escaped as `\|`,
@@ -770,8 +770,26 @@ backslashes are doubled, and line breaks inside a cell become `<br>`.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Exact note ID (`x-coredata://…/ICNote/pNNN`) |
-
-`tableCellsComplete` is false when any table or cell could not be decoded. A
+| `offset` | integer | No | Zero-based position of the first table (default 0); use `page.nextOffset` |
+| `limit` | integer | No | Maximum tables per page (default and maximum 500) |
+| `maxBytes` | integer | No | Full serialized response budget in UTF-8 bytes (default 4 MiB, minimum 1024 bytes, maximum 8 MiB) |
+
+The byte budget includes both the text response and structured data, including
+repeated Markdown and JSON escaping. Tables are returned whole. `tableCount`
+and `page.totalAvailable` count all tables in the note; `page.returned` counts
+the entries in this response. While `page.hasMore` is true, call again with
+`offset: page.nextOffset` and the same `limit` and `maxBytes`. Each call reads
+the note again, so finish paging before editing it.
+
+If one table exceeds an otherwise empty page, its entry contains identifying
+metadata, `complete: false`, `contentOmitted: true`, and a `reason`, without
+partial rows or row/column IDs. The next offset advances past that entry. To
+retrieve its content, retry that offset with a larger `maxBytes`, or export the
+note to a file. If even the metadata exceeds the budget, the tool returns a
+validation error. `page.stoppedAtSizeLimit` reports a byte-budget stop.
+
+`tableCellsComplete` is false when any table or cell could not be decoded, or
+when the current page omits a table's content for its byte budget. A
 cell holding an embedded object is `null` in `rows`, listed in
 `incompleteCells`, and shown as `[undecoded cell]` in Markdown. A table whose
 data cannot be decoded at all has `complete: false`, a `reason`, and no rows.

package/build/index.js

@@ -27885,8 +27885,8 @@ var ZodSet = class _ZodSet extends ZodType {
       maxSize: { value: maxSize, message: errorUtil.toString(message) }
     });
   }
-  size(size, message) {
-    return this.min(size, message).max(size, message);
+  size(size2, message) {
+    return this.min(size2, message).max(size2, message);
   }
   nonempty(message) {
     return this.min(1, message);
@@ -36551,7 +36551,7 @@ var Protocol = class {
       if (abortController.signal.aborted) {
         return;
       }
-      const response = {
+      const response2 = {
         result,
         jsonrpc: "2.0",
         id: request.id
@@ -36559,11 +36559,11 @@ var Protocol = class {
       if (relatedTaskId && this._taskMessageQueue) {
         await this._enqueueTaskMessage(relatedTaskId, {
           type: "response",
-          message: response,
+          message: response2,
           timestamp: Date.now()
         }, capturedTransport?.sessionId);
       } else {
-        await capturedTransport?.send(response);
+        await capturedTransport?.send(response2);
       }
     }, async (error2) => {
       if (abortController.signal.aborted) {
@@ -36616,29 +36616,29 @@ var Protocol = class {
     }
     handler(params);
   }
-  _onresponse(response) {
-    const messageId = Number(response.id);
+  _onresponse(response2) {
+    const messageId = Number(response2.id);
     const resolver = this._requestResolvers.get(messageId);
     if (resolver) {
       this._requestResolvers.delete(messageId);
-      if (isJSONRPCResultResponse(response)) {
-        resolver(response);
+      if (isJSONRPCResultResponse(response2)) {
+        resolver(response2);
       } else {
-        const error2 = new McpError(response.error.code, response.error.message, response.error.data);
+        const error2 = new McpError(response2.error.code, response2.error.message, response2.error.data);
         resolver(error2);
       }
       return;
     }
     const handler = this._responseHandlers.get(messageId);
     if (handler === void 0) {
-      this._onerror(new Error(`Received a response for an unknown message ID: ${JSON.stringify(response)}`));
+      this._onerror(new Error(`Received a response for an unknown message ID: ${JSON.stringify(response2)}`));
       return;
     }
     this._responseHandlers.delete(messageId);
     this._cleanupTimeout(messageId);
     let isTaskResponse = false;
-    if (isJSONRPCResultResponse(response) && response.result && typeof response.result === "object") {
-      const result = response.result;
+    if (isJSONRPCResultResponse(response2) && response2.result && typeof response2.result === "object") {
+      const result = response2.result;
       if (result.task && typeof result.task === "object") {
         const task = result.task;
         if (typeof task.taskId === "string") {
@@ -36650,10 +36650,10 @@ var Protocol = class {
     if (!isTaskResponse) {
       this._progressHandlers.delete(messageId);
     }
-    if (isJSONRPCResultResponse(response)) {
-      handler(response);
+    if (isJSONRPCResultResponse(response2)) {
+      handler(response2);
     } else {
-      const error2 = McpError.fromError(response.error.code, response.error.message, response.error.data);
+      const error2 = McpError.fromError(response2.error.code, response2.error.message, response2.error.data);
       handler(error2);
     }
   }
@@ -36825,15 +36825,15 @@ var Protocol = class {
         const error2 = reason instanceof McpError ? reason : new McpError(ErrorCode.RequestTimeout, String(reason));
         reject(error2);
       };
-      this._responseHandlers.set(messageId, (response) => {
+      this._responseHandlers.set(messageId, (response2) => {
         if (options?.signal?.aborted) {
           return;
         }
-        if (response instanceof Error) {
-          return reject(response);
+        if (response2 instanceof Error) {
+          return reject(response2);
         }
         try {
-          const parseResult = safeParse2(resultSchema, response.result);
+          const parseResult = safeParse2(resultSchema, response2.result);
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
@@ -36851,10 +36851,10 @@ var Protocol = class {
       this._setupTimeout(messageId, timeout, options?.maxTotalTimeout, timeoutHandler, options?.resetTimeoutOnProgress ?? false);
       const relatedTaskId = relatedTask?.taskId;
       if (relatedTaskId) {
-        const responseResolver = (response) => {
+        const responseResolver = (response2) => {
           const handler = this._responseHandlers.get(messageId);
           if (handler) {
-            handler(response);
+            handler(response2);
           } else {
             this._onerror(new Error(`Response handler missing for side-channeled request ${messageId}`));
           }
@@ -41977,10 +41977,10 @@ function readFileBase64(p) {
   return readFileSync(p).toString("base64");
 }
 function readFileBase64Capped(p, maxBytes = maxAttachmentBytes()) {
-  const size = fileSize(p);
-  if (size > maxBytes) {
+  const size2 = fileSize(p);
+  if (size2 > maxBytes) {
     throw new Error(
-      `Attachment is ${size} bytes, exceeding the ${maxBytes}-byte fetch limit (APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES). Use save-attachment to export it to disk instead.`
+      `Attachment is ${size2} bytes, exceeding the ${maxBytes}-byte fetch limit (APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES). Use save-attachment to export it to disk instead.`
     );
   }
   return readFileBase64(p);
@@ -47039,11 +47039,11 @@ function decodeInline(fields) {
   }
   if (font) {
     const name = stringOf(font, 1);
-    const size = fixed32Float(first(font, 2));
-    if (name || size !== void 0)
+    const size2 = fixed32Float(first(font, 2));
+    if (name || size2 !== void 0)
       inline.font = {
         ...name ? { name } : {},
-        ...size !== void 0 && Number.isFinite(size) ? { size } : {}
+        ...size2 !== void 0 && Number.isFinite(size2) ? { size: size2 } : {}
       };
   }
   const attachment = sub3(fields, 12);
@@ -47236,8 +47236,8 @@ function pageNoteBlocks(doc, { offset = 0, limit = 500, maxBytes = blocksMaxResp
   let bytes = 0;
   for (let i = start; i < total && blocks.length < limit; i++) {
     let block = doc.blocks[i];
-    let size = Buffer.byteLength(JSON.stringify(block));
-    if (bytes + size > maxBytes) {
+    let size2 = Buffer.byteLength(JSON.stringify(block));
+    if (bytes + size2 > maxBytes) {
       if (blocks.length) break;
       block = {
         ...block,
@@ -47245,10 +47245,10 @@ function pageNoteBlocks(doc, { offset = 0, limit = 500, maxBytes = blocksMaxResp
         textOmitted: true,
         runs: block.runs.map((run) => ({ ...run, text: "" }))
       };
-      size = Buffer.byteLength(JSON.stringify(block));
+      size2 = Buffer.byteLength(JSON.stringify(block));
     }
     blocks.push(block);
-    bytes += size;
+    bytes += size2;
   }
   const next = start + blocks.length;
   return {
@@ -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(
@@ -49918,7 +50065,7 @@ async function callPublicHelperAsync(action, fields = {}, deps = defaultPublicHe
       stdio: ["pipe", "pipe", "ignore"]
     });
     const chunks = [];
-    let size = 0;
+    let size2 = 0;
     let failure2 = null;
     const stop = (error2) => {
       failure2 ??= error2;
@@ -49935,8 +50082,8 @@ async function callPublicHelperAsync(action, fields = {}, deps = defaultPublicHe
       signal?.removeEventListener("abort", onAbort);
     };
     child2.stdout?.on("data", (chunk) => {
-      size += chunk.length;
-      if (size > MAX_OUTPUT_BYTES2)
+      size2 += chunk.length;
+      if (size2 > MAX_OUTPUT_BYTES2)
         stop(new PublicHelperError("invalid_response", "The helper response is too large."));
       else chunks.push(chunk);
     });
@@ -51034,6 +51181,199 @@ function createShutdown(stream, exit, timeoutMs = SHUTDOWN_DRAIN_TIMEOUT_MS, pen
   };
 }
 
+// src/utils/structuredText.ts
+import { isDeepStrictEqual } from "node:util";
+var STRUCTURED_TEXT_PREFIX = "structuredContent: ";
+var SHOWN_ABOVE = "[shown in full above]";
+var MIN_ELIDED_CHARS = 64;
+var MAX_MIRROR_CHARS = 16384;
+var MAX_FIELD_CHARS = 1024;
+function textOf(content) {
+  return content.map(
+    (item) => item && typeof item === "object" && item.type === "text" ? String(item.text ?? "") : ""
+  ).join("\n");
+}
+function elide(value, text2) {
+  if (typeof value === "string") {
+    return value.length >= MIN_ELIDED_CHARS && text2.includes(value) ? SHOWN_ABOVE : value;
+  }
+  if (Array.isArray(value)) return value.map((item) => elide(item, text2));
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (item !== void 0) out[key] = elide(item, text2);
+    }
+    return out;
+  }
+  return value;
+}
+function textIsTheJson(content, structured) {
+  const plain = JSON.parse(JSON.stringify(structured));
+  return content.some((item) => {
+    const text2 = item?.text;
+    if (item?.type !== "text" || typeof text2 !== "string") return false;
+    const trimmed = text2.trim();
+    if (!trimmed.startsWith("{")) return false;
+    try {
+      return isDeepStrictEqual(JSON.parse(trimmed), plain);
+    } catch {
+      return false;
+    }
+  });
+}
+function structuredTextLine(structured, text2) {
+  const elided = elide(structured, text2);
+  let json2 = JSON.stringify(elided);
+  if (json2.length > MAX_MIRROR_CHARS) {
+    const kept = {};
+    const omitted = [];
+    for (const [key, value] of Object.entries(elided)) {
+      if (JSON.stringify(value).length > MAX_FIELD_CHARS) omitted.push(key);
+      else kept[key] = value;
+    }
+    json2 = JSON.stringify({ ...kept, _omitted: omitted });
+  }
+  return STRUCTURED_TEXT_PREFIX + json2;
+}
+function withStructuredText(result) {
+  const r = result;
+  if (!r || typeof r !== "object") return result;
+  const structured = r.structuredContent;
+  if (!structured || typeof structured !== "object" || Array.isArray(structured)) return result;
+  const content = Array.isArray(r.content) ? r.content : [];
+  if (textIsTheJson(content, structured)) return result;
+  const line = structuredTextLine(structured, textOf(content));
+  return { ...r, content: [...content, { type: "text", text: line }] };
+}
+function installStructuredText(server2) {
+  const target = server2;
+  const register = target.registerTool;
+  if (typeof register === "function") {
+    target.registerTool = function(name, config2, cb) {
+      const wrapped = typeof cb === "function" ? async (...args) => withStructuredText(await cb(...args)) : cb;
+      return register.call(this, name, config2, wrapped);
+    };
+  }
+  const createError = target.createToolError;
+  if (typeof createError === "function") {
+    target.createToolError = (message) => withStructuredText(createError.call(target, message));
+  }
+}
+
+// src/services/tableResponse.ts
+var DEFAULT_TABLE_RESPONSE_BYTES = 4 * 1024 * 1024;
+var MAX_TABLE_RESPONSE_BYTES = 8 * 1024 * 1024;
+var MAX_TABLES_PER_PAGE = 500;
+var MIN_TABLE_RESPONSE_BYTES = 1024;
+function validateTablePageOptions(options) {
+  const {
+    offset = 0,
+    limit = MAX_TABLES_PER_PAGE,
+    maxBytes = DEFAULT_TABLE_RESPONSE_BYTES
+  } = options;
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > MAX_TABLES_PER_PAGE || !Number.isSafeInteger(maxBytes) || maxBytes < MIN_TABLE_RESPONSE_BYTES || maxBytes > MAX_TABLE_RESPONSE_BYTES) {
+    throw new CodedError("Invalid table page offset, limit or maxBytes.", {
+      code: "validation_error"
+    });
+  }
+  return { offset, limit, maxBytes };
+}
+function response(id2, result, tables, options, stoppedAtSizeLimit) {
+  const tableCount = result.tables.length;
+  const next = options.offset + tables.length;
+  const hasMore = next < tableCount;
+  const complete = result.tableCellsComplete && tables.every((table) => table.complete);
+  const markdown = tables.map(
+    (table) => table.markdown ?? `[table ${table.index} could not be ${table.contentOmitted ? "returned" : "decoded"}: ${table.reason}]`
+  ).join("\n\n");
+  let summary = tableCount === 0 ? "This note has no native tables." : `${tables.length === tableCount ? tableCount : `${tables.length} of ${tableCount}`} table(s)${complete ? "" : " (some content could not be returned; see tables[].reason)"}:
+
+${markdown}`;
+  if (hasMore)
+    summary += `
+
+More tables remain: call get-note-tables with offset ${next} and the same limit and maxBytes.`;
+  return {
+    content: [{ type: "text", text: summary }],
+    structuredContent: {
+      id: id2,
+      tables,
+      tableCount,
+      tableCellsComplete: complete,
+      markdown,
+      page: {
+        ...options,
+        totalAvailable: tableCount,
+        returned: tables.length,
+        ...hasMore ? { nextOffset: next } : {},
+        hasMore,
+        stoppedAtSizeLimit
+      }
+    }
+  };
+}
+var size = (value) => Buffer.byteLength(JSON.stringify(withStructuredText(value)));
+function tablePageResponse(id2, result, request = {}) {
+  const options = validateTablePageOptions(request);
+  const available = Math.max(0, Math.min(options.limit, result.tables.length - options.offset));
+  const fits = (count) => {
+    const candidate = result.tables.slice(options.offset, options.offset + count);
+    const couldStopLater = count < available;
+    const candidateBytes = Math.max(
+      size(response(id2, result, candidate, options, false)),
+      couldStopLater ? size(response(id2, result, candidate, options, true)) : 0
+    );
+    return candidateBytes <= options.maxBytes;
+  };
+  let accepted = 0;
+  let trial = 1;
+  while (trial <= available) {
+    if (fits(trial)) {
+      accepted = trial;
+      if (trial === available) break;
+      trial = Math.min(available, trial * 2);
+      continue;
+    }
+    let low = accepted + 1;
+    let high = trial - 1;
+    while (low <= high) {
+      const middle = Math.floor((low + high) / 2);
+      if (fits(middle)) {
+        accepted = middle;
+        low = middle + 1;
+      } else {
+        high = middle - 1;
+      }
+    }
+    break;
+  }
+  let tables = result.tables.slice(options.offset, options.offset + accepted);
+  const stoppedAtSizeLimit = accepted < available;
+  if (stoppedAtSizeLimit && accepted === 0) {
+    const table = result.tables[options.offset];
+    tables = [
+      {
+        index: table.index,
+        id: table.id,
+        ...table.attachmentId !== void 0 ? { attachmentId: table.attachmentId } : {},
+        ...table.rowCount !== void 0 ? { rowCount: table.rowCount } : {},
+        ...table.columnCount !== void 0 ? { columnCount: table.columnCount } : {},
+        complete: false,
+        contentOmitted: true,
+        reason: "Table content exceeds this response size limit. Increase maxBytes or export the note to a file."
+      }
+    ];
+  }
+  const output = response(id2, result, tables, options, stoppedAtSizeLimit);
+  if (size(output) > options.maxBytes) {
+    throw new CodedError(
+      "Table metadata is too large for this response limit; increase maxBytes.",
+      { code: "validation_error" }
+    );
+  }
+  return output;
+}
+
 // src/utils/noteParagraphs.ts
 import { gunzipSync as gunzipSync9 } from "node:zlib";
 var ENVELOPE_CODE = {
@@ -51245,10 +51585,10 @@ function pageParagraphs(paragraphs, { offset = 0, limit = 500, maxBytes = 4 * 10
   const out = [];
   let bytes = 0;
   for (let i = start; i < list.length && out.length < limit; i++) {
-    const size = Buffer.byteLength(JSON.stringify(list[i]));
-    if (out.length && bytes + size > maxBytes) break;
+    const size2 = Buffer.byteLength(JSON.stringify(list[i]));
+    if (out.length && bytes + size2 > maxBytes) break;
     out.push(list[i]);
-    bytes += size;
+    bytes += size2;
   }
   const next = start + out.length;
   return {
@@ -51784,10 +52124,10 @@ function listNoteLinks(options = {}) {
   const page = [];
   let bytes = 0;
   for (let i = start; i < links.length && page.length < limit; i++) {
-    const size = Buffer.byteLength(JSON.stringify(links[i]));
-    if (page.length && bytes + size > maxBytes) break;
+    const size2 = Buffer.byteLength(JSON.stringify(links[i]));
+    if (page.length && bytes + size2 > maxBytes) break;
     page.push(links[i]);
-    bytes += size;
+    bytes += size2;
   }
   const next = start + page.length;
   return {
@@ -52398,8 +52738,8 @@ var DataUrlWriter = class {
     if (!this.fits(data.length)) return { error: "too-large" };
     return this.embed(`generated:${key}`, data, mime);
   }
-  fits(size) {
-    return size <= this.maxBytes && this.embeddedBytes + size <= this.totalBytes;
+  fits(size2) {
+    return size2 <= this.maxBytes && this.embeddedBytes + size2 <= this.totalBytes;
   }
   embed(key, data, mime) {
     const result = { url: `data:${mime};base64,${data.toString("base64")}`, mime };
@@ -55160,85 +55500,6 @@ function exportWithTemplate(request, deps, chosen, notes, skipped, { output, ass
   return { ...receipt, markdown };
 }
 
-// src/utils/structuredText.ts
-import { isDeepStrictEqual } from "node:util";
-var STRUCTURED_TEXT_PREFIX = "structuredContent: ";
-var SHOWN_ABOVE = "[shown in full above]";
-var MIN_ELIDED_CHARS = 64;
-var MAX_MIRROR_CHARS = 16384;
-var MAX_FIELD_CHARS = 1024;
-function textOf(content) {
-  return content.map(
-    (item) => item && typeof item === "object" && item.type === "text" ? String(item.text ?? "") : ""
-  ).join("\n");
-}
-function elide(value, text2) {
-  if (typeof value === "string") {
-    return value.length >= MIN_ELIDED_CHARS && text2.includes(value) ? SHOWN_ABOVE : value;
-  }
-  if (Array.isArray(value)) return value.map((item) => elide(item, text2));
-  if (value && typeof value === "object") {
-    const out = {};
-    for (const [key, item] of Object.entries(value)) {
-      if (item !== void 0) out[key] = elide(item, text2);
-    }
-    return out;
-  }
-  return value;
-}
-function textIsTheJson(content, structured) {
-  const plain = JSON.parse(JSON.stringify(structured));
-  return content.some((item) => {
-    const text2 = item?.text;
-    if (item?.type !== "text" || typeof text2 !== "string") return false;
-    const trimmed = text2.trim();
-    if (!trimmed.startsWith("{")) return false;
-    try {
-      return isDeepStrictEqual(JSON.parse(trimmed), plain);
-    } catch {
-      return false;
-    }
-  });
-}
-function structuredTextLine(structured, text2) {
-  const elided = elide(structured, text2);
-  let json2 = JSON.stringify(elided);
-  if (json2.length > MAX_MIRROR_CHARS) {
-    const kept = {};
-    const omitted = [];
-    for (const [key, value] of Object.entries(elided)) {
-      if (JSON.stringify(value).length > MAX_FIELD_CHARS) omitted.push(key);
-      else kept[key] = value;
-    }
-    json2 = JSON.stringify({ ...kept, _omitted: omitted });
-  }
-  return STRUCTURED_TEXT_PREFIX + json2;
-}
-function withStructuredText(result) {
-  const r = result;
-  if (!r || typeof r !== "object") return result;
-  const structured = r.structuredContent;
-  if (!structured || typeof structured !== "object" || Array.isArray(structured)) return result;
-  const content = Array.isArray(r.content) ? r.content : [];
-  if (textIsTheJson(content, structured)) return result;
-  const line = structuredTextLine(structured, textOf(content));
-  return { ...r, content: [...content, { type: "text", text: line }] };
-}
-function installStructuredText(server2) {
-  const target = server2;
-  const register = target.registerTool;
-  if (typeof register === "function") {
-    target.registerTool = function(name, config2, cb) {
-      const wrapped = typeof cb === "function" ? async (...args) => withStructuredText(await cb(...args)) : cb;
-      return register.call(this, name, config2, wrapped);
-    };
-  }
-  const createError = target.createToolError;
-  if (typeof createError === "function") {
-    target.createToolError = (message) => withStructuredText(createError.call(target, message));
-  }
-}
-
 // src/tools/directOperations.ts
 import { createHash as createHash4 } from "node:crypto";
 import {
@@ -55509,30 +55770,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");
@@ -55547,12 +55791,12 @@ function localAttachment(path10) {
   }
 }
 var MAX_ADD_ATTACHMENT_BYTES = 64 * 1024 * 1024;
-function fileMatches(path10, size, expected) {
+function fileMatches(path10, size2, expected) {
   let descriptor;
   try {
     descriptor = openSync7(path10, constants7.O_RDONLY | constants7.O_NOFOLLOW);
     const stat = fstatSync7(descriptor);
-    if (!stat.isFile() || stat.size !== size) return false;
+    if (!stat.isFile() || stat.size !== size2) return false;
     const hash = createHash4("sha256");
     const chunk = Buffer.allocUnsafe(1024 * 1024);
     let total = 0;
@@ -55560,10 +55804,10 @@ function fileMatches(path10, size, expected) {
       const read = readSync5(descriptor, chunk, 0, chunk.length, null);
       if (read === 0) break;
       total += read;
-      if (total > size) return false;
+      if (total > size2) return false;
       hash.update(chunk.subarray(0, read));
     }
-    return total === size && hash.digest("hex") === expected;
+    return total === size2 && hash.digest("hex") === expected;
   } catch {
     return false;
   } finally {
@@ -55909,8 +56153,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 +60249,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 +60273,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(
@@ -62701,10 +62956,10 @@ async function readEditorJson(req) {
   if (!/^application\/json(?:\s*;|$)/i.test(type))
     throw new EditorHttpError(415, "unsupported-media-type", "Send JSON (application/json).");
   const chunks = [];
-  let size = 0;
+  let size2 = 0;
   for await (const chunk of req) {
-    size += chunk.length;
-    if (size > MAX_EDITOR_BODY_BYTES)
+    size2 += chunk.length;
+    if (size2 > MAX_EDITOR_BODY_BYTES)
       throw new EditorHttpError(413, "too-large", "Request body too large.");
     chunks.push(chunk);
   }
@@ -63055,12 +63310,12 @@ var textFingerprint = (normalized2) => createHash8("sha256").update(normalized2,
 function textSimilarity(a, b) {
   if (a === b) return 1;
   if (!a || !b) return 0;
-  const size = Math.min(a.length, b.length) < 3 ? 2 : 3;
+  const size2 = Math.min(a.length, b.length) < 3 ? 2 : 3;
   const grams = (s) => {
     const out = /* @__PURE__ */ new Map();
     const padded = ` ${s} `;
-    for (let i = 0; i + size <= padded.length; i++) {
-      const g = padded.slice(i, i + size);
+    for (let i = 0; i + size2 <= padded.length; i++) {
+      const g = padded.slice(i, i + size2);
       out.set(g, (out.get(g) ?? 0) + 1);
     }
     return out;
@@ -64900,18 +65155,27 @@ registerTool(
 registerTool(
   "get-note-tables",
   {
-    description: "Use when: reading the native tables in one exact note as data or Markdown.\nReturns: every table in body order as GitHub-flavored Markdown (first row as header) plus JSON rows with stable row/column ids, and tableCellsComplete.\nDo not use when: you need the whole note (get-note-markdown / get-note-content) or native object ranges and checklist ids (get-native-objects).\nSafety: read-only; reads the NoteStore database and requires Full Disk Access. A cell that cannot be decoded is null in rows, listed in incompleteCells, and marked [undecoded cell] in Markdown; it is never guessed. Cell text only: links and styling inside cells are not rendered.",
-    inputSchema: { id: noteIdInput },
+    description: "Use when: reading the native tables in one exact note as data or Markdown.\nReturns: one page of whole tables in body order as GitHub-flavored Markdown (first row as header) plus JSON rows with stable row/column ids, tableCellsComplete, and page info. Default limit 500 and maxBytes 4 MiB; while page.hasMore is true, call again with offset set to page.nextOffset. The byte budget includes the full serialized tool response, including repeated Markdown.\nDo not use when: you need the whole note (get-note-markdown / get-note-content) or native object ranges and checklist ids (get-native-objects).\nSafety: read-only; reads the NoteStore database and requires Full Disk Access. A cell that cannot be decoded is null in rows, listed in incompleteCells, and marked [undecoded cell] in Markdown; it is never guessed. A table larger than an empty page returns metadata only with complete: false and contentOmitted: true; increase maxBytes (max 8 MiB) or export the note to a file. Cell text only: links and styling inside cells are not rendered.",
+    inputSchema: {
+      id: noteIdInput,
+      offset: external_exports.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional().describe("Zero-based position of the first table (default 0); use page.nextOffset"),
+      limit: external_exports.number().int().min(1).max(MAX_TABLES_PER_PAGE).optional().describe(`Maximum tables to return (default and max ${MAX_TABLES_PER_PAGE})`),
+      maxBytes: external_exports.number().int().min(MIN_TABLE_RESPONSE_BYTES).max(MAX_TABLE_RESPONSE_BYTES).optional().describe(
+        `Maximum UTF-8 bytes of the serialized tool response (default ${DEFAULT_TABLE_RESPONSE_BYTES}, max ${MAX_TABLE_RESPONSE_BYTES})`
+      )
+    },
     outputSchema: {
       id: external_exports.string().optional(),
       tables: external_exports.array(external_exports.record(external_exports.unknown())).optional(),
       tableCount: external_exports.number().optional(),
       tableCellsComplete: external_exports.boolean().optional(),
-      markdown: external_exports.string().optional()
+      markdown: external_exports.string().optional(),
+      page: external_exports.record(external_exports.unknown()).optional()
     },
     annotations: { readOnlyHint: true }
   },
-  withErrorHandling(({ id: id2 }) => {
+  withErrorHandling(({ id: id2, offset, limit, maxBytes }) => {
+    const options = validateTablePageOptions({ offset, limit, maxBytes });
     const { metadata, message } = getNoteMetadata(id2);
     if (!metadata) return errorResponse(message || `Failed to read note "${id2}"`);
     if (metadata.passwordProtected) {
@@ -64920,17 +65184,7 @@ registerTool(
       );
     }
     const result = notesManager.getNoteTablesById(id2);
-    const count = result.tables.length;
-    const summary = count === 0 ? "This note has no native tables." : `${count} table(s)${result.tableCellsComplete ? "" : " (some content could not be decoded; see tables[].reason)"}:
-
-${result.markdown}`;
-    return successResponse(summary, {
-      id: id2,
-      tables: result.tables,
-      tableCount: count,
-      tableCellsComplete: result.tableCellsComplete,
-      markdown: result.markdown
-    });
+    return tablePageResponse(id2, result, options);
   }, "Error reading note tables")
 );
 registerTool(
@@ -65709,7 +65963,7 @@ registerTool(
         readLinks: (noteId3) => readRichNote(noteId3).links,
         append: (request) => {
           let route = "applescript";
-          const response = guardedAppend(
+          const response2 = guardedAppend(
             {
               ...request,
               format: "html",
@@ -65717,11 +65971,11 @@ registerTool(
             },
             (r) => route = r
           );
-          if (response.isError) {
-            const envelope = response.structuredContent;
-            throw envelope?.code ? new CodedError(response.content[0].text, envelope) : new Error(response.content[0].text);
+          if (response2.isError) {
+            const envelope = response2.structuredContent;
+            throw envelope?.code ? new CodedError(response2.content[0].text, envelope) : new Error(response2.content[0].text);
           }
-          return { route, contentHash: String(response.structuredContent?.contentHash ?? "") };
+          return { route, contentHash: String(response2.structuredContent?.contentHash ?? "") };
         }
       }
     );
@@ -66862,7 +67116,7 @@ registerTool(
         `Too large to return whole, so oversized inline images were replaced (strippedImages) or the body was left out (contentOmitted): ${degraded.map((n) => n.id).join(", ")}. Read these with get-note-content, and their files with list-attachments and save-attachment.`
       );
     }
-    const response = {
+    const response2 = {
       content: [
         {
           type: "text",
@@ -66877,13 +67131,13 @@ Full JSON export:`
       ],
       structuredContent: { ...exportData }
     };
-    const responseBytes = Buffer.byteLength(JSON.stringify(response));
+    const responseBytes = Buffer.byteLength(JSON.stringify(response2));
     if (responseBytes > maxResponseBytes) {
       return errorResponse(
         `Error exporting notes: this page is ${formatMegabytes(responseBytes)}, over the ${formatMegabytes(maxResponseBytes)} response limit, so it was not sent. Call export-notes-json again with offset ${page.offset} and a smaller limit (for example ${Math.max(1, Math.floor(page.returned / 2))}), or raise APPLE_NOTES_MCP_EXPORT_MAX_BYTES if your MCP client accepts larger messages.`
       );
     }
-    return response;
+    return response2;
   }, "Error exporting notes")
 );
 registerTool(

package/package.json

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