apple-notes-mcp 1.2.18 → 1.2.19

package/README.md

@@ -25,7 +25,7 @@ The AI assistant communicates with this server, which then uses AppleScript to i
 If you're using [Claude Code](https://claude.com/product/claude-code) (in Terminal or VS Code), just ask Claude to install it:
 
 ```
-Install the apple-notes-mcp MCP server so you can help me manage my Apple Notes
+Install the sweetrb/apple-notes-mcp MCP server so you can help me manage my Apple Notes
 ```
 
 Claude will handle the installation and configuration automatically.
@@ -45,7 +45,7 @@ This method also installs a **skill** that teaches Claude when and how to use Ap
 
 **1. Install the server:**
 ```bash
-npm install -g apple-notes-mcp
+npm install -g github:sweetrb/apple-notes-mcp
 ```
 
 **2. Add to Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
@@ -86,6 +86,7 @@ On first use, macOS will ask for permission to automate Notes.app. Click "OK" to
 | **Folder Management** | Create, list, and delete folders |
 | **Multi-Account** | Work with iCloud, Gmail, Exchange, or any configured account |
 | **Batch Operations** | Delete or move multiple notes at once |
+| **Checklist State** | Read checklist done/undone state directly from the Notes database |
 | **Export** | Export all notes as JSON or get individual notes as Markdown |
 | **Attachments** | List attachments in notes |
 | **Sync Awareness** | Detect iCloud sync in progress, warn about incomplete results |
@@ -109,6 +110,7 @@ Creates a new note in Apple Notes.
 | `title` | string | Yes | The title of the note (becomes first line) |
 | `content` | string | Yes | The body content of the note |
 | `tags` | string[] | No | Tags for organization (stored in metadata) |
+| `format` | string | No | Content format: `"plaintext"` (default) or `"html"`. When `"html"`, content is used as raw HTML for rich formatting |
 
 **Example:**
 ```json
@@ -119,6 +121,15 @@ Creates a new note in Apple Notes.
 }
 ```
 
+**Example - HTML formatting:**
+```json
+{
+  "title": "Status Report",
+  "content": "<h1>Status Report</h1><h2>Summary</h2><p>All tasks <b>on track</b>.</p><ul><li>Feature A: complete</li><li>Feature B: in progress</li></ul>",
+  "format": "html"
+}
+```
+
 **Returns:** Confirmation message with note title and ID. Save the ID for subsequent operations like `update-note`, `delete-note`, etc.
 
 ---
@@ -233,9 +244,10 @@ Updates an existing note's content and/or title.
 |-----------|------|----------|-------------|
 | `id` | string | No | Note ID (preferred - more reliable than title) |
 | `title` | string | No | Current title of the note to update (use `id` instead when available) |
-| `newTitle` | string | No | New title (if changing the title) |
+| `newTitle` | string | No | New title (if changing the title; ignored when `format` is `"html"`) |
 | `newContent` | string | Yes | New content for the note body |
 | `account` | string | No | Account containing the note (defaults to iCloud, ignored if `id` is provided) |
+| `format` | string | No | Content format: `"plaintext"` (default) or `"html"`. When `"html"`, content replaces the entire note body as raw HTML and `newTitle` is ignored (the first HTML element serves as the title) |
 
 **Note:** Either `id` or `title` must be provided. Using `id` is recommended.
 
@@ -264,6 +276,15 @@ Updates an existing note's content and/or title.
 }
 ```
 
+**Example - Update with HTML formatting:**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456",
+  "newContent": "<h1>Updated Report</h1><p>New findings with <b>bold</b> emphasis.</p><pre><code>console.log('hello');</code></pre>",
+  "format": "html"
+}
+```
+
 **Returns:** Confirmation message, or error if note not found.
 
 ---
@@ -476,7 +497,7 @@ Exports all notes as a JSON structure.
 
 #### `get-note-markdown`
 
-Gets a note's content as Markdown instead of HTML.
+Gets a note's content as Markdown instead of HTML. If the note contains checklists and Full Disk Access is granted, checklist items are automatically annotated with `[x]` (done) or `[ ]` (undone).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -484,7 +505,35 @@ Gets a note's content as Markdown instead of HTML.
 | `title` | string | No | Note title |
 | `account` | string | No | Account containing the note |
 
-**Returns:** Note content converted to Markdown format.
+**Returns:** Note content converted to Markdown format. Checklist items include `[x]`/`[ ]` prefixes when database access is available.
+
+---
+
+#### `get-checklist-state`
+
+Reads checklist done/undone state for a note. This bypasses the AppleScript limitation where `body of note` strips checklist state, by reading directly from the NoteStore SQLite database.
+
+**Requires:** Full Disk Access for the MCP host process (see [Full Disk Access Setup](#full-disk-access-for-checklist-features)).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Note ID (use `search-notes` to find it first) |
+
+**Example:**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456"
+}
+```
+
+**Returns:** Checklist items with done/undone state and progress count:
+```
+Checklist for "Shopping List" (2/4 done):
+[x] Buy milk
+[x] Get bread
+[ ] Pick up laundry
+[ ] Call dentist
+```
 
 ---
 
@@ -595,7 +644,7 @@ AI: [calls move-note with title="Old Meeting Notes", folder="Archive"]
 ### npm (Recommended)
 
 ```bash
-npm install -g apple-notes-mcp
+npm install -g github:sweetrb/apple-notes-mcp
 ```
 
 ### From Source
@@ -621,6 +670,30 @@ If installed from source, use this configuration:
 
 ---
 
+## Full Disk Access for Checklist Features
+
+The `get-checklist-state` tool and checklist annotations in `get-note-markdown` read directly from the Apple Notes SQLite database. This requires **Full Disk Access** for the process running the MCP server.
+
+### How to Grant Full Disk Access
+
+1. Open **System Settings** (or System Preferences on older macOS)
+2. Go to **Privacy & Security > Full Disk Access**
+3. Click the **+** button
+4. Add the application that hosts the MCP server:
+   - **Claude Desktop**: Add `/Applications/Claude.app`
+   - **Terminal**: Add `/Applications/Utilities/Terminal.app`
+   - **VS Code**: Add `/Applications/Visual Studio Code.app`
+   - **iTerm**: Add `/Applications/iTerm.app`
+5. Restart the application after granting access
+
+### Without Full Disk Access
+
+All other tools work normally without Full Disk Access. Only checklist state features are affected:
+- `get-checklist-state` will return an error explaining that database access is needed
+- `get-note-markdown` will return plain list items without `[x]`/`[ ]` annotations (graceful fallback)
+
+---
+
 ## Security and Privacy
 
 - **Local only** - All operations happen locally via AppleScript. No data is sent to external servers.
@@ -637,8 +710,9 @@ If installed from source, use this configuration:
 | macOS only | Apple Notes and AppleScript are macOS-specific |
 | No attachment content | Attachments can be listed but not downloaded via AppleScript |
 | No pinned notes | Pin status is not exposed via AppleScript |
-| No rich formatting | Content is HTML; complex formatting may not render |
+| 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 |
 
 ### Backslash Escaping (Important for AI Agents)
 
@@ -717,3 +791,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 ## Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Related Projects
+
+- [apple-mail-mcp](https://github.com/sweetrb/apple-mail-mcp) - MCP server for Apple Mail

package/build/index.js

@@ -25,6 +25,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { AppleNotesManager } from "./services/appleNotesManager.js";
 import { getSyncStatus, withSyncAwarenessSync } from "./utils/syncDetection.js";
+import { getChecklistItems, hasFullDiskAccess } from "./utils/checklistParser.js";
 // Read version from package.json to keep it in sync
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
@@ -112,9 +113,14 @@ const folderNameSchema = {
 server.tool("create-note", {
     title: z.string().min(1, "Title is required"),
     content: z.string().min(1, "Content is required"),
+    format: z
+        .enum(["plaintext", "html"])
+        .optional()
+        .default("plaintext")
+        .describe("Content format: 'plaintext' (default) or 'html' for rich formatting"),
     tags: z.array(z.string()).optional().describe("Tags for organization"),
-}, withErrorHandling(({ title, content, tags = [] }) => {
-    const note = notesManager.createNote(title, content, tags);
+}, withErrorHandling(({ title, content, format = "plaintext", tags = [] }) => {
+    const note = notesManager.createNote(title, content, tags, undefined, undefined, format);
     if (!note) {
         return errorResponse(`Failed to create note "${title}". Check that Notes.app is configured and accessible.`);
     }
@@ -244,11 +250,16 @@ server.tool("update-note", {
     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"),
+    format: z
+        .enum(["plaintext", "html"])
+        .optional()
+        .default("plaintext")
+        .describe("Content format: 'plaintext' (default) or 'html' for rich formatting"),
     account: z
         .string()
         .optional()
         .describe("Account containing the note (ignored if id is provided)"),
-}, withErrorHandling(({ id, title, newTitle, newContent, account }) => {
+}, withErrorHandling(({ id, title, newTitle, newContent, format = "plaintext", account }) => {
     // Prefer ID-based update if provided
     if (id) {
         // Check for password protection first for better error message
@@ -259,7 +270,7 @@ server.tool("update-note", {
         if (note.passwordProtected) {
             return errorResponse(`Note "${note.title}" is password-protected and cannot be updated. Unlock it in Notes.app first.`);
         }
-        const success = notesManager.updateNoteById(id, newTitle, newContent);
+        const success = notesManager.updateNoteById(id, newTitle, newContent, format);
         if (!success) {
             return errorResponse(`Failed to update note "${note.title}"`);
         }
@@ -282,7 +293,7 @@ server.tool("update-note", {
     if (note.passwordProtected) {
         return errorResponse(`Note "${title}" is password-protected and cannot be updated. Unlock it in Notes.app first.`);
     }
-    const success = notesManager.updateNote(title, newTitle, newContent, account);
+    const success = notesManager.updateNote(title, newTitle, newContent, account, format);
     if (!success) {
         return errorResponse(`Failed to update note "${title}"`);
     }
@@ -509,7 +520,12 @@ server.tool("health-check", {}, withErrorHandling(() => {
         return `  ${icon} ${c.name}: ${c.message}`;
     })
         .join("\n");
-    return successResponse(`${statusIcon} ${statusText}\n\n${checkLines}`);
+    // Check Full Disk Access for checklist features
+    const fdaAvailable = hasFullDiskAccess();
+    const fdaLine = fdaAvailable
+        ? "  ✓ full_disk_access: Granted (checklist features available)"
+        : "  ⓘ full_disk_access: Not granted (optional — needed for get-checklist-state and checklist annotations in get-note-markdown). Grant in System Settings > Privacy & Security > Full Disk Access.";
+    return successResponse(`${statusIcon} ${statusText}\n\n${checkLines}\n${fdaLine}`);
 }, "Error running health check"));
 // --- get-notes-stats ---
 server.tool("get-notes-stats", {}, withErrorHandling(() => {
@@ -662,6 +678,28 @@ server.tool("get-note-markdown", {
     }
     return successResponse(markdown);
 }, "Error getting note as markdown"));
+// --- get-checklist-state ---
+server.tool("get-checklist-state", {
+    id: z.string().min(1, "Note ID is required. Use search-notes to find the note ID first."),
+}, withErrorHandling(({ id }) => {
+    // Verify the note exists and is accessible
+    const note = notesManager.getNoteById(id);
+    if (!note) {
+        return errorResponse(`Note with ID "${id}" not found`);
+    }
+    if (note.passwordProtected) {
+        return errorResponse(`Note "${note.title}" is password-protected and cannot be read. Unlock it in Notes.app first.`);
+    }
+    const result = getChecklistItems(id);
+    if (!result.items) {
+        return errorResponse(result.message || "Failed to read checklist state.");
+    }
+    const summary = result.items
+        .map((item) => `${item.done ? "[x]" : "[ ]"} ${item.text}`)
+        .join("\n");
+    const checked = result.items.filter((i) => i.done).length;
+    return successResponse(`Checklist for "${note.title}" (${checked}/${result.items.length} done):\n${summary}`);
+}, "Error reading checklist state"));
 // =============================================================================
 // Server Startup
 // =============================================================================

package/build/services/appleNotesManager.js

@@ -15,6 +15,7 @@
  * @module services/appleNotesManager
  */
 import { executeAppleScript } from "../utils/applescript.js";
+import { getChecklistItems } from "../utils/checklistParser.js";
 import TurndownService from "turndown";
 // =============================================================================
 // Text Processing Utilities
@@ -353,10 +354,11 @@ export class AppleNotesManager {
      * to the account's default location.
      *
      * @param title - Display title for the note
-     * @param content - Body content (plain text, will be HTML-escaped)
+     * @param content - Body content (plain text that will be HTML-escaped, or raw HTML when format is "html")
      * @param tags - Optional tags (stored in returned object, not used by Notes.app)
      * @param folder - Optional folder name to create the note in
      * @param account - Account to use (defaults to iCloud)
+     * @param format - Content format: "plaintext" escapes and wraps in div tags (default), "html" uses content as-is
      * @returns Created Note object with metadata, or null on failure
      *
      * @example
@@ -369,13 +371,17 @@ export class AppleNotesManager {
      *
      * // Create in a different account
      * const gmail = manager.createNote("Draft", "...", [], undefined, "Gmail");
+     *
+     * // Create with HTML formatting
+     * const html = manager.createNote("Report", "<h1>Report</h1><p>Details here</p>",
+     *   [], undefined, undefined, "html");
      * ```
      */
-    createNote(title, content, tags = [], folder, account) {
+    createNote(title, content, tags = [], folder, account, format = "plaintext") {
         const targetAccount = this.resolveAccount(account);
         // Escape content for AppleScript embedding
         const safeTitle = escapeForAppleScript(title);
-        const safeContent = escapeForAppleScript(content);
+        const safeContent = format === "html" ? escapeHtmlForAppleScript(content) : 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
@@ -690,25 +696,35 @@ export class AppleNotesManager {
      * so updating content also allows title changes. If newTitle is
      * not provided, the original title is preserved.
      *
+     * When format is 'html', newTitle is ignored — the caller must include
+     * the title in the HTML content.
+     *
      * Note: Password-protected notes will fail with an AppleScript error.
      * Callers should check for password protection beforehand using
      * getNoteDetails() or isNotePasswordProtected().
      *
      * @param title - Current title of the note to update
-     * @param newTitle - New title (optional, keeps existing if not provided)
+     * @param newTitle - New title (optional, keeps existing if not provided; ignored in html format)
      * @param newContent - New content for the note body
      * @param account - Account containing the note (defaults to iCloud)
+     * @param format - Content format: "plaintext" wraps in div tags (default), "html" uses content as-is
      * @returns true if update succeeded, false otherwise
      */
-    updateNote(title, newTitle, newContent, account) {
+    updateNote(title, newTitle, newContent, account, format = "plaintext") {
         const targetAccount = this.resolveAccount(account);
         const safeCurrentTitle = escapeForAppleScript(title);
-        // Determine the effective title (new or keep existing)
-        const effectiveTitle = newTitle || 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>`;
+        let fullBody;
+        if (format === "html") {
+            // HTML mode: content is the complete body, escaped only for AppleScript string
+            fullBody = escapeHtmlForAppleScript(newContent);
+        }
+        else {
+            // Plaintext mode: wrap title + content in <div> tags (existing behavior)
+            const effectiveTitle = newTitle || title;
+            const safeEffectiveTitle = escapeForAppleScript(effectiveTitle);
+            const safeContent = escapeForAppleScript(newContent);
+            fullBody = `<div>${safeEffectiveTitle}</div><div>${safeContent}</div>`;
+        }
         const updateCommand = `set body of note "${safeCurrentTitle}" to "${fullBody}"`;
         const script = buildAccountScopedScript({ account: targetAccount }, updateCommand);
         const result = executeAppleScript(script);
@@ -724,30 +740,41 @@ export class AppleNotesManager {
      * This is more reliable than updateNote() because IDs are unique,
      * while titles can be duplicated.
      *
+     * When format is 'html', newTitle is ignored — the caller must include
+     * the title in the HTML content.
+     *
      * Note: Password-protected notes will fail with an AppleScript error.
      * Callers should check for password protection beforehand using
      * getNoteById() or isNotePasswordProtectedById().
      *
      * @param id - CoreData URL identifier for the note
-     * @param newTitle - New title (optional, keeps existing if not provided)
+     * @param newTitle - New title (optional, keeps existing if not provided; ignored in html format)
      * @param newContent - New content for the note body
+     * @param format - Content format: "plaintext" wraps in div tags (default), "html" uses content as-is
      * @returns true if update succeeded, false otherwise
      */
-    updateNoteById(id, newTitle, newContent) {
-        // Get the note to retrieve current title if newTitle 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;
+    updateNoteById(id, newTitle, newContent, format = "plaintext") {
+        let fullBody;
+        if (format === "html") {
+            // HTML mode: content is the complete body, escaped only for AppleScript string
+            fullBody = escapeHtmlForAppleScript(newContent);
+        }
+        else {
+            // Plaintext mode: wrap title + content in <div> tags (existing behavior)
+            // Get the note to retrieve current title if newTitle 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;
             }
-            effectiveTitle = note.title;
+            const safeEffectiveTitle = escapeForAppleScript(effectiveTitle);
+            const safeContent = escapeForAppleScript(newContent);
+            fullBody = `<div>${safeEffectiveTitle}</div><div>${safeContent}</div>`;
         }
-        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);
@@ -1585,9 +1612,52 @@ export class AppleNotesManager {
         this.initTurndownService();
         return this.turndownService.turndown(html).trim();
     }
+    /**
+     * Enriches markdown with checklist state from the NoteStore database.
+     *
+     * Apple Notes checklists appear as plain list items in the AppleScript HTML
+     * output. This method reads the protobuf data to get done/undone state and
+     * annotates matching list items with [x] or [ ] prefixes.
+     *
+     * Fails silently (returns original markdown) if the database is inaccessible
+     * or the note has no checklists.
+     *
+     * @param markdown - The base markdown content
+     * @param checklistItems - Checklist items with done state
+     * @returns Markdown with checklist annotations
+     */
+    enrichMarkdownWithChecklists(markdown, checklistItems) {
+        if (checklistItems.length === 0)
+            return markdown;
+        // Build a map of checklist text → done state
+        const checklistMap = new Map();
+        for (const item of checklistItems) {
+            checklistMap.set(item.text.trim(), item.done);
+        }
+        // Replace matching list items with checkbox syntax
+        const lines = markdown.split("\n");
+        const enriched = lines.map((line) => {
+            // Match markdown list items: "- text" or "* text"
+            const listMatch = line.match(/^(\s*[-*])\s+(.+)$/);
+            if (!listMatch)
+                return line;
+            const [, prefix, text] = listMatch;
+            const done = checklistMap.get(text.trim());
+            if (done === undefined)
+                return line;
+            // Remove from map so duplicate text lines aren't all converted
+            checklistMap.delete(text.trim());
+            return `${prefix} ${done ? "[x]" : "[ ]"} ${text}`;
+        });
+        return enriched.join("\n");
+    }
     /**
      * Gets note content as Markdown by title.
      *
+     * If the note contains checklists and the NoteStore database is accessible
+     * (Full Disk Access required), checklist items will be annotated with
+     * [x] (done) or [ ] (undone) prefixes.
+     *
      * @param title - Exact title of the note
      * @param account - Account containing the note (defaults to iCloud)
      * @returns Markdown content, or empty string if not found
@@ -1595,14 +1665,23 @@ export class AppleNotesManager {
      * @example
      * ```typescript
      * const md = manager.getNoteMarkdown("Shopping List");
-     * console.log(md); // "# Shopping List\n\n- Eggs\n- Milk"
+     * console.log(md); // "# Shopping List\n\n- [x] Eggs\n- [ ] Milk"
      * ```
      */
     getNoteMarkdown(title, account) {
         const html = this.getNoteContent(title, account);
         if (!html)
             return "";
-        return this.htmlToMarkdown(html);
+        let markdown = this.htmlToMarkdown(html);
+        // Try to enrich with checklist state (requires note ID)
+        const note = this.getNoteDetails(title, account);
+        if (note?.id) {
+            const result = getChecklistItems(note.id);
+            if (result.items) {
+                markdown = this.enrichMarkdownWithChecklists(markdown, result.items);
+            }
+        }
+        return markdown;
     }
     /**
      * Gets note content as Markdown by ID.
@@ -1610,6 +1689,10 @@ export class AppleNotesManager {
      * This is more reliable than getNoteMarkdown() because IDs are unique
      * across all accounts, while titles can be duplicated.
      *
+     * If the note contains checklists and the NoteStore database is accessible
+     * (Full Disk Access required), checklist items will be annotated with
+     * [x] (done) or [ ] (undone) prefixes.
+     *
      * @param id - CoreData URL identifier for the note
      * @returns Markdown content, or empty string if not found
      */
@@ -1617,6 +1700,12 @@ export class AppleNotesManager {
         const html = this.getNoteContentById(id);
         if (!html)
             return "";
-        return this.htmlToMarkdown(html);
+        let markdown = this.htmlToMarkdown(html);
+        // Try to enrich with checklist state
+        const result = getChecklistItems(id);
+        if (result.items) {
+            markdown = this.enrichMarkdownWithChecklists(markdown, result.items);
+        }
+        return markdown;
     }
 }