apple-notes-mcp 2.3.0 → 2.5.0

package/README.md

@@ -135,7 +135,7 @@ A few Notes UI features are not exposed to AppleScript and therefore cannot be
 supported. See **[docs/APPLESCRIPT-LIMITATIONS.md](docs/APPLESCRIPT-LIMITATIONS.md)**
 for the investigation and verification behind each:
 
-- **Pinned notes** — Notes has no scriptable `pinned` property, so pin state can be neither read nor set.
+- **Pinned notes** — Notes has no scriptable `pinned` property via AppleScript. Pin state can now be **read** with the BETA `get-note-metadata` tool (from the NoteStore database), but it still cannot be **set** programmatically.
 - **Note-to-note links** — there is no `applenotes://` deep link or link property; the only stable handle is the `x-coredata://` note id.
 
 ---
@@ -267,6 +267,22 @@ see [docs/APPLESCRIPT-LIMITATIONS.md](../docs/APPLESCRIPT-LIMITATIONS.md#tags--h
 
 ---
 
+#### `get-note-plaintext`
+
+Retrieves a note's body as plain text, with no HTML markup.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `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) |
+
+**Note:** Either `id` or `title` must be provided. This reads the note's native `plaintext` property, so it skips the HTML-to-text conversion that `get-note-content` plus a Markdown pass would do. Use `get-note-content` when you need the HTML, or `get-note-markdown` when you want Markdown with checklist state.
+
+**Returns:** The plain-text content of the note in `structuredContent.plaintext`, or error if not found.
+
+---
+
 #### `get-note-details`
 
 Retrieves metadata about a note (without full content).
@@ -376,6 +392,8 @@ Updates an existing note's content and/or title.
 
 **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`.
 
+**Attachments:** A full-body replace can drop embedded files, images, scans, PDFs, or audio. When a note may hold attachments, run [`list-attachments`](#list-attachments) first, and either save them with `save-attachment` or build a new note rather than overwriting. See the skill's [Attachment-Safe Updates](skills/apple-notes/SKILL.md#attachment-safe-updates) guidance.
+
 ---
 
 #### `delete-note`
@@ -551,6 +569,19 @@ Deletes a folder.
 
 ---
 
+#### `show-folder`
+
+Reveals a folder in Notes.app using its unique CoreData identifier.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | The folder's CoreData identifier (from `list-folders`) |
+| `separately` | boolean | No | Open in a separate window when supported by Notes.app |
+
+**Returns:** Confirmation that Notes.app accepted the show command.
+
+---
+
 ### Account Operations
 
 #### `list-accounts`
@@ -578,6 +609,19 @@ Returns the default account and folder Notes.app uses for newly created notes.
 
 ---
 
+#### `show-account`
+
+Reveals an account in Notes.app using its unique CoreData identifier.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | The account's CoreData identifier (from `list-accounts`) |
+| `separately` | boolean | No | Open in a separate window when supported by Notes.app |
+
+**Returns:** Confirmation that Notes.app accepted the show command.
+
+---
+
 ### Batch Operations
 
 #### `batch-delete-notes`
@@ -662,6 +706,22 @@ Checklist for "Shopping List" (2/4 done):
 
 ---
 
+#### `get-note-metadata` (BETA)
+
+Reads note metadata that AppleScript cannot expose, by querying the NoteStore SQLite database directly: pinned state, checklist flags, trash/recovery state, the preview snippet, and the password hint. The available fields vary by macOS version.
+
+**Requires:** Full Disk Access for the MCP host process (see [Full Disk Access Setup](#full-disk-access-for-checklist-features)).
+
+**BETA:** the NoteStore schema changes between macOS releases, so some fields can be absent on older or newer systems. The database is only ever read, never written.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Note ID (use `search-notes` to find it first) |
+
+**Returns:** A metadata object in `structuredContent` holding any of `pinned`, `hasChecklist`, `hasChecklistInProgress`, `recoveringFromTrash`, `passwordProtected`, `passwordHint`, `snippet`, `widgetSnippet`, and `smartFolderQuery`. Unlike most read tools, it also resolves trashed notes that AppleScript can no longer find.
+
+---
+
 #### `list-attachments`
 
 Lists attachments in a note.
@@ -703,6 +763,20 @@ Returns a note attachment's bytes as base64, without writing to disk (the read c
 
 ---
 
+#### `show-attachment`
+
+Reveals one note attachment in Notes.app. Attachments are elements of a note, so this takes both the note id and the attachment id (the same pair used by `save-attachment` / `fetch-attachment`).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `noteId` | string | Yes | CoreData note ID (from `search-notes`/`list-notes`) |
+| `attachmentId` | string | Yes | Attachment ID (from `list-attachments`) |
+| `separately` | boolean | No | Open in a separate window when supported by Notes.app |
+
+**Returns:** Confirmation that Notes.app revealed the attachment.
+
+---
+
 ### Diagnostics
 
 #### `health-check`

package/build/index.js

@@ -26,6 +26,7 @@ import { z } from "zod";
 import { AppleNotesManager } from "./services/appleNotesManager.js";
 import { getSyncStatus, withSyncAwarenessSync } from "./utils/syncDetection.js";
 import { getChecklistItems, hasFullDiskAccess } from "./utils/checklistParser.js";
+import { getNoteMetadata } from "./utils/noteMetadata.js";
 import { detectChecklistAttempt } from "./utils/contentWarnings.js";
 import { parseHashtags } from "./utils/hashtags.js";
 import { runDoctor, formatDoctorReport } from "./tools/doctor.js";
@@ -254,6 +255,54 @@ server.registerTool("get-note-content", {
     const hashtags = parseHashtags(content);
     return successResponse(content, { title, content, hashtags });
 }, "Error retrieving note content"));
+// --- get-note-plaintext ---
+server.registerTool("get-note-plaintext", {
+    description: "Use when: reading one note's body as plain text with no HTML, by id (preferred) or title.\nReturns: the note's plaintext exactly as Notes exposes it.\nDo not use when: you need the HTML body (get-note-content) or Markdown with checklist state (get-note-markdown).\nNote: this reads the note's native plaintext property, so it skips the HTML-to-text conversion; password-protected notes must be unlocked in Notes.app first.",
+    inputSchema: {
+        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
+            .string()
+            .optional()
+            .describe("Account name (defaults to iCloud, ignored if id is provided)"),
+    },
+    outputSchema: {
+        title: z.string().optional(),
+        plaintext: z.string().optional(),
+    },
+}, withErrorHandling(({ id, title, account }) => {
+    // Prefer ID-based lookup if provided
+    if (id) {
+        const note = notesManager.getNoteById(id);
+        if (!note) {
+            return errorResponse(`Note with ID "${id}" not found`);
+        }
+        if (note.passwordProtected) {
+            return errorResponse(`Note "${note.title}" is password-protected and cannot be read. Unlock it in Notes.app first.`);
+        }
+        const plaintext = notesManager.getNotePlaintextById(id);
+        if (!plaintext) {
+            return errorResponse(`Failed to read plaintext of note "${note.title}"`);
+        }
+        return successResponse(plaintext, { title: note.title, plaintext });
+    }
+    // Fall back to title-based lookup
+    if (!title) {
+        return errorResponse("Either 'id' or 'title' is required");
+    }
+    const note = notesManager.getNoteDetails(title, account);
+    if (!note) {
+        return errorResponse(`Note "${title}" not found`);
+    }
+    if (note.passwordProtected) {
+        return errorResponse(`Note "${title}" is password-protected and cannot be read. Unlock it in Notes.app first.`);
+    }
+    const plaintext = notesManager.getNotePlaintext(title, account);
+    if (!plaintext) {
+        return errorResponse(`Failed to read plaintext of note "${title}"`);
+    }
+    return successResponse(plaintext, { title, plaintext });
+}, "Error retrieving note plaintext"));
 // --- get-note-by-id ---
 server.registerTool("get-note-by-id", {
     description: "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).",
@@ -335,9 +384,51 @@ server.registerTool("show-note", {
     }
     return successResponse(`Shown note with ID "${id}" in Notes.app`, { id, separately });
 }, "Error showing note"));
+// --- show-folder ---
+server.registerTool("show-folder", {
+    description: "Use when: the user wants to reveal a known folder in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need the folder list (list-folders).\nNote: this opens or focuses the Notes UI. Get the id from list-folders.",
+    inputSchema: {
+        id: z.string().min(1, "Folder ID is required"),
+        separately: z
+            .boolean()
+            .optional()
+            .describe("Open in a separate window when supported by Notes.app"),
+    },
+    outputSchema: {
+        id: z.string().optional(),
+        separately: z.boolean().optional(),
+    },
+}, withErrorHandling(({ id, separately = false }) => {
+    const success = notesManager.showFolderById(id, separately);
+    if (!success) {
+        return errorResponse(`Failed to show folder with ID "${id}"`);
+    }
+    return successResponse(`Shown folder with ID "${id}" in Notes.app`, { id, separately });
+}, "Error showing folder"));
+// --- show-account ---
+server.registerTool("show-account", {
+    description: "Use when: the user wants to reveal a known account in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need the account list (list-accounts).\nNote: this opens or focuses the Notes UI. Get the id from list-accounts.",
+    inputSchema: {
+        id: z.string().min(1, "Account ID is required"),
+        separately: z
+            .boolean()
+            .optional()
+            .describe("Open in a separate window when supported by Notes.app"),
+    },
+    outputSchema: {
+        id: z.string().optional(),
+        separately: z.boolean().optional(),
+    },
+}, withErrorHandling(({ id, separately = false }) => {
+    const success = notesManager.showAccountById(id, separately);
+    if (!success) {
+        return errorResponse(`Failed to show account with ID "${id}"`);
+    }
+    return successResponse(`Shown account with ID "${id}" in Notes.app`, { id, separately });
+}, "Error showing account"));
 // --- update-note ---
 server.registerTool("update-note", {
-    description: "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.",
+    description: "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, and run list-attachments first when the note may hold files, images, scans, PDFs, or audio, since a full-body replace can drop embedded attachments. Edits to shared notes are immediately visible to all collaborators.",
     inputSchema: {
         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)"),
@@ -1048,6 +1139,39 @@ server.registerTool("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"));
+// --- show-attachment ---
+server.registerTool("show-attachment", {
+    description: "Use when: the user wants to reveal one note attachment in Notes.app.\nReturns: confirmation that Notes.app revealed the attachment.\nDo not use when: you want the bytes (fetch-attachment) or a file on disk (save-attachment).\nNote: this opens or focuses the Notes UI. Get the ids from list-attachments first.",
+    inputSchema: {
+        noteId: z
+            .string()
+            .min(1, "noteId is required")
+            .describe("CoreData note id (from search/list)"),
+        attachmentId: z
+            .string()
+            .min(1, "attachmentId is required")
+            .describe("Attachment id (from list-attachments)"),
+        separately: z
+            .boolean()
+            .optional()
+            .describe("Open in a separate window when supported by Notes.app"),
+    },
+    outputSchema: {
+        noteId: z.string().optional(),
+        attachmentId: z.string().optional(),
+        separately: z.boolean().optional(),
+    },
+}, withErrorHandling(({ noteId, attachmentId, separately = false }) => {
+    const success = notesManager.showAttachmentById(noteId, attachmentId, separately);
+    if (!success) {
+        return errorResponse(`Failed to show attachment "${attachmentId}" on note "${noteId}"`);
+    }
+    return successResponse(`Shown attachment "${attachmentId}" in Notes.app`, {
+        noteId,
+        attachmentId,
+        separately,
+    });
+}, "Error showing attachment"));
 // --- export-notes-json ---
 server.registerTool("export-notes-json", {
     description: "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.",
@@ -1138,6 +1262,36 @@ server.registerTool("get-checklist-state", {
     const checked = result.items.filter((i) => i.done).length;
     return successResponse(`Checklist for "${note.title}" (${checked}/${result.items.length} done):\n${summary}`, { items: result.items, checked, total: result.items.length });
 }, "Error reading checklist state"));
+// --- get-note-metadata (BETA) ---
+server.registerTool("get-note-metadata", {
+    description: "[BETA] Use when: reading note metadata AppleScript cannot expose — pinned state, checklist flags, trash/recovery state, preview snippet, password hint — by id.\nReturns: a metadata object; fields vary by macOS version and are omitted when unavailable.\nDo not use when: you need the body (get-note-content) or per-item checklist state (get-checklist-state).\nNote: reads the NoteStore SQLite database read-only and requires Full Disk Access. BETA — the database schema changes between macOS releases, so some fields may be absent. Works on trashed notes that AppleScript can no longer resolve.",
+    inputSchema: {
+        id: z.string().min(1, "Note ID is required. Use search-notes to find the note ID first."),
+    },
+    outputSchema: {
+        pinned: z.boolean().optional(),
+        hasChecklist: z.boolean().optional(),
+        hasChecklistInProgress: z.boolean().optional(),
+        recoveringFromTrash: z.boolean().optional(),
+        passwordProtected: z.boolean().optional(),
+        passwordHint: z.string().optional(),
+        snippet: z.string().optional(),
+        widgetSnippet: z.string().optional(),
+        smartFolderQuery: z.string().optional(),
+    },
+}, withErrorHandling(({ id }) => {
+    // No AppleScript existence pre-check: reading straight from the database lets
+    // this resolve trashed/recovering notes that `note id ...` can no longer find.
+    const { metadata, message } = getNoteMetadata(id);
+    if (!metadata) {
+        return errorResponse(message || `Failed to read metadata for note "${id}"`);
+    }
+    const keys = Object.keys(metadata);
+    const summary = keys.length === 0
+        ? `No additional metadata is available for note "${id}" on this macOS version.`
+        : keys.map((k) => `${k}: ${String(metadata[k])}`).join("\n");
+    return successResponse(summary, metadata);
+}, "Error reading note metadata"));
 // =============================================================================
 // Server Startup
 // =============================================================================

package/build/services/__fixtures__/notesNormalizedHtml.js

@@ -0,0 +1,32 @@
+export const NOTES_NORMALIZED_HTML_FIXTURES = [
+    {
+        name: "headingAndParagraphs",
+        description: "An <h1> title and two <div> paragraphs separated by a spacer row",
+        html: "<div><h1>Meeting Notes</h1></div><div>First line.</div><div><br></div><div>Second line.</div>",
+        expectedMarkdown: "# Meeting Notes\n\nFirst line.\n  \n\nSecond line.",
+    },
+    {
+        name: "bulletList",
+        description: "An <h2> section heading followed by a native <ul> bullet list",
+        html: "<div><h2>Tasks</h2></div><ul><li>Buy milk</li><li>Walk dog</li></ul>",
+        expectedMarkdown: "## Tasks\n\n-   Buy milk\n-   Walk dog",
+    },
+    {
+        name: "inlineEmphasis",
+        description: "Inline <b> and <i> emphasis inside a paragraph div",
+        html: "<div>This is <b>bold</b> and <i>italic</i> text.</div>",
+        expectedMarkdown: "This is **bold** and _italic_ text.",
+    },
+    {
+        name: "codeSpan",
+        description: "A <tt> code span — the tag is dropped, only its text survives",
+        html: "<div>Run <tt>npm install</tt> first.</div>",
+        expectedMarkdown: "Run npm install first.",
+    },
+    {
+        name: "spacerRuns",
+        description: "Consecutive <div><br></div> spacer rows between two paragraphs",
+        html: "<div>A</div><div><br></div><div><br></div><div>B</div>",
+        expectedMarkdown: "A\n  \n\n  \n\nB",
+    },
+];

package/build/services/appleNotesManager.js

@@ -781,6 +781,53 @@ export class AppleNotesManager {
         }
         return result.output;
     }
+    /**
+     * Retrieves the plain-text content of a note by its exact title.
+     *
+     * Reads the note's `plaintext` property, which Notes derives from the body
+     * with all HTML markup removed. This is the text Notes itself exposes, so it
+     * is more faithful than converting the HTML body and skips the markup
+     * round-trip entirely.
+     *
+     * @param title - Exact title of the note
+     * @param account - Account to search in (defaults to iCloud)
+     * @returns Plain-text content of the note, or empty string if not found
+     */
+    getNotePlaintext(title, account) {
+        const targetAccount = this.resolveAccount(account);
+        const safeTitle = escapePlainStringForAppleScript(title);
+        const getCommand = `get plaintext of note "${safeTitle}"`;
+        const script = buildAccountScopedScript({ account: targetAccount }, getCommand);
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Failed to get plaintext of note "${title}":`, result.error);
+            return "";
+        }
+        return result.output;
+    }
+    /**
+     * Retrieves the plain-text content of a note by its CoreData ID.
+     *
+     * Reads the read-only `plaintext` property (the body with HTML removed). More
+     * reliable than getNotePlaintext() because IDs are unique across accounts.
+     *
+     * Note: Password-protected notes will fail with an AppleScript error. Callers
+     * should check for password protection beforehand using getNoteById().
+     *
+     * @param id - CoreData URL identifier for the note
+     * @returns Plain-text content of the note, or empty string if not found
+     */
+    getNotePlaintextById(id) {
+        const safeId = sanitizeId(id);
+        const getCommand = `get plaintext of note id "${safeId}"`;
+        const script = buildAppLevelScript(getCommand);
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Failed to get plaintext of note with ID "${id}":`, result.error);
+            return "";
+        }
+        return result.output;
+    }
     /**
      * Retrieves a note by its unique CoreData ID.
      *
@@ -1604,6 +1651,91 @@ export class AppleNotesManager {
         }
         return true;
     }
+    /**
+     * Reveals a folder in the Notes.app UI by its id.
+     *
+     * Wraps the Notes `show` command, which the scripting dictionary exposes for
+     * folders as well as notes. This opens or focuses the Notes UI on the folder.
+     *
+     * @param id - CoreData identifier for the folder (from list-folders)
+     * @param separately - Open in a separate window when supported by Notes.app
+     * @returns true if Notes.app accepted the show command, false otherwise
+     */
+    showFolderById(id, separately = false) {
+        const safeId = sanitizeId(id);
+        const separatelyClause = separately ? " separately true" : "";
+        const result = executeAppleScript(buildAppLevelScript(`show folder id "${safeId}"${separatelyClause}`));
+        if (!result.success) {
+            console.error(`Failed to show folder with ID "${id}":`, result.error);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Reveals an account in the Notes.app UI by its id.
+     *
+     * Wraps the Notes `show` command, which the scripting dictionary exposes for
+     * accounts as well as notes. This opens or focuses the Notes UI on the account.
+     *
+     * @param id - CoreData identifier for the account (from list-accounts)
+     * @param separately - Open in a separate window when supported by Notes.app
+     * @returns true if Notes.app accepted the show command, false otherwise
+     */
+    showAccountById(id, separately = false) {
+        const safeId = sanitizeId(id);
+        const separatelyClause = separately ? " separately true" : "";
+        const result = executeAppleScript(buildAppLevelScript(`show account id "${safeId}"${separatelyClause}`));
+        if (!result.success) {
+            console.error(`Failed to show account with ID "${id}":`, result.error);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Reveals an attachment in the Notes.app UI.
+     *
+     * Attachments are elements of a note, so they cannot be referenced at the
+     * application level by id alone. This resolves the attachment within its note
+     * (the same lookup used by save-attachment) and then runs the Notes `show`
+     * command on it, opening or focusing the Notes UI on the attachment.
+     *
+     * @param noteId - CoreData identifier for the note containing the attachment
+     * @param attachmentId - id of the attachment (from list-attachments)
+     * @param separately - Open in a separate window when supported by Notes.app
+     * @returns true if Notes.app revealed the attachment, false otherwise
+     */
+    showAttachmentById(noteId, attachmentId, separately = false) {
+        const safeNoteId = sanitizeId(noteId);
+        const safeAttId = escapePlainStringForAppleScript(attachmentId);
+        const separatelyClause = separately ? " separately true" : "";
+        const script = `
+      tell application "Notes"
+        set theNote to note id "${safeNoteId}"
+        set theAttachment to missing value
+        repeat with a in attachments of theNote
+          if (id of a as text) is "${safeAttId}" then
+            set theAttachment to a
+            exit repeat
+          end if
+        end repeat
+        if theAttachment is missing value then
+          return "ERR${AS_FIELD_SEP}attachment not found"
+        end if
+        show theAttachment${separatelyClause}
+        return "OK"
+      end tell
+    `;
+        const result = executeAppleScript(script);
+        if (!result.success) {
+            console.error(`Failed to show attachment "${attachmentId}" on note "${noteId}":`, result.error);
+            return false;
+        }
+        if ((result.output ?? "").trim().startsWith("ERR")) {
+            console.error(`Attachment "${attachmentId}" not found on note "${noteId}"`);
+            return false;
+        }
+        return true;
+    }
     // ===========================================================================
     // Health Check
     // ===========================================================================

package/build/services/appleNotesManager.test.js

@@ -664,6 +664,45 @@ describe("AppleNotesManager", () => {
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('tell account "Gmail"'));
         });
     });
+    describe("getNotePlaintext", () => {
+        it("reads the note's plaintext property by title", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "Shopping List\n- Eggs\n- Milk",
+            });
+            const text = manager.getNotePlaintext("Shopping List");
+            expect(text).toBe("Shopping List\n- Eggs\n- Milk");
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('get plaintext of note "Shopping List"'));
+        });
+        it("returns empty string when the note is not found", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: false,
+                output: "",
+                error: 'Can\'t get note "Missing"',
+            });
+            expect(manager.getNotePlaintext("Missing Note")).toBe("");
+        });
+        it("uses the specified account", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "Content" });
+            manager.getNotePlaintext("My Note", "Gmail");
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('tell account "Gmail"'));
+        });
+    });
+    describe("getNotePlaintextById", () => {
+        it("reads the note's plaintext property by id at the application level", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "Just the text" });
+            const text = manager.getNotePlaintextById("x-coredata://ABC/ICNote/p1");
+            expect(text).toBe("Just the text");
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('get plaintext of note id "x-coredata://ABC/ICNote/p1"'));
+        });
+        it("returns empty string when Notes.app rejects the read", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: false, output: "", error: "no such note" });
+            expect(manager.getNotePlaintextById("x-coredata://ABC/ICNote/p1")).toBe("");
+        });
+        it("rejects malformed IDs", () => {
+            expect(() => manager.getNotePlaintextById("arbitrary string")).toThrow();
+        });
+    });
     // ---------------------------------------------------------------------------
     // Password Protection Helpers
     // ---------------------------------------------------------------------------
@@ -1615,6 +1654,76 @@ describe("AppleNotesManager", () => {
             expect(manager.showNoteById("x-coredata://ABC/ICNote/p1")).toBe(false);
         });
     });
+    describe("showFolderById", () => {
+        it("shows a folder by id", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "" });
+            expect(manager.showFolderById("x-coredata://ABC/ICFolder/p1")).toBe(true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('show folder id "x-coredata://ABC/ICFolder/p1"'));
+        });
+        it("can request a separate window", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "" });
+            manager.showFolderById("x-coredata://ABC/ICFolder/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 folder",
+            });
+            expect(manager.showFolderById("x-coredata://ABC/ICFolder/p1")).toBe(false);
+        });
+    });
+    describe("showAccountById", () => {
+        it("shows an account by id", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "" });
+            expect(manager.showAccountById("x-coredata://ABC/ICAccount/p1")).toBe(true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('show account id "x-coredata://ABC/ICAccount/p1"'));
+        });
+        it("can request a separate window", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "" });
+            manager.showAccountById("x-coredata://ABC/ICAccount/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 account",
+            });
+            expect(manager.showAccountById("x-coredata://ABC/ICAccount/p1")).toBe(false);
+        });
+    });
+    describe("showAttachmentById", () => {
+        it("resolves the attachment within its note and shows it", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "OK" });
+            expect(manager.showAttachmentById("x-coredata://ABC/ICNote/p1", "att-123")).toBe(true);
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain('set theNote to note id "x-coredata://ABC/ICNote/p1"');
+            expect(script).toContain('is "att-123"');
+            expect(script).toContain("show theAttachment");
+        });
+        it("can request a separate window", () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "OK" });
+            manager.showAttachmentById("x-coredata://ABC/ICNote/p1", "att-123", true);
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("separately true"));
+        });
+        it("returns false when the attachment is not found on the note", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: `ERR${F}attachment not found`,
+            });
+            expect(manager.showAttachmentById("x-coredata://ABC/ICNote/p1", "missing")).toBe(false);
+        });
+        it("returns false when Notes.app rejects the show command", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: false,
+                output: "",
+                error: "no such note",
+            });
+            expect(manager.showAttachmentById("x-coredata://ABC/ICNote/p1", "att-123")).toBe(false);
+        });
+    });
     // ---------------------------------------------------------------------------
     // Health Check
     // ---------------------------------------------------------------------------

package/build/services/notesHtmlMarkdown.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { NOTES_NORMALIZED_HTML_FIXTURES } from "../services/__fixtures__/notesNormalizedHtml.js";
+// Mock the same seams the main manager test does: AppleScript execution and the
+// SQLite-backed checklist reader (no Full Disk Access in unit tests).
+vi.mock("@/utils/applescript.js", () => ({
+    executeAppleScript: vi.fn(),
+}));
+vi.mock("@/utils/checklistParser.js", () => ({
+    getChecklistItems: vi.fn().mockReturnValue({ items: null }),
+}));
+import { executeAppleScript } from "../utils/applescript.js";
+import { AppleNotesManager } from "../services/appleNotesManager.js";
+const mockExecuteAppleScript = vi.mocked(executeAppleScript);
+const NOTE_ID = "x-coredata://ABC/ICNote/p1";
+/**
+ * Regression coverage for Notes-normalized HTML -> Markdown conversion.
+ *
+ * The fixtures encode the HTML shape Apple Notes returns and the Markdown the
+ * server currently emits. Routing through getNoteMarkdownById exercises the real
+ * Turndown pipeline (including the notesDivs rule) with AppleScript mocked to
+ * return the fixture body.
+ */
+describe("Notes-normalized HTML to Markdown", () => {
+    let manager;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        manager = new AppleNotesManager();
+    });
+    for (const fixture of NOTES_NORMALIZED_HTML_FIXTURES) {
+        it(`converts ${fixture.name} (${fixture.description})`, () => {
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: fixture.html });
+            const markdown = manager.getNoteMarkdownById(NOTE_ID);
+            expect(markdown).toBe(fixture.expectedMarkdown);
+        });
+    }
+    it("documents that a <div><br></div> spacer leaves a two-space line", () => {
+        mockExecuteAppleScript.mockReturnValue({
+            success: true,
+            output: "<div>A</div><div><br></div><div>B</div>",
+        });
+        const markdown = manager.getNoteMarkdownById(NOTE_ID);
+        // The spacer survives as a stray "  " line — the Markdown-side fingerprint of
+        // the whitespace-accumulation behavior CLAUDE.md warns about.
+        expect(markdown).toBe("A\n  \n\nB");
+    });
+    it("documents that <tt> is dropped, keeping only its text", () => {
+        mockExecuteAppleScript.mockReturnValue({
+            success: true,
+            output: "<div>Run <tt>npm install</tt> first.</div>",
+        });
+        const markdown = manager.getNoteMarkdownById(NOTE_ID);
+        expect(markdown).toBe("Run npm install first.");
+        expect(markdown).not.toContain("`");
+    });
+});

package/build/utils/noteMetadata.js

@@ -0,0 +1,135 @@
+/**
+ * Apple Notes Read-Only Metadata Reader [BETA]
+ *
+ * Reads note metadata that the AppleScript dictionary does not expose (pinned
+ * state, checklist flags, trash/recovery, preview snippet, password hint) by
+ * querying the NoteStore SQLite database directly.
+ *
+ * Unlike the note body (a gzipped protobuf blob in ZICNOTEDATA.ZDATA), these are
+ * plain scalar columns on ZICCLOUDSYNCINGOBJECT, so no protobuf decoding is
+ * needed — an ordinary SELECT is enough.
+ *
+ * BETA / safety:
+ * - The database is opened READ-ONLY (`sqlite3 -readonly`). This code never
+ *   writes to the live store; doing so would corrupt CloudKit sync state.
+ * - Requires Full Disk Access for the host process.
+ * - The schema changes between macOS releases, so the reader feature-detects
+ *   which columns exist (PRAGMA table_info) and only selects those.
+ *
+ * @module utils/noteMetadata
+ * @see TECHNICAL_NOTES.md#read-only-metadata-columns-verified-macos-27--notes-413
+ */
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+const NOTES_DB_PATH = path.join(os.homedir(), "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite");
+const FDA_MESSAGE = "Full Disk Access is required to read note metadata. " +
+    "Grant access in System Settings > Privacy & Security > Full Disk Access, " +
+    "then add and restart this application.";
+/**
+ * Friendly field name -> NoteStore column. This is a fixed allowlist; nothing
+ * here is built from user input, so the column names are never an injection
+ * vector. `bool` columns store 0/1; `text` columns store strings.
+ */
+const COLUMN_MAP = [
+    { key: "pinned", column: "ZISPINNED", type: "bool" },
+    { key: "hasChecklist", column: "ZHASCHECKLIST", type: "bool" },
+    { key: "hasChecklistInProgress", column: "ZHASCHECKLISTINPROGRESS", type: "bool" },
+    { key: "recoveringFromTrash", column: "ZISRECOVERINGFROMTRASH", type: "bool" },
+    { key: "passwordProtected", column: "ZISPASSWORDPROTECTED", type: "bool" },
+    { key: "passwordHint", column: "ZPASSWORDHINT", type: "text" },
+    { key: "snippet", column: "ZSNIPPET", type: "text" },
+    { key: "widgetSnippet", column: "ZWIDGETSNIPPET", type: "text" },
+    { key: "smartFolderQuery", column: "ZSMARTFOLDERQUERYJSON", type: "text" },
+];
+/**
+ * Runs a read-only sqlite3 query against the live NoteStore and returns trimmed
+ * stdout. Throws on failure (callers classify the error).
+ *
+ * Uses execFileSync with an argument array (no shell), so the database path's
+ * spaces and the query string are passed verbatim and shell metacharacters are
+ * never interpreted. The only dynamic value in any query is the note's primary
+ * key, which callers constrain to digits before it reaches here.
+ */
+function runSqlite(query) {
+    return execFileSync("sqlite3", ["-readonly", NOTES_DB_PATH, query], {
+        encoding: "utf8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+}
+/**
+ * Returns the set of column names present on ZICCLOUDSYNCINGOBJECT, so the
+ * reader can skip columns that do not exist on this macOS version.
+ */
+function presentColumns() {
+    const out = runSqlite("PRAGMA table_info(ZICCLOUDSYNCINGOBJECT);");
+    const cols = new Set();
+    for (const line of out.split("\n")) {
+        // Each row: cid|name|type|notnull|dflt_value|pk
+        const name = line.split("|")[1];
+        if (name)
+            cols.add(name);
+    }
+    return cols;
+}
+/**
+ * Reads read-only metadata for a note by its CoreData ID.
+ *
+ * @param noteId - CoreData URL identifier (e.g., "x-coredata://ABC/ICNote/p123")
+ * @returns Structured result with the metadata, an error type, and a message
+ */
+export function getNoteMetadata(noteId) {
+    const pkMatch = noteId.match(/\/p(\d+)$/);
+    if (!pkMatch) {
+        return {
+            metadata: null,
+            error: "invalid_id",
+            message: `Invalid note ID format: "${noteId}". Expected format: x-coredata://UUID/ICNote/pNNN`,
+        };
+    }
+    const pk = pkMatch[1];
+    if (!fs.existsSync(NOTES_DB_PATH)) {
+        return { metadata: null, error: "no_fda", message: FDA_MESSAGE };
+    }
+    try {
+        const available = presentColumns();
+        const selected = COLUMN_MAP.filter((c) => available.has(c.column));
+        if (selected.length === 0) {
+            // Schema has none of the known columns (very old or very new macOS).
+            return { metadata: {} };
+        }
+        const pairs = selected.map((c) => `'${c.key}', ${c.column}`).join(", ");
+        const row = runSqlite(`SELECT json_object(${pairs}) FROM ZICCLOUDSYNCINGOBJECT WHERE Z_PK = ${pk};`);
+        if (!row) {
+            return {
+                metadata: null,
+                error: "not_found",
+                message: `No note found in the database for ID "${noteId}".`,
+            };
+        }
+        const raw = JSON.parse(row);
+        const metadata = {};
+        for (const c of selected) {
+            const value = raw[c.key];
+            if (value === null || value === undefined)
+                continue;
+            if (c.type === "bool") {
+                metadata[c.key] = value === 1 || value === "1" || value === true;
+            }
+            else {
+                metadata[c.key] = String(value);
+            }
+        }
+        return { metadata: metadata };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("authorization denied") || message.includes("unable to open database")) {
+            return { metadata: null, error: "no_fda", message: FDA_MESSAGE };
+        }
+        console.error(`Failed to read note metadata: ${message}`);
+        return { metadata: null, error: "query_error", message: "Failed to read note metadata." };
+    }
+}

package/build/utils/noteMetadata.test.js

@@ -0,0 +1,106 @@
+/**
+ * Tests for the read-only note metadata reader.
+ *
+ * The NoteStore SQLite access is mocked, so these exercise the pk extraction,
+ * column feature-detection, JSON parsing, boolean coercion, and error
+ * classification without touching a real database.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+vi.mock("child_process", () => ({
+    execFileSync: vi.fn(),
+}));
+vi.mock("fs", () => ({
+    existsSync: vi.fn(() => true),
+}));
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import { getNoteMetadata } from "./noteMetadata.js";
+const mockExecFileSync = vi.mocked(execFileSync);
+const mockExistsSync = vi.mocked(existsSync);
+const NOTE_ID = "x-coredata://ABC/ICNote/p123";
+/** Builds a PRAGMA table_info dump from a list of column names. */
+function tableInfo(columns) {
+    return columns.map((name, i) => `${i}|${name}|INTEGER|0||0`).join("\n");
+}
+/** The query string is the third sqlite3 argument: [-readonly, dbPath, query]. */
+function queryOf(call) {
+    const args = call[1];
+    return args[2];
+}
+describe("getNoteMetadata", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockExistsSync.mockReturnValue(true);
+    });
+    it("rejects a malformed note id without touching the database", () => {
+        const result = getNoteMetadata("not-a-real-id");
+        expect(result.metadata).toBeNull();
+        expect(result.error).toBe("invalid_id");
+        expect(mockExecFileSync).not.toHaveBeenCalled();
+    });
+    it("reads pinned/checklist/snippet and coerces 0/1 to booleans", () => {
+        mockExecFileSync.mockImplementation((_cmd, args) => {
+            const query = args[2];
+            if (query.includes("table_info")) {
+                return tableInfo(["Z_PK", "ZISPINNED", "ZHASCHECKLIST", "ZSNIPPET", "ZPASSWORDHINT"]);
+            }
+            return JSON.stringify({
+                pinned: 1,
+                hasChecklist: 0,
+                snippet: "Hello world",
+                passwordHint: null,
+            });
+        });
+        const result = getNoteMetadata(NOTE_ID);
+        expect(result.error).toBeUndefined();
+        expect(result.metadata).toEqual({
+            pinned: true,
+            hasChecklist: false,
+            snippet: "Hello world",
+        });
+        // A NULL column (passwordHint) is omitted, not included as null.
+        expect(result.metadata).not.toHaveProperty("passwordHint");
+    });
+    it("only selects columns that exist on this schema", () => {
+        mockExecFileSync.mockImplementation((_cmd, args) => {
+            const query = args[2];
+            if (query.includes("table_info"))
+                return tableInfo(["Z_PK", "ZISPINNED"]);
+            return JSON.stringify({ pinned: 1 });
+        });
+        const result = getNoteMetadata(NOTE_ID);
+        expect(result.metadata).toEqual({ pinned: true });
+        // The SELECT must not reference a column the schema lacks.
+        const selectCall = mockExecFileSync.mock.calls.find((c) => queryOf(c).includes("json_object"));
+        expect(selectCall).toBeDefined();
+        expect(queryOf(selectCall)).toContain("ZISPINNED");
+        expect(queryOf(selectCall)).not.toContain("ZSNIPPET");
+    });
+    it("returns not_found when no row matches the primary key", () => {
+        mockExecFileSync.mockImplementation((_cmd, args) => {
+            const query = args[2];
+            if (query.includes("table_info"))
+                return tableInfo(["Z_PK", "ZISPINNED"]);
+            return "";
+        });
+        const result = getNoteMetadata(NOTE_ID);
+        expect(result.metadata).toBeNull();
+        expect(result.error).toBe("not_found");
+    });
+    it("classifies a Full Disk Access denial", () => {
+        mockExecFileSync.mockImplementation(() => {
+            throw new Error("Error: authorization denied");
+        });
+        const result = getNoteMetadata(NOTE_ID);
+        expect(result.metadata).toBeNull();
+        expect(result.error).toBe("no_fda");
+        expect(result.message).toContain("Full Disk Access");
+    });
+    it("returns no_fda when the database file is missing", () => {
+        mockExistsSync.mockReturnValue(false);
+        const result = getNoteMetadata(NOTE_ID);
+        expect(result.metadata).toBeNull();
+        expect(result.error).toBe("no_fda");
+        expect(mockExecFileSync).not.toHaveBeenCalled();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",