apple-notes-mcp 1.2.19 → 1.3.0

package/README.md

@@ -143,6 +143,9 @@ Searches for notes by title or content.
 | `query` | string | Yes | Text to search for |
 | `searchContent` | boolean | No | If `true`, searches note body; if `false` (default), searches titles only |
 | `account` | string | No | Account to search in (defaults to iCloud) |
+| `folder` | string | No | Limit search to a specific folder |
+| `modifiedSince` | string | No | ISO 8601 date string to filter notes modified on or after this date (e.g., `"2025-01-01"`) |
+| `limit` | number | No | Maximum number of results to return |
 
 **Example - Search titles:**
 ```json
@@ -159,6 +162,16 @@ Searches for notes by title or content.
 }
 ```
 
+**Example - Search recent notes with limit:**
+```json
+{
+  "query": "todo",
+  "searchContent": true,
+  "modifiedSince": "2025-01-01",
+  "limit": 10
+}
+```
+
 **Returns:** List of matching notes with titles, folder names, and IDs. Use the returned ID for subsequent operations like `get-note-content`, `update-note`, etc.
 
 ---
@@ -356,12 +369,14 @@ Moves a note to a different folder.
 
 #### `list-notes`
 
-Lists all notes, optionally filtered by folder.
+Lists all notes, optionally filtered by folder, date, and limit.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `account` | string | No | Account to list notes from (defaults to iCloud) |
 | `folder` | string | No | Filter to notes in this folder only |
+| `modifiedSince` | string | No | ISO 8601 date string to filter notes modified on or after this date (e.g., `"2025-01-01"`) |
+| `limit` | number | No | Maximum number of notes to return |
 
 **Example - All notes:**
 ```json
@@ -375,6 +390,14 @@ Lists all notes, optionally filtered by folder.
 }
 ```
 
+**Example - Recent notes with limit:**
+```json
+{
+  "modifiedSince": "2025-06-01",
+  "limit": 20
+}
+```
+
 **Returns:** List of note titles.
 
 ---

package/build/index.js

@@ -132,11 +132,18 @@ server.tool("search-notes", {
     searchContent: z.boolean().optional().describe("Search note content instead of titles"),
     account: z.string().optional().describe("Account to search in"),
     folder: z.string().optional().describe("Limit search to a specific folder"),
-}, withErrorHandling(({ query, searchContent = false, account, folder }) => {
+    modifiedSince: z
+        .string()
+        .optional()
+        .describe("ISO 8601 date string to filter notes modified on or after this date (e.g., '2025-01-01'). Useful for searching only recent notes in large collections."),
+    limit: z.number().int().positive().optional().describe("Maximum number of results to return"),
+}, withErrorHandling(({ query, searchContent = false, account, folder, modifiedSince, limit }) => {
     // Use sync-aware wrapper for this read operation
-    const { result: notes, syncBefore, syncInterference, } = withSyncAwarenessSync("search-notes", () => notesManager.searchNotes(query, searchContent, account, folder));
+    const { result: notes, syncBefore, syncInterference, } = withSyncAwarenessSync("search-notes", () => notesManager.searchNotes(query, searchContent, account, folder, modifiedSince, limit));
     const searchType = searchContent ? "content" : "titles";
     const folderInfo = folder ? ` in folder "${folder}"` : "";
+    const dateInfo = modifiedSince ? ` modified since ${modifiedSince}` : "";
+    const limitInfo = limit ? ` (limit: ${limit})` : "";
     // Build sync warning if needed
     const syncWarnings = [];
     if (syncBefore.syncDetected) {
@@ -147,7 +154,7 @@ server.tool("search-notes", {
     }
     const syncNote = syncWarnings.length > 0 ? `\n\n${syncWarnings.join(" ")}` : "";
     if (notes.length === 0) {
-        return successResponse(`No notes found matching "${query}" in ${searchType}${folderInfo}${syncNote}`);
+        return successResponse(`No notes found matching "${query}" in ${searchType}${folderInfo}${dateInfo}${syncNote}`);
     }
     // Format each note with ID and folder info, highlighting Recently Deleted
     const noteList = notes
@@ -162,7 +169,7 @@ server.tool("search-notes", {
         return `  - ${n.title}${idSuffix}`;
     })
         .join("\n");
-    return successResponse(`Found ${notes.length} notes (searched ${searchType}${folderInfo}):\n${noteList}${syncNote}`);
+    return successResponse(`Found ${notes.length} notes (searched ${searchType}${folderInfo}${dateInfo}${limitInfo}):\n${noteList}${syncNote}`);
 }, "Error searching notes"));
 // --- get-note-content ---
 server.tool("get-note-content", {
@@ -388,12 +395,19 @@ server.tool("move-note", {
 server.tool("list-notes", {
     account: z.string().optional().describe("Account to list notes from"),
     folder: z.string().optional().describe("Filter to specific folder"),
-}, withErrorHandling(({ account, folder }) => {
+    modifiedSince: z
+        .string()
+        .optional()
+        .describe("ISO 8601 date string to filter notes modified on or after this date (e.g., '2025-01-01'). Useful for listing only recent notes in large collections."),
+    limit: z.number().int().positive().optional().describe("Maximum number of notes to return"),
+}, withErrorHandling(({ account, folder, modifiedSince, limit }) => {
     // Use sync-aware wrapper for this read operation
-    const { result: notes, syncBefore, syncInterference, } = withSyncAwarenessSync("list-notes", () => notesManager.listNotes(account, folder));
+    const { result: notes, syncBefore, syncInterference, } = withSyncAwarenessSync("list-notes", () => notesManager.listNotes(account, folder, modifiedSince, limit));
     // Build context string for the response
     const location = folder ? ` in folder "${folder}"` : "";
     const acct = account ? ` (${account})` : "";
+    const dateInfo = modifiedSince ? ` modified since ${modifiedSince}` : "";
+    const limitInfo = limit ? ` (limit: ${limit})` : "";
     // Build sync warning if needed
     const syncWarnings = [];
     if (syncBefore.syncDetected) {
@@ -404,10 +418,10 @@ server.tool("list-notes", {
     }
     const syncNote = syncWarnings.length > 0 ? `\n\n${syncWarnings.join(" ")}` : "";
     if (notes.length === 0) {
-        return successResponse(`No notes found${location}${acct}${syncNote}`);
+        return successResponse(`No notes found${location}${acct}${dateInfo}${syncNote}`);
     }
     const noteList = notes.map((t) => `  - ${t}`).join("\n");
-    return successResponse(`Found ${notes.length} notes${location}${acct}:\n${noteList}${syncNote}`);
+    return successResponse(`Found ${notes.length} notes${location}${acct}${dateInfo}${limitInfo}:\n${noteList}${syncNote}`);
 }, "Error listing notes"));
 // =============================================================================
 // Folder Tools

package/build/services/appleNotesManager.js

@@ -144,6 +144,33 @@ export function parseAppleScriptDate(appleScriptDate) {
     // Return parsed date if valid, otherwise current date as fallback
     return isNaN(parsed.getTime()) ? new Date() : parsed;
 }
+/**
+ * Generates AppleScript code that creates a date variable with the given values.
+ *
+ * This approach is locale-independent, unlike `date "M/D/YYYY"` coercion which
+ * depends on the system's date format settings and would fail on non-US locales.
+ *
+ * @param date - JavaScript Date object
+ * @param varName - AppleScript variable name to assign (default: "thresholdDate")
+ * @returns AppleScript code that sets up the date variable
+ *
+ * @example
+ * buildAppleScriptDateVar(new Date("2025-06-15T00:00:00"))
+ * // Returns multi-line AppleScript that sets thresholdDate to June 15, 2025 midnight
+ */
+export function buildAppleScriptDateVar(date, varName = "thresholdDate") {
+    const year = date.getFullYear();
+    const month = date.getMonth() + 1;
+    const day = date.getDate();
+    const timeInSeconds = date.getHours() * 3600 + date.getMinutes() * 60 + date.getSeconds();
+    return [
+        `set ${varName} to current date`,
+        `set year of ${varName} to ${year}`,
+        `set month of ${varName} to ${month}`,
+        `set day of ${varName} to ${day}`,
+        `set time of ${varName} to ${timeInSeconds}`,
+    ].join("\n");
+}
 /**
  * Parses AppleScript note properties output into structured data.
  *
@@ -433,6 +460,8 @@ export class AppleNotesManager {
      * @param searchContent - If true, search note bodies; if false, search titles
      * @param account - Account to search in (defaults to iCloud)
      * @param folder - Optional folder to limit search to
+     * @param modifiedSince - Optional ISO 8601 date string to filter notes modified on or after this date
+     * @param limit - Optional maximum number of results to return (default: no limit)
      * @returns Array of matching notes (with minimal metadata)
      *
      * @example
@@ -445,25 +474,53 @@ export class AppleNotesManager {
      *
      * // Search within a specific folder
      * const workNotes = manager.searchNotes("deadline", false, "iCloud", "Work");
+     *
+     * // Search only recently modified notes
+     * const recentNotes = manager.searchNotes("todo", true, undefined, undefined, "2025-01-01");
+     *
+     * // Search with a result limit
+     * const topResults = manager.searchNotes("project", false, undefined, undefined, undefined, 10);
      * ```
      */
-    searchNotes(query, searchContent = false, account, folder) {
+    searchNotes(query, searchContent = false, account, folder, modifiedSince, limit) {
         const targetAccount = this.resolveAccount(account);
         const safeQuery = escapeForAppleScript(query);
+        const safeLimit = limit !== undefined && limit > 0 ? Math.floor(limit) : undefined;
         // Build the where clause based on search type
         // AppleScript uses 'name' for title and 'body' for content
-        const whereClause = searchContent
-            ? `body contains "${safeQuery}"`
-            : `name contains "${safeQuery}"`;
+        const whereParts = [];
+        if (searchContent) {
+            whereParts.push(`body contains "${safeQuery}"`);
+        }
+        else {
+            whereParts.push(`name contains "${safeQuery}"`);
+        }
+        // Add date filter if specified (uses locale-safe date variable)
+        let dateSetup = "";
+        if (modifiedSince) {
+            const date = new Date(modifiedSince);
+            if (!isNaN(date.getTime())) {
+                dateSetup = buildAppleScriptDateVar(date) + "\n";
+                whereParts.push(`modification date >= thresholdDate`);
+            }
+        }
+        const whereClause = whereParts.join(" and ");
         // Build the notes source - either all notes or notes in a specific folder
         const notesSource = folder ? `notes of folder "${escapeForAppleScript(folder)}"` : "notes";
+        // Build the limit logic for the repeat loop
+        // Note: The limit only reduces iteration over already-matched results from the whose clause,
+        // not the query itself. It controls output size, not AppleScript query performance.
+        const limitCheck = safeLimit !== undefined
+            ? `
+          if (count of resultList) >= ${safeLimit} then exit repeat`
+            : "";
         // 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 ${notesSource} where ${whereClause}
+      ${dateSetup}set matchingNotes to ${notesSource} where ${whereClause}
       set resultList to {}
-      repeat with n in matchingNotes
+      repeat with n in matchingNotes${limitCheck}
         try
           set noteName to name of n
           set noteId to id of n
@@ -785,15 +842,60 @@ export class AppleNotesManager {
         return true;
     }
     /**
-     * Lists all notes in an account, optionally filtered by folder.
+     * Lists all notes in an account, optionally filtered by folder, date, and limit.
      *
      * @param account - Account to list notes from (defaults to iCloud)
      * @param folder - Optional folder to filter by
+     * @param modifiedSince - Optional ISO 8601 date string to filter notes modified on or after this date
+     * @param limit - Optional maximum number of results to return (default: no limit)
      * @returns Array of note titles
      */
-    listNotes(account, folder) {
+    listNotes(account, folder, modifiedSince, limit) {
         const targetAccount = this.resolveAccount(account);
-        // Build command based on whether folder filter is specified
+        const safeLimit = limit !== undefined && limit > 0 ? Math.floor(limit) : undefined;
+        // When date or limit filters are needed, use a repeat loop for fine-grained control
+        if (modifiedSince || safeLimit !== undefined) {
+            const baseNotesSource = folder
+                ? `notes of folder "${escapeForAppleScript(folder)}"`
+                : "notes";
+            // Use whose clause for date filtering (locale-safe, no sort order assumption)
+            let dateSetup = "";
+            let notesSource = baseNotesSource;
+            if (modifiedSince) {
+                const date = new Date(modifiedSince);
+                if (!isNaN(date.getTime())) {
+                    dateSetup = buildAppleScriptDateVar(date) + "\n";
+                    notesSource = `(${baseNotesSource} whose modification date >= thresholdDate)`;
+                }
+            }
+            // Build the limit check
+            const limitCheck = safeLimit !== undefined
+                ? `
+            if (count of resultList) >= ${safeLimit} then exit repeat`
+                : "";
+            const listCommand = `
+        ${dateSetup}set resultList to {}
+        repeat with n in ${notesSource}${limitCheck}
+          set end of resultList to name of n
+        end repeat
+        set AppleScript's text item delimiters to "|||"
+        return resultList as text
+      `;
+            const script = buildAccountScopedScript({ account: targetAccount }, listCommand);
+            const result = executeAppleScript(script);
+            if (!result.success) {
+                console.error("Failed to list notes:", result.error);
+                return [];
+            }
+            if (!result.output.trim()) {
+                return [];
+            }
+            return result.output
+                .split("|||")
+                .map((item) => item.trim())
+                .filter((item) => item.length > 0);
+        }
+        // Simple path: no date or limit filters
         let listCommand;
         if (folder) {
             const safeFolder = escapeForAppleScript(folder);

package/build/services/appleNotesManager.test.js

@@ -11,7 +11,7 @@
  * - Script generation is verified by checking for expected AppleScript patterns
  */
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { AppleNotesManager, escapeForAppleScript, escapeHtmlForAppleScript, parseAppleScriptDate, } from "./appleNotesManager.js";
+import { AppleNotesManager, escapeForAppleScript, escapeHtmlForAppleScript, buildAppleScriptDateVar, parseAppleScriptDate, } from "./appleNotesManager.js";
 // Mock the AppleScript execution module
 // This prevents actual osascript calls during testing
 vi.mock("@/utils/applescript.js", () => ({
@@ -210,6 +210,41 @@ describe("parseAppleScriptDate", () => {
     });
 });
 // =============================================================================
+// buildAppleScriptDateVar Tests
+// =============================================================================
+describe("buildAppleScriptDateVar", () => {
+    it("generates locale-safe AppleScript date setup code", () => {
+        const date = new Date(2025, 5, 15, 14, 30, 0); // June 15, 2025 2:30 PM
+        const result = buildAppleScriptDateVar(date);
+        expect(result).toContain("set thresholdDate to current date");
+        expect(result).toContain("set year of thresholdDate to 2025");
+        expect(result).toContain("set month of thresholdDate to 6");
+        expect(result).toContain("set day of thresholdDate to 15");
+        // 14*3600 + 30*60 = 52200
+        expect(result).toContain("set time of thresholdDate to 52200");
+    });
+    it("handles midnight (time = 0)", () => {
+        const date = new Date(2025, 0, 1, 0, 0, 0); // Jan 1, 2025 midnight
+        const result = buildAppleScriptDateVar(date);
+        expect(result).toContain("set month of thresholdDate to 1");
+        expect(result).toContain("set day of thresholdDate to 1");
+        expect(result).toContain("set time of thresholdDate to 0");
+    });
+    it("uses custom variable name", () => {
+        const date = new Date(2025, 0, 1, 0, 0, 0);
+        const result = buildAppleScriptDateVar(date, "myDate");
+        expect(result).toContain("set myDate to current date");
+        expect(result).toContain("set year of myDate to 2025");
+        expect(result).toContain("set month of myDate to 1");
+    });
+    it("calculates time in seconds correctly", () => {
+        const date = new Date(2025, 11, 25, 9, 5, 3); // 9:05:03 AM
+        const result = buildAppleScriptDateVar(date);
+        // 9*3600 + 5*60 + 3 = 32703
+        expect(result).toContain("set time of thresholdDate to 32703");
+    });
+});
+// =============================================================================
 // AppleNotesManager Tests
 // =============================================================================
 describe("AppleNotesManager", () => {
@@ -393,6 +428,65 @@ describe("AppleNotesManager", () => {
             expect(script).toContain('tell account "Exchange"');
             expect(script).toContain('notes of folder "Projects"');
         });
+        it("adds date filter when modifiedSince is provided", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Recent Note|||x-coredata://ABC/ICNote/p1|||Notes",
+            });
+            manager.searchNotes("note", false, undefined, undefined, "2025-06-15T00:00:00");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            // Locale-safe: uses variable setup instead of date "string"
+            expect(script).toContain("set thresholdDate to current date");
+            expect(script).toContain("set year of thresholdDate to 2025");
+            expect(script).toContain("set month of thresholdDate to 6");
+            expect(script).toContain("set day of thresholdDate to 15");
+            expect(script).toContain("modification date >= thresholdDate");
+            expect(script).toContain('name contains "note"');
+        });
+        it("combines date filter with content search", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Note|||x-coredata://ABC/ICNote/p1|||Notes",
+            });
+            manager.searchNotes("keyword", true, undefined, undefined, "2025-01-01");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain('body contains "keyword"');
+            expect(script).toContain("set thresholdDate to current date");
+            expect(script).toContain("modification date >= thresholdDate");
+        });
+        it("ignores invalid modifiedSince date", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Note|||x-coredata://ABC/ICNote/p1|||Notes",
+            });
+            manager.searchNotes("note", false, undefined, undefined, "not-a-date");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).not.toContain("modification date");
+        });
+        it("applies limit to search results", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Note 1|||x-coredata://ABC/ICNote/p1|||Notes",
+            });
+            manager.searchNotes("note", false, undefined, undefined, undefined, 5);
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain("(count of resultList) >= 5");
+            expect(script).toContain("exit repeat");
+        });
+        it("combines modifiedSince, limit, folder, and content search", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Note|||x-coredata://ABC/ICNote/p1|||Work",
+            });
+            manager.searchNotes("project", true, "iCloud", "Work", "2025-03-01", 10);
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain('body contains "project"');
+            expect(script).toContain("set thresholdDate to current date");
+            expect(script).toContain("modification date >= thresholdDate");
+            expect(script).toContain('notes of folder "Work"');
+            expect(script).toContain("(count of resultList) >= 10");
+            expect(script).toContain('tell account "iCloud"');
+        });
     });
     // ---------------------------------------------------------------------------
     // Note Content Retrieval
@@ -742,6 +836,61 @@ describe("AppleNotesManager", () => {
             manager.listNotes("iCloud", "Work");
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('notes of folder "Work"'));
         });
+        it("uses whose clause when modifiedSince is provided", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Recent Note 1|||Recent Note 2",
+            });
+            const results = manager.listNotes(undefined, undefined, "2025-06-15T00:00:00");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            // Locale-safe: uses variable setup + whose clause (no sort order assumption)
+            expect(script).toContain("set thresholdDate to current date");
+            expect(script).toContain("set year of thresholdDate to 2025");
+            expect(script).toContain("set month of thresholdDate to 6");
+            expect(script).toContain("set day of thresholdDate to 15");
+            expect(script).toContain("whose modification date >= thresholdDate");
+            expect(results).toEqual(["Recent Note 1", "Recent Note 2"]);
+        });
+        it("uses repeat loop when limit is provided", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Note 1|||Note 2|||Note 3",
+            });
+            const results = manager.listNotes(undefined, undefined, undefined, 3);
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain("(count of resultList) >= 3");
+            expect(results).toEqual(["Note 1", "Note 2", "Note 3"]);
+        });
+        it("combines folder, modifiedSince, and limit", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Work Note|||Another Work Note",
+            });
+            manager.listNotes("iCloud", "Work", "2025-01-01", 10);
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain("whose modification date >= thresholdDate");
+            expect(script).toContain('notes of folder "Work"');
+            expect(script).toContain("(count of resultList) >= 10");
+        });
+        it("returns empty array when modifiedSince yields no results", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "",
+            });
+            const results = manager.listNotes(undefined, undefined, "2099-01-01");
+            expect(results).toEqual([]);
+        });
+        it("ignores invalid modifiedSince date and falls back to limit-only", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Note 1|||Note 2",
+            });
+            const results = manager.listNotes(undefined, undefined, "not-a-date", 5);
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).not.toContain("thresholdDate");
+            expect(script).toContain("(count of resultList) >= 5");
+            expect(results).toEqual(["Note 1", "Note 2"]);
+        });
     });
     // ---------------------------------------------------------------------------
     // Folder Operations

package/package.json

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