apple-notes-mcp 2.0.1 → 2.1.1

package/build/services/appleNotesManager.test.js

@@ -526,6 +526,19 @@ describe("AppleNotesManager", () => {
             expect(results[1].id).toBe("x-coredata://ABC/ICNote/p2");
             expect(results[1].folder).toBe("Notes");
         });
+        it("deduplicates duplicate note IDs returned by Notes.app", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: [
+                    ["Not uploaded", "x-coredata://ABC/ICNote/p1", "Notes"].join(F),
+                    ["Not uploaded", "x-coredata://ABC/ICNote/p1", "Notes"].join(F),
+                ].join(R),
+            });
+            const results = manager.searchNotes("Not uploaded");
+            expect(results).toHaveLength(1);
+            expect(results[0].title).toBe("Not uploaded");
+            expect(results[0].id).toBe("x-coredata://ABC/ICNote/p1");
+        });
         it("scopes search to specified account", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
@@ -1002,7 +1015,11 @@ describe("AppleNotesManager", () => {
         it("returns array of note titles", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Note A", "Note B", "Note C"].join(R),
+                output: [
+                    ["Note A", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Note B", "x-coredata://ABC/ICNote/p2"].join(F),
+                    ["Note C", "x-coredata://ABC/ICNote/p3"].join(F),
+                ].join(R),
             });
             const titles = manager.listNotes();
             expect(titles).toEqual(["Note A", "Note B", "Note C"]);
@@ -1010,11 +1027,29 @@ describe("AppleNotesManager", () => {
         it("filters out empty entries", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Note A", "", "Note B", "", ""].join(R),
+                output: [
+                    ["Note A", "x-coredata://ABC/ICNote/p1"].join(F),
+                    "",
+                    ["Note B", "x-coredata://ABC/ICNote/p2"].join(F),
+                    "",
+                    "",
+                ].join(R),
             });
             const titles = manager.listNotes();
             expect(titles).toEqual(["Note A", "Note B"]);
         });
+        it("deduplicates duplicate note IDs while preserving separate notes with the same title", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: [
+                    ["Same Title", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Same Title", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Same Title", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
+            });
+            const titles = manager.listNotes();
+            expect(titles).toEqual(["Same Title", "Same Title"]);
+        });
         it("throws on failure rather than returning empty (#19)", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: false,
@@ -1026,7 +1061,10 @@ describe("AppleNotesManager", () => {
         it("filters by folder when specified", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Work Note 1", "Work Note 2"].join(R),
+                output: [
+                    ["Work Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Work Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
             });
             manager.listNotes("iCloud", "Work");
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('notes of folder "Work"'));
@@ -1034,7 +1072,10 @@ describe("AppleNotesManager", () => {
         it("uses whose clause when modifiedSince is provided", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Recent Note 1", "Recent Note 2"].join(R),
+                output: [
+                    ["Recent Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Recent Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
             });
             const results = manager.listNotes(undefined, undefined, "2025-06-15T00:00:00");
             const script = mockExecuteAppleScript.mock.calls[0][0];
@@ -1049,7 +1090,11 @@ describe("AppleNotesManager", () => {
         it("uses repeat loop when limit is provided", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Note 1", "Note 2", "Note 3"].join(R),
+                output: [
+                    ["Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                    ["Note 3", "x-coredata://ABC/ICNote/p3"].join(F),
+                ].join(R),
             });
             const results = manager.listNotes(undefined, undefined, undefined, 3);
             const script = mockExecuteAppleScript.mock.calls[0][0];
@@ -1059,7 +1104,10 @@ describe("AppleNotesManager", () => {
         it("combines folder, modifiedSince, and limit", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Work Note", "Another Work Note"].join(R),
+                output: [
+                    ["Work Note", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Another Work Note", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
             });
             manager.listNotes("iCloud", "Work", "2025-01-01", 10);
             const script = mockExecuteAppleScript.mock.calls[0][0];
@@ -1078,7 +1126,10 @@ describe("AppleNotesManager", () => {
         it("ignores invalid modifiedSince date and falls back to limit-only", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Note 1", "Note 2"].join(R),
+                output: [
+                    ["Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
             });
             const results = manager.listNotes(undefined, undefined, "not-a-date", 5);
             const script = mockExecuteAppleScript.mock.calls[0][0];
@@ -1399,7 +1450,13 @@ describe("AppleNotesManager", () => {
                 // Check 3: listAccounts
                 .mockReturnValueOnce({ success: true, output: "iCloud" })
                 // Check 4: listNotes
-                .mockReturnValueOnce({ success: true, output: ["Note 1", "Note 2"].join(R) });
+                .mockReturnValueOnce({
+                success: true,
+                output: [
+                    ["Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
+            });
             const result = manager.healthCheck();
             expect(result.healthy).toBe(true);
             expect(result.checks).toHaveLength(4);
@@ -1498,6 +1555,56 @@ describe("AppleNotesManager", () => {
             expect(stats.accounts[0].name).toBe("iCloud");
             expect(stats.accounts[1].name).toBe("Gmail");
         });
+        it("reports complete coverage when every scope succeeds (#19)", () => {
+            mockExecuteAppleScript
+                .mockReturnValueOnce({ success: true, output: "iCloud" })
+                .mockReturnValueOnce({ success: true, output: ["Notes", "3"].join(F) + R })
+                .mockReturnValueOnce({ success: true, output: ["1", "2", "3"].join(F) });
+            const stats = manager.getNotesStats();
+            expect(stats.coverage.complete).toBe(true);
+            expect(stats.coverage.warnings).toEqual([]);
+            expect(stats.coverage.covered).toBe(stats.coverage.scanned);
+        });
+        it("degrades gracefully when one account fails, with a coverage warning (#19)", () => {
+            mockExecuteAppleScript
+                // listAccounts
+                .mockReturnValueOnce({ success: true, output: ["iCloud", "Gmail"].join(R) })
+                // iCloud folder counts succeed
+                .mockReturnValueOnce({ success: true, output: ["Notes", "4"].join(F) + R })
+                // Gmail folder counts FAIL
+                .mockReturnValueOnce({ success: false, output: "", error: "Gmail account is locked" })
+                // getRecentlyModifiedCounts succeed
+                .mockReturnValueOnce({ success: true, output: ["0", "0", "0"].join(F) });
+            const stats = manager.getNotesStats();
+            // Healthy account's data is preserved, not discarded
+            expect(stats.totalNotes).toBe(4);
+            expect(stats.accounts).toHaveLength(1);
+            expect(stats.accounts[0].name).toBe("iCloud");
+            // Failure surfaced as a coverage warning
+            expect(stats.coverage.complete).toBe(false);
+            expect(stats.coverage.warnings).toHaveLength(1);
+            expect(stats.coverage.warnings[0].scope).toBe("Gmail");
+            expect(stats.coverage.warnings[0].reason).toContain("locked");
+        });
+        it("flags recent-activity failure as a coverage warning, not fake zeros (#19)", () => {
+            mockExecuteAppleScript
+                .mockReturnValueOnce({ success: true, output: "iCloud" })
+                .mockReturnValueOnce({ success: true, output: ["Notes", "5"].join(F) + R })
+                // getRecentlyModifiedCounts FAILS
+                .mockReturnValueOnce({ success: false, output: "", error: "timed out" });
+            const stats = manager.getNotesStats();
+            expect(stats.totalNotes).toBe(5);
+            expect(stats.recentlyModified.last24h).toBe(0);
+            expect(stats.coverage.complete).toBe(false);
+            expect(stats.coverage.warnings.some((w) => w.scope === "recent-activity")).toBe(true);
+        });
+        it("throws when no account can be read at all (#19)", () => {
+            mockExecuteAppleScript
+                .mockReturnValueOnce({ success: true, output: ["iCloud", "Gmail"].join(R) })
+                .mockReturnValueOnce({ success: false, output: "", error: "iCloud unreachable" })
+                .mockReturnValueOnce({ success: false, output: "", error: "Gmail unreachable" });
+            expect(() => manager.getNotesStats()).toThrow(/Failed to read folder stats for any/);
+        });
     });
     // ---------------------------------------------------------------------------
     // Attachment Listing
@@ -1578,50 +1685,23 @@ describe("AppleNotesManager", () => {
     // Batch Operations
     // ---------------------------------------------------------------------------
     describe("batchDeleteNotes", () => {
-        // Helper to create getNoteById mock output (matches AppleScript format)
-        const noteByIdOutput = (title, passwordProtected = false) => [
-            title,
-            "x-coredata://ABC/ICNote/p1",
-            "Sunday, January 1, 2025 at 1:00:00 PM",
-            "Sunday, January 1, 2025 at 1:00:00 PM",
-            "false",
-            String(passwordProtected),
-        ].join(F);
-        it("deletes multiple notes successfully", () => {
-            // For each note: getNoteById (which isNotePasswordProtectedById also calls), deleteNoteById
-            mockExecuteAppleScript
-                // First note: getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                // First note: getNoteById for password check (isNotePasswordProtectedById calls getNoteById)
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                // First note: deleteNoteById
-                .mockReturnValueOnce({ success: true, output: "" })
-                // Second note: getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 2", false) })
-                // Second note: getNoteById for password check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 2", false) })
-                // Second note: deleteNoteById
-                .mockReturnValueOnce({ success: true, output: "" });
-            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: "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",
+        const ID1 = "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1";
+        const ID2 = "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2";
+        it("deletes the whole batch in a single osascript spawn (#26)", () => {
+            // One script handles all ids; per-id status tokens joined by RECORD_SEP.
+            mockExecuteAppleScript.mockReturnValueOnce({
                 success: true,
+                output: ["ok", "ok"].join(R) + R,
             });
+            const results = manager.batchDeleteNotes([ID1, ID2]);
+            // Exactly one spawn for N notes, not 3N.
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1);
+            expect(results).toHaveLength(2);
+            expect(results[0]).toEqual({ id: ID1, success: true });
+            expect(results[1]).toEqual({ id: ID2, success: true });
         });
         it("returns error for non-existent note", () => {
-            mockExecuteAppleScript.mockReturnValueOnce({
-                success: false,
-                output: "",
-                error: "Not found",
-            });
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "missing" + R });
             const results = manager.batchDeleteNotes([
                 "x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404",
             ]);
@@ -1632,97 +1712,58 @@ describe("AppleNotesManager", () => {
             });
         });
         it("returns error for password-protected note", () => {
-            mockExecuteAppleScript
-                // getNoteById for existence check
-                .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([
-                "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-            ]);
-            expect(results[0]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-                success: false,
-                error: "Note is password-protected",
-            });
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "pw" + R });
+            const results = manager.batchDeleteNotes([ID1]);
+            expect(results[0]).toEqual({ id: ID1, success: false, error: "Note is password-protected" });
         });
-        it("handles mixed success and failure", () => {
-            mockExecuteAppleScript
-                // First note: success
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                .mockReturnValueOnce({ success: true, output: "" })
-                // Second note: not found
-                .mockReturnValueOnce({ success: false, output: "", error: "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",
+        it("handles mixed success and failure, preserving order", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
                 success: true,
+                output: ["ok", "missing"].join(R) + R,
             });
-            expect(results[1]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+            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" });
+        });
+        it("fails an invalid id without spawning, isolating it from valid ids", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "ok" + R });
+            const results = manager.batchDeleteNotes(["not-a-valid-id", ID1]);
+            expect(results[0].success).toBe(false);
+            expect(results[0].error).toMatch(/Invalid note ID/);
+            expect(results[1]).toEqual({ id: ID1, success: true });
+        });
+        it("fails the whole batch when the single script errors", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
                 success: false,
-                error: "Note not found",
+                output: "",
+                error: "Notes.app not responding",
             });
+            const results = manager.batchDeleteNotes([ID1, ID2]);
+            expect(results.every((r) => r.success === false)).toBe(true);
+            expect(results[0].error).toContain("Notes.app not responding");
+        });
+        it("returns [] for an empty batch without spawning", () => {
+            const results = manager.batchDeleteNotes([]);
+            expect(results).toEqual([]);
+            expect(mockExecuteAppleScript).not.toHaveBeenCalled();
         });
     });
     describe("batchMoveNotes", () => {
-        // Helper to create getNoteById mock output (matches AppleScript format)
-        const noteByIdOutput = (title, passwordProtected = false) => [
-            title,
-            "x-coredata://ABC/ICNote/p1",
-            "Sunday, January 1, 2025 at 1:00:00 PM",
-            "Sunday, January 1, 2025 at 1:00:00 PM",
-            "false",
-            String(passwordProtected),
-        ].join(F);
-        it("moves multiple notes successfully", () => {
-            // For each note: getNoteById, getNoteById (password check), getNoteContentById, create, delete
-            mockExecuteAppleScript
-                // First note: getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                // First note: getNoteById for password check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                // First note: moveNoteById calls getNoteContentById
-                .mockReturnValueOnce({ success: true, output: "<div>Note 1</div><div>Content</div>" })
-                // First note: createNote in destination
-                .mockReturnValueOnce({ success: true, output: "" })
-                // First note: deleteNoteById (original)
-                .mockReturnValueOnce({ success: true, output: "" })
-                // Second note: getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 2", false) })
-                // Second note: getNoteById for password check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 2", false) })
-                // Second note: moveNoteById calls getNoteContentById
-                .mockReturnValueOnce({ success: true, output: "<div>Note 2</div><div>Content</div>" })
-                // Second note: createNote in destination
-                .mockReturnValueOnce({ success: true, output: "" })
-                // Second note: deleteNoteById (original)
-                .mockReturnValueOnce({ success: true, output: "" });
-            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: "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",
+        const ID1 = "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1";
+        const ID2 = "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2";
+        it("moves the whole batch in a single osascript spawn (#26)", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
                 success: true,
+                output: ["ok", "ok"].join(R) + R,
             });
+            const results = manager.batchMoveNotes([ID1, ID2], "Archive");
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1);
+            expect(results).toHaveLength(2);
+            expect(results[0]).toEqual({ id: ID1, success: true });
+            expect(results[1]).toEqual({ id: ID2, success: true });
         });
         it("returns error for non-existent note", () => {
-            // getNoteById fails for existence check
-            mockExecuteAppleScript.mockReturnValueOnce({
-                success: false,
-                output: "",
-                error: "Not found",
-            });
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "missing" + R });
             const results = manager.batchMoveNotes(["x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404"], "Archive");
             expect(results[0]).toEqual({
                 id: "x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404",
@@ -1731,17 +1772,18 @@ describe("AppleNotesManager", () => {
             });
         });
         it("returns error for password-protected note", () => {
-            mockExecuteAppleScript
-                // getNoteById for existence check
-                .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(["x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1"], "Archive");
-            expect(results[0]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-                success: false,
-                error: "Note is password-protected",
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "pw" + R });
+            const results = manager.batchMoveNotes([ID1], "Archive");
+            expect(results[0]).toEqual({ id: ID1, success: false, error: "Note is password-protected" });
+        });
+        it("maps a per-item move failure to 'Move failed'", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
+                success: true,
+                output: ["ok", "fail"].join(R) + R,
             });
+            const results = manager.batchMoveNotes([ID1, ID2], "Archive");
+            expect(results[0]).toEqual({ id: ID1, success: true });
+            expect(results[1]).toEqual({ id: ID2, success: false, error: "Move failed" });
         });
     });
     // ---------------------------------------------------------------------------
@@ -1764,7 +1806,10 @@ describe("AppleNotesManager", () => {
                 // listFolders for iCloud
                 .mockReturnValueOnce({ success: true, output: "id1\tNotes" })
                 // listNotes for Notes folder
-                .mockReturnValueOnce({ success: true, output: "Test Note" })
+                .mockReturnValueOnce({
+                success: true,
+                output: ["Test Note", "x-coredata://ABC/ICNote/p1"].join(F),
+            })
                 // getNoteDetails
                 .mockReturnValueOnce({ success: true, output: noteDetailsOutput("Test Note", false) })
                 // getNoteContent
@@ -1789,7 +1834,10 @@ describe("AppleNotesManager", () => {
                 // listFolders for iCloud
                 .mockReturnValueOnce({ success: true, output: "id1\tNotes" })
                 // listNotes for Notes folder
-                .mockReturnValueOnce({ success: true, output: "Locked Note" })
+                .mockReturnValueOnce({
+                success: true,
+                output: ["Locked Note", "x-coredata://ABC/ICNote/p1"].join(F),
+            })
                 // getNoteDetails (passwordProtected = true)
                 .mockReturnValueOnce({ success: true, output: noteDetailsOutput("Locked Note", true) });
             // No getNoteContent call because note is password-protected

package/build/utils/hashtags.js

@@ -0,0 +1,56 @@
+/**
+ * Inline hashtag extraction for Apple Notes.
+ *
+ * Apple Notes "tags" are not a first-class AppleScript property — they are
+ * inline `#hashtag` tokens typed into the note body. Notes stores the tag
+ * relationship in its private Core Data store, which AppleScript does not
+ * expose, so the only way to surface a note's tags is to parse them back out
+ * of the body text. This module does exactly that.
+ *
+ * See docs/APPLESCRIPT-LIMITATIONS.md and issue #29.
+ */
+/**
+ * Strip HTML tags from a Notes body and neutralise numeric character
+ * references so they can't masquerade as hashtags (e.g. `’`).
+ */
+function htmlToText(html) {
+    return html
+        .replace(/<[^>]*>/g, " ") // drop tags
+        .replace(/&#x?[0-9a-f]+;/gi, " ") // neutralise numeric entities (&#8217;)
+        .replace(/&[a-z]+;/gi, " "); // neutralise named entities (&amp; &nbsp;)
+}
+/**
+ * A hashtag token: `#` followed by a run of letters/digits/underscores that
+ * contains at least one letter. This matches Apple Notes' own rule — a purely
+ * numeric token like `#123` is NOT treated as a tag. The token must not be
+ * preceded by a word character, so `foo#bar` and URL fragments like
+ * `page.html#section` (preceded by a letter) are ignored.
+ */
+const HASHTAG_RE = /(?<![\p{L}\p{N}_])#([\p{L}\p{N}_]*\p{L}[\p{L}\p{N}_]*)/gu;
+/**
+ * Extract inline `#hashtag` tokens from a note body (HTML or plain text).
+ *
+ * - HTML is stripped first, so tags inside `<div>#work</div>` are found.
+ * - Pure-number tokens (`#123`) are ignored, matching Notes' behaviour.
+ * - Results are de-duplicated case-insensitively, preserving the first-seen
+ *   casing and document order. The leading `#` is not included.
+ *
+ * @param body - The note body, as HTML or plain text.
+ * @returns Ordered, de-duplicated tag names without the leading `#`.
+ */
+export function parseHashtags(body) {
+    if (!body)
+        return [];
+    const text = htmlToText(body);
+    const seen = new Set();
+    const result = [];
+    for (const match of text.matchAll(HASHTAG_RE)) {
+        const tag = match[1];
+        const key = tag.toLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(tag);
+        }
+    }
+    return result;
+}

package/build/utils/hashtags.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { parseHashtags } from "../utils/hashtags.js";
+describe("parseHashtags", () => {
+    it("returns [] for empty / nullish input", () => {
+        expect(parseHashtags("")).toEqual([]);
+        expect(parseHashtags(null)).toEqual([]);
+        expect(parseHashtags(undefined)).toEqual([]);
+        expect(parseHashtags("no tags here")).toEqual([]);
+    });
+    it("extracts a single tag", () => {
+        expect(parseHashtags("Buy milk #groceries")).toEqual(["groceries"]);
+    });
+    it("extracts multiple tags in document order", () => {
+        expect(parseHashtags("#work then #home then #travel")).toEqual(["work", "home", "travel"]);
+    });
+    it("strips the leading # and not the rest", () => {
+        expect(parseHashtags("#project_alpha")).toEqual(["project_alpha"]);
+    });
+    it("finds tags inside HTML bodies", () => {
+        expect(parseHashtags("<div>Plan <b>#q3</b> launch</div>")).toEqual(["q3"]);
+    });
+    it("de-duplicates case-insensitively, keeping first-seen casing", () => {
+        expect(parseHashtags("#Work and #work and #WORK")).toEqual(["Work"]);
+    });
+    it("ignores purely numeric tokens (matches Notes behaviour)", () => {
+        expect(parseHashtags("ticket #123 and #4you")).toEqual(["4you"]);
+    });
+    it("does not match mid-word or URL fragments", () => {
+        expect(parseHashtags("foo#bar")).toEqual([]);
+        expect(parseHashtags("see page.html#section for details")).toEqual([]);
+    });
+    it("does not treat numeric HTML entities as tags", () => {
+        // &#8217; is a right single quote entity, not a #8217 tag
+        expect(parseHashtags("It&#8217;s a #plan")).toEqual(["plan"]);
+    });
+    it("matches a tag at the very start of the body", () => {
+        expect(parseHashtags("#start of note")).toEqual(["start"]);
+    });
+    it("handles tags terminated by punctuation", () => {
+        expect(parseHashtags("done: #alpha, #beta; #gamma.")).toEqual(["alpha", "beta", "gamma"]);
+    });
+    it("supports unicode letters in tags", () => {
+        expect(parseHashtags("café trip #café")).toEqual(["café"]);
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.0.1",
-  "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude",
+  "version": "2.1.1",
+  "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -20,19 +20,22 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:all": "vitest run && vitest run --config vitest.integration.config.ts",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "format": "prettier --write src",
     "format:check": "prettier --check src",
     "typecheck": "tsc --noEmit",
-    "version": "node -e \"const p=require('./package.json'); const f='.claude-plugin/plugin.json'; const c=JSON.parse(require('fs').readFileSync(f,'utf8')); c.version=p.version; require('fs').writeFileSync(f,JSON.stringify(c,null,2)+'\\n')\" && git add .claude-plugin/plugin.json",
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .hermes-plugin .antigravity-plugin",
     "prepublishOnly": "npm run lint && npm run test && npm run build",
-    "prepare": "husky && npm run build"
+    "prepare": "husky; npm run build"
   },
   "keywords": [
     "mcp",
     "apple-notes",
     "claude",
+    "codex",
     "ai",
     "applescript",
     "macos",
@@ -78,7 +81,7 @@
     "vitest": "^2.0.0"
   },
   "volta": {
-    "node": "22.13.1"
+    "node": "24.17.0"
   },
   "lint-staged": {
     "src/**/*.ts": [