apple-notes-mcp 2.15.7 → 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.

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);

package/package.json

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