apple-notes-mcp 1.4.0 → 1.4.2

package/README.md

@@ -757,6 +757,29 @@ All other tools work normally without Full Disk Access. Only checklist state fea
 | Limited rich formatting | Use `format: "html"` on create/update for headings, lists, bold, code blocks; some complex formatting may not render |
 | Title matching | Most operations require exact title matches |
 | Checklist state | Requires Full Disk Access to read done/undone state from the database |
+| Checklist **creation** | Not supported. AppleScript's `body of note` setter strips `<input type="checkbox">` and ignores any checklist-styling CSS class. Apple Notes stores checklist items as a protobuf paragraph style (`style_type=103`) that AppleScript doesn't expose, and the SQLite database is read-only. See [Creating Checklists](#creating-checklists) below for the workaround. |
+
+### Creating Checklists
+
+**There is no programmatic way to create a true Apple Notes checklist via AppleScript** — and therefore no way via this MCP server. This is an Apple limitation, not a bug.
+
+When a note is created or updated via AppleScript:
+
+| You send | What Notes.app actually renders |
+|----------|--------------------------------|
+| `<input type="checkbox"> Item` | `Item` (the `<input>` tag is stripped) |
+| `<ul class="checklist"><li>Item</li></ul>` | A plain bulleted list — the `checklist` class is dropped |
+| Markdown `- [ ] Item` (in `plaintext` mode) | The literal text `- [ ] Item` |
+
+Apple Notes stores checklists as a paragraph style (`style_type=103`) inside a gzipped protobuf blob in the `NoteStore.sqlite` database. AppleScript's note `body` interface does not expose paragraph styles, and writing directly to the live database is unsafe.
+
+**Workarounds:**
+
+1. **Create the note with bulleted list items, then convert manually in Notes.app.** Select the items and press <kbd>⇧⌘L</kbd> (or **Format → Checklist**). This converts the list in place and the resulting checklist will be readable by `get-checklist-state` and annotated by `get-note-markdown`.
+2. **Use the Apple Shortcuts app** to script the checklist creation, since Shortcuts can manipulate Notes content at a higher level than AppleScript.
+3. **Read-only checklist support is fully implemented** — once a checklist exists (created manually or by another app), `get-checklist-state` and `get-note-markdown` will read its done/undone state correctly (with Full Disk Access).
+
+If you need to *track* todos programmatically and don't strictly need them rendered as Apple Notes checklist UI, plain markdown-style `- [ ] item` / `- [x] item` lines in a `plaintext` note are a reasonable alternative — they are searchable, human-readable, and can be parsed by downstream tooling.
 
 ### Backslash Escaping (Important for AI Agents)
 
@@ -812,7 +835,7 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 ```bash
 npm install      # Install dependencies
 npm run build    # Compile TypeScript
-npm test         # Run test suite (310 tests)
+npm test         # Run test suite (313 tests)
 npm run lint     # Check code style
 npm run format   # Format code
 ```
@@ -838,4 +861,6 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gui
 
 ## Related Projects
 
-- [apple-mail-mcp](https://github.com/sweetrb/apple-mail-mcp) - MCP server for Apple Mail
+- [apple-mail-mcp](https://github.com/sweetrb/apple-mail-mcp) — MCP server for Apple Mail
+- [apple-numbers-mcp](https://github.com/sweetrb/apple-numbers-mcp) — MCP server for Apple Numbers spreadsheets
+- [apple-photos-mcp](https://github.com/sweetrb/apple-photos-mcp) — MCP server for Apple Photos

package/build/index.js

@@ -26,6 +26,7 @@ import { z } from "zod";
 import { AppleNotesManager } from "./services/appleNotesManager.js";
 import { getSyncStatus, withSyncAwarenessSync } from "./utils/syncDetection.js";
 import { getChecklistItems, hasFullDiskAccess } from "./utils/checklistParser.js";
+import { detectChecklistAttempt } from "./utils/contentWarnings.js";
 // Read version from package.json to keep it in sync
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
@@ -112,7 +113,10 @@ const folderNameSchema = {
 // --- create-note ---
 server.tool("create-note", {
     title: z.string().min(1, "Title is required"),
-    content: z.string().min(1, "Content is required"),
+    content: z
+        .string()
+        .min(1, "Content is required")
+        .describe('Note body. AppleScript cannot create true Apple Notes checklists — `<input type="checkbox">`, checklist CSS classes, and markdown `- [ ]` lines do not render as checkable items. To produce a checklist, create the note with a plain `<ul>` or `- ` list and convert it in Notes.app with ⇧⌘L.'),
     format: z
         .enum(["plaintext", "html"])
         .optional()
@@ -129,7 +133,8 @@ 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}" [id: ${note.id}]`);
+    const checklistWarning = detectChecklistAttempt(content) ?? "";
+    return successResponse(`Note created: "${note.title}" [id: ${note.id}]${checklistWarning}`);
 }, "Error creating note"));
 // --- search-notes ---
 server.tool("search-notes", {
@@ -261,7 +266,10 @@ server.tool("update-note", {
     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"),
+    newContent: z
+        .string()
+        .min(1, "New content is required")
+        .describe("New note body. AppleScript cannot produce true Apple Notes checklists; checkbox inputs and `- [ ]` markdown do not render as checkable items. Use a plain list and convert in Notes.app with ⇧⌘L."),
     format: z
         .enum(["plaintext", "html"])
         .optional()
@@ -291,7 +299,8 @@ server.tool("update-note", {
         const sharedWarning = note.shared
             ? "\n\n⚠️ This note is shared with collaborators. Your changes will be visible to them."
             : "";
-        return successResponse(`Note updated: "${displayTitle}"${sharedWarning}`);
+        const checklistWarning = detectChecklistAttempt(newContent) ?? "";
+        return successResponse(`Note updated: "${displayTitle}"${sharedWarning}${checklistWarning}`);
     }
     // Fall back to title-based update
     if (!title) {
@@ -314,7 +323,8 @@ server.tool("update-note", {
     const sharedWarning = note.shared
         ? "\n\n⚠️ This note is shared with collaborators. Your changes will be visible to them."
         : "";
-    return successResponse(`Note updated: "${finalTitle}"${sharedWarning}`);
+    const checklistWarning = detectChecklistAttempt(newContent) ?? "";
+    return successResponse(`Note updated: "${finalTitle}"${sharedWarning}${checklistWarning}`);
 }, "Error updating note"));
 // --- delete-note ---
 server.tool("delete-note", {
@@ -454,10 +464,16 @@ server.tool("list-folders", {
     return successResponse(`Found ${folders.length} folders${acct}:\n${folderList}${syncNote}`);
 }, "Error listing folders"));
 // --- create-folder ---
-server.tool("create-folder", folderNameSchema, withErrorHandling(({ name, account }) => {
+server.tool("create-folder", {
+    name: z
+        .string()
+        .min(1, "Folder name is required")
+        .describe('Folder name or nested path separated by "/". E.g., "Retro Tech/PC/CPUs" creates all intermediate folders. Existing segments are skipped.'),
+    account: z.string().optional().describe("Account name (defaults to iCloud)"),
+}, withErrorHandling(({ name, account }) => {
     const folder = notesManager.createFolder(name, account);
     if (!folder) {
-        return errorResponse(`Failed to create folder "${name}". It may already exist.`);
+        return errorResponse(`Failed to create folder "${name}".`);
     }
     return successResponse(`Folder created: "${folder.name}"`);
 }, "Error creating folder"));

package/build/services/appleNotesManager.js

@@ -539,11 +539,11 @@ export class AppleNotesManager {
         let createCommand;
         if (folder) {
             // Create note in specific folder (supports nested paths like "Work/Clients")
+            // Note: We avoid `set newNote` + `return id of newNote` because AppleScript
+            // fails to resolve the note reference in deeply nested folder contexts (-1728).
+            // The implicit return from `make new note` includes the ID which we parse.
             const folderRef = buildFolderReference(folder);
-            createCommand = `
-        set newNote to make new note at ${folderRef} with properties {body:"${safeBody}"}
-        return id of newNote
-      `;
+            createCommand = `make new note at ${folderRef} with properties {body:"${safeBody}"}`;
         }
         else {
             // Create note in default location
@@ -1194,16 +1194,52 @@ export class AppleNotesManager {
      */
     createFolder(name, account) {
         const targetAccount = this.resolveAccount(account);
-        const safeName = escapeForAppleScript(name);
-        const createCommand = `make new folder with properties {name:"${safeName}"}`;
-        const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
-        const result = executeAppleScript(script);
-        if (!result.success) {
-            console.error(`Failed to create folder "${name}":`, result.error);
+        const parts = splitFolderPath(name);
+        if (parts.length === 0) {
+            console.error(`Invalid folder name: "${name}"`);
             return null;
         }
-        // Extract the folder ID from the response
-        const folderId = extractCoreDataId(result.output, "folder");
+        // Create each segment of the path, checking existence first to avoid duplicates.
+        // For "A/B/C": ensure "A" exists, then "A/B", then "A/B/C".
+        for (let i = 0; i < parts.length; i++) {
+            const currentPath = parts
+                .slice(0, i + 1)
+                .map((p) => escapeFolderName(p))
+                .join("/");
+            const currentRef = buildFolderReference(currentPath);
+            // Check if this folder already exists
+            const checkScript = buildAccountScopedScript({ account: targetAccount }, `return id of ${currentRef}`);
+            const checkResult = executeAppleScript(checkScript);
+            if (checkResult.success) {
+                // Folder exists, move to next segment
+                continue;
+            }
+            // Folder doesn't exist — create it
+            const segmentName = escapeForAppleScript(parts[i]);
+            let createCommand;
+            if (i === 0) {
+                createCommand = `make new folder with properties {name:"${segmentName}"}`;
+            }
+            else {
+                const parentPath = parts
+                    .slice(0, i)
+                    .map((p) => escapeFolderName(p))
+                    .join("/");
+                const parentRef = buildFolderReference(parentPath);
+                createCommand = `make new folder at ${parentRef} with properties {name:"${segmentName}"}`;
+            }
+            const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
+            const result = executeAppleScript(script);
+            if (!result.success) {
+                console.error(`Failed to create folder "${name}":`, result.error);
+                return null;
+            }
+        }
+        // Get the ID of the final (deepest) folder
+        const fullRef = buildFolderReference(name);
+        const idScript = buildAccountScopedScript({ account: targetAccount }, `return id of ${fullRef}`);
+        const idResult = executeAppleScript(idScript);
+        const folderId = idResult.success ? extractCoreDataId(idResult.output, "folder") : "";
         return {
             id: folderId,
             name,

package/build/services/appleNotesManager.test.js

@@ -1047,7 +1047,16 @@ describe("AppleNotesManager", () => {
     });
     describe("createFolder", () => {
         it("returns Folder object on success", () => {
-            mockExecuteAppleScript.mockReturnValue({
+            mockExecuteAppleScript
+                // Check existence — folder doesn't exist
+                .mockReturnValueOnce({ success: false, output: "", error: "Can't get folder" })
+                // Create the folder
+                .mockReturnValueOnce({
+                success: true,
+                output: "folder id x-coredata://ABC123/ICFolder/p456",
+            })
+                // Get ID of created folder
+                .mockReturnValueOnce({
                 success: true,
                 output: "folder id x-coredata://ABC123/ICFolder/p456",
             });
@@ -1056,15 +1065,82 @@ describe("AppleNotesManager", () => {
             expect(result?.name).toBe("New Project");
             expect(result?.id).toBe("x-coredata://ABC123/ICFolder/p456");
         });
-        it("returns null on failure", () => {
-            mockExecuteAppleScript.mockReturnValue({
+        it("returns existing folder without creating duplicate", () => {
+            mockExecuteAppleScript
+                // Check existence — folder already exists
+                .mockReturnValueOnce({
+                success: true,
+                output: "x-coredata://ABC123/ICFolder/p789",
+            })
+                // Get ID of existing folder
+                .mockReturnValueOnce({
+                success: true,
+                output: "folder id x-coredata://ABC123/ICFolder/p789",
+            });
+            const result = manager.createFolder("Existing Folder");
+            expect(result).not.toBeNull();
+            expect(result?.name).toBe("Existing Folder");
+            expect(result?.id).toBe("x-coredata://ABC123/ICFolder/p789");
+            // Should only have 2 calls (check + get ID), no create call
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(2);
+        });
+        it("returns null on genuine failure", () => {
+            mockExecuteAppleScript
+                // Check existence — doesn't exist
+                .mockReturnValueOnce({ success: false, output: "", error: "Can't get folder" })
+                // Create fails
+                .mockReturnValueOnce({
                 success: false,
                 output: "",
-                error: "Folder already exists",
+                error: "Permission denied",
             });
-            const result = manager.createFolder("Existing Folder");
+            const result = manager.createFolder("Restricted Folder");
             expect(result).toBeNull();
         });
+        it("creates nested folder path", () => {
+            mockExecuteAppleScript
+                // Check "Retro Tech" — doesn't exist
+                .mockReturnValueOnce({ success: false, output: "", error: "Can't get folder" })
+                // Create "Retro Tech"
+                .mockReturnValueOnce({ success: true, output: "folder id x-coredata://A/ICFolder/p1" })
+                // Check "Retro Tech/PC" — doesn't exist
+                .mockReturnValueOnce({ success: false, output: "", error: "Can't get folder" })
+                // Create "PC" inside "Retro Tech"
+                .mockReturnValueOnce({ success: true, output: "folder id x-coredata://A/ICFolder/p2" })
+                // Check "Retro Tech/PC/CPUs" — doesn't exist
+                .mockReturnValueOnce({ success: false, output: "", error: "Can't get folder" })
+                // Create "CPUs" inside "Retro Tech/PC"
+                .mockReturnValueOnce({ success: true, output: "folder id x-coredata://A/ICFolder/p3" })
+                // Get ID of final folder
+                .mockReturnValueOnce({ success: true, output: "folder id x-coredata://A/ICFolder/p3" });
+            const result = manager.createFolder("Retro Tech/PC/CPUs");
+            expect(result).not.toBeNull();
+            expect(result?.name).toBe("Retro Tech/PC/CPUs");
+            expect(result?.id).toBe("x-coredata://A/ICFolder/p3");
+            // Verify the create commands (calls at index 1, 3, 5)
+            const calls = mockExecuteAppleScript.mock.calls;
+            expect(calls[1][0]).toContain('make new folder with properties {name:"Retro Tech"}');
+            expect(calls[3][0]).toContain('make new folder at folder "Retro Tech" with properties {name:"PC"}');
+            expect(calls[5][0]).toContain('make new folder at folder "PC" of folder "Retro Tech" with properties {name:"CPUs"}');
+        });
+        it("skips existing intermediate folders in nested path", () => {
+            mockExecuteAppleScript
+                // Check "Retro Tech" — exists
+                .mockReturnValueOnce({ success: true, output: "x-coredata://A/ICFolder/p1" })
+                // Check "Retro Tech/PC" — doesn't exist
+                .mockReturnValueOnce({ success: false, output: "", error: "Can't get folder" })
+                // Create "PC" inside "Retro Tech"
+                .mockReturnValueOnce({ success: true, output: "folder id x-coredata://A/ICFolder/p2" })
+                // Get ID of final folder
+                .mockReturnValueOnce({ success: true, output: "folder id x-coredata://A/ICFolder/p2" });
+            const result = manager.createFolder("Retro Tech/PC");
+            expect(result).not.toBeNull();
+            expect(result?.name).toBe("Retro Tech/PC");
+            // No create call for "Retro Tech" — only for "PC"
+            const createCalls = mockExecuteAppleScript.mock.calls.filter((c) => c[0].includes("make new folder"));
+            expect(createCalls).toHaveLength(1);
+            expect(createCalls[0][0]).toContain('name:"PC"');
+        });
     });
     describe("deleteFolder", () => {
         it("returns true on successful deletion", () => {

package/build/utils/contentWarnings.js

@@ -0,0 +1,44 @@
+/**
+ * Content Warnings for create-note / update-note
+ *
+ * Detects content patterns that look like the user is trying to do something
+ * Apple Notes via AppleScript cannot actually render — so the response can
+ * carry a clear warning instead of silently producing a broken note.
+ *
+ * @module utils/contentWarnings
+ */
+/**
+ * Detects checklist-like syntax in note content.
+ *
+ * Apple Notes checklists are a paragraph style stored in a protobuf blob in
+ * the NoteStore SQLite database. AppleScript's `body of note` setter does not
+ * expose paragraph styles: `<input type="checkbox">` is stripped, a
+ * `class="checklist"` on `<ul>` is dropped, and markdown `- [ ]` lines in
+ * `plaintext` mode arrive as literal text. There is no input that produces a
+ * real checklist.
+ *
+ * @param content - The user-supplied note body (HTML or plaintext)
+ * @returns A user-facing warning string, or null when no checklist-like
+ *   patterns are present
+ */
+export function detectChecklistAttempt(content) {
+    if (!content)
+        return null;
+    // HTML checkbox input — `<input type="checkbox" ...>` in either quoting style.
+    const htmlCheckbox = /<input\b[^>]*\btype\s*=\s*["']checkbox["']/i.test(content);
+    // Markdown-style checklist: lines starting with optional whitespace, then
+    // `-` or `*`, a space, and `[ ]` / `[x]` / `[X]`.
+    const markdownCheckbox = /^[ \t]*[-*]\s+\[[ xX]\]/m.test(content);
+    // CSS class hint — some clients try `<ul class="checklist">` or
+    // `<li class="todo">`. AppleScript drops these classes too.
+    const checklistClass = /class\s*=\s*["'][^"']*\b(?:checklist|todo)\b/i.test(content);
+    if (!htmlCheckbox && !markdownCheckbox && !checklistClass)
+        return null;
+    return ("\n\n⚠️ Your content looks like a checklist, but Apple Notes checklists " +
+        'cannot be created via AppleScript — `<input type="checkbox">` is ' +
+        "stripped, checklist CSS classes are dropped, and markdown `- [ ]` lines " +
+        "arrive as literal text. The note was created with the surrounding " +
+        "structure (list items or paragraphs) intact. To convert it to a real " +
+        "Apple Notes checklist, open the note, select the items, and press " +
+        "⇧⌘L (Format → Checklist).");
+}

package/build/utils/contentWarnings.test.js

@@ -0,0 +1,52 @@
+/**
+ * Tests for the content-warning detectors.
+ */
+import { describe, it, expect } from "vitest";
+import { detectChecklistAttempt } from "./contentWarnings.js";
+describe("detectChecklistAttempt", () => {
+    it("returns null for plain text without checklist syntax", () => {
+        expect(detectChecklistAttempt("Just a regular note.")).toBeNull();
+    });
+    it("returns null for empty content", () => {
+        expect(detectChecklistAttempt("")).toBeNull();
+    });
+    it("returns null for HTML lists that are not checklists", () => {
+        expect(detectChecklistAttempt("<ul><li>Apple</li><li>Banana</li></ul>")).toBeNull();
+    });
+    it('warns on <input type="checkbox"> (double-quoted)', () => {
+        const w = detectChecklistAttempt('<input type="checkbox"> Buy milk');
+        expect(w).not.toBeNull();
+        expect(w).toContain("⚠️");
+        expect(w).toContain("⇧⌘L");
+    });
+    it("warns on <input type='checkbox'> (single-quoted)", () => {
+        expect(detectChecklistAttempt("<input type='checkbox'> Buy milk")).not.toBeNull();
+    });
+    it("warns on <input> with extra attributes before type", () => {
+        expect(detectChecklistAttempt('<input id="x" type="checkbox"> Item')).not.toBeNull();
+    });
+    it('warns on <INPUT TYPE="CHECKBOX"> (case-insensitive)', () => {
+        expect(detectChecklistAttempt('<INPUT TYPE="CHECKBOX"> Item')).not.toBeNull();
+    });
+    it("warns on markdown `- [ ]` syntax", () => {
+        expect(detectChecklistAttempt("- [ ] todo 1\n- [x] done 1")).not.toBeNull();
+    });
+    it("warns on markdown `* [ ]` syntax", () => {
+        expect(detectChecklistAttempt("* [ ] todo 1")).not.toBeNull();
+    });
+    it("warns on markdown checklist with leading whitespace", () => {
+        expect(detectChecklistAttempt("  - [ ] indented todo")).not.toBeNull();
+    });
+    it('warns on <ul class="checklist">', () => {
+        expect(detectChecklistAttempt('<ul class="checklist"><li>a</li></ul>')).not.toBeNull();
+    });
+    it('warns on <li class="todo">', () => {
+        expect(detectChecklistAttempt('<ul><li class="todo">a</li></ul>')).not.toBeNull();
+    });
+    it("does not warn on the word 'checklist' in prose", () => {
+        expect(detectChecklistAttempt("My checklist of things to do tomorrow.")).toBeNull();
+    });
+    it("does not warn on a literal `[ ]` not at start of a list line", () => {
+        expect(detectChecklistAttempt("The brackets [ ] are not a checklist.")).toBeNull();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude",
   "type": "module",
   "main": "build/index.js",
@@ -25,6 +25,7 @@
     "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",
     "prepublishOnly": "npm run lint && npm run test && npm run build",
     "prepare": "husky && npm run build"
   },