apple-notes-mcp 2.8.11 → 2.8.13

package/README.md

@@ -565,8 +565,22 @@ visible text after saving, not byte-identical rich formatting. Warns when the
 note is shared with collaborators.
 
 **Safety:** The append is rejected if the note changed since it was read, rich
-metadata is unavailable, or the note contains attachments or other native
-objects. Existing link destinations are verified after saving.
+metadata is unavailable, or the note contains attachments. Existing link
+destinations are verified after saving.
+
+**Notes containing native objects** (a table, a checklist, native tags) cannot be
+spliced, so they are routed to the native end-append bridge — see
+[`append-native`](#append-native). That path additionally requires `scopeText`,
+keeps the default blank-line `separator` and `position: "after"`, and accepts a
+fixed HTML subset rather than anything Notes.app can render:
+
+| | Native append |
+|---|---|
+| Elements | `<a>` `<b>` `<br>` `<code>` `<del>` `<div>` `<em>` `<h1>` `<h2>` `<h3>` `<i>` `<li>` `<ol>` `<p>` `<s>` `<span>` `<strong>` `<table>` `<tbody>` `<td>` `<th>` `<thead>` `<tr>` `<tt>` `<u>` `<ul>` |
+| Attributes | `href` on `<a>` (`https:`, `http:`, `notes:`, `applenotes:`, `mailto:` only) and a `font-size` style on `<span>`, e.g. `<span style="font-size: 18px">` — the form Notes itself stores a heading as |
+| Refused | every other element and attribute, by name, naming the accepted subset; `<table>` here (use [`create-table`](#create-table)); comments, doctype and processing instructions |
+
+Ordinary notes take the guarded HTML path and are not restricted to that subset.
 
 ---
 
@@ -1050,7 +1064,11 @@ Appends bounded plaintext, semantic HTML, or Markdown while preserving existing
 native objects. The regular `append-to-note` tool routes protected notes here
 when `scopeText` is supplied. Use a distinctive phrase of plain words without
 punctuation, hashtags, or paths because Notes search may not resolve them
-literally.
+literally. `format: "html"` accepts the fixed subset tabulated under
+[`append-to-note`](#append-to-note); content outside it is refused by name, with
+the accepted subset in the error. A transport failure names the Shortcut it was
+waiting on, so a missing or unapproved bridge is identified rather than guessed
+at.
 
 #### `create-checklist-item`
 

package/build/index.js

@@ -39708,7 +39708,7 @@ function visibleCharacters(html) {
     token++;
     if (part[0].startsWith("<")) continue;
     for (const item of part[0].matchAll(
-      /&(?:#[0-9]+;?|#x[0-9a-f]+;?|(?:amp|lt|gt|quot|apos|nbsp)(?:;|(?![a-z0-9=])))|[\s\S]/gi
+      /&(?:#[0-9]+;?|#x[0-9a-f]+;?|(?:amp|lt|gt|quot|nbsp);?|apos;)|[\s\S]/gi
     )) {
       const value = decodeEntity(item[0]);
       for (let i = 0; i < value.length; i++) {
@@ -39770,7 +39770,8 @@ function enrichNoteRead(id2, rawBody) {
         warning: "Native tags, inline objects or checklists are present. Their state is not writable through AppleScript; full-body edits are blocked to preserve them."
       } : {}
     };
-  } catch {
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
     return {
       content: rawBody,
       links: metadata?.links ?? [],
@@ -39778,7 +39779,7 @@ function enrichNoteRead(id2, rawBody) {
       complete: false,
       writable: false,
       revision: metadata?.revision ?? "unavailable",
-      warning: "Rich Notes metadata could not be read or matched. Links/native tags may be missing from this view. Full-body edits are blocked; check Full Disk Access and retry after sync."
+      warning: `Rich Notes metadata could not be read or matched. Links/native tags may be missing from this view. Full-body edits are blocked; check Full Disk Access and retry after sync. (${detail})`
     };
   }
 }
@@ -42832,7 +42833,7 @@ function runNativeTagsShortcut(input) {
     });
   } catch {
     throw new Error(
-      "Native tag operation did not complete cleanly (possibly waiting for macOS permission). Do not retry automatically; read the exact note and check Shortcuts"
+      `Native tag operation did not complete cleanly; the "${status.shortcut}" Shortcut may be waiting for macOS permission. Do not retry automatically; read the exact note and check that Shortcut in Shortcuts.app`
     );
   } finally {
     rmSync2(directory, { recursive: true, force: true });
@@ -42930,49 +42931,62 @@ function readBackgroundSnapshot(manager, id2) {
     checklist: getChecklistItems(id2).items || []
   };
 }
+var NATIVE_APPEND_ELEMENTS = [
+  "a",
+  "b",
+  "br",
+  "code",
+  "del",
+  "div",
+  "em",
+  "h1",
+  "h2",
+  "h3",
+  "i",
+  "li",
+  "ol",
+  "p",
+  "s",
+  "span",
+  "strong",
+  "table",
+  "tbody",
+  "td",
+  "th",
+  "thead",
+  "tr",
+  "tt",
+  "u",
+  "ul"
+];
+var NATIVE_APPEND_SPAN_STYLE = /^font-size\s*:\s*\d{1,3}(?:\.\d+)?(?:px|pt)\s*;?$/i;
+var NATIVE_APPEND_HTML_SUBSET = `Native append accepts ${NATIVE_APPEND_ELEMENTS.map((e) => `<${e}>`).join(" ")}, with href on <a> and a font-size style on <span> as the only attributes; everything else needs update-note.`;
 function validateAppendContent(content, format) {
   if (!content || content.length > 1024 * 1024 || content.includes("\0"))
     throw new Error("Invalid append content (limit 1 MiB)");
   if (format === "html") {
-    const allowed = /* @__PURE__ */ new Set([
-      "div",
-      "p",
-      "br",
-      "b",
-      "strong",
-      "i",
-      "em",
-      "u",
-      "s",
-      "del",
-      "h1",
-      "h2",
-      "h3",
-      "ul",
-      "ol",
-      "li",
-      "a",
-      "table",
-      "thead",
-      "tbody",
-      "tr",
-      "td",
-      "th"
-    ]);
+    const allowed = new Set(NATIVE_APPEND_ELEMENTS);
     for (const tag of content.matchAll(/<\/?\s*([a-z][a-z0-9]*)\b([^>]*)>/gi)) {
-      if (!allowed.has(tag[1].toLowerCase()))
-        throw new Error(`Unsupported HTML element: ${tag[1]}`);
+      const name = tag[1].toLowerCase();
+      if (!allowed.has(name))
+        throw new Error(`Unsupported HTML element: <${name}>. ${NATIVE_APPEND_HTML_SUBSET}`);
       let attrs = tag[2].replace(/\/$/, "").trim();
-      if (tag[1].toLowerCase() === "a")
+      if (name === "a")
         attrs = attrs.replace(/\bhref\s*=\s*(["'])(.*?)\1/gi, (_s, _q, url) => {
           if (!/^(https?:\/\/|notes:\/\/|applenotes:|mailto:)/i.test(url) || Array.from(url).some((c) => c.charCodeAt(0) < 33))
             throw new Error("Unsupported link URL");
           return "";
         });
+      if (name === "span")
+        attrs = attrs.replace(/\bstyle\s*=\s*(["'])(.*?)\1/gi, (_s, _q, style) => {
+          if (!NATIVE_APPEND_SPAN_STYLE.test(style.trim()))
+            throw new Error(
+              `Unsupported <span> style: ${style.trim().slice(0, 80)}. Native append accepts font-size only, as in <span style="font-size: 18px">.`
+            );
+          return "";
+        });
       if (attrs.trim())
-        throw new Error(
-          "Unsupported HTML attributes; use semantic formatting and explicit blank paragraphs"
-        );
+        throw new Error(`Unsupported HTML attributes on <${name}>. ${NATIVE_APPEND_HTML_SUBSET}`);
     }
     if (/<!--|<!|<\?|<[^>]*$/u.test(content)) throw new Error("Unsupported HTML markup");
   }
@@ -42982,7 +42996,9 @@ function validateAppendContent(content, format) {
 function runBackgroundShortcut(input) {
   const status = backgroundStatus();
   if (!status.installed)
-    throw new Error("Install the supplied Background Operations shortcut once");
+    throw new Error(
+      `Install the supplied "${status.shortcut}" Shortcut once; Shortcuts must list it exactly once`
+    );
   const directory = mkdtempSync3(join8(tmpdir3(), "apple-notes-background-"));
   try {
     const file = join8(directory, "request.json");
@@ -43004,12 +43020,16 @@ function runBackgroundShortcut(input) {
       }),
       { mode: 384 }
     );
-    execFileSync7("/usr/bin/shortcuts", ["run", status.identifier, "--input-path", file], {
-      encoding: "utf8",
-      timeout: 6e4,
-      maxBuffer: 1024 * 1024,
-      stdio: ["ignore", "pipe", "pipe"]
-    });
+    try {
+      execFileSync7("/usr/bin/shortcuts", ["run", status.identifier, "--input-path", file], {
+        encoding: "utf8",
+        timeout: 6e4,
+        maxBuffer: 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch (error2) {
+      throw Object.assign(error2, { shortcut: status.shortcut });
+    }
   } finally {
     rmSync3(directory, { recursive: true, force: true });
   }
@@ -43096,7 +43116,8 @@ function mutateBackground(request, operation, data, verify, deps) {
   } catch (error2) {
     transportUncertain = true;
     const detail = error2;
-    transportMessage = detail?.code === "ETIMEDOUT" ? "Shortcuts timed out; check for an interactive parameter or permission request" : String(detail?.stderr || detail?.message || "Shortcuts failed").trim().slice(0, 500);
+    const named = detail?.shortcut ? `the "${detail.shortcut}" Shortcut` : "the background Shortcut";
+    transportMessage = detail?.code === "ETIMEDOUT" ? `Shortcuts timed out waiting for ${named}; check for an interactive parameter or permission request` : `${named} failed: ${String(detail?.stderr || detail?.message || "no output").trim().slice(0, 400)}`;
   }
   const after = deps.read(request.id);
   try {
@@ -43980,7 +44001,7 @@ function registerNativeOperations(server2, manager) {
   );
   tool(
     "append-native",
-    "Use when: appending formatted content to a native-object note without replacing its body.\nReturns: exact-ID preservation and appended-content readback.\nDo not use when: the existing note can be safely handled by append-to-note or the scope phrase is ambiguous.\nSafety: requires a fresh revision and unique existing scope phrase of plain words; avoid punctuation, hashtags, and paths because Notes search may not resolve them literally. Supports bounded plaintext, semantic HTML, and Markdown without external fetching or automatic retries.",
+    "Use when: appending formatted content to a native-object note without replacing its body.\nReturns: exact-ID preservation and appended-content readback.\nDo not use when: the existing note can be safely handled by append-to-note or the scope phrase is ambiguous.\nSafety: requires a fresh revision and unique existing scope phrase of plain words; avoid punctuation, hashtags, and paths because Notes search may not resolve them literally. Supports bounded plaintext, semantic HTML, and Markdown without external fetching or automatic retries.\nHTML subset: " + NATIVE_APPEND_HTML_SUBSET,
     {
       ...common,
       content: external_exports.string().min(1).max(1024 * 1024),
@@ -45022,7 +45043,7 @@ registerTool(
 registerTool(
   "append-to-note",
   {
-    description: "Use when: adding content to one exact note after reading it by id.\nReturns: exact id, new content hash, and visible-text readback verification.\nDo not use when: you only have a title or the note changed since the read.\nSafety: protected native-object notes use native end-append with scopeText; ordinary notes retain guarded HTML editing. Notes.app normalizes HTML, so rich formatting is not claimed as byte-identical.",
+    description: "Use when: adding content to one exact note after reading it by id.\nReturns: exact id, new content hash, and visible-text readback verification.\nDo not use when: you only have a title or the note changed since the read.\nSafety: protected native-object notes use native end-append with scopeText; ordinary notes retain guarded HTML editing. Notes.app normalizes HTML, so rich formatting is not claimed as byte-identical.\nNative-append HTML subset (protected notes only; ordinary notes accept any HTML Notes.app renders): " + NATIVE_APPEND_HTML_SUBSET + " Native append also requires scopeText, the default blank-line separator and position 'after'.",
     inputSchema: {
       id: noteIdInput,
       expectedContentHash: expectedContentHashInput,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.8.11",
+  "version": "2.8.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",