apple-notes-mcp 1.1.0

package/build/types.js

@@ -0,0 +1,13 @@
+/**
+ * Type Definitions for Apple Notes MCP Server
+ *
+ * This module contains all TypeScript interfaces and types used throughout
+ * the Apple Notes MCP server. These types model:
+ *
+ * - Apple Notes data structures (notes, folders, accounts)
+ * - AppleScript execution results
+ * - MCP tool parameters
+ *
+ * @module types
+ */
+export {};

package/build/utils/applescript.js

@@ -0,0 +1,141 @@
+/**
+ * AppleScript Execution Utilities
+ *
+ * This module provides a safe interface for executing AppleScript commands
+ * on macOS. It handles script execution, error capture, and result parsing.
+ *
+ * @module utils/applescript
+ */
+import { execSync } from "child_process";
+/**
+ * Maximum execution time for AppleScript commands in milliseconds.
+ * Apple Notes operations are typically fast, but complex searches
+ * or operations on large note collections may take longer.
+ */
+const EXECUTION_TIMEOUT_MS = 10000;
+/**
+ * Escapes a string for safe inclusion in a shell command.
+ *
+ * When passing AppleScript to osascript via shell, we need to handle
+ * the interaction between shell quoting and AppleScript string literals.
+ * This function escapes single quotes since we wrap the script in single quotes.
+ *
+ * @param script - The raw AppleScript code
+ * @returns Shell-safe version of the script
+ *
+ * @example
+ * // Input: tell app "Notes" to get note "Rob's Note"
+ * // Output: tell app "Notes" to get note "Rob'\''s Note"
+ */
+function escapeForShell(script) {
+    // Replace single quotes with: end quote, escaped quote, start quote
+    // This is the standard shell escaping pattern for single-quoted strings
+    return script.replace(/'/g, "'\\''");
+}
+/**
+ * Parses error output from osascript to extract meaningful error messages.
+ *
+ * osascript errors typically include execution error numbers and descriptions.
+ * This function attempts to extract the human-readable portion.
+ *
+ * @param errorOutput - Raw error string from execSync
+ * @returns Cleaned error message
+ */
+function parseErrorMessage(errorOutput) {
+    // Check for common AppleScript error patterns
+    const executionError = errorOutput.match(/execution error: (.+?)(?:\s*\(-?\d+\))?$/m);
+    if (executionError) {
+        return executionError[1].trim();
+    }
+    // Check for "not found" type errors
+    const notFoundError = errorOutput.match(/Can't get (.+?)\./);
+    if (notFoundError) {
+        return `Not found: ${notFoundError[1]}`;
+    }
+    // Return cleaned version of original error
+    return errorOutput.trim() || "Unknown AppleScript error";
+}
+/**
+ * Executes an AppleScript command and returns a structured result.
+ *
+ * This function serves as the bridge between TypeScript and macOS AppleScript.
+ * It handles the complexity of shell escaping, execution, and error handling
+ * so that calling code can work with clean TypeScript interfaces.
+ *
+ * The script is executed synchronously via the `osascript` command-line tool.
+ * Multi-line scripts are supported and preserved (important for AppleScript
+ * tell blocks and repeat loops).
+ *
+ * @param script - The AppleScript code to execute
+ * @returns A result object with success status and output or error message
+ *
+ * @example
+ * ```typescript
+ * const result = executeAppleScript(`
+ *   tell application "Notes"
+ *     get name of every note
+ *   end tell
+ * `);
+ *
+ * if (result.success) {
+ *   console.log("Notes:", result.output);
+ * } else {
+ *   console.error("Failed:", result.error);
+ * }
+ * ```
+ */
+export function executeAppleScript(script) {
+    // Validate input - empty scripts are likely programmer errors
+    if (!script || !script.trim()) {
+        return {
+            success: false,
+            output: "",
+            error: "Cannot execute empty AppleScript",
+        };
+    }
+    // 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());
+    // Build the osascript command
+    // We use single quotes to wrap the script, which is why we escape
+    // single quotes within the script itself
+    const command = `osascript -e '${preparedScript}'`;
+    try {
+        // Execute synchronously - MCP tools are inherently synchronous
+        // and Apple Notes operations are fast enough that async isn't needed
+        const output = execSync(command, {
+            encoding: "utf8",
+            timeout: EXECUTION_TIMEOUT_MS,
+            // Capture stderr separately to get error details
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return {
+            success: true,
+            output: output.trim(),
+        };
+    }
+    catch (error) {
+        // execSync throws on non-zero exit codes
+        // The error object contains stderr output with AppleScript error details
+        let errorMessage;
+        if (error instanceof Error) {
+            // Node's ExecException includes stderr in the message
+            errorMessage = parseErrorMessage(error.message);
+        }
+        else if (typeof error === "string") {
+            errorMessage = parseErrorMessage(error);
+        }
+        else {
+            errorMessage = "AppleScript execution failed with unknown error";
+        }
+        // Log for debugging (MCP servers typically run in terminal)
+        console.error(`AppleScript error: ${errorMessage}`);
+        return {
+            success: false,
+            output: "",
+            error: errorMessage,
+        };
+    }
+}

package/build/utils/applescript.test.js

@@ -0,0 +1,129 @@
+/**
+ * Tests for AppleScript execution utilities
+ *
+ * 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 { execSync } from "child_process";
+import { executeAppleScript } from "./applescript.js";
+// Mock the child_process module
+vi.mock("child_process", () => ({
+    execSync: vi.fn(),
+}));
+const mockExecSync = vi.mocked(execSync);
+describe("executeAppleScript", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe("successful execution", () => {
+        it("returns success result with trimmed output", () => {
+            // Arrange: Mock a successful AppleScript execution
+            mockExecSync.mockReturnValue("  Note Title  \n");
+            // Act: Execute a simple script
+            const result = executeAppleScript('tell app "Notes" to get name of note 1');
+            // Assert: Output should be trimmed
+            expect(result.success).toBe(true);
+            expect(result.output).toBe("Note Title");
+            expect(result.error).toBeUndefined();
+        });
+        it("preserves newlines within the script for AppleScript syntax", () => {
+            mockExecSync.mockReturnValue("success");
+            // Multi-line AppleScript with tell blocks
+            const script = `
+        tell application "Notes"
+          tell account "iCloud"
+            get notes
+          end tell
+        end tell
+      `;
+            executeAppleScript(script);
+            // Verify the script was passed with newlines preserved
+            const calledCommand = mockExecSync.mock.calls[0][0];
+            expect(calledCommand).toContain("tell application");
+            expect(calledCommand).toContain("end tell");
+        });
+        it("escapes single quotes in the script for shell safety", () => {
+            mockExecSync.mockReturnValue("content");
+            // Script containing a single quote (e.g., in a note title)
+            executeAppleScript('get note "Rob\'s Notes"');
+            // Verify the quote was escaped for shell
+            const calledCommand = mockExecSync.mock.calls[0][0];
+            expect(calledCommand).toContain("Rob'\\''s");
+        });
+    });
+    describe("error handling", () => {
+        it("returns error result when execution fails", () => {
+            // Arrange: Mock an AppleScript execution failure
+            mockExecSync.mockImplementation(() => {
+                throw new Error("execution error: Can't get note. (-1728)");
+            });
+            // Act: Try to execute a script that will fail
+            const result = executeAppleScript('get note "Nonexistent"');
+            // Assert: Should return structured error
+            expect(result.success).toBe(false);
+            expect(result.output).toBe("");
+            expect(result.error).toBeDefined();
+        });
+        it("parses execution error messages cleanly", () => {
+            mockExecSync.mockImplementation(() => {
+                throw new Error("execution error: Note not found (-1728)");
+            });
+            const result = executeAppleScript("get note 1");
+            // Should extract the meaningful part of the error
+            expect(result.error).toBe("Note not found");
+        });
+        it("handles 'not found' error patterns", () => {
+            mockExecSync.mockImplementation(() => {
+                throw new Error('Can\'t get note "Missing".');
+            });
+            const result = executeAppleScript('get note "Missing"');
+            expect(result.error).toContain("Not found");
+        });
+        it("handles non-Error exceptions gracefully", () => {
+            mockExecSync.mockImplementation(() => {
+                throw "string error"; // Some code throws strings
+            });
+            const result = executeAppleScript("some script");
+            expect(result.success).toBe(false);
+            expect(result.error).toBe("string error");
+        });
+        it("handles unknown error types", () => {
+            mockExecSync.mockImplementation(() => {
+                throw { weird: "object" }; // Unusual but possible
+            });
+            const result = executeAppleScript("some script");
+            expect(result.success).toBe(false);
+            expect(result.error).toBe("AppleScript execution failed with unknown error");
+        });
+    });
+    describe("input validation", () => {
+        it("returns error for empty script", () => {
+            const result = executeAppleScript("");
+            expect(result.success).toBe(false);
+            expect(result.error).toBe("Cannot execute empty AppleScript");
+            expect(mockExecSync).not.toHaveBeenCalled();
+        });
+        it("returns error for whitespace-only script", () => {
+            const result = executeAppleScript("   \n\t  ");
+            expect(result.success).toBe(false);
+            expect(result.error).toBe("Cannot execute empty AppleScript");
+            expect(mockExecSync).not.toHaveBeenCalled();
+        });
+    });
+    describe("execution options", () => {
+        it("uses correct timeout setting", () => {
+            mockExecSync.mockReturnValue("ok");
+            executeAppleScript("test");
+            const options = mockExecSync.mock.calls[0][1];
+            expect(options.timeout).toBe(10000); // 10 second timeout
+        });
+        it("uses UTF-8 encoding for output", () => {
+            mockExecSync.mockReturnValue("日本語テスト");
+            const result = executeAppleScript("test");
+            expect(result.output).toBe("日本語テスト");
+            const options = mockExecSync.mock.calls[0][1];
+            expect(options.encoding).toBe("utf8");
+        });
+    });
+});

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "apple-notes-mcp",
+  "version": "1.1.0",
+  "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "start": "node build/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "ESLINT_USE_FLAT_CONFIG=false eslint src --ext .ts",
+    "lint:fix": "ESLINT_USE_FLAT_CONFIG=false eslint src --ext .ts --fix",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "apple-notes",
+    "claude",
+    "ai",
+    "applescript",
+    "macos",
+    "notes",
+    "model-context-protocol"
+  ],
+  "author": "Rob Sweet <rob@superiortech.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sweetrb/mcp-apple-notes.git"
+  },
+  "homepage": "https://github.com/sweetrb/mcp-apple-notes#readme",
+  "bugs": {
+    "url": "https://github.com/sweetrb/mcp-apple-notes/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.4.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0",
+    "tsc-alias": "^1.8.10",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "volta": {
+    "node": "22.13.1"
+  }
+}