apple-notes-mcp 2.9.20 → 2.9.21

package/README.md

@@ -256,14 +256,14 @@ Creates a new note in Apple Notes.
 | `title` | string | Yes | The title of the note. Automatically prepended as `<h1>` — do NOT include the title in `content` |
 | `content` | string | One of `content`/`contentPath` | The body content of the note (do not repeat the title here) |
 | `contentPath` | string | One of `content`/`contentPath` | Absolute path of a local UTF-8 file to use as the body instead of `content`. Allowed in the same places [`save-attachment`](#save-attachment) may write (home, temp, `/Volumes`); symbolic links, non-regular files, invalid UTF-8 and files over 1 MiB are refused before anything is written. A leading byte-order mark is dropped |
-| `tags` | string[] | No | Returned-only metadata — **NOT written to Notes.app**. Apple Notes tags can't be set via AppleScript, so values passed here are echoed back in the response but do not appear on the created note. Use inline `#hashtags` in `content` instead (Notes.app turns those into real tags). Refused with `format: "markdown"` |
+| `tags` | string[] | No | Returned-only metadata — **NOT written to Notes.app**. Apple Notes tags can't be set via AppleScript, so values passed here are echoed back in the response but do not appear on the created note. Inline `#hashtags` in `content` stay searchable text and are returned as `hashtags`, but they do not become native Notes tags; add real tags afterwards with [`add-native-tags`](#add-native-tags). Refused with `format: "markdown"` |
 | `folder` | string | No | Folder to create the note in. Supports nested paths like `"Work/Clients"`. **The folder must already exist** — create it first with [`create-folder`](#create-folder). A smart folder is refused (see [`move-note`](#move-note)). Defaults to account root |
 | `account` | string | No | Account name (defaults to Notes.app's default account; matched exactly or by a *unique* prefix — an ambiguous prefix is refused). Must be an account Notes.app already has configured — see [`list-accounts`](#list-accounts) |
 | `format` | string | No | Content format: `"plaintext"` (default), `"html"`, or `"markdown"`. In all formats, the title is automatically prepended as the note's title line. In plaintext mode, newlines become `<br>`, tabs become `<br>`, and backslashes are preserved as HTML entities. `"markdown"` produces real Title/Heading/Subheading styles through a Shortcut; see [Markdown notes](#markdown-notes) |
 | `markdownRoute` | string | No | With `format: "markdown"` only: `"shortcut"` (default) or `"html"`. See [Markdown through HTML](#markdown-through-html) |
 | `timeoutSeconds` | number | No | Whole seconds, 1–120, for each Notes.app automation step this call runs; overrides `APPLE_NOTES_MCP_TIMEOUT_MS` for this call only. A timed-out write is uncertain, not failed: read the note by id before any retry. Also accepted by `get-note-content`, `update-note`, `append-to-note`, `delete-note` and `move-note` |
 
-**Example (tagged with inline hashtags):**
+**Example (with inline textual hashtags):**
 ```json
 {
   "title": "Meeting Notes",
@@ -587,8 +587,9 @@ base64 images larger than `APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES` (default
 image-heavy note cannot blow the MCP message limit. `structuredContent` reports
 this as `strippedImages` (count) and `truncated` (boolean). When either is set,
 passing this body to an unguarded full-body writer would replace the real images
-with placeholder text. This server refuses update and append operations on
-attachment-bearing notes; edit them in Notes.app.
+with placeholder text. This server's `update-note` refuses attachment-bearing
+notes, and `append-to-note` routes them to native end-append with `scopeText`,
+which never rewrites the existing body; make any other edit in Notes.app.
 
 ---
 

package/build/index.js

@@ -59329,7 +59329,7 @@ ${lines}${footer}`,
 registerTool(
   "get-note-content",
   {
-    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the exact note id, content, contentHash revision token, parsed hashtags, nativeTags, restored links, richContentComplete/writable, and strippedImages/truncated when the body was capped. Read the warning when writable is false.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.\nSafety: inline images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with '[inline image omitted: ...]' text placeholders, so the returned body is lossy whenever truncated is true. Mutations refuse attachment-bearing notes; edit those in Notes.app. Notes.app returns images inside the body as base64, so a note with a very large image can time out; the error then names the cause, and a larger timeoutSeconds gives the read more time.",
+    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the exact note id, content, contentHash revision token, parsed hashtags, nativeTags, restored links, richContentComplete/writable, and strippedImages/truncated when the body was capped. Read the warning when writable is false.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.\nSafety: inline images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with '[inline image omitted: ...]' text placeholders, so the returned body is lossy whenever truncated is true. For an attachment-bearing note, update-note refuses a full-body replacement; append-to-note with scopeText appends natively at the end and leaves attachments in place; add-attachment adds a file; move-note and delete-note work as usual. Make any other edit in Notes.app. Notes.app returns images inside the body as base64, so a note with a very large image can time out; the error then names the cause, and a larger timeoutSeconds gives the read more time.",
     inputSchema: {
       id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),

package/docs/APPLESCRIPT-LIMITATIONS.md

@@ -91,24 +91,28 @@ a note in a follow-up tool call, use the `id` returned by every read tool.
 
 ## Tags / hashtags (#29)
 
-**Status: parsed from the body, not first-class.** Apple Notes "tags" are inline
-`#hashtag` tokens you type into a note's text. They are **not** a scriptable
-property — the `note` class exposes no `tags` element, and the tag relationship
-lives only in Notes' private Core Data store. So the only way to surface a
-note's tags via AppleScript is to read them back out of the body text.
-
-This server does that: `get-note-content` parses the body and returns the tags
-as `hashtags` in its `structuredContent` (see `src/utils/hashtags.ts`). The
-rules match Notes' own behaviour — a token is `#` followed by letters/digits/
-underscores containing **at least one letter**, so `#123` is not a tag; tokens
-are de-duplicated case-insensitively.
+**Status: not scriptable; native tags go through Shortcuts.** A native Apple
+Notes tag is an inline tag attachment backed by an `ICHashtag` object in Notes'
+private Core Data store. It is **not** a scriptable property — the `note` class
+exposes no `tags` element — and `#word` text written through AppleScript stays
+plain text: Notes does not convert it into a native tag.
+
+This server therefore separates two things. `get-note-content` parses textual
+`#hashtag` tokens out of the body and returns them as `hashtags` (see
+`src/utils/hashtags.ts`); the rules match Notes' own — `#` followed by
+letters/digits/underscores containing **at least one letter**, so `#123` is not
+a tag; tokens are de-duplicated case-insensitively. Actual native tags are read
+from the database (`nativeTags`, `list-native-tags`, Full Disk Access) and
+written with `add-native-tags` / `remove-native-tags` / `replace-native-tag`,
+which drive the Notes Shortcuts action. A textual `hashtags` entry is not proof
+that Notes registered a native tag.
 
 Two related caveats:
 
 - The `tags` parameter on `create-note` is an application-level pass-through. It
   is stored on the returned object but Notes does **not** persist it, and it does
-  **not** create real `#hashtags` in the body. To make a real tag, put `#tag`
-  in the note content.
+  **not** create tags. Typing `#tag` into the content does not either; use
+  `add-native-tags` on the created note.
 - **Smart folders are not scriptable.** Notes' tag-driven Smart Folders cannot be
   created, read, or enumerated via AppleScript; there is no `smart folder` class
   in the dictionary. Only regular folders are scriptable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.9.20",
+  "version": "2.9.21",
   "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",