apple-notes-mcp 1.2.1 → 1.2.17

package/README.md

@@ -85,6 +85,12 @@ On first use, macOS will ask for permission to automate Notes.app. Click "OK" to
 | **Move Notes** | Organize notes into folders |
 | **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 |
+| **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 |
+| **Collaboration** | Detect shared notes, warn before modifying |
+| **Diagnostics** | Health check, sync status, and statistics tools |
 
 ---
 
@@ -113,7 +119,7 @@ Creates a new note in Apple Notes.
 }
 ```
 
-**Returns:** Confirmation message with note title, or error if creation failed.
+**Returns:** Confirmation message with note title and ID. Save the ID for subsequent operations like `update-note`, `delete-note`, etc.
 
 ---
 
@@ -142,7 +148,7 @@ Searches for notes by title or content.
 }
 ```
 
-**Returns:** List of matching note titles, or message if no matches found.
+**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.
 
 ---
 
@@ -152,10 +158,20 @@ Retrieves the full content of a specific note.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `title` | string | Yes | Exact title of the note to retrieve |
-| `account` | string | No | Account containing the note (defaults to iCloud) |
+| `id` | string | No | Note ID (preferred - more reliable than title) |
+| `title` | string | No | Note title (use `id` instead when available) |
+| `account` | string | No | Account containing the note (defaults to iCloud, ignored if `id` is provided) |
 
-**Example:**
+**Note:** Either `id` or `title` must be provided. Using `id` is recommended as it's unique and avoids issues with duplicate titles.
+
+**Example - Using ID (recommended):**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456"
+}
+```
+
+**Example - Using title:**
 ```json
 {
   "title": "Shopping List"
@@ -215,10 +231,21 @@ Updates an existing note's content and/or title.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `title` | string | Yes | Current title of the note to update |
+| `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) |
 | `newContent` | string | Yes | New content for the note body |
-| `account` | string | No | Account containing the note (defaults to iCloud) |
+| `account` | string | No | Account containing the note (defaults to iCloud, ignored if `id` is provided) |
+
+**Note:** Either `id` or `title` must be provided. Using `id` is recommended.
+
+**Example - Using ID (recommended):**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456",
+  "newContent": "Updated content here"
+}
+```
 
 **Example - Update content only:**
 ```json
@@ -247,10 +274,20 @@ Deletes a note (moves to Recently Deleted in Notes.app).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `title` | string | Yes | Exact title of the note to delete |
-| `account` | string | No | Account containing the note (defaults to iCloud) |
+| `id` | string | No | Note ID (preferred - more reliable than title) |
+| `title` | string | No | Exact title of the note to delete (use `id` instead when available) |
+| `account` | string | No | Account containing the note (defaults to iCloud, ignored if `id` is provided) |
 
-**Example:**
+**Note:** Either `id` or `title` must be provided. Using `id` is recommended.
+
+**Example - Using ID (recommended):**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456"
+}
+```
+
+**Example - Using title:**
 ```json
 {
   "title": "Old Draft"
@@ -267,11 +304,22 @@ Moves a note to a different folder.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `title` | string | Yes | Title of the note to move |
+| `id` | string | No | Note ID (preferred - more reliable than title) |
+| `title` | string | No | Title of the note to move (use `id` instead when available) |
 | `folder` | string | Yes | Name of the destination folder |
-| `account` | string | No | Account containing the note (defaults to iCloud) |
+| `account` | string | No | Account containing the note (defaults to iCloud, ignored if `id` is provided) |
 
-**Example:**
+**Note:** Either `id` or `title` must be provided. Using `id` is recommended.
+
+**Example - Using ID (recommended):**
+```json
+{
+  "id": "x-coredata://ABC123/ICNote/p456",
+  "folder": "Archive"
+}
+```
+
+**Example - Using title:**
 ```json
 {
   "title": "Completed Task",
@@ -386,6 +434,116 @@ Lists all configured Notes accounts.
 
 ---
 
+### Batch Operations
+
+#### `batch-delete-notes`
+
+Deletes multiple notes at once by ID.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ids` | string[] | Yes | Array of note IDs to delete |
+
+**Returns:** Summary of successes and failures.
+
+---
+
+#### `batch-move-notes`
+
+Moves multiple notes to a folder.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ids` | string[] | Yes | Array of note IDs to move |
+| `folder` | string | Yes | Destination folder name |
+| `account` | string | No | Account containing the folder |
+
+**Returns:** Summary of successes and failures.
+
+---
+
+### Export Operations
+
+#### `export-notes-json`
+
+Exports all notes as a JSON structure.
+
+**Parameters:** None
+
+**Returns:** Complete JSON export with all accounts, folders, and notes including metadata.
+
+---
+
+#### `get-note-markdown`
+
+Gets a note's content as Markdown instead of HTML.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | No | Note ID (preferred) |
+| `title` | string | No | Note title |
+| `account` | string | No | Account containing the note |
+
+**Returns:** Note content converted to Markdown format.
+
+---
+
+#### `list-attachments`
+
+Lists attachments in a note.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | No | Note ID (preferred) |
+| `title` | string | No | Note title |
+| `account` | string | No | Account containing the note |
+
+**Returns:** List of attachments with names and content types.
+
+---
+
+### Diagnostics
+
+#### `health-check`
+
+Verifies Notes.app connectivity and permissions.
+
+**Parameters:** None
+
+**Returns:** Status of all health checks (app installed, permissions, account access).
+
+---
+
+#### `get-notes-stats`
+
+Gets comprehensive statistics about your notes.
+
+**Parameters:** None
+
+**Returns:** Total counts, per-account breakdown, folder statistics, and recently modified counts.
+
+---
+
+#### `get-sync-status`
+
+Checks iCloud sync status.
+
+**Parameters:** None
+
+**Returns:** Whether sync is active, pending uploads, and last activity time.
+
+---
+
+#### `list-shared-notes`
+
+Lists all notes shared with collaborators.
+
+**Parameters:** None
+
+**Returns:** List of shared notes with warnings about collaboration.
+
+---
+
 ## Usage Patterns
 
 ### Basic Workflow
@@ -443,8 +601,8 @@ npm install -g apple-notes-mcp
 ### From Source
 
 ```bash
-git clone https://github.com/sweetrb/mcp-apple-notes.git
-cd mcp-apple-notes
+git clone https://github.com/sweetrb/apple-notes-mcp.git
+cd apple-notes-mcp
 npm install
 npm run build
 ```
@@ -455,7 +613,7 @@ If installed from source, use this configuration:
   "mcpServers": {
     "apple-notes": {
       "command": "node",
-      "args": ["/path/to/mcp-apple-notes/build/index.js"]
+      "args": ["/path/to/apple-notes-mcp/build/index.js"]
     }
   }
 }
@@ -477,7 +635,7 @@ If installed from source, use this configuration:
 | Limitation | Reason |
 |------------|--------|
 | macOS only | Apple Notes and AppleScript are macOS-specific |
-| No attachments | AppleScript cannot access note attachments |
+| 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 |
 | Title matching | Most operations require exact title matches |
@@ -536,7 +694,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 (121 tests)
+npm test         # Run test suite (217 tests)
 npm run lint     # Check code style
 npm run format   # Format code
 ```