apple-notes-mcp 1.4.1 → 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)
 
@@ -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", {

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.1",
+  "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"
   },