apple-notes-mcp 2.8.43 → 2.8.45

package/README.md

@@ -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.
 
@@ -1145,11 +1178,12 @@ 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. The
-`id` may also be the folder's Notes UUID or numeric key, and the result adds
-`identifier`, `parentIdentifier`, and `accountIdentifier` when Full Disk Access
-is granted.
+Reads one exact folder's current name, parent ID, and account ID (`accountId`,
+plus `isRoot`, true when the folder sits at the account root). Use these values
+with `rename-folder` or `delete-folder-by-id`; this avoids relying on ambiguous
+folder names or paths. The `id` may also be the folder's Notes UUID or numeric
+key, and the result adds `identifier`, `parentIdentifier`, and
+`accountIdentifier` when Full Disk Access is granted.
 
 ---
 
@@ -1161,6 +1195,54 @@ and descendants. It refuses stale metadata and a conflicting sibling name.
 
 ---
 
+#### `delete-folder-by-id`
+
+Deletes one exact, empty, ordinary folder through a plan-then-apply handshake.
+Read the folder first with `get-folder-by-id`, call once with `dryRun: true`,
+then repeat the same guards with `dryRun: false` and the returned `revision`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Exact folder id (`x-coredata://…/ICFolder/pN`), or the folder's Notes UUID or numeric key |
+| `expectedName` | string | Yes | Current folder name (not a path), matched case-sensitively |
+| `expectedAccountId` | string | Yes | Owning account id (`x-coredata://…/ICAccount/pN`) |
+| `expectedParentId` | string | One of these two | Current parent folder id (same forms as `id`) |
+| `expectedRoot` | `true` | One of these two | The folder sits at the account root |
+| `dryRun` | boolean | Yes | `true` plans; `false` applies |
+| `expectedRevision` | string | On apply | The `revision` from the dry run |
+
+**Example (plan, then apply with the returned revision):**
+```json
+{
+  "id": "x-coredata://ABC/ICFolder/p42",
+  "expectedName": "Old Projects",
+  "expectedAccountId": "x-coredata://ABC/ICAccount/p3",
+  "expectedRoot": true,
+  "dryRun": true
+}
+```
+
+**Returns:** `status: "planned"` with `wouldDelete`, `identifier`, `name`,
+`accountId`, `parentId`, `folderType: 0`, zero `childFolderCount` and
+`noteCount`, and `revision`; on apply, `status: "deleted"`, `committed: true`,
+`verified: true` (Notes.app no longer resolves the id), and `storeTombstoned`.
+
+**Safety:** it always refuses Recently Deleted, smart folders, the account's
+default and other system folders, shared folders (or folders inside a shared
+folder), and any folder that still holds notes or subfolders. There is no
+override. It is **not atomic**: the guard is a pre-check followed by an
+AppleScript delete. The name, parent, account, sharing, and emptiness checks
+repeat inside the delete script, but the folder type and stable identifier come
+from the local Notes database just before it. It needs Full Disk Access and
+fails closed without it.
+
+**Errors** carry the standard `code`: `revision_conflict` (a `Conflict:` message;
+read and plan again), `unsupported` (a `Refused:` message), `verification_failed`
+with `indeterminate: true` (read the folder before any retry), and
+`full_disk_access_missing`.
+
+---
+
 #### `delete-folder`
 
 Deletes a folder.