apple-notes-mcp 2.8.45 → 2.8.47

package/README.md

@@ -56,7 +56,7 @@ Install as a Claude Code plugin for automatic configuration and enhanced AI beha
 
 This method also installs a **skill** that teaches Claude when and how to use Apple Notes effectively.
 
-On the first tool call, macOS shows an Automation permission prompt ("Claude" wants access to control "Notes") — click **OK**. Optionally, grant **Full Disk Access** to the app that launches the server to enable the database-backed tools (`get-checklist-state`, `get-note-metadata`, `get-audio-transcripts`, `list-special-notes`, `list-native-tags`, `get-note-link`, checklist annotations in `get-note-markdown`, and full `get-sync-status` detail); see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md). The rest of the server is pure AppleScript and works without it.
+On the first tool call, macOS shows an Automation permission prompt ("Claude" wants access to control "Notes") — click **OK**. Optionally, grant **Full Disk Access** (under Claude Desktop, to the Node binary that runs the server; from a terminal, to the terminal app) to enable the database-backed tools (`get-checklist-state`, `get-note-metadata`, `get-audio-transcripts`, `list-special-notes`, `list-native-tags`, `get-note-link`, checklist annotations in `get-note-markdown`, and full `get-sync-status` detail); see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md). The rest of the server is pure AppleScript and works without it.
 
 Native tag, checklist, table, pin, and rich append operations use two packaged
 Apple Shortcuts. A third, `Apple Notes MCP - Create Markdown Note`, is optional:
@@ -1035,7 +1035,7 @@ Returns the `notes://showNote?identifier=<uuid>` deep-link URL for a note. The U
 
 **Returns:** `notes://showNote?identifier=<uuid>` URL string, plus the note id and title.
 
-**Note:** Requires Full Disk Access for the app that launches the server so the Notes SQLite database is readable. On macOS 12–15 the tool also falls back to the AppleScript `note link` property. Run the `doctor` tool to verify access.
+**Note:** Requires Full Disk Access for the process that runs the server so the Notes SQLite database is readable. On macOS 12–15 the tool also falls back to the AppleScript `note link` property. Run the `doctor` tool to verify access.
 
 ---
 
@@ -1174,6 +1174,8 @@ Creates a new folder, including a whole nested hierarchy in one call.
 
 **Returns:** Confirmation message. The call is **idempotent** — an already-existing folder (or path segment) is skipped rather than treated as an error, so it is safe to call before every `create-note` that targets a folder.
 
+Existence is decided by folder id, not by name: a folder deleted earlier in the same Notes session no longer counts as existing, and the call succeeds only once the created folder is confirmed by its id. Otherwise it reports failure.
+
 ---
 
 #### `get-folder-by-id`
@@ -2125,12 +2127,12 @@ Several tools read directly from the Apple Notes SQLite database, which lives in
 1. Open **System Settings** (or System Preferences on older macOS)
 2. Go to **Privacy & Security > Full Disk Access**
 3. Click the **+** button
-4. Add the application that hosts the MCP server:
-   - **Claude Desktop**: Add `/Applications/Claude.app`
+4. Add the entry that matches how the server runs:
+   - **Claude Desktop**: add the **Node binary** that runs the server (the `doctor` tool prints its path, e.g. `~/.nvm/versions/node/v24.11.1/bin/node`; press ⌘⇧G in the file picker to paste it). Claude Desktop launches MCP servers as their own responsible process, so a grant on `/Applications/Claude.app` alone does not reach them ([#220](https://github.com/sweetrb/apple-notes-mcp/issues/220)).
    - **Terminal**: Add `/Applications/Utilities/Terminal.app`
    - **VS Code**: Add `/Applications/Visual Studio Code.app`
    - **iTerm**: Add `/Applications/iTerm.app`
-5. Restart the application after granting access
+5. Fully quit (⌘Q) and relaunch the host app after granting access; if `doctor` still reports it missing, restart the Mac
 
 ### Without Full Disk Access
 

package/build/index.js

@@ -39536,7 +39536,7 @@ function getChecklistItems(noteId3) {
     return {
       items: null,
       error: "no_fda",
-      message: `Full Disk Access is required to read checklist state. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`
+      message: `Full Disk Access is required to read checklist state. In System Settings > Privacy & Security > Full Disk Access, grant access to the Node binary running this server (required under Claude Desktop) or the terminal that launches it, then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`
     };
   }
   if (!hexData) {
@@ -40199,7 +40199,7 @@ function readAudioTranscripts(noteId3, options = {}) {
     if (/authorization denied|unable to open database/i.test(message))
       throw new AudioTranscriptError(
         "no_fda",
-        `Full Disk Access is required to read stored transcripts. Grant it to the app that launches this server, then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`
+        `Full Disk Access is required to read stored transcripts. Grant it to the Node binary running this server (or the terminal that launches it), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`
       );
     throw new AudioTranscriptError("query_error", "Failed to read the Notes database.");
   }
@@ -40516,7 +40516,7 @@ var NOTES_DB_PATH3 = path2.join(
   os2.homedir(),
   "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
 );
-var FDA_MESSAGE = `Full Disk Access is required to read smart folders. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
+var FDA_MESSAGE = `Full Disk Access is required to read smart folders. In System Settings > Privacy & Security > Full Disk Access, grant access to the Node binary running this server (required under Claude Desktop) or the terminal that launches it, then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
 var COCOA_EPOCH_OFFSET = 978307200;
 var MAX_DEPTH = 32;
 var RELATIVE_RANGES = {
@@ -41275,7 +41275,7 @@ function runSqlite3(dbPath2, sql) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     if (/authorization denied|unable to open database/i.test(message)) {
       throw new AttachmentStoreError(
-        "Full Disk Access is required to read attachment paths. Grant it to the app that launches this server, then relaunch it (run the doctor tool to verify).",
+        "Full Disk Access is required to read attachment paths. Grant it to the Node binary running this server (or the terminal that launches it), then relaunch it (run the doctor tool to verify).",
         "no_fda"
       );
     }
@@ -41809,7 +41809,7 @@ function runSqlite4(dbPath2, sql) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     if (/authorization denied|unable to open database/i.test(message)) {
       throw new AttachmentStoreError(
-        "Full Disk Access is required to read drawing attachments. Grant it to the app that launches this server, then relaunch it (run the doctor tool to verify).",
+        "Full Disk Access is required to read drawing attachments. Grant it to the Node binary running this server (or the terminal that launches it), then relaunch it (run the doctor tool to verify).",
         "no_fda"
       );
     }
@@ -42321,6 +42321,58 @@ function buildFolderReference(folderPath) {
   return parts.reverse().map((part) => `folder "${escapePlainStringForAppleScript(part)}"`).join(" of ");
 }
 var AS_ACCOUNT_REF = "__acctRef";
+var LIVE_FOLDER_NOT_FOUND = "Folder not found";
+function buildLiveFolderResolution(folderPath, varName, opts = {}) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(varName)) throw new Error("Invalid AppleScript variable");
+  buildFolderReference(folderPath);
+  const parts = splitFolderPath(folderPath);
+  const c = `${varName}_c`;
+  const cid = `${varName}_cid`;
+  const any = `${varName}_any`;
+  const parent = `${varName}_p`;
+  const notFound = `error "${LIVE_FOLDER_NOT_FOUND}: ${escapePlainStringForAppleScript(folderPath)}" number -1728`;
+  const lines = [];
+  parts.forEach((part, i) => {
+    const name = escapePlainStringForAppleScript(part);
+    if (i === 0) {
+      lines.push(
+        `set ${varName} to missing value`,
+        `set ${any} to missing value`,
+        `repeat with ${c} in (folders of ${AS_ACCOUNT_REF} whose name is "${name}")`,
+        `  try`,
+        `    set ${cid} to id of ${c}`,
+        `    if exists folder id ${cid} then`,
+        `      if class of (container of ${c}) is not folder then`,
+        `        set ${varName} to folder id ${cid}`,
+        `        exit repeat`,
+        `      else if ${any} is missing value then`,
+        `        set ${any} to folder id ${cid}`,
+        `      end if`,
+        `    end if`,
+        `  end try`,
+        `end repeat`
+      );
+      if (!opts.rootOnly)
+        lines.push(`if ${varName} is missing value then set ${varName} to ${any}`);
+    } else {
+      lines.push(
+        `set ${parent} to ${varName}`,
+        `set ${varName} to missing value`,
+        `repeat with ${c} in (folders of ${parent} whose name is "${name}")`,
+        `  try`,
+        `    set ${cid} to id of ${c}`,
+        `    if exists folder id ${cid} then`,
+        `      set ${varName} to folder id ${cid}`,
+        `      exit repeat`,
+        `    end if`,
+        `  end try`,
+        `end repeat`
+      );
+    }
+    lines.push(`if ${varName} is missing value then ${notFound}`);
+  });
+  return lines.join("\n");
+}
 var ACCOUNT_RESOLUTION_ERROR = "AccountResolutionError:";
 function throwIfAccountResolutionFailed(error2) {
   if (!error2) return;
@@ -42550,8 +42602,8 @@ var AppleNotesManager = class {
     const safeBody = escapeHtmlForAppleScript(`<h1>${htmlTitle}</h1>${bodyContent}`);
     let createCommand;
     if (folder) {
-      const folderRef = buildFolderReference(folder);
-      createCommand = `make new note at ${folderRef} with properties {body:"${safeBody}"}`;
+      createCommand = `${buildLiveFolderResolution(folder, "__folder")}
+      make new note at __folder with properties {body:"${safeBody}"}`;
     } else {
       createCommand = `
         set newNote to make new note with properties {body:"${safeBody}"}
@@ -43663,10 +43715,10 @@ var AppleNotesManager = class {
     }
     for (let i = 0; i < parts.length; i++) {
       const currentPath = parts.slice(0, i + 1).map((p) => escapeFolderName(p)).join("/");
-      const currentRef = buildFolderReference(currentPath);
       const checkScript = buildAccountScopedScript(
         { account: targetAccount },
-        `return id of ${currentRef}`
+        `${buildLiveFolderResolution(currentPath, "__folder", { rootOnly: true })}
+        return id of __folder`
       );
       const checkResult = executeAppleScript(checkScript);
       if (checkResult.success) {
@@ -43678,8 +43730,8 @@ var AppleNotesManager = class {
         createCommand = `make new folder with properties {name:"${segmentName}"}`;
       } else {
         const parentPath = parts.slice(0, i).map((p) => escapeFolderName(p)).join("/");
-        const parentRef = buildFolderReference(parentPath);
-        createCommand = `make new folder at ${parentRef} with properties {name:"${segmentName}"}`;
+        createCommand = `${buildLiveFolderResolution(parentPath, "__parent", { rootOnly: true })}
+        make new folder at __parent with properties {name:"${segmentName}"}`;
       }
       const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
       const result = executeMutationAppleScript(script);
@@ -43689,14 +43741,23 @@ var AppleNotesManager = class {
         return null;
       }
     }
-    const fullRef = buildFolderReference(name);
     const idScript = buildAccountScopedScript(
       { account: targetAccount },
-      `return (id of ${fullRef}) & ${AS_FIELD_SEP} & (name of it)`
+      `${buildLiveFolderResolution(name, "__folder", { rootOnly: true })}
+      return (id of __folder) & ${AS_FIELD_SEP} & (name of it)`
     );
     const idResult = executeAppleScript(idScript);
     const [rawId = "", rawAccount = ""] = idResult.success ? idResult.output.split(FIELD_SEP) : [];
-    const folderId2 = idResult.success ? extractCoreDataId(rawId, "folder") : "";
+    const bareId = rawId.trim();
+    const folderId2 = !idResult.success ? "" : FOLDER_ID_PATTERN.test(bareId) ? bareId : extractCoreDataId(rawId, "folder");
+    if (!folderId2) {
+      throwIfAccountResolutionFailed(idResult.error);
+      console.error(
+        `Folder "${name}" could not be confirmed after creation:`,
+        idResult.error ?? "no folder id returned"
+      );
+      return null;
+    }
     return {
       id: folderId2,
       name,
@@ -43714,7 +43775,8 @@ var AppleNotesManager = class {
    */
   deleteFolder(name, account) {
     const targetAccount = this.resolveAccount(account);
-    const deleteCommand = `delete ${buildFolderReference(name)}`;
+    const deleteCommand = `${buildLiveFolderResolution(name, "__folder")}
+    delete __folder`;
     const script = buildAccountScopedScript({ account: targetAccount }, deleteCommand);
     const result = executeMutationAppleScript(script);
     if (!result.success) {
@@ -43740,10 +43802,10 @@ var AppleNotesManager = class {
   moveNoteById(id2, destinationFolder, account, scope2) {
     const targetAccount = this.resolveAccount(account);
     const safeId = sanitizeNoteId(id2);
-    const destFolderRef = `${buildFolderReference(destinationFolder)} of ${AS_ACCOUNT_REF}`;
+    const destFolderSetup = buildLiveFolderResolution(destinationFolder, "destFolder");
     const moveCommand = `
       ${buildAccountResolution(targetAccount)}
-      set destFolder to ${destFolderRef}
+      ${destFolderSetup}
       set noteRef to note id "${safeId}"${buildScopeGuardScript("noteRef", scope2, "destFolder")}
       move noteRef to destFolder
       set movedNoteRef to note id "${safeId}"
@@ -44649,7 +44711,7 @@ var AppleNotesManager = class {
   batchMoveNotes(ids, folder, account) {
     if (ids.length === 0) return [];
     const targetAccount = this.resolveAccount(account);
-    const destFolderRef = `${buildFolderReference(folder)} of ${AS_ACCOUNT_REF}`;
+    const destFolderSetup = buildLiveFolderResolution(folder, "destFolder");
     const results = new Array(ids.length);
     const runnable = [];
     ids.forEach((id2, i) => {
@@ -44667,7 +44729,7 @@ var AppleNotesManager = class {
       const idList2 = runnable.map((r) => `"${r.safe}"`).join(", ");
       const script = buildAppLevelScript(`
         ${buildAccountResolution(targetAccount)}
-        set destFolder to ${destFolderRef}
+        ${destFolderSetup}
         set out to ""
         repeat with rawId in {${idList2}}
           set theId to (rawId as text)
@@ -45118,7 +45180,7 @@ var NOTES_DB_PATH6 = path5.join(
   os5.homedir(),
   "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
 );
-var FDA_MESSAGE2 = `Full Disk Access is required to read note metadata. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
+var FDA_MESSAGE2 = `Full Disk Access is required to read note metadata. In System Settings > Privacy & Security > Full Disk Access, grant access to the Node binary running this server (required under Claude Desktop) or the terminal that launches it, then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
 var COLUMN_MAP = [
   { key: "pinned", column: "ZISPINNED", type: "bool" },
   { key: "hasChecklist", column: "ZHASCHECKLIST", type: "bool" },
@@ -45211,7 +45273,7 @@ var NOTES_DB_PATH7 = path6.join(
   "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
 );
 var CORE_DATA_EPOCH_MS = Date.UTC(2001, 0, 1);
-var STORE_FDA_MESSAGE = `Full Disk Access is required to read the Notes database. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
+var STORE_FDA_MESSAGE = `Full Disk Access is required to read the Notes database. In System Settings > Privacy & Security > Full Disk Access, grant access to the Node binary running this server (required under Claude Desktop) or the terminal that launches it, then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
 var NoteStoreError = class extends Error {
   constructor(message, kind) {
     super(message);
@@ -45635,7 +45697,7 @@ var ENTITY_LABEL = {
   ICFolder: "folder",
   ICAccount: "account"
 };
-var NO_FDA_MESSAGE = `Resolving a Notes UUID or numeric key reads the Notes database, which needs Full Disk Access for the app that launches this server (System Settings > Privacy & Security > Full Disk Access, then fully quit and relaunch it). x-coredata ids from search-notes, list-notes, or list-folders work without it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`;
+var NO_FDA_MESSAGE = `Resolving a Notes UUID or numeric key reads the Notes database, which needs Full Disk Access for the Node binary running this server, or the terminal that launches it (System Settings > Privacy & Security > Full Disk Access, then fully quit and relaunch it). x-coredata ids from search-notes, list-notes, or list-folders work without it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`;
 function canonicalKey(value) {
   return BigInt(value).toString();
 }
@@ -46391,7 +46453,7 @@ var QUERY_RESULTS = { DEFAULT: 50, MAX: 500 };
 var CORE_DATA_EPOCH_MS2 = Date.UTC(2001, 0, 1);
 var SNIPPET_BEFORE = 60;
 var SNIPPET_LENGTH = 180;
-var QUERY_FDA_MESSAGE = `Full Disk Access is required to query notes. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
+var QUERY_FDA_MESSAGE = `Full Disk Access is required to query notes. In System Settings > Privacy & Security > Full Disk Access, grant access to the Node binary running this server (required under Claude Desktop) or the terminal that launches it, then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
 var NoteQueryStoreError = class extends Error {
   constructor(message, kind) {
     super(message);
@@ -46776,7 +46838,7 @@ function describeContentScan(scan) {
 }
 function contentSearchFailureHint(message, dbUnavailable) {
   if (!/timed out/i.test(message)) return message;
-  const remedy = dbUnavailable === "no_fda" ? " Grant Full Disk Access to the app that launches this server (run the doctor tool) so search-notes can search note bodies through the Notes database instead, which takes well under a second." : "";
+  const remedy = dbUnavailable === "no_fda" ? " Grant Full Disk Access to the Node binary running this server (run the doctor tool for its path) so search-notes can search note bodies through the Notes database instead, which takes well under a second." : "";
   return `${message} Body search through AppleScript scans every note body before the result limit applies, so a broad term can exceed the time budget on a large library.${remedy} Otherwise narrow the search with \`folder\` or \`modifiedSince\`, or use a more specific term.`;
 }
 
@@ -47868,7 +47930,7 @@ function runDoctor(manager, capabilityMatrix = getCapabilityMatrix) {
   checks.push({
     name: "Full Disk Access",
     status: fda ? "ok" : "warn",
-    detail: fda ? "granted \u2014 the Notes database is readable (checklist state, note metadata, note links, sync detail)" : `not granted \u2014 get-checklist-state, get-note-metadata, and the checklist annotations in get-note-markdown won't work; get-note-link fails on macOS 26+ (macOS 12-15 falls back to AppleScript); get-sync-status still answers but cannot see pending uploads. Everything else is pure AppleScript and is unaffected. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it and re-run doctor. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`
+    detail: fda ? "granted \u2014 the Notes database is readable (checklist state, note metadata, note links, sync detail)" : "not granted \u2014 get-checklist-state, get-note-metadata, and the checklist annotations in get-note-markdown won't work; get-note-link fails on macOS 26+ (macOS 12-15 falls back to AppleScript); get-sync-status still answers but cannot see pending uploads. Everything else is pure AppleScript and is unaffected. " + fdaRemediation()
   });
   const consentReminder = "After install or upgrade, run each bridge Shortcut once in the foreground in Shortcuts.app and choose Always Allow: a background run cannot display a first-run consent prompt, so an unanswered one stalls that bridge's native writes until they time out while this check stays ok";
   try {
@@ -47899,6 +47961,10 @@ function runDoctor(manager, capabilityMatrix = getCapabilityMatrix) {
   }
   return matrix ? { healthy, checks, runtimeOS: matrix.runtimeOS, features: matrix.features } : { healthy, checks };
 }
+function fdaRemediation(execPath = process.execPath) {
+  const versioned = /\/(\.nvm|\.fnm|\.volta|\.asdf|\.local\/share\/mise|\.nodenv|n\/versions)\//.test(execPath);
+  return `In System Settings > Privacy & Security > Full Disk Access, click + and add the Node binary running this server: ${execPath} (press Cmd+Shift+G in the file picker to paste the path). Under Claude Desktop that entry is required: Claude Desktop launches servers as their own responsible process, so a grant on Claude.app does not reach them. When the server runs from a terminal (Terminal, iTerm2) or an editor, granting that app is enough. Then fully quit (Cmd+Q) and relaunch the host app and re-run doctor; if it still reports not granted, restart the Mac. ` + (versioned ? "This Node lives under a version manager, so the path changes with each Node version and the grant has to be added again after switching; pointing the MCP config at one fixed Node path avoids that. " : "") + `Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`;
+}
 function markdownBridgeDetail() {
   const purpose = 'needed only for create-note format: "markdown" on macOS 26+';
   try {
@@ -50522,7 +50588,7 @@ function classify(error2) {
   const message = error2 instanceof Error ? error2.message : String(error2);
   if (/authorization denied|unable to open database|not authorized/i.test(message)) {
     return new FolderStoreError(
-      "Full Disk Access is required to verify folder type and contents before deleting. Grant it to the app that launches this server, then relaunch it.",
+      "Full Disk Access is required to verify folder type and contents before deleting. Grant it to the Node binary running this server (or the terminal that launches it), then relaunch it.",
       "no_fda"
     );
   }
@@ -52104,7 +52170,7 @@ registerTool(
 registerTool(
   "get-note-link",
   {
-    description: "Use when: you need the notes:// deep-link URL for a note so it can be stored in a Reminders task, shared, or opened directly.\nReturns: a notes://showNote?identifier=<uuid> URL that opens the note in Notes.app on iOS and macOS.\nDo not use when: you only need the note's CoreData id (get-note-by-id) or want to reveal the note on screen (show-note).\nNote: the primary path reads the note's identifier from the Notes database, so it needs Full Disk Access for the app that launches this server; macOS 12-15 can fall back to the AppleScript 'note link' property, which macOS 26+ no longer exposes. Password-protected notes cannot be linked.",
+    description: "Use when: you need the notes:// deep-link URL for a note so it can be stored in a Reminders task, shared, or opened directly.\nReturns: a notes://showNote?identifier=<uuid> URL that opens the note in Notes.app on iOS and macOS.\nDo not use when: you only need the note's CoreData id (get-note-by-id) or want to reveal the note on screen (show-note).\nNote: the primary path reads the note's identifier from the Notes database, so it needs Full Disk Access for the Node binary running this server; macOS 12-15 can fall back to the AppleScript 'note link' property, which macOS 26+ no longer exposes. Password-protected notes cannot be linked.",
     inputSchema: {
       id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
@@ -52130,7 +52196,7 @@ registerTool(
       const url2 = notesManager.getNoteLinkById(id2);
       if (!url2) {
         return errorResponse(
-          `Failed to get note link for "${note2.title}". The Notes database may not be accessible \u2014 grant Full Disk Access to the app that launches the server, fully quit and relaunch, then run the doctor tool. See: ${FULL_DISK_ACCESS_GUIDE_URL}. (On macOS 12\u201315 this also falls back to the AppleScript note link property.)`
+          `Failed to get note link for "${note2.title}". The Notes database may not be accessible \u2014 grant Full Disk Access to the Node binary running the server (or the terminal that launches it), fully quit and relaunch, then run the doctor tool. See: ${FULL_DISK_ACCESS_GUIDE_URL}. (On macOS 12\u201315 this also falls back to the AppleScript note link property.)`
         );
       }
       return successResponse(`Note link: ${url2}`, { id: id2, title: note2.title, url: url2 });
@@ -52150,7 +52216,7 @@ registerTool(
     const url = notesManager.getNoteLink(title, account);
     if (!url) {
       return errorResponse(
-        `Failed to get note link for "${title}". The Notes database may not be accessible \u2014 grant Full Disk Access to the app that launches the server, fully quit and relaunch, then run the doctor tool. See: ${FULL_DISK_ACCESS_GUIDE_URL}. (On macOS 12\u201315 this also falls back to the AppleScript note link property.)`
+        `Failed to get note link for "${title}". The Notes database may not be accessible \u2014 grant Full Disk Access to the Node binary running the server (or the terminal that launches it), fully quit and relaunch, then run the doctor tool. See: ${FULL_DISK_ACCESS_GUIDE_URL}. (On macOS 12\u201315 this also falls back to the AppleScript note link property.)`
       );
     }
     return successResponse(`Note link: ${url}`, { title, url });
@@ -52323,7 +52389,7 @@ registerTool(
       page = pageNoteBlocks(readNoteBlocks(id2), { offset, limit });
     } catch (error2) {
       if (!(error2 instanceof NoteBlocksError)) throw error2;
-      const hint = error2.code === "no-full-disk-access" ? ` Grant Full Disk Access to the app that launches this server: ${FULL_DISK_ACCESS_GUIDE_URL}` : "";
+      const hint = error2.code === "no-full-disk-access" ? ` Grant Full Disk Access to the Node binary running this server (run the doctor tool for its path): ${FULL_DISK_ACCESS_GUIDE_URL}` : "";
       return errorResponse(`Error reading note blocks [${error2.code}]: ${error2.message}${hint}`);
     }
     const { summary } = page;
@@ -53207,7 +53273,7 @@ registerTool(
       return `  ${icon} ${c.name}: ${c.message}`;
     }).join("\n");
     const fdaAvailable = hasFullDiskAccess();
-    const fdaLine = fdaAvailable ? "  \u2713 full_disk_access: Granted (Notes database readable \u2014 checklist state, note metadata, note links, sync detail)" : `  \u24D8 full_disk_access: Not granted \u2014 get-checklist-state, get-note-metadata, and the checklist annotations in get-note-markdown won't work; get-note-link fails on macOS 26+ (macOS 12-15 falls back to AppleScript); get-sync-status cannot see pending uploads. The rest of the server is pure AppleScript and is unaffected. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
+    const fdaLine = fdaAvailable ? "  \u2713 full_disk_access: Granted (Notes database readable \u2014 checklist state, note metadata, note links, sync detail)" : "  \u24D8 full_disk_access: Not granted \u2014 get-checklist-state, get-note-metadata, and the checklist annotations in get-note-markdown won't work; get-note-link fails on macOS 26+ (macOS 12-15 falls back to AppleScript); get-sync-status cannot see pending uploads. The rest of the server is pure AppleScript and is unaffected. " + fdaRemediation();
     return successResponse(`${statusIcon} ${statusText}
 
 ${checkLines}
@@ -53887,7 +53953,7 @@ registerTool(
       });
     } catch (error2) {
       if (!(error2 instanceof NotesExportError || error2 instanceof NoteBlocksError)) throw error2;
-      const hint = error2.code === "no-full-disk-access" ? ` Grant Full Disk Access to the app that launches this server: ${FULL_DISK_ACCESS_GUIDE_URL}` : "";
+      const hint = error2.code === "no-full-disk-access" ? ` Grant Full Disk Access to the Node binary running this server (run the doctor tool for its path): ${FULL_DISK_ACCESS_GUIDE_URL}` : "";
       return errorResponse(`Error exporting Markdown [${error2.code}]: ${error2.message}${hint}`);
     }
     const skipped = receipt.skipped.length ? `; skipped ${receipt.skipped.length}` : "";
@@ -53939,7 +54005,7 @@ registerTool(
       });
     } catch (error2) {
       if (!(error2 instanceof NotesExportError || error2 instanceof NoteBlocksError)) throw error2;
-      const hint = error2.code === "no-full-disk-access" ? ` Grant Full Disk Access to the app that launches this server: ${FULL_DISK_ACCESS_GUIDE_URL}` : "";
+      const hint = error2.code === "no-full-disk-access" ? ` Grant Full Disk Access to the Node binary running this server (run the doctor tool for its path): ${FULL_DISK_ACCESS_GUIDE_URL}` : "";
       return errorResponse(`Error exporting HTML [${error2.code}]: ${error2.message}${hint}`);
     }
     const assets = receipt.assets ? `; copied ${receipt.assets.files} asset file(s) to ${receipt.assets.dir}` : `; embedded ${receipt.embedded ?? 0} asset(s)`;

package/docs/FULL-DISK-ACCESS.md

@@ -37,7 +37,7 @@ That database lives in a macOS-protected directory:
 ```
 
 Reading anything under `~/Library/Group Containers/` requires **Full Disk
-Access** for the host process — without it, macOS denies the read. (The MCP only
+Access** for the process that runs the server — without it, macOS denies the read. (The MCP only
 ever **reads** this database; it never writes to it.)
 
 ## How to grant Full Disk Access
@@ -45,21 +45,47 @@ ever **reads** this database; it never writes to it.)
 1. Open **System Settings** (or **System Preferences** on older macOS).
 2. Go to **Privacy & Security → Full Disk Access**.
 3. Click the **+** button (you may need to unlock with Touch ID / your password
-   first), and add the application that **hosts** the MCP server — i.e. the app
-   that actually launches `node`:
-   - **Claude Desktop** → `/Applications/Claude.app`
-   - **Terminal** (if you run Claude Code from a shell) → `/Applications/Utilities/Terminal.app`
-   - **iTerm** → `/Applications/iTerm.app`
+   first) and add the right entry for how you run the server:
+   - **Claude Desktop** → the **Node binary** that runs the server, e.g.
+     `/usr/local/bin/node` or `~/.nvm/versions/node/v24.11.1/bin/node`. The
+     `doctor` tool prints the exact path. In the file picker, press **⌘⇧G** and
+     paste it (use **⌘⇧.** to show hidden folders such as `~/.nvm`). Adding
+     `/Applications/Claude.app` as well does no harm, but on its own it is not
+     enough (see below).
+   - **Claude Code or another client in a terminal** → the terminal app:
+     `/Applications/Utilities/Terminal.app` or `/Applications/iTerm.app`
    - **VS Code** → `/Applications/Visual Studio Code.app`
-4. Make sure the toggle next to the app is **on**.
+4. Make sure the toggle next to the entry is **on**.
 5. **Fully quit and reopen the host app.** macOS only applies the new permission
-   to processes started *after* the change — a reload or restart-server is not
-   enough; the host application itself must be quit (⌘Q) and relaunched.
-
-> **Grant FDA to the right app.** FDA applies to the process that spawns the
-> server, not to `node` or to Notes.app. If you launch Claude Code from iTerm,
-> grant it to iTerm; if you use Claude Desktop, grant it to Claude. Granting it to
-> the wrong app has no effect.
+   to processes started *after* the change. A reload or restart-server is not
+   enough; quit the host application itself (⌘Q) and relaunch it. If `doctor`
+   still reports Full Disk Access as not granted after that, restart the Mac.
+
+> **Why Claude Desktop needs the Node binary itself.** macOS checks Full Disk
+> Access against the *responsible process*, the app it holds accountable for a
+> request. A terminal passes that role on to everything it launches, so a grant
+> on Terminal or iTerm covers the server. Claude Desktop does not: it starts each
+> MCP server through a helper that *disclaims* responsibility, which makes the
+> `node` process its own responsible process. macOS then looks for a grant on the
+> Node binary's path and ignores the one on Claude.app
+> ([#220](https://github.com/sweetrb/apple-notes-mcp/issues/220)).
+>
+> The grant is tied to that exact path. With a version manager (nvm, fnm, Volta,
+> asdf, mise) the path changes with every Node version, so switching versions
+> drops the grant, and `npx` runs whichever `node` is first on the `PATH` Claude
+> Desktop sees. Pointing the config at one fixed Node binary keeps the grant
+> stable:
+>
+> ```json
+> "apple-notes": {
+>   "command": "/Users/you/.nvm/versions/node/v24.11.1/bin/node",
+>   "args": ["/path/to/global/node_modules/apple-notes-mcp/build/index.js"]
+> }
+> ```
+>
+> A Developer-ID-signed Node keeps its grant across updates at the same path;
+> an ad-hoc-signed one (typically Homebrew's) does not. See
+> [Node runtime and TCC permissions](NODE-RUNTIME-AND-TCC-PERMISSIONS.md).
 
 ## Verifying it worked
 

package/package.json

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