apple-notes-mcp 2.3.0 → 2.4.0

package/README.md

@@ -267,6 +267,22 @@ see [docs/APPLESCRIPT-LIMITATIONS.md](../docs/APPLESCRIPT-LIMITATIONS.md#tags--h
 
 ---
 
+#### `get-note-plaintext`
+
+Retrieves a note's body as plain text, with no HTML markup.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | No | Note ID (preferred - more reliable than title) |
+| `title` | string | No | Note title (use `id` instead when available) |
+| `account` | string | No | Account containing the note (defaults to iCloud, ignored if `id` is provided) |
+
+**Note:** Either `id` or `title` must be provided. This reads the note's native `plaintext` property, so it skips the HTML-to-text conversion that `get-note-content` plus a Markdown pass would do. Use `get-note-content` when you need the HTML, or `get-note-markdown` when you want Markdown with checklist state.
+
+**Returns:** The plain-text content of the note in `structuredContent.plaintext`, or error if not found.
+
+---
+
 #### `get-note-details`
 
 Retrieves metadata about a note (without full content).
@@ -376,6 +392,8 @@ Updates an existing note's content and/or title.
 
 **Note:** `newContent` **replaces the entire note body** — it is not appended. To preserve existing content, read it first (e.g. with `get-note-content`) and include it in `newContent`.
 
+**Attachments:** A full-body replace can drop embedded files, images, scans, PDFs, or audio. When a note may hold attachments, run [`list-attachments`](#list-attachments) first, and either save them with `save-attachment` or build a new note rather than overwriting. See the skill's [Attachment-Safe Updates](skills/apple-notes/SKILL.md#attachment-safe-updates) guidance.
+
 ---
 
 #### `delete-note`
@@ -551,6 +569,19 @@ Deletes a folder.
 
 ---
 
+#### `show-folder`
+
+Reveals a folder in Notes.app using its unique CoreData identifier.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | The folder's CoreData identifier (from `list-folders`) |
+| `separately` | boolean | No | Open in a separate window when supported by Notes.app |
+
+**Returns:** Confirmation that Notes.app accepted the show command.
+
+---
+
 ### Account Operations
 
 #### `list-accounts`
@@ -578,6 +609,19 @@ Returns the default account and folder Notes.app uses for newly created notes.
 
 ---
 
+#### `show-account`
+
+Reveals an account in Notes.app using its unique CoreData identifier.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | The account's CoreData identifier (from `list-accounts`) |
+| `separately` | boolean | No | Open in a separate window when supported by Notes.app |
+
+**Returns:** Confirmation that Notes.app accepted the show command.
+
+---
+
 ### Batch Operations
 
 #### `batch-delete-notes`
@@ -703,6 +747,20 @@ Returns a note attachment's bytes as base64, without writing to disk (the read c
 
 ---
 
+#### `show-attachment`
+
+Reveals one note attachment in Notes.app. Attachments are elements of a note, so this takes both the note id and the attachment id (the same pair used by `save-attachment` / `fetch-attachment`).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `noteId` | string | Yes | CoreData note ID (from `search-notes`/`list-notes`) |
+| `attachmentId` | string | Yes | Attachment ID (from `list-attachments`) |
+| `separately` | boolean | No | Open in a separate window when supported by Notes.app |
+
+**Returns:** Confirmation that Notes.app revealed the attachment.
+
+---
+
 ### Diagnostics
 
 #### `health-check`

package/build/index.js

@@ -254,6 +254,54 @@ server.registerTool("get-note-content", {
     const hashtags = parseHashtags(content);
     return successResponse(content, { title, content, hashtags });
 }, "Error retrieving note content"));
+// --- get-note-plaintext ---
+server.registerTool("get-note-plaintext", {
+    description: "Use when: reading one note's body as plain text with no HTML, by id (preferred) or title.\nReturns: the note's plaintext exactly as Notes exposes it.\nDo not use when: you need the HTML body (get-note-content) or Markdown with checklist state (get-note-markdown).\nNote: this reads the note's native plaintext property, so it skips the HTML-to-text conversion; password-protected notes must be unlocked in Notes.app first.",
+    inputSchema: {
+        id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
+        title: z.string().optional().describe("Note title (use id instead when available)"),
+        account: z
+            .string()
+            .optional()
+            .describe("Account name (defaults to iCloud, ignored if id is provided)"),
+    },
+    outputSchema: {
+        title: z.string().optional(),
+        plaintext: z.string().optional(),
+    },
+}, withErrorHandling(({ id, title, account }) => {
+    // Prefer ID-based lookup if provided
+    if (id) {
+        const note = notesManager.getNoteById(id);
+        if (!note) {
+            return errorResponse(`Note with ID "${id}" not found`);
+        }
+        if (note.passwordProtected) {
+            return errorResponse(`Note "${note.title}" is password-protected and cannot be read. Unlock it in Notes.app first.`);
+        }
+        const plaintext = notesManager.getNotePlaintextById(id);
+        if (!plaintext) {
+            return errorResponse(`Failed to read plaintext of note "${note.title}"`);
+        }
+        return successResponse(plaintext, { title: note.title, plaintext });
+    }
+    // Fall back to title-based lookup
+    if (!title) {
+        return errorResponse("Either 'id' or 'title' is required");
+    }
+    const note = notesManager.getNoteDetails(title, account);
+    if (!note) {
+        return errorResponse(`Note "${title}" not found`);
+    }
+    if (note.passwordProtected) {
+        return errorResponse(`Note "${title}" is password-protected and cannot be read. Unlock it in Notes.app first.`);
+    }
+    const plaintext = notesManager.getNotePlaintext(title, account);
+    if (!plaintext) {
+        return errorResponse(`Failed to read plaintext of note "${title}"`);
+    }
+    return successResponse(plaintext, { title, plaintext });
+}, "Error retrieving note plaintext"));
 // --- get-note-by-id ---
 server.registerTool("get-note-by-id", {
     description: "Use when: you have a note id and need its metadata only.\nReturns: id, title, created, modified, shared, passwordProtected.\nDo not use when: you need the body text (get-note-content) or only have a title (get-note-details).",
@@ -335,9 +383,51 @@ server.registerTool("show-note", {
     }
     return successResponse(`Shown note with ID "${id}" in Notes.app`, { id, separately });
 }, "Error showing note"));
+// --- show-folder ---
+server.registerTool("show-folder", {
+    description: "Use when: the user wants to reveal a known folder in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need the folder list (list-folders).\nNote: this opens or focuses the Notes UI. Get the id from list-folders.",
+    inputSchema: {
+        id: z.string().min(1, "Folder ID is required"),
+        separately: z
+            .boolean()
+            .optional()
+            .describe("Open in a separate window when supported by Notes.app"),
+    },
+    outputSchema: {
+        id: z.string().optional(),
+        separately: z.boolean().optional(),
+    },
+}, withErrorHandling(({ id, separately = false }) => {
+    const success = notesManager.showFolderById(id, separately);
+    if (!success) {
+        return errorResponse(`Failed to show folder with ID "${id}"`);
+    }
+    return successResponse(`Shown folder with ID "${id}" in Notes.app`, { id, separately });
+}, "Error showing folder"));
+// --- show-account ---
+server.registerTool("show-account", {
+    description: "Use when: the user wants to reveal a known account in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need the account list (list-accounts).\nNote: this opens or focuses the Notes UI. Get the id from list-accounts.",
+    inputSchema: {
+        id: z.string().min(1, "Account ID is required"),
+        separately: z
+            .boolean()
+            .optional()
+            .describe("Open in a separate window when supported by Notes.app"),
+    },
+    outputSchema: {
+        id: z.string().optional(),
+        separately: z.boolean().optional(),
+    },
+}, withErrorHandling(({ id, separately = false }) => {
+    const success = notesManager.showAccountById(id, separately);
+    if (!success) {
+        return errorResponse(`Failed to show account with ID "${id}"`);
+    }
+    return successResponse(`Shown account with ID "${id}" in Notes.app`, { id, separately });
+}, "Error showing account"));
 // --- update-note ---
 server.registerTool("update-note", {
-    description: "Use when: changing the title and/or replacing the body of an existing note, by id (preferred) or title.\nReturns: confirmation; warns when the note is shared.\nDo not use when: creating a new note (create-note).\nSafety: newContent REPLACES the entire body — it does not append. Read the note first if you need to preserve existing text. Edits to shared notes are immediately visible to all collaborators.",
+    description: "Use when: changing the title and/or replacing the body of an existing note, by id (preferred) or title.\nReturns: confirmation; warns when the note is shared.\nDo not use when: creating a new note (create-note).\nSafety: newContent REPLACES the entire body — it does not append. Read the note first if you need to preserve existing text, and run list-attachments first when the note may hold files, images, scans, PDFs, or audio, since a full-body replace can drop embedded attachments. Edits to shared notes are immediately visible to all collaborators.",
     inputSchema: {
         id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
         title: z.string().optional().describe("Current note title (use id instead when available)"),
@@ -1048,6 +1138,39 @@ server.registerTool("fetch-attachment", {
     }
     return successResponse(`Fetched "${r.name ?? "attachment"}" (${r.contentType ?? "unknown type"}, ${r.bytes ?? 0} bytes) as base64.`, { name: r.name, contentType: r.contentType, bytes: r.bytes, base64: r.base64 });
 }, "Error fetching attachment"));
+// --- show-attachment ---
+server.registerTool("show-attachment", {
+    description: "Use when: the user wants to reveal one note attachment in Notes.app.\nReturns: confirmation that Notes.app revealed the attachment.\nDo not use when: you want the bytes (fetch-attachment) or a file on disk (save-attachment).\nNote: this opens or focuses the Notes UI. Get the ids from list-attachments first.",
+    inputSchema: {
+        noteId: z
+            .string()
+            .min(1, "noteId is required")
+            .describe("CoreData note id (from search/list)"),
+        attachmentId: z
+            .string()
+            .min(1, "attachmentId is required")
+            .describe("Attachment id (from list-attachments)"),
+        separately: z
+            .boolean()
+            .optional()
+            .describe("Open in a separate window when supported by Notes.app"),
+    },
+    outputSchema: {
+        noteId: z.string().optional(),
+        attachmentId: z.string().optional(),
+        separately: z.boolean().optional(),
+    },
+}, withErrorHandling(({ noteId, attachmentId, separately = false }) => {
+    const success = notesManager.showAttachmentById(noteId, attachmentId, separately);
+    if (!success) {
+        return errorResponse(`Failed to show attachment "${attachmentId}" on note "${noteId}"`);
+    }
+    return successResponse(`Shown attachment "${attachmentId}" in Notes.app`, {
+        noteId,
+        attachmentId,
+        separately,
+    });
+}, "Error showing attachment"));
 // --- export-notes-json ---
 server.registerTool("export-notes-json", {
     description: "Use when: exporting the entire notes library as structured JSON for backup or bulk processing.\nReturns: a summary plus the full JSON of all notes, folders, and accounts.\nDo not use when: you need a single note (get-note-content) — this reads everything and can be large.\nRead-only.",

package/build/services/__fixtures__/notesNormalizedHtml.js

@@ -0,0 +1,32 @@
+export const NOTES_NORMALIZED_HTML_FIXTURES = [
+    {
+        name: "headingAndParagraphs",
+        description: "An <h1> title and two <div> paragraphs separated by a spacer row",
+        html: "<div><h1>Meeting Notes</h1></div><div>First line.</div><div><br></div><div>Second line.</div>",
+        expectedMarkdown: "# Meeting Notes\n\nFirst line.\n  \n\nSecond line.",
+    },
+    {
+        name: "bulletList",
+        description: "An <h2> section heading followed by a native <ul> bullet list",
+        html: "<div><h2>Tasks</h2></div><ul><li>Buy milk</li><li>Walk dog</li></ul>",
+        expectedMarkdown: "## Tasks\n\n-   Buy milk\n-   Walk dog",
+    },
+    {
+        name: "inlineEmphasis",
+        description: "Inline <b> and <i> emphasis inside a paragraph div",
+        html: "<div>This is <b>bold</b> and <i>italic</i> text.</div>",
+        expectedMarkdown: "This is **bold** and _italic_ text.",
+    },
+    {
+        name: "codeSpan",
+        description: "A <tt> code span — the tag is dropped, only its text survives",
+        html: "<div>Run <tt>npm install</tt> first.</div>",
+        expectedMarkdown: "Run npm install first.",
+    },
+    {
+        name: "spacerRuns",
+        description: "Consecutive <div><br></div> spacer rows between two paragraphs",
+        html: "<div>A</div><div><br></div><div><br></div><div>B</div>",
+        expectedMarkdown: "A\n  \n\n  \n\nB",
+    },
+];

package/build/services/appleNotesManager.js

@@ -781,6 +781,53 @@ export class AppleNotesManager {
         }
         return result.output;
     }
+    /**
+     * Retrieves the plain-text content of a note by its exact title.
+     *
+     * Reads the note's `plaintext` property, which Notes derives from the body
+     * with all HTML markup removed. This is the text Notes itself exposes, so it
+     * is more faithful than converting the HTML body and skips the markup
+     * round-trip entirely.
+     *
+     * @param title - Exact title of the note
+     * @param account - Account to search in (defaults to iCloud)
+     * @returns Plain-text content of the note, or empty string if not found
+     */
+    getNotePlaintext(title, account) {
+        const targetAccount = this.resolveAccount(account);
+        const safeTitle = escapePlainStringForAppleScript(title);
+        const getCommand = `get plaintext of note "${safeTitle}"`;
+        const script = buildAccountScopedScript({ account: targetAccount }, getCommand);
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Failed to get plaintext of note "${title}":`, result.error);
+            return "";
+        }
+        return result.output;
+    }
+    /**
+     * Retrieves the plain-text content of a note by its CoreData ID.
+     *
+     * Reads the read-only `plaintext` property (the body with HTML removed). More
+     * reliable than getNotePlaintext() because IDs are unique across accounts.
+     *
+     * Note: Password-protected notes will fail with an AppleScript error. Callers
+     * should check for password protection beforehand using getNoteById().
+     *
+     * @param id - CoreData URL identifier for the note
+     * @returns Plain-text content of the note, or empty string if not found
+     */
+    getNotePlaintextById(id) {
+        const safeId = sanitizeId(id);
+        const getCommand = `get plaintext of note id "${safeId}"`;
+        const script = buildAppLevelScript(getCommand);
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Failed to get plaintext of note with ID "${id}":`, result.error);
+            return "";
+        }
+        return result.output;
+    }
     /**
      * Retrieves a note by its unique CoreData ID.
      *
@@ -1604,6 +1651,91 @@ export class AppleNotesManager {
         }
         return true;
     }
+    /**
+     * Reveals a folder in the Notes.app UI by its id.
+     *
+     * Wraps the Notes `show` command, which the scripting dictionary exposes for
+     * folders as well as notes. This opens or focuses the Notes UI on the folder.
+     *
+     * @param id - CoreData identifier for the folder (from list-folders)
+     * @param separately - Open in a separate window when supported by Notes.app
+     * @returns true if Notes.app accepted the show command, false otherwise
+     */
+    showFolderById(id, separately = false) {
+        const safeId = sanitizeId(id);
+        const separatelyClause = separately ? " separately true" : "";
+        const result = executeAppleScript(buildAppLevelScript(`show folder id "${safeId}"${separatelyClause}`));
+        if (!result.success) {
+            console.error(`Failed to show folder with ID "${id}":`, result.error);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Reveals an account in the Notes.app UI by its id.
+     *
+     * Wraps the Notes `show` command, which the scripting dictionary exposes for
+     * accounts as well as notes. This opens or focuses the Notes UI on the account.
+     *
+     * @param id - CoreData identifier for the account (from list-accounts)
+     * @param separately - Open in a separate window when supported by Notes.app
+     * @returns true if Notes.app accepted the show command, false otherwise
+     */
+    showAccountById(id, separately = false) {
+        const safeId = sanitizeId(id);
+        const separatelyClause = separately ? " separately true" : "";
+        const result = executeAppleScript(buildAppLevelScript(`show account id "${safeId}"${separatelyClause}`));
+        if (!result.success) {
+            console.error(`Failed to show account with ID "${id}":`, result.error);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Reveals an attachment in the Notes.app UI.
+     *
+     * Attachments are elements of a note, so they cannot be referenced at the
+     * application level by id alone. This resolves the attachment within its note
+     * (the same lookup used by save-attachment) and then runs the Notes `show`
+     * command on it, opening or focusing the Notes UI on the attachment.
+     *
+     * @param noteId - CoreData identifier for the note containing the attachment
+     * @param attachmentId - id of the attachment (from list-attachments)
+     * @param separately - Open in a separate window when supported by Notes.app
+     * @returns true if Notes.app revealed the attachment, false otherwise
+     */
+    showAttachmentById(noteId, attachmentId, separately = false) {
+        const safeNoteId = sanitizeId(noteId);
+        const safeAttId = escapePlainStringForAppleScript(attachmentId);
+        const separatelyClause = separately ? " separately true" : "";
+        const script = `
+      tell application "Notes"
+        set theNote to note id "${safeNoteId}"
+        set theAttachment to missing value
+        repeat with a in attachments of theNote
+          if (id of a as text) is "${safeAttId}" then
+            set theAttachment to a
+            exit repeat
+          end if
+        end repeat
+        if theAttachment is missing value then
+          return "ERR${AS_FIELD_SEP}attachment not found"
+        end if
+        show theAttachment${separatelyClause}
+        return "OK"
+      end tell
+    `;
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Failed to show attachment "${attachmentId}" on note "${noteId}":`, result.error);
+            return false;
+        }
+        if ((result.output ?? "").trim().startsWith("ERR")) {
+            console.error(`Attachment "${attachmentId}" not found on note "${noteId}"`);
+            return false;
+        }
+        return true;
+    }
     // ===========================================================================
     // Health Check
     // ===========================================================================

package/build/services/appleNotesManager.test.js

@@ -664,6 +664,45 @@ describe("AppleNotesManager", () => {
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('tell account "Gmail"'));
         });
     });
+    describe("getNotePlaintext", () => {
+        it("reads the note's plaintext property by title", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Shopping List\n- Eggs\n- Milk",
+            });
+            const text = manager.getNotePlaintext("Shopping List");
+            expect(text).toBe("Shopping List\n- Eggs\n- Milk");
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('get plaintext of note "Shopping List"'));
+        });
+        it("returns empty string when the note is not found", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: false,
+                output: "",
+                error: 'Can\'t get note "Missing"',
+            });
+            expect(manager.getNotePlaintext("Missing Note")).toBe("");
+        });
+        it("uses the specified account", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "Content" });
+            manager.getNotePlaintext("My Note", "Gmail");
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('tell account "Gmail"'));
+        });
+    });
+    describe("getNotePlaintextById", () => {
+        it("reads the note's plaintext property by id at the application level", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "Just the text" });
+            const text = manager.getNotePlaintextById("x-coredata://ABC/ICNote/p1");
+            expect(text).toBe("Just the text");
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('get plaintext of note id "x-coredata://ABC/ICNote/p1"'));
+        });
+        it("returns empty string when Notes.app rejects the read", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: false, output: "", error: "no such note" });
+            expect(manager.getNotePlaintextById("x-coredata://ABC/ICNote/p1")).toBe("");
+        });
+        it("rejects malformed IDs", () => {
+            expect(() => manager.getNotePlaintextById("arbitrary string")).toThrow();
+        });
+    });
     // ---------------------------------------------------------------------------
     // Password Protection Helpers
     // ---------------------------------------------------------------------------
@@ -1615,6 +1654,76 @@ describe("AppleNotesManager", () => {
             expect(manager.showNoteById("x-coredata://ABC/ICNote/p1")).toBe(false);
         });
     });
+    describe("showFolderById", () => {
+        it("shows a folder by id", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "" });
+            expect(manager.showFolderById("x-coredata://ABC/ICFolder/p1")).toBe(true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('show folder id "x-coredata://ABC/ICFolder/p1"'));
+        });
+        it("can request a separate window", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "" });
+            manager.showFolderById("x-coredata://ABC/ICFolder/p1", true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("separately true"));
+        });
+        it("returns false when Notes.app rejects the show command", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: false,
+                output: "",
+                error: "no such folder",
+            });
+            expect(manager.showFolderById("x-coredata://ABC/ICFolder/p1")).toBe(false);
+        });
+    });
+    describe("showAccountById", () => {
+        it("shows an account by id", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "" });
+            expect(manager.showAccountById("x-coredata://ABC/ICAccount/p1")).toBe(true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('show account id "x-coredata://ABC/ICAccount/p1"'));
+        });
+        it("can request a separate window", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "" });
+            manager.showAccountById("x-coredata://ABC/ICAccount/p1", true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("separately true"));
+        });
+        it("returns false when Notes.app rejects the show command", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: false,
+                output: "",
+                error: "no such account",
+            });
+            expect(manager.showAccountById("x-coredata://ABC/ICAccount/p1")).toBe(false);
+        });
+    });
+    describe("showAttachmentById", () => {
+        it("resolves the attachment within its note and shows it", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "OK" });
+            expect(manager.showAttachmentById("x-coredata://ABC/ICNote/p1", "att-123")).toBe(true);
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain('set theNote to note id "x-coredata://ABC/ICNote/p1"');
+            expect(script).toContain('is "att-123"');
+            expect(script).toContain("show theAttachment");
+        });
+        it("can request a separate window", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "OK" });
+            manager.showAttachmentById("x-coredata://ABC/ICNote/p1", "att-123", true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("separately true"));
+        });
+        it("returns false when the attachment is not found on the note", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: `ERR${F}attachment not found`,
+            });
+            expect(manager.showAttachmentById("x-coredata://ABC/ICNote/p1", "missing")).toBe(false);
+        });
+        it("returns false when Notes.app rejects the show command", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: false,
+                output: "",
+                error: "no such note",
+            });
+            expect(manager.showAttachmentById("x-coredata://ABC/ICNote/p1", "att-123")).toBe(false);
+        });
+    });
     // ---------------------------------------------------------------------------
     // Health Check
     // ---------------------------------------------------------------------------

package/build/services/notesHtmlMarkdown.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { NOTES_NORMALIZED_HTML_FIXTURES } from "../services/__fixtures__/notesNormalizedHtml.js";
+// Mock the same seams the main manager test does: AppleScript execution and the
+// SQLite-backed checklist reader (no Full Disk Access in unit tests).
+vi.mock("@/utils/applescript.js", () => ({
+    executeAppleScript: vi.fn(),
+}));
+vi.mock("@/utils/checklistParser.js", () => ({
+    getChecklistItems: vi.fn().mockReturnValue({ items: null }),
+}));
+import { executeAppleScript } from "../utils/applescript.js";
+import { AppleNotesManager } from "../services/appleNotesManager.js";
+const mockExecuteAppleScript = vi.mocked(executeAppleScript);
+const NOTE_ID = "x-coredata://ABC/ICNote/p1";
+/**
+ * Regression coverage for Notes-normalized HTML -> Markdown conversion.
+ *
+ * The fixtures encode the HTML shape Apple Notes returns and the Markdown the
+ * server currently emits. Routing through getNoteMarkdownById exercises the real
+ * Turndown pipeline (including the notesDivs rule) with AppleScript mocked to
+ * return the fixture body.
+ */
+describe("Notes-normalized HTML to Markdown", () => {
+    let manager;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        manager = new AppleNotesManager();
+    });
+    for (const fixture of NOTES_NORMALIZED_HTML_FIXTURES) {
+        it(`converts ${fixture.name} (${fixture.description})`, () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: fixture.html });
+            const markdown = manager.getNoteMarkdownById(NOTE_ID);
+            expect(markdown).toBe(fixture.expectedMarkdown);
+        });
+    }
+    it("documents that a <div><br></div> spacer leaves a two-space line", () => {
+        mockExecuteAppleScript.mockReturnValue({
+            success: true,
+            output: "<div>A</div><div><br></div><div>B</div>",
+        });
+        const markdown = manager.getNoteMarkdownById(NOTE_ID);
+        // The spacer survives as a stray "  " line — the Markdown-side fingerprint of
+        // the whitespace-accumulation behavior CLAUDE.md warns about.
+        expect(markdown).toBe("A\n  \n\nB");
+    });
+    it("documents that <tt> is dropped, keeping only its text", () => {
+        mockExecuteAppleScript.mockReturnValue({
+            success: true,
+            output: "<div>Run <tt>npm install</tt> first.</div>",
+        });
+        const markdown = manager.getNoteMarkdownById(NOTE_ID);
+        expect(markdown).toBe("Run npm install first.");
+        expect(markdown).not.toContain("`");
+    });
+});

package/package.json

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