apple-notes-mcp 2.9.17 → 2.9.19

package/README.md

@@ -1355,7 +1355,7 @@ Lists all folders in an account with full hierarchical paths.
 {}
 ```
 
-**Returns:** List of folders with IDs, paths, account names, and shared state, plus `identifier`, `parentIdentifier`, and `accountIdentifier` when Full Disk Access is granted. Nested folders are shown as full paths (e.g., `Work/Clients/Omnia`). Duplicate folder names are disambiguated by their full path. Literal slashes in folder names are escaped as `\/` (e.g., `Spain\/Portugal 2023`).
+**Returns:** List of folders with IDs, paths, account names, and shared state, plus `identifier`, `parentIdentifier`, and `accountIdentifier` when Full Disk Access is granted. Nested folders are shown as full paths (e.g., `Work/Clients/Omnia`). Duplicate folder names are disambiguated by their full path. Literal slashes in folder names are escaped as `\/` (e.g., `Spain\/Portugal 2023`). Smart folders are listed too, because Notes' AppleScript lists them like ordinary folders; with Full Disk Access they carry `smartFolder: true` (and `(smart folder)` in the text list). A smart folder cannot hold notes or folders.
 
 ---
 
@@ -2016,7 +2016,8 @@ Each take gets a deadline of 1.5 times its length plus a minute (at most 30 minu
 Adds one nonempty local file of at most 64 MiB to an exact note using `id`, the
 latest `expectedContentHash`, and an absolute `path`. The server never retries
 the insertion. It verifies that existing rich content survived and compares the
-fetched attachment bytes with the source before reporting success.
+size and streamed SHA-256 of Notes' saved copy with the source before reporting
+success, with no read cap below the 64 MiB write limit.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -2353,6 +2354,17 @@ distinctive existing `scopeText` so the Shortcut and server can independently
 resolve the same note. Creating a note from Markdown is
 [`create-note`](#create-note) with `format: "markdown"`.
 
+When the Shortcut refuses a request (its Find Notes step did not return
+exactly one note with that exact title and `scopeText`) or stops with its own
+action error, and the note reads back unchanged, the tool reports the
+Shortcut's reason with `code: "operation_failed"`, `committed: false` and
+`indeterminate: false`: nothing was written, so a retry is safe once the cause
+is fixed. Notes search can lag behind a note created or edited moments ago, so
+a refusal on a brand-new note may clear after a minute. A timeout, or a failed
+readback on a note that did change, is still reported as indeterminate.
+If the Shortcut is not installed, the error is `code: "shortcut_not_installed"`
+with `committed: false`.
+
 #### `get-capabilities`
 
 Reports which background operations are implemented, live-verified, installed,

package/build/index.js

@@ -42435,7 +42435,7 @@ function readSmartFolderIds(read = readSmartFolders) {
 }
 function smartFolderDestinationError(folderPath) {
   return new CodedError(
-    `Refused: "${folderPath}" is a smart folder. Smart folders only gather notes by their rules and cannot hold notes or folders; choose an ordinary folder (list-folders). Nothing was changed`,
+    `Refused: "${folderPath}" is a smart folder. Smart folders only gather notes by their rules and cannot hold notes or folders; choose an ordinary folder (list-folders marks smart folders smartFolder: true). Nothing was changed`,
     {
       code: "unsupported",
       committed: false,
@@ -43881,6 +43881,9 @@ var AppleNotesManager = class {
   /**
    * Lists all folders in an account with full hierarchical paths.
    *
+   * Smart folders are included (AppleScript lists them like ordinary folders)
+   * and carry `smartFolder: true` when the NoteStore database is readable.
+   *
    * Each folder's `name` field contains the full path (e.g., "Work/Clients/Omnia")
    * so that duplicate folder names (e.g., multiple "Archive" folders) are
    * distinguishable and can be used directly in other operations.
@@ -43939,11 +43942,13 @@ var AppleNotesManager = class {
       }
       return safeName;
     };
+    const smart = new Set(entries2.some((entry) => entry.id) ? this.smartFolderIds() : []);
     return entries2.map((entry) => ({
       id: entry.id,
       name: buildPath(entry),
       account: entry.account || targetAccount || "",
-      shared: entry.shared
+      shared: entry.shared,
+      ...smart.has(entry.id) ? { smartFolder: true } : {}
     }));
   }
   /**
@@ -48265,6 +48270,7 @@ function comparableVisibleText(html) {
 }
 
 // src/services/backgroundNotes.ts
+var capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
 var BACKGROUND_SHORTCUT = "Apple Notes MCP - Background Operations v5";
 var backgroundShortcutName = () => process.env.APPLE_NOTES_MCP_BACKGROUND_SHORTCUT || BACKGROUND_SHORTCUT;
 var backgroundStatus = () => nativeTagsStatus(backgroundShortcutName());
@@ -48375,10 +48381,14 @@ function validateAppendContent(content, format, options = {}) {
         );
   }
 }
+var BRIDGE_REFUSED = "refused the request without running it: its Find Notes step did not find exactly one note with this exact title whose body contains the scope text. Notes search can lag behind a note created or edited moments ago, so wait a minute and retry, or pass a longer, more distinctive scopeText";
 function runBackgroundShortcut(input, status = backgroundStatus()) {
   if (!status.installed)
-    throw new Error(
-      `Install the supplied "${status.shortcut}" Shortcut once; Shortcuts must list it exactly once`
+    throw Object.assign(
+      new Error(
+        `Install the supplied "${status.shortcut}" Shortcut once; Shortcuts must list it exactly once`
+      ),
+      { shortcut: status.shortcut, notInstalled: true }
     );
   const directory = mkdtempSync4(join17(tmpdir4(), "apple-notes-background-"));
   try {
@@ -48401,16 +48411,31 @@ function runBackgroundShortcut(input, status = backgroundStatus()) {
       }),
       { mode: 384 }
     );
+    let output;
     try {
-      execFileSync16("/usr/bin/shortcuts", ["run", status.identifier, "--input-path", file], {
-        encoding: "utf8",
-        timeout: callTimeoutMs() ?? 6e4,
-        maxBuffer: 1024 * 1024,
-        stdio: ["ignore", "pipe", "pipe"]
-      });
+      output = execFileSync16(
+        "/usr/bin/shortcuts",
+        ["run", status.identifier, "--input-path", file],
+        {
+          encoding: "utf8",
+          timeout: callTimeoutMs() ?? 6e4,
+          maxBuffer: 1024 * 1024,
+          stdio: ["ignore", "pipe", "pipe"]
+        }
+      );
     } catch (error2) {
       throw Object.assign(error2, { shortcut: status.shortcut });
     }
+    if (/_REFUSED\b/.test(String(output ?? "")))
+      throw Object.assign(
+        new Error(
+          status.shortcut === markdownShortcutName() ? "refused the request without running it" : BRIDGE_REFUSED
+        ),
+        {
+          shortcut: status.shortcut,
+          refused: true
+        }
+      );
   } finally {
     rmSync4(directory, { recursive: true, force: true });
   }
@@ -48480,6 +48505,7 @@ function assertPreserved(before, after, options = {}) {
 function describeTransportFailure(error2) {
   const detail = error2;
   const named = detail?.shortcut ? `the "${detail.shortcut}" Shortcut` : "the background Shortcut";
+  if (detail?.refused) return `${named} ${detail.message}`;
   return detail?.code === "ETIMEDOUT" ? `Shortcuts timed out waiting for ${named}. ${shortcutConsentHint(detail.shortcut)}` : `${named} failed: ${String(detail?.stderr || detail?.message || "no output").trim().slice(0, 400)}`;
 }
 function mutateBackground(request, operation, data, verify, deps) {
@@ -48497,16 +48523,30 @@ function mutateBackground(request, operation, data, verify, deps) {
     throw new Error("Note revision changed during preflight");
   let transportUncertain = false;
   let transportMessage = "";
+  let transportError;
   try {
     deps.run({ ...data, operation, title: before.title, scopeText: request.scopeText });
   } catch (error2) {
     transportUncertain = true;
+    transportError = error2 ?? {};
     transportMessage = describeTransportFailure(error2);
   }
   const after = deps.read(request.id);
   try {
     verify(before, after);
   } catch (error2) {
+    const unchanged = after.hash === before.hash && after.pinned === before.pinned;
+    if (transportError?.notInstalled && unchanged)
+      throw new CodedError(
+        `${transportError.message}. The Shortcut never ran, so nothing was written; run apple-notes-mcp setup, then retry.`,
+        { code: "shortcut_not_installed", committed: false, indeterminate: false }
+      );
+    const exitedWithError = typeof transportError?.status === "number" && transportError.status !== 0 && !transportError.signal && transportError.code !== "ETIMEDOUT";
+    if (transportError && (transportError.refused || exitedWithError) && unchanged)
+      throw new CodedError(
+        `${capitalize(transportMessage)}. The note is unchanged, so nothing was written; it is safe to retry once the cause is fixed.`,
+        { code: "operation_failed", committed: false, indeterminate: false }
+      );
     throw new Error(
       `Operation outcome uncertain; read exact note before any retry: ${error2 instanceof Error ? error2.message : "readback failed"}${transportMessage ? "; " + transportMessage : ""}`
     );
@@ -53063,6 +53103,7 @@ import {
   mkdtempSync as mkdtempSync6,
   openSync as openSync7,
   readFileSync as readFileSync4,
+  readSync as readSync5,
   rmSync as rmSync6,
   writeFileSync as writeFileSync5
 } from "node:fs";
@@ -53344,7 +53385,7 @@ function localAttachment(path10) {
   const descriptor = openSync7(path10, constants7.O_RDONLY | constants7.O_NOFOLLOW);
   try {
     const stat = fstatSync7(descriptor);
-    if (!stat.isFile() || stat.size === 0 || stat.size > 64 * 1024 * 1024)
+    if (!stat.isFile() || stat.size === 0 || stat.size > MAX_ADD_ATTACHMENT_BYTES)
       throw new Error("Attachment must be a nonempty regular file of at most 64 MiB");
     const bytes = readFileSync4(descriptor);
     if (bytes.length !== stat.size)
@@ -53354,6 +53395,30 @@ function localAttachment(path10) {
     closeSync7(descriptor);
   }
 }
+var MAX_ADD_ATTACHMENT_BYTES = 64 * 1024 * 1024;
+function fileMatches(path10, size, expected) {
+  let descriptor;
+  try {
+    descriptor = openSync7(path10, constants7.O_RDONLY | constants7.O_NOFOLLOW);
+    const stat = fstatSync7(descriptor);
+    if (!stat.isFile() || stat.size !== size) return false;
+    const hash = createHash3("sha256");
+    const chunk = Buffer.allocUnsafe(1024 * 1024);
+    let total = 0;
+    for (; ; ) {
+      const read = readSync5(descriptor, chunk, 0, chunk.length, null);
+      if (read === 0) break;
+      total += read;
+      if (total > size) return false;
+      hash.update(chunk.subarray(0, read));
+    }
+    return total === size && hash.digest("hex") === expected;
+  } catch {
+    return false;
+  } finally {
+    if (descriptor !== void 0) closeSync7(descriptor);
+  }
+}
 function registerDirectOperations(server2, manager) {
   function tool(name, description, inputSchema, handler, readOnly = false) {
     server2.registerTool(
@@ -53560,18 +53625,7 @@ function storedInsertion(manager, id2, before, bytes, returnedId) {
   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 = openSync7(path10, constants7.O_RDONLY | constants7.O_NOFOLLOW);
-      const stat = fstatSync7(descriptor);
-      return stat.isFile() && stat.size === bytes.length && sha256(readFileSync4(descriptor)) === expected;
-    } catch {
-      return false;
-    } finally {
-      if (descriptor !== void 0) closeSync7(descriptor);
-    }
-  });
+  const matches = row.assetPaths.some((path10) => fileMatches(path10, bytes.length, expected));
   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`
@@ -53615,9 +53669,9 @@ function attachFile(manager, args, checked) {
     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))
+      const verifyPath = join24(directory, "verify", "attachment.bin");
+      const saved = manager.saveAttachmentById(id2, attachmentId, verifyPath);
+      if (!saved.success || !fileMatches(saved.savedPath ?? verifyPath, bytes.length, 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;
@@ -53987,7 +54041,7 @@ import {
   mkdirSync as mkdirSync7,
   openSync as openSync8,
   readdirSync as readdirSync4,
-  readSync as readSync5,
+  readSync as readSync6,
   renameSync,
   unlinkSync as unlinkSync3,
   writeSync as writeSync5
@@ -54078,7 +54132,7 @@ var TemplateStore = class {
       const data = Buffer.alloc(stat.size);
       let read = 0;
       while (read < stat.size) {
-        const n = readSync5(fd, data, read, stat.size - read, read);
+        const n = readSync6(fd, data, read, stat.size - read, read);
         if (n <= 0) break;
         read += n;
       }
@@ -54395,7 +54449,7 @@ function registerMarkdownTemplates(server2, store = () => new TemplateStore()) {
 
 // src/utils/svgAnalyzer.ts
 import { createHash as createHash5 } from "node:crypto";
-import { closeSync as closeSync9, constants as constants9, fstatSync as fstatSync9, openSync as openSync9, readSync as readSync6 } from "node:fs";
+import { closeSync as closeSync9, constants as constants9, fstatSync as fstatSync9, openSync as openSync9, readSync as readSync7 } from "node:fs";
 
 // src/utils/svgColor.ts
 var NAMED = {
@@ -56382,7 +56436,7 @@ function readSvgSource(path10) {
     const buffer = Buffer.alloc(SVG_LIMITS.maxSourceBytes + 1);
     let total = 0;
     for (; ; ) {
-      const n = readSync6(fd, buffer, total, buffer.length - total, null);
+      const n = readSync7(fd, buffer, total, buffer.length - total, null);
       if (n === 0) break;
       total += n;
       if (total > SVG_LIMITS.maxSourceBytes)
@@ -56633,7 +56687,9 @@ function appendChecklistItems(args, deps, readRich) {
         stoppedAt: {
           index,
           text: text2,
-          outcome: wrote ? "uncertain" : "not-written",
+          // A bridge refusal or failure with an unchanged readback is
+          // reported as not written even though verification ran (#248).
+          outcome: wrote && !(error2 instanceof CodedError && error2.envelope.committed === false) ? "uncertain" : "not-written",
           error: error2 instanceof Error ? error2.message : String(error2)
         },
         notAttempted: args.items.slice(index + 1),
@@ -60581,7 +60637,7 @@ ${noteList}`, {
 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.",
+    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: smart folders are listed too (AppleScript lists them like ordinary folders) and are marked smartFolder: true when Full Disk Access lets the server read the Notes database; they cannot hold notes. Warns if iCloud sync is active.",
     inputSchema: {
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account to list folders from")
     },
@@ -60611,7 +60667,7 @@ ${syncWarnings.join(" ")}` : "";
       return successResponse(`No folders found${acct}${syncNote}`, { folders: [], count: 0 });
     }
     const resolvedAcct = folders[0]?.account ? ` (${folders[0].account})` : acct;
-    const folderList = folders.map((f) => `  - ${f.name}`).join("\n");
+    const folderList = folders.map((f) => `  - ${f.name}${f.smartFolder ? " (smart folder)" : ""}`).join("\n");
     return successResponse(
       `Found ${folders.length} folders${resolvedAcct}:
 ${folderList}${syncNote}`,
@@ -60627,7 +60683,7 @@ registerTool(
   {
     description: `Use when: listing Smart Folders and the rules that define them.
 Returns: each smart folder's name, ids, account, and parent, its rules decoded as match ("all"/"any"/"none") plus filters (each with a readable description), the stored query with the outer deleted wrapper removed, and the raw stored query JSON. With includeMatchingNotes, also the notes Notes.app currently shows in each folder.
-Do not use when: listing ordinary folders (list-folders) or searching notes (search-notes).
+Do not use when: listing all folders with paths (list-folders, which lists smart folders alongside ordinary ones) or searching notes (search-notes).
 Safety: read-only; reads the NoteStore database and requires Full Disk Access. includeMatchingNotes asks Notes.app (Automation permission) for each folder's current contents rather than re-evaluating the rules. Unrecognized rules are kept as "unknown" filters and set fullyDecoded false.`,
     inputSchema: {
       includeMatchingNotes: external_exports.boolean().optional().describe(

package/package.json

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