apple-notes-mcp 2.8.32 → 2.8.34

package/README.md

@@ -171,7 +171,7 @@ On first use, macOS will ask for permission to automate Notes.app. Click "OK" to
 | **Checklist State** | Read checklist done/undone state directly from the Notes database (requires Full Disk Access) |
 | **Audio Transcripts** | Read the transcripts and summaries Notes stored for audio recordings (requires Full Disk Access) |
 | **Export** | Export all notes as JSON or get individual notes as Markdown |
-| **Attachments** | List attachments, save them to disk, or fetch their bytes as base64 |
+| **Attachments** | List attachments with their on-disk asset and preview paths, find a note's lead image, save or batch-export them to disk, or fetch their bytes as base64 |
 | **Notes.app UI State** | Reveal a note in Notes.app or read the current Notes.app selection |
 | **Sync Awareness** | Detect iCloud sync in progress, warn about incomplete results |
 | **Collaboration** | Detect shared notes, warn before modifying |
@@ -332,13 +332,42 @@ title line, with no seed line.
   It also refuses Markdown that Notes would rewrite and the server could not
   verify: `_` emphasis (underscores inside a word, as in `snake_case`, and
   inside a link destination, as in `[docs](https://example.com/_next/static)`,
-  are fine), backslash escapes, character references such as `&`, `---` or
-  `===` lines, indented headings or list items, `1)` lists, closing `#`s, and
+  are fine), backslash escapes, character references such as `&`, `===` lines
+  and rule lines other than the `---` divider described below, indented headings or list items, `1)` lists, closing `#`s, and
   formatting inside link labels. Content that needs one of these literally, such
   as a `/_next` path or a literal `\*`, has no Markdown form here: use
   `format: "html"` for that note (or `append-native` with `format: "html"` on an
   existing one), which keeps the characters but not the Heading and Subheading
   styles. Markdown punctuation in `title` is escaped, so the title stays literal.
+- Notes' importer also maps these block constructs to native styles. They are
+  gated separately, and `get-capabilities` reports them as
+  `create-note-markdown-blocks`. Each mapping below was live-verified on
+  macOS 27.2 by reading the created note's stored styles.
+
+  | Markdown | Native result |
+  |----------|---------------|
+  | `- [ ] item` / `- [x] item` | Checklist item, unchecked / checked |
+  | `> text` (consecutive lines form one quote) | Body paragraph with a block quote |
+  | A fence of bare ```` ``` ```` lines (no language) | Monospaced paragraphs; the code text is kept literally |
+  | `---` on its own line, after a blank line | Divider line |
+  | `` `inline code` `` | **Highlighted** text, not monospace |
+
+  Constructs Notes would not render faithfully, or that this server cannot yet
+  verify, are refused before anything is created: `~~~` fences, a language
+  after the opening fence, nested (`>>`) or indented quotes, lists or headings
+  inside a quote, a quote followed directly by text (Markdown would join that
+  text to the quote), `---` directly under text (Markdown would make that text
+  a heading), `***`/`___`/`----` rules, `[X]`, `* [ ]` or `+ [ ]` items, checklist
+  items directly next to ordinary list items, inline code padded with spaces or
+  inside a link label, tables, and `~~strikethrough~~`. The readback checks the
+  block-quote text, the Monospaced text, each checklist item's text and done
+  state, the divider count, and the highlighted text. These mappings apply to
+  the default Shortcut route only; see
+  [Markdown through HTML](#markdown-through-html) for `markdownRoute: "html"`.
+- [`append-native`](#append-native)'s `format: "markdown"` refuses all of the
+  constructs above: its Shortcuts converter is a different one, which renders
+  a quote and a fenced block as plain body text, `- [ ]` as a bullet with
+  literal brackets, and inline code as plain text, and drops `---`.
 - The server finds the new note among the notes added to the default folder
   during the run by verifying each one's visible text, heading levels and links
   by exact-ID readback, and moves it only after exactly one verifies. On any
@@ -366,7 +395,9 @@ On this route, bullet task items (`- [ ] item`, `- [x] item`) become ordinary
 list rows that start with a visible `☐` or `☑` character, and the response
 reports how many as `taskItemsRendered`. They are text, not native checkable
 checklist items. Use this route as the glyph fallback when the Shortcut is not
-installed or the note is outside iCloud.
+installed or the note is outside iCloud. Block quotes, fenced code and inline code, which
+the Shortcut route maps natively, are refused on this route, and a `---` line
+stays literal text rather than becoming a divider.
 
 ```json
 {
@@ -1404,10 +1435,22 @@ Lists attachments in a note.
 | `id` | string | No | Note ID (preferred) |
 | `title` | string | No | Note title |
 | `account` | string | No | Account containing the note |
+| `includePaths` | boolean | No | Also report where each attachment's files are on disk (needs `id` and Full Disk Access) |
+| `firstImage` | boolean | No | Return only the note's lead visual instead of the list (needs `id` and Full Disk Access) |
 
 **Returns:** List of attachments with IDs, names, content identifiers, URLs when available, created/modified dates, and shared state.
 
-**⚠️ Safety:** A lookup failure is reported as an error, never as an empty list — so an empty result reliably means the note has no attachments and is safe to replace wholesale. Treat an error as "unknown", not "none".
+With `includePaths`, each attachment also carries `identifier`, `uti`, `kind` (`image`, `scan`, `drawing`, `pdf`, `audio`, `video`, `url`, `table`, `other`), `bodyIndex`, and three path fields read from NoteStore and the Notes data folder (read-only):
+
+- `assetPaths`: the attachment's own files, best first (the media file, or Notes' fallback image or PDF rendering).
+- `previewPath`: Notes' largest rendered thumbnail, chosen by pixel area from the `Previews` entries named `<identifier>-<scale>-<W>x<H>-<appearance>`. It is always the image file, including when the entry is a directory holding `<n>_<uuid>/Preview.png`. `null` when there is none.
+- `paths`: `assetPaths` followed by `previewPath`.
+
+Container attachments (a scan gallery) list their child rows under `children`. If the database cannot be read, the list is still returned with a `pathsError`.
+
+With `firstImage`, the result is `{firstImage, orderSource}`. `firstImage` is the first image in the note's body order, even when its asset has not downloaded (`path: null`, possibly with a `previewPath`). A scan or drawing stands in only when the note has no image, and a gallery's pages are considered at the gallery's position (`parentIdentifier`, `galleryIndex`). `orderSource` is `body`, or `creation` when the body did not record attachment order. `firstImage` is `null` when the note has no visual.
+
+**⚠️ Safety:** A lookup failure is reported as an error, never as an empty list — so an empty result reliably means the note has no attachments and is safe to replace wholesale. Treat an error as "unknown", not "none". Treat returned paths as local data: copy files out with [`export-attachments`](#export-attachments) instead of passing raw paths on.
 
 ---
 
@@ -1425,6 +1468,22 @@ Saves a note attachment to disk.
 
 ---
 
+#### `export-attachments`
+
+Copies a note's attachment files into a directory without opening Notes.app.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `noteId` | string | Yes | Exact CoreData note ID |
+| `exportDir` | string | Yes | Absolute destination directory, created if missing. Same allowlist as `save-attachment` (home, temp, or `/Volumes`), and never inside the Notes data folder |
+| `firstImageOnly` | boolean | No | Export only the lead visual that `list-attachments` `firstImage` reports |
+
+**Returns:** `exportDir`, counts (`exported`, `previews`, `skipped`, `failed`), and per attachment its `attachmentId`, `identifier`, `kind`, `exportedTo`, and `exportedKind`: `"asset"` for the real file, `"preview"` when the asset never downloaded and only Notes' thumbnail was on disk, or `null` when nothing was on disk. A preview is never chosen over an available asset, and it is named `<name>-preview.<ext>` so it is not mistaken for the original. A scan gallery with no file of its own exports its pages.
+
+**⚠️ Safety:** Existing files are never replaced. A name that is taken gets `-2`, `-3`, and so on. Reads NoteStore and the Notes data folder read-only and needs Full Disk Access.
+
+---
+
 #### `fetch-attachment`
 
 Returns a note attachment's bytes as base64, without writing to disk (the read counterpart to `save-attachment`).
@@ -1805,7 +1864,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-blocks`, `get-audio-transcripts`, `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-audio-transcripts`, `get-note-link`, the checklist annotations in `get-note-markdown`, `list-attachments` with `includePaths` or `firstImage`, `export-attachments`, 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.
 
@@ -1870,7 +1929,7 @@ Apple Notes stores checklists as a paragraph style (`style_type=103`) inside a g
 **Workarounds:**
 
 1. **Create the note with bulleted list items, then convert manually in Notes.app.** Select the items and press <kbd>⇧⌘L</kbd> (or **Format → Checklist**). This converts the list in place and the resulting checklist will be readable by `get-checklist-state` and annotated by `get-note-markdown`.
-2. **Use the Apple Shortcuts app** to script the checklist creation, since Shortcuts can manipulate Notes content at a higher level than AppleScript.
+2. **Use the Apple Shortcuts app** to script the checklist creation, since Shortcuts can manipulate Notes content at a higher level than AppleScript. This server does that for you in two ways: [`create-checklist-item`](#create-checklist-item) appends one unchecked item to an existing note, and [`create-note`](#create-note) with `format: "markdown"` turns `- [ ]` / `- [x]` lines into checklist items with that done state through Notes' own Markdown importer, (see [Markdown notes](#markdown-notes)).
 3. **Read-only checklist support is fully implemented** — once a checklist exists (created manually or by another app), `get-checklist-state` and `get-note-markdown` will read its done/undone state correctly (with Full Disk Access).
 
 If you need to *track* todos programmatically and don't strictly need them rendered as Apple Notes checklist UI, plain markdown-style `- [ ] item` / `- [x] item` lines in a `plaintext` note are a reasonable alternative — they are searchable, human-readable, and can be parsed by downstream tooling.