apple-notes-mcp 2.8.14 → 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:
@@ -347,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)).
 
 ---
 
@@ -1056,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.
@@ -1081,7 +1097,9 @@ 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.
+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`
 
@@ -1396,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

@@ -42736,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");
@@ -42790,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 {
@@ -42833,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 });
@@ -43119,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 {
@@ -43239,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)
@@ -43247,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({
@@ -44261,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.14",
+  "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.