apple-notes-mcp 2.5.5 → 2.5.6

package/README.md

@@ -431,7 +431,7 @@ Deletes a note (moves to Recently Deleted in Notes.app).
 
 #### `move-note`
 
-Moves a note to a different folder.
+Moves a note to a different folder. The note is relocated in place via Notes.app's native `move`, so its id, creation date, and all embedded attachments (files, images, scans, PDFs, audio) are preserved. The destination folder must already exist — create it first with [`create-folder`](#create-folder).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -942,6 +942,7 @@ All configuration is optional — the server works out of the box. Override beha
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `APPLE_NOTES_MCP_MAX_BUFFER` | `67108864` (64 MB) | Max bytes captured from a single AppleScript invocation. Raise it if a very large export/list is truncated; lower it to cap memory. |
+| `APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES` | `26214400` (25 MB) | Max size of an attachment that [`fetch-attachment`](#fetch-attachment) will base64-encode inline. Larger attachments are rejected with an error pointing at [`save-attachment`](#save-attachment) (which streams to disk and has no such limit). Raise it to fetch bigger attachments inline; lower it to cap memory. |
 | `APPLE_NOTES_MCP_CONFIG_FILE` | `~/Library/Application Support/apple-notes-mcp/config.json` | Path to the JSON config file (see below). |
 | `DEBUG` / `VERBOSE` | unset | Set either to enable verbose diagnostic logging to stderr. |
 

package/build/index.js

@@ -89,21 +89,45 @@ function withErrorHandling(handler, errorPrefix) {
     };
 }
 // =============================================================================
+// Input Bounds
+// =============================================================================
+/**
+ * Upper bounds on string/array inputs (#validation). Zod's `.min(1)` rejected
+ * empty input but nothing capped the maximum, so a caller could pass an
+ * arbitrarily large string/array straight through to AppleScript. These mirror
+ * the limits the AppleNotesManager already enforces internally (title 2000,
+ * content 5 MB, folder path 1000, account 200) and add sane caps for the rest,
+ * so oversized input is rejected at the schema boundary with a clear message.
+ */
+const MAX = {
+    TITLE: 2000,
+    CONTENT: 5 * 1024 * 1024,
+    FOLDER: 1000,
+    ACCOUNT: 200,
+    QUERY: 2000,
+    ID: 2000,
+    SAVE_PATH: 4096,
+    ATTACHMENT_ID: 2000,
+    TAG: 200,
+    TAGS: 100,
+    BATCH_IDS: 500,
+};
+// =============================================================================
 // Schema Definitions
 // =============================================================================
 /**
  * Common schema for operations requiring a note title.
  */
 const noteTitleSchema = {
-    title: z.string().min(1, "Note title is required"),
-    account: z.string().optional().describe("Account name (defaults to iCloud)"),
+    title: z.string().min(1, "Note title is required").max(MAX.TITLE),
+    account: z.string().max(MAX.ACCOUNT).optional().describe("Account name (defaults to iCloud)"),
 };
 /**
  * Common schema for operations requiring a folder name.
  */
 const folderNameSchema = {
-    name: z.string().min(1, "Folder name is required"),
-    account: z.string().optional().describe("Account name (defaults to iCloud)"),
+    name: z.string().min(1, "Folder name is required").max(MAX.FOLDER),
+    account: z.string().max(MAX.ACCOUNT).optional().describe("Account name (defaults to iCloud)"),
 };
 // =============================================================================
 // Note Tools
@@ -112,22 +136,28 @@ const 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 — 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).",
     inputSchema: {
-        title: z.string().min(1, "Title is required"),
+        title: z.string().min(1, "Title is required").max(MAX.TITLE),
         content: z
             .string()
             .min(1, "Content is required")
+            .max(MAX.CONTENT)
             .describe('Note body. AppleScript cannot create true Apple Notes checklists — `<input type="checkbox">`, checklist CSS classes, and markdown `- [ ]` lines do not render as checkable items. To produce a checklist, create the note with a plain `<ul>` or `- ` list and convert it in Notes.app with ⇧⌘L.'),
         format: z
             .enum(["plaintext", "html"])
             .optional()
             .default("plaintext")
             .describe("Content format: 'plaintext' (default) or 'html' for rich formatting"),
-        tags: z.array(z.string()).optional().describe("Tags for organization"),
+        tags: z
+            .array(z.string().max(MAX.TAG))
+            .max(MAX.TAGS)
+            .optional()
+            .describe("Returned-only metadata — 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: z
             .string()
+            .max(MAX.FOLDER)
             .optional()
             .describe("Folder to create the note in (supports nested paths like 'Work/Clients')"),
-        account: z.string().optional().describe("Account name (defaults to iCloud)"),
+        account: z.string().max(MAX.ACCOUNT).optional().describe("Account name (defaults to iCloud)"),
     },
     outputSchema: {
         ok: z.boolean().optional(),
@@ -154,12 +184,13 @@ server.registerTool("create-note", {
 server.registerTool("search-notes", {
     description: "Use when: finding notes by a keyword in the title (or body with searchContent=true) and you need their ids.\nReturns: matching notes with title, folder, and id.\nDo not use when: you already have a note id (use get-note-content) or want every note (use list-notes).\nPrefer this first to obtain ids for subsequent read/update/delete/move calls.",
     inputSchema: {
-        query: z.string().min(1, "Search query is required"),
+        query: z.string().min(1, "Search query is required").max(MAX.QUERY),
         searchContent: z.boolean().optional().describe("Search note content instead of titles"),
-        account: z.string().optional().describe("Account to search in"),
-        folder: z.string().optional().describe("Limit search to a specific folder"),
+        account: z.string().max(MAX.ACCOUNT).optional().describe("Account to search in"),
+        folder: z.string().max(MAX.FOLDER).optional().describe("Limit search to a specific folder"),
         modifiedSince: z
             .string()
+            .max(64)
             .optional()
             .describe("ISO 8601 date string to filter notes modified on or after this date (e.g., '2025-01-01'). Useful for searching only recent notes in large collections."),
         limit: z.number().int().positive().optional().describe("Maximum number of results to return"),
@@ -206,10 +237,19 @@ server.registerTool("search-notes", {
 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.",
     inputSchema: {
-        id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
-        title: z.string().optional().describe("Note title (use id instead when available)"),
+        id: z
+            .string()
+            .max(MAX.ID)
+            .optional()
+            .describe("Note ID (preferred - more reliable than title)"),
+        title: z
+            .string()
+            .max(MAX.TITLE)
+            .optional()
+            .describe("Note title (use id instead when available)"),
         account: z
             .string()
+            .max(MAX.ACCOUNT)
             .optional()
             .describe("Account name (defaults to iCloud, ignored if id is provided)"),
     },
@@ -259,10 +299,19 @@ server.registerTool("get-note-content", {
 server.registerTool("get-note-plaintext", {
     description: "Use when: reading one note's body as plain text with no HTML, by id (preferred) or title.\nReturns: the note's plaintext exactly as Notes exposes it.\nDo not use when: you need the HTML body (get-note-content) or Markdown with checklist state (get-note-markdown).\nNote: this reads the note's native plaintext property, so it skips the HTML-to-text conversion; password-protected notes must be unlocked in Notes.app first.",
     inputSchema: {
-        id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
-        title: z.string().optional().describe("Note title (use id instead when available)"),
+        id: z
+            .string()
+            .max(MAX.ID)
+            .optional()
+            .describe("Note ID (preferred - more reliable than title)"),
+        title: z
+            .string()
+            .max(MAX.TITLE)
+            .optional()
+            .describe("Note title (use id instead when available)"),
         account: z
             .string()
+            .max(MAX.ACCOUNT)
             .optional()
             .describe("Account name (defaults to iCloud, ignored if id is provided)"),
     },
@@ -307,7 +356,7 @@ server.registerTool("get-note-plaintext", {
 server.registerTool("get-note-by-id", {
     description: "Use when: you have a note id and need its metadata only.\nReturns: id, title, created, modified, shared, passwordProtected.\nDo not use when: you need the body text (get-note-content) or only have a title (get-note-details).",
     inputSchema: {
-        id: z.string().min(1, "Note ID is required"),
+        id: z.string().min(1, "Note ID is required").max(MAX.ID),
     },
     outputSchema: {
         id: z.string().optional(),
@@ -367,7 +416,7 @@ server.registerTool("get-note-details", {
 server.registerTool("show-note", {
     description: "Use when: the user wants to reveal a known note in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need note content (get-note-content) or metadata (get-note-by-id).\nNote: this opens or focuses the Notes UI.",
     inputSchema: {
-        id: z.string().min(1, "Note ID is required"),
+        id: z.string().min(1, "Note ID is required").max(MAX.ID),
         separately: z
             .boolean()
             .optional()
@@ -388,7 +437,7 @@ server.registerTool("show-note", {
 server.registerTool("show-folder", {
     description: "Use when: the user wants to reveal a known folder in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need the folder list (list-folders).\nNote: this opens or focuses the Notes UI. Get the id from list-folders.",
     inputSchema: {
-        id: z.string().min(1, "Folder ID is required"),
+        id: z.string().min(1, "Folder ID is required").max(MAX.ID),
         separately: z
             .boolean()
             .optional()
@@ -409,7 +458,7 @@ server.registerTool("show-folder", {
 server.registerTool("show-account", {
     description: "Use when: the user wants to reveal a known account in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need the account list (list-accounts).\nNote: this opens or focuses the Notes UI. Get the id from list-accounts.",
     inputSchema: {
-        id: z.string().min(1, "Account ID is required"),
+        id: z.string().min(1, "Account ID is required").max(MAX.ID),
         separately: z
             .boolean()
             .optional()
@@ -430,12 +479,21 @@ server.registerTool("show-account", {
 server.registerTool("update-note", {
     description: "Use when: changing the title and/or replacing the body of an existing note, by id (preferred) or title.\nReturns: confirmation; warns when the note is shared.\nDo not use when: creating a new note (create-note).\nSafety: newContent REPLACES the entire body — it does not append. Read the note first if you need to preserve existing text, and run list-attachments first when the note may hold files, images, scans, PDFs, or audio, since a full-body replace can drop embedded attachments. Edits to shared notes are immediately visible to all collaborators.",
     inputSchema: {
-        id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
-        title: z.string().optional().describe("Current note title (use id instead when available)"),
-        newTitle: z.string().optional().describe("New title for the note"),
+        id: z
+            .string()
+            .max(MAX.ID)
+            .optional()
+            .describe("Note ID (preferred - more reliable than title)"),
+        title: z
+            .string()
+            .max(MAX.TITLE)
+            .optional()
+            .describe("Current note title (use id instead when available)"),
+        newTitle: z.string().max(MAX.TITLE).optional().describe("New title for the note"),
         newContent: z
             .string()
             .min(1, "New content is required")
+            .max(MAX.CONTENT)
             .describe("New note body. AppleScript cannot produce true Apple Notes checklists; checkbox inputs and `- [ ]` markdown do not render as checkable items. Use a plain list and convert in Notes.app with ⇧⌘L."),
         format: z
             .enum(["plaintext", "html"])
@@ -444,6 +502,7 @@ server.registerTool("update-note", {
             .describe("Content format: 'plaintext' (default) or 'html' for rich formatting"),
         account: z
             .string()
+            .max(MAX.ACCOUNT)
             .optional()
             .describe("Account containing the note (ignored if id is provided)"),
     },
@@ -513,10 +572,19 @@ server.registerTool("update-note", {
 server.registerTool("delete-note", {
     description: "Use when: permanently deleting a single note, by id (preferred) or title.\nReturns: confirmation; warns when the note was shared.\nDo not use when: deleting many notes (batch-delete-notes) or just relocating one (move-note).\nSafety: requires explicit user confirmation before deleting. Prefer search-notes/list-notes first to show the affected note id and title. Deleting a shared note removes collaborator access.",
     inputSchema: {
-        id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
-        title: z.string().optional().describe("Note title (use id instead when available)"),
+        id: z
+            .string()
+            .max(MAX.ID)
+            .optional()
+            .describe("Note ID (preferred - more reliable than title)"),
+        title: z
+            .string()
+            .max(MAX.TITLE)
+            .optional()
+            .describe("Note title (use id instead when available)"),
         account: z
             .string()
+            .max(MAX.ACCOUNT)
             .optional()
             .describe("Account name (defaults to iCloud, ignored if id is provided)"),
     },
@@ -574,12 +642,24 @@ server.registerTool("delete-note", {
 }, "Error deleting note"));
 // --- move-note ---
 server.registerTool("move-note", {
-    description: "Use when: moving one note to a different folder, by id (preferred) or title.\nReturns: confirmation of the note and destination folder.\nDo not use when: moving many notes (batch-move-notes).\nNote: implemented as copy-then-delete; the destination folder must already exist (create-folder).",
+    description: "Use when: moving one note to a different folder, by id (preferred) or title.\nReturns: confirmation of the note and destination folder.\nDo not use when: moving many notes (batch-move-notes).\nNote: the note is relocated in place via Notes.app's native move, preserving its id, creation date, and all attachments. The destination folder must already exist (create-folder).",
     inputSchema: {
-        id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
-        title: z.string().optional().describe("Note title (use id instead when available)"),
-        folder: z.string().min(1, "Destination folder is required"),
-        account: z.string().optional().describe("Account containing the note/folder"),
+        id: z
+            .string()
+            .max(MAX.ID)
+            .optional()
+            .describe("Note ID (preferred - more reliable than title)"),
+        title: z
+            .string()
+            .max(MAX.TITLE)
+            .optional()
+            .describe("Note title (use id instead when available)"),
+        folder: z.string().min(1, "Destination folder is required").max(MAX.FOLDER),
+        account: z
+            .string()
+            .max(MAX.ACCOUNT)
+            .optional()
+            .describe("Account containing the note/folder"),
     },
     outputSchema: {
         ok: z.boolean().optional(),
@@ -629,10 +709,11 @@ server.registerTool("move-note", {
 server.registerTool("list-notes", {
     description: "Use when: enumerating notes in an account or folder; supports modifiedSince and limit for large collections.\nReturns: note titles only (no content or ids).\nDo not use when: you need content (get-note-content) or ids for follow-up edits (use search-notes).\nNote: warns if iCloud sync is active and results may be partial.",
     inputSchema: {
-        account: z.string().optional().describe("Account to list notes from"),
-        folder: z.string().optional().describe("Filter to specific folder"),
+        account: z.string().max(MAX.ACCOUNT).optional().describe("Account to list notes from"),
+        folder: z.string().max(MAX.FOLDER).optional().describe("Filter to specific folder"),
         modifiedSince: z
             .string()
+            .max(64)
             .optional()
             .describe("ISO 8601 date string to filter notes modified on or after this date (e.g., '2025-01-01'). Useful for listing only recent notes in large collections."),
         limit: z.number().int().positive().optional().describe("Maximum number of notes to return"),
@@ -693,7 +774,7 @@ server.registerTool("get-selected-notes", {
 server.registerTool("list-folders", {
     description: "Use when: listing all folders, with full nested paths, for an account.\nReturns: folder names/paths.\nDo not use when: listing notes (list-notes).\nNote: warns if iCloud sync is active.",
     inputSchema: {
-        account: z.string().optional().describe("Account to list folders from"),
+        account: z.string().max(MAX.ACCOUNT).optional().describe("Account to list folders from"),
     },
     outputSchema: {
         folders: z.array(z.object({}).passthrough()).optional(),
@@ -728,8 +809,9 @@ server.registerTool("create-folder", {
         name: z
             .string()
             .min(1, "Folder name is required")
+            .max(MAX.FOLDER)
             .describe('Folder name or nested path separated by "/". E.g., "Retro Tech/PC/CPUs" creates all intermediate folders. Existing segments are skipped.'),
-        account: z.string().optional().describe("Account name (defaults to iCloud)"),
+        account: z.string().max(MAX.ACCOUNT).optional().describe("Account name (defaults to iCloud)"),
     },
     outputSchema: {
         ok: z.boolean().optional(),
@@ -960,10 +1042,19 @@ server.registerTool("get-notes-stats", {
 server.registerTool("list-attachments", {
     description: "Use when: listing the attachments of one note, by id (preferred) or title.\nReturns: each attachment's name, content type, and id (use with save-attachment/fetch-attachment).\nDo not use when: you want the attachment bytes (fetch-attachment) or a file on disk (save-attachment).",
     inputSchema: {
-        id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
-        title: z.string().optional().describe("Note title (use id instead when available)"),
+        id: z
+            .string()
+            .max(MAX.ID)
+            .optional()
+            .describe("Note ID (preferred - more reliable than title)"),
+        title: z
+            .string()
+            .max(MAX.TITLE)
+            .optional()
+            .describe("Note title (use id instead when available)"),
         account: z
             .string()
+            .max(MAX.ACCOUNT)
             .optional()
             .describe("Account containing the note (ignored if id is provided)"),
     },
@@ -1007,7 +1098,10 @@ server.registerTool("list-attachments", {
 server.registerTool("batch-delete-notes", {
     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: z.array(z.string()).describe("Array of note IDs to delete"),
+        ids: z
+            .array(z.string().max(MAX.ID))
+            .max(MAX.BATCH_IDS)
+            .describe("Array of note IDs to delete"),
     },
     outputSchema: {
         ok: z.boolean().optional(),
@@ -1042,10 +1136,14 @@ server.registerTool("batch-delete-notes", {
 server.registerTool("batch-move-notes", {
     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: z.array(z.string()).describe("Array of note IDs to move"),
-        folder: z.string().describe("Destination folder name"),
+        ids: z
+            .array(z.string().max(MAX.ID))
+            .max(MAX.BATCH_IDS)
+            .describe("Array of note IDs to move"),
+        folder: z.string().max(MAX.FOLDER).describe("Destination folder name"),
         account: z
             .string()
+            .max(MAX.ACCOUNT)
             .optional()
             .describe("Account containing the destination folder (defaults to iCloud)"),
     },
@@ -1087,14 +1185,17 @@ server.registerTool("save-attachment", {
         noteId: z
             .string()
             .min(1, "noteId is required")
+            .max(MAX.ID)
             .describe("CoreData note id (from search/list)"),
         attachmentId: z
             .string()
             .min(1, "attachmentId is required")
+            .max(MAX.ATTACHMENT_ID)
             .describe("Attachment id (from list-attachments)"),
         savePath: z
             .string()
             .min(1, "savePath is required")
+            .max(MAX.SAVE_PATH)
             .describe("Absolute destination file path (must be under home, temp, or /Volumes)"),
     },
     outputSchema: {
@@ -1120,10 +1221,12 @@ server.registerTool("fetch-attachment", {
         noteId: z
             .string()
             .min(1, "noteId is required")
+            .max(MAX.ID)
             .describe("CoreData note id (from search/list)"),
         attachmentId: z
             .string()
             .min(1, "attachmentId is required")
+            .max(MAX.ATTACHMENT_ID)
             .describe("Attachment id (from list-attachments)"),
     },
     outputSchema: {
@@ -1146,10 +1249,12 @@ server.registerTool("show-attachment", {
         noteId: z
             .string()
             .min(1, "noteId is required")
+            .max(MAX.ID)
             .describe("CoreData note id (from search/list)"),
         attachmentId: z
             .string()
             .min(1, "attachmentId is required")
+            .max(MAX.ATTACHMENT_ID)
             .describe("Attachment id (from list-attachments)"),
         separately: z
             .boolean()
@@ -1203,10 +1308,19 @@ server.registerTool("export-notes-json", {
 server.registerTool("get-note-markdown", {
     description: "Use when: reading a note as Markdown, with checklist items annotated [x]/[ ] when Full Disk Access is granted.\nReturns: the note's Markdown.\nDo not use when: you need the raw HTML/plaintext body (get-note-content) or only metadata (get-note-details).\nNote: falls back to plain lists (no checkmarks) without Full Disk Access.",
     inputSchema: {
-        id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
-        title: z.string().optional().describe("Note title (use id instead when available)"),
+        id: z
+            .string()
+            .max(MAX.ID)
+            .optional()
+            .describe("Note ID (preferred - more reliable than title)"),
+        title: z
+            .string()
+            .max(MAX.TITLE)
+            .optional()
+            .describe("Note title (use id instead when available)"),
         account: z
             .string()
+            .max(MAX.ACCOUNT)
             .optional()
             .describe("Account containing the note (ignored if id is provided)"),
     },
@@ -1236,7 +1350,10 @@ server.registerTool("get-note-markdown", {
 server.registerTool("get-checklist-state", {
     description: "Use when: reading the checked/unchecked state of a note's checklist items, by id.\nReturns: each item's text and done state plus checked/total counts.\nDo not use when: you only have a title (get the id via search-notes first) or want the full body text (get-note-content).\nNote: requires Full Disk Access; reads the NoteStore database directly.",
     inputSchema: {
-        id: z.string().min(1, "Note ID is required. Use search-notes to find the note ID first."),
+        id: z
+            .string()
+            .min(1, "Note ID is required. Use search-notes to find the note ID first.")
+            .max(MAX.ID),
     },
     outputSchema: {
         items: z.array(z.object({}).passthrough()).optional(),
@@ -1266,7 +1383,10 @@ server.registerTool("get-checklist-state", {
 server.registerTool("get-note-metadata", {
     description: "[BETA] Use when: reading note metadata AppleScript cannot expose — pinned state, checklist flags, trash/recovery state, preview snippet, password hint — by id.\nReturns: a metadata object; fields vary by macOS version and are omitted when unavailable.\nDo not use when: you need the body (get-note-content) or per-item checklist state (get-checklist-state).\nNote: reads the NoteStore SQLite database read-only and requires Full Disk Access. BETA — the database schema changes between macOS releases, so some fields may be absent. Works on trashed notes that AppleScript can no longer resolve.",
     inputSchema: {
-        id: z.string().min(1, "Note ID is required. Use search-notes to find the note ID first."),
+        id: z
+            .string()
+            .min(1, "Note ID is required. Use search-notes to find the note ID first.")
+            .max(MAX.ID),
     },
     outputSchema: {
         pinned: z.boolean().optional(),
@@ -1314,5 +1434,23 @@ process.on("uncaughtException", (err) => {
 process.on("unhandledRejection", (reason) => {
     console.error("[unhandledRejection]", reason);
 });
+// Graceful shutdown. This server holds no persistent resources (AppleScript runs
+// are one-shot via execSync), so there's nothing to drain — but wiring SIGINT/
+// SIGTERM and stdin EOF/close to a clean exit keeps behavior tidy and consistent
+// with the sibling apple-mail server: when the parent kills us (signal) or the
+// MCP client disconnects (stdin 'end'/'close'), exit 0 promptly instead of
+// lingering as an orphan. Idempotent so multiple triggers don't double-exit.
+let _shuttingDown = false;
+const shutdown = () => {
+    if (_shuttingDown)
+        return;
+    _shuttingDown = true;
+    process.exit(0);
+};
+for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, shutdown);
+}
+process.stdin.on("end", shutdown);
+process.stdin.on("close", shutdown);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/build/services/appleNotesManager.js

@@ -16,7 +16,7 @@
  */
 import { executeAppleScript } from "../utils/applescript.js";
 import { getChecklistItems } from "../utils/checklistParser.js";
-import { assertSafeSavePath, readFileBase64, fileSize, makeTempDir, cleanupTempDir, } from "../utils/attachmentFs.js";
+import { assertSafeSavePath, readFileBase64Capped, fileSize, makeTempDir, cleanupTempDir, } from "../utils/attachmentFs.js";
 import { existsSync } from "fs";
 import TurndownService from "turndown";
 // =============================================================================
@@ -1395,99 +1395,65 @@ export class AppleNotesManager {
         return true;
     }
     /**
-     * Moves a note to a different folder.
+     * Moves a note to a different folder, looked up by title.
      *
-     * Since AppleScript doesn't support direct note moves, this operation:
-     * 1. Retrieves the source note's content
-     * 2. Creates a new note with that content in the destination folder
-     * 3. Deletes the original note (only if copy succeeded)
+     * Uses Notes.app's native `move` command (the same one `batchMoveNotes`
+     * uses), which relocates the note in place — preserving its identity, id,
+     * creation date, AND all embedded attachments (files/images/PDFs/scans/audio).
+     * The previous copy-then-delete implementation rebuilt the note from its body
+     * HTML, which silently dropped attachments and reset the note's identity.
      *
-     * This ensures the note is never lost - if the copy fails, the
-     * original remains untouched. If only the delete fails, the note
-     * exists in the new location (success is still returned).
+     * The note is resolved to its id first (titles can be duplicated), then moved
+     * by id so the title-based and id-based paths share the same native move.
      *
      * @param title - Title of the note to move
-     * @param destinationFolder - Name of the folder to move to
+     * @param destinationFolder - Name of the folder to move to (must already exist)
      * @param account - Account containing the note (defaults to iCloud)
-     * @returns true if move succeeded (or copy succeeded but delete failed)
+     * @returns true if the move succeeded, false otherwise
      */
     moveNote(title, destinationFolder, account) {
         const targetAccount = this.resolveAccount(account);
-        // Step 1: Get the original note's ID first (before creating a copy with the same title)
+        // Resolve the note's id first (titles can be duplicated), then delegate to
+        // the id-based native move so both paths preserve attachments + identity.
         const originalNote = this.getNoteDetails(title, targetAccount);
         if (!originalNote) {
             console.error(`Cannot move note "${title}": note not found`);
             return false;
         }
-        // Step 2: Retrieve the original note's content
-        const originalContent = this.getNoteContent(title, targetAccount);
-        if (!originalContent) {
-            console.error(`Cannot move note "${title}": failed to retrieve content`);
-            return false;
-        }
-        // Step 3: Create a copy in the destination folder
-        // Content is already HTML from getNoteContent(), so use escapeHtmlForAppleScript()
-        const folderRef = buildFolderReference(destinationFolder);
-        const safeContent = escapeHtmlForAppleScript(originalContent);
-        const createCommand = `make new note at ${folderRef} with properties {body:"${safeContent}"}`;
-        const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
-        const copyResult = executeAppleScript(script);
-        if (!copyResult.success) {
-            console.error(`Cannot move note "${title}": failed to create in destination folder:`, copyResult.error);
-            return false;
-        }
-        // Step 4: Delete the original by ID (not by title, since there are now two notes with the same title)
-        const safeOrigId = sanitizeId(originalNote.id);
-        const deleteCommand = `delete note id "${safeOrigId}"`;
-        const deleteScript = buildAppLevelScript(deleteCommand);
-        const deleteResult = executeAppleScript(deleteScript);
-        if (!deleteResult.success) {
-            // The note was copied successfully but we couldn't delete the original.
-            // This is still a partial success - the note exists in the new location.
-            console.error(`Note "${title}" was copied to "${destinationFolder}" but original could not be deleted:`, deleteResult.error);
-            return true;
-        }
-        return true;
+        return this.moveNoteById(originalNote.id, destinationFolder, targetAccount);
     }
     /**
      * Moves a note to a different folder by its CoreData ID.
      *
-     * This is more reliable than moveNote() because IDs are unique,
-     * while titles can be duplicated.
+     * Uses Notes.app's native `move <noteRef> to <destFolder>` command — the same
+     * one `batchMoveNotes` uses — which relocates the note in place, preserving its
+     * id, creation date, and all embedded attachments. (The old copy-then-delete
+     * approach rebuilt the note from body HTML and silently lost attachments.)
      *
      * @param id - CoreData URL identifier for the note
-     * @param destinationFolder - Name of the folder to move to
+     * @param destinationFolder - Name of the folder to move to (must already exist)
      * @param account - Account containing the destination folder (defaults to iCloud)
-     * @returns true if move succeeded (or copy succeeded but delete failed)
+     * @returns true if the move succeeded, false otherwise
      */
     moveNoteById(id, destinationFolder, account) {
         const targetAccount = this.resolveAccount(account);
         const safeId = sanitizeId(id);
-        // Step 1: Retrieve the original note's content by ID
-        const originalContent = this.getNoteContentById(id);
-        if (!originalContent) {
-            console.error(`Cannot move note: note with ID "${id}" not found`);
-            return false;
-        }
-        // Step 2: Create a copy in the destination folder
-        // Content is already HTML from getNoteContentById(), so use escapeHtmlForAppleScript()
-        const folderRef = buildFolderReference(destinationFolder);
-        const safeContent = escapeHtmlForAppleScript(originalContent);
-        const createCommand = `make new note at ${folderRef} with properties {body:"${safeContent}"}`;
-        const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
-        const copyResult = executeAppleScript(script);
-        if (!copyResult.success) {
-            console.error(`Cannot move note: failed to create in destination folder:`, copyResult.error);
+        const safeAccount = sanitizeAccountName(targetAccount);
+        // buildFolderReference validates the destination path; a malformed folder is
+        // a precondition error, so let it throw. The destination folder must already
+        // exist — Notes.app's `move` does not create it.
+        const destFolderRef = `${buildFolderReference(destinationFolder)} of account "${safeAccount}"`;
+        const moveCommand = `
+      set destFolder to ${destFolderRef}
+      set noteRef to note id "${safeId}"
+      move noteRef to destFolder
+    `;
+        const script = buildAppLevelScript(moveCommand);
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Cannot move note to "${destinationFolder}" (folder may not exist):`, result.error);
             return false;
         }
-        // Step 3: Delete the original by ID
-        const deleteCommand = `delete note id "${safeId}"`;
-        const deleteScript = buildAppLevelScript(deleteCommand);
-        const deleteResult = executeAppleScript(deleteScript);
-        if (!deleteResult.success) {
-            console.error(`Note was copied to "${destinationFolder}" but original could not be deleted:`, deleteResult.error);
-            return true; // Partial success - note exists in new location
-        }
         return true;
     }
     // ===========================================================================
@@ -2184,11 +2150,15 @@ export class AppleNotesManager {
             if (!saved.success || !saved.savedPath) {
                 return { success: false, error: saved.error };
             }
+            // readFileBase64Capped checks the file size BEFORE reading and throws if it
+            // exceeds APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES — the throw is caught below
+            // and the temp dir is still cleaned up in `finally`.
+            const base64 = readFileBase64Capped(saved.savedPath);
             return {
                 success: true,
                 name: saved.name,
                 contentType: saved.contentType,
-                base64: readFileBase64(saved.savedPath),
+                base64,
                 bytes: fileSize(saved.savedPath),
             };
         }

package/build/services/appleNotesManager.test.js

@@ -1395,35 +1395,35 @@ describe("AppleNotesManager", () => {
     // Note Moving
     // ---------------------------------------------------------------------------
     describe("moveNote", () => {
-        it("returns true when move completes successfully", () => {
-            // Mock sequence: getNoteDetails -> getNoteContent -> createNote -> deleteNote
+        // The note-details lookup output reused by the title-based move tests.
+        const detailsOutput = [
+            "My Note",
+            "x-coredata://ABC/ICNote/p123",
+            "Monday, January 1, 2024 at 12:00:00 PM",
+            "Monday, January 1, 2024 at 12:00:00 PM",
+            "false",
+            "false",
+        ].join(F);
+        it("returns true when the native move completes successfully", () => {
+            // Mock sequence: getNoteDetails (resolve id) -> native move
             mockExecuteAppleScript
-                .mockReturnValueOnce({
-                success: true,
-                output: [
-                    "My Note",
-                    "x-coredata://ABC/ICNote/p123",
-                    "Monday, January 1, 2024 at 12:00:00 PM",
-                    "Monday, January 1, 2024 at 12:00:00 PM",
-                    "false",
-                    "false",
-                ].join(F),
-            })
-                .mockReturnValueOnce({
-                success: true,
-                output: "<div>Note Title</div><div>Content</div>",
-            })
-                .mockReturnValueOnce({
-                success: true,
-                output: "note id x-coredata://...",
-            })
-                .mockReturnValueOnce({
-                success: true,
-                output: "",
-            });
+                .mockReturnValueOnce({ success: true, output: detailsOutput })
+                .mockReturnValueOnce({ success: true, output: "" });
             const result = manager.moveNote("My Note", "Archive");
             expect(result).toBe(true);
-            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(4);
+            // No copy-then-delete: just the details lookup + a single native `move`.
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(2);
+        });
+        it("uses the native AppleScript `move` command (preserves attachments/identity)", () => {
+            mockExecuteAppleScript
+                .mockReturnValueOnce({ success: true, output: detailsOutput })
+                .mockReturnValueOnce({ success: true, output: "" });
+            manager.moveNote("My Note", "Archive");
+            // The second call is the move; assert it issues a native `move ... to` and
+            // does NOT rebuild the note via `make new note` (the old lossy path).
+            const moveScript = mockExecuteAppleScript.mock.calls[1][0];
+            expect(moveScript).toContain("move noteRef to destFolder");
+            expect(moveScript).not.toContain("make new note");
         });
         it("returns false when source note cannot be found", () => {
             mockExecuteAppleScript.mockReturnValueOnce({
@@ -1435,23 +1435,9 @@ describe("AppleNotesManager", () => {
             expect(result).toBe(false);
             expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1); // Only tried to get details
         });
-        it("returns false when copy to destination fails", () => {
+        it("returns false when the move fails (e.g. destination folder missing)", () => {
             mockExecuteAppleScript
-                .mockReturnValueOnce({
-                success: true,
-                output: [
-                    "My Note",
-                    "x-coredata://ABC/ICNote/p123",
-                    "Monday, January 1, 2024 at 12:00:00 PM",
-                    "Monday, January 1, 2024 at 12:00:00 PM",
-                    "false",
-                    "false",
-                ].join(F),
-            })
-                .mockReturnValueOnce({
-                success: true,
-                output: "<div>Content</div>",
-            })
+                .mockReturnValueOnce({ success: true, output: detailsOutput })
                 .mockReturnValueOnce({
                 success: false,
                 output: "",
@@ -1459,38 +1445,29 @@ describe("AppleNotesManager", () => {
             });
             const result = manager.moveNote("My Note", "Nonexistent Folder");
             expect(result).toBe(false);
-            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(3); // Details + Read + failed create
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(2); // Details + failed move
         });
-        it("returns true even if delete fails (note exists in new location)", () => {
-            // This is partial success - note was copied but original couldn't be deleted
-            mockExecuteAppleScript
-                .mockReturnValueOnce({
-                success: true,
-                output: [
-                    "My Note",
-                    "x-coredata://ABC/ICNote/p123",
-                    "Monday, January 1, 2024 at 12:00:00 PM",
-                    "Monday, January 1, 2024 at 12:00:00 PM",
-                    "false",
-                    "false",
-                ].join(F),
-            })
-                .mockReturnValueOnce({
-                success: true,
-                output: "<div>Content</div>",
-            })
-                .mockReturnValueOnce({
-                success: true,
-                output: "note id x-coredata://...",
-            })
-                .mockReturnValueOnce({
+    });
+    describe("moveNoteById", () => {
+        it("returns true when the native move succeeds", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "" });
+            const result = manager.moveNoteById("x-coredata://ABC/ICNote/p123", "Archive");
+            expect(result).toBe(true);
+            // Single native `move` — no getNoteContentById/create/delete fan-out.
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1);
+            const moveScript = mockExecuteAppleScript.mock.calls[0][0];
+            expect(moveScript).toContain("move noteRef to destFolder");
+            expect(moveScript).not.toContain("make new note");
+        });
+        it("returns false when the move fails", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
                 success: false,
                 output: "",
-                error: "Cannot delete original",
+                error: "Folder not found",
             });
-            const result = manager.moveNote("My Note", "Archive");
-            // Should still return true because the note exists in the destination
-            expect(result).toBe(true);
+            const result = manager.moveNoteById("x-coredata://ABC/ICNote/p123", "Nonexistent");
+            expect(result).toBe(false);
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1);
         });
     });
     // ---------------------------------------------------------------------------

package/build/utils/attachmentFs.js

@@ -30,10 +30,48 @@ export function assertSafeSavePath(p, roots = allowedSaveRoots()) {
     }
     return abs;
 }
+/**
+ * Default upper bound on an attachment that `fetch-attachment` will base64-encode
+ * into a single MCP response. `readFileSync` loads the whole file into memory and
+ * base64 grows it ~33%, so an unbounded read of a multi-GB attachment (video,
+ * disk image) could exhaust memory. 25 MB is generous for the inline-fetch use
+ * case (docs, images, PDFs); larger attachments should be exported to disk with
+ * `save-attachment` instead. Overridable via APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES.
+ */
+const DEFAULT_MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+/** Resolve the configured max attachment size (bytes) for inline base64 fetch. */
+export function maxAttachmentBytes(env = process.env) {
+    const raw = env.APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_MAX_ATTACHMENT_BYTES;
+}
 /** Read a file as base64. */
 export function readFileBase64(p) {
     return readFileSync(p).toString("base64");
 }
+/**
+ * Read a file as base64, refusing files larger than `maxBytes`.
+ *
+ * Guards `fetch-attachment` against unbounded in-memory reads: the size is
+ * checked from filesystem metadata BEFORE the file is read, so an oversized
+ * attachment is rejected with a clear error instead of loading it (and its
+ * ~33%-larger base64) into memory. (`APPLE_NOTES_MCP_MAX_BUFFER` does not apply
+ * to `readFileSync`.)
+ *
+ * @throws if the file exceeds `maxBytes`
+ */
+export function readFileBase64Capped(p, maxBytes = maxAttachmentBytes()) {
+    const size = fileSize(p);
+    if (size > maxBytes) {
+        throw new Error(`Attachment is ${size} bytes, exceeding the ${maxBytes}-byte fetch limit ` +
+            `(APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES). Use save-attachment to export it to disk instead.`);
+    }
+    return readFileBase64(p);
+}
 /** Byte size of a file (0 if missing). */
 export function fileSize(p) {
     try {

package/build/utils/attachmentFs.test.js

@@ -2,7 +2,7 @@ import { describe, it, expect, afterEach } from "vitest";
 import { writeFileSync, existsSync, mkdtempSync } from "fs";
 import { homedir, tmpdir } from "os";
 import { join } from "path";
-import { assertSafeSavePath, readFileBase64, fileSize, makeTempDir, cleanupTempDir, allowedSaveRoots, } from "../utils/attachmentFs.js";
+import { assertSafeSavePath, readFileBase64, readFileBase64Capped, maxAttachmentBytes, fileSize, makeTempDir, cleanupTempDir, allowedSaveRoots, } from "../utils/attachmentFs.js";
 const dirs = [];
 afterEach(() => dirs.splice(0).forEach(cleanupTempDir));
 describe("assertSafeSavePath (#27)", () => {
@@ -44,3 +44,26 @@ describe("base64 / size / temp helpers (#27)", () => {
         expect(() => cleanupTempDir(dir)).not.toThrow();
     });
 });
+describe("readFileBase64Capped / maxAttachmentBytes (size guard)", () => {
+    it("reads files at or under the cap", () => {
+        const dir = mkdtempSync(join(tmpdir(), "anatt-"));
+        dirs.push(dir);
+        const f = join(dir, "ok.bin");
+        writeFileSync(f, Buffer.from("hello"));
+        expect(readFileBase64Capped(f, 1024)).toBe(Buffer.from("hello").toString("base64"));
+    });
+    it("throws (without reading) when the file exceeds the cap", () => {
+        const dir = mkdtempSync(join(tmpdir(), "anatt-"));
+        dirs.push(dir);
+        const f = join(dir, "big.bin");
+        writeFileSync(f, Buffer.alloc(2048));
+        expect(() => readFileBase64Capped(f, 1024)).toThrow(/exceeding the 1024-byte fetch limit/);
+    });
+    it("maxAttachmentBytes honors APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES and falls back to a sane default", () => {
+        expect(maxAttachmentBytes({ APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES: "12345" })).toBe(12345);
+        // Invalid / non-positive values fall back to the default (25 MB).
+        expect(maxAttachmentBytes({ APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES: "0" })).toBe(25 * 1024 * 1024);
+        expect(maxAttachmentBytes({ APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES: "nope" })).toBe(25 * 1024 * 1024);
+        expect(maxAttachmentBytes({})).toBe(25 * 1024 * 1024);
+    });
+});

package/build/utils/syncDetection.js

@@ -11,7 +11,7 @@
  *
  * @module utils/syncDetection
  */
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
@@ -76,7 +76,10 @@ export function getSyncStatus(useCache = true) {
       WHERE ZCURRENTLOCALVERSION > ZLATESTVERSIONSYNCEDTOCLOUD
       AND ZLATESTVERSIONSYNCEDTOCLOUD IS NOT NULL;
     `;
-        const result = execSync(`sqlite3 -readonly "${NOTES_DB_PATH}" "${query.replace(/\n/g, " ")}"`, {
+        // Use execFileSync (argv array, no shell) to match the sibling sqlite callers
+        // (checklistParser.ts, noteMetadata.ts). The values here aren't user-controlled,
+        // but argv form avoids shell quoting/interpolation entirely.
+        const result = execFileSync("sqlite3", ["-readonly", NOTES_DB_PATH, query.replace(/\n/g, " ")], {
             encoding: "utf8",
             timeout: 5000,
             stdio: ["pipe", "pipe", "pipe"],

package/build/utils/syncDetection.test.js

@@ -5,16 +5,16 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { getSyncStatus, logSyncWarning, withSyncAwareness, withSyncAwarenessSync, isSyncActive, getSyncStatusSummary, clearSyncStatusCache, } from "./syncDetection.js";
 // Mock child_process
 vi.mock("child_process", () => ({
-    execSync: vi.fn(),
+    execFileSync: vi.fn(),
 }));
 // Mock fs
 vi.mock("fs", () => ({
     existsSync: vi.fn(),
     statSync: vi.fn(),
 }));
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 import * as fs from "fs";
-const mockExecSync = vi.mocked(execSync);
+const mockExecSync = vi.mocked(execFileSync);
 const mockExistsSync = vi.mocked(fs.existsSync);
 const mockStatSync = vi.mocked(fs.statSync);
 describe("getSyncStatus", () => {

package/package.json

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