apple-notes-mcp 2.4.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.
 
 ---
@@ -706,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.

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";
@@ -1261,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/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.4.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",