apple-notes-mcp 2.6.12 → 2.6.13

package/README.md

@@ -56,7 +56,7 @@ Install as a Claude Code plugin for automatic configuration and enhanced AI beha
 
 This method also installs a **skill** that teaches Claude when and how to use Apple Notes effectively.
 
-On the first tool call, macOS shows an Automation permission prompt ("Claude" wants access to control "Notes") — click **OK**. Optionally, grant **Full Disk Access** to the app that launches the server to enable the checklist-state and note-metadata features; see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md). Everything else works without it.
+On the first tool call, macOS shows an Automation permission prompt ("Claude" wants access to control "Notes") — click **OK**. Optionally, grant **Full Disk Access** to the app that launches the server to enable the database-backed tools (`get-checklist-state`, `get-note-metadata`, `get-note-link`, checklist annotations in `get-note-markdown`, and full `get-sync-status` detail); see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md). The rest of the server is pure AppleScript and works without it.
 
 ### Using the Codex Marketplace
 
@@ -153,14 +153,15 @@ Resources expose read-only context the client can attach without a tool call:
 `notes://note/{id}` template (returns the note as Markdown). Prompts package
 common workflows: `find-note`, `weekly-review`, `new-meeting-note`.
 
-### Known limitations
+### AppleScript limitations
 
-A few Notes UI features are not exposed to AppleScript and therefore cannot be
-supported. See **[docs/APPLESCRIPT-LIMITATIONS.md](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/APPLESCRIPT-LIMITATIONS.md)**
+A few Notes UI features are not exposed to AppleScript. Some are recovered by
+reading Notes' own database instead; the rest genuinely cannot be supported. See
+**[docs/APPLESCRIPT-LIMITATIONS.md](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/APPLESCRIPT-LIMITATIONS.md)**
 for the investigation and verification behind each:
 
 - **Pinned notes** — Notes has no scriptable `pinned` property via AppleScript. Pin state can now be **read** with the BETA `get-note-metadata` tool (from the NoteStore database), but it still cannot be **set** programmatically.
-- **Note-to-note links** — there is no `applenotes://` deep link or link property; the only stable handle is the `x-coredata://` note id.
+- **Note-to-note links** — AppleScript exposes no link property or link element, so link *relationships* between notes cannot be read, and a link cannot be inserted into a note body. A shareable `notes://showNote?identifier=<uuid>` deep link **is** available via [`get-note-link`](#get-note-link).
 
 ---
 
@@ -179,8 +180,8 @@ 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 | Yes | The body content of the note (do not repeat the title here) |
 | `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) |
-| `folder` | string | No | Folder to create the note in. Supports nested paths like `"Work/Clients"`. Defaults to account root |
-| `account` | string | No | Account name (defaults to iCloud) |
+| `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). Defaults to account root |
+| `account` | string | No | Account name (defaults to iCloud). Must be an account Notes.app already has configured — see [`list-accounts`](#list-accounts) |
 | `format` | string | No | Content format: `"plaintext"` (default) or `"html"`. In both formats, the title is automatically prepended as `<h1>`. In plaintext mode, newlines become `<br>`, tabs become `<br>`, and backslashes are preserved as HTML entities |
 
 **Example (tagged with inline hashtags):**
@@ -288,6 +289,16 @@ Retrieves the full content of a specific note.
 from the body. Apple Notes tags are inline hashtags, not a scriptable property;
 see [docs/APPLESCRIPT-LIMITATIONS.md](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/APPLESCRIPT-LIMITATIONS.md#tags--hashtags-29). Smart Folders are not scriptable.
 
+**⚠️ The returned body can be lossy — do not write it back verbatim.** Inline
+base64 images larger than `APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES` (default
+256 KB) are replaced with `[inline image omitted: …]` text placeholders so an
+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 [`update-note`](#update-note) would replace the real images
+with the placeholder text — use [`append-to-note`](#append-to-note) for
+additions, or export the images with `save-attachment` / `fetch-attachment`
+first.
+
 ---
 
 #### `get-note-plaintext`
@@ -415,7 +426,7 @@ Updates an existing note's content and/or title.
 
 **Returns:** Confirmation message, or error if note not found.
 
-**Note:** `newContent` **replaces the entire note body** — it is not appended. To preserve existing content, read it first (e.g. with `get-note-content`) and include it in `newContent`.
+**Note:** `newContent` **replaces the entire note body** — it is not appended. To add to a note, prefer [`append-to-note`](#append-to-note), which does the read-and-concatenate for you and always round-trips the body as HTML. If you do read-modify-write by hand, note that `get-note-content` replaces oversized inline images with text placeholders (see [`get-note-content`](#get-note-content)) — writing that body back bakes the placeholders in.
 
 **Attachments:** A full-body replace can drop embedded files, images, scans, PDFs, or audio. When a note may hold attachments, run [`list-attachments`](#list-attachments) first, and either save them with `save-attachment` or build a new note rather than overwriting. See the skill's [Attachment-Safe Updates](https://github.com/sweetrb/apple-notes-mcp/blob/main/skills/apple-notes/SKILL.md#attachment-safe-updates) guidance.
 
@@ -617,11 +628,11 @@ Lists all folders in an account with full hierarchical paths.
 
 #### `create-folder`
 
-Creates a new folder.
+Creates a new folder, including a whole nested hierarchy in one call.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `name` | string | Yes | Name for the new folder |
+| `name` | string | Yes | Folder name, or a nested path separated by `/` (e.g. `"Retro Tech/PC/CPUs"`). Every intermediate folder is created; segments that already exist are skipped |
 | `account` | string | No | Account to create folder in (defaults to iCloud) |
 
 **Example:**
@@ -631,7 +642,14 @@ Creates a new folder.
 }
 ```
 
-**Returns:** Confirmation message, or error if folder already exists.
+**Example - Create a nested hierarchy:**
+```json
+{
+  "name": "Work/Clients/Omnia"
+}
+```
+
+**Returns:** Confirmation message. The call is **idempotent** — an already-existing folder (or path segment) is skipped rather than treated as an error, so it is safe to call before every `create-note` that targets a folder.
 
 ---
 
@@ -718,7 +736,7 @@ Deletes multiple notes at once by ID.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `ids` | string[] | Yes | Array of note IDs to delete |
+| `ids` | string[] | Yes | Array of note IDs to delete (max 500 per request) |
 
 **Returns:** Summary of successes and failures.
 
@@ -732,8 +750,8 @@ Moves multiple notes to a folder.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `ids` | string[] | Yes | Array of note IDs to move |
-| `folder` | string | Yes | Destination folder name or nested path (e.g., `"Work/Clients"`) |
+| `ids` | string[] | Yes | Array of note IDs to move (max 500 per request) |
+| `folder` | string | Yes | Destination folder name or nested path (e.g., `"Work/Clients"`). Must already exist — create it with [`create-folder`](#create-folder) |
 | `account` | string | No | Account containing the folder |
 
 **Returns:** Summary of successes and failures.
@@ -770,7 +788,7 @@ Gets a note's content as Markdown instead of HTML. If the note contains checklis
 
 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.
 
-**Requires:** Full Disk Access for the MCP host process (see [Full Disk Access Setup](#full-disk-access-for-checklist-features)).
+**Requires:** Full Disk Access for the MCP host process (see [Full Disk Access Setup](#full-disk-access)).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -798,7 +816,7 @@ Checklist for "Shopping List" (2/4 done):
 
 Reads note metadata that AppleScript cannot expose, by querying the NoteStore SQLite database directly: pinned state, checklist flags, trash/recovery state, the preview snippet, and the password hint. The available fields vary by macOS version.
 
-**Requires:** Full Disk Access for the MCP host process (see [Full Disk Access Setup](#full-disk-access-for-checklist-features)).
+**Requires:** Full Disk Access for the MCP host process (see [Full Disk Access Setup](#full-disk-access)).
 
 **BETA:** the NoteStore schema changes between macOS releases, so some fields can be absent on older or newer systems. The database is only ever read, never written.
 
@@ -1063,9 +1081,9 @@ MCP stores no secrets, but as a general rule keep only non-secret config here.
 
 ---
 
-## Full Disk Access for Checklist Features
+## Full Disk Access
 
-The `get-checklist-state` tool and checklist annotations in `get-note-markdown` read directly from the Apple Notes SQLite database. This requires **Full Disk Access** for the process running the MCP server.
+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`.
 
 > 📘 **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.
 
@@ -1083,9 +1101,12 @@ The `get-checklist-state` tool and checklist annotations in `get-note-markdown`
 
 ### Without Full Disk Access
 
-All other tools work normally without Full Disk Access. Only checklist state features are affected:
-- `get-checklist-state` will return an error explaining that database access is needed
-- `get-note-markdown` will return plain list items without `[x]`/`[ ]` annotations (graceful fallback)
+Every tool that does not read the Notes database works normally without Full Disk Access — that is the whole AppleScript surface (create, read, search, update, move, delete, folders, accounts, attachments, stats, export). The database-backed tools degrade like this:
+- `get-checklist-state` returns an error explaining that database access is needed
+- `get-note-metadata` returns the same kind of error — it has no non-database path
+- `get-note-link` returns an error on macOS 26+; on macOS 12–15 it still works via the AppleScript `note link` fallback
+- `get-note-markdown` returns plain list items without `[x]`/`[ ]` annotations (graceful fallback)
+- `get-sync-status` still answers, but reports no pending uploads and no active sync — treat that as "unknown", not "idle"
 
 ---
 
@@ -1104,21 +1125,12 @@ All other tools work normally without Full Disk Access. Only checklist state fea
 |------------|--------|
 | macOS only | Apple Notes and AppleScript are macOS-specific |
 | Batch ops run per-note | `batch-delete-notes` / `batch-move-notes` apply each note individually rather than as one bulk operation — AppleScript has no bulk equivalent to IMAP's `UID STORE`/`MOVE`. This is deliberate: it preserves per-note success/failure reporting. ([#26](https://github.com/sweetrb/apple-notes-mcp/issues/26)) |
-| No pinned notes | Pin status is not exposed via AppleScript ([#28](https://github.com/sweetrb/apple-notes-mcp/issues/28)) |
+| Pinned notes are read-only | AppleScript exposes no `pinned` property. Pin state is readable via the BETA `get-note-metadata` tool (NoteStore database, needs Full Disk Access) but cannot be set ([#28](https://github.com/sweetrb/apple-notes-mcp/issues/28)) |
 | Limited rich formatting | Use `format: "html"` on create/update for headings, lists, bold, code blocks; some complex formatting may not render |
 | Title matching | Most operations require exact title matches |
 | Checklist state | Requires [Full Disk Access](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md) to read done/undone state from the database |
 | Checklist **creation** | Not supported. AppleScript's `body of note` setter strips `<input type="checkbox">` and ignores any checklist-styling CSS class. Apple Notes stores checklist items as a protobuf paragraph style (`style_type=103`) that AppleScript doesn't expose, and the SQLite database is read-only. See [Creating Checklists](#creating-checklists) below for the workaround. |
 
-### Roadmap
-
-A few capabilities are deliberately deferred to a future release, tracked as open issues:
-
-- **Pinned-note support** ([#28](https://github.com/sweetrb/apple-notes-mcp/issues/28)) — Apple doesn't expose pin status via AppleScript.
-- **Tags / hashtags** ([#29](https://github.com/sweetrb/apple-notes-mcp/issues/29)).
-- **Note links** ([#30](https://github.com/sweetrb/apple-notes-mcp/issues/30)).
-- **Local integration-test suite** ([#31](https://github.com/sweetrb/apple-notes-mcp/issues/31)).
-
 ### Creating Checklists
 
 **There is no programmatic way to create a true Apple Notes checklist via AppleScript** — and therefore no way via this MCP server. This is an Apple limitation, not a bug.

package/build/index.js

@@ -38669,6 +38669,14 @@ var StdioServerTransport = class {
 
 // src/utils/applescript.ts
 import { execFileSync } from "child_process";
+
+// src/utils/docsUrls.ts
+var FULL_DISK_ACCESS_GUIDE_URL = "https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md";
+var NODE_RUNTIME_TCC_GUIDE_URL = "https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md";
+var AUTOMATION_PERMISSION_GUIDE_URL = "https://github.com/sweetrb/apple-notes-mcp#permission-denied";
+var AUTOMATION_REMEDIATION = `Grant automation access in System Settings > Privacy & Security > Automation to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it \u2014 run the doctor tool to verify. See: ${AUTOMATION_PERMISSION_GUIDE_URL}`;
+
+// src/utils/applescript.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
 function envPositiveNumber(name) {
@@ -38732,7 +38740,7 @@ var ERROR_MAPPINGS = [
   // Permission errors
   {
     pattern: /not authorized|not permitted|access.*denied/i,
-    message: "Permission denied. Grant automation access in System Settings > Privacy & Security > Automation."
+    message: `Permission denied. ${AUTOMATION_REMEDIATION}`
   },
   // Application not running
   {
@@ -39000,10 +39008,6 @@ function embeddedMessage(field) {
   return decodeMessage(bytes);
 }
 
-// src/utils/docsUrls.ts
-var FULL_DISK_ACCESS_GUIDE_URL = "https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md";
-var NODE_RUNTIME_TCC_GUIDE_URL = "https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md";
-
 // src/utils/checklistParser.ts
 var CHECKLIST_STYLE_TYPE = 103;
 var NOTES_DB_PATH = path.join(
@@ -40722,7 +40726,7 @@ var AppleNotesManager = class {
       checks.push({
         name: "permissions",
         passed: !isPermError,
-        message: isPermError ? "AppleScript permissions denied. Grant access in System Settings > Privacy & Security > Automation" : `Permission check returned: ${permCheck.error}`
+        message: isPermError ? `AppleScript permissions denied. ${AUTOMATION_REMEDIATION}` : `Permission check returned: ${permCheck.error}`
       });
       if (isPermError) {
         return { healthy: false, checks };
@@ -41833,7 +41837,7 @@ function strippedImagesWarning(stripped) {
 
 \u26A0\uFE0F ${stripped.strippedCount} inline ${plural} (~${formatBytes(
     stripped.strippedBytes
-  )} decoded) exceeded the per-image inline cap and ${stripped.strippedCount === 1 ? "was" : "were"} replaced with placeholders so the response stays within MCP message limits. The images are still in the note: use list-attachments with save-attachment or fetch-attachment to export them, or raise APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES.`;
+  )} decoded) exceeded the per-image inline cap and ${stripped.strippedCount === 1 ? "was" : "were"} replaced with placeholders so the response stays within MCP message limits. This body is therefore lossy \u2014 do NOT write it back with update-note, or the real images are replaced by the placeholder text; use append-to-note to add content. The images are still in the note: use list-attachments with save-attachment or fetch-attachment to export them, or raise APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES.`;
 }
 
 // src/utils/updateResponseTitle.ts
@@ -41924,7 +41928,7 @@ function runDoctor(manager) {
   checks.push({
     name: "Full Disk Access",
     status: fda ? "ok" : "warn",
-    detail: fda ? "granted \u2014 checklist features available" : `not granted \u2014 get-checklist-state and checklist annotations in get-note-markdown won't work. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it and re-run doctor. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`
+    detail: fda ? "granted \u2014 the Notes database is readable (checklist state, note metadata, note links, sync detail)" : `not granted \u2014 get-checklist-state, get-note-metadata, and the checklist annotations in get-note-markdown won't work; get-note-link fails on macOS 26+ (macOS 12-15 falls back to AppleScript); get-sync-status still answers but cannot see pending uploads. Everything else is pure AppleScript and is unaffected. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it and re-run doctor. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`
   });
   checks.push(checkNodeRuntimeSignature());
   const healthy = !checks.some((c) => c.status === "fail");
@@ -42125,7 +42129,7 @@ var folderNameSchema = {
 server.registerTool(
   "create-note",
   {
-    description: "Use when: the user wants to create a brand-new Apple Note.\nReturns: the new note's title and id \u2014 reuse the id for follow-up reads/edits.\nDo not use when: editing an existing note (use update-note).\nNote: the title is prepended as an <h1>; true Apple Notes checklists cannot be created via AppleScript (see the content field).",
+    description: "Use when: the user wants to create a brand-new Apple Note.\nReturns: the new note's title and id \u2014 reuse the id for follow-up reads/edits.\nDo not use when: editing an existing note (use update-note).\nNote: the title is prepended as an <h1>; true Apple Notes checklists cannot be created via AppleScript (see the content field). A 'folder' must already exist \u2014 create-folder first (it is idempotent), since this tool does not create it.",
     inputSchema: {
       title: external_exports.string().min(1, "Title is required").max(MAX.TITLE),
       content: external_exports.string().min(1, "Content is required").max(MAX.CONTENT).describe(
@@ -42135,8 +42139,12 @@ server.registerTool(
       tags: external_exports.array(external_exports.string().max(MAX.TAG)).max(MAX.TAGS).optional().describe(
         "Returned-only metadata \u2014 NOT written to Notes.app. Apple Notes tags can't be set via AppleScript, so any values passed here are echoed back in the response but do not appear on the created note. Use #hashtags inside the content body instead (Notes.app turns those into real tags)."
       ),
-      folder: external_exports.string().max(MAX.FOLDER).optional().describe("Folder to create the note in (supports nested paths like 'Work/Clients')"),
-      account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account name (defaults to iCloud)")
+      folder: external_exports.string().max(MAX.FOLDER).optional().describe(
+        "Folder to create the note in (supports nested paths like 'Work/Clients'). The folder must already exist \u2014 this tool does not create it; call create-folder first, which is idempotent and creates intermediate segments."
+      ),
+      account: external_exports.string().max(MAX.ACCOUNT).optional().describe(
+        "Account name (defaults to iCloud). Must be an account Notes.app already has configured \u2014 see list-accounts."
+      )
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -42149,8 +42157,9 @@ server.registerTool(
   withErrorHandling(({ title, content, format = "plaintext", tags = [], folder, account }) => {
     const note = notesManager.createNote(title, content, tags, folder, account, format);
     if (!note) {
+      const target = folder ? ` Most often the folder "${folder}" does not exist: run list-folders to check, then create-folder to create it (it is idempotent and creates intermediate segments).` : account ? ` Most often the account "${account}" is not configured in Notes.app: run list-accounts to check the exact name.` : "";
       return errorResponse(
-        `Failed to create note "${title}". Check that Notes.app is configured and accessible.`
+        `Failed to create note "${title}".${target} Otherwise check that Notes.app is running and this server has Automation access (run the doctor tool).`
       );
     }
     const checklistWarning = detectChecklistAttempt(content) ?? "";
@@ -42239,7 +42248,7 @@ ${noteList}${truncationNote}${syncNote}`,
 server.registerTool(
   "get-note-content",
   {
-    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the note's content plus parsed hashtags.\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.",
+    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the note's content plus parsed hashtags, and strippedImages/truncated when the body was capped.\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 \u2014 do NOT write it back with update-note or the real images are replaced by that text. Use append-to-note to add content, or export the images with save-attachment / fetch-attachment first.",
     inputSchema: {
       id: external_exports.string().max(MAX.ID).optional().describe("Note ID (preferred - more reliable than title)"),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
@@ -42248,7 +42257,11 @@ server.registerTool(
     outputSchema: {
       title: external_exports.string().optional(),
       content: external_exports.string().optional(),
-      hashtags: external_exports.array(external_exports.string()).optional()
+      hashtags: external_exports.array(external_exports.string()).optional(),
+      /** Number of oversized inline images replaced with text placeholders. */
+      strippedImages: external_exports.number().optional(),
+      /** True when content is lossy — see strippedImages. Never write a truncated body back. */
+      truncated: external_exports.boolean().optional()
     }
   },
   withErrorHandling(({ id, title, account }) => {
@@ -42273,7 +42286,9 @@ server.registerTool(
       return successResponse(warning2 ? content2 + warning2 : content2, {
         title: note2.title,
         content: content2,
-        hashtags: hashtags2
+        hashtags: hashtags2,
+        strippedImages: stripped2.strippedCount,
+        truncated: stripped2.strippedCount > 0
       });
     }
     if (!title) {
@@ -42296,7 +42311,13 @@ server.registerTool(
     const content = stripped.html;
     const hashtags = parseHashtags(content);
     const warning = strippedImagesWarning(stripped);
-    return successResponse(warning ? content + warning : content, { title, content, hashtags });
+    return successResponse(warning ? content + warning : content, {
+      title,
+      content,
+      hashtags,
+      strippedImages: stripped.strippedCount,
+      truncated: stripped.strippedCount > 0
+    });
   }, "Error retrieving note content")
 );
 server.registerTool(
@@ -42437,7 +42458,7 @@ server.registerTool(
 server.registerTool(
   "get-note-link",
   {
-    description: "Use when: you need the notes:// deep-link URL for a note so it can be stored in a Reminders task, shared, or opened directly.\nReturns: a notes://showNote?identifier=<uuid> URL that opens the note in Notes.app on iOS and macOS.\nDo not use when: you only need the note's CoreData id (get-note-by-id) or want to reveal the note on screen (show-note).\nNote: requires macOS 12+; returns an error on older systems.",
+    description: "Use when: you need the notes:// deep-link URL for a note so it can be stored in a Reminders task, shared, or opened directly.\nReturns: a notes://showNote?identifier=<uuid> URL that opens the note in Notes.app on iOS and macOS.\nDo not use when: you only need the note's CoreData id (get-note-by-id) or want to reveal the note on screen (show-note).\nNote: the primary path reads the note's identifier from the Notes database, so it needs Full Disk Access for the app that launches this server; macOS 12-15 can fall back to the AppleScript 'note link' property, which macOS 26+ no longer exposes. Password-protected notes cannot be linked.",
     inputSchema: {
       id: external_exports.string().max(MAX.ID).optional().describe("Note ID (preferred - more reliable than title)"),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
@@ -43132,7 +43153,7 @@ server.registerTool(
       return `  ${icon} ${c.name}: ${c.message}`;
     }).join("\n");
     const fdaAvailable = hasFullDiskAccess();
-    const fdaLine = fdaAvailable ? "  \u2713 full_disk_access: Granted (checklist features available)" : `  \u24D8 full_disk_access: Not granted (optional \u2014 needed for get-checklist-state and checklist annotations in get-note-markdown). In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
+    const fdaLine = fdaAvailable ? "  \u2713 full_disk_access: Granted (Notes database readable \u2014 checklist state, note metadata, note links, sync detail)" : `  \u24D8 full_disk_access: Not granted \u2014 get-checklist-state, get-note-metadata, and the checklist annotations in get-note-markdown won't work; get-note-link fails on macOS 26+ (macOS 12-15 falls back to AppleScript); get-sync-status cannot see pending uploads. The rest of the server is pure AppleScript and is unaffected. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
     return successResponse(`${statusIcon} ${statusText}
 
 ${checkLines}
@@ -43263,7 +43284,7 @@ server.registerTool(
   {
     description: "Use when: permanently deleting multiple notes by id in one call.\nReturns: per-id success/failure counts.\nDo not use when: deleting a single note (delete-note).\nSafety: requires explicit user confirmation; this is destructive and not undoable. Prefer search-notes/list-notes first to confirm the exact ids being deleted.",
     inputSchema: {
-      ids: external_exports.array(external_exports.string().max(MAX.ID)).max(MAX.BATCH_IDS).describe("Array of note IDs to delete")
+      ids: external_exports.array(external_exports.string().max(MAX.ID)).max(MAX.BATCH_IDS).describe(`Array of note IDs to delete (max ${MAX.BATCH_IDS} per request)`)
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -43299,8 +43320,10 @@ server.registerTool(
   {
     description: "Use when: moving multiple notes by id into one destination folder.\nReturns: per-id success/failure counts.\nDo not use when: moving a single note (move-note).\nNote: the destination folder must already exist (create-folder).",
     inputSchema: {
-      ids: external_exports.array(external_exports.string().max(MAX.ID)).max(MAX.BATCH_IDS).describe("Array of note IDs to move"),
-      folder: external_exports.string().max(MAX.FOLDER).describe("Destination folder name"),
+      ids: external_exports.array(external_exports.string().max(MAX.ID)).max(MAX.BATCH_IDS).describe(`Array of note IDs to move (max ${MAX.BATCH_IDS} per request)`),
+      folder: external_exports.string().max(MAX.FOLDER).describe(
+        'Destination folder name or nested path (e.g. "Work/Clients"). Must already exist \u2014 create-folder first.'
+      ),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account containing the destination folder (defaults to iCloud)")
     },
     outputSchema: {

package/docs/APPLESCRIPT-LIMITATIONS.md

@@ -1,10 +1,12 @@
 # AppleScript Limitations
 
 Apple Notes is automated through its AppleScript dictionary. A few features that
-exist in the Notes UI are simply **not exposed to AppleScript**, so this MCP
-server cannot read or write them no matter how the script is written. This page
-documents what was investigated, how it was verified, and the conclusion, so the
-limitation isn't re-investigated every release.
+exist in the Notes UI are simply **not exposed to AppleScript**, so no script can
+read or write them. Where this server recovers one of them anyway, it does so by
+reading Notes' private `NoteStore.sqlite` store **read-only** — which needs
+[Full Disk Access](./FULL-DISK-ACCESS.md). Each section below says which case it
+is. This page documents what was investigated, how it was verified, and the
+conclusion, so the limitation isn't re-investigated every release.
 
 The full set of properties Notes exposes on a `note` is:
 
@@ -17,9 +19,9 @@ shared, body, id, name, plaintext
 
 ## Pinned notes (#28)
 
-**Status: not feasible via AppleScript.** The Notes UI lets you pin a note to
-the top of a folder, but the `note` class has no `pinned` property. Asking for
-it raises error `-1700`:
+**Status: not feasible via AppleScript; readable via the NoteStore database.**
+The Notes UI lets you pin a note to the top of a folder, but the `note` class
+has no `pinned` property. Asking for it raises error `-1700`:
 
 ```applescript
 tell application "Notes"
@@ -31,41 +33,61 @@ end tell
 There is no alternative property, element, or command (`pin`, `pinned`,
 `favorite`, …) in the dictionary. Pinned state lives only in Notes' private
 Core Data store (`NoteStore.sqlite`), which is not part of the scriptable
-surface. Reading it would require parsing the SQLite store directly — brittle
-across macOS releases and outside what an AppleScript-based server should do —
-and there is no supported way to *set* it at all.
+surface, and there is no supported way to *set* it at all.
 
-**Conclusion:** pinned read/write is not supported and will not be added while
-Notes lacks a scriptable property. If a future macOS exposes one, revisit by
-re-running the probe above.
+Reading it, however, did turn out to be worth doing. Since 2.5.0 the BETA
+`get-note-metadata` tool queries `ZISPINNED` on `ZICCLOUDSYNCINGOBJECT` in that
+store, opened **read-only**, feature-detecting each column with
+`PRAGMA table_info` so it degrades instead of breaking when the private schema
+changes across macOS releases. It requires
+[Full Disk Access](./FULL-DISK-ACCESS.md) and is marked BETA precisely because
+the schema is version-dependent.
+
+**Conclusion:** pin state is **readable** (BETA, from the NoteStore database,
+Full Disk Access required) but **not settable** — and setting will not be added
+while Notes lacks a scriptable property. If a future macOS exposes one, revisit
+by re-running the probe above.
 
 ## Note-to-note links (#30)
 
-**Status: not supported as data; navigation-only.** Apple Notes lets you insert
-a link from one note to another in the UI, but AppleScript exposes no property
-or element for it:
+**Status: link *relationships* are not exposed; a shareable deep link is.**
+Apple Notes lets you insert a link from one note to another in the UI, but
+AppleScript exposes no property or element for that relationship:
 
 - A `note` has no `URL`, `url`, or `link` property — each raises error `-2753`
   (undefined). There is no element that enumerates outgoing/incoming links.
-- There is no readable or constructable `applenotes://` / `notes://` deep link.
-  The note's `id` (`x-coredata://…/ICNote/p123`) is the only stable handle, and
-  it is a Core Data URI, not a shareable or clickable link.
+- Nothing in the dictionary inserts a link into a note's body.
+
+A shareable deep link to a note *is* available, and has been since 2.6.0:
+`get-note-link` returns a `notes://showNote?identifier=<uuid>` URL that opens
+the note in Notes.app on macOS and iOS.
+
+- **Primary path — the NoteStore database.** The UUID in that URL is
+  `ZIDENTIFIER` on `ZICCLOUDSYNCINGOBJECT`, read **read-only** from
+  `NoteStore.sqlite`. This works on every macOS version but needs
+  [Full Disk Access](./FULL-DISK-ACCESS.md).
+- **Fallback — AppleScript.** On macOS 12–15 the Notes dictionary does expose a
+  two-word `note link` property, used when the database read fails. It is absent
+  from the Notes SDEF on macOS 26+, which is why the database is the primary
+  path. (`note link` is a different term from the `URL` / `url` / `link` names
+  probed above, which genuinely do not exist.)
+- Password-protected notes return no link.
 
-The one related capability that *does* work is the `show` command, which reveals
-a note in the Notes UI by id:
+The `show` command reveals an object in the Notes UI by id:
 
 ```applescript
 tell application "Notes" to show note id "x-coredata://…/ICNote/p123"
 ```
 
-This is deliberately **not** wrapped as a tool: it pops the GUI (unhelpful for a
-headless server), and an agent already has the note's content via
-`get-note-content` / `get-note-markdown`. Link relationships between notes
-cannot be read at all, so a "list links in this note" feature is not possible.
+It **is** wrapped, as `show-note`, `show-folder`, `show-account`, and
+`show-attachment`. Those tools activate the Notes.app GUI, so they only do
+something useful on a machine with an active desktop session; to read a note's
+content, use `get-note-content` / `get-note-markdown` instead.
 
-**Conclusion:** note-to-note link data is not exposed and cannot be surfaced.
-The `id` field already returned by every read tool is the canonical reference;
-use that to address a specific note.
+**Conclusion:** link relationships between notes cannot be read, so a "list
+links in this note" feature is not possible, and links cannot be inserted into a
+body. To hand a note to a person or another app, use `get-note-link`; to address
+a note in a follow-up tool call, use the `id` returned by every read tool.
 
 ## Tags / hashtags (#29)
 

package/docs/FULL-DISK-ACCESS.md

@@ -1,12 +1,21 @@
-# Full Disk Access for Checklist Features
+# Full Disk Access
 
-Apple Notes MCP works almost entirely without any special disk permission. **One
-feature area** needs **Full Disk Access (FDA)** for the process that runs the MCP
-server:
+Apple Notes MCP works almost entirely without any special disk permission. The
+tools that need **Full Disk Access (FDA)** for the process that runs the MCP
+server are the ones that read Notes' own SQLite store:
 
 - **`get-checklist-state`** — reads a note's checklist done/undone state.
 - **Checklist annotations in `get-note-markdown`** — the `[x]` / `[ ]` prefixes on
   checklist items.
+- **`get-note-metadata` (BETA)** — pinned state, checklist flags, trash/recovery
+  state, snippets, password hint. These columns exist nowhere else, so this tool
+  needs FDA unconditionally.
+- **`get-note-link`** — its primary path reads the note's `ZIDENTIFIER` from the
+  database. On macOS 12–15 it can fall back to the AppleScript `note link`
+  property; that property is absent from the Notes SDEF on macOS 26+, so there
+  FDA is the only route.
+- **`get-sync-status`** — degrades rather than fails: without database access it
+  cannot see pending uploads or recent write activity.
 
 Everything else (creating, reading, searching, updating, moving, deleting notes;
 folders, accounts, attachments, stats, export, etc.) works **without** Full Disk
@@ -17,7 +26,9 @@ Access.
 Apple Notes stores checklist items as a paragraph style inside a gzipped protobuf
 blob in its SQLite store, `NoteStore.sqlite`. AppleScript's `body of note`
 interface strips that state — it can't tell you whether a checklist item is
-checked. To recover it, the MCP reads the SQLite store directly.
+checked. The same store also holds the pinned/trash/snippet columns behind
+`get-note-metadata` and the `ZIDENTIFIER` value behind `get-note-link`. To
+recover any of them, the MCP reads the SQLite store directly.
 
 That database lives in a macOS-protected directory:
 
@@ -26,9 +37,8 @@ That database lives in a macOS-protected directory:
 ```
 
 Reading anything under `~/Library/Group Containers/` requires **Full Disk
-Access** for the host process — without it, macOS denies the read and the MCP
-cannot parse checklist state. (The MCP only ever **reads** this database; it never
-writes to it.)
+Access** for the host process — without it, macOS denies the read. (The MCP only
+ever **reads** this database; it never writes to it.)
 
 ## How to grant Full Disk Access
 
@@ -64,9 +74,16 @@ The server degrades gracefully — nothing crashes:
 
 - `get-checklist-state` returns a clear error explaining that database access is
   needed (and points here).
+- `get-note-metadata` returns the same kind of error — it has no non-database
+  path, so it cannot answer at all without FDA.
+- `get-note-link` returns an error on macOS 26+. On macOS 12–15 it still works,
+  via the AppleScript `note link` fallback.
 - `get-note-markdown` still returns the note as Markdown, but checklist items
   appear as plain list items without the `[x]`/`[ ]` annotations.
-- **All other tools work normally.**
+- `get-sync-status` still answers, but with no database visibility it reports no
+  pending uploads and no active sync — treat that as "unknown", not "idle".
+- **Every other tool works normally**, since the rest of the server is pure
+  AppleScript.
 
 See also: [Known Limitations](../README.md#known-limitations) and
 [Creating Checklists](../README.md#creating-checklists) in the README.

package/docs/STABILITY-PERF-AUDIT-2026-06-19.md

@@ -11,29 +11,33 @@ of code already hardened in apple-mail. Line numbers are against `main` @ `bb677
 
 ## Resolution status
 
+All seventeen findings are closed; issues #16–#32 are all closed on GitHub. The
+body below is kept as the dated 1.4.4 snapshot that motivated the 2.0 line — it
+describes the code as it was on 2026-06-19, **not** as it is today.
+
 | # | Finding | Tier | Issue | Status |
 |---|---------|------|-------|--------|
-| H1 | `execSync` has no `maxBuffer` cap | High | [#16](https://github.com/sweetrb/apple-notes-mcp/issues/16) | Open |
-| H2 | No `with timeout` + SIGTERM wedges Notes.app | High | [#17](https://github.com/sweetrb/apple-notes-mcp/issues/17) | Open |
-| H3 | Printable `\|\|\|` / comma delimiters collide with user content | High | [#18](https://github.com/sweetrb/apple-notes-mcp/issues/18) | Open |
-| H4 | Swallowed failures return `[]`/`null`/`0` | High | [#19](https://github.com/sweetrb/apple-notes-mcp/issues/19) | Open |
-| H5 | Unbounded full-library scans, no partial-result signal | High | [#20](https://github.com/sweetrb/apple-notes-mcp/issues/20) | Open |
-| M1 | No `structuredContent` on any tool | Medium | [#21](https://github.com/sweetrb/apple-notes-mcp/issues/21) | Open |
-| M2 | No `doctor` tool (incl. Full Disk Access check) | Medium | [#22](https://github.com/sweetrb/apple-notes-mcp/issues/22) | Open |
-| M3 | No MCP resources or prompts | Medium | [#23](https://github.com/sweetrb/apple-notes-mcp/issues/23) | Open |
-| M4 | No file-based config loader | Medium | [#24](https://github.com/sweetrb/apple-notes-mcp/issues/24) | Open |
-| M5 | Locale-fragile date parsing | Medium | [#25](https://github.com/sweetrb/apple-notes-mcp/issues/25) | Open |
-| M6 | Batch ops are N+1 osascript fan-out | Medium | [#26](https://github.com/sweetrb/apple-notes-mcp/issues/26) | Open |
-| M7 | No `save-attachment` / `fetch-attachment` | Medium | [#27](https://github.com/sweetrb/apple-notes-mcp/issues/27) | Open |
-| L1 | Pinned notes not exposed | Low | [#28](https://github.com/sweetrb/apple-notes-mcp/issues/28) | Open |
-| L2 | Tags/hashtags not surfaced | Low | [#29](https://github.com/sweetrb/apple-notes-mcp/issues/29) | Open |
-| L3 | Note-to-note links not supported | Low | [#30](https://github.com/sweetrb/apple-notes-mcp/issues/30) | Open |
-| L5 | No integration test suite | Low | [#31](https://github.com/sweetrb/apple-notes-mcp/issues/31) | Open |
-| L6 | Full Disk Access guide + commit this audit | Low | [#32](https://github.com/sweetrb/apple-notes-mcp/issues/32) | Open |
-
-Target release for the fixes: **2.0.0** (full parity with apple-mail), built on a
-long-lived `v2` branch, one item at a time with tests, then full regression +
-docs + merge.
+| H1 | `execSync` has no `maxBuffer` cap | High | [#16](https://github.com/sweetrb/apple-notes-mcp/issues/16) | Shipped 2.0.0 (64 MB default, `APPLE_NOTES_MCP_MAX_BUFFER`) |
+| H2 | No `with timeout` + SIGTERM wedges Notes.app | High | [#17](https://github.com/sweetrb/apple-notes-mcp/issues/17) | Shipped 2.0.0 (`with timeout` wrap + `killSignal: SIGKILL`) |
+| H3 | Printable `\|\|\|` / comma delimiters collide with user content | High | [#18](https://github.com/sweetrb/apple-notes-mcp/issues/18) | Shipped 2.0.0 (ASCII `\x1f` / `\x1e` delimiters) |
+| H4 | Swallowed failures return `[]`/`null`/`0` | High | [#19](https://github.com/sweetrb/apple-notes-mcp/issues/19) | Shipped 2.0.0 (failures surface as MCP errors) + 2.1.0 (`get-notes-stats` partial-coverage reporting) |
+| H5 | Unbounded full-library scans, no partial-result signal | High | [#20](https://github.com/sweetrb/apple-notes-mcp/issues/20) | Shipped 2.0.0 (server-side counting) |
+| M1 | No `structuredContent` on any tool | Medium | [#21](https://github.com/sweetrb/apple-notes-mcp/issues/21) | Shipped 2.0.0, completed 2.2.0 (all tools) and 2.3.0 (`outputSchema` on all tools) |
+| M2 | No `doctor` tool (incl. Full Disk Access check) | Medium | [#22](https://github.com/sweetrb/apple-notes-mcp/issues/22) | Shipped 2.0.0 |
+| M3 | No MCP resources or prompts | Medium | [#23](https://github.com/sweetrb/apple-notes-mcp/issues/23) | Shipped 2.0.0 |
+| M4 | No file-based config loader | Medium | [#24](https://github.com/sweetrb/apple-notes-mcp/issues/24) | Shipped 2.0.0 |
+| M5 | Locale-fragile date parsing | Medium | [#25](https://github.com/sweetrb/apple-notes-mcp/issues/25) | Shipped 2.0.0 |
+| M6 | Batch ops are N+1 osascript fan-out | Medium | [#26](https://github.com/sweetrb/apple-notes-mcp/issues/26) | Shipped 2.1.0 (one osascript spawn per batch; explicitly deferred in 2.0.0) |
+| M7 | No `save-attachment` / `fetch-attachment` | Medium | [#27](https://github.com/sweetrb/apple-notes-mcp/issues/27) | Shipped 2.0.0 |
+| L1 | Pinned notes not exposed | Low | [#28](https://github.com/sweetrb/apple-notes-mcp/issues/28) | Partial — AppleScript infeasibility documented 2.1.0 ([APPLESCRIPT-LIMITATIONS](./APPLESCRIPT-LIMITATIONS.md)); pin state made **readable** in 2.5.0 via the BETA `get-note-metadata` NoteStore path. Setting is still unsupported |
+| L2 | Tags/hashtags not surfaced | Low | [#29](https://github.com/sweetrb/apple-notes-mcp/issues/29) | Shipped 2.1.0, read-only — `get-note-content` parses inline `#hashtags`; `create-note`'s `tags` param stays a cosmetic pass-through |
+| L3 | Note-to-note links not supported | Low | [#30](https://github.com/sweetrb/apple-notes-mcp/issues/30) | Partial — closed 2.1.0 as documented-infeasible, then superseded in 2.6.0 by `get-note-link` (`notes://showNote?identifier=<uuid>`). Reading link *relationships*, and inserting a link, remain infeasible |
+| L5 | No integration test suite | Low | [#31](https://github.com/sweetrb/apple-notes-mcp/issues/31) | Shipped 2.1.0 (`test/integration.test.ts` + the required `integration` CI job) |
+| L6 | Full Disk Access guide + commit this audit | Low | [#32](https://github.com/sweetrb/apple-notes-mcp/issues/32) | Shipped 2.0.0 ([FULL-DISK-ACCESS.md](./FULL-DISK-ACCESS.md)) |
+
+The fixes landed across the 2.0.0–2.6.x line rather than in a single release;
+per-item detail is in [CHANGELOG.md](../CHANGELOG.md). This document is retained
+as a historical record and is not a live backlog.
 
 ---
 

package/package.json

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