apple-notes-mcp 2.2.0 → 2.4.0

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.2.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",