apple-notes-mcp 2.1.0 → 2.1.2

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:**
@@ -95,11 +103,12 @@ On first use, macOS will ask for permission to automate Notes.app. Click "OK" to
 | **Delete Notes** | Remove notes (moves to Recently Deleted) |
 | **Move Notes** | Organize notes into folders (supports nested paths) |
 | **Folder Management** | Create, list, and delete folders with full hierarchical path support |
-| **Multi-Account** | Work with iCloud, Gmail, Exchange, or any configured account |
+| **Multi-Account** | Work with iCloud, Gmail, Exchange, or any configured account, including account IDs and default folders |
 | **Batch Operations** | Delete or move multiple notes at once |
 | **Checklist State** | Read checklist done/undone state directly from the Notes database (requires Full Disk Access) |
 | **Export** | Export all notes as JSON or get individual notes as Markdown |
 | **Attachments** | List attachments, save them to disk, or fetch their bytes as base64 |
+| **Notes.app UI State** | Reveal a note in Notes.app or read the current Notes.app selection |
 | **Sync Awareness** | Detect iCloud sync in progress, warn about incomplete results |
 | **Collaboration** | Detect shared notes, warn before modifying |
 | **Diagnostics** | `health-check` plus a richer `doctor` (reachability, automation permission, accounts, Full Disk Access), sync status, and statistics |
@@ -294,6 +303,19 @@ Retrieves a note using its unique CoreData identifier.
 
 ---
 
+#### `show-note`
+
+Reveals a note in Notes.app using its unique CoreData identifier.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | The CoreData URL identifier (e.g., `x-coredata://...`) |
+| `separately` | boolean | No | Open in a separate note window when supported by Notes.app |
+
+**Returns:** Confirmation that Notes.app accepted the show command.
+
+---
+
 #### `update-note`
 
 Updates an existing note's content and/or title.
@@ -345,6 +367,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 +399,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`
@@ -447,6 +473,16 @@ Lists all notes, optionally filtered by folder, date, and limit.
 
 ---
 
+#### `get-selected-notes`
+
+Reads the currently selected note(s) from the Notes.app UI.
+
+**Parameters:** None
+
+**Returns:** Selected note metadata, including IDs for follow-up operations. Returns an empty list when Notes.app has no selected note.
+
+---
+
 ### Folder Operations
 
 #### `list-folders`
@@ -462,7 +498,7 @@ Lists all folders in an account with full hierarchical paths.
 {}
 ```
 
-**Returns:** List of folder paths. Nested folders are shown as full paths (e.g., `Work/Clients/Omnia`). Duplicate folder names are disambiguated by their full path. Literal slashes in folder names are escaped as `\/` (e.g., `Spain\/Portugal 2023`).
+**Returns:** List of folders with IDs, paths, account names, and shared state. Nested folders are shown as full paths (e.g., `Work/Clients/Omnia`). Duplicate folder names are disambiguated by their full path. Literal slashes in folder names are escaped as `\/` (e.g., `Spain\/Portugal 2023`).
 
 ---
 
@@ -504,6 +540,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
@@ -519,7 +557,17 @@ Lists all configured Notes accounts.
 {}
 ```
 
-**Returns:** List of account names (e.g., "iCloud", "Gmail", "Exchange").
+**Returns:** List of accounts with names, IDs, upgraded state, and default folder metadata.
+
+---
+
+#### `get-default-location`
+
+Returns the default account and folder Notes.app uses for newly created notes.
+
+**Parameters:** None
+
+**Returns:** Default account and folder metadata, including IDs and shared state.
 
 ---
 
@@ -535,6 +583,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`
@@ -615,7 +665,7 @@ Lists attachments in a note.
 | `title` | string | No | Note title |
 | `account` | string | No | Account containing the note |
 
-**Returns:** List of attachments with names and content types.
+**Returns:** List of attachments with IDs, names, content identifiers, URLs when available, created/modified dates, and shared state.
 
 ---
 
@@ -676,6 +726,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 +1057,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`);
@@ -260,8 +260,22 @@ server.tool("get-note-details", noteTitleSchema, withErrorHandling(({ title, acc
     };
     return successResponse(JSON.stringify(metadata, null, 2), metadata);
 }, "Error retrieving note details"));
+// --- show-note ---
+server.tool("show-note", "Use when: the user wants to reveal a known note in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need note content (get-note-content) or metadata (get-note-by-id).\nNote: this opens or focuses the Notes UI.", {
+    id: z.string().min(1, "Note ID is required"),
+    separately: z
+        .boolean()
+        .optional()
+        .describe("Open in a separate note window when supported by Notes.app"),
+}, withErrorHandling(({ id, separately = false }) => {
+    const success = notesManager.showNoteById(id, separately);
+    if (!success) {
+        return errorResponse(`Failed to show note with ID "${id}"`);
+    }
+    return successResponse(`Shown note with ID "${id}" in Notes.app`, { id, separately });
+}, "Error showing note"));
 // --- 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 +340,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 +385,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 +420,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
@@ -440,11 +454,23 @@ server.tool("list-notes", {
     const noteList = notes.map((t) => `  - ${t}`).join("\n");
     return successResponse(`Found ${notes.length} notes${location}${acct}${dateInfo}${limitInfo}:\n${noteList}${syncNote}`, { notes, count: notes.length });
 }, "Error listing notes"));
+// --- get-selected-notes ---
+server.tool("get-selected-notes", "Use when: the user asks what note(s) are currently selected in Notes.app.\nReturns: selected note metadata with ids for follow-up operations.\nDo not use when: searching all notes (search-notes) or listing a folder (list-notes).\nNote: reads Notes.app UI selection; it may be empty if Notes is closed or no note is selected.", {}, withErrorHandling(() => {
+    const notes = notesManager.getSelectedNotes();
+    if (notes.length === 0) {
+        return successResponse("No notes are currently selected in Notes.app", {
+            notes: [],
+            count: 0,
+        });
+    }
+    const noteList = notes.map((n) => `  - ${n.title} [id: ${n.id}]`).join("\n");
+    return successResponse(`Selected note(s):\n${noteList}`, { notes, count: notes.length });
+}, "Error getting selected 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 +495,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 +509,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,22 +520,35 @@ 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 });
     }
-    const accountList = accounts.map((a) => `  - ${a.name}`).join("\n");
+    const accountList = accounts
+        .map((a) => {
+        const defaultFolder = a.defaultFolder ? ` (default folder: ${a.defaultFolder})` : "";
+        const upgraded = a.upgraded === undefined ? "" : `, upgraded: ${a.upgraded ? "yes" : "no"}`;
+        return `  - ${a.name}${defaultFolder}${upgraded}`;
+    })
+        .join("\n");
     return successResponse(`Found ${accounts.length} accounts:\n${accountList}`, {
         accounts,
         count: accounts.length,
     });
 }, "Error listing accounts"));
+// --- get-default-location ---
+server.tool("get-default-location", "Use when: discovering where Notes.app will create new notes by default.\nReturns: default account and default folder metadata.\nDo not use when: you already have an explicit account/folder target.", {}, withErrorHandling(() => {
+    const location = notesManager.getDefaultLocation();
+    const message = `Default account: ${location.account.name} [id: ${location.account.id}]\n` +
+        `Default folder: ${location.folder.name} [id: ${location.folder.id}]`;
+    return successResponse(message, { ...location });
+}, "Error getting default Notes location"));
 // =============================================================================
 // 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 +566,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 +592,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 +610,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 +653,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 +693,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 +712,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 +736,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 +758,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 +772,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 +790,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 +817,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/build/services/appleNotesManager.js

@@ -1207,25 +1207,23 @@ export class AppleNotesManager {
      */
     listFolders(account) {
         const targetAccount = this.resolveAccount(account);
-        // Get each folder's ID, name, and parent ID in a single AppleScript call.
-        // Each line: "id\tname\tparentId" for subfolders, "id\tname" for top-level.
+        // Get each folder's ID, name, parent ID, and shared state in a single AppleScript call.
         // Using IDs enables correct tree building even with duplicate folder names.
         const listCommand = `
-      set folderList to ""
+      set folderList to {}
       set allFolders to every folder
       repeat with f in allFolders
         set fRef to contents of f
         set cRef to container of fRef
-        if folderList is not "" then
-          set folderList to folderList & linefeed
-        end if
+        set parentId to ""
         if class of cRef is folder then
-          set folderList to folderList & (id of fRef) & tab & (name of fRef) & tab & (id of cRef)
-        else
-          set folderList to folderList & (id of fRef) & tab & (name of fRef)
+          set parentId to id of cRef
         end if
+        set sharedFlag to shared of fRef as text
+        set end of folderList to (id of fRef) & ${AS_FIELD_SEP} & (name of fRef) & ${AS_FIELD_SEP} & parentId & ${AS_FIELD_SEP} & sharedFlag
       end repeat
-      return folderList
+      set AppleScript's text item delimiters to ${AS_RECORD_SEP}
+      return folderList as text
     `;
         const script = buildAccountScopedScript({ account: targetAccount }, listCommand);
         const result = executeAppleScript(script);
@@ -1235,13 +1233,14 @@ export class AppleNotesManager {
         if (!result.output.trim()) {
             return [];
         }
-        // Parse "id\tname[\tparentId]" lines
-        const entries = result.output.split("\n").map((line) => {
-            const parts = line.split("\t");
+        const recordSeparator = result.output.includes(RECORD_SEP) ? RECORD_SEP : "\n";
+        const entries = result.output.split(recordSeparator).map((line) => {
+            const parts = line.includes(FIELD_SEP) ? line.split(FIELD_SEP) : line.split("\t");
             return {
                 id: (parts[0] || "").trim(),
                 name: (parts[1] || "").trim(),
                 parentId: (parts[2] || "").trim(),
+                shared: (parts[3] || "").trim().toLowerCase() === "true",
             };
         });
         // Build an ID-to-entry map for efficient parent lookups
@@ -1264,6 +1263,7 @@ export class AppleNotesManager {
             id: entry.id,
             name: buildPath(entry),
             account: targetAccount,
+            shared: entry.shared,
         }));
     }
     /**
@@ -1455,10 +1455,22 @@ export class AppleNotesManager {
      * @returns Array of Account objects
      */
     listAccounts() {
-        // Coerce the name list to text with a control-char record separator so an
-        // account name containing a comma can't split into phantom accounts (#18).
+        // Coerce account records to text with control-char delimiters so names
+        // containing commas or tabs can't split into phantom accounts (#18).
         const listCommand = `
-      set resultList to name of accounts
+      set resultList to {}
+      repeat with a in accounts
+        set aRef to contents of a
+        set defaultFolderId to ""
+        set defaultFolderName to ""
+        try
+          set fRef to default folder of aRef
+          set defaultFolderId to id of fRef
+          set defaultFolderName to name of fRef
+        end try
+        set upgradedFlag to upgraded of aRef as text
+        set end of resultList to (id of aRef) & ${AS_FIELD_SEP} & (name of aRef) & ${AS_FIELD_SEP} & upgradedFlag & ${AS_FIELD_SEP} & defaultFolderId & ${AS_FIELD_SEP} & defaultFolderName
+      end repeat
       set AppleScript's text item delimiters to ${AS_RECORD_SEP}
       return resultList as text
     `;
@@ -1467,11 +1479,130 @@ export class AppleNotesManager {
         if (!result.success) {
             throw new Error(`Failed to list accounts: ${result.error ?? "unknown error"}`);
         }
-        const names = result.output
+        return result.output
             .split(RECORD_SEP)
             .map((s) => s.trim())
-            .filter((s) => s.length > 0);
-        return names.map((name) => ({ name }));
+            .filter((s) => s.length > 0)
+            .map((item) => {
+            const parts = item.split(FIELD_SEP);
+            if (parts.length === 1) {
+                return { name: parts[0].trim() };
+            }
+            return {
+                id: (parts[0] || "").trim(),
+                name: (parts[1] || "").trim(),
+                upgraded: (parts[2] || "").trim().toLowerCase() === "true",
+                defaultFolderId: (parts[3] || "").trim() || undefined,
+                defaultFolder: (parts[4] || "").trim() || undefined,
+            };
+        });
+    }
+    /**
+     * Gets the default account and folder used by Notes.app for new notes.
+     *
+     * @returns Default account and folder metadata
+     */
+    getDefaultLocation() {
+        const command = `
+      set aRef to default account
+      set fRef to default folder of aRef
+      return (id of aRef) & ${AS_FIELD_SEP} & (name of aRef) & ${AS_FIELD_SEP} & (upgraded of aRef as text) & ${AS_FIELD_SEP} & (id of fRef) & ${AS_FIELD_SEP} & (name of fRef) & ${AS_FIELD_SEP} & (shared of fRef as text)
+    `;
+        const result = executeAppleScript(buildAppLevelScript(command));
+        if (!result.success) {
+            throw new Error(`Failed to get default Notes location: ${result.error ?? "unknown error"}`);
+        }
+        const parts = result.output.split(FIELD_SEP);
+        if (parts.length < 6) {
+            throw new Error(`Failed to parse default Notes location: ${result.output}`);
+        }
+        const accountName = (parts[1] || "").trim();
+        return {
+            account: {
+                id: (parts[0] || "").trim(),
+                name: accountName,
+                upgraded: (parts[2] || "").trim().toLowerCase() === "true",
+                defaultFolderId: (parts[3] || "").trim(),
+                defaultFolder: (parts[4] || "").trim(),
+            },
+            folder: {
+                id: (parts[3] || "").trim(),
+                name: (parts[4] || "").trim(),
+                account: accountName,
+                shared: (parts[5] || "").trim().toLowerCase() === "true",
+            },
+        };
+    }
+    /**
+     * Lists the currently selected Notes in the Notes.app UI.
+     *
+     * @returns Array of selected notes, or an empty array when nothing is selected
+     */
+    getSelectedNotes() {
+        const command = `
+      set selectedNotes to selection
+      set noteList to {}
+      repeat with n in selectedNotes
+        set nRef to contents of n
+        set createdDate to creation date of nRef
+        set modifiedDate to modification date of nRef
+        set createdParts to ${asDatePartsExpr("createdDate")}
+        set modifiedParts to ${asDatePartsExpr("modifiedDate")}
+        set folderName to ""
+        set accountName to ""
+        try
+          set fRef to container of nRef
+          set folderName to name of fRef
+          set aRef to container of fRef
+          set accountName to name of aRef
+        end try
+        set end of noteList to (id of nRef) & ${AS_FIELD_SEP} & (name of nRef) & ${AS_FIELD_SEP} & createdParts & ${AS_FIELD_SEP} & modifiedParts & ${AS_FIELD_SEP} & (shared of nRef as text) & ${AS_FIELD_SEP} & (password protected of nRef as text) & ${AS_FIELD_SEP} & folderName & ${AS_FIELD_SEP} & accountName
+      end repeat
+      set AppleScript's text item delimiters to ${AS_RECORD_SEP}
+      return noteList as text
+    `;
+        const result = executeAppleScript(buildAppLevelScript(command));
+        if (!result.success) {
+            throw new Error(`Failed to get selected notes: ${result.error ?? "unknown error"}`);
+        }
+        if (!result.output.trim()) {
+            return [];
+        }
+        return result.output
+            .split(RECORD_SEP)
+            .filter((s) => s.trim())
+            .map((item) => {
+            const parts = item.split(FIELD_SEP);
+            return {
+                id: (parts[0] || "").trim(),
+                title: (parts[1] || "").trim(),
+                content: "",
+                tags: [],
+                created: parseAppleScriptDate((parts[2] || "").trim()),
+                modified: parseAppleScriptDate((parts[3] || "").trim()),
+                shared: (parts[4] || "").trim().toLowerCase() === "true",
+                passwordProtected: (parts[5] || "").trim().toLowerCase() === "true",
+                folder: (parts[6] || "").trim() || undefined,
+                account: (parts[7] || "").trim() || undefined,
+            };
+        });
+    }
+    /**
+     * Reveals a note in the Notes.app UI by ID.
+     *
+     * @param id - CoreData URL identifier for the note
+     * @param separately - Whether to open the note in a separate window
+     * @returns true if Notes.app accepted the show command
+     */
+    showNoteById(id, separately = false) {
+        const safeId = sanitizeId(id);
+        const separatelyClause = separately ? " separately true" : "";
+        const result = executeAppleScript(buildAppLevelScript(`show note id "${safeId}"${separatelyClause}`));
+        if (!result.success) {
+            console.error(`Failed to show note with ID "${id}":`, result.error);
+            return false;
+        }
+        return true;
     }
     // ===========================================================================
     // Health Check
@@ -1738,8 +1869,17 @@ export class AppleNotesManager {
         repeat with a in attachments of theNote
           set attachId to id of a
           set attachName to name of a
-          set attachType to content identifier of a
-          set end of attachmentList to attachId & ${AS_FIELD_SEP} & attachName & ${AS_FIELD_SEP} & attachType
+          set attachContentId to content identifier of a
+          set attachUrl to ""
+          try
+            set attachUrl to URL of a as text
+          end try
+          set createdDate to creation date of a
+          set modifiedDate to modification date of a
+          set createdParts to ${asDatePartsExpr("createdDate")}
+          set modifiedParts to ${asDatePartsExpr("modifiedDate")}
+          set sharedFlag to shared of a as text
+          set end of attachmentList to attachId & ${AS_FIELD_SEP} & attachName & ${AS_FIELD_SEP} & attachContentId & ${AS_FIELD_SEP} & attachUrl & ${AS_FIELD_SEP} & createdParts & ${AS_FIELD_SEP} & modifiedParts & ${AS_FIELD_SEP} & sharedFlag
         end repeat
         set output to ""
         repeat with item in attachmentList
@@ -1765,6 +1905,11 @@ export class AppleNotesManager {
                     id: parts[0].trim(),
                     name: parts[1].trim(),
                     contentType: parts[2].trim(),
+                    contentId: parts[2].trim() || undefined,
+                    url: parts[3]?.trim() || undefined,
+                    created: parts[4] ? parseAppleScriptDate(parts[4].trim()) : undefined,
+                    modified: parts[5] ? parseAppleScriptDate(parts[5].trim()) : undefined,
+                    shared: parts[6] ? parts[6].trim().toLowerCase() === "true" : undefined,
                 });
             }
         }
@@ -1784,13 +1929,22 @@ export class AppleNotesManager {
       tell application "Notes"
         tell account "${targetAccount}"
           set theNote to note "${safeTitle}"
-          set attachmentList to {}
-          repeat with a in attachments of theNote
-            set attachId to id of a
-            set attachName to name of a
-            set attachType to content identifier of a
-            set end of attachmentList to attachId & ${AS_FIELD_SEP} & attachName & ${AS_FIELD_SEP} & attachType
-          end repeat
+        set attachmentList to {}
+        repeat with a in attachments of theNote
+          set attachId to id of a
+          set attachName to name of a
+          set attachContentId to content identifier of a
+          set attachUrl to ""
+          try
+            set attachUrl to URL of a as text
+          end try
+          set createdDate to creation date of a
+          set modifiedDate to modification date of a
+          set createdParts to ${asDatePartsExpr("createdDate")}
+          set modifiedParts to ${asDatePartsExpr("modifiedDate")}
+          set sharedFlag to shared of a as text
+          set end of attachmentList to attachId & ${AS_FIELD_SEP} & attachName & ${AS_FIELD_SEP} & attachContentId & ${AS_FIELD_SEP} & attachUrl & ${AS_FIELD_SEP} & createdParts & ${AS_FIELD_SEP} & modifiedParts & ${AS_FIELD_SEP} & sharedFlag
+        end repeat
           set output to ""
           repeat with item in attachmentList
             set output to output & item & ${AS_RECORD_SEP}
@@ -1816,6 +1970,11 @@ export class AppleNotesManager {
                     id: parts[0].trim(),
                     name: parts[1].trim(),
                     contentType: parts[2].trim(),
+                    contentId: parts[2].trim() || undefined,
+                    url: parts[3]?.trim() || undefined,
+                    created: parts[4] ? parseAppleScriptDate(parts[4].trim()) : undefined,
+                    modified: parts[5] ? parseAppleScriptDate(parts[5].trim()) : undefined,
+                    shared: parts[6] ? parts[6].trim().toLowerCase() === "true" : undefined,
                 });
             }
         }

package/build/services/appleNotesManager.test.js

@@ -1145,7 +1145,11 @@ describe("AppleNotesManager", () => {
         it("returns array of Folder objects with paths", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "id1\tNotes\nid2\tArchive\nid3\tWork",
+                output: [
+                    ["id1", "Notes", "", "false"].join(F),
+                    ["id2", "Archive", "", "false"].join(F),
+                    ["id3", "Work", "", "true"].join(F),
+                ].join(R),
             });
             const folders = manager.listFolders();
             expect(folders).toHaveLength(3);
@@ -1153,11 +1157,17 @@ describe("AppleNotesManager", () => {
             expect(folders[1].name).toBe("Archive");
             expect(folders[2].name).toBe("Work");
             expect(folders[0].id).toBe("id1");
+            expect(folders[2].shared).toBe(true);
         });
         it("includes parent folder in path", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "id1\tDev\nid2\tAccessibility\tid1\nid3\tWork\nid4\tClients\tid3",
+                output: [
+                    ["id1", "Dev", "", "false"].join(F),
+                    ["id2", "Accessibility", "id1", "false"].join(F),
+                    ["id3", "Work", "", "false"].join(F),
+                    ["id4", "Clients", "id3", "false"].join(F),
+                ].join(R),
             });
             const folders = manager.listFolders();
             expect(folders).toHaveLength(4);
@@ -1169,7 +1179,13 @@ describe("AppleNotesManager", () => {
         it("disambiguates duplicate folder names using IDs", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "id1\tFinance\nid2\tArchive\tid1\nid3\tTravel\nid4\tTrips\tid3\nid5\tArchive\tid4",
+                output: [
+                    ["id1", "Finance", "", "false"].join(F),
+                    ["id2", "Archive", "id1", "false"].join(F),
+                    ["id3", "Travel", "", "false"].join(F),
+                    ["id4", "Trips", "id3", "false"].join(F),
+                    ["id5", "Archive", "id4", "false"].join(F),
+                ].join(R),
             });
             const folders = manager.listFolders();
             expect(folders).toHaveLength(5);
@@ -1179,17 +1195,31 @@ describe("AppleNotesManager", () => {
         it("escapes slashes in folder names", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "id1\tTravel\nid2\tSpain/Portugal 2023\tid1",
+                output: [
+                    ["id1", "Travel", "", "false"].join(F),
+                    ["id2", "Spain/Portugal 2023", "id1", "false"].join(F),
+                ].join(R),
             });
             const folders = manager.listFolders();
             expect(folders).toHaveLength(2);
             expect(folders[0].name).toBe("Travel");
             expect(folders[1].name).toBe("Travel/Spain\\/Portugal 2023");
         });
+        it("parses legacy tab/newline output (backward compat)", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "id1\tNotes\nid2\tArchive\tid1",
+            });
+            const folders = manager.listFolders();
+            expect(folders).toHaveLength(2);
+            expect(folders[0].name).toBe("Notes");
+            expect(folders[1].name).toBe("Notes/Archive");
+            expect(folders[1].shared).toBe(false);
+        });
         it("includes account in Folder objects", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: "id1\tNotes",
+                output: ["id1", "Notes", "", "false"].join(F),
             });
             const folders = manager.listFolders("Gmail");
             expect(folders[0].account).toBe("Gmail");
@@ -1420,13 +1450,41 @@ describe("AppleNotesManager", () => {
         it("returns array of Account objects", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["iCloud", "Gmail", "Exchange"].join(R),
+                output: [
+                    ["acc1", "iCloud", "true", "folder1", "Notes"].join(F),
+                    ["acc2", "Gmail", "false", "folder2", "Inbox"].join(F),
+                    ["acc3", "Exchange", "false", "", ""].join(F),
+                ].join(R),
             });
             const accounts = manager.listAccounts();
             expect(accounts).toHaveLength(3);
             expect(accounts[0].name).toBe("iCloud");
             expect(accounts[1].name).toBe("Gmail");
             expect(accounts[2].name).toBe("Exchange");
+            expect(accounts[0].id).toBe("acc1");
+            expect(accounts[0].upgraded).toBe(true);
+            expect(accounts[0].defaultFolder).toBe("Notes");
+        });
+        it("parses legacy plain-name output (backward compat)", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: ["iCloud", "Gmail"].join(R),
+            });
+            const accounts = manager.listAccounts();
+            expect(accounts).toHaveLength(2);
+            expect(accounts[0]).toEqual({ name: "iCloud" });
+            expect(accounts[1]).toEqual({ name: "Gmail" });
+        });
+        it("handles account records with empty fields", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: ["", "", "", "", ""].join(F),
+            });
+            const accounts = manager.listAccounts();
+            expect(accounts).toHaveLength(1);
+            expect(accounts[0].name).toBe("");
+            expect(accounts[0].upgraded).toBe(false);
+            expect(accounts[0].defaultFolderId).toBeUndefined();
         });
         it("throws on failure rather than returning empty (#19)", () => {
             mockExecuteAppleScript.mockReturnValue({
@@ -1437,6 +1495,126 @@ describe("AppleNotesManager", () => {
             expect(() => manager.listAccounts()).toThrow(/Notes.app not available/);
         });
     });
+    describe("getDefaultLocation", () => {
+        it("returns default account and folder metadata", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: ["acc1", "iCloud", "true", "folder1", "Notes", "false"].join(F),
+            });
+            const location = manager.getDefaultLocation();
+            expect(location.account).toMatchObject({
+                id: "acc1",
+                name: "iCloud",
+                upgraded: true,
+                defaultFolderId: "folder1",
+                defaultFolder: "Notes",
+            });
+            expect(location.folder).toMatchObject({
+                id: "folder1",
+                name: "Notes",
+                account: "iCloud",
+                shared: false,
+            });
+        });
+        it("throws when default location output cannot be parsed", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "bad-output",
+            });
+            expect(() => manager.getDefaultLocation()).toThrow(/parse default Notes location/);
+        });
+        it("throws when AppleScript fails", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: false, output: "", error: "boom" });
+            expect(() => manager.getDefaultLocation()).toThrow(/Failed to get default Notes location/);
+        });
+        it("handles empty fields in default location output", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: ["", "", "", "", "", ""].join(F),
+            });
+            const location = manager.getDefaultLocation();
+            expect(location.account.name).toBe("");
+            expect(location.account.upgraded).toBe(false);
+            expect(location.folder.id).toBe("");
+            expect(location.folder.shared).toBe(false);
+        });
+    });
+    describe("getSelectedNotes", () => {
+        it("returns selected note metadata", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: [
+                    [
+                        "x-coredata://ABC/ICNote/p1",
+                        "Selected Note",
+                        "2026-6-22-14-30-0",
+                        "2026-6-22-14-35-0",
+                        "false",
+                        "false",
+                        "Notes",
+                        "iCloud",
+                    ].join(F),
+                ].join(R),
+            });
+            const notes = manager.getSelectedNotes();
+            expect(notes).toHaveLength(1);
+            expect(notes[0]).toMatchObject({
+                id: "x-coredata://ABC/ICNote/p1",
+                title: "Selected Note",
+                shared: false,
+                passwordProtected: false,
+                folder: "Notes",
+                account: "iCloud",
+            });
+            expect(notes[0].created.getFullYear()).toBe(2026);
+        });
+        it("returns an empty array when no note is selected", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "",
+            });
+            expect(manager.getSelectedNotes()).toEqual([]);
+        });
+        it("throws when AppleScript fails", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: false, output: "", error: "boom" });
+            expect(() => manager.getSelectedNotes()).toThrow(/Failed to get selected notes/);
+        });
+        it("handles selected notes with empty optional fields", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: ["", "", "", "", "", "", "", ""].join(F),
+            });
+            const notes = manager.getSelectedNotes();
+            expect(notes).toHaveLength(1);
+            expect(notes[0].id).toBe("");
+            expect(notes[0].shared).toBe(false);
+            expect(notes[0].passwordProtected).toBe(false);
+            expect(notes[0].folder).toBeUndefined();
+            expect(notes[0].account).toBeUndefined();
+        });
+    });
+    describe("showNoteById", () => {
+        it("shows a note by id", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "",
+            });
+            expect(manager.showNoteById("x-coredata://ABC/ICNote/p1")).toBe(true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('show note id "x-coredata://ABC/ICNote/p1"'));
+        });
+        it("can request a separate window", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "",
+            });
+            manager.showNoteById("x-coredata://ABC/ICNote/p1", true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("separately true"));
+        });
+        it("returns false when Notes.app rejects the show command", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: false, output: "", error: "no such note" });
+            expect(manager.showNoteById("x-coredata://ABC/ICNote/p1")).toBe(false);
+        });
+    });
     // ---------------------------------------------------------------------------
     // Health Check
     // ---------------------------------------------------------------------------
@@ -1620,16 +1798,45 @@ describe("AppleNotesManager", () => {
             });
             const attachments = manager.listAttachmentsById("x-coredata://ABC/ICNote/p123");
             expect(attachments).toHaveLength(2);
-            expect(attachments[0]).toEqual({
+            expect(attachments[0]).toMatchObject({
                 id: "x-coredata://ABC/ICAttachment/p1",
                 name: "photo.jpg",
                 contentType: "public.jpeg",
+                contentId: "public.jpeg",
             });
-            expect(attachments[1]).toEqual({
+            expect(attachments[1]).toMatchObject({
                 id: "x-coredata://ABC/ICAttachment/p2",
                 name: "document.pdf",
                 contentType: "com.adobe.pdf",
+                contentId: "com.adobe.pdf",
+            });
+        });
+        it("parses richer attachment metadata when present", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
+                success: true,
+                output: [
+                    [
+                        "x-coredata://ABC/ICAttachment/p1",
+                        "site.webloc",
+                        "cid:123",
+                        "https://example.com",
+                        "2026-6-22-10-0-0",
+                        "2026-6-22-11-0-0",
+                        "true",
+                    ].join(F),
+                ].join(R),
+            });
+            const attachments = manager.listAttachmentsById("x-coredata://ABC/ICNote/p123");
+            expect(attachments[0]).toMatchObject({
+                id: "x-coredata://ABC/ICAttachment/p1",
+                name: "site.webloc",
+                contentType: "cid:123",
+                contentId: "cid:123",
+                url: "https://example.com",
+                shared: true,
             });
+            expect(attachments[0].created?.getFullYear()).toBe(2026);
+            expect(attachments[0].modified?.getHours()).toBe(11);
         });
         it("returns empty array when note has no attachments", () => {
             mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "" });
@@ -1659,10 +1866,11 @@ describe("AppleNotesManager", () => {
             });
             const attachments = manager.listAttachments("My Note");
             expect(attachments).toHaveLength(1);
-            expect(attachments[0]).toEqual({
+            expect(attachments[0]).toMatchObject({
                 id: "attach-id",
                 name: "image.png",
                 contentType: "public.png",
+                contentId: "public.png",
             });
         });
         it("uses specified account", () => {

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.2",
+  "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": [