apple-notes-mcp 2.9.24 → 2.9.26

package/README.md

@@ -261,8 +261,10 @@ Two optional booleans describe a write's outcome when it is known.
 id before any retry, and never retry blindly. `committed: true` means the write
 took effect even though its verification failed; `committed: false` means
 nothing was written (for example a `revision_conflict`). An absent flag means
-unknown. Errors the MCP SDK raises itself before a tool runs, such as an
-argument that fails the input schema, carry no `structuredContent`.
+unknown. An argument that fails the input schema is rejected before the tool
+runs, with `code: "validation_error"` and `committed: false`. The exception is
+a Notes UUID or numeric key that could not be resolved to an id: it carries
+`not_found`, or `full_disk_access_missing` when the database is unreadable.
 
 ### Note Operations
 
@@ -2060,7 +2062,7 @@ success, with no read cap below the 64 MiB write limit.
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Exact CoreData note ID |
 | `expectedContentHash` | string | Yes | `contentHash` from the note version being extended |
-| `path` | string | Yes | Absolute path of the local file; symbolic links are refused |
+| `path` | string | Yes | Absolute path of the local file. Read under the same rules as `create-note`'s [`contentPath`](#create-note): home, temp or `/Volumes` only; hidden paths (any component starting with `.`, such as `~/.ssh` or a project `.env`) and `~/Library` other than iCloud Drive (`~/Library/Mobile Documents`) and `~/Library/CloudStorage` are refused, checked again after resolving symbolic links and letter case, unless the server sets `APPLE_NOTES_MCP_ALLOW_PRIVATE_CONTENT_PATHS=1`. Symbolic links and anything but a regular file (a FIFO, a device) are refused |
 | `filename` | string | No | Name the attachment gets in Notes instead of the source file's name. One path component that keeps the source file's extension, with no slash, colon, backslash, control character, leading dot or surrounding spaces. Notes names a file attachment after the file it receives, so the server gives its private temporary copy this name |
 
 **Returns:** `attachmentId`, `bytes`, the `name` Notes reports, and the new
@@ -2091,7 +2093,7 @@ same verification as [`add-attachment`](#add-attachment).
 | `content` | string | No | Plain-text body placed above the attachment |
 | `folder` | string | No | Existing folder or nested path; create it first with [`create-folder`](#create-folder) |
 | `account` | string | No | Account name; defaults to Notes.app's default account |
-| `path` | string | Yes | Absolute path of the local file (at most 64 MiB) |
+| `path` | string | Yes | Absolute path of the local file (at most 64 MiB), under the same read rules as `add-attachment`; a refused path creates no note |
 | `filename` | string | No | Attachment name override, as in `add-attachment` |
 
 ```json
@@ -2104,9 +2106,12 @@ same verification as [`add-attachment`](#add-attachment).
 ```
 
 **Returns:** the new note's `id` with `noteCreated: true` and the
-`add-attachment` result. If the attachment step fails after the note exists,
-the error names the new note's id: attach to it with `add-attachment` instead of
-calling this tool again, which would create a second note.
+`add-attachment` result. If the attachment step fails after the note exists but
+before the file is inserted, the error names the new note's id: attach to it
+with `add-attachment` instead of calling this tool again, which would create a
+second note. If insertion started and could not be verified, the error is
+`code: "verification_failed"` with `indeterminate: true`: the file may already
+be in the note, so read it with `list-attachments` before attaching again.
 
 ---
 
@@ -2419,11 +2424,13 @@ and currently available, with a specific reason for each unavailable operation.
 It also reports `runtimeOS` (`platform`, `macOSVersion` from `sw_vers`,
 `darwinRelease`) and a `features` matrix, one entry per feature group:
 `applescriptCore`, `fullDiskAccessReads`, `shortcutsBridges`,
-`backgroundOperationsBridge`, `nativeTagsBridge`, `markdownNoteBridge`, and the
-placeholders `checklistToggle`, `smartFolders`, `paragraphLinks`, and
-`audioTranscription`, which need a native *write* helper this server does not
-ship (requirement `native_write_helper`). The opt-in private helper below is
-read-only, so enabling it does not change them: they stay `not_implemented`.
+`backgroundOperationsBridge`, `nativeTagsBridge`, `markdownNoteBridge`,
+`paragraphLinks` and `audioTranscription` (both database reads that need Full
+Disk Access), and the placeholders `checklistToggle` and `smartFolders`
+(creating or editing smart folders), which need a native *write* helper this
+server does not ship (requirement `native_write_helper`). The opt-in private
+helper below is read-only, so enabling it does not change them: they stay
+`not_implemented`.
 Each entry carries `available`, `osSupported`, `minimumMacOSVersion`,
 `requirements`, `missing`, `unverified`, `tools`, and a machine-readable
 `reason` that is `null` when available and otherwise the first that applies:
@@ -2503,12 +2510,15 @@ the note's last checklist items in the requested order.
 }
 ```
 
-**Returns:** `items`, each with its `index`, native `id` and `text`, plus
-`orderVerified` and the new `contentHash`. The first uncertain result stops the
-call without a retry and returns `ok: false` with `landed` (the verified items),
-`stoppedAt` (the item's index, text, `outcome` of `"not-written"` or
-`"uncertain"`, and the error), and `notAttempted`. After an uncertain stop, read
-the note before retrying, and retry only the items that are not present.
+**Returns:** `items` (also as `landed`), each with its `index`, native `id` and
+`text`, plus `orderVerified` and the new `contentHash`. The first uncertain
+result stops the call without a retry and returns `ok: false` with `landed` (the
+verified items), `stoppedAt` (the item's index, text, `outcome` of
+`"not-written"` or `"uncertain"`, and the error), and `notAttempted`. Every
+`ok: false` result is an error result (`isError: true`) with a `code`; after an
+uncertain stop it has `indeterminate: true` and no `contentHash`, since the note
+may have changed. Read the note before retrying, and retry only the items that
+are not present.
 
 #### `create-table`
 
@@ -2765,7 +2775,7 @@ All configuration is optional — the server works out of the box. Override beha
 | `APPLE_NOTES_MCP_BACKGROUND_SHORTCUT` | `Apple Notes MCP - Background Operations v5` | Name or UUID of the installed Background Operations bridge to run. `setup` still installs and checks the default name. |
 | `APPLE_NOTES_MCP_MARKDOWN_SHORTCUT` | `Apple Notes MCP - Create Markdown Note` | Name or UUID of the installed Create Markdown Note bridge to run. `setup` still installs and checks the default name. |
 | `APPLE_NOTES_MCP_PASTEBOARD_NAME` | unset | Testing only: makes [`add-attachment-from-pasteboard`](#add-attachment-from-pasteboard) read a private named pasteboard instead of the general clipboard. |
-| `APPLE_NOTES_MCP_ALLOW_PRIVATE_CONTENT_PATHS` | unset | Set to `1` to let `create-note` read a [`contentPath`](#create-note) inside a hidden directory or file (such as `~/.config`) or `~/Library` outside iCloud Drive and `~/Library/CloudStorage`. Off by default because those places hold keys, tokens and app data. |
+| `APPLE_NOTES_MCP_ALLOW_PRIVATE_CONTENT_PATHS` | unset | Set to `1` to let `create-note` read a [`contentPath`](#create-note), and [`add-attachment`](#add-attachment) and [`create-note-with-attachment`](#create-note-with-attachment) attach a `path`, inside a hidden directory or file (such as `~/.config`) or `~/Library` outside iCloud Drive and `~/Library/CloudStorage`. Off by default because those places hold keys, tokens and app data. |
 | `DEBUG` / `VERBOSE` | unset | Set either to enable verbose diagnostic logging to stderr. |
 
 ### Configuration file (when the host strips `env`)