apple-notes-mcp 2.1.0 → 2.1.1

package/README.md

@@ -6,6 +6,10 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that e
 [![CI](https://github.com/sweetrb/apple-notes-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sweetrb/apple-notes-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<p align="center">
+  <img src="codex/assets/screenshot.png" alt="Apple Notes MCP — create, search, and organize Apple Notes from Codex, Claude, and other AI assistants" width="680">
+</p>
+
 ## What is This?
 
 This server acts as a bridge between AI assistants and Apple Notes. Once configured, you can ask Claude (or any MCP-compatible AI) to:
@@ -52,6 +56,10 @@ codex plugin add apple-notes@apple-notes-mcp
 
 The Codex plugin runs the published `apple-notes-mcp` server through `npx` and ships the same Apple Notes skill, so behavior matches the Claude Code plugin.
 
+### Other Hosts (Hermes, Antigravity)
+
+Plugin packaging for the Hermes and Antigravity hosts is also included (`.hermes-plugin/` and `.antigravity-plugin/`). Each registers the same `apple-notes` MCP server (launched via `npx -y apple-notes-mcp`) and bundles the Apple Notes skill, so behavior matches the Claude Code and Codex plugins. Install them through each host's plugin/marketplace mechanism pointed at this repository.
+
 ### Manual Installation
 
 **1. Install the server:**
@@ -345,6 +353,8 @@ Updates an existing note's content and/or title.
 
 **Returns:** Confirmation message, or error if note not found.
 
+**Note:** `newContent` **replaces the entire note body** — it is not appended. To preserve existing content, read it first (e.g. with `get-note-content`) and include it in `newContent`.
+
 ---
 
 #### `delete-note`
@@ -375,6 +385,8 @@ Deletes a note (moves to Recently Deleted in Notes.app).
 
 **Returns:** Confirmation message, or error if note not found.
 
+**⚠️ Safety:** Irreversible from the agent's side — requires explicit user confirmation before calling. Prefer `search-notes` / `list-notes` first to confirm the exact id(s) being deleted.
+
 ---
 
 #### `move-note`
@@ -504,6 +516,8 @@ Deletes a folder.
 
 **Returns:** Confirmation message, or error if folder not found or not empty.
 
+**⚠️ Safety:** Irreversible — requires explicit user confirmation before calling. Prefer `list-folders` first to confirm the exact folder path being deleted.
+
 ---
 
 ### Account Operations
@@ -535,6 +549,8 @@ Deletes multiple notes at once by ID.
 
 **Returns:** Summary of successes and failures.
 
+**⚠️ Safety:** Irreversible — requires explicit user confirmation before calling. Prefer `search-notes` / `list-notes` first to confirm the exact ids being deleted.
+
 ---
 
 #### `batch-move-notes`
@@ -676,6 +692,8 @@ Gets comprehensive statistics about your notes.
 
 **Returns:** Total counts, per-account breakdown, folder statistics, and recently modified counts.
 
+The `structuredContent` also includes a `coverage` object — `{ complete, scanned, covered, warnings[] }`. If `complete` is `false`, one or more accounts (or the recent-activity scan) could not be read and the counts reflect only the scopes that succeeded; the text output adds a "⚠️ Partial results" line. This lets you tell a genuinely empty library apart from a partial failure.
+
 ---
 
 #### `get-sync-status`
@@ -1005,6 +1023,12 @@ 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-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
+Part of a family of macOS MCP servers:
+
+- [apple-mail-mcp](https://github.com/sweetrb/apple-mail-mcp) — MCP server for Apple Mail (read, search, send, and organize email)
+- [apple-numbers-mcp](https://github.com/sweetrb/apple-numbers-mcp) — MCP server for Apple Numbers (read and write .numbers spreadsheets)
+- [apple-photos-mcp](https://github.com/sweetrb/apple-photos-mcp) — MCP server for Apple Photos (query metadata and export originals)
+
+## Recurring macOS permission prompts
+
+If macOS keeps re-prompting for Full Disk Access or Automation for `node` (often after a `brew upgrade`), see [docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md](docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md) — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.

package/build/index.js

@@ -108,7 +108,7 @@ const folderNameSchema = {
 // Note Tools
 // =============================================================================
 // --- create-note ---
-server.tool("create-note", {
+server.tool("create-note", "Use when: the user wants to create a brand-new Apple Note.\nReturns: the new note's title and id — reuse the id for follow-up reads/edits.\nDo not use when: editing an existing note (use update-note).\nNote: the title is prepended as an <h1>; true Apple Notes checklists cannot be created via AppleScript (see the content field).", {
     title: z.string().min(1, "Title is required"),
     content: z
         .string()
@@ -134,7 +134,7 @@ server.tool("create-note", {
     return successResponse(`Note created: "${note.title}" [id: ${note.id}]${checklistWarning}`);
 }, "Error creating note"));
 // --- search-notes ---
-server.tool("search-notes", {
+server.tool("search-notes", "Use when: finding notes by a keyword in the title (or body with searchContent=true) and you need their ids.\nReturns: matching notes with title, folder, and id.\nDo not use when: you already have a note id (use get-note-content) or want every note (use list-notes).\nPrefer this first to obtain ids for subsequent read/update/delete/move calls.", {
     query: z.string().min(1, "Search query is required"),
     searchContent: z.boolean().optional().describe("Search note content instead of titles"),
     account: z.string().optional().describe("Account to search in"),
@@ -179,7 +179,7 @@ server.tool("search-notes", {
     return successResponse(`Found ${notes.length} notes (searched ${searchType}${folderInfo}${dateInfo}${limitInfo}):\n${noteList}${syncNote}`, { notes, count: notes.length });
 }, "Error searching notes"));
 // --- get-note-content ---
-server.tool("get-note-content", {
+server.tool("get-note-content", "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the note's content plus parsed hashtags.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     account: z
@@ -224,7 +224,7 @@ server.tool("get-note-content", {
     return successResponse(content, { title, content, hashtags });
 }, "Error retrieving note content"));
 // --- get-note-by-id ---
-server.tool("get-note-by-id", {
+server.tool("get-note-by-id", "Use when: you have a note id and need its metadata only.\nReturns: id, title, created, modified, shared, passwordProtected.\nDo not use when: you need the body text (get-note-content) or only have a title (get-note-details).", {
     id: z.string().min(1, "Note ID is required"),
 }, withErrorHandling(({ id }) => {
     const note = notesManager.getNoteById(id);
@@ -243,7 +243,7 @@ server.tool("get-note-by-id", {
     return successResponse(JSON.stringify(metadata, null, 2), metadata);
 }, "Error retrieving note"));
 // --- get-note-details ---
-server.tool("get-note-details", noteTitleSchema, withErrorHandling(({ title, account }) => {
+server.tool("get-note-details", "Use when: you have a note title (not an id) and need its metadata.\nReturns: id, title, created, modified, shared, passwordProtected, account.\nDo not use when: you have an id (get-note-by-id) or need the body text (get-note-content).\nUse the returned id for reliable follow-up operations.", noteTitleSchema, withErrorHandling(({ title, account }) => {
     const note = notesManager.getNoteDetails(title, account);
     if (!note) {
         return errorResponse(`Note "${title}" not found`);
@@ -261,7 +261,7 @@ server.tool("get-note-details", noteTitleSchema, withErrorHandling(({ title, acc
     return successResponse(JSON.stringify(metadata, null, 2), metadata);
 }, "Error retrieving note details"));
 // --- update-note ---
-server.tool("update-note", {
+server.tool("update-note", "Use when: changing the title and/or replacing the body of an existing note, by id (preferred) or title.\nReturns: confirmation; warns when the note is shared.\nDo not use when: creating a new note (create-note).\nSafety: newContent REPLACES the entire body — it does not append. Read the note first if you need to preserve existing text. Edits to shared notes are immediately visible to all collaborators.", {
     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"),
@@ -326,7 +326,7 @@ server.tool("update-note", {
     return successResponse(`Note updated: "${finalTitle}"${sharedWarning}${checklistWarning}`);
 }, "Error updating note"));
 // --- delete-note ---
-server.tool("delete-note", {
+server.tool("delete-note", "Use when: permanently deleting a single note, by id (preferred) or title.\nReturns: confirmation; warns when the note was shared.\nDo not use when: deleting many notes (batch-delete-notes) or just relocating one (move-note).\nSafety: requires explicit user confirmation before deleting. Prefer search-notes/list-notes first to show the affected note id and title. Deleting a shared note removes collaborator access.", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     account: z
@@ -371,7 +371,7 @@ server.tool("delete-note", {
     return successResponse(`Note deleted: "${title}"${sharedWarning}`);
 }, "Error deleting note"));
 // --- move-note ---
-server.tool("move-note", {
+server.tool("move-note", "Use when: moving one note to a different folder, by id (preferred) or title.\nReturns: confirmation of the note and destination folder.\nDo not use when: moving many notes (batch-move-notes).\nNote: implemented as copy-then-delete; the destination folder must already exist (create-folder).", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     folder: z.string().min(1, "Destination folder is required"),
@@ -406,7 +406,7 @@ server.tool("move-note", {
     return successResponse(`Note moved: "${title}" -> "${folder}"`);
 }, "Error moving note"));
 // --- list-notes ---
-server.tool("list-notes", {
+server.tool("list-notes", "Use when: enumerating notes in an account or folder; supports modifiedSince and limit for large collections.\nReturns: note titles only (no content or ids).\nDo not use when: you need content (get-note-content) or ids for follow-up edits (use search-notes).\nNote: warns if iCloud sync is active and results may be partial.", {
     account: z.string().optional().describe("Account to list notes from"),
     folder: z.string().optional().describe("Filter to specific folder"),
     modifiedSince: z
@@ -444,7 +444,7 @@ server.tool("list-notes", {
 // Folder Tools
 // =============================================================================
 // --- list-folders ---
-server.tool("list-folders", {
+server.tool("list-folders", "Use when: listing all folders, with full nested paths, for an account.\nReturns: folder names/paths.\nDo not use when: listing notes (list-notes).\nNote: warns if iCloud sync is active.", {
     account: z.string().optional().describe("Account to list folders from"),
 }, withErrorHandling(({ account }) => {
     // Use sync-aware wrapper for this read operation
@@ -469,7 +469,7 @@ server.tool("list-folders", {
     });
 }, "Error listing folders"));
 // --- create-folder ---
-server.tool("create-folder", {
+server.tool("create-folder", "Use when: creating a folder, including nested paths like 'Work/Clients' (intermediate folders are created, existing ones skipped).\nReturns: confirmation.\nDo not use when: creating a note (create-note).", {
     name: z
         .string()
         .min(1, "Folder name is required")
@@ -483,7 +483,7 @@ server.tool("create-folder", {
     return successResponse(`Folder created: "${folder.name}"`);
 }, "Error creating folder"));
 // --- delete-folder ---
-server.tool("delete-folder", folderNameSchema, withErrorHandling(({ name, account }) => {
+server.tool("delete-folder", "Use when: deleting an existing folder by name or nested path.\nReturns: confirmation.\nDo not use when: deleting a note (delete-note).\nSafety: requires explicit user confirmation. Deletion fails if the folder still contains notes — list or move those notes first.", folderNameSchema, withErrorHandling(({ name, account }) => {
     const success = notesManager.deleteFolder(name, account);
     if (!success) {
         return errorResponse(`Failed to delete folder "${name}". Folder may not exist or may contain notes.`);
@@ -494,7 +494,7 @@ server.tool("delete-folder", folderNameSchema, withErrorHandling(({ name, accoun
 // Account Tools
 // =============================================================================
 // --- list-accounts ---
-server.tool("list-accounts", {}, withErrorHandling(() => {
+server.tool("list-accounts", "Use when: discovering which Notes accounts exist (iCloud, Gmail, Exchange, etc.) before targeting one.\nReturns: account names.\nDo not use when: you already know the account, or are working by note id (ids are account-independent).", {}, withErrorHandling(() => {
     const accounts = notesManager.listAccounts();
     if (accounts.length === 0) {
         return successResponse("No Notes accounts found", { accounts: [], count: 0 });
@@ -509,7 +509,7 @@ server.tool("list-accounts", {}, withErrorHandling(() => {
 // Collaboration Tools
 // =============================================================================
 // --- list-shared-notes ---
-server.tool("list-shared-notes", {}, withErrorHandling(() => {
+server.tool("list-shared-notes", "Use when: finding notes shared with collaborators.\nReturns: shared notes with title, account, and id.\nDo not use when: searching all notes (search-notes).\nNote: edits or deletes to these notes affect all collaborators.", {}, withErrorHandling(() => {
     const sharedNotes = notesManager.listSharedNotes();
     if (sharedNotes.length === 0) {
         return successResponse("No shared notes found. You have no notes shared with collaborators.", { notes: [], count: 0 });
@@ -527,7 +527,7 @@ server.tool("list-shared-notes", {}, withErrorHandling(() => {
 // Diagnostics Tools
 // =============================================================================
 // --- get-sync-status ---
-server.tool("get-sync-status", {}, withErrorHandling(() => {
+server.tool("get-sync-status", "Use when: checking whether iCloud sync is in progress before trusting read results.\nReturns: sync active/idle, pending upload count, and seconds since last change.\nDo not use when: you need note data — this is a read-only diagnostics tool.", {}, withErrorHandling(() => {
     const status = getSyncStatus();
     if (status.error) {
         return successResponse(`⚠️ Sync status unknown: ${status.error}`, { ...status });
@@ -553,7 +553,7 @@ server.tool("get-sync-status", {}, withErrorHandling(() => {
     return successResponse(lines.join("\n"), { ...status });
 }, "Error checking sync status"));
 // --- health-check ---
-server.tool("health-check", {}, withErrorHandling(() => {
+server.tool("health-check", "Use when: a quick check that Notes.app is reachable and (optionally) Full Disk Access is granted for checklist features.\nReturns: pass/fail per check.\nDo not use when: you need detailed, actionable setup diagnostics (use doctor).\nRead-only.", {}, withErrorHandling(() => {
     const result = notesManager.healthCheck();
     const statusIcon = result.healthy ? "✓" : "✗";
     const statusText = result.healthy ? "All checks passed" : "Issues detected";
@@ -571,14 +571,14 @@ server.tool("health-check", {}, withErrorHandling(() => {
     return successResponse(`${statusIcon} ${statusText}\n\n${checkLines}\n${fdaLine}`);
 }, "Error running health check"));
 // --- doctor ---
-server.tool("doctor", {}, withErrorHandling(() => {
+server.tool("doctor", "Use when: diagnosing setup problems (Notes.app automation permission, account state, Full Disk Access) with actionable guidance.\nReturns: a detailed report plus structured fields.\nDo not use when: you just need a quick pass/fail (health-check).\nRead-only.", {}, withErrorHandling(() => {
     // Richer than health-check: Notes.app permission, account state, and Full
     // Disk Access with actionable messages + structuredContent (#22).
     const report = runDoctor(notesManager);
     return successResponse(formatDoctorReport(report), { ...report });
 }, "Error running doctor"));
 // --- get-notes-stats ---
-server.tool("get-notes-stats", {}, withErrorHandling(() => {
+server.tool("get-notes-stats", "Use when: summarizing the library — total notes, per-account/folder counts, and recent activity.\nReturns: aggregate statistics; flags partial coverage when some scopes were unreadable.\nDo not use when: you need individual notes (list-notes/search-notes).\nRead-only.", {}, withErrorHandling(() => {
     const stats = notesManager.getNotesStats();
     // Format the output
     const lines = [];
@@ -614,7 +614,7 @@ server.tool("get-notes-stats", {}, withErrorHandling(() => {
     return successResponse(lines.join("\n"), { ...stats });
 }, "Error getting notes statistics"));
 // --- list-attachments ---
-server.tool("list-attachments", {
+server.tool("list-attachments", "Use when: listing the attachments of one note, by id (preferred) or title.\nReturns: each attachment's name, content type, and id (use with save-attachment/fetch-attachment).\nDo not use when: you want the attachment bytes (fetch-attachment) or a file on disk (save-attachment).", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     account: z
@@ -654,7 +654,7 @@ server.tool("list-attachments", {
     return successResponse(`Found ${attachments.length} attachment(s) in "${title}":\n${attachmentList}`, { attachments, count: attachments.length });
 }, "Error listing attachments"));
 // --- batch-delete-notes ---
-server.tool("batch-delete-notes", {
+server.tool("batch-delete-notes", "Use when: permanently deleting multiple notes by id in one call.\nReturns: per-id success/failure counts.\nDo not use when: deleting a single note (delete-note).\nSafety: requires explicit user confirmation; this is destructive and not undoable. Prefer search-notes/list-notes first to confirm the exact ids being deleted.", {
     ids: z.array(z.string()).describe("Array of note IDs to delete"),
 }, withErrorHandling(({ ids }) => {
     if (ids.length === 0) {
@@ -673,7 +673,7 @@ server.tool("batch-delete-notes", {
     return succeeded > 0 ? successResponse(lines.join("\n")) : errorResponse(lines.join("\n"));
 }, "Error performing batch delete"));
 // --- batch-move-notes ---
-server.tool("batch-move-notes", {
+server.tool("batch-move-notes", "Use when: moving multiple notes by id into one destination folder.\nReturns: per-id success/failure counts.\nDo not use when: moving a single note (move-note).\nNote: the destination folder must already exist (create-folder).", {
     ids: z.array(z.string()).describe("Array of note IDs to move"),
     folder: z.string().describe("Destination folder name"),
     account: z
@@ -697,7 +697,7 @@ server.tool("batch-move-notes", {
     return succeeded > 0 ? successResponse(lines.join("\n")) : errorResponse(lines.join("\n"));
 }, "Error performing batch move"));
 // --- save-attachment ---
-server.tool("save-attachment", {
+server.tool("save-attachment", "Use when: writing one note attachment to a file on disk.\nReturns: the saved path.\nDo not use when: you want the bytes in-memory as base64 (fetch-attachment).\nSafety: writes a file; savePath must be absolute and under the home directory, a temp dir, or /Volumes. Get the ids from list-attachments first.", {
     noteId: z.string().min(1, "noteId is required").describe("CoreData note id (from search/list)"),
     attachmentId: z
         .string()
@@ -719,7 +719,7 @@ server.tool("save-attachment", {
     });
 }, "Error saving attachment"));
 // --- fetch-attachment ---
-server.tool("fetch-attachment", {
+server.tool("fetch-attachment", "Use when: retrieving one note attachment's bytes inline as base64 (no file written).\nReturns: name, content type, byte count, and base64 data.\nDo not use when: you want it saved to disk (save-attachment).\nNote: get the ids from list-attachments first.", {
     noteId: z.string().min(1, "noteId is required").describe("CoreData note id (from search/list)"),
     attachmentId: z
         .string()
@@ -733,7 +733,7 @@ server.tool("fetch-attachment", {
     return successResponse(`Fetched "${r.name ?? "attachment"}" (${r.contentType ?? "unknown type"}, ${r.bytes ?? 0} bytes) as base64.`, { name: r.name, contentType: r.contentType, bytes: r.bytes, base64: r.base64 });
 }, "Error fetching attachment"));
 // --- export-notes-json ---
-server.tool("export-notes-json", {}, withErrorHandling(() => {
+server.tool("export-notes-json", "Use when: exporting the entire notes library as structured JSON for backup or bulk processing.\nReturns: a summary plus the full JSON of all notes, folders, and accounts.\nDo not use when: you need a single note (get-note-content) — this reads everything and can be large.\nRead-only.", {}, withErrorHandling(() => {
     const exportData = notesManager.exportNotesAsJson();
     const { summary } = exportData;
     return {
@@ -751,7 +751,7 @@ server.tool("export-notes-json", {}, withErrorHandling(() => {
     };
 }, "Error exporting notes"));
 // --- get-note-markdown ---
-server.tool("get-note-markdown", {
+server.tool("get-note-markdown", "Use when: reading a note as Markdown, with checklist items annotated [x]/[ ] when Full Disk Access is granted.\nReturns: the note's Markdown.\nDo not use when: you need the raw HTML/plaintext body (get-note-content) or only metadata (get-note-details).\nNote: falls back to plain lists (no checkmarks) without Full Disk Access.", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     account: z
@@ -778,7 +778,7 @@ server.tool("get-note-markdown", {
     return successResponse(markdown, { markdown });
 }, "Error getting note as markdown"));
 // --- get-checklist-state ---
-server.tool("get-checklist-state", {
+server.tool("get-checklist-state", "Use when: reading the checked/unchecked state of a note's checklist items, by id.\nReturns: each item's text and done state plus checked/total counts.\nDo not use when: you only have a title (get the id via search-notes first) or want the full body text (get-note-content).\nNote: requires Full Disk Access; reads the NoteStore database directly.", {
     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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.1.0",
-  "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and Codex",
+  "version": "2.1.1",
+  "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -27,7 +27,7 @@
     "format": "prettier --write src",
     "format:check": "prettier --check src",
     "typecheck": "tsc --noEmit",
-    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .agents/plugins/marketplace.json codex/.codex-plugin/plugin.json",
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .hermes-plugin .antigravity-plugin",
     "prepublishOnly": "npm run lint && npm run test && npm run build",
     "prepare": "husky; npm run build"
   },
@@ -81,7 +81,7 @@
     "vitest": "^2.0.0"
   },
   "volta": {
-    "node": "22.13.1"
+    "node": "24.17.0"
   },
   "lint-staged": {
     "src/**/*.ts": [