apple-notes-mcp 1.4.2 → 1.4.4

package/README.md

@@ -712,6 +712,22 @@ If installed from source, use this configuration:
 }
 ```
 
+#### Running from a clone in Claude Code (project-scope `.mcp.json`)
+
+This repo ships a `.mcp.json` at its root so that, when you run `claude` from inside a clone, the server is registered automatically as a **project-scope** server — no manual config needed. After `npm run build`, just launch Claude Code from the repo directory and approve the server when prompted.
+
+The entrypoint is written as:
+
+```json
+"args": ["${CLAUDE_PROJECT_DIR:-.}/build/index.js"]
+```
+
+`CLAUDE_PROJECT_DIR` is the variable Claude Code injects into a project/user-scoped server's environment, and it resolves to the repo root. **You must launch `claude` from inside the repo** for this to work — the bare `.` fallback is only a last resort and is *not* reliable, because it resolves against the launching process's working directory, not the repo.
+
+> **Why not `${CLAUDE_PLUGIN_ROOT}`?** `CLAUDE_PLUGIN_ROOT` is set **only** for marketplace plugin installs, never for a project-scope clone, so it can't drive the clone workflow. Conversely, a plugin install can't use `CLAUDE_PROJECT_DIR` (in a plugin, that points at the *user's* project, not the plugin's own directory). Claude Code does **not** support nested defaults like `${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}`, so a single entrypoint string cannot serve both contexts. The two distribution paths are therefore decoupled: the **plugin** carries its own MCP config in `.claude-plugin/plugin.json` (using `${CLAUDE_PLUGIN_ROOT}`), while the root `.mcp.json` is dedicated to the **clone** workflow (using `${CLAUDE_PROJECT_DIR:-.}`). Because `plugin.json` declares its own `mcpServers`, the plugin does not also auto-load the root `.mcp.json`, so there is no double-registration.
+
+> **Heads-up on scope precedence:** project-scope (`.mcp.json`) outranks user-scope. If you *also* have an `apple-notes` entry registered at user scope (e.g. an absolute path in `~/.claude.json`), the project-scope entry wins and the user-scope one is ignored entirely. Pick one — for local development on this repo, the project-scope `.mcp.json` is the intended source. To pin a specific local build instead, register it at **local** scope (`claude mcp add apple-notes -s local -- node /abs/path/build/index.js`), which outranks project scope.
+
 ---
 
 ## Full Disk Access for Checklist Features
@@ -828,6 +844,12 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 - Use `\\` to represent each literal backslash
 - See "Backslash Escaping" section under Known Limitations
 
+### `apple-notes` server fails to connect when run from a clone
+- Launch `claude` from **inside the repo directory** so `CLAUDE_PROJECT_DIR` resolves to the repo root (the bare `.` fallback is unreliable — it points at the launching process's working directory)
+- Run `npm run build` first — the entrypoint is `${CLAUDE_PROJECT_DIR:-.}/build/index.js`, which won't exist until you build
+- Run `claude mcp list` to check for a conflicting `apple-notes` entry at another scope (project-scope outranks user-scope, but local-scope outranks project-scope)
+- Approve the pending project-scope server when Claude Code prompts you
+
 ---
 
 ## Development

package/build/services/appleNotesManager.js

@@ -97,6 +97,22 @@ export function escapeHtmlForAppleScript(htmlContent) {
     // We do NOT re-encode HTML entities since content is already HTML from Notes.app
     return htmlContent.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
+/**
+ * Escapes a plain (non-HTML) string for safe embedding in an AppleScript string literal.
+ *
+ * Use this for folder names, account names, and other metadata that Apple Notes
+ * stores as plain text — NOT for note body content (use escapeForAppleScript instead).
+ * HTML-encoding ampersands here would produce `folder "R&D"`, which Apple Notes
+ * would fail to match against the real folder named "R&D".
+ *
+ * @param text - Plain string (folder name, account name, etc.)
+ * @returns String safe for AppleScript string embedding
+ */
+export function escapePlainStringForAppleScript(text) {
+    if (!text)
+        return "";
+    return text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
 // =============================================================================
 // Input Validation & Sanitization
 // =============================================================================
@@ -154,7 +170,7 @@ export function sanitizeId(id) {
  */
 function sanitizeAccountName(account) {
     validateLength(account, MAX_ACCOUNT_LENGTH, "Account name");
-    return escapeForAppleScript(account);
+    return escapePlainStringForAppleScript(account);
 }
 /**
  * Counter for generating unique fallback IDs within the same millisecond.
@@ -325,7 +341,7 @@ export function buildFolderReference(folderPath) {
     // Build inside-out: last part is innermost, first part is outermost
     return parts
         .reverse()
-        .map((part) => `folder "${escapeForAppleScript(part)}"`)
+        .map((part) => `folder "${escapePlainStringForAppleScript(part)}"`)
         .join(" of ");
 }
 /**

package/build/services/appleNotesManager.test.js

@@ -242,7 +242,7 @@ describe("buildFolderReference", () => {
     it("handles special characters in folder names", () => {
         const result = buildFolderReference("Food & Drink/🥘 Recipes");
         expect(result).toContain('folder "🥘 Recipes"');
-        expect(result).toContain('folder "Food & Drink"');
+        expect(result).toContain('folder "Food & Drink"');
     });
     it("handles escaped slashes in folder names", () => {
         const result = buildFolderReference("Travel/Spain\\/Portugal 2023");

package/package.json

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