apple-notes-mcp 2.12.0 → 2.14.0

package/README.md

@@ -2,7 +2,7 @@
 
 A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets Claude (Claude Code and Claude Desktop), Codex, and other MCP clients read, search, create, edit, organize, and export notes in Apple Notes on macOS. It runs locally on your Mac and talks to Notes through AppleScript, Apple Shortcuts, and read-only access to the Notes database.
 
-Beyond creating and editing notes, it manages folders and accounts, native tags, checklists, tables, pinned notes, links, and attachments. It can also export notes as Markdown, HTML, or JSON, read audio transcripts and drawings, and run a query language across your whole library.
+Beyond creating and editing notes, it manages folders and accounts, native tags, checklists, tables, pinned notes, links, and attachments. It can also export notes as Markdown (through templates you can edit in a local web editor), HTML (with classic drawings as SVG), or JSON, read audio transcripts and drawings, link to single paragraphs with anchors that survive edits, and run a query language across your whole library.
 
 [![npm version](https://img.shields.io/npm/v/apple-notes-mcp)](https://www.npmjs.com/package/apple-notes-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/apple-notes-mcp)](https://www.npmjs.com/package/apple-notes-mcp)
@@ -704,8 +704,10 @@ stable code in brackets, such as `[encrypted]` or `[no-full-disk-access]`.
 
 #### `list-note-paragraphs`
 
-Lists one note's non-empty paragraphs in body order, read-only from the
-NoteStore database. Each paragraph has `blockIndex` (its index in
+Lists one note's non-empty paragraphs in body order, read from the NoteStore
+database. It never changes Notes. With `recordAnchors` it also writes the
+local anchor registry, so the tool is not marked read-only in its MCP
+annotations. Each paragraph has `blockIndex` (its index in
 `get-note-blocks`, where empty paragraphs also count), `text`, `style`,
 `styleType`, `paragraphId` (the UUID Notes stores on the paragraph's first
 text run), and `paragraphIdStatus`:
@@ -733,6 +735,7 @@ IDs.
 | `linkableOnly` | boolean | No | Return only paragraphs with a `url` |
 | `offset` | number | No | First paragraph to return (default 0). Use `page.nextOffset` |
 | `limit` | number | No | Maximum paragraphs per page (default 500, max 5000) |
+| `recordAnchors` | boolean | No | Also record a [paragraph anchor](#paragraph-anchors) for each returned paragraph (at most 500 per call); each row gains `anchorId` and the result gains `anchorsRecorded` (the new ones). Writes only the local anchor registry |
 
 ---
 
@@ -756,7 +759,9 @@ Otherwise the result is an error whose `structuredContent` carries the usual
 `no-match`, `ambiguous-paragraph`, `occurrence-out-of-range`, `ambiguous-note`
 (several notes have that title; the message lists their folders), `not-found`,
 `encrypted`, or `no-body`. The tool never creates or changes a paragraph ID,
-and an edit in Notes can later replace the ID and break the link.
+and an edit in Notes can later replace the ID and break the link. With
+`recordAnchor` it also writes the local anchor registry, so the tool is not
+marked read-only in its MCP annotations.
 
 **Requires:** Full Disk Access.
 
@@ -767,6 +772,117 @@ and an edit in Notes can later replace the ID and break the link.
 | `match` | string | One of `contains`, `match`, `blockIndex` | The whole paragraph |
 | `blockIndex` | number | One of `contains`, `match`, `blockIndex` | The paragraph's `blockIndex` |
 | `occurrence` | number | No | Which match to use when several paragraphs match |
+| `recordAnchor` | boolean | No | Also record a [paragraph anchor](#paragraph-anchors) for the linked paragraph and return its `anchorId`. Writes only the local anchor registry |
+
+---
+
+#### Paragraph anchors
+
+A paragraph link breaks when Notes replaces or copies the paragraph's ID. A
+paragraph anchor records enough about the paragraph to find it again: the
+note's Notes UUID, the paragraph ID and its status, the paragraph's normalized
+text and a fingerprint of it, the fingerprints of the paragraphs before and
+after it, its `blockIndex`, and when it was recorded. Anchors are kept in one
+local file, `~/Library/Application Support/apple-notes-mcp/paragraph-anchors.json`
+(or the absolute path in `APPLE_NOTES_MCP_ANCHOR_FILE`). It is created with
+mode 0600 in a 0700 directory, replaced atomically under a lock file, and
+holds the text of every anchored paragraph. A symlinked, unreadable or
+corrupt registry is refused and left as it is. The anchor tools never change
+Notes.
+
+Resolving an anchor tries three steps in order, and every step fails closed:
+
+1. **Paragraph ID.** A paragraph whose ID is still unique in the note is the
+   anchored paragraph, even if its text was edited or it moved. A link to that
+   ID opens exactly that paragraph.
+2. **Exact text.** The same normalized text. When several paragraphs have it,
+   only the one whose neighbours still match is chosen; a tie is `ambiguous`.
+3. **Text and neighbours.** Similar text between both recorded neighbours, or
+   nearly identical text beside one of them. Two close candidates are
+   `ambiguous`; one below `minConfidence` is `low-confidence`.
+
+A match whose ID is now shared or missing is `needs-reminting`: the paragraph
+is found (the result names its block), but no safe link exists until it gets a
+new ID. Public automation cannot set a paragraph ID, so this server only
+reports it and returns no `url`.
+
+To share anchored links outside Notes, see the
+[paragraph anchor resolver](#paragraph-anchor-resolver-opt-in).
+
+#### `create-paragraph-anchor`
+
+Records an anchor for one paragraph, selected exactly as in
+`get-paragraph-link` (note by `id` or `title`/`folder`; paragraph by one of
+`contains`, `match`, `blockIndex`, plus `occurrence`). Unlike
+`get-paragraph-link`, a paragraph whose ID is shared or missing can be
+anchored. Recording the same paragraph again (same note, ID, text and block)
+returns the existing anchor with `created: false`.
+
+Returns `anchor`, `created`, and `url` when the paragraph currently has a
+unique ID.
+
+**Requires:** Full Disk Access. Writes only the anchor registry.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id`, `title`, `folder` | string | One of `id`, `title` | Note selector, as in `list-note-paragraphs` |
+| `contains`, `match`, `blockIndex`, `occurrence` | | One of `contains`, `match`, `blockIndex` | Paragraph selector, as in `get-paragraph-link` |
+
+#### `resolve-paragraph-anchor`
+
+Finds an anchored paragraph in the note as it is now. The result has `status`
+(`resolved`, `needs-reminting`, `ambiguous`, `low-confidence`, `not-found`,
+`note-not-found`, `note-deleted` for a note in Recently Deleted, or
+`note-unreadable` for a locked note), `method` (`paragraph-id`, `exact-text`,
+`text-and-neighbours`), `confidence` (0 to 1), `match` (`blockIndex`, `text`,
+`paragraphId`, `paragraphIdStatus`), `changes` (`textChanged`,
+`blockIndexChanged`, `paragraphIdChanged`), and `message`. `url`, the current
+`applenotes://` link, is present only when `status` is `resolved`.
+
+**Requires:** Full Disk Access.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `anchorId` | string | Yes | The anchor (`pa_` and 24 hex digits) |
+| `minConfidence` | number | No | Lowest confidence accepted as a match (default 0.6) |
+| `refresh` | boolean | No | After a match with confidence 0.8 or more, store the paragraph as it is now (text, neighbours, block, ID), so later edits are tracked from here. Reports `refreshed` or `refreshSkipped` |
+
+#### `list-paragraph-anchors`
+
+Lists recorded anchors in the order recorded, with `total`, the `registry`
+path and `page` info. Reads only the registry.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `noteIdentifier` | string | No | Only anchors in the note with this Notes UUID |
+| `offset` | number | No | First anchor to return (default 0) |
+| `limit` | number | No | Maximum anchors (default 100, max 1000) |
+
+#### `get-paragraph-anchor`
+
+Returns one stored anchor as recorded. Reads only the registry.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `anchorId` | string | Yes | The anchor |
+
+#### `prune-paragraph-anchors`
+
+Removes anchors that no longer resolve, or the anchors you list. It is a dry
+run unless `dryRun` is `false`. Without `anchorIds` it resolves every anchor
+in scope and treats `not-found` and `note-not-found` as stale. A note in
+Recently Deleted (`note-deleted`) is kept by default because it can be
+restored. Returns `stale` (`anchorId`, `status`, `message`), `examined`, and
+`removed`.
+
+**Requires:** Full Disk Access unless `anchorIds` is given.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `anchorIds` | string[] | No | Remove exactly these anchors instead of resolving |
+| `noteIdentifier` | string | No | Only anchors in the note with this Notes UUID |
+| `statuses` | string[] | No | Statuses treated as stale (default `not-found`, `note-not-found`) |
+| `dryRun` | boolean | No | Report without removing (default `true`) |
 
 ---
 
@@ -1950,6 +2066,21 @@ be deleted.
 
 **Returns:** `name`, `path`, and `deleted: true`.
 
+#### Template editor (command line)
+
+`apple-notes-mcp templates edit [name]` starts a local web editor for
+templates: edit the JSON on one side and see it validated and rendered
+against built-in sample notes on the other, then save it to the library
+(create-only unless you tick "replace"). It prints one address with a
+per-run token, listens on `127.0.0.1` only, refuses cross-origin requests,
+and stops on Ctrl-C or after 30 idle minutes (`--idle-minutes`). It reads a
+real note only when you pass `--note <id>`, and then read-only. `--tailnet`
+listens on this Mac's Tailscale address instead, so another device on your
+tailnet can open it; it never changes Tailscale or firewall settings. With
+`--tailnet`, `--note` exposes the full note body to anyone who has the URL. See
+[docs/markdown-templates.md](docs/markdown-templates.md#editing-in-a-browser)
+for options and exactly what it exposes.
+
 ---
 
 #### `get-checklist-state`
@@ -2813,6 +2944,8 @@ 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, 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_ANCHOR_FILE` | `~/Library/Application Support/apple-notes-mcp/paragraph-anchors.json` | Absolute path of the [paragraph anchor](#paragraph-anchors) registry. |
+| `APPLE_NOTES_MCP_ANCHORS_TOKEN` | unset | Token for `apple-notes-mcp anchors serve` (at least 32 characters). Unset, the resolver makes a new random token each run. |
 | `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. |
@@ -2940,6 +3073,48 @@ The helper never opens the Notes database and never writes under the Notes group
 
 ---
 
+## Paragraph anchor resolver (opt-in)
+
+An `applenotes://` paragraph link only opens on an Apple device, and it breaks
+when the paragraph's ID changes. For links shared outside Notes, you can run a
+small local resolver that looks up a [paragraph anchor](#paragraph-anchors)
+when the link is opened and redirects to the paragraph's current link:
+
+```bash
+apple-notes-mcp anchors serve                 # http://127.0.0.1:<random port>
+apple-notes-mcp anchors serve --port 8765     # a fixed port
+apple-notes-mcp anchors serve --tailnet       # this Mac's Tailscale address instead
+```
+
+It serves one route, `GET /a/<anchor-id>?token=<token>`. A `resolved` anchor
+answers with a 302 redirect to the `applenotes://` link. Any other status gets
+a short plain-text answer and no redirect: 409 for `ambiguous`,
+`low-confidence`, `needs-reminting` and `note-unreadable`, and 404 for a gone
+paragraph or note.
+
+- **Off by default.** Only this command starts it; the MCP server never does.
+  It runs in the foreground until you press Ctrl-C.
+- **Loopback by default.** It binds `127.0.0.1`. `--tailnet` binds the first
+  `100.64.0.0/10` address on this Mac (a Tailscale address) instead, and fails
+  if there is none. It never runs `tailscale` and never changes Tailscale,
+  firewall or system settings.
+- **Token required.** Every request needs the token, as `?token=` or
+  `Authorization: Bearer`. It is `APPLE_NOTES_MCP_ANCHORS_TOKEN` when set (at
+  least 32 characters; use this for links that must survive a restart), or a
+  random token printed once at startup. Tokens are compared in constant time
+  and never logged; request logs on stderr omit the query string. After 20
+  failed token checks in a minute from one peer address, that peer gets 429
+  until the minute passes. The count is per peer, so one client guessing
+  tokens cannot lock out another, and requests refused for their method or
+  `Host` header never count.
+- **Host check.** The `Host` header must name the bound address, which blocks
+  DNS rebinding. Only `GET` and `HEAD` are served, with `Cache-Control:
+  no-store` and `Referrer-Policy: no-referrer`.
+- It needs Full Disk Access for the terminal or process that runs it, and it
+  reads the same registry as the anchor tools.
+
+---
+
 ## Security and Privacy
 
 - **Local only** - All operations happen locally, through AppleScript, the packaged Shortcuts, read-only reads of the Notes database, and helpers you build on your own Mac. The server makes no network requests, and `transcribe-note-audio` uses on-device speech recognition only. Whatever your MCP client does with the results is governed by that client.