apple-notes-mcp 1.3.0 → 1.4.0

package/README.md

@@ -77,13 +77,13 @@ On first use, macOS will ask for permission to automate Notes.app. Click "OK" to
 
 | Feature | Description |
 |---------|-------------|
-| **Create Notes** | Create notes with titles, content, and optional organization |
+| **Create Notes** | Create notes with titles, content, and optional folder/account targeting |
 | **Search Notes** | Find notes by title or search within note content |
 | **Read Notes** | Retrieve note content and metadata |
 | **Update Notes** | Modify existing notes (title and/or content) |
 | **Delete Notes** | Remove notes (moves to Recently Deleted) |
-| **Move Notes** | Organize notes into folders |
-| **Folder Management** | Create, list, and delete folders |
+| **Move Notes** | Organize notes into folders (supports nested paths) |
+| **Folder Management** | Create, list, and delete folders with full hierarchical path support |
 | **Multi-Account** | Work with iCloud, Gmail, Exchange, or any configured account |
 | **Batch Operations** | Delete or move multiple notes at once |
 | **Checklist State** | Read checklist done/undone state directly from the Notes database |
@@ -107,10 +107,12 @@ Creates a new note in Apple Notes.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `title` | string | Yes | The title of the note (becomes first line) |
-| `content` | string | Yes | The body content of the note |
+| `title` | string | Yes | The title of the note. Automatically prepended as `<h1>` — do NOT include the title in `content` |
+| `content` | string | Yes | The body content of the note (do not repeat the title here) |
 | `tags` | string[] | No | Tags for organization (stored in metadata) |
-| `format` | string | No | Content format: `"plaintext"` (default) or `"html"`. When `"html"`, content is used as raw HTML for rich formatting |
+| `folder` | string | No | Folder to create the note in. Supports nested paths like `"Work/Clients"`. Defaults to account root |
+| `account` | string | No | Account name (defaults to iCloud) |
+| `format` | string | No | Content format: `"plaintext"` (default) or `"html"`. In both formats, the title is automatically prepended as `<h1>`. In plaintext mode, newlines become `<br>`, tabs become `<br>`, and backslashes are preserved as HTML entities |
 
 **Example:**
 ```json
@@ -121,15 +123,26 @@ Creates a new note in Apple Notes.
 }
 ```
 
+**Example - Create in a specific folder:**
+```json
+{
+  "title": "Client Meeting",
+  "content": "Discussed project timeline",
+  "folder": "Work/Clients"
+}
+```
+
 **Example - HTML formatting:**
 ```json
 {
   "title": "Status Report",
-  "content": "<h1>Status Report</h1><h2>Summary</h2><p>All tasks <b>on track</b>.</p><ul><li>Feature A: complete</li><li>Feature B: in progress</li></ul>",
+  "content": "<h2>Summary</h2><p>All tasks <b>on track</b>.</p><ul><li>Feature A: complete</li><li>Feature B: in progress</li></ul>",
   "format": "html"
 }
 ```
 
+> **Note:** The title is automatically prepended as `<h1>` in both plaintext and HTML formats. Do not include a `<h1>` title tag in the `content` parameter, or the title will appear twice.
+
 **Returns:** Confirmation message with note title and ID. Save the ID for subsequent operations like `update-note`, `delete-note`, etc.
 
 ---
@@ -143,7 +156,7 @@ Searches for notes by title or content.
 | `query` | string | Yes | Text to search for |
 | `searchContent` | boolean | No | If `true`, searches note body; if `false` (default), searches titles only |
 | `account` | string | No | Account to search in (defaults to iCloud) |
-| `folder` | string | No | Limit search to a specific folder |
+| `folder` | string | No | Limit search to a specific folder (supports nested paths like `"Work/Clients"`) |
 | `modifiedSince` | string | No | ISO 8601 date string to filter notes modified on or after this date (e.g., `"2025-01-01"`) |
 | `limit` | number | No | Maximum number of results to return |
 
@@ -293,7 +306,7 @@ Updates an existing note's content and/or title.
 ```json
 {
   "id": "x-coredata://ABC123/ICNote/p456",
-  "newContent": "<h1>Updated Report</h1><p>New findings with <b>bold</b> emphasis.</p><pre><code>console.log('hello');</code></pre>",
+  "newContent": "<p>New findings with <b>bold</b> emphasis.</p><pre><code>console.log('hello');</code></pre>",
   "format": "html"
 }
 ```
@@ -340,7 +353,7 @@ Moves a note to a different folder.
 |-----------|------|----------|-------------|
 | `id` | string | No | Note ID (preferred - more reliable than title) |
 | `title` | string | No | Title of the note to move (use `id` instead when available) |
-| `folder` | string | Yes | Name of the destination folder |
+| `folder` | string | Yes | Destination folder name or nested path (e.g., `"Work/Clients"`) |
 | `account` | string | No | Account containing the note (defaults to iCloud, ignored if `id` is provided) |
 
 **Note:** Either `id` or `title` must be provided. Using `id` is recommended.
@@ -374,7 +387,7 @@ Lists all notes, optionally filtered by folder, date, and limit.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `account` | string | No | Account to list notes from (defaults to iCloud) |
-| `folder` | string | No | Filter to notes in this folder only |
+| `folder` | string | No | Filter to notes in this folder only (supports nested paths like `"Work/Clients"`) |
 | `modifiedSince` | string | No | ISO 8601 date string to filter notes modified on or after this date (e.g., `"2025-01-01"`) |
 | `limit` | number | No | Maximum number of notes to return |
 
@@ -406,7 +419,7 @@ Lists all notes, optionally filtered by folder, date, and limit.
 
 #### `list-folders`
 
-Lists all folders in an account.
+Lists all folders in an account with full hierarchical paths.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -417,7 +430,7 @@ Lists all folders in an account.
 {}
 ```
 
-**Returns:** List of folder names.
+**Returns:** List of folder paths. Nested folders are shown as full paths (e.g., `Work/Clients/Omnia`). Duplicate folder names are disambiguated by their full path. Literal slashes in folder names are escaped as `\/` (e.g., `Spain\/Portugal 2023`).
 
 ---
 
@@ -447,7 +460,7 @@ Deletes a folder.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `name` | string | Yes | Name of the folder to delete |
+| `name` | string | Yes | Name or path of the folder to delete (supports nested paths like `"Work/Old"`) |
 | `account` | string | No | Account containing the folder (defaults to iCloud) |
 
 **Example:**
@@ -499,7 +512,7 @@ Moves multiple notes to a folder.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `ids` | string[] | Yes | Array of note IDs to move |
-| `folder` | string | Yes | Destination folder name |
+| `folder` | string | Yes | Destination folder name or nested path (e.g., `"Work/Clients"`) |
 | `account` | string | No | Account containing the folder |
 
 **Returns:** Summary of successes and failures.
@@ -658,6 +671,14 @@ AI: [calls create-folder with name="Archive"]
 User: "Move my old meeting notes to Archive"
 AI: [calls move-note with title="Old Meeting Notes", folder="Archive"]
     "Moved 'Old Meeting Notes' to 'Archive'"
+
+User: "What folders do I have?"
+AI: [calls list-folders]
+    "You have 5 folders: Work, Work/Clients, Work/Clients/Omnia, Archive, Recipes"
+
+User: "Create a note in Work/Clients about Acme Corp"
+AI: [calls create-note with title="Acme Corp", content="...", folder="Work/Clients"]
+    "Created 'Acme Corp' in Work/Clients"
 ```
 
 ---
@@ -791,7 +812,7 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 ```bash
 npm install      # Install dependencies
 npm run build    # Compile TypeScript
-npm test         # Run test suite (217 tests)
+npm test         # Run test suite (310 tests)
 npm run lint     # Check code style
 npm run format   # Format code
 ```

package/build/index.js

@@ -119,8 +119,13 @@ server.tool("create-note", {
         .default("plaintext")
         .describe("Content format: 'plaintext' (default) or 'html' for rich formatting"),
     tags: z.array(z.string()).optional().describe("Tags for organization"),
-}, withErrorHandling(({ title, content, format = "plaintext", tags = [] }) => {
-    const note = notesManager.createNote(title, content, tags, undefined, undefined, format);
+    folder: z
+        .string()
+        .optional()
+        .describe("Folder to create the note in (supports nested paths like 'Work/Clients')"),
+    account: z.string().optional().describe("Account name (defaults to iCloud)"),
+}, withErrorHandling(({ title, content, format = "plaintext", tags = [], folder, account }) => {
+    const note = notesManager.createNote(title, content, tags, folder, account, format);
     if (!note) {
         return errorResponse(`Failed to create note "${title}". Check that Notes.app is configured and accessible.`);
     }

package/build/services/appleNotesManager.js

@@ -97,6 +97,65 @@ 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, '\\"');
 }
+// =============================================================================
+// Input Validation & Sanitization
+// =============================================================================
+/** Maximum allowed length for note titles */
+const MAX_TITLE_LENGTH = 2000;
+/** Maximum allowed length for note content (5 MB of text) */
+const MAX_CONTENT_LENGTH = 5 * 1024 * 1024;
+/** Maximum allowed length for folder names/paths */
+const MAX_FOLDER_PATH_LENGTH = 1000;
+/** Maximum allowed length for account names */
+const MAX_ACCOUNT_LENGTH = 200;
+/** Maximum nesting depth for folder paths */
+const MAX_FOLDER_DEPTH = 20;
+/**
+ * Validates and constrains string input length.
+ *
+ * @param value - The input string
+ * @param maxLength - Maximum allowed length
+ * @param label - Human-readable label for error messages
+ * @returns The validated string
+ * @throws Error if input exceeds maximum length
+ */
+function validateLength(value, maxLength, label) {
+    if (value.length > maxLength) {
+        throw new Error(`${label} exceeds maximum length of ${maxLength} characters (got ${value.length})`);
+    }
+    return value;
+}
+/**
+ * Sanitizes a CoreData ID for safe embedding in AppleScript.
+ *
+ * CoreData IDs follow the pattern: x-coredata://UUID/ICNote/pNNN
+ * This function validates the format and escapes the value for AppleScript.
+ *
+ * @param id - CoreData URL identifier
+ * @returns Escaped ID safe for AppleScript string embedding
+ * @throws Error if ID format is invalid
+ */
+export function sanitizeId(id) {
+    // CoreData IDs should match: x-coredata://hex-hex-hex-hex-hex/ICEntity/pDigits
+    // or temp-timestamp-counter format from generateFallbackId()
+    const coreDataPattern = /^x-coredata:\/\/[0-9A-Fa-f-]+\/IC[A-Za-z]+\/p\d+$/;
+    const tempIdPattern = /^temp-\d+-\d+$/;
+    if (!coreDataPattern.test(id) && !tempIdPattern.test(id)) {
+        throw new Error(`Invalid note ID format: "${id.substring(0, 80)}". Expected CoreData URL (x-coredata://...) or temp ID.`);
+    }
+    // Even with validation, escape for defense-in-depth
+    return escapeForAppleScript(id);
+}
+/**
+ * Sanitizes an account name for safe embedding in AppleScript.
+ *
+ * @param account - Account name string
+ * @returns Escaped account name safe for AppleScript string embedding
+ */
+function sanitizeAccountName(account) {
+    validateLength(account, MAX_ACCOUNT_LENGTH, "Account name");
+    return escapeForAppleScript(account);
+}
 /**
  * Counter for generating unique fallback IDs within the same millisecond.
  */
@@ -216,6 +275,59 @@ export function parseNotePropertiesOutput(output) {
         passwordProtected,
     };
 }
+/**
+ * Splits a folder path on unescaped `/` separators.
+ *
+ * Folder names may contain literal slashes (e.g., "Spain/Portugal 2023").
+ * In path strings these are escaped as `\/`. This function splits only on
+ * unescaped `/` and restores the literal slashes in each segment.
+ *
+ * @param folderPath - Folder path with `/` as hierarchy separator and `\/` for literal slashes
+ * @returns Array of folder name segments
+ */
+export function splitFolderPath(folderPath) {
+    // Split on `/` that is NOT preceded by `\`
+    // We use a negative lookbehind to avoid splitting on escaped slashes
+    const parts = folderPath.split(/(?<!\\)\//);
+    // Unescape `\/` → `/` in each segment
+    return parts.map((p) => p.replace(/\\\//g, "/")).filter((p) => p.length > 0);
+}
+/**
+ * Escapes literal slashes in a folder name for use in path strings.
+ *
+ * @param name - Raw folder name (may contain `/`)
+ * @returns Folder name with `/` escaped as `\/`
+ */
+function escapeFolderName(name) {
+    return name.replace(/\//g, "\\/");
+}
+/**
+ * Builds an AppleScript folder reference from a path string.
+ *
+ * Converts a folder path like "Work/Clients/Omnia" into the nested
+ * AppleScript syntax: `folder "Omnia" of folder "Clients" of folder "Work"`.
+ *
+ * A simple folder name like "Work" returns `folder "Work"`.
+ * Literal slashes in folder names must be escaped as `\/` (e.g., "Travel/Spain\/Portugal").
+ *
+ * @param folderPath - Folder name or slash-separated path (e.g., "Work/Clients")
+ * @returns AppleScript folder reference string
+ */
+export function buildFolderReference(folderPath) {
+    validateLength(folderPath, MAX_FOLDER_PATH_LENGTH, "Folder path");
+    const parts = splitFolderPath(folderPath);
+    if (parts.length > MAX_FOLDER_DEPTH) {
+        throw new Error(`Folder path exceeds maximum nesting depth of ${MAX_FOLDER_DEPTH} (got ${parts.length})`);
+    }
+    if (parts.length === 0) {
+        throw new Error("Folder path is empty");
+    }
+    // Build inside-out: last part is innermost, first part is outermost
+    return parts
+        .reverse()
+        .map((part) => `folder "${escapeForAppleScript(part)}"`)
+        .join(" of ");
+}
 /**
  * Builds an AppleScript command wrapped in account context.
  *
@@ -235,9 +347,10 @@ export function parseNotePropertiesOutput(output) {
  * @returns Complete AppleScript ready for execution
  */
 function buildAccountScopedScript(scope, command) {
+    const safeAccount = sanitizeAccountName(scope.account);
     return `
     tell application "Notes"
-      tell account "${scope.account}"
+      tell account "${safeAccount}"
         ${command}
       end tell
     end tell
@@ -399,32 +512,43 @@ export class AppleNotesManager {
      * // Create in a different account
      * const gmail = manager.createNote("Draft", "...", [], undefined, "Gmail");
      *
-     * // Create with HTML formatting
-     * const html = manager.createNote("Report", "<h1>Report</h1><p>Details here</p>",
+     * // Create with HTML formatting (no need for <h1> — title is auto-prepended)
+     * const html = manager.createNote("Report", "<p>Details here</p>",
      *   [], undefined, undefined, "html");
      * ```
      */
     createNote(title, content, tags = [], folder, account, format = "plaintext") {
+        validateLength(title, MAX_TITLE_LENGTH, "Note title");
+        validateLength(content, MAX_CONTENT_LENGTH, "Note content");
         const targetAccount = this.resolveAccount(account);
-        // Escape content for AppleScript embedding
-        const safeTitle = escapeForAppleScript(title);
-        const safeContent = format === "html" ? escapeHtmlForAppleScript(content) : escapeForAppleScript(content);
+        // Build body HTML: title as <h1>, content follows.
+        // We set only 'body' (not 'name') to avoid title duplication —
+        // Notes.app auto-uses the first line of body as the note's display title.
+        const htmlTitle = title.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+        const bodyContent = format === "html"
+            ? content
+            : content
+                .replace(/&/g, "&amp;")
+                .replace(/\\/g, "&#92;")
+                .replace(/</g, "&lt;")
+                .replace(/>/g, "&gt;")
+                .replace(/\n/g, "<br>")
+                .replace(/\t/g, "<br>");
+        const safeBody = escapeHtmlForAppleScript(`<h1>${htmlTitle}</h1>${bodyContent}`);
         // Build the AppleScript command
-        // Notes.app uses 'name' for the title and 'body' for content
-        // We capture the ID of the newly created note
         let createCommand;
         if (folder) {
-            // Create note in specific folder
-            const safeFolder = escapeForAppleScript(folder);
+            // Create note in specific folder (supports nested paths like "Work/Clients")
+            const folderRef = buildFolderReference(folder);
             createCommand = `
-        set newNote to make new note at folder "${safeFolder}" with properties {name:"${safeTitle}", body:"${safeContent}"}
+        set newNote to make new note at ${folderRef} with properties {body:"${safeBody}"}
         return id of newNote
       `;
         }
         else {
             // Create note in default location
             createCommand = `
-        set newNote to make new note with properties {name:"${safeTitle}", body:"${safeContent}"}
+        set newNote to make new note with properties {body:"${safeBody}"}
         return id of newNote
       `;
         }
@@ -506,7 +630,7 @@ export class AppleNotesManager {
         }
         const whereClause = whereParts.join(" and ");
         // Build the notes source - either all notes or notes in a specific folder
-        const notesSource = folder ? `notes of folder "${escapeForAppleScript(folder)}"` : "notes";
+        const notesSource = folder ? `notes of ${buildFolderReference(folder)}` : "notes";
         // Build the limit logic for the repeat loop
         // Note: The limit only reduces iteration over already-matched results from the whose clause,
         // not the query itself. It controls output size, not AppleScript query performance.
@@ -613,8 +737,9 @@ export class AppleNotesManager {
      * @returns HTML content of the note, or empty string if not found
      */
     getNoteContentById(id) {
+        const safeId = sanitizeId(id);
         // Note IDs work at the application level, not scoped to account
-        const getCommand = `get body of note id "${id}"`;
+        const getCommand = `get body of note id "${safeId}"`;
         const script = buildAppLevelScript(getCommand);
         const result = executeAppleScript(script);
         if (!result.success) {
@@ -635,9 +760,10 @@ export class AppleNotesManager {
      * @returns Note object with metadata, or null if not found
      */
     getNoteById(id) {
+        const safeId = sanitizeId(id);
         // Note IDs work at the application level, not scoped to account
         const getCommand = `
-      set n to note id "${id}"
+      set n to note id "${safeId}"
       set noteProps to {name of n, id of n, creation date of n, modification date of n, shared of n, password protected of n}
       return noteProps
     `;
@@ -737,7 +863,8 @@ export class AppleNotesManager {
      * @returns true if deletion succeeded, false otherwise
      */
     deleteNoteById(id) {
-        const deleteCommand = `delete note id "${id}"`;
+        const safeId = sanitizeId(id);
+        const deleteCommand = `delete note id "${safeId}"`;
         const script = buildAppLevelScript(deleteCommand);
         const result = executeAppleScript(script);
         if (!result.success) {
@@ -768,6 +895,9 @@ export class AppleNotesManager {
      * @returns true if update succeeded, false otherwise
      */
     updateNote(title, newTitle, newContent, account, format = "plaintext") {
+        if (newTitle)
+            validateLength(newTitle, MAX_TITLE_LENGTH, "Note title");
+        validateLength(newContent, MAX_CONTENT_LENGTH, "Note content");
         const targetAccount = this.resolveAccount(account);
         const safeCurrentTitle = escapeForAppleScript(title);
         let fullBody;
@@ -811,6 +941,9 @@ export class AppleNotesManager {
      * @returns true if update succeeded, false otherwise
      */
     updateNoteById(id, newTitle, newContent, format = "plaintext") {
+        if (newTitle)
+            validateLength(newTitle, MAX_TITLE_LENGTH, "Note title");
+        validateLength(newContent, MAX_CONTENT_LENGTH, "Note content");
         let fullBody;
         if (format === "html") {
             // HTML mode: content is the complete body, escaped only for AppleScript string
@@ -832,7 +965,8 @@ export class AppleNotesManager {
             const safeContent = escapeForAppleScript(newContent);
             fullBody = `<div>${safeEffectiveTitle}</div><div>${safeContent}</div>`;
         }
-        const updateCommand = `set body of note id "${id}" to "${fullBody}"`;
+        const safeId = sanitizeId(id);
+        const updateCommand = `set body of note id "${safeId}" to "${fullBody}"`;
         const script = buildAppLevelScript(updateCommand);
         const result = executeAppleScript(script);
         if (!result.success) {
@@ -855,9 +989,7 @@ export class AppleNotesManager {
         const safeLimit = limit !== undefined && limit > 0 ? Math.floor(limit) : undefined;
         // When date or limit filters are needed, use a repeat loop for fine-grained control
         if (modifiedSince || safeLimit !== undefined) {
-            const baseNotesSource = folder
-                ? `notes of folder "${escapeForAppleScript(folder)}"`
-                : "notes";
+            const baseNotesSource = folder ? `notes of ${buildFolderReference(folder)}` : "notes";
             // Use whose clause for date filtering (locale-safe, no sort order assumption)
             let dateSetup = "";
             let notesSource = baseNotesSource;
@@ -898,8 +1030,7 @@ export class AppleNotesManager {
         // Simple path: no date or limit filters
         let listCommand;
         if (folder) {
-            const safeFolder = escapeForAppleScript(folder);
-            listCommand = `get name of notes of folder "${safeFolder}"`;
+            listCommand = `get name of notes of ${buildFolderReference(folder)}`;
         }
         else {
             listCommand = `get name of notes`;
@@ -931,38 +1062,38 @@ export class AppleNotesManager {
         // Query each account for shared notes
         const accounts = this.listAccounts();
         for (const account of accounts) {
+            // Use delimited output to avoid fragile comma-based parsing.
+            // Format: name|||id|||createdDate|||modifiedDate|||shared|||passwordProtected
             const script = buildAccountScopedScript({ account: account.name }, `
-        set sharedList to {}
+        set resultList to {}
         repeat with n in notes
           if shared of n is true then
-            set noteProps to {name of n, id of n, creation date of n, modification date of n, shared of n, password protected of n}
-            set end of sharedList to noteProps
+            set end of resultList to (name of n) & "|||" & (id of n) & "|||" & (creation date of n as text) & "|||" & (modification date of n as text) & "|||" & (shared of n as text) & "|||" & (password protected of n as text)
           end if
         end repeat
-        return sharedList
+        set AppleScript's text item delimiters to "|||ITEM|||"
+        return resultList as text
         `);
             const result = executeAppleScript(script);
             if (!result.success) {
                 console.error(`Failed to list shared notes for ${account.name}:`, result.error);
                 continue;
             }
-            // Parse the result - format is: {{name, id, date, date, bool, bool}, {...}, ...}
             const output = result.output.trim();
-            if (!output || output === "{}" || output === "{}") {
+            if (!output) {
                 continue;
             }
-            // Extract individual note data using regex
-            const notePattern = /\{([^{}]+)\}/g;
-            let match;
-            while ((match = notePattern.exec(output)) !== null) {
-                const parts = match[1].split(", ");
+            // Parse delimited output: "name|||id|||created|||modified|||shared|||pp|||ITEM|||..."
+            const items = output.split("|||ITEM|||");
+            for (const item of items) {
+                const parts = item.split("|||");
                 if (parts.length >= 6) {
                     const title = parts[0].trim();
                     const id = parts[1].trim();
-                    const createdStr = parts.slice(2, parts.length - 3).join(", ");
-                    const modifiedStr = parts[parts.length - 3];
-                    const shared = parts[parts.length - 2] === "true";
-                    const passwordProtected = parts[parts.length - 1] === "true";
+                    const createdStr = parts[2].trim();
+                    const modifiedStr = parts[3].trim();
+                    const shared = parts[4].trim() === "true";
+                    const passwordProtected = parts[5].trim() === "true";
                     sharedNotes.push({
                         id,
                         title,
@@ -983,26 +1114,74 @@ export class AppleNotesManager {
     // Folder Operations
     // ===========================================================================
     /**
-     * Lists all folders in an account.
+     * Lists all folders in an account with full hierarchical paths.
+     *
+     * Each folder's `name` field contains the full path (e.g., "Work/Clients/Omnia")
+     * so that duplicate folder names (e.g., multiple "Archive" folders) are
+     * distinguishable and can be used directly in other operations.
      *
      * @param account - Account to list folders from (defaults to iCloud)
-     * @returns Array of Folder objects
+     * @returns Array of Folder objects with path-based names
      */
     listFolders(account) {
         const targetAccount = this.resolveAccount(account);
-        // Get folder names (simpler than getting full objects)
-        const listCommand = `get name of folders`;
+        // Get each folder's ID, name, and parent ID in a single AppleScript call.
+        // Each line: "id\tname\tparentId" for subfolders, "id\tname" for top-level.
+        // Using IDs enables correct tree building even with duplicate folder names.
+        const listCommand = `
+      set folderList to ""
+      set allFolders to every folder
+      repeat with f in allFolders
+        set fRef to contents of f
+        set cRef to container of fRef
+        if folderList is not "" then
+          set folderList to folderList & linefeed
+        end if
+        if class of cRef is folder then
+          set folderList to folderList & (id of fRef) & tab & (name of fRef) & tab & (id of cRef)
+        else
+          set folderList to folderList & (id of fRef) & tab & (name of fRef)
+        end if
+      end repeat
+      return folderList
+    `;
         const script = buildAccountScopedScript({ account: targetAccount }, listCommand);
         const result = executeAppleScript(script);
         if (!result.success) {
             console.error("Failed to list folders:", result.error);
             return [];
         }
-        // Convert names to Folder objects
-        const names = parseCommaSeparatedList(result.output);
-        return names.map((name) => ({
-            id: "", // Would require additional query to get
-            name,
+        if (!result.output.trim()) {
+            return [];
+        }
+        // Parse "id\tname[\tparentId]" lines
+        const entries = result.output.split("\n").map((line) => {
+            const parts = line.split("\t");
+            return {
+                id: (parts[0] || "").trim(),
+                name: (parts[1] || "").trim(),
+                parentId: (parts[2] || "").trim(),
+            };
+        });
+        // Build an ID-to-entry map for efficient parent lookups
+        const byId = new Map(entries.map((e) => [e.id, e]));
+        // Build full path by walking up the parent chain using unique IDs
+        // Build full path by walking up the parent chain using unique IDs.
+        // Literal slashes in folder names are escaped as `\/` so they don't
+        // collide with the `/` path separator.
+        const buildPath = (entry) => {
+            const safeName = escapeFolderName(entry.name);
+            if (!entry.parentId)
+                return safeName;
+            const parent = byId.get(entry.parentId);
+            if (parent) {
+                return buildPath(parent) + "/" + safeName;
+            }
+            return safeName;
+        };
+        return entries.map((entry) => ({
+            id: entry.id,
+            name: buildPath(entry),
             account: targetAccount,
         }));
     }
@@ -1042,8 +1221,7 @@ export class AppleNotesManager {
      */
     deleteFolder(name, account) {
         const targetAccount = this.resolveAccount(account);
-        const safeName = escapeForAppleScript(name);
-        const deleteCommand = `delete folder "${safeName}"`;
+        const deleteCommand = `delete ${buildFolderReference(name)}`;
         const script = buildAccountScopedScript({ account: targetAccount }, deleteCommand);
         const result = executeAppleScript(script);
         if (!result.success) {
@@ -1085,9 +1263,9 @@ export class AppleNotesManager {
         }
         // Step 3: Create a copy in the destination folder
         // Content is already HTML from getNoteContent(), so use escapeHtmlForAppleScript()
-        const safeFolder = escapeForAppleScript(destinationFolder);
+        const folderRef = buildFolderReference(destinationFolder);
         const safeContent = escapeHtmlForAppleScript(originalContent);
-        const createCommand = `make new note at folder "${safeFolder}" with properties {body:"${safeContent}"}`;
+        const createCommand = `make new note at ${folderRef} with properties {body:"${safeContent}"}`;
         const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
         const copyResult = executeAppleScript(script);
         if (!copyResult.success) {
@@ -1095,7 +1273,8 @@ export class AppleNotesManager {
             return false;
         }
         // Step 4: Delete the original by ID (not by title, since there are now two notes with the same title)
-        const deleteCommand = `delete note id "${originalNote.id}"`;
+        const safeOrigId = sanitizeId(originalNote.id);
+        const deleteCommand = `delete note id "${safeOrigId}"`;
         const deleteScript = buildAppLevelScript(deleteCommand);
         const deleteResult = executeAppleScript(deleteScript);
         if (!deleteResult.success) {
@@ -1119,6 +1298,7 @@ export class AppleNotesManager {
      */
     moveNoteById(id, destinationFolder, account) {
         const targetAccount = this.resolveAccount(account);
+        const safeId = sanitizeId(id);
         // Step 1: Retrieve the original note's content by ID
         const originalContent = this.getNoteContentById(id);
         if (!originalContent) {
@@ -1127,9 +1307,9 @@ export class AppleNotesManager {
         }
         // Step 2: Create a copy in the destination folder
         // Content is already HTML from getNoteContentById(), so use escapeHtmlForAppleScript()
-        const safeFolder = escapeForAppleScript(destinationFolder);
+        const folderRef = buildFolderReference(destinationFolder);
         const safeContent = escapeHtmlForAppleScript(originalContent);
-        const createCommand = `make new note at folder "${safeFolder}" with properties {body:"${safeContent}"}`;
+        const createCommand = `make new note at ${folderRef} with properties {body:"${safeContent}"}`;
         const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
         const copyResult = executeAppleScript(script);
         if (!copyResult.success) {
@@ -1137,7 +1317,7 @@ export class AppleNotesManager {
             return false;
         }
         // Step 3: Delete the original by ID
-        const deleteCommand = `delete note id "${id}"`;
+        const deleteCommand = `delete note id "${safeId}"`;
         const deleteScript = buildAppLevelScript(deleteCommand);
         const deleteResult = executeAppleScript(deleteScript);
         if (!deleteResult.success) {
@@ -1390,7 +1570,7 @@ export class AppleNotesManager {
      * ```
      */
     listAttachmentsById(id) {
-        const safeId = escapeForAppleScript(id);
+        const safeId = sanitizeId(id);
         const script = `
       tell application "Notes"
         set theNote to note id "${safeId}"

package/build/services/appleNotesManager.test.js

@@ -11,7 +11,7 @@
  * - Script generation is verified by checking for expected AppleScript patterns
  */
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { AppleNotesManager, escapeForAppleScript, escapeHtmlForAppleScript, buildAppleScriptDateVar, parseAppleScriptDate, } from "./appleNotesManager.js";
+import { AppleNotesManager, escapeForAppleScript, escapeHtmlForAppleScript, buildAppleScriptDateVar, buildFolderReference, splitFolderPath, parseAppleScriptDate, sanitizeId, } from "./appleNotesManager.js";
 // Mock the AppleScript execution module
 // This prevents actual osascript calls during testing
 vi.mock("@/utils/applescript.js", () => ({
@@ -210,6 +210,46 @@ describe("parseAppleScriptDate", () => {
     });
 });
 // =============================================================================
+// buildFolderReference Tests
+// =============================================================================
+describe("splitFolderPath", () => {
+    it("splits simple path on /", () => {
+        expect(splitFolderPath("Work/Clients")).toEqual(["Work", "Clients"]);
+    });
+    it("returns single segment for a name without /", () => {
+        expect(splitFolderPath("Work")).toEqual(["Work"]);
+    });
+    it("preserves escaped slashes in folder names", () => {
+        expect(splitFolderPath("Travel/Spain\\/Portugal 2023")).toEqual([
+            "Travel",
+            "Spain/Portugal 2023",
+        ]);
+    });
+    it("handles multiple escaped slashes", () => {
+        expect(splitFolderPath("A\\/B/C\\/D")).toEqual(["A/B", "C/D"]);
+    });
+});
+describe("buildFolderReference", () => {
+    it("returns simple folder reference for a single name", () => {
+        expect(buildFolderReference("Work")).toBe('folder "Work"');
+    });
+    it("returns nested folder reference for a path", () => {
+        expect(buildFolderReference("Work/Clients")).toBe('folder "Clients" of folder "Work"');
+    });
+    it("handles deeply nested paths", () => {
+        expect(buildFolderReference("Work/Clients/Omnia")).toBe('folder "Omnia" of folder "Clients" of folder "Work"');
+    });
+    it("handles special characters in folder names", () => {
+        const result = buildFolderReference("Food & Drink/🥘 Recipes");
+        expect(result).toContain('folder "🥘 Recipes"');
+        expect(result).toContain('folder "Food & Drink"');
+    });
+    it("handles escaped slashes in folder names", () => {
+        const result = buildFolderReference("Travel/Spain\\/Portugal 2023");
+        expect(result).toBe('folder "Spain/Portugal 2023" of folder "Travel"');
+    });
+});
+// =============================================================================
 // buildAppleScriptDateVar Tests
 // =============================================================================
 describe("buildAppleScriptDateVar", () => {
@@ -333,6 +373,62 @@ describe("AppleNotesManager", () => {
             // Double quotes must be escaped for AppleScript string embedding
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('<div class=\\"test\\">Content</div>'));
         });
+        it("sets title as h1 in body, not as name property", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "note id x-coredata://12345/ICNote/p203",
+            });
+            manager.createNote("My Title", "Body content");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            // Title must appear as h1 in body
+            expect(script).toContain("<h1>My Title</h1>");
+            // name property must NOT be set (causes title duplication in Notes.app)
+            expect(script).not.toContain('name:"My Title"');
+        });
+        it("HTML-encodes special chars in title for h1 tag", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "note id x-coredata://12345/ICNote/p204",
+            });
+            manager.createNote("Q&A: <Hello> World", "Content");
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("<h1>Q&amp;A: &lt;Hello&gt; World</h1>"));
+        });
+        it("HTML-encodes special chars in plaintext content", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "note id x-coredata://12345/ICNote/p205",
+            });
+            manager.createNote("Title", "Price: <10 & >5\nNext line");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain("Price: &lt;10 &amp; &gt;5<br>Next line");
+        });
+        it("prepends h1 title before html content", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "note id x-coredata://12345/ICNote/p206",
+            });
+            manager.createNote("Report", "<h2>Section</h2><div>Details</div>", [], undefined, undefined, "html");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain("<h1>Report</h1><h2>Section</h2><div>Details</div>");
+        });
+        it("encodes backslashes as HTML entities in plaintext content", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "note id x-coredata://12345/ICNote/p207",
+            });
+            manager.createNote("Title", "path\\to\\file");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain("path&#92;to&#92;file");
+        });
+        it("converts tabs to br in plaintext content", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "note id x-coredata://12345/ICNote/p208",
+            });
+            manager.createNote("Title", "col1\tcol2\tcol3");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain("col1<br>col2<br>col3");
+        });
     });
     // ---------------------------------------------------------------------------
     // Note Search
@@ -571,7 +667,7 @@ describe("AppleNotesManager", () => {
                 output: "",
                 error: "Note not found",
             });
-            const result = manager.isNotePasswordProtectedById("x-coredata://invalid");
+            const result = manager.isNotePasswordProtectedById("x-coredata://00000000-0000-0000-0000-000000000000/ICNote/p999");
             expect(result).toBe(false);
         });
     });
@@ -597,7 +693,7 @@ describe("AppleNotesManager", () => {
                 output: "",
                 error: "Can't get note id",
             });
-            const result = manager.getNoteById("x-coredata://invalid");
+            const result = manager.getNoteById("x-coredata://00000000-0000-0000-0000-000000000000/ICNote/p999");
             expect(result).toBeNull();
         });
         it("returns null when response format is unexpected (no commas)", () => {
@@ -779,7 +875,7 @@ describe("AppleNotesManager", () => {
                 output: "",
             });
             const htmlContent = "<h1>My Title</h1><div>A &amp; B</div>";
-            const result = manager.updateNoteById("x-coredata://abc/123", undefined, htmlContent, "html");
+            const result = manager.updateNoteById("x-coredata://ABC00000-0000-0000-0000-000000000001/ICNote/p123", undefined, htmlContent, "html");
             expect(result).toBe(true);
             // HTML mode: content passed directly, no <div> wrapper
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining(`to "${htmlContent}"`));
@@ -792,7 +888,7 @@ describe("AppleNotesManager", () => {
                 output: "",
             });
             const htmlContent = "<h1>Title</h1><div>Body</div>";
-            manager.updateNoteById("x-coredata://abc/456", undefined, htmlContent, "html");
+            manager.updateNoteById("x-coredata://ABC00000-0000-0000-0000-000000000002/ICNote/p456", undefined, htmlContent, "html");
             // In HTML mode, getNoteById should NOT be called (it would trigger
             // an additional executeAppleScript call). Only one call should happen:
             // the update itself.
@@ -896,21 +992,54 @@ describe("AppleNotesManager", () => {
     // Folder Operations
     // ---------------------------------------------------------------------------
     describe("listFolders", () => {
-        it("returns array of Folder objects", () => {
+        it("returns array of Folder objects with paths", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "Notes, Archive, Work",
+                output: "id1\tNotes\nid2\tArchive\nid3\tWork",
             });
             const folders = manager.listFolders();
             expect(folders).toHaveLength(3);
             expect(folders[0].name).toBe("Notes");
             expect(folders[1].name).toBe("Archive");
             expect(folders[2].name).toBe("Work");
+            expect(folders[0].id).toBe("id1");
+        });
+        it("includes parent folder in path", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "id1\tDev\nid2\tAccessibility\tid1\nid3\tWork\nid4\tClients\tid3",
+            });
+            const folders = manager.listFolders();
+            expect(folders).toHaveLength(4);
+            expect(folders[0].name).toBe("Dev");
+            expect(folders[1].name).toBe("Dev/Accessibility");
+            expect(folders[2].name).toBe("Work");
+            expect(folders[3].name).toBe("Work/Clients");
+        });
+        it("disambiguates duplicate folder names using IDs", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "id1\tFinance\nid2\tArchive\tid1\nid3\tTravel\nid4\tTrips\tid3\nid5\tArchive\tid4",
+            });
+            const folders = manager.listFolders();
+            expect(folders).toHaveLength(5);
+            expect(folders[1].name).toBe("Finance/Archive");
+            expect(folders[4].name).toBe("Travel/Trips/Archive");
+        });
+        it("escapes slashes in folder names", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "id1\tTravel\nid2\tSpain/Portugal 2023\tid1",
+            });
+            const folders = manager.listFolders();
+            expect(folders).toHaveLength(2);
+            expect(folders[0].name).toBe("Travel");
+            expect(folders[1].name).toBe("Travel/Spain\\/Portugal 2023");
         });
         it("includes account in Folder objects", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "Notes",
+                output: "id1\tNotes",
             });
             const folders = manager.listFolders("Gmail");
             expect(folders[0].account).toBe("Gmail");
@@ -1133,7 +1262,7 @@ describe("AppleNotesManager", () => {
                 // listAccounts
                 .mockReturnValueOnce({ success: true, output: "iCloud" })
                 // listFolders for iCloud
-                .mockReturnValueOnce({ success: true, output: "Notes, Work" })
+                .mockReturnValueOnce({ success: true, output: "id1\tNotes\nid2\tWork" })
                 // listNotes for Notes folder
                 .mockReturnValueOnce({ success: true, output: "Note 1, Note 2, Note 3" })
                 // listNotes for Work folder
@@ -1151,7 +1280,7 @@ describe("AppleNotesManager", () => {
         it("returns zero counts when no notes exist", () => {
             mockExecuteAppleScript
                 .mockReturnValueOnce({ success: true, output: "iCloud" })
-                .mockReturnValueOnce({ success: true, output: "Notes" })
+                .mockReturnValueOnce({ success: true, output: "id1\tNotes" })
                 .mockReturnValueOnce({ success: true, output: "" })
                 .mockReturnValueOnce({ success: true, output: "" });
             const stats = manager.getNotesStats();
@@ -1165,11 +1294,11 @@ describe("AppleNotesManager", () => {
                 // listAccounts
                 .mockReturnValueOnce({ success: true, output: "iCloud, Gmail" })
                 // listFolders for iCloud
-                .mockReturnValueOnce({ success: true, output: "Notes" })
+                .mockReturnValueOnce({ success: true, output: "id1\tNotes" })
                 // listNotes for iCloud/Notes
                 .mockReturnValueOnce({ success: true, output: "Note 1" })
                 // listFolders for Gmail
-                .mockReturnValueOnce({ success: true, output: "Notes" })
+                .mockReturnValueOnce({ success: true, output: "id2\tNotes" })
                 // listNotes for Gmail/Notes
                 .mockReturnValueOnce({ success: true, output: "Email Note" })
                 // getRecentlyModifiedCounts
@@ -1274,10 +1403,19 @@ describe("AppleNotesManager", () => {
                 .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 2", false) })
                 // Second note: deleteNoteById
                 .mockReturnValueOnce({ success: true, output: "" });
-            const results = manager.batchDeleteNotes(["id1", "id2"]);
+            const results = manager.batchDeleteNotes([
+                "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
+                "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+            ]);
             expect(results).toHaveLength(2);
-            expect(results[0]).toEqual({ id: "id1", success: true });
-            expect(results[1]).toEqual({ id: "id2", success: true });
+            expect(results[0]).toEqual({
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
+                success: true,
+            });
+            expect(results[1]).toEqual({
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+                success: true,
+            });
         });
         it("returns error for non-existent note", () => {
             mockExecuteAppleScript.mockReturnValueOnce({
@@ -1285,9 +1423,11 @@ describe("AppleNotesManager", () => {
                 output: "",
                 error: "Not found",
             });
-            const results = manager.batchDeleteNotes(["nonexistent"]);
+            const results = manager.batchDeleteNotes([
+                "x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404",
+            ]);
             expect(results[0]).toEqual({
-                id: "nonexistent",
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404",
                 success: false,
                 error: "Note not found",
             });
@@ -1298,9 +1438,11 @@ describe("AppleNotesManager", () => {
                 .mockReturnValueOnce({ success: true, output: noteByIdOutput("Locked Note", true) })
                 // getNoteById for password check (returns true for passwordProtected)
                 .mockReturnValueOnce({ success: true, output: noteByIdOutput("Locked Note", true) });
-            const results = manager.batchDeleteNotes(["id1"]);
+            const results = manager.batchDeleteNotes([
+                "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
+            ]);
             expect(results[0]).toEqual({
-                id: "id1",
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
                 success: false,
                 error: "Note is password-protected",
             });
@@ -1313,9 +1455,19 @@ describe("AppleNotesManager", () => {
                 .mockReturnValueOnce({ success: true, output: "" })
                 // Second note: not found
                 .mockReturnValueOnce({ success: false, output: "", error: "Not found" });
-            const results = manager.batchDeleteNotes(["id1", "id2"]);
-            expect(results[0]).toEqual({ id: "id1", success: true });
-            expect(results[1]).toEqual({ id: "id2", success: false, error: "Note not found" });
+            const results = manager.batchDeleteNotes([
+                "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
+                "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+            ]);
+            expect(results[0]).toEqual({
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
+                success: true,
+            });
+            expect(results[1]).toEqual({
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+                success: false,
+                error: "Note not found",
+            });
         });
     });
     describe("batchMoveNotes", () => {
@@ -1344,10 +1496,19 @@ describe("AppleNotesManager", () => {
                 .mockReturnValueOnce({ success: true, output: "" })
                 // Second note: deleteNoteById (original)
                 .mockReturnValueOnce({ success: true, output: "" });
-            const results = manager.batchMoveNotes(["id1", "id2"], "Archive");
+            const results = manager.batchMoveNotes([
+                "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
+                "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+            ], "Archive");
             expect(results).toHaveLength(2);
-            expect(results[0]).toEqual({ id: "id1", success: true });
-            expect(results[1]).toEqual({ id: "id2", success: true });
+            expect(results[0]).toEqual({
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
+                success: true,
+            });
+            expect(results[1]).toEqual({
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+                success: true,
+            });
         });
         it("returns error for non-existent note", () => {
             // getNoteById fails for existence check
@@ -1356,9 +1517,9 @@ describe("AppleNotesManager", () => {
                 output: "",
                 error: "Not found",
             });
-            const results = manager.batchMoveNotes(["nonexistent"], "Archive");
+            const results = manager.batchMoveNotes(["x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404"], "Archive");
             expect(results[0]).toEqual({
-                id: "nonexistent",
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404",
                 success: false,
                 error: "Note not found",
             });
@@ -1369,9 +1530,9 @@ describe("AppleNotesManager", () => {
                 .mockReturnValueOnce({ success: true, output: noteByIdOutput("Locked Note", true) })
                 // getNoteById for password check (returns true for passwordProtected)
                 .mockReturnValueOnce({ success: true, output: noteByIdOutput("Locked Note", true) });
-            const results = manager.batchMoveNotes(["id1"], "Archive");
+            const results = manager.batchMoveNotes(["x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1"], "Archive");
             expect(results[0]).toEqual({
-                id: "id1",
+                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
                 success: false,
                 error: "Note is password-protected",
             });
@@ -1388,7 +1549,7 @@ describe("AppleNotesManager", () => {
                 // listAccounts
                 .mockReturnValueOnce({ success: true, output: "iCloud" })
                 // listFolders for iCloud
-                .mockReturnValueOnce({ success: true, output: "Notes" })
+                .mockReturnValueOnce({ success: true, output: "id1\tNotes" })
                 // listNotes for Notes folder
                 .mockReturnValueOnce({ success: true, output: "Test Note" })
                 // getNoteDetails
@@ -1413,7 +1574,7 @@ describe("AppleNotesManager", () => {
                 // listAccounts
                 .mockReturnValueOnce({ success: true, output: "iCloud" })
                 // listFolders for iCloud
-                .mockReturnValueOnce({ success: true, output: "Notes" })
+                .mockReturnValueOnce({ success: true, output: "id1\tNotes" })
                 // listNotes for Notes folder
                 .mockReturnValueOnce({ success: true, output: "Locked Note" })
                 // getNoteDetails (passwordProtected = true)
@@ -1429,7 +1590,7 @@ describe("AppleNotesManager", () => {
                 // listAccounts
                 .mockReturnValueOnce({ success: true, output: "iCloud" })
                 // listFolders for iCloud
-                .mockReturnValueOnce({ success: true, output: "Notes" })
+                .mockReturnValueOnce({ success: true, output: "id1\tNotes" })
                 // listNotes returns empty
                 .mockReturnValueOnce({ success: true, output: "" });
             const result = manager.exportNotesAsJson();
@@ -1486,7 +1647,7 @@ describe("AppleNotesManager", () => {
                 output: "",
                 error: "Note not found",
             });
-            const markdown = manager.getNoteMarkdownById("x-coredata://invalid");
+            const markdown = manager.getNoteMarkdownById("x-coredata://00000000-0000-0000-0000-000000000000/ICNote/p999");
             expect(markdown).toBe("");
         });
         it("enriches markdown with checklist state when available", () => {
@@ -1523,4 +1684,103 @@ describe("AppleNotesManager", () => {
             expect(markdown).not.toContain("[ ]");
         });
     });
+    // ===========================================================================
+    // Security Tests
+    // ===========================================================================
+    describe("sanitizeId", () => {
+        it("accepts valid CoreData IDs", () => {
+            const id = "x-coredata://12345ABC-DEF0-1234-5678-9ABCDEF01234/ICNote/p100";
+            expect(sanitizeId(id)).toBe(id);
+        });
+        it("accepts temp IDs from generateFallbackId", () => {
+            expect(sanitizeId("temp-1704067200000-0")).toBe("temp-1704067200000-0");
+            expect(sanitizeId("temp-1704067200000-42")).toBe("temp-1704067200000-42");
+        });
+        it("rejects IDs with AppleScript injection", () => {
+            expect(() => sanitizeId('x-coredata://test" & do shell script "rm -rf ~" & "')).toThrow("Invalid note ID format");
+        });
+        it("rejects IDs with double-quote breakout", () => {
+            expect(() => sanitizeId('x-coredata://test"; delete note id "dummy" & "')).toThrow("Invalid note ID format");
+        });
+        it("rejects arbitrary strings", () => {
+            expect(() => sanitizeId("not-a-valid-id")).toThrow("Invalid note ID format");
+        });
+        it("rejects empty string", () => {
+            expect(() => sanitizeId("")).toThrow("Invalid note ID format");
+        });
+        it("accepts various ICEntity types", () => {
+            expect(sanitizeId("x-coredata://ABC123/ICFolder/p50")).toBe("x-coredata://ABC123/ICFolder/p50");
+            expect(sanitizeId("x-coredata://ABC123/ICAttachment/p1")).toBe("x-coredata://ABC123/ICAttachment/p1");
+        });
+    });
+    describe("escapeForAppleScript - injection prevention", () => {
+        it("escapes double quotes to prevent AppleScript string breakout", () => {
+            const malicious = 'Hello "World" end tell';
+            const escaped = escapeForAppleScript(malicious);
+            expect(escaped).toContain('\\"');
+            expect(escaped).not.toContain('"World"');
+        });
+        it("escapes backslashes to prevent escape sequence injection", () => {
+            const malicious = "path\\to\\file";
+            const escaped = escapeForAppleScript(malicious);
+            // Backslashes should be encoded as HTML entities (&#92;)
+            expect(escaped).toContain("&#92;");
+        });
+        it("handles combined injection payload", () => {
+            const payload = '" & do shell script "echo pwned" & "';
+            const escaped = escapeForAppleScript(payload);
+            // All double quotes must be escaped with backslash
+            // Count unescaped double quotes — there should be none
+            const unescapedQuotes = escaped.replace(/\\"/g, "").match(/"/g);
+            expect(unescapedQuotes).toBeNull();
+        });
+    });
+    describe("buildFolderReference - input validation", () => {
+        it("rejects empty folder paths", () => {
+            expect(() => buildFolderReference("")).toThrow("Folder path is empty");
+        });
+        it("rejects paths that are only slashes", () => {
+            expect(() => buildFolderReference("///")).toThrow("Folder path is empty");
+        });
+        it("rejects excessively deep folder nesting", () => {
+            const deepPath = Array(25).fill("folder").join("/");
+            expect(() => buildFolderReference(deepPath)).toThrow("maximum nesting depth");
+        });
+        it("rejects excessively long folder paths", () => {
+            const longPath = "a".repeat(1001);
+            expect(() => buildFolderReference(longPath)).toThrow("maximum length");
+        });
+        it("escapes folder names with double quotes", () => {
+            const result = buildFolderReference('My "Special" Folder');
+            expect(result).toContain('\\"');
+            expect(result).not.toContain('"Special"');
+        });
+        it("handles folder names with emoji", () => {
+            const result = buildFolderReference("Food & Drink/\uD83C\uDF72 Recipes");
+            expect(result).toContain("folder");
+            expect(result).toContain("of");
+        });
+    });
+    describe("ID-based operations sanitize input", () => {
+        it("getNoteById rejects malformed IDs", () => {
+            expect(() => {
+                manager.getNoteById('malicious" & do shell script "echo pwned');
+            }).toThrow("Invalid note ID format");
+        });
+        it("deleteNoteById rejects malformed IDs", () => {
+            expect(() => {
+                manager.deleteNoteById('x-coredata://test"; delete note 1 & "');
+            }).toThrow("Invalid note ID format");
+        });
+        it("getNoteContentById rejects malformed IDs", () => {
+            expect(() => {
+                manager.getNoteContentById("arbitrary string");
+            }).toThrow("Invalid note ID format");
+        });
+        it("updateNoteById rejects malformed IDs", () => {
+            expect(() => {
+                manager.updateNoteById("not-valid", undefined, "content");
+            }).toThrow("Invalid note ID format");
+        });
+    });
 });

package/package.json

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