apple-notes-mcp 1.1.1 → 1.1.2

package/README.md

@@ -30,6 +30,17 @@ Install the apple-notes-mcp MCP server so you can help me manage my Apple Notes
 
 Claude will handle the installation and configuration automatically.
 
+### Using the Plugin Marketplace
+
+Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:
+
+```bash
+/plugin marketplace add sweetrb/apple-notes-mcp
+/plugin install apple-notes
+```
+
+This method also installs a **skill** that teaches Claude when and how to use Apple Notes effectively.
+
 ### Manual Installation
 
 **1. Install the server:**
@@ -471,6 +482,29 @@ If installed from source, use this configuration:
 | No rich formatting | Content is HTML; complex formatting may not render |
 | Title matching | Most operations require exact title matches |
 
+### Backslash Escaping (Important for AI Agents)
+
+When sending content containing backslashes (`\`) to this MCP server, **you must escape them as `\\`** in the JSON parameters.
+
+**Why:** The MCP protocol uses JSON for parameter passing. In JSON, a single backslash is an escape character. To include a literal backslash in content, it must be escaped as `\\`.
+
+**Example - Shell command with escaped path:**
+```json
+{
+  "title": "Install Script",
+  "content": "cp ~/Library/Mobile\\\\ Documents/file.txt ~/.config/"
+}
+```
+
+The `\\\\` in JSON becomes `\\` in the actual string, which represents a single `\` in the note.
+
+**Common patterns requiring escaping:**
+- Shell escaped spaces: `Mobile\ Documents` → `Mobile\\\\ Documents` in JSON
+- Windows paths: `C:\Users\` → `C:\\\\Users\\\\` in JSON
+- Regex patterns: `\d+` → `\\\\d+` in JSON
+
+**If you see errors** when creating/updating notes with backslashes, double-check that backslashes are properly escaped in the JSON payload.
+
 ---
 
 ## Troubleshooting
@@ -490,6 +524,11 @@ If installed from source, use this configuration:
 - Check if the note is in a different account
 - Use `list-notes` to see available notes
 
+### Note creation/update fails silently with backslashes
+- Content containing `\` characters requires JSON escaping
+- Use `\\` to represent each literal backslash
+- See "Backslash Escaping" section under Known Limitations
+
 ---
 
 ## Development

package/build/services/appleNotesManager.js

@@ -46,16 +46,23 @@ export function escapeForAppleScript(text) {
     if (!text) {
         return "";
     }
-    // Step 1: Escape single quotes for shell embedding
-    // When we run: osascript -e 'tell app...'
-    // Any single quotes in the script need special handling
-    // Pattern: ' becomes '\'' (end quote, escaped quote, begin quote)
-    let escaped = text.replace(/'/g, "'\\''");
-    // Step 2: Escape double quotes for AppleScript strings
-    // AppleScript uses: "hello \"quoted\" world"
+    // Content goes inside AppleScript double-quoted strings: body:"content here"
+    // Within double-quoted AppleScript strings, we need to escape:
+    // 1. Backslashes (\ → \\) - AppleScript escape character
+    // 2. Double quotes (" → \") - String delimiter
+    // Single quotes do NOT need escaping in double-quoted AppleScript strings.
+    // Step 1: Encode HTML ampersands FIRST (before adding any HTML entities)
+    let escaped = text.replace(/&/g, "&");
+    // Step 2: Encode backslashes as HTML entities
+    // This avoids AppleScript escaping issues since Notes stores HTML
+    // Must happen AFTER ampersand encoding (so \ doesn't become \)
+    // and BEFORE double-quote escaping (so \" doesn't become \")
+    escaped = escaped.replace(/\\/g, "\");
+    // Step 3: Escape double quotes for AppleScript strings
+    // The backslash in \" is for AppleScript, not content, so it's added AFTER
+    // backslash encoding to avoid being HTML-encoded
     escaped = escaped.replace(/"/g, '\\"');
-    // Step 3: Convert control characters to HTML for Notes.app
-    // Apple Notes stores content as HTML, so we convert:
+    // Step 4: Convert control characters to HTML for Notes.app
     // - Newlines (\n) to <br> tags
     // - Tabs (\t) to <br> tags (better than &nbsp; for readability)
     escaped = escaped.replace(/\n/g, "<br>");
@@ -316,13 +323,21 @@ export class AppleNotesManager {
             : `name contains "${safeQuery}"`;
         // Get names and folder for each matching note
         // We use a repeat loop to get both properties, separated by a delimiter
+        // Note: Some notes may have inaccessible containers, so we wrap in try/on error
         const searchCommand = `
       set matchingNotes to notes where ${whereClause}
       set resultList to {}
       repeat with n in matchingNotes
-        set noteName to name of n
-        set noteFolder to name of container of n
-        set end of resultList to noteName & "|||" & noteFolder
+        try
+          set noteName to name of n
+          set noteFolder to name of container of n
+          set end of resultList to noteName & "|||" & noteFolder
+        on error
+          try
+            set noteName to name of n
+            set end of resultList to noteName & "|||" & "Notes"
+          end try
+        end try
       end repeat
       set AppleScript's text item delimiters to "|||ITEM|||"
       return resultList as text

package/build/services/appleNotesManager.test.js

@@ -32,16 +32,15 @@ describe("escapeForAppleScript", () => {
             expect(escapeForAppleScript(undefined)).toBe("");
         });
     });
-    describe("single quote escaping (shell safety)", () => {
-        it("escapes single quotes for shell embedding", () => {
-            // Single quotes in: osascript -e 'tell app...'
-            // Need to become: '\'' (end quote, escaped quote, start quote)
+    describe("single quote handling", () => {
+        it("preserves single quotes (no escaping needed in AppleScript double-quoted strings)", () => {
+            // Single quotes don't need escaping inside AppleScript double-quoted strings
             const result = escapeForAppleScript("it's working");
-            expect(result).toBe("it'\\''s working");
+            expect(result).toBe("it's working");
         });
         it("handles multiple single quotes", () => {
             const result = escapeForAppleScript("Rob's mom's note");
-            expect(result).toBe("Rob'\\''s mom'\\''s note");
+            expect(result).toBe("Rob's mom's note");
         });
     });
     describe("double quote escaping (AppleScript strings)", () => {
@@ -52,7 +51,7 @@ describe("escapeForAppleScript", () => {
         });
         it("handles mixed quotes", () => {
             const result = escapeForAppleScript('He said "it\'s fine"');
-            expect(result).toBe("He said \\\"it'\\''s fine\\\"");
+            expect(result).toBe('He said \\"it\'s fine\\"');
         });
     });
     describe("control character conversion (HTML for Notes.app)", () => {
@@ -73,7 +72,7 @@ describe("escapeForAppleScript", () => {
         it("handles real-world note content", () => {
             const content = 'John\'s "Meeting Notes"\n- Item 1\n- Item 2';
             const result = escapeForAppleScript(content);
-            expect(result).toBe("John'\\''s \\\"Meeting Notes\\\"<br>- Item 1<br>- Item 2");
+            expect(result).toBe('John\'s \\"Meeting Notes\\"<br>- Item 1<br>- Item 2');
         });
     });
     describe("unicode and special characters", () => {
@@ -90,29 +89,34 @@ describe("escapeForAppleScript", () => {
             expect(result).toBe("Café résumé naïve");
         });
         it("handles backslashes", () => {
+            // Backslashes are HTML-encoded to avoid AppleScript escaping issues
             const result = escapeForAppleScript("path\\to\\file");
-            expect(result).toBe("path\\to\\file");
+            expect(result).toBe("path&#92;to&#92;file");
+        });
+        it("handles ampersands", () => {
+            // Ampersands are HTML-encoded for Notes.app (& becomes &amp;)
+            const result = escapeForAppleScript("A && B & C");
+            expect(result).toBe("A &amp;&amp; B &amp; C");
         });
         it("handles angle brackets (HTML-like content)", () => {
-            // Single quotes become '\'' (shell escape pattern)
+            // Single quotes pass through unchanged
             const result = escapeForAppleScript("<script>alert('xss')</script>");
-            expect(result).toBe("<script>alert('\\''xss'\\'')</script>");
+            expect(result).toBe("<script>alert('xss')</script>");
         });
     });
     describe("boundary conditions", () => {
         it("handles very short strings", () => {
             expect(escapeForAppleScript("a")).toBe("a");
-            expect(escapeForAppleScript("'")).toBe("'\\''");
+            expect(escapeForAppleScript("'")).toBe("'");
             expect(escapeForAppleScript('"')).toBe('\\"');
         });
         it("handles string with only whitespace", () => {
             expect(escapeForAppleScript("   ")).toBe("   ");
         });
         it("handles multiple consecutive special characters", () => {
-            // Three single quotes become three '\'' sequences
-            // Three double quotes become three \" sequences
+            // Single quotes pass through, double quotes are escaped
             const result = escapeForAppleScript("'''\"\"\"");
-            expect(result).toBe("'\\'''\\'''\\''\\\"\\\"\\\"");
+            expect(result).toBe("'''\\\"\\\"\\\"");
         });
     });
 });

package/package.json

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