apple-notes-mcp 2.9.15 → 2.9.17

package/README.md

@@ -1710,7 +1710,7 @@ single note.
 | `outputPath` | string | No | Absolute file to create. Create-only: an existing file (or symlink) is refused with `[output_exists]` |
 | `assetsDir` | string | No | Absolute directory for attachment copies. Existing files are never replaced; a taken name gets `-2`, `-3`, ... |
 | `wrap` | number | No | Hard-wrap prose at this many columns. Code, tables and headings are never wrapped |
-| `template` | string | No | Render through a template: `standard-markdown` or `obsidian`. Exclusive with `templateFile` |
+| `template` | string | No | Render through a template: `standard-markdown`, `obsidian`, or a saved template's name. Exclusive with `templateFile` |
 | `templateFile` | string | No | Render through the JSON template in this `.json` file (same path rules; at most 256 KiB) |
 
 Both paths follow the `save-attachment` rules (absolute, under the home
@@ -1785,6 +1785,88 @@ already written is deleted if a later step fails.
 
 ---
 
+#### `list-markdown-templates`
+
+Lists the Markdown export templates: the built-ins (`standard-markdown`,
+`obsidian`) and every saved template in the library, with its display name,
+description, size and modification date. Unreadable, invalid or unsafe files
+in the library are skipped and counted in `skipped`. Takes no parameters.
+
+**Returns:** `builtins`, `templates`, `skipped`, and `dir` (the library
+directory).
+
+---
+
+#### `show-markdown-template`
+
+Returns one template in its portable form: a built-in, or a saved template
+exactly as stored (overrides only). Use it as the starting point for a new
+template.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | A built-in or saved template name |
+| `expanded` | boolean | No | Also return `expanded`, with every rule filled in from its base |
+
+**Returns:** `name`, `source` (`builtin` or `saved`), `template`, and
+optionally `expanded`.
+
+---
+
+#### `validate-markdown-template`
+
+Checks a template without saving it. Pass exactly one of `name`, `template`
+or `templateFile`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | One of three | A saved or built-in template |
+| `template` | object or string | One of three | The template as a JSON object or JSON text |
+| `templateFile` | string | One of three | Absolute path of a JSON template file (home, a temp directory, or `/Volumes`; at most 256 KiB) |
+
+**Returns:** `valid`, and `errors` as `{path, message}` pairs such as
+`$.rules["inline.bold"].after: is required when mode is "wrap"`. An invalid
+template is a normal result, not a tool error.
+
+---
+
+#### `save-markdown-template`
+
+Validates a template and stores it in the library so `export-notes-markdown`
+can use it by `template` name.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Lowercase `a-z`, `0-9`, `-` and `_`, 1-64 characters, starting with a letter or digit. Built-in names are reserved |
+| `template` | object or string | One of `template`/`templateFile` | The template |
+| `templateFile` | string | One of `template`/`templateFile` | A JSON template file |
+| `force` | boolean | No | Replace an existing template of this name (default `false`) |
+
+Saving is create-only: an existing name is refused with `[template-exists]`
+unless `force` is true. An invalid template is refused with
+`[invalid-template]` and one JSON path per problem. The file is written to a
+temporary name and then moved into place, with mode `0600` in a `0700`
+directory. The library is `~/Library/Application Support/apple-notes-mcp/templates`,
+or `APPLE_NOTES_MCP_TEMPLATE_DIR`. A symlinked library or template file is
+refused.
+
+**Returns:** `name`, `path`, `bytes`, and `replaced`.
+
+---
+
+#### `delete-markdown-template`
+
+Removes one saved template file from the library. Built-in templates cannot
+be deleted.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | The saved template to delete |
+
+**Returns:** `name`, `path`, and `deleted: true`.
+
+---
+
 #### `get-checklist-state`
 
 Reads checklist done/undone state for a note. This bypasses the AppleScript limitation where `body of note` strips checklist state, by reading directly from the NoteStore SQLite database.
@@ -1990,6 +2072,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.
@@ -2508,6 +2656,7 @@ All configuration is optional — the server works out of the box. Override beha
 | `APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES` | `262144` (256 KB) | Per-image cap on the base64 payload kept inline in a [`get-note-content`](#get-note-content) response. Inline images over the cap are replaced with placeholders (with a warning appended) so an image-heavy note cannot exceed the MCP client's message limit and drop the connection; export the real files with [`save-attachment`](#save-attachment) or [`fetch-attachment`](#fetch-attachment). Raise it to keep bigger images inline. |
 | `APPLE_NOTES_MCP_CONFIG_FILE` | `~/Library/Application Support/apple-notes-mcp/config.json` | Path to the JSON config file (see below). |
 | `APPLE_NOTES_MCP_TIMEOUT_MS` | `30000` (30 s) | Total AppleScript operation timeout, including retry attempts and delays. Raise it if full-library operations (large searches, exports) time out on a big Notes library. Per-call `timeoutMs` options still win, and a write tool's `timeoutSeconds` argument overrides it for that call. |
+| `APPLE_NOTES_MCP_TEMPLATE_DIR` | `~/Library/Application Support/apple-notes-mcp/templates` | Absolute directory of the saved Markdown template library (`save-markdown-template` and friends). |
 | `APPLE_NOTES_MCP_EXPORT_MAX_BYTES` | `8388608` (8 MB) | Largest response `export-notes-json` sends; a page closes early to stay under it. `export-notes-markdown` returns inline Markdown up to half of it. The default sits below the 10 MB per-message limit of MCP SDK stdio clients, which drop the connection on anything larger. Raise it only if your MCP client accepts bigger messages. |
 | `APPLE_NOTES_MCP_BLOCKS_MAX_BYTES` | `4194304` (4 MB) | Largest block payload one [`get-note-blocks`](#get-note-blocks) page returns; the page closes early to stay under it, and a single oversized paragraph comes back with `textOmitted: true`. [`get-note-structure`](#get-note-structure) also omits note text larger than this. A [`list-note-paragraphs`](#list-note-paragraphs) or [`list-note-links`](#list-note-links) page also stops early to stay under it. |
 | `APPLE_NOTES_MCP_MAX_RETRIES` | `2` | Maximum attempts for a read-only AppleScript call that fails with a **transient** error (Notes.app busy / not responding / lost connection). `2` means one retry; set `1` to fail fast with no retries. Retries share the single `APPLE_NOTES_MCP_TIMEOUT_MS` budget rather than each getting a fresh one, and a retry is skipped when under a second of that budget remains — so this is a ceiling, not a guarantee. In particular a call that exhausts the budget with a **timeout** has no time left to retry by construction. Mutating operations run once because a timeout can occur after Notes.app applied the change. Non-transient errors (e.g. "note not found") never retry. |