apple-notes-mcp 1.4.3 → 2.0.0

package/build/services/attachmentSave.test.js

@@ -0,0 +1,85 @@
+/**
+ * Tests for save-attachment / fetch-attachment manager methods (#27).
+ * AppleScript is mocked; the filesystem side runs for real in a temp dir, with
+ * the mock writing the file the way Notes.app's `save` would.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { writeFileSync, mkdtempSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+vi.mock("@/utils/applescript.js", () => ({ executeAppleScript: vi.fn() }));
+vi.mock("@/utils/checklistParser.js", () => ({
+    getChecklistItems: vi.fn().mockReturnValue({ items: null }),
+}));
+import { AppleNotesManager } from "../services/appleNotesManager.js";
+import { executeAppleScript } from "../utils/applescript.js";
+const mockExec = vi.mocked(executeAppleScript);
+const F = "\x1f";
+let manager;
+const tmpDirs = [];
+beforeEach(() => {
+    vi.clearAllMocks();
+    manager = new AppleNotesManager();
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("saveAttachmentById (#27)", () => {
+    it("saves to an allowed path and returns metadata", () => {
+        const dir = mkdtempSync(join(tmpdir(), "anatt-"));
+        tmpDirs.push(dir);
+        const dest = join(dir, "photo.png");
+        mockExec.mockImplementation((script) => {
+            const m = script.match(/POSIX file "([^"]+)"/);
+            if (m)
+                writeFileSync(m[1], Buffer.from("PNGDATA"));
+            return { success: true, output: ["OK", "photo.png", "public.png"].join(F) };
+        });
+        const r = manager.saveAttachmentById("x-coredata://A/ICNote/p1", "att-1", dest);
+        expect(r.success).toBe(true);
+        expect(r.savedPath).toBe(dest);
+        expect(r.name).toBe("photo.png");
+        expect(r.contentType).toBe("public.png");
+    });
+    it("rejects an unsafe destination before running AppleScript", () => {
+        const r = manager.saveAttachmentById("x-coredata://A/ICNote/p1", "att-1", "/etc/evil.png");
+        expect(r.success).toBe(false);
+        expect(r.error).toMatch(/outside allowed/);
+        expect(mockExec).not.toHaveBeenCalled();
+    });
+    it("surfaces 'attachment not found' from AppleScript", () => {
+        const dest = join(tmpdir(), "nope.png");
+        mockExec.mockReturnValue({ success: true, output: ["ERR", "attachment not found"].join(F) });
+        const r = manager.saveAttachmentById("x-coredata://A/ICNote/p1", "missing", dest);
+        expect(r.success).toBe(false);
+        expect(r.error).toMatch(/not found/);
+    });
+    it("fails when Notes reports OK but no file was written", () => {
+        const dest = join(tmpdir(), "ghost-" + Date.now() + ".png");
+        mockExec.mockReturnValue({ success: true, output: ["OK", "x.png", "public.png"].join(F) });
+        const r = manager.saveAttachmentById("x-coredata://A/ICNote/p1", "att-1", dest);
+        expect(r.success).toBe(false);
+        expect(r.error).toMatch(/no file was written/);
+    });
+});
+describe("getAttachmentBase64ById (#27)", () => {
+    it("exports to a temp file and returns base64, cleaning up", () => {
+        mockExec.mockImplementation((script) => {
+            const m = script.match(/POSIX file "([^"]+)"/);
+            if (m)
+                writeFileSync(m[1], Buffer.from("hello-bytes"));
+            return { success: true, output: ["OK", "doc.pdf", "com.adobe.pdf"].join(F) };
+        });
+        const r = manager.getAttachmentBase64ById("x-coredata://A/ICNote/p1", "att-1");
+        expect(r.success).toBe(true);
+        expect(r.name).toBe("doc.pdf");
+        expect(r.bytes).toBe("hello-bytes".length);
+        expect(Buffer.from(r.base64 ?? "", "base64").toString()).toBe("hello-bytes");
+    });
+    it("returns the error when the save step fails", () => {
+        mockExec.mockReturnValue({ success: false, output: "", error: "Notes not running" });
+        const r = manager.getAttachmentBase64ById("x-coredata://A/ICNote/p1", "att-1");
+        expect(r.success).toBe(false);
+        expect(r.error).toMatch(/Notes not running/);
+    });
+});

package/build/services/fileConfig.js

@@ -0,0 +1,51 @@
+/**
+ * File-based configuration loader (#24).
+ *
+ * Some host apps (e.g. Claude Desktop) spawn the MCP server with a scrubbed
+ * environment and ignore the `env` block in their server config, so there's no
+ * way to pass `APPLE_NOTES_MCP_*` settings in. This loads them from a JSON file
+ * the host doesn't manage, merging into `process.env` WITHOUT overriding
+ * anything already set (so an explicit env still wins).
+ *
+ * Only non-secret config belongs here (e.g. APPLE_NOTES_MCP_MAX_BUFFER, DEBUG).
+ *
+ * Path: `APPLE_NOTES_MCP_CONFIG_FILE`, else
+ * `~/Library/Application Support/apple-notes-mcp/config.json`.
+ *
+ * @module services/fileConfig
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+export function fileConfigPath(env = process.env) {
+    const override = env.APPLE_NOTES_MCP_CONFIG_FILE;
+    if (override && override.trim())
+        return override.trim();
+    return join(homedir(), "Library", "Application Support", "apple-notes-mcp", "config.json");
+}
+/**
+ * Merge a JSON config file's string values into `env` for keys not already set.
+ * Returns the keys applied. Tolerates a missing/corrupt file.
+ */
+export function loadFileConfig(env = process.env, path = fileConfigPath(env)) {
+    const applied = [];
+    try {
+        if (!existsSync(path))
+            return applied;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return applied;
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v !== "string")
+                continue;
+            if (env[k] === undefined || env[k] === "") {
+                env[k] = v;
+                applied.push(k);
+            }
+        }
+    }
+    catch (e) {
+        console.error(`Failed to load apple-notes-mcp config file ${path}: ${String(e)}`);
+    }
+    return applied;
+}

package/build/services/fileConfig.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { loadFileConfig, fileConfigPath } from "../services/fileConfig.js";
+let dir;
+let file;
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "anmcp-cfg-"));
+    file = join(dir, "config.json");
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+describe("loadFileConfig (#24)", () => {
+    it("applies file values for keys not already in env", () => {
+        writeFileSync(file, JSON.stringify({ APPLE_NOTES_MCP_MAX_BUFFER: "1048576", DEBUG: "1" }));
+        const env = {};
+        const applied = loadFileConfig(env, file);
+        expect(env.APPLE_NOTES_MCP_MAX_BUFFER).toBe("1048576");
+        expect(env.DEBUG).toBe("1");
+        expect(applied.sort()).toEqual(["APPLE_NOTES_MCP_MAX_BUFFER", "DEBUG"]);
+    });
+    it("never overrides a value already set in the environment", () => {
+        writeFileSync(file, JSON.stringify({ APPLE_NOTES_MCP_MAX_BUFFER: "1" }));
+        const env = { APPLE_NOTES_MCP_MAX_BUFFER: "999" };
+        loadFileConfig(env, file);
+        expect(env.APPLE_NOTES_MCP_MAX_BUFFER).toBe("999");
+    });
+    it("treats empty-string env as unset and fills it", () => {
+        writeFileSync(file, JSON.stringify({ DEBUG: "1" }));
+        const env = { DEBUG: "" };
+        loadFileConfig(env, file);
+        expect(env.DEBUG).toBe("1");
+    });
+    it("ignores non-string values", () => {
+        writeFileSync(file, JSON.stringify({ A: "ok", B: 5, C: true }));
+        const env = {};
+        expect(loadFileConfig(env, file)).toEqual(["A"]);
+    });
+    it("tolerates a missing file and a corrupt file", () => {
+        expect(loadFileConfig({}, join(dir, "nope.json"))).toEqual([]);
+        writeFileSync(file, "{ not json");
+        expect(loadFileConfig({}, file)).toEqual([]);
+    });
+    it("defaults the path to the app-support dir, honoring the override", () => {
+        expect(fileConfigPath({})).toMatch(/apple-notes-mcp\/config\.json$/);
+        expect(fileConfigPath({ APPLE_NOTES_MCP_CONFIG_FILE: "/tmp/x.json" })).toBe("/tmp/x.json");
+    });
+});

package/build/tools/doctor.js

@@ -0,0 +1,50 @@
+import { hasFullDiskAccess } from "../utils/checklistParser.js";
+export function runDoctor(manager) {
+    const checks = [];
+    // 1. Notes.app reachability + Automation permission (existing health checks).
+    const hc = manager.healthCheck();
+    for (const c of hc.checks) {
+        checks.push({
+            name: `Notes.app: ${c.name}`,
+            status: c.passed ? "ok" : "fail",
+            detail: c.message,
+        });
+    }
+    // 2. Accounts.
+    try {
+        const accounts = manager.listAccounts();
+        checks.push({
+            name: "Accounts",
+            status: accounts.length > 0 ? "ok" : "warn",
+            detail: accounts.length > 0
+                ? `${accounts.length} account(s): ${accounts.map((a) => a.name).join(", ")}`
+                : "no Notes accounts found",
+        });
+    }
+    catch (e) {
+        checks.push({
+            name: "Accounts",
+            status: "fail",
+            detail: `could not list accounts: ${String(e)}`,
+        });
+    }
+    // 3. Full Disk Access — required for checklist state + checklist annotations.
+    const fda = hasFullDiskAccess();
+    checks.push({
+        name: "Full Disk Access",
+        status: fda ? "ok" : "warn",
+        detail: fda
+            ? "granted — checklist features available"
+            : "not granted — get-checklist-state and checklist annotations in get-note-markdown won't work. Grant in System Settings > Privacy & Security > Full Disk Access.",
+    });
+    const healthy = !checks.some((c) => c.status === "fail");
+    return { healthy, checks };
+}
+/** Render a DoctorReport as readable text. */
+export function formatDoctorReport(r) {
+    const icon = (s) => (s === "ok" ? "✅" : s === "warn" ? "⚠️ " : "❌");
+    const lines = [`🩺 apple-notes-mcp doctor — ${r.healthy ? "healthy" : "ISSUES FOUND"}`, ""];
+    for (const c of r.checks)
+        lines.push(`${icon(c.status)} ${c.name}: ${c.detail}`);
+    return lines.join("\n");
+}

package/build/tools/doctor.test.js

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi } from "vitest";
+vi.mock("@/utils/checklistParser.js", () => ({ hasFullDiskAccess: vi.fn(() => true) }));
+import { runDoctor, formatDoctorReport } from "../tools/doctor.js";
+import { hasFullDiskAccess } from "../utils/checklistParser.js";
+function fakeMgr(over = {}) {
+    return {
+        healthCheck: () => ({
+            healthy: true,
+            checks: [{ name: "reachable", passed: true, message: "Notes.app responded" }],
+        }),
+        listAccounts: () => [{ name: "iCloud" }, { name: "Gmail" }],
+        ...over,
+    };
+}
+describe("runDoctor (#22)", () => {
+    it("reports accounts + Full Disk Access and stays healthy on warnings", () => {
+        const r = runDoctor(fakeMgr());
+        expect(r.healthy).toBe(true);
+        expect(r.checks.find((c) => c.name === "Accounts")?.status).toBe("ok");
+        expect(r.checks.find((c) => c.name === "Accounts")?.detail).toMatch(/iCloud, Gmail/);
+        expect(r.checks.find((c) => c.name === "Full Disk Access")?.status).toBe("ok");
+    });
+    it("warns (not fails) when Full Disk Access is not granted", () => {
+        vi.mocked(hasFullDiskAccess).mockReturnValueOnce(false);
+        const r = runDoctor(fakeMgr());
+        const fda = r.checks.find((c) => c.name === "Full Disk Access");
+        expect(fda?.status).toBe("warn");
+        expect(fda?.detail).toMatch(/Full Disk Access/);
+        expect(r.healthy).toBe(true);
+    });
+    it("is unhealthy when a Notes.app check fails", () => {
+        const r = runDoctor(fakeMgr({
+            healthCheck: () => ({
+                healthy: false,
+                checks: [{ name: "permission", passed: false, message: "not authorized" }],
+            }),
+        }));
+        expect(r.healthy).toBe(false);
+        expect(formatDoctorReport(r)).toMatch(/ISSUES FOUND/);
+        expect(formatDoctorReport(r)).toMatch(/❌ Notes\.app: permission/);
+    });
+});

package/build/tools/resourcesAndPrompts.js

@@ -0,0 +1,70 @@
+/**
+ * MCP resources & prompts for apple-notes (#23).
+ *
+ * Resources expose read-only views agents can attach as context without a tool
+ * round-trip (accounts, folders, stats, and a note-by-id template). Prompts are
+ * reusable starting points for common Notes workflows.
+ *
+ * @module tools/resourcesAndPrompts
+ */
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+const json = (uri, data) => ({
+    contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(data, null, 2) }],
+});
+export function registerResourcesAndPrompts(server, manager) {
+    // --- Resources ---
+    server.resource("accounts", "notes://accounts", (uri) => json(uri, { accounts: manager.listAccounts() }));
+    server.resource("folders", "notes://folders", (uri) => {
+        const data = manager
+            .listAccounts()
+            .map((a) => ({ account: a.name, folders: manager.listFolders(a.name) }));
+        return json(uri, { accounts: data });
+    });
+    server.resource("stats", "notes://stats", (uri) => json(uri, manager.getNotesStats()));
+    server.resource("note", new ResourceTemplate("notes://note/{id}", { list: undefined }), (uri, variables) => {
+        const id = decodeURIComponent(String(variables.id));
+        const markdown = manager.getNoteMarkdownById(id);
+        return {
+            contents: [{ uri: uri.href, mimeType: "text/markdown", text: markdown || "(not found)" }],
+        };
+    });
+    // --- Prompts ---
+    server.prompt("find-note", "Search Apple Notes for a topic and summarize the best match", { topic: z.string().describe("What to search for") }, ({ topic }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Search my Apple Notes for "${topic}" with the search-notes tool (set searchContent: true). Open the most relevant result with get-note-content and give me a concise summary plus its note id.`,
+                },
+            },
+        ],
+    }));
+    server.prompt("weekly-review", "Review notes changed recently and surface follow-ups", () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "Use get-notes-stats to see how many notes changed in the last 7 days, then search-notes (searchContent: true, modifiedSince: the date 7 days ago) to list them. Summarize the themes and call out any open action items or checklists I should follow up on.",
+                },
+            },
+        ],
+    }));
+    server.prompt("new-meeting-note", "Draft and create a structured meeting note", {
+        subject: z.string().describe("Meeting subject"),
+        attendees: z.string().optional().describe("Comma-separated attendees"),
+        folder: z.string().optional().describe("Target folder"),
+    }, ({ subject, attendees, folder }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Create an Apple Note titled "${subject}" ${folder ? `in folder "${folder}" ` : ""}using create-note (format: html). Include sections for Attendees${attendees ? ` (${attendees})` : ""}, Agenda, Discussion, and Action Items. Render Action Items as a plain bulleted list and remind me I can convert it to a checklist in Notes with ⇧⌘L.`,
+                },
+            },
+        ],
+    }));
+}

package/build/tools/resourcesAndPrompts.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from "vitest";
+import { registerResourcesAndPrompts } from "../tools/resourcesAndPrompts.js";
+class FakeServer {
+    resources = new Map();
+    prompts = new Map();
+    resource(name, uriOrTemplate, cb) {
+        this.resources.set(name, { uriOrTemplate, cb });
+    }
+    prompt(name, ...rest) {
+        this.prompts.set(name, rest[rest.length - 1]);
+    }
+}
+function fakeMgr() {
+    return {
+        listAccounts: () => [{ name: "iCloud" }],
+        listFolders: vi.fn(() => [{ name: "Notes" }]),
+        getNotesStats: () => ({
+            totalNotes: 1,
+            accounts: [],
+            recentlyModified: { last24h: 0, last7d: 0, last30d: 0 },
+        }),
+        getNoteMarkdownById: vi.fn(() => "# Hello"),
+    };
+}
+describe("registerResourcesAndPrompts (#23)", () => {
+    it("registers the expected resources and prompts", () => {
+        const s = new FakeServer();
+        registerResourcesAndPrompts(s, fakeMgr());
+        expect([...s.resources.keys()].sort()).toEqual(["accounts", "folders", "note", "stats"]);
+        expect([...s.prompts.keys()].sort()).toEqual([
+            "find-note",
+            "new-meeting-note",
+            "weekly-review",
+        ]);
+    });
+    it("accounts/folders/stats resources return JSON", () => {
+        const s = new FakeServer();
+        registerResourcesAndPrompts(s, fakeMgr());
+        const acc = s.resources.get("accounts").cb(new URL("notes://accounts"), {});
+        expect(JSON.parse(acc.contents[0].text)).toEqual({ accounts: [{ name: "iCloud" }] });
+        const fol = s.resources.get("folders").cb(new URL("notes://folders"), {});
+        expect(JSON.parse(fol.contents[0].text).accounts[0].account).toBe("iCloud");
+        const st = s.resources.get("stats").cb(new URL("notes://stats"), {});
+        expect(JSON.parse(st.contents[0].text).totalNotes).toBe(1);
+    });
+    it("note template resolves the id and returns markdown", () => {
+        const s = new FakeServer();
+        const mgr = fakeMgr();
+        registerResourcesAndPrompts(s, mgr);
+        const out = s.resources.get("note").cb(new URL("notes://note/abc%20def"), { id: "abc%20def" });
+        expect(mgr.getNoteMarkdownById).toHaveBeenCalledWith("abc def");
+        expect(out.contents[0].text).toBe("# Hello");
+    });
+    it("prompts produce user messages including their args", () => {
+        const s = new FakeServer();
+        registerResourcesAndPrompts(s, fakeMgr());
+        expect(s.prompts.get("find-note")({ topic: "taxes" }).messages[0].content.text).toMatch(/taxes/);
+        expect(s.prompts.get("weekly-review")({}).messages[0].content.text).toMatch(/last 7 days/);
+        const mtg = s.prompts.get("new-meeting-note")({ subject: "Q3 Plan", attendees: "Rob, Sam" });
+        expect(mtg.messages[0].content.text).toMatch(/Q3 Plan/);
+        expect(mtg.messages[0].content.text).toMatch(/Rob, Sam/);
+    });
+});

package/build/utils/applescript.js

@@ -13,6 +13,41 @@ import { execSync, spawnSync } from "child_process";
  * searches on large note collections. Can be overridden per-call.
  */
 const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Output cap for osascript. Node's execSync defaults to 1 MB, which a large
+ * Notes library (export-notes-json, full-library stat scans, long-note content)
+ * can blow past — execSync then throws ENOBUFS and the failure surfaces as an
+ * empty result. 64 MB headroom, overridable via APPLE_NOTES_MCP_MAX_BUFFER. (#16)
+ */
+const DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+function getMaxBuffer() {
+    const raw = process.env.APPLE_NOTES_MCP_MAX_BUFFER;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_MAX_BUFFER_BYTES;
+}
+/**
+ * Headroom (ms) between the in-AppleScript `with timeout` and the outer
+ * osascript process timeout. The script-level timeout must fire first so
+ * Notes.app aborts from inside its own AppleScript dispatch — releasing the
+ * event queue — before Node SIGKILLs osascript. Killing osascript alone does
+ * not stop work already dispatched into Notes.app, which is what wedges it for
+ * subsequent calls. (#17)
+ */
+const SCRIPT_TIMEOUT_HEADROOM_MS = 5000;
+/**
+ * Wrap a script body in an AppleScript `with timeout` block so an Apple Event
+ * that honors timeouts aborts cleanly rather than holding Notes.app's
+ * single-threaded dispatch open. Set below the process timeout so the in-app
+ * abort wins the race against the outer SIGKILL. (#17)
+ */
+function wrapWithTimeout(script, processTimeoutMs) {
+    const seconds = Math.max(1, Math.ceil((processTimeoutMs - SCRIPT_TIMEOUT_HEADROOM_MS) / 1000));
+    return `with timeout of ${seconds} seconds\n${script}\nend timeout`;
+}
 /**
  * Default retry configuration.
  * - 1 attempt means no retries (default behavior)
@@ -274,9 +309,11 @@ export function executeAppleScript(script, options = {}) {
     }
     // Prepare the script:
     // 1. Trim leading/trailing whitespace (cosmetic)
-    // 2. Preserve internal newlines (required for AppleScript syntax)
-    // 3. Escape for shell execution
-    const preparedScript = escapeForShell(script.trim());
+    // 2. Wrap in `with timeout` so Notes.app aborts cleanly from inside its own
+    //    dispatch before the outer process SIGKILL (#17)
+    // 3. Preserve internal newlines (required for AppleScript syntax)
+    // 4. Escape for shell execution
+    const preparedScript = escapeForShell(wrapWithTimeout(script.trim(), timeoutMs));
     // Build the osascript command
     // We use single quotes to wrap the script, which is why we escape
     // single quotes within the script itself
@@ -297,6 +334,13 @@ export function executeAppleScript(script, options = {}) {
             const output = execSync(command, {
                 encoding: "utf8",
                 timeout: timeoutMs,
+                // SIGKILL (not the default SIGTERM): a wedged osascript blocked on an
+                // unresponsive Notes.app can ignore SIGTERM and leak, piling up and
+                // worsening contention. SIGKILL guarantees reaping on timeout. (#17)
+                killSignal: "SIGKILL",
+                // Raise the output cap above Node's 1 MB default so large exports /
+                // long notes aren't truncated into an ENOBUFS failure. (#16)
+                maxBuffer: getMaxBuffer(),
                 // Capture stderr separately to get error details
                 stdio: ["pipe", "pipe", "pipe"],
             });

package/build/utils/applescript.test.js

@@ -4,7 +4,7 @@
  * These tests mock the child_process.execSync function to avoid
  * requiring actual AppleScript execution during testing.
  */
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { execSync } from "child_process";
 import { executeAppleScript } from "./applescript.js";
 // Mock the child_process module
@@ -53,6 +53,34 @@ describe("executeAppleScript", () => {
             expect(calledCommand).toContain("Rob'\\''s");
         });
     });
+    describe("hardened executor (#16/#17)", () => {
+        afterEach(() => {
+            delete process.env.APPLE_NOTES_MCP_MAX_BUFFER;
+        });
+        it("wraps the script in `with timeout` so Notes.app aborts cleanly", () => {
+            mockExecSync.mockReturnValue("ok");
+            executeAppleScript("get name of notes", { timeoutMs: 30000 });
+            const cmd = mockExecSync.mock.calls[0][0];
+            expect(cmd).toContain("with timeout of");
+            expect(cmd).toContain("end timeout");
+            // 30s process timeout − 5s headroom = 25s script timeout
+            expect(cmd).toContain("with timeout of 25 seconds");
+        });
+        it("passes SIGKILL and a large maxBuffer to execSync", () => {
+            mockExecSync.mockReturnValue("ok");
+            executeAppleScript("get name of notes");
+            const opts = mockExecSync.mock.calls[0][1];
+            expect(opts.killSignal).toBe("SIGKILL");
+            expect(opts.maxBuffer).toBe(64 * 1024 * 1024);
+        });
+        it("honors APPLE_NOTES_MCP_MAX_BUFFER override", () => {
+            process.env.APPLE_NOTES_MCP_MAX_BUFFER = "1048576";
+            mockExecSync.mockReturnValue("ok");
+            executeAppleScript("get name of notes");
+            const opts = mockExecSync.mock.calls[0][1];
+            expect(opts.maxBuffer).toBe(1048576);
+        });
+    });
     describe("error handling", () => {
         it("returns error result when execution fails", () => {
             // Arrange: Mock an AppleScript execution failure

package/build/utils/attachmentFs.js

@@ -0,0 +1,59 @@
+/**
+ * Filesystem helpers for saving / fetching note attachments (#27).
+ *
+ * Notes.app exports an attachment to a path via AppleScript `save`. These helpers
+ * keep that safe (no writing outside sensible roots, no path traversal) and
+ * provide a base64 read for the fetch-attachment tool.
+ *
+ * @module utils/attachmentFs
+ */
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "fs";
+import { isAbsolute, resolve, sep } from "path";
+import { homedir, tmpdir } from "os";
+/** Roots an attachment may be written to. */
+export function allowedSaveRoots() {
+    return [resolve(homedir()), resolve(tmpdir()), "/Volumes", "/private/var/folders", "/tmp"];
+}
+/**
+ * Validate a user-supplied destination path. Returns the resolved absolute path,
+ * or throws if it is relative or escapes the allowed roots.
+ */
+export function assertSafeSavePath(p, roots = allowedSaveRoots()) {
+    if (!p || !p.trim())
+        throw new Error("A destination path is required.");
+    if (!isAbsolute(p))
+        throw new Error(`Destination path must be absolute: "${p}"`);
+    const abs = resolve(p);
+    const ok = roots.some((r) => abs === r || abs.startsWith(r.endsWith(sep) ? r : r + sep));
+    if (!ok) {
+        throw new Error(`Refusing to write outside allowed locations (home, temp, /Volumes): "${abs}"`);
+    }
+    return abs;
+}
+/** Read a file as base64. */
+export function readFileBase64(p) {
+    return readFileSync(p).toString("base64");
+}
+/** Byte size of a file (0 if missing). */
+export function fileSize(p) {
+    try {
+        return statSync(p).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Make a private temp dir for a one-shot attachment export; caller cleans up. */
+export function makeTempDir() {
+    return mkdtempSync(resolve(tmpdir(), "apple-notes-att-"));
+}
+/** Remove a temp dir tree, ignoring errors. */
+export function cleanupTempDir(dir) {
+    try {
+        if (existsSync(dir))
+            rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}

package/build/utils/attachmentFs.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { writeFileSync, existsSync, mkdtempSync } from "fs";
+import { homedir, tmpdir } from "os";
+import { join } from "path";
+import { assertSafeSavePath, readFileBase64, fileSize, makeTempDir, cleanupTempDir, allowedSaveRoots, } from "../utils/attachmentFs.js";
+const dirs = [];
+afterEach(() => dirs.splice(0).forEach(cleanupTempDir));
+describe("assertSafeSavePath (#27)", () => {
+    it("accepts absolute paths under the temp dir and home dir", () => {
+        const p = join(tmpdir(), "x.png");
+        expect(assertSafeSavePath(p)).toBe(p);
+        const h = join(homedir(), "Downloads", "x.png");
+        expect(assertSafeSavePath(h)).toBe(h);
+    });
+    it("rejects empty, relative, and out-of-root paths", () => {
+        expect(() => assertSafeSavePath("")).toThrow(/required/);
+        expect(() => assertSafeSavePath("relative/x.png")).toThrow(/absolute/);
+        expect(() => assertSafeSavePath("/etc/passwd")).toThrow(/outside allowed/);
+    });
+    it("blocks traversal that escapes an allowed root", () => {
+        expect(() => assertSafeSavePath(join(tmpdir(), "..", "..", "etc", "x"))).toThrow(/outside allowed/);
+    });
+    it("exposes the allowed roots", () => {
+        expect(allowedSaveRoots()).toEqual(expect.arrayContaining(["/Volumes"]));
+    });
+});
+describe("base64 / size / temp helpers (#27)", () => {
+    it("reads a file as base64 and reports its size", () => {
+        const dir = mkdtempSync(join(tmpdir(), "anatt-"));
+        dirs.push(dir);
+        const f = join(dir, "f.bin");
+        writeFileSync(f, Buffer.from("hello"));
+        expect(readFileBase64(f)).toBe(Buffer.from("hello").toString("base64"));
+        expect(fileSize(f)).toBe(5);
+    });
+    it("fileSize returns 0 for a missing file", () => {
+        expect(fileSize(join(tmpdir(), "definitely-missing-xyz.bin"))).toBe(0);
+    });
+    it("makeTempDir creates a dir and cleanupTempDir removes it (idempotent)", () => {
+        const dir = makeTempDir();
+        expect(existsSync(dir)).toBe(true);
+        cleanupTempDir(dir);
+        expect(existsSync(dir)).toBe(false);
+        expect(() => cleanupTempDir(dir)).not.toThrow();
+    });
+});

package/build/utils/jxa.js

@@ -14,6 +14,21 @@
  * @module utils/jxa
  */
 import { execSync } from "child_process";
+/**
+ * Output cap for osascript (JXA). Mirrors the AppleScript executor — Node's 1 MB
+ * default truncates large JXA output into an ENOBUFS failure. 64 MB default,
+ * overridable via APPLE_NOTES_MCP_MAX_BUFFER. (#16)
+ */
+const DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+function getMaxBuffer() {
+    const raw = process.env.APPLE_NOTES_MCP_MAX_BUFFER;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_MAX_BUFFER_BYTES;
+}
 const DEFAULT_TIMEOUT_MS = 30000;
 /**
  * Escapes a string for safe inclusion in a JXA script.
@@ -79,6 +94,8 @@ export function executeJXA(script, options = {}) {
         const output = execSync(command, {
             encoding: "utf8",
             timeout: timeoutMs,
+            killSignal: "SIGKILL", // reap a wedged osascript reliably (#17)
+            maxBuffer: getMaxBuffer(), // avoid ENOBUFS truncation on large output (#16)
             stdio: ["pipe", "pipe", "pipe"],
         });
         return {