Apple Notes MCP

Instructions

Implementation Reference

• src/notes.ts:90-114 (handler)

  The actual implementation of deleteFolder function that executes the folder deletion logic using AppleScript/JXA. It parses the nested folder path, navigates through parent folders, and deletes the target folder if it exists.

  export async function deleteFolder(path: string): Promise<boolean> {
    const parts = path.split("/").filter(Boolean);
    if (parts.length === 0) throw new Error("empty folder path");
    const escAS = (s: string) => s.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"");
    const lines: string[] = [
      'tell application "Notes"',
      '  set targetAcc to default account'
    ];
    let chain = 'targetAcc';
    for (let i = 0; i < parts.length - 1; i++) {
      const name = escAS(parts[i]);
      lines.push(`  if not (exists folder "${name}" of ${chain}) then error "Folder path not found"`);
      lines.push(`  set parentFolder to folder "${name}" of ${chain}`);
      chain = 'parentFolder';
    }
    const leaf = escAS(parts[parts.length - 1]);
    lines.push(`  if (exists folder "${leaf}" of ${chain}) then delete folder "${leaf}" of ${chain}`);
    lines.push('end tell');
    try {
      await runAppleScript(lines.join("\n"));
      return true;
    } catch {
      return false;
    }
  }

• src/index.ts:101-114 (registration)

  Tool registration for 'folders.delete' with input schema (path string), output schema (ok boolean), and handler that wraps deleteFolder in guardWrite for safe mode protection.

  server.registerTool(
    "folders.delete",
    {
      title: "Delete Folder",
      description: "Delete a folder by nested path (e.g., 'parent/child').",
      inputSchema: z.object({ path: z.string() }),
      outputSchema: z.object({ ok: z.boolean() }),
      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
    },
    async (args) => {
      const ok = await guardWrite(() => deleteFolder(args.path));
      return { content: [], structuredContent: { ok } };
    }
  );

• src/index.ts:29-35 (helper)

  guardWrite helper function that enforces safe mode by blocking write operations when SAFE_MODE flag is enabled.

  let SAFE_MODE = ["1", "true", "yes"].includes(String(process.env.NOTES_MCP_SAFE || "").toLowerCase());
  function guardWrite<T>(fn: () => Promise<T> | T): Promise<T> | T {
    if (SAFE_MODE) {
      throw new Error("Safe mode enabled: write operations are disabled");
    }
    return fn();
  }

• src/notes.ts:3-7 (schema)

  FolderInfo interface defining the structure for folder data including id, name, and account fields.

  export interface FolderInfo {
    id: string;
    name: string;
    account: string;
  }