apple-notes-mcp 1.4.1 → 1.4.3

package/README.md

@@ -712,6 +712,22 @@ If installed from source, use this configuration:
 }
 ```
 
+#### Running from a clone in Claude Code (project-scope `.mcp.json`)
+
+This repo ships a `.mcp.json` at its root so that, when you run `claude` from inside a clone, the server is registered automatically as a **project-scope** server — no manual config needed. After `npm run build`, just launch Claude Code from the repo directory and approve the server when prompted.
+
+The entrypoint is written as:
+
+```json
+"args": ["${CLAUDE_PROJECT_DIR:-.}/build/index.js"]
+```
+
+`CLAUDE_PROJECT_DIR` is the variable Claude Code injects into a project/user-scoped server's environment, and it resolves to the repo root. **You must launch `claude` from inside the repo** for this to work — the bare `.` fallback is only a last resort and is *not* reliable, because it resolves against the launching process's working directory, not the repo.
+
+> **Why not `${CLAUDE_PLUGIN_ROOT}`?** `CLAUDE_PLUGIN_ROOT` is set **only** for marketplace plugin installs, never for a project-scope clone, so it can't drive the clone workflow. Conversely, a plugin install can't use `CLAUDE_PROJECT_DIR` (in a plugin, that points at the *user's* project, not the plugin's own directory). Claude Code does **not** support nested defaults like `${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}`, so a single entrypoint string cannot serve both contexts. The two distribution paths are therefore decoupled: the **plugin** carries its own MCP config in `.claude-plugin/plugin.json` (using `${CLAUDE_PLUGIN_ROOT}`), while the root `.mcp.json` is dedicated to the **clone** workflow (using `${CLAUDE_PROJECT_DIR:-.}`). Because `plugin.json` declares its own `mcpServers`, the plugin does not also auto-load the root `.mcp.json`, so there is no double-registration.
+
+> **Heads-up on scope precedence:** project-scope (`.mcp.json`) outranks user-scope. If you *also* have an `apple-notes` entry registered at user scope (e.g. an absolute path in `~/.claude.json`), the project-scope entry wins and the user-scope one is ignored entirely. Pick one — for local development on this repo, the project-scope `.mcp.json` is the intended source. To pin a specific local build instead, register it at **local** scope (`claude mcp add apple-notes -s local -- node /abs/path/build/index.js`), which outranks project scope.
+
 ---
 
 ## Full Disk Access for Checklist Features
@@ -757,6 +773,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)
 
@@ -805,6 +844,12 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 - Use `\\` to represent each literal backslash
 - See "Backslash Escaping" section under Known Limitations
 
+### `apple-notes` server fails to connect when run from a clone
+- Launch `claude` from **inside the repo directory** so `CLAUDE_PROJECT_DIR` resolves to the repo root (the bare `.` fallback is unreliable — it points at the launching process's working directory)
+- Run `npm run build` first — the entrypoint is `${CLAUDE_PROJECT_DIR:-.}/build/index.js`, which won't exist until you build
+- Run `claude mcp list` to check for a conflicting `apple-notes` entry at another scope (project-scope outranks user-scope, but local-scope outranks project-scope)
+- Approve the pending project-scope server when Claude Code prompts you
+
 ---
 
 ## Development
@@ -838,4 +883,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.3",
   "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"
   },