apple-notes-mcp 1.2.18 → 1.3.0

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.
 
 ---
@@ -132,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
@@ -148,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.
 
 ---
@@ -233,9 +257,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 +289,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.
 
 ---
@@ -335,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
@@ -354,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.
 
 ---
@@ -476,7 +520,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 +528,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 +667,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 +693,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 +733,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 +814,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.`);
     }
@@ -126,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) {
@@ -141,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
@@ -156,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", {
@@ -244,11 +257,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 +277,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 +300,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}"`);
     }
@@ -377,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) {
@@ -393,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
@@ -509,7 +534,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 +692,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
 // =============================================================================