apple-notes-mcp 2.8.42 → 2.8.44

package/README.md

@@ -420,7 +420,7 @@ Searches for notes by title or content.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `query` | string | Yes | Text to search for |
-| `searchContent` | boolean | No | If `true`, searches note body; if `false` (default), searches titles only |
+| `searchContent` | boolean | No | If `true`, searches note content (title line included); if `false` (default), searches titles only. With Full Disk Access, content search reads the Notes database (well under a second, the 5000 most recently modified notes, Recently Deleted excluded); without it, it falls back to AppleScript, which scans every body and can time out on a broad term |
 | `account` | string | No | Account to search in (defaults to Notes.app's default account; exact or unique-prefix match) |
 | `folder` | string | No | Limit search to a specific folder (supports nested paths like `"Work/Clients"`) |
 | `modifiedSince` | string | No | ISO 8601 date string to filter notes modified on or after this date (e.g., `"2025-01-01"`) |
@@ -451,7 +451,7 @@ Searches for notes by title or content.
 }
 ```
 
-**Returns:** List of matching notes with titles, folder names, and IDs. Use the returned ID for subsequent operations like `get-note-content`, `update-note`, etc.
+**Returns:** List of matching notes with titles, folder names, and IDs. Use the returned ID for subsequent operations like `get-note-content`, `update-note`, etc. A content search also returns `source` (`"database"` or `"applescript"`), and `scanTruncated` when the database path left older notes unsearched.
 
 ---
 
@@ -763,6 +763,7 @@ Updates an existing note's content and/or title.
 | `newContent` | string | Yes | New content for the note body |
 | `format` | string | No | Content format: `"plaintext"` (default) or `"html"`. When `"html"`, content replaces the entire note body as raw HTML and `newTitle` is ignored (the first HTML element serves as the title) |
 | `allowLinkChanges` | boolean | No | Set to `true` only when intentionally changing or removing existing links |
+| `ifFolderId`, `ifAncestorFolderId`, `forbiddenAncestorFolderIds` | string, string, string[] | No | Folder preconditions; see [Folder scope guards](#folder-scope-guards) |
 
 Title-only updates are rejected because Apple Notes titles are not unique.
 
@@ -807,6 +808,7 @@ Deletes a note (moves to Recently Deleted in Notes.app).
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Exact CoreData note ID returned by a read or search |
 | `expectedContentHash` | string | Yes | `contentHash` from the exact note version being deleted |
+| `ifFolderId`, `ifAncestorFolderId`, `forbiddenAncestorFolderIds` | string, string, string[] | No | Folder preconditions; see [Folder scope guards](#folder-scope-guards) |
 
 Title-only deletion is rejected. If the note changed after the supplied hash
 was read, deletion is also rejected.
@@ -842,6 +844,7 @@ Moves a note to a different folder. The note is relocated in place via Notes.app
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Exact CoreData note ID returned by a read or search |
 | `folder` | string | Yes | Destination folder name or nested path (e.g., `"Work/Clients"`) |
+| `ifFolderId`, `ifAncestorFolderId`, `forbiddenAncestorFolderIds` | string, string, string[] | No | Folder preconditions; see [Folder scope guards](#folder-scope-guards) |
 
 Title-only moves are rejected.
 
@@ -858,6 +861,35 @@ actual destination folder ID matches the requested folder.
 
 ---
 
+#### Folder scope guards
+
+`update-note`, `append-to-note`, `delete-note`, and `move-note` accept three
+optional folder preconditions. Use exact folder ids from `list-folders`.
+
+- `ifFolderId`: the note must currently be in exactly this folder.
+- `ifAncestorFolderId`: the note must be inside this folder or any of its
+  subfolders.
+- `forbiddenAncestorFolderIds` (up to 50): the note must not be inside any of
+  these folders or their subfolders. For `move-note`, the destination must not
+  be either.
+
+The checks read Notes.app's live folders inside the same AppleScript as the
+write, immediately before it, so a note moved after you reviewed it is left
+alone and the call fails with `Scope guard failed: …`. The one exception is a
+native append to a protected note (it runs through Shortcuts): there the check
+is a separate read just before the append, so it is not atomic.
+
+**Example - retire a note only while it is still in the inbox:**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456",
+  "expectedContentHash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "ifFolderId": "x-coredata://ABC123/ICFolder/p12"
+}
+```
+
+---
+
 #### `append-to-note`
 
 Appends or prepends content to an existing note without replacing it. Always reads and writes as HTML, preserving all existing rich formatting.
@@ -870,6 +902,7 @@ Appends or prepends content to an existing note without replacing it. Always rea
 | `position` | string | No | `"after"` (default) appends to the end; `"before"` inserts directly below the note's title line, so the title stays first |
 | `separator` | string | No | String placed between existing content and new content (default: two newlines → `<div><br></div>` in HTML) |
 | `format` | string | No | Format of the content being appended: `"plaintext"` (default) or `"html"` |
+| `ifFolderId`, `ifAncestorFolderId`, `forbiddenAncestorFolderIds` | string, string, string[] | No | Folder preconditions; see [Folder scope guards](#folder-scope-guards) |
 
 Title-only appends are rejected.
 

package/build/index.js

@@ -42053,6 +42053,77 @@ function exportDrawingRaster(drawing, savePath, containerDir = NOTES_CONTAINER_D
   }
 }
 
+// src/utils/scopeGuard.ts
+var SCOPE_FOLDER_ID = /^x-coredata:\/\/[0-9a-f-]+\/ICFolder\/p\d+$/i;
+var MAX_FORBIDDEN_FOLDERS = 50;
+var SCOPE_MARKER = "SAFETY_SCOPE";
+function hasScopeGuard(guard) {
+  return Boolean(
+    guard && (guard.ifFolderId || guard.ifAncestorFolderId || guard.forbiddenAncestorFolderIds && guard.forbiddenAncestorFolderIds.length > 0)
+  );
+}
+function validateScopeGuard(guard) {
+  const ids = [
+    guard.ifFolderId,
+    guard.ifAncestorFolderId,
+    ...guard.forbiddenAncestorFolderIds ?? []
+  ].filter((value) => value !== void 0);
+  for (const id2 of ids) {
+    if (!SCOPE_FOLDER_ID.test(id2)) throw new Error(`Scope guard needs exact folder ids: ${id2}`);
+  }
+  if ((guard.forbiddenAncestorFolderIds?.length ?? 0) > MAX_FORBIDDEN_FOLDERS)
+    throw new Error(`At most ${MAX_FORBIDDEN_FOLDERS} forbidden folder ids are allowed`);
+}
+function chainScript(chainVar, startExpr) {
+  return `
+      set ${chainVar} to {}
+      set ${chainVar}Cursor to ${startExpr}
+      repeat while class of ${chainVar}Cursor is folder
+        set end of ${chainVar} to (id of ${chainVar}Cursor)
+        set ${chainVar}Cursor to container of ${chainVar}Cursor
+      end repeat`;
+}
+function idList(ids) {
+  return `{${ids.map((id2) => `"${id2}"`).join(", ")}}`;
+}
+function buildScopeGuardScript(noteVar, guard, destinationVar) {
+  if (!hasScopeGuard(guard)) return "";
+  validateScopeGuard(guard);
+  const forbidden = guard.forbiddenAncestorFolderIds ?? [];
+  let script = `
+      set scopeFolder to container of ${noteVar}
+      if class of scopeFolder is not folder then return "${SCOPE_MARKER}:the note is not in a folder"`;
+  if (guard.ifFolderId)
+    script += `
+      if (id of scopeFolder) is not "${guard.ifFolderId}" then return "${SCOPE_MARKER}:the note is not in the expected folder"`;
+  if (guard.ifAncestorFolderId || forbidden.length > 0)
+    script += chainScript("scopeChain", "scopeFolder");
+  if (guard.ifAncestorFolderId)
+    script += `
+      if scopeChain does not contain "${guard.ifAncestorFolderId}" then return "${SCOPE_MARKER}:the note is not inside the expected ancestor folder"`;
+  if (forbidden.length > 0) {
+    script += `
+      repeat with forbiddenId in ${idList(forbidden)}
+        if scopeChain contains (contents of forbiddenId) then return "${SCOPE_MARKER}:the note is inside a forbidden folder"
+      end repeat`;
+    if (destinationVar) {
+      script += chainScript("scopeDestChain", destinationVar);
+      script += `
+      repeat with forbiddenId in ${idList(forbidden)}
+        if scopeDestChain contains (contents of forbiddenId) then return "${SCOPE_MARKER}:the destination is inside a forbidden folder"
+      end repeat`;
+    }
+  }
+  return script;
+}
+function parseScopeFailure(output) {
+  const trimmed = output.trim();
+  return trimmed.startsWith(`${SCOPE_MARKER}:`) ? trimmed.slice(SCOPE_MARKER.length + 1) : null;
+}
+function scopeConflictMessage(reason) {
+  return `Scope guard failed: ${reason}. Nothing was changed; read the note's current folder and review before retrying.`;
+}
+
 // src/services/appleNotesManager.ts
 var import_turndown = __toESM(require_turndown_cjs(), 1);
 import { existsSync as existsSync5 } from "fs";
@@ -42373,6 +42444,16 @@ var AppleNotesManager = class {
     }
     return this.defaultAccountName || void 0;
   }
+  /**
+   * The account a search with this `account` argument is scoped to: the
+   * caller's account when named, else Notes.app's default account (cached).
+   * Returns `undefined` when no account was named and the default cannot be
+   * determined. Used by search-notes' database path so it searches the same
+   * account the AppleScript path would.
+   */
+  searchAccountScope(account) {
+    return this.reportedAccount(this.resolveAccount(account));
+  }
   /**
    * Checks if a note is password-protected by its ID.
    *
@@ -42816,7 +42897,7 @@ var AppleNotesManager = class {
    * race that would exist if JavaScript checked the note and then issued a
    * separate unconditional `set body` command.
    */
-  updateNoteByIdIfUnchanged(id2, currentTitle, expectedBody, newTitle, newContent, format = "plaintext", expectedRichRevision) {
+  updateNoteByIdIfUnchanged(id2, currentTitle, expectedBody, newTitle, newContent, format = "plaintext", expectedRichRevision, scope2) {
     const safeId = sanitizeNoteId(id2);
     if (expectedRichRevision) {
       const rich = readRichNote(id2);
@@ -42837,7 +42918,7 @@ var AppleNotesManager = class {
     const safeExpectedBody = escapeHtmlForAppleScript(expectedBody);
     const safeWrittenBody = escapeHtmlForAppleScript(writtenBody);
     const script = buildAppLevelScript(`
-      set noteRef to note id "${safeId}"
+      set noteRef to note id "${safeId}"${buildScopeGuardScript("noteRef", scope2)}
       if (count of attachments of noteRef) is greater than 0 then return "SAFETY_ATTACHMENTS"
       set currentBody to body of noteRef
       considering case
@@ -42851,6 +42932,8 @@ var AppleNotesManager = class {
       console.error(`Failed guarded update for note ID "${id2}":`, result.error);
       return { status: "failed" };
     }
+    const updateScopeFailure = parseScopeFailure(result.output);
+    if (updateScopeFailure) return { status: "scope_conflict", reason: updateScopeFailure };
     const status = result.output.trim();
     if (status === "SAFETY_CONFLICT") return { status: "conflict" };
     if (status === "SAFETY_ATTACHMENTS") return { status: "attachments" };
@@ -42862,12 +42945,12 @@ var AppleNotesManager = class {
    * the caller reviewed. The comparison and delete are one AppleScript action,
    * so a concurrent edit cannot slip between the guard and deletion.
    */
-  deleteNoteByIdIfUnchanged(id2, expectedBody) {
+  deleteNoteByIdIfUnchanged(id2, expectedBody, scope2) {
     const safeId = sanitizeNoteId(id2);
     validateLength(expectedBody, MAX_CONTENT_LENGTH, "Expected note content");
     const safeExpectedBody = escapeHtmlForAppleScript(expectedBody);
     const script = buildAppLevelScript(`
-      set noteRef to note id "${safeId}"
+      set noteRef to note id "${safeId}"${buildScopeGuardScript("noteRef", scope2)}
       set originalFolder to missing value
       try
         set originalFolder to container of noteRef
@@ -42899,12 +42982,31 @@ var AppleNotesManager = class {
       console.error(`Failed guarded delete for note ID "${id2}":`, result.error);
       return { status: "failed" };
     }
+    const deleteScopeFailure = parseScopeFailure(result.output);
+    if (deleteScopeFailure) return { status: "scope_conflict", reason: deleteScopeFailure };
     const status = result.output.trim();
     if (status === "SAFETY_CONFLICT") return { status: "conflict" };
     if (status === "SAFETY_IN_RECENTLY_DELETED") return { status: "in-recently-deleted" };
     if (status === "SAFETY_NOT_DELETED") return { status: "not-deleted" };
     return status === "SAFETY_DELETED" ? { status: "deleted" } : { status: "failed" };
   }
+  /**
+   * Read-only scope pre-check for writes that do not run as AppleScript (the
+   * native Shortcuts operations). Runs the same checks the AppleScript writes
+   * embed, but in a separate script, so it is not atomic with the write.
+   *
+   * @returns null when every precondition holds, otherwise the failure reason
+   */
+  checkNoteScope(id2, scope2) {
+    const safeId = sanitizeNoteId(id2);
+    const result = executeAppleScript(
+      buildAppLevelScript(`
+      set noteRef to note id "${safeId}"${buildScopeGuardScript("noteRef", scope2)}
+      return "SCOPE_OK"`)
+    );
+    if (!result.success) return result.error || "the note's folder could not be read";
+    return parseScopeFailure(result.output);
+  }
   /**
    * Builds the AppleScript body for a bulk note listing.
    *
@@ -43491,14 +43593,14 @@ var AppleNotesManager = class {
    * @param account - Account containing the destination folder (defaults to Notes.app's default account)
    * @returns true if the move succeeded, false otherwise
    */
-  moveNoteById(id2, destinationFolder, account) {
+  moveNoteById(id2, destinationFolder, account, scope2) {
     const targetAccount = this.resolveAccount(account);
     const safeId = sanitizeNoteId(id2);
     const destFolderRef = `${buildFolderReference(destinationFolder)} of ${AS_ACCOUNT_REF}`;
     const moveCommand = `
       ${buildAccountResolution(targetAccount)}
       set destFolder to ${destFolderRef}
-      set noteRef to note id "${safeId}"
+      set noteRef to note id "${safeId}"${buildScopeGuardScript("noteRef", scope2, "destFolder")}
       move noteRef to destFolder
       set movedNoteRef to note id "${safeId}"
       set actualFolder to container of movedNoteRef
@@ -43515,6 +43617,8 @@ var AppleNotesManager = class {
       );
       return false;
     }
+    const scopeFailure = parseScopeFailure(result.output);
+    if (scopeFailure) throw new Error(scopeConflictMessage(scopeFailure));
     if (result.output.trim() !== "SAFETY_MOVED") {
       console.error(
         `Move result for note ID "${id2}" did not verify destination "${destinationFolder}"`
@@ -44416,12 +44520,12 @@ var AppleNotesManager = class {
       }
     });
     if (runnable.length > 0) {
-      const idList = runnable.map((r) => `"${r.safe}"`).join(", ");
+      const idList2 = runnable.map((r) => `"${r.safe}"`).join(", ");
       const script = buildAppLevelScript(`
         ${buildAccountResolution(targetAccount)}
         set destFolder to ${destFolderRef}
         set out to ""
-        repeat with rawId in {${idList}}
+        repeat with rawId in {${idList2}}
           set theId to (rawId as text)
           set noteRef to missing value
           try
@@ -45681,6 +45785,13 @@ function describeSearchScope(searchContent, resultCount) {
   return "\n\n\u2139\uFE0F Only note titles were searched, so a term that appears in note bodies would not match. Retry with `searchContent: true` to search bodies instead.";
 }
 
+// src/utils/noteQueryStore.ts
+import { execFileSync as execFileSync13 } from "child_process";
+import * as fs8 from "fs";
+import * as os8 from "os";
+import * as path8 from "path";
+import { gunzipSync as gunzipSync7 } from "zlib";
+
 // src/utils/noteQuery.ts
 var QUERY_LIMITS = {
   /** Maximum number of tokens (terms, operators, parentheses). */
@@ -46127,11 +46238,6 @@ function positiveTextTerms(node, negated = false) {
 }
 
 // src/utils/noteQueryStore.ts
-import { execFileSync as execFileSync13 } from "child_process";
-import * as fs8 from "fs";
-import * as os8 from "os";
-import * as path8 from "path";
-import { gunzipSync as gunzipSync7 } from "zlib";
 var NOTES_DB_PATH9 = path8.join(
   os8.homedir(),
   "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
@@ -46327,7 +46433,13 @@ function buildSnippet(text2, terms) {
 }
 function queryNotes(expression, options = {}) {
   const ast = parseNoteQuery(expression);
-  const limit = Math.min(options.limit ?? QUERY_RESULTS.DEFAULT, QUERY_RESULTS.MAX);
+  return runNoteQuery(ast, {
+    ...options,
+    limit: Math.min(options.limit ?? QUERY_RESULTS.DEFAULT, QUERY_RESULTS.MAX)
+  });
+}
+function runNoteQuery(ast, options = {}) {
+  const limit = options.limit ?? QUERY_RESULTS.DEFAULT;
   const scanLimit = Math.min(options.scanLimit ?? QUERY_SCAN.DEFAULT, QUERY_SCAN.MAX);
   const includeDeleted = options.includeDeleted ?? false;
   const withBodies = needsContent(ast);
@@ -46464,6 +46576,66 @@ function queryNotes(expression, options = {}) {
   };
 }
 
+// src/utils/searchContentDb.ts
+function buildSearchContentQuery(options) {
+  const children = [{ type: "text", field: "any", value: options.query }];
+  const folder = options.folder?.trim();
+  if (folder) children.push({ type: "folder", value: folder });
+  const account = options.account?.trim();
+  if (account) children.push({ type: "account", value: account });
+  if (options.modifiedSince) {
+    const start = new Date(options.modifiedSince).getTime();
+    if (Number.isFinite(start)) {
+      children.push({
+        type: "date",
+        field: "modified",
+        op: ">=",
+        date: options.modifiedSince,
+        start,
+        end: start + 24 * 60 * 60 * 1e3
+      });
+    }
+  }
+  return children.length === 1 ? children[0] : { type: "and", children };
+}
+function searchContentViaDatabase(options) {
+  const result = runNoteQuery(buildSearchContentQuery(options), {
+    limit: options.limit,
+    scanLimit: QUERY_SCAN.MAX,
+    dbPath: options.dbPath
+  });
+  const notes = result.notes.map((hit) => ({
+    id: hit.id,
+    title: hit.title,
+    content: "",
+    tags: [],
+    created: hit.created ? new Date(hit.created) : /* @__PURE__ */ new Date(0),
+    modified: hit.modified ? new Date(hit.modified) : /* @__PURE__ */ new Date(0),
+    ...hit.folder !== void 0 ? { folder: hit.folder } : {},
+    ...hit.account !== void 0 ? { account: hit.account } : {}
+  }));
+  return {
+    notes,
+    scan: {
+      scanned: result.scanned,
+      eligible: result.eligible,
+      scanTruncated: result.scanTruncated,
+      matched: result.matched
+    }
+  };
+}
+function describeContentScan(scan) {
+  if (!scan?.scanTruncated) return "";
+  return `
+
+\u2139\uFE0F Searched the ${scan.scanned} most recently modified of ${scan.eligible} notes; older notes were not searched. A title search (\`searchContent: false\`) covers every note.`;
+}
+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." : "";
+  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.`;
+}
+
 // src/tools/doctor.ts
 import { spawnSync } from "child_process";
 
@@ -50801,6 +50973,36 @@ function noteIdentifiers(id2) {
 var expectedContentHashInput = external_exports.string().regex(/^sha256:[a-f0-9]{64}$/, "expectedContentHash must come from get-note-content").describe(
   "Revision token returned by get-note-content for this exact ID. The mutation stops if the note changed since that read."
 );
+var SCOPE_FOLDER_ID_MESSAGE = "An exact folder id is required: x-coredata://.../ICFolder/p..., Notes UUID, or numeric key (from list-folders)";
+var scopeFolderIdInput = exactIdInput("ICFolder", SCOPE_FOLDER_ID, SCOPE_FOLDER_ID_MESSAGE, {
+  maxLength: MAX.ID
+});
+var scopeGuardInputs = {
+  ifFolderId: scopeFolderIdInput.optional().describe(
+    "Precondition: the note must currently be in exactly this folder (id from list-folders). Re-checked immediately before the write."
+  ),
+  ifAncestorFolderId: scopeFolderIdInput.optional().describe(
+    "Precondition: the note must be inside this folder or any of its subfolders. Re-checked immediately before the write."
+  ),
+  forbiddenAncestorFolderIds: exactIdArrayInput(
+    "ICFolder",
+    SCOPE_FOLDER_ID,
+    SCOPE_FOLDER_ID_MESSAGE,
+    {
+      maxLength: MAX.ID,
+      maxItems: MAX_FORBIDDEN_FOLDERS
+    }
+  ).optional().describe(
+    "Precondition: the note must not be inside any of these folders or their subfolders (for move-note, neither may the destination). Re-checked immediately before the write."
+  )
+};
+function scopeFrom(args) {
+  return {
+    ifFolderId: args.ifFolderId,
+    ifAncestorFolderId: args.ifAncestorFolderId,
+    forbiddenAncestorFolderIds: args.forbiddenAncestorFolderIds
+  };
+}
 var timeoutSecondsInput = external_exports.number().int().min(CALL_TIMEOUT_SECONDS.min).max(CALL_TIMEOUT_SECONDS.max).optional().describe(
   `Per-call timeout in seconds (${CALL_TIMEOUT_SECONDS.min}-${CALL_TIMEOUT_SECONDS.max}) for each Notes.app automation step this call runs, overriding APPLE_NOTES_MCP_TIMEOUT_MS. A timed-out write is uncertain, not failed: read the note by id before any retry.`
 );
@@ -50981,10 +51183,12 @@ registerTool(
 registerTool(
   "search-notes",
   {
-    description: "Use when: finding notes by a keyword in the title (or body with searchContent=true) and you need their ids.\nReturns: matching notes with title, folder, and id.\nDo not use when: you already have a note id (use get-note-content) or want every note (use list-notes).\nPrefer this first to obtain ids for subsequent read/update/delete/move calls.",
+    description: "Use when: finding notes by a keyword in the title (or body with searchContent=true) and you need their ids.\nReturns: matching notes with title, folder, and id; `source` says whether a body search read the Notes database or fell back to AppleScript.\nDo not use when: you already have a note id (use get-note-content), want every note (use list-notes), or need boolean or metadata filters (use query-notes).\nPrefer this first to obtain ids for subsequent read/update/delete/move calls.\nNote: with Full Disk Access, body search reads the Notes database (fast; the most recent 5000 notes, Recently Deleted excluded); without it, it falls back to AppleScript, which scans every body and can time out on broad terms.",
     inputSchema: {
       query: external_exports.string().min(1, "Search query is required").max(MAX.QUERY),
-      searchContent: external_exports.boolean().optional().describe("Search note content instead of titles"),
+      searchContent: external_exports.boolean().optional().describe(
+        "Search note content (title line included) instead of titles. Uses the Notes database when Full Disk Access is available, else AppleScript"
+      ),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account to search in"),
       folder: external_exports.string().max(MAX.FOLDER).optional().describe("Limit search to a specific folder"),
       modifiedSince: external_exports.string().max(64).optional().describe(
@@ -50996,21 +51200,59 @@ registerTool(
     },
     outputSchema: {
       notes: external_exports.array(external_exports.object({}).passthrough()).optional(),
-      count: external_exports.number().optional()
+      count: external_exports.number().optional(),
+      source: external_exports.enum(["database", "applescript"]).optional(),
+      scanTruncated: external_exports.boolean().optional()
     }
   },
   withErrorHandling(({ query: query2, searchContent = false, account, folder, modifiedSince, limit }) => {
     const effectiveLimit = resolveSearchLimit(limit);
     const limitWasDefault = limit === void 0;
+    let source;
+    let dbScan;
+    let dbUnavailable;
+    const runSearch = () => {
+      if (searchContent) {
+        try {
+          const db = searchContentViaDatabase({
+            query: query2,
+            account: notesManager.searchAccountScope(account),
+            folder,
+            modifiedSince,
+            limit: effectiveLimit
+          });
+          source = "database";
+          dbScan = db.scan;
+          return db.notes;
+        } catch (error2) {
+          if (!(error2 instanceof NoteQueryStoreError)) throw error2;
+          dbUnavailable = error2.kind;
+        }
+        source = "applescript";
+      }
+      try {
+        return notesManager.searchNotes(
+          query2,
+          searchContent,
+          account,
+          folder,
+          modifiedSince,
+          effectiveLimit
+        );
+      } catch (error2) {
+        if (!searchContent || !(error2 instanceof Error)) throw error2;
+        throw new Error(contentSearchFailureHint(error2.message, dbUnavailable));
+      }
+    };
     const {
       result: notes,
       syncBefore,
       syncInterference
-    } = withSyncAwarenessSync(
-      "search-notes",
-      () => notesManager.searchNotes(query2, searchContent, account, folder, modifiedSince, effectiveLimit)
-    );
-    const searchType = searchContent ? "content" : "titles";
+    } = withSyncAwarenessSync("search-notes", runSearch);
+    const searchType = searchContent ? source === "database" ? "content via the Notes database" : "content" : "titles";
+    const sourceFields = source ? { source } : {};
+    const scanFields = dbScan ? { scanTruncated: dbScan.scanTruncated } : {};
+    const scanNote = describeContentScan(dbScan);
     const folderInfo = folder ? ` in folder "${folder}"` : "";
     const dateInfo = modifiedSince ? ` modified since ${modifiedSince}` : "";
     const { info: limitInfo, truncationNote } = describeSearchLimit(
@@ -51031,8 +51273,8 @@ ${syncWarnings.join(" ")}` : "";
     if (notes.length === 0) {
       const scopeHint = describeSearchScope(searchContent, notes.length);
       return successResponse(
-        `No notes found matching "${query2}" in ${searchType}${folderInfo}${dateInfo}${scopeHint}${syncNote}`,
-        { notes: [], count: 0 }
+        `No notes found matching "${query2}" in ${searchType}${folderInfo}${dateInfo}${scopeHint}${scanNote}${syncNote}`,
+        { notes: [], count: 0, ...sourceFields, ...scanFields }
       );
     }
     const noteList = notes.map((n) => {
@@ -51046,8 +51288,13 @@ ${syncWarnings.join(" ")}` : "";
     }).join("\n");
     return successResponse(
       `Found ${notes.length} notes (searched ${searchType}${folderInfo}${dateInfo}${limitInfo}):
-${noteList}${truncationNote}${syncNote}`,
-      { notes: withStableIdentifiers(notes, "ICNote"), count: notes.length }
+${noteList}${truncationNote}${scanNote}${syncNote}`,
+      {
+        notes: withStableIdentifiers(notes, "ICNote"),
+        count: notes.length,
+        ...sourceFields,
+        ...scanFields
+      }
     );
   }, "Error searching notes")
 );
@@ -51682,7 +51929,7 @@ ${lines.join("\n")}` : ".") + partial2,
 registerTool(
   "update-note",
   {
-    description: "Use when: replacing the body of one exact Apple Note after reading it by id.\nReturns: exact id, new content hash, and visible-text readback verification.\nDo not use when: you only have a title, the note changed since the read, or the note has attachments.\nSafety: requires the exact note id and expectedContentHash from get-note-content. The server checks rich metadata revision, atomically checks the AppleScript body, blocks native objects/checklists, and verifies actual link destinations after saving. Preserve returned HTML links unless allowLinkChanges is explicitly requested. Notes.app normalizes HTML, so rich formatting is not claimed as byte-identical.",
+    description: "Use when: replacing the body of one exact Apple Note after reading it by id.\nReturns: exact id, new content hash, and visible-text readback verification.\nDo not use when: you only have a title, the note changed since the read, or the note has attachments.\nSafety: requires the exact note id and expectedContentHash from get-note-content. The server checks rich metadata revision, atomically checks the AppleScript body, blocks native objects/checklists, and verifies actual link destinations after saving. Optional ifFolderId, ifAncestorFolderId, and forbiddenAncestorFolderIds are re-checked inside the same AppleScript as the write. Preserve returned HTML links unless allowLinkChanges is explicitly requested. Notes.app normalizes HTML, so rich formatting is not claimed as byte-identical.",
     inputSchema: {
       id: noteIdInput,
       expectedContentHash: expectedContentHashInput,
@@ -51696,7 +51943,8 @@ registerTool(
         "New note body. AppleScript cannot produce true Apple Notes checklists; checkbox inputs and `- [ ]` markdown do not render as checkable items. Use a plain list and convert in Notes.app with \u21E7\u2318L."
       ),
       format: external_exports.enum(["plaintext", "html"]).optional().default("plaintext").describe("Content format: 'plaintext' (default) or 'html' for rich formatting"),
-      timeoutSeconds: timeoutSecondsInput
+      timeoutSeconds: timeoutSecondsInput,
+      ...scopeGuardInputs
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -51715,7 +51963,8 @@ registerTool(
       newTitle,
       newContent,
       format = "plaintext",
-      allowLinkChanges = false
+      allowLinkChanges = false,
+      ...scopeArgs
     }) => {
       const snapshot = readExactNoteSnapshot(id2);
       if ("error" in snapshot) return errorResponse(snapshot.error);
@@ -51736,11 +51985,15 @@ registerTool(
         newTitle,
         newContent,
         format,
-        snapshot.rich.revision
+        snapshot.rich.revision,
+        scopeFrom(scopeArgs)
       );
       if (result.status === "conflict") {
         return errorResponse(revisionConflictMessage(snapshot.note.title));
       }
+      if (result.status === "scope_conflict") {
+        return errorResponse(scopeConflictMessage(result.reason));
+      }
       if (result.status === "attachments") {
         return errorResponse(
           `Note "${snapshot.note.title}" gained an attachment before saving. No content was replaced.`
@@ -51796,7 +52049,8 @@ function guardedAppend({
   separator = "\n\n",
   format = "plaintext",
   scopeText,
-  htmlSeparator
+  htmlSeparator,
+  ...scopeArgs
 }, onRoute) {
   const contentToHtml = (text2) => {
     if (format === "html") return text2;
@@ -51824,6 +52078,11 @@ function guardedAppend({
       return errorResponse("Provide scopeText: a unique existing phrase for native append");
     if (!VERIFIED_BACKGROUND.has("append-native"))
       return errorResponse("Native append has not passed live validation; see get-capabilities");
+    const nativeScope = scopeFrom(scopeArgs);
+    if (hasScopeGuard(nativeScope)) {
+      const reason = notesManager.checkNoteScope(id2, nativeScope);
+      if (reason) return errorResponse(scopeConflictMessage(reason));
+    }
     onRoute?.("native");
     const result2 = appendNative(notesManager, {
       id: id2,
@@ -51855,11 +52114,15 @@ function guardedAppend({
     void 0,
     combinedBody,
     "html",
-    snapshot.rich.revision
+    snapshot.rich.revision,
+    scopeFrom(scopeArgs)
   );
   if (result.status === "conflict") {
     return errorResponse(revisionConflictMessage(snapshot.note.title));
   }
+  if (result.status === "scope_conflict") {
+    return errorResponse(scopeConflictMessage(result.reason));
+  }
   if (result.status === "attachments") {
     return errorResponse(
       `Note "${snapshot.note.title}" gained an attachment before saving. No content was appended.`
@@ -51900,7 +52163,7 @@ function guardedAppend({
 registerTool(
   "append-to-note",
   {
-    description: "Use when: adding content to one exact note after reading it by id.\nReturns: exact id, new content hash, and visible-text readback verification.\nDo not use when: you only have a title or the note changed since the read.\nSafety: protected native-object notes use native end-append with scopeText; ordinary notes retain guarded HTML editing. Notes.app normalizes HTML, so rich formatting is not claimed as byte-identical.\nNative-append HTML subset (protected notes only; ordinary notes accept any HTML Notes.app renders): " + NATIVE_APPEND_HTML_SUBSET + " Native append also requires scopeText, the default blank-line separator and position 'after'.",
+    description: "Use when: adding content to one exact note after reading it by id.\nReturns: exact id, new content hash, and visible-text readback verification.\nDo not use when: you only have a title or the note changed since the read.\nSafety: protected native-object notes use native end-append with scopeText; ordinary notes retain guarded HTML editing. Optional ifFolderId, ifAncestorFolderId, and forbiddenAncestorFolderIds are re-checked inside the write AppleScript for ordinary notes, and as a separate read just before a native append. Notes.app normalizes HTML, so rich formatting is not claimed as byte-identical.\nNative-append HTML subset (protected notes only; ordinary notes accept any HTML Notes.app renders): " + NATIVE_APPEND_HTML_SUBSET + " Native append also requires scopeText, the default blank-line separator and position 'after'.",
     inputSchema: {
       id: noteIdInput,
       expectedContentHash: expectedContentHashInput,
@@ -51911,7 +52174,8 @@ registerTool(
       ),
       separator: external_exports.string().max(20).optional().default("\n\n").describe("String placed between existing content and new content (default: two newlines)"),
       format: external_exports.enum(["plaintext", "html"]).optional().default("plaintext").describe("Format of the content being appended: 'plaintext' (default) or 'html'"),
-      timeoutSeconds: timeoutSecondsInput
+      timeoutSeconds: timeoutSecondsInput,
+      ...scopeGuardInputs
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -51997,11 +52261,12 @@ registerTool(
 registerTool(
   "delete-note",
   {
-    description: "Use when: moving one exact note to Recently Deleted after reading and reviewing it.\nReturns: confirmation with the exact id.\nDo not use when: you only have a title or the note changed since review.\nSafety: requires id and expectedContentHash from get-note-content. The body comparison and delete happen in one AppleScript, so a newer edit is preserved. Refuses a note already in Recently Deleted, where a delete would be permanent.",
+    description: "Use when: moving one exact note to Recently Deleted after reading and reviewing it.\nReturns: confirmation with the exact id.\nDo not use when: you only have a title or the note changed since review.\nSafety: requires id and expectedContentHash from get-note-content. The body comparison and delete happen in one AppleScript, so a newer edit is preserved. Refuses a note already in Recently Deleted, where a delete would be permanent. Optional ifFolderId, ifAncestorFolderId, and forbiddenAncestorFolderIds are re-checked inside that AppleScript too.",
     inputSchema: {
       id: noteIdInput,
       expectedContentHash: expectedContentHashInput,
-      timeoutSeconds: timeoutSecondsInput
+      timeoutSeconds: timeoutSecondsInput,
+      ...scopeGuardInputs
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -52011,16 +52276,19 @@ registerTool(
       previousContentHash: external_exports.string().optional()
     }
   },
-  withErrorHandling(({ id: id2, expectedContentHash }) => {
+  withErrorHandling(({ id: id2, expectedContentHash, ...scopeArgs }) => {
     const snapshot = readExactNoteSnapshot(id2);
     if ("error" in snapshot) return errorResponse(snapshot.error);
     if (snapshot.contentHash !== expectedContentHash) {
       return errorResponse(revisionConflictMessage(snapshot.note.title));
     }
-    const result = notesManager.deleteNoteByIdIfUnchanged(id2, snapshot.body);
+    const result = notesManager.deleteNoteByIdIfUnchanged(id2, snapshot.body, scopeFrom(scopeArgs));
     if (result.status === "conflict") {
       return errorResponse(revisionConflictMessage(snapshot.note.title));
     }
+    if (result.status === "scope_conflict") {
+      return errorResponse(scopeConflictMessage(result.reason));
+    }
     if (result.status === "in-recently-deleted") {
       return errorResponse(inRecentlyDeletedMessage(snapshot.note.title));
     }
@@ -52048,12 +52316,13 @@ registerTool(
 registerTool(
   "move-note",
   {
-    description: "Use when: moving one exact note to a different folder by id.\nReturns: confirmation and exact-ID readback.\nDo not use when: you only have a title or want to move many notes (batch-move-notes).\nNote: Notes.app's native move preserves the note id, creation date, body, and attachments. The destination folder must already exist.",
+    description: "Use when: moving one exact note to a different folder by id.\nReturns: confirmation and exact-ID readback.\nDo not use when: you only have a title or want to move many notes (batch-move-notes).\nNote: Notes.app's native move preserves the note id, creation date, body, and attachments. The destination folder must already exist. Optional ifFolderId, ifAncestorFolderId, and forbiddenAncestorFolderIds (which also covers the destination) are re-checked inside the move AppleScript.",
     inputSchema: {
       id: noteIdInput,
       folder: external_exports.string().min(1, "Destination folder is required").max(MAX.FOLDER),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account containing the note/folder"),
-      timeoutSeconds: timeoutSecondsInput
+      timeoutSeconds: timeoutSecondsInput,
+      ...scopeGuardInputs
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -52063,12 +52332,12 @@ registerTool(
       verified: external_exports.boolean().optional()
     }
   },
-  withErrorHandling(({ id: id2, folder, account }) => {
+  withErrorHandling(({ id: id2, folder, account, ...scopeArgs }) => {
     const note = notesManager.getNoteById(id2);
     if (!note) {
       return errorResponse(`Note with ID "${id2}" not found`);
     }
-    const success = notesManager.moveNoteById(id2, folder, account);
+    const success = notesManager.moveNoteById(id2, folder, account, scopeFrom(scopeArgs));
     if (!success) {
       return errorResponse(
         `Failed to move note "${note.title}" to folder "${folder}". Folder may not exist.`

package/package.json

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