apple-notes-mcp 2.9.23 → 2.9.25

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
 
@@ -274,7 +276,7 @@ Creates a new note in Apple Notes.
 |-----------|------|----------|-------------|
 | `title` | string | Yes | The title of the note. Automatically prepended as `<h1>` — do NOT include the title in `content` |
 | `content` | string | One of `content`/`contentPath` | The body content of the note (do not repeat the title here) |
-| `contentPath` | string | One of `content`/`contentPath` | Absolute path of a local UTF-8 file to use as the body instead of `content`. Allowed in the same places [`save-attachment`](#save-attachment) may write (home, temp, `/Volumes`); symbolic links, non-regular files, invalid UTF-8 and files over 1 MiB are refused before anything is written. A leading byte-order mark is dropped |
+| `contentPath` | string | One of `content`/`contentPath` | Absolute path of a local UTF-8 file to use as the body instead of `content`. Allowed in the same places [`save-attachment`](#save-attachment) may write (home, temp, `/Volumes`), except hidden paths (any component starting with `.`, such as `~/.ssh` or a project `.env`) and `~/Library` other than iCloud Drive (`~/Library/Mobile Documents`) and cloud storage folders (`~/Library/CloudStorage`), which can hold credentials; set `APPLE_NOTES_MCP_ALLOW_PRIVATE_CONTENT_PATHS=1` to allow those. Symbolic links, non-regular files, invalid UTF-8 and files over 1 MiB are refused before anything is written. A leading byte-order mark is dropped |
 | `tags` | string[] | No | Returned-only metadata — **NOT written to Notes.app**. Apple Notes tags can't be set via AppleScript, so values passed here are echoed back in the response but do not appear on the created note. Inline `#hashtags` in `content` stay searchable text and are returned as `hashtags`, but they do not become native Notes tags; add real tags afterwards with [`add-native-tags`](#add-native-tags). Refused with `format: "markdown"` |
 | `folder` | string | No | Folder to create the note in. Supports nested paths like `"Work/Clients"`. **The folder must already exist** — create it first with [`create-folder`](#create-folder). A smart folder is refused (see [`move-note`](#move-note)). Defaults to account root |
 | `account` | string | No | Account name (defaults to Notes.app's default account; matched exactly or by a *unique* prefix — an ambiguous prefix is refused). Must be an account Notes.app already has configured — see [`list-accounts`](#list-accounts) |
@@ -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,6 +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. |
 | `DEBUG` / `VERBOSE` | unset | Set either to enable verbose diagnostic logging to stderr. |
 
 ### Configuration file (when the host strips `env`)