apple-notes-mcp 2.8.26 → 2.8.28

package/README.md

@@ -513,6 +513,36 @@ Disk Access.
 
 ---
 
+#### `get-note-blocks`
+
+Decodes one note's body into typed blocks, read-only, from the NoteStore
+database. Each block is one paragraph with its `style` (`title`, `heading`,
+`subheading`, `body`, `monospaced`, `bulleted`, `dashed`, `numbered`,
+`checklist`, or `unknown` with the raw `styleType`), `indent`, `alignment`,
+`blockQuote`, checklist `id`/`done`, and `paragraphUuid` when stored. Each
+block lists its inline `runs` with `bold`, `italic`, `underline`,
+`strikethrough`, `superscript`, `subscript`, `color`, `highlight`, `link`
+(plus `linkSafe`), `font`, and `attachment`, and its attachment markers in body
+order. Offsets and lengths count UTF-16 code units. `summary` counts styles and
+inline attributes for the whole note. `undecodedFields` lists stored field
+numbers the decoder deliberately does not interpret.
+
+**Requires:** Full Disk Access. Password-protected notes are refused.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Exact note ID |
+| `offset` | number | No | First block to return (default 0). Use `page.nextOffset` |
+| `limit` | number | No | Maximum blocks per page (default 500, max 5000) |
+
+A page also stops early to stay under `APPLE_NOTES_MCP_BLOCKS_MAX_BYTES`
+(default 4 MB). `paragraphUuid` is not unique: Notes copies it when a paragraph
+is split. Link URLs are returned as stored, and `linkSafe` is false for schemes
+other than http(s), `notes:`, `applenotes:` and `mailto:`. Errors carry a
+stable code in brackets, such as `[encrypted]` or `[no-full-disk-access]`.
+
+---
+
 #### `list-native-tags`
 
 Lists actual native Notes tags used within one explicit `account` and `folder`,
@@ -930,6 +960,47 @@ Lists all folders in an account with full hierarchical paths.
 
 ---
 
+#### `list-smart-folders`
+
+Lists every Smart Folder with the rules that define it, read from the NoteStore
+database. Requires Full Disk Access.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `includeMatchingNotes` | boolean | No | Also list the notes each smart folder currently shows (default `false`) |
+| `limit` | number | No | Maximum matching notes per folder, 1–500 (default 50). `matchingNoteCount` is always the total |
+
+**Example:**
+```json
+{
+  "includeMatchingNotes": true,
+  "limit": 20
+}
+```
+
+**Returns:** For each smart folder: `name`, `id`, `identifier`, `account`,
+`accountId`, `accountIdentifier`, `parent`, `parentId`, and `parentIdentifier`
+(the parent fields are `null` at the account root). Its rules are decoded as
+`match` (`"all"`, `"any"`, or `"none"`) and `filters`. Each filter has a `type`
+(the stored rule key, such as `folder`, `tag`, `checklist`, or
+`creationDateRelativeRange`), its stored `value`, `excluded` for an Exclude
+rule, and a readable `description`. Folder filters add the folder's `name` and
+`folderId`, and a nested rule group is a filter of type `group` with its own
+`match` and `filters`. Notes stores each query inside an outer
+`{"deleted": false}` wrapper that keeps Recently Deleted out. `query` is the
+stored query with that wrapper removed, `includesRecentlyDeleted` reports the
+wrapper's value, and `rawQuery` is the stored JSON verbatim. A rule this server
+does not recognize is kept as a filter of type `unknown`, and `fullyDecoded` is
+then `false`.
+
+With `includeMatchingNotes`, each folder also carries `matchingNoteCount` and
+`matchingNotes` (`title` and `id`). These come from Notes.app itself, which
+evaluates the folder's rules, so they need Automation permission. The server
+does not re-evaluate the rules on its own. A folder whose notes cannot be read
+carries `matchingNotesError` instead.
+
+---
+
 #### `create-folder`
 
 Creates a new folder, including a whole nested hierarchy in one call.
@@ -1569,6 +1640,7 @@ All configuration is optional — the server works out of the box. Override beha
 | `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. |
 | `APPLE_NOTES_MCP_EXPORT_MAX_BYTES` | `8388608` (8 MB) | Largest response `export-notes-json` sends; a page closes early to stay under 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`. |
 | `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. |
 | `APPLE_NOTES_MCP_RETRY_DELAY_MS` | `1000` (1 s) | Base delay before the first retry; subsequent retries back off exponentially (1s, 2s, 4s, ...). |
 | `DEBUG` / `VERBOSE` | unset | Set either to enable verbose diagnostic logging to stderr. |
@@ -1597,7 +1669,7 @@ MCP stores no secrets, but as a general rule keep only non-secret config here.
 
 ## Full Disk Access
 
-Several tools read directly from the Apple Notes SQLite database, which lives in a macOS-protected directory. Those tools require **Full Disk Access** for the process running the MCP server: `get-checklist-state`, `get-note-metadata`, `get-note-link`, the checklist annotations in `get-note-markdown`, and the database half of `get-sync-status`.
+Several tools read directly from the Apple Notes SQLite database, which lives in a macOS-protected directory. Those tools require **Full Disk Access** for the process running the MCP server: `get-checklist-state`, `get-note-metadata`, `get-note-blocks`, `get-note-link`, the checklist annotations in `get-note-markdown`, and the database half of `get-sync-status`.
 
 > 📘 **For the full why-and-how walkthrough (which app to grant, verifying with `doctor`, graceful degradation), see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md).** The summary below is the quick version.