apple-notes-mcp 2.9.8 → 2.9.10

package/README.md

@@ -261,7 +261,7 @@ Creates a new note in Apple Notes.
 | `account` | string | No | Account name (defaults to Notes.app's default account; matched exactly or by a *unique* prefix — an ambiguous prefix is refused). Must be an account Notes.app already has configured — see [`list-accounts`](#list-accounts) |
 | `format` | string | No | Content format: `"plaintext"` (default), `"html"`, or `"markdown"`. In all formats, the title is automatically prepended as the note's title line. In plaintext mode, newlines become `<br>`, tabs become `<br>`, and backslashes are preserved as HTML entities. `"markdown"` produces real Title/Heading/Subheading styles through a Shortcut; see [Markdown notes](#markdown-notes) |
 | `markdownRoute` | string | No | With `format: "markdown"` only: `"shortcut"` (default) or `"html"`. See [Markdown through HTML](#markdown-through-html) |
-| `timeoutSeconds` | number | No | Whole seconds, 1–120, for each Notes.app automation step this call runs; overrides `APPLE_NOTES_MCP_TIMEOUT_MS` for this call only. A timed-out write is uncertain, not failed: read the note by id before any retry. Also accepted by `update-note`, `append-to-note`, `delete-note` and `move-note` |
+| `timeoutSeconds` | number | No | Whole seconds, 1–120, for each Notes.app automation step this call runs; overrides `APPLE_NOTES_MCP_TIMEOUT_MS` for this call only. A timed-out write is uncertain, not failed: read the note by id before any retry. Also accepted by `get-note-content`, `update-note`, `append-to-note`, `delete-note` and `move-note` |
 
 **Example (tagged with inline hashtags):**
 ```json
@@ -531,9 +531,12 @@ Retrieves the full content of a specific note.
 | `id` | string | No | Note ID (preferred - more reliable than title) |
 | `title` | string | No | Note title (use `id` instead when available) |
 | `account` | string | No | Account containing the note (defaults to Notes.app's default account; exact or unique-prefix match, ignored if `id` is provided) |
+| `timeoutSeconds` | number | No | Whole seconds, 1–120, for the body read; overrides `APPLE_NOTES_MCP_TIMEOUT_MS` for this call only |
 
 **Note:** Either `id` or `title` must be provided. Using `id` is recommended as it's unique and avoids issues with duplicate titles.
 
+**Large images:** Notes.app returns images inside the body as base64, so a note holding a very large image (tens of MB) can take longer to read than the timeout allows. When the read times out or overflows the output buffer, the error says so and, with Full Disk Access, names the attachments of 5 MB or more. Retry with a larger `timeoutSeconds`; `delete-note` accepts the same argument, and it needs a successful read to verify the note before deleting it.
+
 **Example - Using ID (recommended):**
 ```json
 {
@@ -1873,6 +1876,14 @@ fetched attachment bytes with the source before reporting success.
 that exact name. A mismatch is a warning (`filenameWarning`), not a failure,
 because the attachment and its bytes are already verified.
 
+On macOS 27, Notes' AppleScript does not list PDF attachments, so it cannot see
+a PDF this tool just added. When that happens and the server has Full Disk
+Access, it verifies through the read-only NoteStore database instead: success
+requires exactly one new attachment row on the note whose media file matches
+the source bytes, and the result carries `verifiedBy: "database"`. Without Full
+Disk Access a PDF attach reports "insertion outcome uncertain"; read the note
+before retrying, because the attachment was probably created.
+
 ---
 
 #### `create-note-with-attachment`

package/build/index.js

@@ -42825,15 +42825,27 @@ var AppleNotesManager = class {
    * @returns HTML content of the note, or empty string if not found
    */
   getNoteContentById(id2) {
+    return this.readNoteBodyById(id2).body;
+  }
+  /**
+   * Like {@link getNoteContentById}, but keeps the automation error so a
+   * caller can explain a failed read (for example a timeout on a note whose
+   * body carries a very large inline image, #237) instead of reporting a bare
+   * failure.
+   *
+   * @param id - CoreData URL identifier for the note
+   * @returns The HTML body, or an empty body plus the error that stopped the read
+   */
+  readNoteBodyById(id2) {
     const safeId = sanitizeId(id2);
     const getCommand = `get body of note id "${safeId}"`;
     const script = buildAppLevelScript(getCommand);
     const result = executeAppleScript(script);
     if (!result.success) {
       console.error(`Failed to get content of note with ID "${id2}":`, result.error);
-      return "";
+      return { body: "", error: result.error };
     }
-    return result.output;
+    return { body: result.output };
   }
   /**
    * Retrieves the plain-text content of a note by its exact title.
@@ -49593,6 +49605,37 @@ function readNoteStructure(id2, { dbPath: dbPath2 = NOTES_DB_PATH7, includeText
   };
 }
 
+// src/utils/bodyReadFailure.ts
+var LARGE_ATTACHMENT_BYTES = 5 * 1024 * 1024;
+function classifyBodyReadError(error2) {
+  if (!error2) return "other";
+  if (/ENOBUFS|maxBuffer/i.test(error2)) return "buffer";
+  if (/timed out|timeout|-1712/i.test(error2)) return "timeout";
+  return "other";
+}
+function formatBytes2(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${bytes} bytes`;
+}
+function largeAttachments(attachments, threshold = LARGE_ATTACHMENT_BYTES) {
+  const flat = attachments.flatMap((a) => [a, ...a.children ?? []]);
+  return flat.filter((a) => typeof a.fileSize === "number" && a.fileSize >= threshold).map((a) => ({ name: a.filename || a.title || "attachment", bytes: a.fileSize })).sort((a, b) => b.bytes - a.bytes);
+}
+function describeBodyReadFailure(title, error2, attachments) {
+  const base = `Failed to read content of note "${title}"${error2 ? `: ${error2}` : ""}`;
+  const kind = classifyBodyReadError(error2);
+  if (kind === "other") return base;
+  const large = attachments ? largeAttachments(attachments) : [];
+  const cause = large.length > 0 ? `The note holds ${large.length === 1 ? "a large attachment" : "large attachments"} (${large.map((a) => `${a.name}, ${formatBytes2(a.bytes)}`).join(
+    "; "
+  )}). Notes.app returns images inside the note body as base64, so a large image makes the body too big to read in time.` : "Notes.app returns images inside the note body as base64, so a note with a very large image can take longer to read than the timeout allows.";
+  const remedy = kind === "buffer" ? "Raise APPLE_NOTES_MCP_MAX_BUFFER (bytes) and retry, or remove the attachment in Notes.app." : "Retry with a longer timeoutSeconds (up to 120) or raise APPLE_NOTES_MCP_TIMEOUT_MS. If it still fails, delete or shrink the attachment in Notes.app; delete-note needs a successful read to verify the note first.";
+  return `${base}
+
+${cause} ${remedy}`;
+}
+
 // src/utils/noteLinkInventory.ts
 import { dirname as dirname5 } from "node:path";
 var BODY_BATCH = 100;
@@ -51463,7 +51506,7 @@ function registerDirectOperations(server2, manager) {
   };
   tool(
     "add-attachment",
-    "Use when: adding one local file to an exact note without replacing its body.\nReturns: the new attachment id, byte count, attachment name, and post-write content hash after exact byte verification.\nDo not use when: reading or exporting an existing attachment.\nSafety: requires a fresh rich revision, copies at most 64 MiB through a private temporary file, never retries insertion, and verifies existing content plus fetched bytes.",
+    "Use when: adding one local file to an exact note without replacing its body.\nReturns: the new attachment id, byte count, attachment name, and post-write content hash after exact byte verification.\nDo not use when: reading or exporting an existing attachment.\nSafety: requires a fresh rich revision, copies at most 64 MiB through a private temporary file, never retries insertion, and verifies existing content plus fetched bytes. On macOS 27 Notes' AppleScript does not list PDF attachments; with Full Disk Access the new attachment is verified through the read-only NoteStore database instead (verifiedBy: database), otherwise the outcome is reported as uncertain.",
     { id: noteId, expectedContentHash: revision, ...attachmentInput },
     (args) => attachFile(manager, args)
   );
@@ -51532,6 +51575,56 @@ function attachmentName(path10, filename) {
     );
   return filename;
 }
+var UNCERTAIN = "Attachment insertion outcome uncertain; read the exact note before retrying";
+var pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+var sha256 = (data) => createHash2("sha256").update(data).digest("hex");
+function storedAttachmentIds(manager, id2) {
+  try {
+    return new Set(
+      manager.getAttachmentAssetsById(id2).attachments.filter((item) => item.parentIdentifier === null).map((item) => item.identifier.toLowerCase())
+    );
+  } catch {
+    return null;
+  }
+}
+function storedInsertion(manager, id2, before, bytes, returnedId) {
+  let added = [];
+  for (let attempt = 0; attempt < 8; attempt++) {
+    if (attempt > 0) pause(250);
+    try {
+      added = manager.getAttachmentAssetsById(id2).attachments.filter(
+        (item) => item.parentIdentifier === null && !before.has(item.identifier.toLowerCase())
+      );
+    } catch {
+      added = [];
+    }
+    if (added.length === 1 && added[0].assetPaths.length > 0) break;
+  }
+  if (added.length === 0) return null;
+  if (added.length > 1) throw new Error(UNCERTAIN);
+  const row = added[0];
+  const attachmentId = attachmentCoreDataId(id2, row.pk);
+  if (returnedId && /\/ICAttachment\/p\d+$/.test(returnedId) && returnedId !== attachmentId)
+    throw new Error(UNCERTAIN);
+  const expected = sha256(bytes);
+  const matches = row.assetPaths.some((path10) => {
+    let descriptor;
+    try {
+      descriptor = openSync5(path10, constants5.O_RDONLY | constants5.O_NOFOLLOW);
+      const stat = fstatSync5(descriptor);
+      return stat.isFile() && stat.size === bytes.length && sha256(readFileSync3(descriptor)) === expected;
+    } catch {
+      return false;
+    } finally {
+      if (descriptor !== void 0) closeSync5(descriptor);
+    }
+  });
+  if (!matches)
+    throw new Error(
+      `Notes' database shows new attachment ${attachmentId} on this note, but its file bytes could not be verified; read the exact note and do not attach the file again`
+    );
+  return { attachmentId, name: row.filename };
+}
 function attachFile(manager, args) {
   const { id: id2, expectedContentHash, path: path10 } = args;
   const name = attachmentName(path10, args.filename);
@@ -51539,6 +51632,7 @@ function attachFile(manager, args) {
   if (before.hash !== expectedContentHash) throw new Error("Note revision changed");
   const bytes = localAttachment(path10);
   const beforeAttachments = manager.listAttachmentsById(id2);
+  const beforeStored = storedAttachmentIds(manager, id2);
   const directory = mkdtempSync4(join22(tmpdir4(), "notes-attachment-add-"));
   const temporaryFile = join22(directory, name);
   try {
@@ -51558,27 +51652,39 @@ function attachFile(manager, args) {
     );
     let inserted = readInserted();
     for (let attempt = 0; attempt < 4 && (inserted.length !== 1 || returnedId && returnedId !== inserted[0].id); attempt++) {
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250);
+      pause(250);
       inserted = readInserted();
     }
     const persistentReturnedId = returnedId && /\/ICAttachment\/p\d+$/.test(returnedId);
-    if (inserted.length !== 1 || persistentReturnedId && returnedId !== inserted[0].id)
-      throw new Error(
-        "Attachment insertion outcome uncertain; read the exact note before retrying"
-      );
-    const attachmentId = inserted[0].id;
-    const fetched = manager.getAttachmentBase64ById(id2, attachmentId);
-    const actual = typeof fetched.base64 === "string" ? Buffer.from(fetched.base64, "base64") : null;
-    if (!actual || createHash2("sha256").update(actual).digest("hex") !== createHash2("sha256").update(bytes).digest("hex"))
-      throw new Error("Attachment bytes were not verified; read the exact note before retrying");
-    const nameVerified = inserted[0].name === name;
+    let attachmentId;
+    let reportedName;
+    let verifiedBy = "applescript";
+    if (inserted.length === 1 && !(persistentReturnedId && returnedId !== inserted[0].id)) {
+      attachmentId = inserted[0].id;
+      reportedName = inserted[0].name;
+      const fetched = manager.getAttachmentBase64ById(id2, attachmentId);
+      const actual = typeof fetched.base64 === "string" ? Buffer.from(fetched.base64, "base64") : null;
+      if (!actual || sha256(actual) !== sha256(bytes))
+        throw new Error("Attachment bytes were not verified; read the exact note before retrying");
+    } else {
+      const stored = inserted.length === 0 && beforeStored ? storedInsertion(manager, id2, beforeStored, bytes, returnedId) : null;
+      if (!stored)
+        throw new Error(
+          inserted.length === 0 && !beforeStored ? `${UNCERTAIN}. Notes' AppleScript does not list some attachments (PDFs on macOS 27); grant Full Disk Access so the server can verify through the Notes database` : UNCERTAIN
+        );
+      attachmentId = stored.attachmentId;
+      reportedName = stored.name;
+      verifiedBy = "database";
+    }
+    const nameVerified = reportedName === name;
     return {
       ok: true,
       id: id2,
       attachmentId,
       contentHash: after.hash,
       bytes: bytes.length,
-      name: inserted[0].name,
+      name: reportedName,
+      ...verifiedBy === "database" ? { verifiedBy } : {},
       ...args.filename === void 0 ? {} : {
         filenameVerified: nameVerified,
         ...nameVerified ? {} : {
@@ -53000,7 +53106,7 @@ function canonicalJson(value) {
     return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
   return JSON.stringify(value);
 }
-function sha256(text2) {
+function sha2562(text2) {
   return createHash4("sha256").update(text2).digest("hex");
 }
 var round = (v, digits) => {
@@ -53840,7 +53946,7 @@ function analysisFor(source, analyzer, viewport) {
   const classification = !importable || requiredLosses.includes("drop-content") ? "unsupported" : requiredLosses.length ? "lossy" : "safe";
   const analysis = {
     analyzer: SVG_ANALYZER_VERSION,
-    source: { sha256: sha256(source), bytes: source.length },
+    source: { sha256: sha2562(source), bytes: source.length },
     classification,
     importable,
     defaultWriteAllowed: importable && classification === "safe",
@@ -53861,7 +53967,7 @@ function analysisFor(source, analyzer, viewport) {
     issues: analyzer.issues,
     issuesTruncated: analyzer.issuesTruncated
   };
-  const analysisDigest = "sha256:" + sha256(canonicalJson({ analysis, drawing }));
+  const analysisDigest = "sha256:" + sha2562(canonicalJson({ analysis, drawing }));
   return { analysis: { ...analysis, analysisDigest }, drawing };
 }
 function analyzeSvgBuffer(source) {
@@ -55947,11 +56053,25 @@ function readExactNoteSnapshot(id2) {
       error: `Note "${note.title}" is password-protected and cannot be changed. Unlock it in Notes.app first.`
     };
   }
-  const body = notesManager.getNoteContentById(id2);
-  if (!body) return { error: `Failed to read content of note "${note.title}"` };
+  const { body, error: error2 } = notesManager.readNoteBodyById(id2);
+  if (!body) {
+    const reason = bodyReadFailureMessage(id2, note.title, error2);
+    return { error: `${reason}${error2 ? "\n\nNothing was changed." : ""}` };
+  }
   const rich = enrichNoteRead(id2, body);
   return { note, body, rich, contentHash: richContentHash(body, rich) };
 }
+function bodyReadFailureMessage(id2, title, error2) {
+  let attachments;
+  if (classifyBodyReadError(error2) !== "other") {
+    try {
+      attachments = readNoteStructure(id2, { includeText: false }).attachments;
+    } catch {
+      attachments = void 0;
+    }
+  }
+  return describeBodyReadFailure(title, error2, attachments);
+}
 var NOT_DELETED_MESSAGE = "Notes.app accepted the delete, but the note is still in its original folder, so it was not moved to Recently Deleted. Nothing was deleted; read the note again before retrying.";
 function containerUnknownMessage(title) {
   return `Could not read which folder note "${title}" is in, so it may already be in Recently Deleted, where deleting it would remove it permanently. Nothing was deleted. Retry in a moment; if it keeps failing, quit and reopen Notes.app, then retry.`;
@@ -56365,13 +56485,14 @@ ${lines}${footer}`,
 registerTool(
   "get-note-content",
   {
-    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the exact note id, content, contentHash revision token, parsed hashtags, nativeTags, restored links, richContentComplete/writable, and strippedImages/truncated when the body was capped. Read the warning when writable is false.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.\nSafety: inline images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with '[inline image omitted: ...]' text placeholders, so the returned body is lossy whenever truncated is true. Mutations refuse attachment-bearing notes; edit those in Notes.app.",
+    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the exact note id, content, contentHash revision token, parsed hashtags, nativeTags, restored links, richContentComplete/writable, and strippedImages/truncated when the body was capped. Read the warning when writable is false.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.\nSafety: inline images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with '[inline image omitted: ...]' text placeholders, so the returned body is lossy whenever truncated is true. Mutations refuse attachment-bearing notes; edit those in Notes.app. Notes.app returns images inside the body as base64, so a note with a very large image can time out; the error then names the cause, and a larger timeoutSeconds gives the read more time.",
     inputSchema: {
       id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe(
         "Account name (defaults to Notes.app's default account; exact or unique-prefix match, ignored if id is provided)"
-      )
+      ),
+      timeoutSeconds: timeoutSecondsInput
     },
     outputSchema: {
       id: external_exports.string().optional(),
@@ -56404,9 +56525,9 @@ registerTool(
           `Note "${note2.title}" is password-protected and cannot be read. Unlock it in Notes.app first.`
         );
       }
-      const rawContent2 = notesManager.getNoteContentById(id2);
+      const { body: rawContent2, error: readError2 } = notesManager.readNoteBodyById(id2);
       if (!rawContent2) {
-        return errorResponse(`Failed to read content of note "${note2.title}"`);
+        return errorResponse(bodyReadFailureMessage(id2, note2.title, readError2));
       }
       const rich2 = enrichNoteRead(id2, rawContent2);
       const stripped2 = stripLargeInlineImages(rich2.content);
@@ -56446,9 +56567,9 @@ registerTool(
         `Note "${title}" is password-protected and cannot be read. Unlock it in Notes.app first.`
       );
     }
-    const rawContent = notesManager.getNoteContent(title, account);
+    const { body: rawContent, error: readError } = notesManager.readNoteBodyById(note.id);
     if (!rawContent) {
-      return errorResponse(`Failed to read content of note "${title}"`);
+      return errorResponse(bodyReadFailureMessage(note.id, title, readError));
     }
     const rich = enrichNoteRead(note.id, rawContent);
     const stripped = stripLargeInlineImages(rich.content);

package/package.json

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