apple-notes-mcp 2.15.6 → 2.15.8

package/README.md

@@ -153,6 +153,30 @@ In the IDE, open **MCP Servers → Manage MCP Servers → View raw config**. Mer
 
 The repository's `.antigravity-plugin/mcp_config.json` supplies an unpinned stdio server entry; the JSON above pins the audited release. Use `command` and `args`; this package does not provide a remote `serverUrl`.
 
+#### Gemini Spark (macOS Local MCP)
+
+In Gemini macOS builds that offer **Local MCP**, open **Connected Apps**, click **+ Custom**, and select **Local MCP** in "Set up a custom connected app". Fill in the form with:
+
+| Field | Value |
+|-------|-------|
+| Server Name | Apple Notes |
+| Description | Read, search, create, edit, organize, and export Apple Notes on this Mac. |
+| Command | `npx -y apple-notes-mcp@2.15.1` |
+
+You can print these instructions from the installed server:
+
+```bash
+npx -y apple-notes-mcp setup --gemini-spark
+```
+
+The command only prints the guide. It exits before loading server configuration, checking Notes, or running the other setup commands, and it doesn't register the app or change permissions. Exit 0 means the guide was printed, not that Gemini connected. Run it by itself; combining it with other setup options exits 2.
+
+Keep **Sandbox settings** at **Default** initially, then click **Next** and review the discovered tools and permission requests before connecting. If Gemini can't launch the server, inspect **Show Logs** and check whether `npx` is available to the app. For a stable local installation, `npm install -g apple-notes-mcp` provides the `apple-notes-mcp` command; you can also use absolute paths to your Node executable and the installed `build/index.js` if the app can't find them. Keep that installation available, and update the command if you move it or replace Node.
+
+Gemini's sandbox and macOS permissions are separate. Review any additional filesystem access the launcher needs; **Full Access** isn't a required setup step. Automation of Notes.app enables the AppleScript tools, while database tools need the runtime's [Full Disk Access](#full-disk-access). Shortcut operations need the packaged bridge setup above. After connecting, ask Gemini to run `get-capabilities` for tool availability, then `doctor` for Notes access diagnostics before attempting a write. A successful terminal check doesn't verify the permissions of Gemini's process.
+
+This integration uses the Mac app's Local MCP command interface and the server's existing stdio transport. Availability depends on your Gemini build. Google's [custom apps documentation](https://support.google.com/gemini/answer/17209137) currently describes URL-based setup in the web app; it doesn't document this local form. **Cloud MCP**, Gemini web/mobile, and a hosted HTTP endpoint aren't supported by this server. These instructions apply to Gemini Spark, separately from Gemini CLI and Antigravity.
+
 #### Other MCP clients and remote execution
 
 A local MCP client can use the command `npx` with arguments `-y` and `apple-notes-mcp@2.15.1`. Follow that client's stdio configuration format: JSON `mcpServers`, TOML, and YAML are not interchangeable.
@@ -1376,21 +1400,28 @@ actual destination folder ID matches the requested folder.
 
 #### Folder scope guards
 
-`update-note`, `append-to-note`, `delete-note`, and `move-note` accept three
-optional folder preconditions. Use exact folder ids from `list-folders`.
+`update-note`, `append-to-note`, `delete-note`, `move-note`, and
+`batch-move-notes` accept three optional folder preconditions. Use exact
+folder ids from `list-folders`.
 
 - `ifFolderId`: the note must currently be in exactly this folder.
 - `ifAncestorFolderId`: the note must be inside this folder or any of its
   subfolders.
 - `forbiddenAncestorFolderIds` (up to 50): the note must not be inside any of
-  these folders or their subfolders. For `move-note`, the destination must not
-  be either.
+  these folders or their subfolders. For `move-note` and `batch-move-notes`,
+  the destination must not be either.
 
 The checks read Notes.app's live folders inside the same AppleScript as the
-write, immediately before it, so a note moved after you reviewed it is left
-alone and the call fails with `Scope guard failed: …`. The one exception is a
-native append to a protected note (it runs through Shortcuts): there the check
-is a separate read just before the append, so it is not atomic.
+write, immediately before it. If the folder observed by the check fails a
+precondition, the write is refused with `Scope guard failed: …`. The check and
+write are separate Notes operations; another actor can move the note between
+them. A native append to a protected note runs through Shortcuts, so its
+precheck runs in a separate AppleScript before the append.
+
+For `batch-move-notes`, the same preconditions apply to every supplied note ID.
+Each note is checked independently immediately before its move. A scope mismatch
+leaves that note unchanged and appears in its failure result; the remaining
+items continue. A batch can therefore move some notes and refuse others.
 
 **Example - retire a note only while it is still in the inbox:**
 ```json
@@ -1915,9 +1946,35 @@ Moves multiple notes to a folder.
 | `ids` | string[] | Yes | Array of note IDs to move (max 500 per request) |
 | `folder` | string | Yes | Destination folder name or nested path (e.g., `"Work/Clients"`). Must already exist — create it with [`create-folder`](#create-folder). A smart folder is refused for the whole call before any note moves |
 | `account` | string | No | Account containing the folder |
+| `ifFolderId`, `ifAncestorFolderId`, `forbiddenAncestorFolderIds` | string, string, string[] | No | Shared folder preconditions applied independently to each note; see [Folder scope guards](#folder-scope-guards). Forbidden folders also apply to the destination |
 
 **Returns:** Summary of successes and failures. Each success is reported only
 after the note's actual container folder ID matches the destination folder ID.
+If every note fails, the call returns its existing error response; the exact
+note IDs and reasons remain in the failure text.
+
+Failure rows carry `committed: false, indeterminate: false` only when that
+item was refused before its move. Move/readback failures and an unknown
+whole-script outcome carry `indeterminate: true`, with `committed` omitted.
+If every item fails, the batch reports `committed: false` only when every row
+is a proven pre-move refusal. Otherwise its error result is indeterminate;
+read each exact note ID before retrying, even if another row has a scope refusal.
+
+**Example - move only notes that are still in the reviewed inbox:**
+```json
+{
+  "ids": ["x-coredata://ABC123/ICNote/p456", "x-coredata://ABC123/ICNote/p457"],
+  "folder": "Archive",
+  "ifFolderId": "x-coredata://ABC123/ICFolder/p12"
+}
+```
+
+The source-folder check runs immediately before each move in the same
+AppleScript. If the check finds that a note is no longer in that inbox, its
+result reports `Scope guard failed: …` while a note still there can move.
+The check does not lock the note against another actor moving it before the
+move. The batch is not a transaction, and successful moves are not rolled
+back after a refusal.
 
 ---
 

package/build/index.js

@@ -24535,8 +24535,9 @@ Targets (choose at most one; default: packaged Shortcuts):
   --permissions-window Build and install the optional permission checklist window
   --permissions         Check permissions; does not grant them
   --broker              Build and install the opt-in permission broker
+  --gemini-spark        Print the macOS Local MCP guide; no setup effects
 
-Options for every target:
+Options for installation and permission targets:
   --check               Inspect only; do not install or import anything
   --help, -h            Show this help without performing any checks
 
@@ -24547,6 +24548,9 @@ Options only with --permissions:
   --window              Show the checklist in the installed optional window
   --probe-automation    Send a read-only Apple event (may show a consent prompt)
 
+Options only with --gemini-spark:
+  --help, -h            Print the guide without connecting a client
+
 Options only with --broker:
   --uninstall           Remove the installed broker and LaunchAgent
   --sign-identity <id>   Select an existing signing identity
@@ -24560,7 +24564,8 @@ var SETUP_TARGETS = /* @__PURE__ */ new Map([
   ["--native-helper", "native-helper"],
   ["--permissions-window", "permissions-window"],
   ["--permissions", "permissions"],
-  ["--broker", "broker"]
+  ["--broker", "broker"],
+  ["--gemini-spark", "gemini-spark"]
 ]);
 var PERMISSION_OPTIONS = /* @__PURE__ */ new Set([
   "--once",
@@ -24590,6 +24595,13 @@ function parseSetupArgs(args) {
       throw new Error(`Unknown setup option "${arg}".`);
     }
   }
+  if (target === "gemini-spark") {
+    if (args.filter((arg) => arg === "--gemini-spark").length !== 1 || args.some((arg) => !["--gemini-spark", "--help", "-h"].includes(arg)) || args.filter((arg) => arg === "--help" || arg === "-h").length > 1)
+      throw new Error(
+        "The Gemini Spark print-only guide cannot be combined with other setup options."
+      );
+    return { kind: "setup", target, args: [...args], checkOnly: false };
+  }
   if (args.some((arg) => arg === "--uninstall" || arg === "--sign-identity") && target !== "broker")
     throw new Error("--uninstall and --sign-identity require setup --broker.");
   for (const arg of args) {
@@ -24611,6 +24623,33 @@ function parseCliArgs(args) {
   throw new Error(`Unknown command or option "${command2}".`);
 }
 
+// src/setupGeminiSpark.ts
+var GEMINI_SPARK_LOCAL_MCP = {
+  serverName: "Apple Notes",
+  description: "Read, search, create, edit, organize, and export Apple Notes on this Mac.",
+  command: "npx -y apple-notes-mcp"
+};
+function formatGeminiSparkSetup() {
+  return [
+    "Gemini Spark on macOS: Local MCP",
+    "Requires a Gemini macOS build with Local MCP in Connected Apps > + Custom.",
+    "Select Local MCP and enter:",
+    "",
+    `Server Name: ${GEMINI_SPARK_LOCAL_MCP.serverName}`,
+    `Description: ${GEMINI_SPARK_LOCAL_MCP.description}`,
+    `Command: ${GEMINI_SPARK_LOCAL_MCP.command}`,
+    "",
+    "Keep Sandbox settings at Default initially. If startup fails, inspect Show Logs",
+    "and review the specific launcher or filesystem access it needs.",
+    "Sandbox access and macOS Automation / Full Disk Access are separate permissions.",
+    "Click Next, review the tools and permissions, and complete the connection yourself.",
+    "Verify tool discovery with get-capabilities in Gemini; use doctor for Notes diagnostics.",
+    "",
+    "This command only prints instructions; a successful exit does not verify a connection.",
+    "Cloud MCP needs a hosted MCP URL. This server provides local stdio only."
+  ].join("\n");
+}
+
 // src/cliEntry.ts
 var parsed;
 try {
@@ -24623,6 +24662,11 @@ ${usage}`);
   process.exit(2);
 }
 var command = parsed;
+if (command.kind === "setup" && command.target === "gemini-spark") {
+  process.stdout.write(`${formatGeminiSparkSetup()}
+`);
+  process.exit(0);
+}
 if (command.kind === "help") {
   process.stdout.write(command.topic === "setup" ? SETUP_USAGE : CLI_USAGE);
   process.exit(0);
@@ -43149,8 +43193,9 @@ function parseScopeFailure(output) {
   const trimmed = output.trim();
   return trimmed.startsWith(`${SCOPE_MARKER}:`) ? trimmed.slice(SCOPE_MARKER.length + 1) : null;
 }
-function scopeConflictMessage(reason) {
-  return `Scope guard failed: ${reason}. Nothing was changed; read the note's current folder and review before retrying.`;
+function scopeConflictMessage(reason, operation) {
+  const refusal = operation === "batch-move" ? "This note's move was refused" : "Nothing was changed";
+  return `Scope guard failed: ${reason}. ${refusal}; read the note's current folder and review before retrying.`;
 }
 
 // src/services/appleNotesManager.ts
@@ -43499,8 +43544,9 @@ function buildAccountScopedScript(scope2, command2) {
     end tell
   `;
 }
-function buildAppLevelScript(command2) {
+function buildAppLevelScript(command2, handlers = "") {
   return `
+    ${handlers}
     tell application "Notes"
       ${command2}
     end tell
@@ -45881,8 +45927,8 @@ var AppleNotesManager = class {
   /**
    * Result of a batch operation on a single item.
    */
-  createBatchResult(id2, success, error2) {
-    return error2 ? { id: id2, success, error: error2 } : { id: id2, success };
+  createBatchResult(id2, success, error2, certainty) {
+    return { ...error2 ? { id: id2, success, error: error2 } : { id: id2, success }, ...certainty };
   }
   /**
    * Maps a per-item status token emitted by a batch AppleScript loop to a
@@ -45890,23 +45936,39 @@ var AppleNotesManager = class {
    * per-note implementation. See {@link batchMoveNotes}.
    */
   mapBatchStatus(id2, status, op) {
+    const beforeMove = op === "move" ? { committed: false, indeterminate: false } : void 0;
+    const uncertainMove = op === "move" ? { indeterminate: true } : void 0;
+    const scopeFailure = parseScopeFailure(status ?? "");
+    if (scopeFailure !== null)
+      return this.createBatchResult(
+        id2,
+        false,
+        scopeConflictMessage(scopeFailure, op === "move" ? "batch-move" : void 0),
+        beforeMove
+      );
     switch (status) {
       case "ok":
         return this.createBatchResult(id2, true);
       case "pw":
-        return this.createBatchResult(id2, false, "Note is password-protected");
+        return this.createBatchResult(id2, false, "Note is password-protected", beforeMove);
       case "missing":
-        return this.createBatchResult(id2, false, "Note not found");
+        return this.createBatchResult(id2, false, "Note not found", beforeMove);
       case "fail":
         return this.createBatchResult(
           id2,
           false,
-          op === "delete" ? "Deletion failed" : "Move failed"
+          op === "delete" ? "Deletion failed" : "Move failed",
+          uncertainMove
         );
       case "wrongfolder":
-        return this.createBatchResult(id2, false, "Destination folder verification failed");
+        return this.createBatchResult(
+          id2,
+          false,
+          "Destination folder verification failed",
+          uncertainMove
+        );
       default:
-        return this.createBatchResult(id2, false, "Unknown error");
+        return this.createBatchResult(id2, false, "Unknown error", uncertainMove);
     }
   }
   /**
@@ -45918,6 +45980,7 @@ var AppleNotesManager = class {
    * @param ids - Array of CoreData URL identifiers for notes to move
    * @param folder - Destination folder name
    * @param account - Account containing the folder (defaults to Notes.app's default account)
+   * @param scope - Shared folder preconditions checked independently before each move
    * @returns Array of results with id, success status, and optional error message
    *
    * @example
@@ -45928,8 +45991,26 @@ var AppleNotesManager = class {
    * );
    * ```
    */
-  batchMoveNotes(ids, folder, account) {
+  batchMoveNotes(ids, folder, account, scope2) {
     if (ids.length === 0) return [];
+    const scopeChecks = buildScopeGuardScript("noteRef", scope2, "destFolder");
+    const moveHandler = `
+      script batchMoveWorker
+        on moveBatchNote(noteRef, destFolder, theId)
+          tell application "Notes"
+            ${scopeChecks}
+            move noteRef to destFolder
+            set movedNoteRef to note id theId
+            set actualFolder to container of movedNoteRef
+            if (id of actualFolder) is (id of destFolder) then
+              return "ok"
+            else
+              return "wrongfolder"
+            end if
+          end tell
+        end moveBatchNote
+      end script
+    `;
     const targetAccount = this.resolveAccount(account);
     const destFolderSetup = buildLiveFolderResolution(folder, "destFolder", {
       excludeFolderIds: this.smartFolderIds()
@@ -45943,13 +46024,15 @@ var AppleNotesManager = class {
         results[i] = this.createBatchResult(
           id2,
           false,
-          e instanceof Error ? e.message : "Invalid note ID"
+          e instanceof Error ? e.message : "Invalid note ID",
+          { committed: false, indeterminate: false }
         );
       }
     });
     if (runnable.length > 0) {
       const idList2 = runnable.map((r) => `"${r.safe}"`).join(", ");
-      const script = buildAppLevelScript(`
+      const script = buildAppLevelScript(
+        `
         ${buildAccountResolution(targetAccount)}
         ${destFolderSetup}
         set out to ""
@@ -45970,14 +46053,8 @@ var AppleNotesManager = class {
               set out to out & "pw" & ${AS_RECORD_SEP}
             else
               try
-                move noteRef to destFolder
-                set movedNoteRef to note id theId
-                set actualFolder to container of movedNoteRef
-                if (id of actualFolder) is (id of destFolder) then
-                  set out to out & "ok" & ${AS_RECORD_SEP}
-                else
-                  set out to out & "wrongfolder" & ${AS_RECORD_SEP}
-                end if
+                set itemStatus to batchMoveWorker's moveBatchNote(noteRef, destFolder, theId)
+                set out to out & itemStatus & ${AS_RECORD_SEP}
               on error
                 set out to out & "fail" & ${AS_RECORD_SEP}
               end try
@@ -45985,7 +46062,9 @@ var AppleNotesManager = class {
           end if
         end repeat
         return out
-      `);
+      `,
+        moveHandler
+      );
       const res = executeMutationAppleScript(script);
       if (!res.success) {
         throwIfAccountResolutionFailed(res.error);
@@ -45994,11 +46073,12 @@ var AppleNotesManager = class {
           results[r.index] = this.createBatchResult(
             ids[r.index],
             false,
-            res.error ?? "Batch move failed"
+            res.error ?? "Batch move failed",
+            { indeterminate: true }
           );
         }
       } else {
-        const statuses = res.output.split(RECORD_SEP).map((s) => s.trim()).filter((s) => s.length > 0);
+        const statuses = res.output.split(RECORD_SEP).map((s) => s.trim());
         runnable.forEach((r, k) => {
           results[r.index] = this.mapBatchStatus(ids[r.index], statuses[k], "move");
         });
@@ -64232,7 +64312,7 @@ var scopeGuardInputs = {
       maxItems: MAX_FORBIDDEN_FOLDERS
     }
   ).optional().describe(
-    "Precondition: the note must not be inside any of these folders or their subfolders (for move-note, neither may the destination). Re-checked immediately before the write."
+    "Precondition: the note must not be inside any of these folders or their subfolders (for move-note and batch-move-notes, neither may the destination). Re-checked immediately before the write."
   )
 };
 function scopeFrom(args) {
@@ -66791,8 +66871,9 @@ registerTool(
 registerTool(
   "batch-move-notes",
   {
-    description: "Use when: moving multiple notes by id into one destination folder.\nReturns: per-id success/failure counts after destination-folder verification.\nDo not use when: moving a single note (move-note).\nSafety: each moved note's actual container ID is compared with the destination folder ID before success is reported. The destination folder must already exist (create-folder); a smart folder is refused for the whole call (code unsupported) before any note moves.",
+    description: "Use when: moving multiple notes by id into one destination folder.\nReturns: per-id success/failure counts after destination-folder verification.\nDo not use when: moving a single note (move-note).\nSafety: optional folder preconditions apply independently to every note, checked live immediately before its move in the same AppleScript; a scope mismatch leaves that note unchanged and other items continue. Each moved note's actual container ID is compared with the destination folder ID before success is reported. The destination folder must already exist (create-folder); a smart folder is refused for the whole call (code unsupported) before any note moves.",
     inputSchema: {
+      ...scopeGuardInputs,
       ids: noteIdArrayInput.describe(
         `Array of note IDs to move (max ${MAX.BATCH_IDS} per request)`
       ),
@@ -66811,11 +66892,12 @@ registerTool(
       results: external_exports.array(external_exports.object({}).passthrough()).optional()
     }
   },
-  withErrorHandling(({ ids, folder, account }) => {
+  withErrorHandling((args) => {
+    const { ids, folder, account } = args;
     if (ids.length === 0) {
       return errorResponse("No note IDs provided");
     }
-    const results = notesManager.batchMoveNotes(ids, folder, account);
+    const results = notesManager.batchMoveNotes(ids, folder, account, scopeFrom(args));
     const succeeded = results.filter((r) => r.success).length;
     const failed = results.filter((r) => !r.success).length;
     const lines = [`Batch move to "${folder}": ${succeeded} succeeded, ${failed} failed`];
@@ -66825,13 +66907,20 @@ registerTool(
         lines.push(`  - ${result.id}: ${result.error}`);
       }
     }
-    return succeeded > 0 ? successResponse(lines.join("\n"), {
-      ok: failed === 0,
-      folder,
-      succeeded,
-      failed,
-      results
-    }) : errorResponse(lines.join("\n"));
+    if (succeeded > 0)
+      return successResponse(lines.join("\n"), {
+        ok: failed === 0,
+        folder,
+        succeeded,
+        failed,
+        results
+      });
+    const allRefusedBeforeMove = results.length === ids.length && results.every((result) => result.committed === false && result.indeterminate === false);
+    if (!allRefusedBeforeMove)
+      lines.push("\nBatch move outcome is uncertain; read each exact note ID before retrying.");
+    const message = lines.join("\n");
+    const envelope = allRefusedBeforeMove ? { ...classifyError(message), committed: false, indeterminate: false } : { code: "verification_failed", indeterminate: true };
+    return errorResponse(message, new CodedError(message, envelope));
   }, "Error performing batch move")
 );
 registerTool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.15.6",
+  "version": "2.15.8",
   "description": "MCP server for Apple Notes - read, search, create, edit, organize, and export notes on macOS via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",