apple-notes-mcp 2.9.16 → 2.9.19

package/README.md

@@ -1355,7 +1355,7 @@ Lists all folders in an account with full hierarchical paths.
 {}
 ```
 
-**Returns:** List of folders with IDs, paths, account names, and shared state, plus `identifier`, `parentIdentifier`, and `accountIdentifier` when Full Disk Access is granted. Nested folders are shown as full paths (e.g., `Work/Clients/Omnia`). Duplicate folder names are disambiguated by their full path. Literal slashes in folder names are escaped as `\/` (e.g., `Spain\/Portugal 2023`).
+**Returns:** List of folders with IDs, paths, account names, and shared state, plus `identifier`, `parentIdentifier`, and `accountIdentifier` when Full Disk Access is granted. Nested folders are shown as full paths (e.g., `Work/Clients/Omnia`). Duplicate folder names are disambiguated by their full path. Literal slashes in folder names are escaped as `\/` (e.g., `Spain\/Portugal 2023`). Smart folders are listed too, because Notes' AppleScript lists them like ordinary folders; with Full Disk Access they carry `smartFolder: true` (and `(smart folder)` in the text list). A smart folder cannot hold notes or folders.
 
 ---
 
@@ -2016,7 +2016,8 @@ Each take gets a deadline of 1.5 times its length plus a minute (at most 30 minu
 Adds one nonempty local file of at most 64 MiB to an exact note using `id`, the
 latest `expectedContentHash`, and an absolute `path`. The server never retries
 the insertion. It verifies that existing rich content survived and compares the
-fetched attachment bytes with the source before reporting success.
+size and streamed SHA-256 of Notes' saved copy with the source before reporting
+success, with no read cap below the 64 MiB write limit.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -2072,6 +2073,72 @@ calling this tool again, which would create a second note.
 
 ---
 
+#### `add-attachment-from-pasteboard`
+
+Attaches whatever image, PDF, or file is on the pasteboard (a screenshot, "Copy
+Image", or a file copied in Finder) to an exact note. The pasteboard is read once
+through AppKit's public `NSPasteboard` API (via JXA, no native build) and its
+bytes are frozen into a private temporary file before anything touches the note.
+The pasteboard itself is never written. The note and `expectedContentHash` are
+checked before the pasteboard is read, so a request with a wrong id, a stale
+revision, or a malformed `filename` never captures your clipboard. The frozen
+file then goes through [`add-attachment`](#add-attachment)'s checks.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Note ID |
+| `expectedContentHash` | string | Yes | The note's current `contentHash` (from `get-note-content`) |
+| `filename` | string | No | Attachment name. Defaults to the copied file's name, or `Pasted image.png` / `Pasted document.pdf` for image or PDF data. Without an extension, the pasted type's extension is added; with one, it must match the pasted type. Otherwise the same rules as `add-attachment` |
+| `allowPasteAlert` | boolean | No | Default `false`. Read the pasteboard even when macOS will show its paste alert (see **Paste privacy** below). Never overrides a Deny setting |
+
+**Returns:** the `add-attachment` result plus `source` (`kind`: `file` or
+`data`, the pasteboard `type`, and the default `filename`). A copied file wins
+over image data; among data types PNG is preferred, then JPEG, HEIC, GIF, TIFF,
+and PDF.
+
+**Paste privacy (macOS 15.4 and later):** macOS can show an alert asking
+whether to allow a paste when a process reads the general pasteboard without a
+user paste. Before reading anything, the tool checks AppKit's
+[`NSPasteboard.accessBehavior`](https://developer.apple.com/documentation/appkit/nspasteboard/accessbehavior-swift.enum).
+It reads only when the value is `alwaysAllow`, or when you pass
+`allowPasteAlert: true` and the value is `default` or `ask` (macOS then shows
+its alert, and the call waits for your answer up to the automation timeout).
+Otherwise it reads nothing and returns `code: "permission_denied"` with
+`pasteboardCode: "pasteboard_access_denied"` and `accessBehavior` (`default`,
+`ask`, `alwaysDeny`, or `unknown`). `alwaysDeny` is always refused; change it in
+System Settings, where macOS lists an app after its first paste alert. On macOS
+before 15.4 the property does not exist and the pasteboard is read as before.
+
+**Errors** carry a `pasteboardCode` next to the shared `code`, and
+`committed: false` because nothing was written:
+
+| `pasteboardCode` | `code` | Cause |
+|------------------|--------|-------|
+| `pasteboard_access_denied` | `permission_denied` | Reading would show the macOS paste alert, or pasting is denied (see above) |
+| `pasteboard_empty` | `validation_error` | Nothing is on the pasteboard |
+| `unsupported_content` | `validation_error` | No PNG, JPEG, HEIC, GIF, TIFF, PDF, or copied file (text belongs in `append-to-note`); the message and `types` list the pasteboard types found |
+| `multiple_files` | `validation_error` | More than one copied file; `count` says how many. Copy one file, or use `add-attachment` per file |
+| `too_large` | `validation_error` | More than 64 MiB |
+| `file_unreadable` | `validation_error` | The copied file is a symlink, empty, over 64 MiB, or unreadable |
+| `pasteboard_changed` | `operation_failed` | The pasteboard changed while it was being read; try again |
+| `pasteboard_timeout` | `operation_failed` | The read timed out (for example an unanswered paste alert) |
+| `pasteboard_unavailable` | `operation_failed` | The MCP host is not running in your logged-in GUI session (for example over SSH) |
+| `write_failed` | `operation_failed` | The temporary copy could not be written |
+
+The pasteboard read uses the same timeout as other automation steps
+(`APPLE_NOTES_MCP_TIMEOUT_MS`, 30 seconds by default).
+
+**Known limitation ([#236](https://github.com/sweetrb/apple-notes-mcp/issues/236)):** on macOS 27, Notes' AppleScript dictionary does not list
+PDF attachments, so a PDF (pasted or from `add-attachment`) is inserted but
+cannot be verified and the call reports "insertion outcome uncertain". Read the
+note before retrying.
+
+For testing, `APPLE_NOTES_MCP_PASTEBOARD_NAME` makes the tool read a private
+named pasteboard instead of the general one, so a test never touches your
+clipboard.
+
+---
+
 #### `list-attachments`
 
 Lists attachments in a note.
@@ -2287,6 +2354,17 @@ distinctive existing `scopeText` so the Shortcut and server can independently
 resolve the same note. Creating a note from Markdown is
 [`create-note`](#create-note) with `format: "markdown"`.
 
+When the Shortcut refuses a request (its Find Notes step did not return
+exactly one note with that exact title and `scopeText`) or stops with its own
+action error, and the note reads back unchanged, the tool reports the
+Shortcut's reason with `code: "operation_failed"`, `committed: false` and
+`indeterminate: false`: nothing was written, so a retry is safe once the cause
+is fixed. Notes search can lag behind a note created or edited moments ago, so
+a refusal on a brand-new note may clear after a minute. A timeout, or a failed
+readback on a note that did change, is still reported as indeterminate.
+If the Shortcut is not installed, the error is `code: "shortcut_not_installed"`
+with `committed: false`.
+
 #### `get-capabilities`
 
 Reports which background operations are implemented, live-verified, installed,