apple-notes-mcp 2.8.13 → 2.8.15

package/README.md

@@ -71,6 +71,16 @@ workflows. Confirm **Add Shortcut** in each macOS window, then verify with
 support silent Shortcut import, so merely connecting an MCP client never opens
 setup windows or bypasses these confirmations.
 
+After install **and after every upgrade**, open Shortcuts.app and run each
+bridge — `Apple Notes MCP - Native Tags` and
+`Apple Notes MCP - Background Operations v5` — once in the foreground, choosing
+**Always Allow** when Shortcuts asks for permission. The server runs these
+Shortcuts in the background, where Shortcuts cannot display a first-run consent
+prompt: an unanswered one stalls every native write on that bridge until it
+times out, while `doctor` still reports the bridge installed. Quitting or
+relaunching Shortcuts.app or Notes.app does not clear it; the foreground run
+does, once per bridge.
+
 ### Using the Codex Marketplace
 
 The same plugin is available for Codex. Add the marketplace and install the plugin:
@@ -225,6 +235,14 @@ Creates a new note in Apple Notes.
 
 > **Note:** The title is automatically prepended as `<h1>` in both plaintext and HTML formats. Do not include a `<h1>` title tag in the `content` parameter, or the title will appear twice.
 
+> **Known limitation:** `create-note` sets the note body directly via AppleScript's
+> `body` property, which does not apply real Notes paragraph styles for interior
+> content — an `<h2>`/`<h3>` tag or a `<span style="font-size: …px">` heading span
+> in `content` renders as plain bold, styled text, not an actual Heading or
+> Subheading ([#172](https://github.com/sweetrb/apple-notes-mcp/issues/172)). Real
+> Heading/Subheading styles can currently only be added to a note that already
+> exists, with [`append-native`](#append-native)'s `format: "markdown"`.
+
 **Returns:** Confirmation message with note title and ID. Save the ID for subsequent operations like `update-note`, `delete-note`, etc.
 
 ---
@@ -339,7 +357,10 @@ Access.
 #### `native-tags-status`
 
 Checks whether exactly one configured Native Tags Shortcut is installed. An
-installed workflow may still need macOS permission on its first execution.
+installed workflow may still need macOS permission on its first execution, and
+installation does not show whether that consent was given: run it once in the
+foreground in Shortcuts.app and choose **Always Allow** after install or upgrade
+(see [Troubleshooting](#native-writes-time-out-or-report-an-uncertain-outcome)).
 
 ---
 
@@ -1048,7 +1069,10 @@ Lists all notes shared with collaborators.
 ### Native background operations
 
 Install the signed workflows once as described in
-[`shortcuts/README.md`](shortcuts/README.md). Native writes never use UI
+[`shortcuts/README.md`](shortcuts/README.md), then run each once in the
+foreground in Shortcuts.app and choose **Always Allow** — again after every
+upgrade — so no first-run consent prompt is left for a background run that
+cannot display it. Native writes never use UI
 automation or write directly to the Notes database. Every operation requires an
 exact note ID, a fresh `expectedContentHash`, and a distinctive existing
 `scopeText` so the Shortcut and server can independently resolve the same note.
@@ -1066,9 +1090,16 @@ when `scopeText` is supplied. Use a distinctive phrase of plain words without
 punctuation, hashtags, or paths because Notes search may not resolve them
 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.
+the accepted subset in the error. `format: "markdown"` accepts the same bounded
+subset as `format: "html"`'s Markdown-shaped content (`#`/`##`/`###` headings,
+flat lists, emphasis, and inline links) but is sent through Notes' own native
+Markdown importer rather than converted to HTML first, so `#`/`##`/`###`
+produce real Title/Heading/Subheading — Notes' HTML importer only
+distinguishes two heading levels and renders `###` the same as `##`. A
+transport failure names the Shortcut it was waiting on, so a missing or
+unapproved bridge is identified rather than guessed at; a timeout also says it
+may be an unanswered first-run consent prompt and names the Shortcut to run once
+in the foreground.
 
 #### `create-checklist-item`
 
@@ -1383,6 +1414,12 @@ In a JSON string literal the two characters `\\` denote **one** literal backslas
 - Go to System Settings > Privacy & Security > Automation
 - Ensure your terminal/Claude has permission to control Notes
 
+### Native writes time out or report an uncertain outcome
+- Symptom: `add-native-tags`, `set-note-pinned`, `append-native` or another native write fails with "Shortcuts timed out waiting for …", "Operation outcome uncertain" or "readback was not verified", while `doctor` and `get-capabilities` report the bridges installed
+- Common cause, especially right after install or upgrade: the bridge Shortcut is waiting on a first-run consent prompt. The server runs it in the background, where Shortcuts cannot display that prompt, so the run stalls until it times out
+- Fix: open Shortcuts.app, run the Shortcut the error names (`Apple Notes MCP - Native Tags` or `Apple Notes MCP - Background Operations v5`) once in the foreground and choose **Always Allow**. Each bridge needs this once; quitting or relaunching Shortcuts.app or Notes.app does not clear it
+- Read the exact note before retrying — the write may have landed
+
 ### "Note not found"
 - Note titles must match exactly (case-sensitive)
 - Check if the note is in a different account

package/build/index.js

@@ -39800,10 +39800,12 @@ function htmlLinks(html) {
   }
   return links;
 }
+var BARE_HTTP_ORIGIN = /^https?:\/\/[^/?#]+$/i;
+var normalizedUrl = (url) => BARE_HTTP_ORIGIN.test(url) ? `${url}/` : url;
 function linkSignature(links) {
   return JSON.stringify(
     links.flatMap(
-      (link) => normalized(link.text).split("").map((char) => [char, link.url])
+      (link) => normalized(link.text).split("").map((char) => [char, normalizedUrl(link.url)])
     )
   );
 }
@@ -42734,6 +42736,14 @@ import { execFileSync as execFileSync6 } from "node:child_process";
 import { mkdtempSync as mkdtempSync2, writeFileSync, rmSync as rmSync2 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { join as join7 } from "node:path";
+
+// src/services/shortcutConsent.ts
+function shortcutConsentHint(shortcut) {
+  const target = shortcut ? `"${shortcut}"` : "the bridge Shortcut";
+  return `This may be an unanswered first-run Shortcuts consent prompt, which a background run cannot display: run ${target} once in the foreground in Shortcuts.app and choose Always Allow.`;
+}
+
+// src/services/nativeTags.ts
 var NATIVE_TAGS_SHORTCUT = "Apple Notes MCP - Native Tags";
 function normalizeNativeTags(tags) {
   if (!tags.length || tags.length > 100) throw new Error("Provide between 1 and 100 tags");
@@ -42788,7 +42798,7 @@ function addNativeTags(request, deps) {
   };
   if (after.title !== before.title || allTags.some((tag) => !after.rich.nativeTags.includes(tag)) || textWithoutTags(before.rich.text) !== textWithoutTags(after.rich.text) || linkSignature(before.rich.links) !== linkSignature(after.rich.links) || before.rich.nativeObjectIds.some((id2) => !after.rich.nativeObjectIds.includes(id2)) || before.rich.hasChecklist !== after.rich.hasChecklist) {
     throw new Error(
-      "Shortcuts ran, but exact-ID tags/text/links readback was not verified. Read the note before any retry"
+      transportWarning ? `Shortcuts did not complete cleanly, and exact-ID tags/text/links readback was not verified. Read the note before any retry. ${transportWarning}` : "Shortcuts ran, but exact-ID tags/text/links readback was not verified. Read the note before any retry"
     );
   }
   return {
@@ -42831,9 +42841,12 @@ function runNativeTagsShortcut(input) {
       maxBuffer: 1024 * 1024,
       stdio: ["ignore", "pipe", "pipe"]
     });
-  } catch {
-    throw new Error(
-      `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`
+  } catch (error2) {
+    throw Object.assign(
+      new Error(
+        `Native tag operation did not complete cleanly. ${shortcutConsentHint(status.shortcut)} Do not retry automatically; read the exact note first`
+      ),
+      { shortcut: status.shortcut, code: error2?.code }
     );
   } finally {
     rmSync2(directory, { recursive: true, force: true });
@@ -43117,7 +43130,7 @@ function mutateBackground(request, operation, data, verify, deps) {
     transportUncertain = true;
     const detail = error2;
     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)}`;
+    transportMessage = 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)}`;
   }
   const after = deps.read(request.id);
   try {
@@ -43157,15 +43170,10 @@ function assertAppendedVisibleText(beforeHtml, afterHtml, expected) {
 }
 function appendNative(manager, request) {
   validateAppendContent(request.content, request.format);
-  if (request.format === "markdown")
-    return appendNative(manager, {
-      ...request,
-      content: appendMarkdownHtml(request.content),
-      format: "html"
-    });
   if (request.format === "html" && /<table\b/i.test(request.content))
     throw new Error("Use create-table for verified native table insertion");
-  const op = request.format === "plaintext" ? "append-text" : request.format === "html" ? "append-html" : "append-markdown";
+  const markdownHtml = request.format === "markdown" ? appendMarkdownHtml(request.content) : null;
+  const op = request.format === "plaintext" ? "append-text" : request.format === "markdown" ? "append-markdown" : "append-html";
   const text = request.format === "html" ? "<div><br></div>" + request.content : "\n\n" + request.content;
   return mutateBackground(
     request,
@@ -43173,10 +43181,11 @@ function appendNative(manager, request) {
     { text },
     (before, after) => {
       assertPreserved(before, after, { append: true });
-      const expected = request.format === "html" ? comparableVisibleText(request.content) : request.format === "plaintext" ? request.content : null;
+      const verifyHtml = markdownHtml ?? request.content;
+      const expected = request.format === "plaintext" ? request.content : comparableVisibleText(verifyHtml);
       if (expected) assertAppendedVisibleText(before.html, after.html, expected);
-      if (request.format === "html")
-        assertAppendedHtmlLinks(before.rich.links.length, after.rich.links, request.content);
+      if (request.format === "html" || request.format === "markdown")
+        assertAppendedHtmlLinks(before.rich.links.length, after.rich.links, verifyHtml);
     },
     backgroundDependencies(manager)
   );
@@ -43241,6 +43250,7 @@ function runDoctor(manager) {
     status: fda ? "ok" : "warn",
     detail: fda ? "granted \u2014 the Notes database is readable (checklist state, note metadata, note links, sync detail)" : `not granted \u2014 get-checklist-state, get-note-metadata, and the checklist annotations in get-note-markdown won't work; get-note-link fails on macOS 26+ (macOS 12-15 falls back to AppleScript); get-sync-status still answers but cannot see pending uploads. Everything else is pure AppleScript and is unaffected. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it and re-run doctor. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`
   });
+  const consentReminder = "After install or upgrade, run each bridge Shortcut once in the foreground in Shortcuts.app and choose Always Allow: a background run cannot display a first-run consent prompt, so an unanswered one stalls that bridge's native writes until they time out while this check stays ok";
   try {
     const bridgeStatuses = [NATIVE_TAGS_SHORTCUT, BACKGROUND_SHORTCUT].map(
       (name) => nativeTagsStatus(name)
@@ -43249,7 +43259,7 @@ function runDoctor(manager) {
     checks.push({
       name: "Native write Shortcuts",
       status: missing.length ? "warn" : "ok",
-      detail: missing.length ? `missing: ${missing.map((status) => status.shortcut).join(", ")}. Run apple-notes-mcp setup and approve Add Shortcut in macOS` : "both native-write bridges are installed"
+      detail: missing.length ? `missing: ${missing.map((status) => status.shortcut).join(", ")}. Run apple-notes-mcp setup and approve Add Shortcut in macOS. ${consentReminder}` : `both native-write bridges are installed. ${consentReminder}`
     });
   } catch (error2) {
     checks.push({
@@ -44263,6 +44273,9 @@ function formatShortcutSetup(report) {
     lines.push(
       "After approving the macOS dialogs, run `apple-notes-mcp setup --check` or the MCP doctor tool."
     );
+  lines.push(
+    "After install or upgrade, run each bridge once in the foreground in Shortcuts.app and choose Always Allow; a background run cannot display a first-run consent prompt and stalls until it times out."
+  );
   return lines.join("\n");
 }
 

package/package.json

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

package/shortcuts/README.md

@@ -15,6 +15,13 @@ Open the signed file and confirm **Add Shortcut** once. macOS may also request
 Notes access on first execution. The `shortcuts` CLI can run an installed
 workflow but cannot silently import one.
 
+After install and after every upgrade, run each bridge once in the foreground in
+Shortcuts.app and choose **Always Allow** when it asks for permission. The
+server runs bridges in the background, where Shortcuts cannot display a
+first-run consent prompt, so an unanswered one stalls that bridge's native
+writes until they time out. Quitting or relaunching Shortcuts.app or Notes.app
+does not clear it; one foreground run per bridge does.
+
 The bridge receives a private temporary JSON file with a title, a distinctive
 existing scope phrase, and normalized tags. Both the server and workflow refuse
 ambiguous note selection. Server readback, rather than CLI output, establishes
@@ -38,6 +45,7 @@ shortcuts sign --mode anyone \
   --output "shortcuts/Apple Notes MCP - Background Operations v5.shortcut"
 ```
 
-Open the signed file and confirm **Add Shortcut** once. Do not install obsolete
+Open the signed file and confirm **Add Shortcut** once, then run it once in the
+foreground in Shortcuts.app and choose **Always Allow** (see above). Do not install obsolete
 workflow versions with the same display name; the server resolves one exact
 installed UUID and refuses duplicates.