apple-notes-mcp 1.1.2 → 1.2.1

package/build/index.js

@@ -31,7 +31,7 @@ import { AppleNotesManager } from "./services/appleNotesManager.js";
  */
 const server = new McpServer({
     name: "apple-notes",
-    version: "1.1.0",
+    version: "1.2.0",
     description: "MCP server for managing Apple Notes - create, search, update, and organize notes",
 });
 /**
@@ -113,7 +113,7 @@ server.tool("create-note", {
     if (!note) {
         return errorResponse(`Failed to create note "${title}". Check that Notes.app is configured and accessible.`);
     }
-    return successResponse(`Note created: "${note.title}"`);
+    return successResponse(`Note created: "${note.title}" [id: ${note.id}]`);
 }, "Error creating note"));
 // --- search-notes ---
 server.tool("search-notes", {
@@ -126,22 +126,42 @@ server.tool("search-notes", {
     if (notes.length === 0) {
         return successResponse(`No notes found matching "${query}" in ${searchType}`);
     }
-    // Format each note with folder info, highlighting Recently Deleted
+    // Format each note with ID and folder info, highlighting Recently Deleted
     const noteList = notes
         .map((n) => {
+        const idSuffix = n.id ? ` [id: ${n.id}]` : "";
         if (n.folder === "Recently Deleted") {
-            return `  - ${n.title} [DELETED]`;
+            return `  - ${n.title} [DELETED]${idSuffix}`;
         }
         else if (n.folder) {
-            return `  - ${n.title} (${n.folder})`;
+            return `  - ${n.title} (${n.folder})${idSuffix}`;
         }
-        return `  - ${n.title}`;
+        return `  - ${n.title}${idSuffix}`;
     })
         .join("\n");
     return successResponse(`Found ${notes.length} notes (searched ${searchType}):\n${noteList}`);
 }, "Error searching notes"));
 // --- get-note-content ---
-server.tool("get-note-content", noteTitleSchema, withErrorHandling(({ title, account }) => {
+server.tool("get-note-content", {
+    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)"),
+}, withErrorHandling(({ id, title, account }) => {
+    // Prefer ID-based lookup if provided
+    if (id) {
+        const content = notesManager.getNoteContentById(id);
+        if (!content) {
+            return errorResponse(`Note with ID "${id}" not found`);
+        }
+        return successResponse(content);
+    }
+    // Fall back to title-based lookup
+    if (!title) {
+        return errorResponse("Either 'id' or 'title' is required");
+    }
     const content = notesManager.getNoteContent(title, account);
     if (!content) {
         return errorResponse(`Note "${title}" not found`);
@@ -187,11 +207,28 @@ server.tool("get-note-details", noteTitleSchema, withErrorHandling(({ title, acc
 }, "Error retrieving note details"));
 // --- update-note ---
 server.tool("update-note", {
-    title: z.string().min(1, "Current note title is required"),
+    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)"),
     newTitle: z.string().optional().describe("New title for the note"),
     newContent: z.string().min(1, "New content is required"),
-    account: z.string().optional().describe("Account containing the note"),
-}, withErrorHandling(({ title, newTitle, newContent, account }) => {
+    account: z
+        .string()
+        .optional()
+        .describe("Account containing the note (ignored if id is provided)"),
+}, withErrorHandling(({ id, title, newTitle, newContent, account }) => {
+    // Prefer ID-based update if provided
+    if (id) {
+        const success = notesManager.updateNoteById(id, newTitle, newContent);
+        if (!success) {
+            return errorResponse(`Failed to update note with ID "${id}". Note may not exist.`);
+        }
+        const displayTitle = newTitle || "(title preserved)";
+        return successResponse(`Note updated: "${displayTitle}"`);
+    }
+    // Fall back to title-based update
+    if (!title) {
+        return errorResponse("Either 'id' or 'title' is required");
+    }
     const success = notesManager.updateNote(title, newTitle, newContent, account);
     if (!success) {
         return errorResponse(`Failed to update note "${title}". Note may not exist.`);
@@ -200,7 +237,26 @@ server.tool("update-note", {
     return successResponse(`Note updated: "${finalTitle}"`);
 }, "Error updating note"));
 // --- delete-note ---
-server.tool("delete-note", noteTitleSchema, withErrorHandling(({ title, account }) => {
+server.tool("delete-note", {
+    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)"),
+}, withErrorHandling(({ id, title, account }) => {
+    // Prefer ID-based deletion if provided
+    if (id) {
+        const success = notesManager.deleteNoteById(id);
+        if (!success) {
+            return errorResponse(`Failed to delete note with ID "${id}". Note may not exist.`);
+        }
+        return successResponse(`Note deleted (by ID)`);
+    }
+    // Fall back to title-based deletion
+    if (!title) {
+        return errorResponse("Either 'id' or 'title' is required");
+    }
     const success = notesManager.deleteNote(title, account);
     if (!success) {
         return errorResponse(`Failed to delete note "${title}". Note may not exist.`);
@@ -209,10 +265,23 @@ server.tool("delete-note", noteTitleSchema, withErrorHandling(({ title, account
 }, "Error deleting note"));
 // --- move-note ---
 server.tool("move-note", {
-    title: z.string().min(1, "Note title is required"),
+    id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
+    title: z.string().optional().describe("Note title (use id instead when available)"),
     folder: z.string().min(1, "Destination folder is required"),
-    account: z.string().optional().describe("Account containing the note"),
-}, withErrorHandling(({ title, folder, account }) => {
+    account: z.string().optional().describe("Account containing the note/folder"),
+}, withErrorHandling(({ id, title, folder, account }) => {
+    // Prefer ID-based move if provided
+    if (id) {
+        const success = notesManager.moveNoteById(id, folder, account);
+        if (!success) {
+            return errorResponse(`Failed to move note with ID "${id}" to folder "${folder}". Note or folder may not exist.`);
+        }
+        return successResponse(`Note moved to "${folder}" (by ID)`);
+    }
+    // Fall back to title-based move
+    if (!title) {
+        return errorResponse("Either 'id' or 'title' is required");
+    }
     const success = notesManager.moveNote(title, folder, account);
     if (!success) {
         return errorResponse(`Failed to move note "${title}" to folder "${folder}". Note or folder may not exist.`);

package/build/services/appleNotesManager.js

@@ -262,15 +262,22 @@ export class AppleNotesManager {
         const safeContent = escapeForAppleScript(content);
         // 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);
-            createCommand = `make new note at folder "${safeFolder}" with properties {name:"${safeTitle}", body:"${safeContent}"}`;
+            createCommand = `
+        set newNote to make new note at folder "${safeFolder}" with properties {name:"${safeTitle}", body:"${safeContent}"}
+        return id of newNote
+      `;
         }
         else {
             // Create note in default location
-            createCommand = `make new note with properties {name:"${safeTitle}", body:"${safeContent}"}`;
+            createCommand = `
+        set newNote to make new note with properties {name:"${safeTitle}", body:"${safeContent}"}
+        return id of newNote
+      `;
         }
         // Execute the script
         const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
@@ -279,11 +286,12 @@ export class AppleNotesManager {
             console.error(`Failed to create note "${title}":`, result.error);
             return null;
         }
-        // Return a Note object representing the created note
-        // Note: We use a timestamp as ID since we can't easily get the real ID
+        // Extract the CoreData ID from the response
+        const noteId = result.output.trim();
+        // Return a Note object representing the created note with real ID
         const now = new Date();
         return {
-            id: Date.now().toString(),
+            id: noteId || Date.now().toString(), // Use real ID, fallback to timestamp
             title,
             content,
             tags,
@@ -321,8 +329,8 @@ export class AppleNotesManager {
         const whereClause = searchContent
             ? `body contains "${safeQuery}"`
             : `name contains "${safeQuery}"`;
-        // Get names and folder for each matching note
-        // We use a repeat loop to get both properties, separated by a delimiter
+        // Get names, IDs, and folder for each matching note
+        // We use a repeat loop to get all properties, separated by a delimiter
         // Note: Some notes may have inaccessible containers, so we wrap in try/on error
         const searchCommand = `
       set matchingNotes to notes where ${whereClause}
@@ -330,12 +338,14 @@ export class AppleNotesManager {
       repeat with n in matchingNotes
         try
           set noteName to name of n
+          set noteId to id of n
           set noteFolder to name of container of n
-          set end of resultList to noteName & "|||" & noteFolder
+          set end of resultList to noteName & "|||" & noteId & "|||" & noteFolder
         on error
           try
             set noteName to name of n
-            set end of resultList to noteName & "|||" & "Notes"
+            set noteId to id of n
+            set end of resultList to noteName & "|||" & noteId & "|||" & "Notes"
           end try
         end try
       end repeat
@@ -352,15 +362,15 @@ export class AppleNotesManager {
         if (!result.output.trim()) {
             return [];
         }
-        // Parse the delimited output: "name|||folder|||ITEM|||name|||folder..."
+        // Parse the delimited output: "name|||id|||folder|||ITEM|||name|||id|||folder..."
         const items = result.output.split("|||ITEM|||");
         const notes = [];
         for (const item of items) {
-            const [title, folder] = item.split("|||");
+            const [title, id, folder] = item.split("|||");
             if (!title?.trim())
                 continue;
             notes.push({
-                id: Date.now().toString(),
+                id: id?.trim() || Date.now().toString(), // Use real ID, fallback to timestamp
                 title: title.trim(),
                 content: "", // Not fetched in search
                 tags: [],
@@ -400,6 +410,26 @@ export class AppleNotesManager {
         }
         return result.output;
     }
+    /**
+     * Retrieves the HTML content of a note by its CoreData ID.
+     *
+     * This is more reliable than getNoteContent() because IDs are unique
+     * across all accounts, while titles can be duplicated.
+     *
+     * @param id - CoreData URL identifier for the note
+     * @returns HTML content of the note, or empty string if not found
+     */
+    getNoteContentById(id) {
+        // Note IDs work at the application level, not scoped to account
+        const getCommand = `get body of note id "${id}"`;
+        const script = buildAppLevelScript(getCommand);
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Failed to get content of note with ID "${id}":`, result.error);
+            return "";
+        }
+        return result.output;
+    }
     /**
      * Retrieves a note by its unique CoreData ID.
      *
@@ -533,6 +563,25 @@ export class AppleNotesManager {
         }
         return true;
     }
+    /**
+     * Deletes a note by its CoreData ID.
+     *
+     * This is more reliable than deleteNote() because IDs are unique
+     * across all accounts, while titles can be duplicated.
+     *
+     * @param id - CoreData URL identifier for the note
+     * @returns true if deletion succeeded, false otherwise
+     */
+    deleteNoteById(id) {
+        const deleteCommand = `delete note id "${id}"`;
+        const script = buildAppLevelScript(deleteCommand);
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Failed to delete note with ID "${id}":`, result.error);
+            return false;
+        }
+        return true;
+    }
     /**
      * Updates an existing note's content and optionally its title.
      *
@@ -564,6 +613,41 @@ export class AppleNotesManager {
         }
         return true;
     }
+    /**
+     * Updates an existing note by its CoreData ID.
+     *
+     * This is more reliable than updateNote() because IDs are unique,
+     * while titles can be duplicated.
+     *
+     * @param id - CoreData URL identifier for the note
+     * @param newTitle - New title (optional, keeps existing if not provided)
+     * @param newContent - New content for the note body
+     * @returns true if update succeeded, false otherwise
+     */
+    updateNoteById(id, newTitle, newContent) {
+        // First get the current title if newTitle is not provided
+        let effectiveTitle = newTitle;
+        if (!effectiveTitle) {
+            const note = this.getNoteById(id);
+            if (!note) {
+                console.error(`Cannot update note: note with ID "${id}" not found`);
+                return false;
+            }
+            effectiveTitle = note.title;
+        }
+        const safeEffectiveTitle = escapeForAppleScript(effectiveTitle);
+        const safeContent = escapeForAppleScript(newContent);
+        // Apple Notes uses HTML body; first <div> becomes the title
+        const fullBody = `<div>${safeEffectiveTitle}</div><div>${safeContent}</div>`;
+        const updateCommand = `set body of note id "${id}" to "${fullBody}"`;
+        const script = buildAppLevelScript(updateCommand);
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Failed to update note with ID "${id}":`, result.error);
+            return false;
+        }
+        return true;
+    }
     /**
      * Lists all notes in an account, optionally filtered by folder.
      *
@@ -682,13 +766,19 @@ export class AppleNotesManager {
      */
     moveNote(title, destinationFolder, account) {
         const targetAccount = this.resolveAccount(account);
-        // Step 1: Retrieve the original note's content
+        // Step 1: Get the original note's ID first (before creating a copy with the same title)
+        const originalNote = this.getNoteDetails(title, targetAccount);
+        if (!originalNote) {
+            console.error(`Cannot move note "${title}": note not found`);
+            return false;
+        }
+        // Step 2: Retrieve the original note's content
         const originalContent = this.getNoteContent(title, targetAccount);
         if (!originalContent) {
             console.error(`Cannot move note "${title}": failed to retrieve content`);
             return false;
         }
-        // Step 2: Create a copy in the destination folder
+        // Step 3: Create a copy in the destination folder
         // We need to escape the HTML content for AppleScript embedding
         const safeFolder = escapeForAppleScript(destinationFolder);
         const safeContent = originalContent.replace(/"/g, '\\"').replace(/'/g, "'\\''");
@@ -699,16 +789,57 @@ export class AppleNotesManager {
             console.error(`Cannot move note "${title}": failed to create in destination folder:`, copyResult.error);
             return false;
         }
-        // Step 3: Delete the original (only after successful copy)
-        const deleteSuccess = this.deleteNote(title, targetAccount);
-        if (!deleteSuccess) {
+        // 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 deleteScript = buildAppLevelScript(deleteCommand);
+        const deleteResult = executeAppleScript(deleteScript);
+        if (!deleteResult.success) {
             // The note was copied successfully but we couldn't delete the original.
             // This is still a partial success - the note exists in the new location.
-            console.error(`Note "${title}" was copied to "${destinationFolder}" but original could not be deleted`);
+            console.error(`Note "${title}" was copied to "${destinationFolder}" but original could not be deleted:`, deleteResult.error);
             return true;
         }
         return true;
     }
+    /**
+     * Moves a note to a different folder by its CoreData ID.
+     *
+     * This is more reliable than moveNote() because IDs are unique,
+     * while titles can be duplicated.
+     *
+     * @param id - CoreData URL identifier for the note
+     * @param destinationFolder - Name of the folder to move to
+     * @param account - Account containing the destination folder (defaults to iCloud)
+     * @returns true if move succeeded (or copy succeeded but delete failed)
+     */
+    moveNoteById(id, destinationFolder, account) {
+        const targetAccount = this.resolveAccount(account);
+        // Step 1: Retrieve the original note's content by ID
+        const originalContent = this.getNoteContentById(id);
+        if (!originalContent) {
+            console.error(`Cannot move note: note with ID "${id}" not found`);
+            return false;
+        }
+        // Step 2: Create a copy in the destination folder
+        const safeFolder = escapeForAppleScript(destinationFolder);
+        const safeContent = originalContent.replace(/"/g, '\\"').replace(/'/g, "'\\''");
+        const createCommand = `make new note at folder "${safeFolder}" with properties {body:"${safeContent}"}`;
+        const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
+        const copyResult = executeAppleScript(script);
+        if (!copyResult.success) {
+            console.error(`Cannot move note: failed to create in destination folder:`, copyResult.error);
+            return false;
+        }
+        // Step 3: Delete the original by ID
+        const deleteCommand = `delete note id "${id}"`;
+        const deleteScript = buildAppLevelScript(deleteCommand);
+        const deleteResult = executeAppleScript(deleteScript);
+        if (!deleteResult.success) {
+            console.error(`Note was copied to "${destinationFolder}" but original could not be deleted:`, deleteResult.error);
+            return true; // Partial success - note exists in new location
+        }
+        return true;
+    }
     // ===========================================================================
     // Account Operations
     // ===========================================================================

package/build/services/appleNotesManager.test.js

@@ -231,15 +231,18 @@ describe("AppleNotesManager", () => {
         it("returns array of matching notes with folder info", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "Meeting Notes|||Work|||ITEM|||Project Plan|||Notes|||ITEM|||Weekly Review|||Archive",
+                output: "Meeting Notes|||x-coredata://ABC/ICNote/p1|||Work|||ITEM|||Project Plan|||x-coredata://ABC/ICNote/p2|||Notes|||ITEM|||Weekly Review|||x-coredata://ABC/ICNote/p3|||Archive",
             });
             const results = manager.searchNotes("notes");
             expect(results).toHaveLength(3);
             expect(results[0].title).toBe("Meeting Notes");
+            expect(results[0].id).toBe("x-coredata://ABC/ICNote/p1");
             expect(results[0].folder).toBe("Work");
             expect(results[1].title).toBe("Project Plan");
+            expect(results[1].id).toBe("x-coredata://ABC/ICNote/p2");
             expect(results[1].folder).toBe("Notes");
             expect(results[2].title).toBe("Weekly Review");
+            expect(results[2].id).toBe("x-coredata://ABC/ICNote/p3");
             expect(results[2].folder).toBe("Archive");
         });
         it("returns empty array when no matches found", () => {
@@ -262,7 +265,7 @@ describe("AppleNotesManager", () => {
         it("searches content when searchContent is true", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "Note with keyword|||Notes",
+                output: "Note with keyword|||x-coredata://ABC/ICNote/p1|||Notes",
             });
             manager.searchNotes("project alpha", true);
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('body contains "project alpha"'));
@@ -270,7 +273,7 @@ describe("AppleNotesManager", () => {
         it("searches titles when searchContent is false", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "Project Alpha Notes|||Notes",
+                output: "Project Alpha Notes|||x-coredata://ABC/ICNote/p1|||Notes",
             });
             manager.searchNotes("Project Alpha", false);
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('name contains "Project Alpha"'));
@@ -278,13 +281,15 @@ describe("AppleNotesManager", () => {
         it("identifies notes in Recently Deleted folder", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "Old Note|||Recently Deleted|||ITEM|||Active Note|||Notes",
+                output: "Old Note|||x-coredata://ABC/ICNote/p1|||Recently Deleted|||ITEM|||Active Note|||x-coredata://ABC/ICNote/p2|||Notes",
             });
             const results = manager.searchNotes("note");
             expect(results).toHaveLength(2);
             expect(results[0].title).toBe("Old Note");
+            expect(results[0].id).toBe("x-coredata://ABC/ICNote/p1");
             expect(results[0].folder).toBe("Recently Deleted");
             expect(results[1].title).toBe("Active Note");
+            expect(results[1].id).toBe("x-coredata://ABC/ICNote/p2");
             expect(results[1].folder).toBe("Notes");
         });
         it("scopes search to specified account", () => {
@@ -596,8 +601,12 @@ describe("AppleNotesManager", () => {
     // ---------------------------------------------------------------------------
     describe("moveNote", () => {
         it("returns true when move completes successfully", () => {
-            // Mock sequence: getNoteContent -> createNote -> deleteNote
+            // Mock sequence: getNoteDetails -> getNoteContent -> createNote -> deleteNote
             mockExecuteAppleScript
+                .mockReturnValueOnce({
+                success: true,
+                output: "My Note, x-coredata://ABC/ICNote/p123, date Monday January 1 2024, date Monday January 1 2024, false, false",
+            })
                 .mockReturnValueOnce({
                 success: true,
                 output: "<div>Note Title</div><div>Content</div>",
@@ -612,9 +621,9 @@ describe("AppleNotesManager", () => {
             });
             const result = manager.moveNote("My Note", "Archive");
             expect(result).toBe(true);
-            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(3);
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(4);
         });
-        it("returns false when source note cannot be read", () => {
+        it("returns false when source note cannot be found", () => {
             mockExecuteAppleScript.mockReturnValueOnce({
                 success: false,
                 output: "",
@@ -622,10 +631,14 @@ describe("AppleNotesManager", () => {
             });
             const result = manager.moveNote("Missing Note", "Archive");
             expect(result).toBe(false);
-            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1); // Only tried to read
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1); // Only tried to get details
         });
         it("returns false when copy to destination fails", () => {
             mockExecuteAppleScript
+                .mockReturnValueOnce({
+                success: true,
+                output: "My Note, x-coredata://ABC/ICNote/p123, date Monday January 1 2024, date Monday January 1 2024, false, false",
+            })
                 .mockReturnValueOnce({
                 success: true,
                 output: "<div>Content</div>",
@@ -637,11 +650,15 @@ describe("AppleNotesManager", () => {
             });
             const result = manager.moveNote("My Note", "Nonexistent Folder");
             expect(result).toBe(false);
-            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(2); // Read + failed create
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(3); // Details + Read + failed create
         });
         it("returns true even if delete fails (note exists in new location)", () => {
             // This is partial success - note was copied but original couldn't be deleted
             mockExecuteAppleScript
+                .mockReturnValueOnce({
+                success: true,
+                output: "My Note, x-coredata://ABC/ICNote/p123, date Monday January 1 2024, date Monday January 1 2024, false, false",
+            })
                 .mockReturnValueOnce({
                 success: true,
                 output: "<div>Content</div>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude",
   "type": "module",
   "main": "build/index.js",
@@ -40,11 +40,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sweetrb/mcp-apple-notes.git"
+    "url": "git+https://github.com/sweetrb/apple-notes-mcp.git"
   },
-  "homepage": "https://github.com/sweetrb/mcp-apple-notes#readme",
+  "homepage": "https://github.com/sweetrb/apple-notes-mcp#readme",
   "bugs": {
-    "url": "https://github.com/sweetrb/mcp-apple-notes/issues"
+    "url": "https://github.com/sweetrb/apple-notes-mcp/issues"
   },
   "engines": {
     "node": ">=20.0.0"