apple-notes-mcp 2.8.5 → 2.8.7

package/README.md

@@ -303,6 +303,26 @@ attachment-bearing notes; edit them in Notes.app.
 
 ---
 
+#### `get-native-objects`
+
+Reads native object identities and ranges, checklist item IDs and state, actual
+native tags, and native table data from one exact note ID. Table output includes
+stable row and column identifiers. `tableCellsComplete` is false when Notes
+metadata cannot be decoded completely. This tool is read-only and requires Full
+Disk Access.
+
+---
+
+#### `list-native-tags`
+
+Lists actual native Notes tags used within one explicit `account` and `folder`,
+mapping each tag to its matching note IDs. This differs from textual hashtag
+search. The response reports `complete: false` and per-note errors when some
+native metadata is unavailable. This tool is read-only and requires Full Disk
+Access.
+
+---
+
 #### `get-note-plaintext`
 
 Retrieves a note's body as plain text, with no HTML markup.
@@ -639,6 +659,21 @@ Creates a new folder, including a whole nested hierarchy in one call.
 
 ---
 
+#### `get-folder-by-id`
+
+Reads one exact folder's current name and parent ID. Use these values with
+`rename-folder`; this avoids relying on ambiguous folder names or paths.
+
+---
+
+#### `rename-folder`
+
+Renames an existing folder in place using its exact `id`, `expectedName`,
+`expectedParentId`, and `newName`. The operation preserves the folder ID, notes,
+and descendants. It refuses stale metadata and a conflicting sibling name.
+
+---
+
 #### `delete-folder`
 
 Deletes a folder.
@@ -815,6 +850,15 @@ Reads note metadata that AppleScript cannot expose, by querying the NoteStore SQ
 
 ---
 
+#### `add-attachment`
+
+Adds one nonempty local file of at most 64 MiB to an exact note using `id`, the
+latest `expectedContentHash`, and an absolute `path`. The server never retries
+the insertion. It verifies that existing rich content survived and compares the
+fetched attachment bytes with the source before reporting success.
+
+---
+
 #### `list-attachments`
 
 Lists attachments in a note.

package/build/index.js

@@ -417,11 +417,11 @@ var require_codegen = __commonJS({
         const rhs = this.rhs === void 0 ? "" : ` = ${this.rhs}`;
         return `${varKind} ${this.name}${rhs};` + _n;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         if (!names[this.name.str])
           return;
         if (this.rhs)
-          this.rhs = optimizeExpr(this.rhs, names, constants);
+          this.rhs = optimizeExpr(this.rhs, names, constants2);
         return this;
       }
       get names() {
@@ -438,10 +438,10 @@ var require_codegen = __commonJS({
       render({ _n }) {
         return `${this.lhs} = ${this.rhs};` + _n;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         if (this.lhs instanceof code_1.Name && !names[this.lhs.str] && !this.sideEffects)
           return;
-        this.rhs = optimizeExpr(this.rhs, names, constants);
+        this.rhs = optimizeExpr(this.rhs, names, constants2);
         return this;
       }
       get names() {
@@ -502,8 +502,8 @@ var require_codegen = __commonJS({
       optimizeNodes() {
         return `${this.code}` ? this : void 0;
       }
-      optimizeNames(names, constants) {
-        this.code = optimizeExpr(this.code, names, constants);
+      optimizeNames(names, constants2) {
+        this.code = optimizeExpr(this.code, names, constants2);
         return this;
       }
       get names() {
@@ -532,12 +532,12 @@ var require_codegen = __commonJS({
         }
         return nodes.length > 0 ? this : void 0;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         const { nodes } = this;
         let i = nodes.length;
         while (i--) {
           const n = nodes[i];
-          if (n.optimizeNames(names, constants))
+          if (n.optimizeNames(names, constants2))
             continue;
           subtractNames(names, n.names);
           nodes.splice(i, 1);
@@ -590,12 +590,12 @@ var require_codegen = __commonJS({
           return void 0;
         return this;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         var _a;
-        this.else = (_a = this.else) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants);
-        if (!(super.optimizeNames(names, constants) || this.else))
+        this.else = (_a = this.else) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants2);
+        if (!(super.optimizeNames(names, constants2) || this.else))
           return;
-        this.condition = optimizeExpr(this.condition, names, constants);
+        this.condition = optimizeExpr(this.condition, names, constants2);
         return this;
       }
       get names() {
@@ -618,10 +618,10 @@ var require_codegen = __commonJS({
       render(opts) {
         return `for(${this.iteration})` + super.render(opts);
       }
-      optimizeNames(names, constants) {
-        if (!super.optimizeNames(names, constants))
+      optimizeNames(names, constants2) {
+        if (!super.optimizeNames(names, constants2))
           return;
-        this.iteration = optimizeExpr(this.iteration, names, constants);
+        this.iteration = optimizeExpr(this.iteration, names, constants2);
         return this;
       }
       get names() {
@@ -657,10 +657,10 @@ var require_codegen = __commonJS({
       render(opts) {
         return `for(${this.varKind} ${this.name} ${this.loop} ${this.iterable})` + super.render(opts);
       }
-      optimizeNames(names, constants) {
-        if (!super.optimizeNames(names, constants))
+      optimizeNames(names, constants2) {
+        if (!super.optimizeNames(names, constants2))
           return;
-        this.iterable = optimizeExpr(this.iterable, names, constants);
+        this.iterable = optimizeExpr(this.iterable, names, constants2);
         return this;
       }
       get names() {
@@ -702,11 +702,11 @@ var require_codegen = __commonJS({
         (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNodes();
         return this;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         var _a, _b;
-        super.optimizeNames(names, constants);
-        (_a = this.catch) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants);
-        (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNames(names, constants);
+        super.optimizeNames(names, constants2);
+        (_a = this.catch) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants2);
+        (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNames(names, constants2);
         return this;
       }
       get names() {
@@ -1007,7 +1007,7 @@ var require_codegen = __commonJS({
     function addExprNames(names, from) {
       return from instanceof code_1._CodeOrName ? addNames(names, from.names) : names;
     }
-    function optimizeExpr(expr, names, constants) {
+    function optimizeExpr(expr, names, constants2) {
       if (expr instanceof code_1.Name)
         return replaceName(expr);
       if (!canOptimize(expr))
@@ -1022,14 +1022,14 @@ var require_codegen = __commonJS({
         return items;
       }, []));
       function replaceName(n) {
-        const c = constants[n.str];
+        const c = constants2[n.str];
         if (c === void 0 || names[n.str] !== 1)
           return n;
         delete names[n.str];
         return c;
       }
       function canOptimize(e) {
-        return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants[c.str] !== void 0);
+        return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants2[c.str] !== void 0);
       }
     }
     function subtractNames(names, from) {
@@ -3358,9 +3358,9 @@ var require_utils = __commonJS({
       let output = "";
       for (let i = 0; i < input.length; i++) {
         if (input[i] === "%" && i + 2 < input.length) {
-          const hex = input.slice(i + 1, i + 3);
-          if (isHexPair(hex)) {
-            const normalizedHex = hex.toUpperCase();
+          const hex2 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex2)) {
+            const normalizedHex = hex2.toUpperCase();
             const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
             if (decodeUnreserved && isUnreserved(decoded)) {
               output += decoded;
@@ -3380,9 +3380,9 @@ var require_utils = __commonJS({
       for (let i = 0; i < input.length; i++) {
         const ch = input[i];
         if (ch === "%" && i + 2 < input.length) {
-          const hex = input.slice(i + 1, i + 3);
-          if (isHexPair(hex)) {
-            const normalizedHex = hex.toUpperCase();
+          const hex2 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex2)) {
+            const normalizedHex = hex2.toUpperCase();
             const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
             if (decoded !== "." && isUnreserved(decoded)) {
               output += decoded;
@@ -3422,9 +3422,9 @@ var require_utils = __commonJS({
       for (let i = 0; i < input.length; i++) {
         const ch = input[i];
         if (ch === "%" && i + 2 < input.length) {
-          const hex = input.slice(i + 1, i + 3);
-          if (isHexPair(hex)) {
-            output += "%" + hex.toUpperCase();
+          const hex2 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex2)) {
+            output += "%" + hex2.toUpperCase();
             i += 2;
             continue;
           }
@@ -3460,9 +3460,9 @@ var require_utils = __commonJS({
       for (let i = 0; i < input.length; i++) {
         const ch = input[i];
         if (ch === "%" && i + 2 < input.length) {
-          const hex = input.slice(i + 1, i + 3);
-          if (isHexPair(hex)) {
-            output += "%" + hex.toUpperCase();
+          const hex2 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex2)) {
+            output += "%" + hex2.toUpperCase();
             i += 2;
             continue;
           }
@@ -3507,9 +3507,9 @@ var require_utils = __commonJS({
       for (let i = 0; i < input.length; i++) {
         const ch = input[i];
         if (ch === "%" && i + 2 < input.length) {
-          const hex = input.slice(i + 1, i + 3);
-          if (isHexPair(hex)) {
-            const normalizedHex = hex.toUpperCase();
+          const hex2 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex2)) {
+            const normalizedHex = hex2.toUpperCase();
             const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
             if (isUnreserved(decoded)) {
               output += decoded;
@@ -3547,9 +3547,9 @@ var require_utils = __commonJS({
       let output = "";
       for (let i = 0; i < input.length; i++) {
         if (input[i] === "%" && i + 2 < input.length) {
-          const hex = input.slice(i + 1, i + 3);
-          if (isHexPair(hex)) {
-            output += "%" + hex.toUpperCase();
+          const hex2 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex2)) {
+            output += "%" + hex2.toUpperCase();
             i += 2;
             continue;
           }
@@ -7422,7 +7422,7 @@ var require_DOMException = __commonJS({
       "INVALID_NODE_TYPE_ERR (24): the supplied node is invalid or has an invalid ancestor for this operation",
       "DATA_CLONE_ERR (25): the object can not be cloned."
     ];
-    var constants = {
+    var constants2 = {
       INDEX_SIZE_ERR,
       DOMSTRING_SIZE_ERR: 2,
       // historical
@@ -7461,8 +7461,8 @@ var require_DOMException = __commonJS({
       this.name = names[code];
     }
     DOMException.prototype.__proto__ = Error.prototype;
-    for (c in constants) {
-      v = { value: constants[c] };
+    for (c in constants2) {
+      v = { value: constants2[c] };
       Object.defineProperty(DOMException, c, v);
       Object.defineProperty(DOMException.prototype, c, v);
     }
@@ -9329,8 +9329,8 @@ var require_select = __commonJS({
       regex = regex.replace(name, val.source || val);
       return new RegExp(regex);
     };
-    var truncateUrl = function(url, num) {
-      return url.replace(/^(?:\w+:\/\/|\/+)/, "").replace(/(?:\/+|\/*#.*?)$/, "").split("/", num).join("/");
+    var truncateUrl = function(url, num2) {
+      return url.replace(/^(?:\w+:\/\/|\/+)/, "").replace(/(?:\/+|\/*#.*?)$/, "").split("/", num2).join("/");
     };
     var parseNth = function(param_, test) {
       var param = param_.replace(/\s+/g, ""), cap;
@@ -24465,14 +24465,14 @@ var require_turndown_cjs = __commonJS({
         } else if (node.nodeType === 1) {
           replacement = replacementForNode.call(self, node);
         }
-        return join8(output, replacement);
+        return join9(output, replacement);
       }, "");
     }
     function postProcess(output) {
       var self = this;
       this.rules.forEach(function(rule) {
         if (typeof rule.append === "function") {
-          output = join8(output, rule.append(self.options));
+          output = join9(output, rule.append(self.options));
         }
       });
       return output.replace(/^[\t\r\n]+/, "").replace(/[\t\r\n\s]+$/, "");
@@ -24484,7 +24484,7 @@ var require_turndown_cjs = __commonJS({
       if (whitespace.leading || whitespace.trailing) content = content.trim();
       return whitespace.leading + rule.replacement(content, node, this.options) + whitespace.trailing;
     }
-    function join8(output, replacement) {
+    function join9(output, replacement) {
       var s1 = trimTrailingNewlines(output);
       var s2 = trimLeadingNewlines(replacement);
       var nls = Math.max(output.length - s1.length, replacement.length - s2.length);
@@ -24777,8 +24777,8 @@ var ZodError = class _ZodError extends Error {
   constructor(issues) {
     super();
     this.issues = [];
-    this.addIssue = (sub) => {
-      this.issues = [...this.issues, sub];
+    this.addIssue = (sub2) => {
+      this.issues = [...this.issues, sub2];
     };
     this.addIssues = (subs = []) => {
       this.issues = [...this.issues, ...subs];
@@ -24845,13 +24845,13 @@ var ZodError = class _ZodError extends Error {
   flatten(mapper = (issue2) => issue2.message) {
     const fieldErrors = {};
     const formErrors = [];
-    for (const sub of this.issues) {
-      if (sub.path.length > 0) {
-        const firstEl = sub.path[0];
+    for (const sub2 of this.issues) {
+      if (sub2.path.length > 0) {
+        const firstEl = sub2.path[0];
         fieldErrors[firstEl] = fieldErrors[firstEl] || [];
-        fieldErrors[firstEl].push(mapper(sub));
+        fieldErrors[firstEl].push(mapper(sub2));
       } else {
-        formErrors.push(mapper(sub));
+        formErrors.push(mapper(sub2));
       }
     }
     return { formErrors, fieldErrors };
@@ -29150,12 +29150,12 @@ var $ZodRealError = $constructor("$ZodError", initializer, { Parent: Error });
 function flattenError(error2, mapper = (issue2) => issue2.message) {
   const fieldErrors = {};
   const formErrors = [];
-  for (const sub of error2.issues) {
-    if (sub.path.length > 0) {
-      fieldErrors[sub.path[0]] = fieldErrors[sub.path[0]] || [];
-      fieldErrors[sub.path[0]].push(mapper(sub));
+  for (const sub2 of error2.issues) {
+    if (sub2.path.length > 0) {
+      fieldErrors[sub2.path[0]] = fieldErrors[sub2.path[0]] || [];
+      fieldErrors[sub2.path[0]].push(mapper(sub2));
     } else {
-      formErrors.push(mapper(sub));
+      formErrors.push(mapper(sub2));
     }
   }
   return { formErrors, fieldErrors };
@@ -39350,10 +39350,10 @@ function hasFullDiskAccess() {
     return false;
   }
 }
-function queryNoteData(noteId) {
-  const pkMatch = noteId.match(/\/p(\d+)$/);
+function queryNoteData(noteId2) {
+  const pkMatch = noteId2.match(/\/p(\d+)$/);
   if (!pkMatch) {
-    console.error(`Invalid note ID format: ${noteId}`);
+    console.error(`Invalid note ID format: ${noteId2}`);
     return { hex: null, error: "invalid_id" };
   }
   const pk = pkMatch[1];
@@ -39364,9 +39364,9 @@ function queryNoteData(noteId) {
       timeout: 5e3,
       stdio: ["pipe", "pipe", "pipe"]
     });
-    const hex = result.trim();
-    if (!hex) return { hex: null };
-    return { hex };
+    const hex2 = result.trim();
+    if (!hex2) return { hex: null };
+    return { hex: hex2 };
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     console.error(`Failed to query NoteStore database: ${message}`);
@@ -39376,10 +39376,10 @@ function queryNoteData(noteId) {
     return { hex: null };
   }
 }
-function hexToBytes(hex) {
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < hex.length; i += 2) {
-    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+function hexToBytes(hex2) {
+  const bytes = new Uint8Array(hex2.length / 2);
+  for (let i = 0; i < hex2.length; i += 2) {
+    bytes[i / 2] = parseInt(hex2.substring(i, i + 2), 16);
   }
   return bytes;
 }
@@ -39438,13 +39438,13 @@ function parseChecklistFromProtobuf(data) {
     return null;
   }
 }
-function getChecklistItems(noteId) {
-  const { hex: hexData, error: queryError } = queryNoteData(noteId);
+function getChecklistItems(noteId2) {
+  const { hex: hexData, error: queryError } = queryNoteData(noteId2);
   if (queryError === "invalid_id") {
     return {
       items: null,
       error: "invalid_id",
-      message: `Invalid note ID format: "${noteId}". Expected format: x-coredata://UUID/ICNote/pNNN`
+      message: `Invalid note ID format: "${noteId2}". Expected format: x-coredata://UUID/ICNote/pNNN`
     };
   }
   if (queryError === "no_fda") {
@@ -40281,20 +40281,20 @@ var AppleNotesManager = class {
       return null;
     }
     const rawOutput = result.output.trim();
-    const noteId = extractCoreDataId(rawOutput, "note") || rawOutput;
-    if (!noteId) {
+    const noteId2 = extractCoreDataId(rawOutput, "note") || rawOutput;
+    if (!noteId2) {
       console.error(`Created note "${title}" but Notes.app returned no canonical note ID`);
       return null;
     }
     try {
-      sanitizeNoteId(noteId);
+      sanitizeNoteId(noteId2);
     } catch {
       console.error(`Created note "${title}" but Notes.app returned an invalid note ID`);
       return null;
     }
     const now = /* @__PURE__ */ new Date();
     return {
-      id: noteId,
+      id: noteId2,
       title,
       content,
       tags,
@@ -40408,11 +40408,11 @@ var AppleNotesManager = class {
     for (const item of items) {
       const [title, id, folder2, created, modified] = item.split(FIELD_SEP);
       if (!title?.trim()) continue;
-      const noteId = id?.trim() || generateFallbackId();
-      if (seenIds.has(noteId)) continue;
-      seenIds.add(noteId);
+      const noteId2 = id?.trim() || generateFallbackId();
+      if (seenIds.has(noteId2)) continue;
+      seenIds.add(noteId2);
       notes.push({
-        id: noteId,
+        id: noteId2,
         title: title.trim(),
         content: "",
         // Not fetched in search
@@ -40780,10 +40780,10 @@ var AppleNotesManager = class {
     for (const item of output.split(RECORD_SEP)) {
       const [title, id] = item.split(FIELD_SEP);
       if (!title?.trim()) continue;
-      const noteId = id?.trim() || generateFallbackId();
-      if (seenIds.has(noteId)) continue;
-      seenIds.add(noteId);
-      refs.push({ title: title.trim(), id: noteId });
+      const noteId2 = id?.trim() || generateFallbackId();
+      if (seenIds.has(noteId2)) continue;
+      seenIds.add(noteId2);
+      refs.push({ title: title.trim(), id: noteId2 });
       if (safeLimit !== void 0 && refs.length >= safeLimit) break;
     }
     return refs;
@@ -40930,6 +40930,69 @@ var AppleNotesManager = class {
   // ===========================================================================
   // Folder Operations
   // ===========================================================================
+  /** Rename a folder in place while preserving its identity and contents. */
+  renameFolderById(id, expectedName, expectedParentId, newName) {
+    if (!/^x-coredata:\/\/[0-9a-f-]+\/ICFolder\/p\d+$/i.test(id))
+      throw new Error("An exact folder ID is required");
+    if (!newName.trim() || newName.length > 1e3 || Array.from(newName).some((char) => char.charCodeAt(0) < 32))
+      throw new Error("Invalid folder name");
+    const literal2 = (value) => `"${escapePlainStringForAppleScript(value)}"`;
+    const script = `tell application "Notes"
+      set targetFolder to folder id ${literal2(id)}
+      set parentRef to container of targetFolder
+      set parentId to id of parentRef
+      considering case
+        if name of targetFolder is not ${literal2(expectedName)} or parentId is not ${literal2(expectedParentId)} then error "Folder changed; read it again"
+      end considering
+      repeat with sibling in folders of parentRef
+        if name of sibling is ${literal2(newName)} and id of sibling is not ${literal2(id)} then error "A sibling folder already has this name"
+      end repeat
+      set name of targetFolder to ${literal2(newName)}
+      considering case
+        if id of targetFolder is not ${literal2(id)} or name of targetFolder is not ${literal2(newName)} or id of container of targetFolder is not parentId then error "Rename readback failed"
+      end considering
+      return id of targetFolder
+    end tell`;
+    const result = executeMutationAppleScript(script);
+    if (!result.success)
+      throw new Error(
+        result.error || "Rename outcome uncertain; read folder by ID before retrying"
+      );
+    return { id, name: newName, parentId: expectedParentId };
+  }
+  /** Read the exact name and parent identity used by guarded folder rename. */
+  getFolderById(id) {
+    if (!/^x-coredata:\/\/[0-9a-f-]+\/ICFolder\/p\d+$/i.test(id))
+      throw new Error("An exact folder ID is required");
+    const result = executeAppleScript(`tell application "Notes"
+      set f to folder id "${id}"
+      return (name of f) & ${AS_FIELD_SEP} & (id of container of f)
+    end tell`);
+    if (!result.success) throw new Error(result.error || "Folder not found");
+    const [name, parentId] = result.output.replace(/\n$/, "").split(FIELD_SEP);
+    if (!name || !parentId) throw new Error("Incomplete folder metadata");
+    return { id, name, parentId };
+  }
+  /** Insert one file into an unchanged exact note and return Notes' attachment ID. */
+  addAttachmentById(id, expectedBody, filePath) {
+    if (!/^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i.test(id))
+      throw new Error("Exact note ID required");
+    const quote = (value) => `"${escapePlainStringForAppleScript(value)}"`;
+    const result = executeMutationAppleScript(`tell application "Notes"
+      set n to note id ${quote(id)}
+      if password protected of n then error "Locked note"
+      considering case
+        if body of n is not ${quote(expectedBody)} and body of n is not (${quote(expectedBody)} & linefeed) then error "Note changed before attachment insertion"
+      end considering
+      set a to make new attachment at n with data (POSIX file ${quote(filePath)})
+      return id of a
+    end tell`);
+    if (!result.success)
+      throw new Error(
+        result.error || "Attachment insertion outcome uncertain; read note before retrying"
+      );
+    return result.output.trim();
+  }
   /**
    * Lists all folders in an account with full hierarchical paths.
    *
@@ -41372,8 +41435,8 @@ var AppleNotesManager = class {
    * @param separately - Open in a separate window when supported by Notes.app
    * @returns true if Notes.app revealed the attachment, false otherwise
    */
-  showAttachmentById(noteId, attachmentId, separately = false) {
-    const safeNoteId = sanitizeId(noteId);
+  showAttachmentById(noteId2, attachmentId, separately = false) {
+    const safeNoteId = sanitizeId(noteId2);
     const safeAttId = escapePlainStringForAppleScript(attachmentId);
     const separatelyClause = separately ? " separately true" : "";
     const script = `
@@ -41393,13 +41456,13 @@ var AppleNotesManager = class {
     const result = executeMutationAppleScript(script);
     if (!result.success) {
       console.error(
-        `Failed to show attachment "${attachmentId}" on note "${noteId}":`,
+        `Failed to show attachment "${attachmentId}" on note "${noteId2}":`,
         result.error
       );
       return false;
     }
     if ((result.output ?? "").trim().startsWith("ERR")) {
-      console.error(`Attachment "${attachmentId}" not found on note "${noteId}"`);
+      console.error(`Attachment "${attachmentId}" not found on note "${noteId2}"`);
       return false;
     }
     return true;
@@ -41799,7 +41862,7 @@ var AppleNotesManager = class {
    * @param savePath - absolute destination file path (within home / temp / /Volumes)
    * @returns { success, savedPath?, name?, contentType?, error? }
    */
-  saveAttachmentById(noteId, attachmentId, savePath) {
+  saveAttachmentById(noteId2, attachmentId, savePath) {
     let abs;
     try {
       abs = assertSafeSavePath(savePath);
@@ -41807,7 +41870,7 @@ var AppleNotesManager = class {
     } catch (e) {
       return { success: false, error: e instanceof Error ? e.message : String(e) };
     }
-    const safeNoteId = sanitizeId(noteId);
+    const safeNoteId = sanitizeId(noteId2);
     const safeAttId = escapePlainStringForAppleScript(attachmentId);
     const safePath = escapePlainStringForAppleScript(abs);
     const script = `
@@ -41871,11 +41934,11 @@ var AppleNotesManager = class {
    * @param attachmentId - id of the attachment
    * @returns { success, name?, contentType?, base64?, bytes?, error? }
    */
-  getAttachmentBase64ById(noteId, attachmentId) {
+  getAttachmentBase64ById(noteId2, attachmentId) {
     const dir = makeTempDir();
     try {
       const dest = `${dir}/attachment.bin`;
-      const saved = this.saveAttachmentById(noteId, attachmentId, dest);
+      const saved = this.saveAttachmentById(noteId2, attachmentId, dest);
       if (!saved.success || !saved.savedPath) {
         return { success: false, error: saved.error };
       }
@@ -42375,13 +42438,13 @@ function presentColumns() {
   }
   return cols;
 }
-function getNoteMetadata(noteId) {
-  const pkMatch = noteId.match(/\/p(\d+)$/);
+function getNoteMetadata(noteId2) {
+  const pkMatch = noteId2.match(/\/p(\d+)$/);
   if (!pkMatch) {
     return {
       metadata: null,
       error: "invalid_id",
-      message: `Invalid note ID format: "${noteId}". Expected format: x-coredata://UUID/ICNote/pNNN`
+      message: `Invalid note ID format: "${noteId2}". Expected format: x-coredata://UUID/ICNote/pNNN`
     };
   }
   const pk = pkMatch[1];
@@ -42402,7 +42465,7 @@ function getNoteMetadata(noteId) {
       return {
         metadata: null,
         error: "not_found",
-        message: `No note found in the database for ID "${noteId}".`
+        message: `No note found in the database for ID "${noteId2}".`
       };
     }
     const raw = JSON.parse(row);
@@ -42511,7 +42574,7 @@ function decodeHtmlEntities(text) {
     }
     return String.fromCodePoint(codePoint);
   };
-  return text.replace(/&#x([0-9a-f]+);?/gi, (match, hex) => decodeCodePoint(match, hex, 16)).replace(/&#([0-9]+);?/g, (match, decimal) => decodeCodePoint(match, decimal, 10)).replace(/&nbsp(?:;|(?![0-9a-z]))/gi, " ").replace(/&quot(?:;|(?![0-9a-z]))/gi, '"').replace(/&apos(?:;|(?![0-9a-z]))/gi, "'").replace(/&lt(?:;|(?![0-9a-z]))/gi, "<").replace(/&gt(?:;|(?![0-9a-z]))/gi, ">").replace(/&amp(?:;|(?![0-9a-z]))/gi, "&");
+  return text.replace(/&#x([0-9a-f]+);?/gi, (match, hex2) => decodeCodePoint(match, hex2, 16)).replace(/&#([0-9]+);?/g, (match, decimal) => decodeCodePoint(match, decimal, 10)).replace(/&nbsp(?:;|(?![0-9a-z]))/gi, " ").replace(/&quot(?:;|(?![0-9a-z]))/gi, '"').replace(/&apos(?:;|(?![0-9a-z]))/gi, "'").replace(/&lt(?:;|(?![0-9a-z]))/gi, "<").replace(/&gt(?:;|(?![0-9a-z]))/gi, ">").replace(/&amp(?:;|(?![0-9a-z]))/gi, "&");
 }
 function firstVisibleHtmlLine(html) {
   let text = html;
@@ -42852,6 +42915,282 @@ function comparableVisibleText(html) {
   ).replace(/\s+/g, " ").trim();
 }
 
+// src/utils/noteTables.ts
+import { gunzipSync as gunzipSync3 } from "node:zlib";
+var sub = (f, n) => {
+  const value = embeddedMessage(getField(f, n));
+  if (!value) throw new Error(`Missing table field ${n}`);
+  return value;
+};
+var num = (f, n) => {
+  const v = varintValue(getField(f, n));
+  if (v === void 0) throw new Error(`Missing table index ${n}`);
+  return v;
+};
+var many = (f, n) => getFields(f, n).map((v) => {
+  const m = embeddedMessage(v);
+  if (!m) throw new Error("Invalid table entry");
+  return m;
+});
+var hex = (f) => {
+  if (!(f?.value instanceof Uint8Array)) throw new Error("Missing table UUID");
+  return Buffer.from(f.value).toString("hex");
+};
+function parseNoteTable(compressed) {
+  const root = decodeMessage(gunzipSync3(compressed, { maxOutputLength: 16 * 1024 * 1024 }));
+  const data = sub(sub(root, 2), 3), entries = many(data, 3);
+  if (entries.length > 1e5) throw new Error("Table too large");
+  const keys = getFields(data, 4).map(stringValue), types = getFields(data, 5).map(stringValue), uuids = getFields(data, 6).map(hex);
+  const entry = (index) => {
+    if (!entries[index]) throw new Error("Invalid table reference");
+    return entries[index];
+  };
+  const uuidIndex = (index) => num(sub(many(sub(entry(index), 13), 3)[0], 2), 2);
+  const roots = entries.filter((e) => {
+    const map = embeddedMessage(getField(e, 13));
+    return map && types[num(map, 1)] === "com.apple.notes.ICTable";
+  });
+  if (roots.length !== 1) throw new Error("Ambiguous native table root");
+  const refs = new Map(
+    many(sub(roots[0], 13), 3).filter((m) => ["crRows", "crColumns", "cellColumns"].includes(keys[num(m, 1)] || "")).map((m) => [keys[num(m, 1)], num(sub(m, 2), 6)])
+  );
+  const ordered = (key) => {
+    const ref = refs.get(key);
+    if (ref === void 0) throw new Error("Missing table dimension");
+    const ordering = sub(sub(entry(ref), 16), 1), array2 = sub(ordering, 1);
+    const ids = many(array2, 2).map((a) => hex(getField(a, 2)));
+    const map = /* @__PURE__ */ new Map();
+    ids.forEach((id, i) => {
+      const index = uuids.indexOf(id);
+      if (index < 0) throw new Error("Missing dimension UUID");
+      map.set(index, i);
+    });
+    const aliases = many(sub(ordering, 2), 1).map((pair) => [
+      uuidIndex(num(sub(pair, 1), 6)),
+      uuidIndex(num(sub(pair, 2), 6))
+    ]);
+    for (let pass = 0; pass < aliases.length + 1; pass++) {
+      let changed = false;
+      for (const [key2, value] of aliases)
+        if (map.has(key2) && !map.has(value)) {
+          map.set(value, map.get(key2));
+          changed = true;
+        }
+      if (!changed) break;
+    }
+    return { ids, map };
+  };
+  const rows = ordered("crRows"), columns = ordered("crColumns");
+  if (!rows.ids.length || !columns.ids.length || rows.ids.length * columns.ids.length > 1e5)
+    throw new Error("Unsupported table size");
+  const values = rows.ids.map(() => columns.ids.map(() => ""));
+  const cellRef = refs.get("cellColumns");
+  if (cellRef === void 0) throw new Error("Missing table cells");
+  for (const column of many(sub(entry(cellRef), 6), 1)) {
+    const ci = columns.map.get(uuidIndex(num(sub(column, 1), 6)));
+    const cells = entry(num(sub(column, 2), 6));
+    for (const row of many(sub(cells, 6), 1)) {
+      const ri = rows.map.get(uuidIndex(num(sub(row, 1), 6)));
+      if (ri === void 0 || ci === void 0) continue;
+      const note = sub(entry(num(sub(row, 2), 6)), 10);
+      const text = stringValue(getField(note, 2));
+      if (text === void 0 || text.includes("\uFFFC"))
+        throw new Error("Embedded or unsupported table cell");
+      values[ri][ci] = text.replace(/\n$/u, "");
+    }
+  }
+  const rtl = entries.some((e) => {
+    const map = embeddedMessage(getField(e, 13));
+    return map && many(map, 3).some(
+      (m) => stringValue(getField(sub(m, 2), 4)) === "CRTableColumnDirectionRightToLeft"
+    );
+  });
+  if (rtl) {
+    for (const row of values) row.reverse();
+    columns.ids.reverse();
+  }
+  return { rows: values, rowIds: rows.ids, columnIds: columns.ids };
+}
+
+// src/tools/directOperations.ts
+import { createHash as createHash2 } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  mkdtempSync as mkdtempSync2,
+  openSync,
+  readFileSync as readFileSync3,
+  rmSync as rmSync2,
+  writeFileSync
+} from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { basename, isAbsolute as isAbsolute2, join as join8 } from "node:path";
+var noteId = external_exports.string().regex(/^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i);
+var revision = external_exports.string().regex(/^sha256:[a-f0-9]{64}$/);
+function readSnapshot(manager, id) {
+  const note = manager.getNoteById(id);
+  if (!note) throw new Error("Note not found");
+  if (note.passwordProtected) throw new Error("Locked notes cannot receive attachments");
+  const body = manager.getNoteContentById(id);
+  if (!body) throw new Error("Note content is unavailable");
+  const enriched = enrichNoteRead(id, body);
+  const rich = readRichNote(id);
+  if (!enriched.complete || enriched.revision !== rich.revision)
+    throw new Error("Native metadata changed during read; read the note again");
+  return { id, 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 = (text) => text.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((id) => !after.rich.nativeObjectIds.includes(id)))
+    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");
+  }
+}
+function localAttachment(path4) {
+  if (!isAbsolute2(path4)) throw new Error("An absolute local file path is required");
+  const descriptor = openSync(path4, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile() || stat.size === 0 || stat.size > 64 * 1024 * 1024)
+      throw new Error("Attachment must be a nonempty regular file of at most 64 MiB");
+    const bytes = readFileSync3(descriptor);
+    if (bytes.length !== stat.size)
+      throw new Error("Attachment changed while it was being read; try again");
+    return bytes;
+  } finally {
+    closeSync(descriptor);
+  }
+}
+function registerDirectOperations(server2, manager) {
+  function tool(name, description, inputSchema, handler, readOnly = false) {
+    server2.registerTool(
+      name,
+      {
+        description,
+        inputSchema,
+        outputSchema: external_exports.object({ ok: external_exports.boolean().optional() }).passthrough(),
+        annotations: { readOnlyHint: readOnly }
+      },
+      (async (args) => {
+        try {
+          const result = handler(args);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+            structuredContent: result
+          };
+        } catch (error2) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: error2 instanceof Error ? error2.message : String(error2)
+              }
+            ],
+            isError: true
+          };
+        }
+      })
+    );
+  }
+  tool(
+    "get-folder-by-id",
+    "Use when: reading the exact folder name and parent before a guarded rename.\nReturns: folder id, current name, and parent id.\nDo not use when: listing folders by path (list-folders).\nSafety: read-only.",
+    { id: external_exports.string().max(2e3) },
+    ({ id }) => manager.getFolderById(id),
+    true
+  );
+  tool(
+    "rename-folder",
+    "Use when: renaming one previously read folder in place.\nReturns: the unchanged folder id, new name, and parent id after readback.\nDo not use when: creating, moving, or deleting a folder.\nSafety: requires the expected current name and parent; refuses stale metadata and sibling conflicts.",
+    {
+      id: external_exports.string().max(2e3),
+      expectedName: external_exports.string().max(1e3),
+      expectedParentId: external_exports.string().max(2e3),
+      newName: external_exports.string().min(1).max(1e3)
+    },
+    (args) => ({
+      ok: true,
+      ...manager.renameFolderById(args.id, args.expectedName, args.expectedParentId, args.newName)
+    })
+  );
+  tool(
+    "add-attachment",
+    "Use when: adding one local file to an exact note without replacing its body.\nReturns: the new attachment id, byte count, and post-write content hash after exact byte verification.\nDo not use when: reading or exporting an existing attachment.\nSafety: requires a fresh rich revision, copies at most 64 MiB through a private temporary file, never retries insertion, and verifies existing content plus fetched bytes.",
+    { id: noteId, expectedContentHash: revision, path: external_exports.string().min(1).max(4096) },
+    ({ id, expectedContentHash, path: path4 }) => {
+      const before = readSnapshot(manager, id);
+      if (before.hash !== expectedContentHash) throw new Error("Note revision changed");
+      const bytes = localAttachment(path4);
+      const beforeAttachments = manager.listAttachmentsById(id);
+      const directory = mkdtempSync2(join8(tmpdir2(), "notes-attachment-add-"));
+      const temporaryFile = join8(directory, basename(path4));
+      try {
+        writeFileSync(temporaryFile, bytes, { mode: 384 });
+        if (readSnapshot(manager, id).hash !== before.hash)
+          throw new Error("Note revision changed");
+        let returnedId;
+        let transportUncertain = false;
+        try {
+          returnedId = manager.addAttachmentById(id, before.body, temporaryFile);
+        } catch {
+          transportUncertain = true;
+        }
+        const after = readSnapshot(manager, id);
+        assertExistingContentPreserved(before, after);
+        const readInserted = () => [
+          ...new Map(manager.listAttachmentsById(id).map((item) => [item.id, item])).values()
+        ].filter((item) => !beforeAttachments.some((existing) => existing.id === item.id));
+        let inserted = readInserted();
+        for (let attempt = 0; attempt < 4 && (inserted.length !== 1 || returnedId && returnedId !== inserted[0].id); attempt++) {
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250);
+          inserted = readInserted();
+        }
+        const persistentReturnedId = returnedId && /\/ICAttachment\/p\d+$/.test(returnedId);
+        if (inserted.length !== 1 || persistentReturnedId && returnedId !== inserted[0].id)
+          throw new Error(
+            "Attachment insertion outcome uncertain; read the exact note before retrying"
+          );
+        const attachmentId = inserted[0].id;
+        const fetched = manager.getAttachmentBase64ById(id, attachmentId);
+        const actual = typeof fetched.base64 === "string" ? Buffer.from(fetched.base64, "base64") : null;
+        if (!actual || createHash2("sha256").update(actual).digest("hex") !== createHash2("sha256").update(bytes).digest("hex"))
+          throw new Error(
+            "Attachment bytes were not verified; read the exact note before retrying"
+          );
+        return {
+          ok: true,
+          id,
+          attachmentId,
+          contentHash: after.hash,
+          bytes: bytes.length,
+          ...transportUncertain ? {
+            transportWarning: "Transport was uncertain; exact bytes and prior content were verified"
+          } : {}
+        };
+      } finally {
+        rmSync2(directory, { recursive: true, force: true });
+      }
+    }
+  );
+}
+
 // src/index.ts
 loadFileConfig();
 var require2 = createRequire(import.meta.url);
@@ -42862,6 +43201,7 @@ var server = new McpServer({
   description: "MCP server for managing Apple Notes - create, search, update, and organize notes"
 });
 var notesManager = new AppleNotesManager();
+registerDirectOperations(server, notesManager);
 function successResponse(message, structured) {
   const res = { content: [{ type: "text", text: message }] };
   if (structured) res.structuredContent = structured;
@@ -43406,6 +43746,100 @@ registerTool(
     return successResponse(`Shown account with ID "${id}" in Notes.app`, { id, separately });
   }, "Error showing account")
 );
+registerTool(
+  "get-native-objects",
+  {
+    description: "Use when: inspecting native objects, checklist identities, or tables in one exact note.\nReturns: native object IDs and ranges, checklist IDs and state, actual native tags, decoded tables, and the current rich content hash.\nDo not use when: you only need the note body (get-note-content) or AppleScript attachment metadata (list-attachments).\nSafety: read-only; requires Full Disk Access and reports incomplete table metadata instead of guessing.",
+    inputSchema: { id: noteIdInput },
+    outputSchema: {
+      id: external_exports.string().optional(),
+      contentHash: external_exports.string().optional(),
+      objects: external_exports.array(external_exports.record(external_exports.unknown())).optional(),
+      checklistItems: external_exports.array(external_exports.record(external_exports.unknown())).optional(),
+      nativeTags: external_exports.array(external_exports.string()).optional(),
+      tables: external_exports.array(external_exports.record(external_exports.unknown())).optional(),
+      tableCellsComplete: external_exports.boolean().optional()
+    },
+    annotations: { readOnlyHint: true }
+  },
+  withErrorHandling(({ id }) => {
+    const note = notesManager.getNoteById(id);
+    if (!note) return errorResponse(`Note with ID "${id}" not found`);
+    const body = notesManager.getNoteContentById(id);
+    if (!body) return errorResponse(`Failed to read content of note "${note.title}"`);
+    const rich = readRichNote(id);
+    const tables = (rich.objectData || []).filter((object3) => object3.type?.includes("table")).map((object3) => {
+      try {
+        return {
+          id: object3.id,
+          attachmentId: id.replace(/ICNote\/p\d+$/, `ICAttachment/p${object3.pk}`),
+          complete: true,
+          ...parseNoteTable(Buffer.from(object3.mergeable, "hex"))
+        };
+      } catch (error2) {
+        return { id: object3.id, complete: false, reason: String(error2) };
+      }
+    });
+    for (const object3 of rich.objects || []) {
+      if (object3.type.includes("table") && !tables.some((table) => table.id === object3.id)) {
+        tables.push({
+          id: object3.id,
+          complete: false,
+          reason: "Native table metadata is unavailable"
+        });
+      }
+    }
+    const richRead = {
+      content: body,
+      links: rich.links,
+      nativeTags: rich.nativeTags,
+      complete: true,
+      writable: !rich.hasNativeObjects && !rich.hasChecklist,
+      revision: rich.revision
+    };
+    return successResponse("Native objects read from the exact note", {
+      id,
+      contentHash: richContentHash(body, richRead),
+      objects: rich.objects,
+      checklistItems: rich.checklistItems,
+      nativeTags: rich.nativeTags,
+      tables,
+      tableCellsComplete: tables.every((table) => table.complete)
+    });
+  }, "Error reading native objects")
+);
+registerTool(
+  "list-native-tags",
+  {
+    description: "Use when: listing actual native Notes tags used in one explicit account and folder.\nReturns: each native tag mapped to exact matching note IDs, plus completeness and per-note errors.\nDo not use when: searching textual #hashtags in note bodies (search-notes).\nSafety: read-only; requires Full Disk Access and discloses partial reads.",
+    inputSchema: {
+      account: external_exports.string().min(1).max(MAX.ACCOUNT),
+      folder: external_exports.string().min(1).max(MAX.FOLDER)
+    },
+    outputSchema: {
+      tags: external_exports.record(external_exports.array(external_exports.string())).optional(),
+      complete: external_exports.boolean().optional(),
+      errors: external_exports.record(external_exports.string()).optional()
+    },
+    annotations: { readOnlyHint: true }
+  },
+  withErrorHandling(({ account, folder }) => {
+    const tags = {};
+    const errors = {};
+    for (const note of notesManager.listNoteRefs(account, folder)) {
+      try {
+        for (const tag of readRichNote(note.id).nativeTags) (tags[tag] ||= []).push(note.id);
+      } catch {
+        errors[note.id] = "Native metadata unavailable";
+      }
+    }
+    return successResponse("Native tags read from the requested folder", {
+      tags,
+      complete: Object.keys(errors).length === 0,
+      errors
+    });
+  }, "Error listing native tags")
+);
 registerTool(
   "update-note",
   {
@@ -44263,8 +44697,8 @@ registerTool(
       contentType: external_exports.string().optional()
     }
   },
-  withErrorHandling(({ noteId, attachmentId, savePath }) => {
-    const r = notesManager.saveAttachmentById(noteId, attachmentId, savePath);
+  withErrorHandling(({ noteId: noteId2, attachmentId, savePath }) => {
+    const r = notesManager.saveAttachmentById(noteId2, attachmentId, savePath);
     if (!r.success) {
       return errorResponse(`Failed to save attachment: ${r.error ?? "unknown error"}`);
     }
@@ -44290,8 +44724,8 @@ registerTool(
       base64: external_exports.string().optional()
     }
   },
-  withErrorHandling(({ noteId, attachmentId }) => {
-    const r = notesManager.getAttachmentBase64ById(noteId, attachmentId);
+  withErrorHandling(({ noteId: noteId2, attachmentId }) => {
+    const r = notesManager.getAttachmentBase64ById(noteId2, attachmentId);
     if (!r.success || !r.base64) {
       return errorResponse(`Failed to fetch attachment: ${r.error ?? "unknown error"}`);
     }
@@ -44316,13 +44750,13 @@ registerTool(
       separately: external_exports.boolean().optional()
     }
   },
-  withErrorHandling(({ noteId, attachmentId, separately = false }) => {
-    const success = notesManager.showAttachmentById(noteId, attachmentId, separately);
+  withErrorHandling(({ noteId: noteId2, attachmentId, separately = false }) => {
+    const success = notesManager.showAttachmentById(noteId2, attachmentId, separately);
     if (!success) {
-      return errorResponse(`Failed to show attachment "${attachmentId}" on note "${noteId}"`);
+      return errorResponse(`Failed to show attachment "${attachmentId}" on note "${noteId2}"`);
     }
     return successResponse(`Shown attachment "${attachmentId}" in Notes.app`, {
-      noteId,
+      noteId: noteId2,
       attachmentId,
       separately
     });

package/package.json

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