omnifocus-mcp-enhanced 1.7.0 → 1.9.0

package/README.md

@@ -44,6 +44,8 @@ Want to see where the project is heading next? See the [roadmap](docs/roadmap/20
 
 ## 🆕 Latest Release
 
+- **v1.9.0** - Added 3 productivity tools: `append_to_note` (append text to a task/project note without overwriting), `count_tasks` (fast "how many" aggregate queries with a status breakdown, using the same filters as `filter_tasks`), and `duplicate_task` (clone a task with or without its subtasks, optionally renamed).
+- **v1.8.0** - Added full **Folder Management** support: `add_folder`, `edit_folder`, `remove_folder`, `list_folders`, and `get_folder`. Create nested folder hierarchies, rename/move folders (with cycle protection), and inspect folder contents (child projects + subfolders). Note: removing a folder permanently deletes all projects and tasks it contains.
 - **v1.7.0** - Added OmniFocus 4.7+ repeat rule support via `set_repetition_rule` (ICS rule strings, schedule type, anchor date, catch-up, end date, repetition count), mutually exclusive tag support via `exclusiveTags` on add/edit tools, and improved planned-date editing tests.
 - **v1.6.10** - Fixed Inbox task completion via `edit_item`, fixed AppleScript special-character handling for apostrophes/backslashes, fixed JSON result escaping for special characters, and clarified `batch_add_items` / `mcporter` usage with working examples.
 - **v1.6.9** - Added task attachment support: `get_task_by_id` now lists attachment metadata, `dump_database` exports attachment/link metadata, and new `read_task_attachment` returns image attachments as MCP image content when possible.
@@ -65,6 +67,7 @@ Want to see where the project is heading next? See the [roadmap](docs/roadmap/20
 - **🎯 Batch Operations** - Add/remove multiple tasks efficiently
 - **📊 Smart Querying** - Find tasks by ID, name, or complex criteria
 - **🔄 Full CRUD Operations** - Create, read, update, delete tasks and projects
+- **📁 Folder Management** - Full CRUD for folders with nested hierarchy, move/rename, and content inspection
 - **📅 Time Management** - Due, defer, planned dates, estimates, and scheduling
 - **🏷️ Advanced Tagging** - Tag-based filtering with exact/partial matching
 - **🚫 Mutually Exclusive Tags** - Automatically respects exclusive tag groups when applying tags
@@ -512,8 +515,20 @@ read_task_attachment {
 16. **list_custom_perspectives** - 🌟 **NEW**: List all custom perspectives with details
 17. **get_custom_perspective_tasks** - 🌟 **NEW**: Access custom perspective with hierarchical display
 
+### 📁 Folder Management Tools (NEW)
+18. **add_folder** - 🆕 **NEW**: Create a folder, optionally nested under a parent folder
+19. **edit_folder** - 🆕 **NEW**: Rename a folder or move it under a different parent (empty string moves to root)
+20. **remove_folder** - 🆕 **NEW**: Delete a folder (⚠️ also deletes all contained projects and tasks)
+21. **list_folders** - 🆕 **NEW**: List all folders with IDs, parents, status, and project counts
+22. **get_folder** - 🆕 **NEW**: Get a single folder with its child projects and subfolders
+
+### ⚡ Productivity Tools (NEW)
+23. **append_to_note** - 🆕 **NEW**: Append text to a task/project note without overwriting
+24. **count_tasks** - 🆕 **NEW**: Fast "how many" queries with a status breakdown (same filters as filter_tasks)
+25. **duplicate_task** - 🆕 **NEW**: Clone a task with/without subtasks, optionally renamed
+
 ### 📊 Analytics & Tracking
-18. **get_today_completed_tasks** - View today's completed tasks
+26. **get_today_completed_tasks** - View today's completed tasks
 
 Batch move feature roadmap (future): [docs/roadmap/2026-02-25-batch-move-tasks-plan.md](docs/roadmap/2026-02-25-batch-move-tasks-plan.md)
 
@@ -623,6 +638,58 @@ get_custom_perspective_tasks {
 }
 ```
 
+### 📁 Folder Management
+
+```bash
+# List all folders with project counts
+list_folders {"includeDropped": false}
+
+# Create a top-level folder
+add_folder {"name": "Work"}
+
+# Create a nested folder
+add_folder {"name": "Clients", "parentFolderName": "Work"}
+
+# Inspect a folder's projects and subfolders
+get_folder {"name": "Work"}
+
+# Rename or move a folder (empty string moves to root)
+edit_folder {"name": "Clients", "newName": "Key Clients"}
+edit_folder {"name": "Key Clients", "newParentFolderName": ""}
+
+# Delete a folder (⚠️ also deletes all contained projects and tasks)
+remove_folder {"name": "Old Archive"}
+```
+
+### ⚡ Productivity Tools
+
+```bash
+# Append a progress note without overwriting the existing note
+append_to_note {
+  "itemType": "task",
+  "name": "Write report",
+  "text": "Drafted section 1 today"
+}
+
+# Fast count: how many flagged tasks are still actionable?
+count_tasks {
+  "flagged": true,
+  "taskStatus": ["Available", "Next", "DueSoon", "Overdue"]
+}
+
+# How many tasks remain in a project (by status breakdown)
+count_tasks {"projectFilter": "Website Redesign"}
+
+# Duplicate a task template with its subtasks
+duplicate_task {
+  "name": "Weekly Review Checklist",
+  "newName": "Weekly Review - 2026-03-02"
+}
+
+# Duplicate without subtasks
+duplicate_task {"taskId": "abc123", "includeSubtasks": false}
+```
+
 ## 🔧 Configuration
 
 ### Claude Code

package/dist/server.js

@@ -25,10 +25,20 @@ import * as filterTasksTool from './tools/definitions/filterTasks.js';
 // Import custom perspective tools
 import * as listCustomPerspectivesTool from './tools/definitions/listCustomPerspectives.js';
 import * as getCustomPerspectiveTasksTool from './tools/definitions/getCustomPerspectiveTasks.js';
+// Import folder management tools
+import * as addFolderTool from './tools/definitions/addFolder.js';
+import * as editFolderTool from './tools/definitions/editFolder.js';
+import * as removeFolderTool from './tools/definitions/removeFolder.js';
+import * as listFoldersTool from './tools/definitions/listFolders.js';
+import * as getFolderTool from './tools/definitions/getFolder.js';
+// Import productivity tools
+import * as appendToNoteTool from './tools/definitions/appendToNote.js';
+import * as countTasksTool from './tools/definitions/countTasks.js';
+import * as duplicateTaskTool from './tools/definitions/duplicateTask.js';
 // Create an MCP server
 const server = new McpServer({
     name: "OmniFocus MCP",
-    version: "1.6.9"
+    version: "1.9.0"
 });
 // Register tools
 server.tool("dump_database", "Gets the current state of your OmniFocus database", dumpDatabaseTool.schema.shape, dumpDatabaseTool.handler);
@@ -54,6 +64,16 @@ server.tool("filter_tasks", "Advanced task filtering with unlimited perspective
 // Custom perspective tools
 server.tool("list_custom_perspectives", "List all custom perspectives defined in OmniFocus", listCustomPerspectivesTool.schema.shape, listCustomPerspectivesTool.handler);
 server.tool("get_custom_perspective_tasks", "Get tasks from a specific OmniFocus custom perspective by name. Use this when user refers to perspective names like '今日工作安排', '今日复盘', '本周项目' etc. - these are custom views created in OmniFocus, NOT tags. Supports hierarchical tree display of task relationships.", getCustomPerspectiveTasksTool.schema.shape, getCustomPerspectiveTasksTool.handler);
+// Folder management tools
+server.tool("add_folder", "Create a new folder in OmniFocus, optionally nested under a parent folder. Folders organize projects into a hierarchy.", addFolderTool.schema.shape, addFolderTool.handler);
+server.tool("edit_folder", "Rename a folder or move it under a different parent folder (use an empty string for newParentFolderName to move it to the root level).", editFolderTool.schema.shape, editFolderTool.handler);
+server.tool("remove_folder", "Remove a folder from OmniFocus. WARNING: this also permanently deletes all projects and tasks contained in the folder.", removeFolderTool.schema.shape, removeFolderTool.handler);
+server.tool("list_folders", "List all OmniFocus folders with IDs, parent relationships, status, and project counts without loading tasks.", listFoldersTool.schema.shape, listFoldersTool.handler);
+server.tool("get_folder", "Get a single OmniFocus folder by ID or name, including its child projects and subfolders.", getFolderTool.schema.shape, getFolderTool.handler);
+// Productivity tools
+server.tool("append_to_note", "Append text to a task or project note without overwriting the existing note. Useful for logging progress or adding context.", appendToNoteTool.schema.shape, appendToNoteTool.handler);
+server.tool("count_tasks", "Count tasks matching filters without returning the full list. Fast 'how many' queries that return a total plus a breakdown by status. Uses the same filters as filter_tasks.", countTasksTool.schema.shape, countTasksTool.handler);
+server.tool("duplicate_task", "Duplicate an existing task, optionally with its subtasks, and optionally with a new name. Useful for template-based workflows.", duplicateTaskTool.schema.shape, duplicateTaskTool.handler);
 // Start the MCP server
 const transport = new StdioServerTransport();
 // Use await with server.connect to ensure proper connection

package/dist/tools/definitions/addFolder.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { addFolder } from '../primitives/addFolder.js';
+export const schema = z.object({
+    name: z.string().describe('The name of the folder'),
+    parentFolderName: z.string().optional().describe('The name of the parent folder to nest this folder under (created at the root level if not specified)')
+});
+export async function handler(args, _extra) {
+    try {
+        const result = await addFolder(args);
+        if (result.success) {
+            const locationText = args.parentFolderName
+                ? `inside folder "${args.parentFolderName}"`
+                : 'at the root level';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Folder "${args.name}" created successfully ${locationText}.\n\nid: ${result.folderId}`
+                    }]
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to create folder: ${result.error}`
+                }],
+            isError: true
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Error creating folder: ${error.message}`
+                }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/appendToNote.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { appendToNote } from '../primitives/appendToNote.js';
+export const schema = z.object({
+    id: z.string().optional().describe('The ID of the task or project'),
+    name: z.string().optional().describe('The name of the task or project (as fallback if ID not provided)'),
+    itemType: z.enum(['task', 'project']).describe("Type of item whose note to append to ('task' or 'project')"),
+    text: z.string().describe('The text to append to the existing note'),
+    separator: z.string().optional().describe('Separator inserted between the existing note and the new text (default: a newline). Pass an empty string to append with no separator.')
+});
+export async function handler(args, _extra) {
+    try {
+        if (!args.id && !args.name) {
+            return {
+                content: [{ type: 'text', text: 'Either id or name must be provided to append to a note.' }],
+                isError: true
+            };
+        }
+        const result = await appendToNote(args);
+        if (result.success) {
+            const itemTypeLabel = args.itemType === 'task' ? 'Task' : 'Project';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Appended text to ${itemTypeLabel} "${result.name}" note.\n\nid: ${result.id}`
+                    }]
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Failed to append to note: ${result.error}` }],
+            isError: true
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error appending to note: ${error.message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/countTasks.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { countTasks } from '../primitives/countTasks.js';
+export const schema = z.object({
+    taskStatus: z.array(z.string()).optional().describe('Filter by task status: Available, Next, Blocked, DueSoon, Overdue, Completed, Dropped'),
+    perspective: z.enum(['inbox', 'flagged', 'all']).optional().describe("Scope: 'inbox', 'flagged', or 'all' (default: all)"),
+    projectFilter: z.string().optional().describe('Only count tasks in projects whose name contains this text'),
+    tagFilter: z.union([z.string(), z.array(z.string())]).optional().describe('Only count tasks with these tags'),
+    exactTagMatch: z.boolean().optional().describe('Require exact tag name match (default: false)'),
+    flagged: z.boolean().optional().describe('Only count flagged (true) or unflagged (false) tasks'),
+    searchText: z.string().optional().describe('Only count tasks whose name or note contains this text'),
+    dueToday: z.boolean().optional().describe('Only count tasks due today'),
+    dueThisWeek: z.boolean().optional().describe('Only count tasks due this week'),
+    overdue: z.boolean().optional().describe('Only count overdue tasks'),
+    completedToday: z.boolean().optional().describe('Only count tasks completed today'),
+    completedThisWeek: z.boolean().optional().describe('Only count tasks completed this week'),
+    plannedToday: z.boolean().optional().describe('Only count tasks planned for today'),
+    plannedThisWeek: z.boolean().optional().describe('Only count tasks planned for this week')
+});
+export async function handler(args, _extra) {
+    try {
+        const result = await countTasks(args);
+        const statusEntries = Object.entries(result.byStatus).sort((a, b) => b[1] - a[1]);
+        const breakdown = statusEntries.length > 0
+            ? statusEntries.map(([status, count]) => `- ${status}: ${count}`).join('\n')
+            : '- (no matching tasks)';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# Task Count\n\n**Total: ${result.total}**\n\nBy status:\n${breakdown}`
+                }]
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error counting tasks: ${error.message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/duplicateTask.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { duplicateTask } from '../primitives/duplicateTask.js';
+export const schema = z.object({
+    taskId: z.string().optional().describe('The ID of the task to duplicate'),
+    taskName: z.string().optional().describe('The name of the task to duplicate (as fallback if ID not provided)'),
+    newName: z.string().optional().describe('Optional new name for the duplicated task (keeps the original name if omitted)'),
+    includeSubtasks: z.boolean().optional().describe('Whether to include the task\'s subtasks in the copy (default: true)')
+});
+export async function handler(args, _extra) {
+    try {
+        if (!args.taskId && !args.taskName) {
+            return {
+                content: [{ type: 'text', text: 'Either taskId or taskName must be provided to duplicate a task.' }],
+                isError: true
+            };
+        }
+        const result = await duplicateTask(args);
+        if (result.success) {
+            const subtaskText = (result.childrenCount && result.childrenCount > 0)
+                ? ` with ${result.childrenCount} subtask(s)`
+                : '';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Duplicated task as "${result.name}"${subtaskText}.\n\nid: ${result.newTaskId}`
+                    }]
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Failed to duplicate task: ${result.error}` }],
+            isError: true
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error duplicating task: ${error.message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/editFolder.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { editFolder } from '../primitives/editFolder.js';
+export const schema = z.object({
+    id: z.string().optional().describe('The ID of the folder to edit'),
+    name: z.string().optional().describe('The name of the folder to edit (as fallback if ID not provided)'),
+    newName: z.string().optional().describe('New name for the folder'),
+    newParentFolderName: z.string().optional().describe('Move the folder under this parent folder. Use an empty string "" to move it to the root level.')
+});
+export async function handler(args, _extra) {
+    try {
+        if (!args.id && !args.name) {
+            return {
+                content: [{ type: 'text', text: 'Either id or name must be provided to edit a folder.' }],
+                isError: true
+            };
+        }
+        const result = await editFolder(args);
+        if (result.success) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Folder "${result.name}" updated successfully.\nChanged: ${result.changedProperties || 'nothing'}\n\nid: ${result.id}`
+                    }]
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Failed to edit folder: ${result.error}` }],
+            isError: true
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error editing folder: ${error.message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/getFolder.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { getFolder } from '../primitives/getFolder.js';
+export const schema = z.object({
+    id: z.string().optional().describe('The ID of the folder to get'),
+    name: z.string().optional().describe('The name of the folder to get (as fallback if ID not provided)')
+});
+export async function handler(args, _extra) {
+    try {
+        if (!args.id && !args.name) {
+            return {
+                content: [{ type: 'text', text: 'Either id or name must be provided to get a folder.' }],
+                isError: true
+            };
+        }
+        const folder = await getFolder({ id: args.id, name: args.name });
+        const lines = [];
+        lines.push(`# Folder: ${folder.name}`);
+        lines.push('');
+        lines.push(`- id: ${folder.id}`);
+        lines.push(`- status: ${folder.status}`);
+        if (folder.parentFolderID) {
+            lines.push(`- parent folder id: ${folder.parentFolderID}`);
+        }
+        lines.push('');
+        lines.push(`## Subfolders (${folder.subfolders.length})`);
+        if (folder.subfolders.length === 0) {
+            lines.push('None');
+        }
+        else {
+            for (const sub of folder.subfolders) {
+                lines.push(`- ${sub.name} [${sub.status}] (id:${sub.id})`);
+            }
+        }
+        lines.push('');
+        lines.push(`## Projects (${folder.projects.length})`);
+        if (folder.projects.length === 0) {
+            lines.push('None');
+        }
+        else {
+            for (const project of folder.projects) {
+                lines.push(`- ${project.name} [${project.status}] (id:${project.id}, remaining:${project.remainingTaskCount})`);
+            }
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error occurred';
+        return {
+            content: [{ type: 'text', text: `Error getting folder: ${message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/listFolders.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { listFolders } from '../primitives/listFolders.js';
+export const schema = z.object({
+    includeDropped: z.boolean().optional().describe('Include dropped folders (default: true)')
+});
+export async function handler(args, _extra) {
+    try {
+        const result = await listFolders(args.includeDropped !== false);
+        return { content: [{ type: 'text', text: result }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error occurred';
+        return {
+            content: [{ type: 'text', text: `Error listing folders: ${message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/removeFolder.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { removeFolder } from '../primitives/removeFolder.js';
+export const schema = z.object({
+    id: z.string().optional().describe('The ID of the folder to remove'),
+    name: z.string().optional().describe('The name of the folder to remove (as fallback if ID not provided)')
+});
+export async function handler(args, _extra) {
+    try {
+        if (!args.id && !args.name) {
+            return {
+                content: [{ type: 'text', text: 'Either id or name must be provided to remove a folder.' }],
+                isError: true
+            };
+        }
+        const result = await removeFolder(args);
+        if (result.success) {
+            const projectCount = result.deletedProjectCount ?? 0;
+            const taskCount = result.deletedTaskCount ?? 0;
+            const cascadeWarning = (projectCount > 0 || taskCount > 0)
+                ? `\n⚠️ This also permanently deleted ${projectCount} contained project(s) and ${taskCount} task(s).`
+                : '';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Folder "${result.name}" removed successfully.${cascadeWarning}`
+                    }]
+            };
+        }
+        let errorMsg = 'Failed to remove folder';
+        if (result.error) {
+            if (result.error.includes('Folder not found')) {
+                errorMsg = 'Folder not found';
+                if (args.id)
+                    errorMsg += ` with ID "${args.id}"`;
+                if (args.name)
+                    errorMsg += `${args.id ? ' or' : ' with'} name "${args.name}"`;
+                errorMsg += '.';
+            }
+            else {
+                errorMsg += `: ${result.error}`;
+            }
+        }
+        return {
+            content: [{ type: 'text', text: errorMsg }],
+            isError: true
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error removing folder: ${error.message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/primitives/addFolder.js

@@ -0,0 +1,87 @@
+import { executeAppleScript } from '../../utils/scriptExecution.js';
+import { buildAppleScriptJsonHelpers } from '../../utils/appleScriptJson.js';
+import { escapeAppleScriptString } from '../../utils/appleScriptString.js';
+/**
+ * Generate pure AppleScript for folder creation
+ */
+export function generateAppleScript(params) {
+    const name = escapeAppleScriptString(params.name);
+    const parentFolderName = params.parentFolderName ? escapeAppleScriptString(params.parentFolderName) : '';
+    const jsonHelpers = buildAppleScriptJsonHelpers();
+    const script = `
+${jsonHelpers}
+  try
+    tell application "OmniFocus"
+      tell front document
+        -- Determine the container (root or parent folder)
+        if "${parentFolderName}" is "" then
+          -- Create folder at the root level
+          set newFolder to make new folder with properties {name:"${name}"}
+        else
+          -- Resolve parent folder with duplicate protection
+          set parentMatches to (flattened folders where name = "${parentFolderName}")
+          set parentMatchCount to count of parentMatches
+
+          if parentMatchCount = 0 then
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Parent folder not found: ${parentFolderName}") & "\\\"}"
+          else if parentMatchCount > 1 then
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Ambiguous parent folder name: ${parentFolderName}. Multiple matches found; please rename or use a unique folder.") & "\\\"}"
+          end if
+
+          set parentFolder to item 1 of parentMatches
+          set newFolder to make new folder with properties {name:"${name}"} at end of folders of parentFolder
+        end if
+
+        -- Get the folder ID and name
+        set folderId to id of newFolder as string
+        set folderNameValue to name of newFolder
+
+        -- Return success with folder ID
+        return "{\\\"success\\\":true,\\\"folderId\\\":\\"" & my jsonEscape(folderId) & "\\",\\\"name\\\":\\"" & my jsonEscape(folderNameValue) & "\\\"}"
+      end tell
+    end tell
+  on error errorMessage
+    return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape(errorMessage) & "\\\"}"
+  end try
+  `;
+    return script;
+}
+/**
+ * Add a folder to OmniFocus
+ */
+export async function addFolder(params) {
+    try {
+        const script = generateAppleScript(params);
+        console.error('Executing AppleScript for folder creation...');
+        const stdout = await executeAppleScript(script);
+        console.error('AppleScript stdout:', stdout);
+        try {
+            const result = JSON.parse(stdout);
+            if (!result.success) {
+                return {
+                    success: false,
+                    error: result.error
+                };
+            }
+            return {
+                success: true,
+                folderId: result.folderId,
+                name: result.name
+            };
+        }
+        catch (parseError) {
+            console.error('Error parsing AppleScript result:', parseError);
+            return {
+                success: false,
+                error: `Failed to parse result: ${stdout}`
+            };
+        }
+    }
+    catch (error) {
+        console.error('Error in addFolder:', error);
+        return {
+            success: false,
+            error: error?.message || 'Unknown error in addFolder'
+        };
+    }
+}

package/dist/tools/primitives/addFolder.test.js

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { generateAppleScript } from './addFolder.js';
+test('addFolder creates folder at root level when no parent specified', () => {
+    const script = generateAppleScript({ name: 'Work' });
+    // Root branch is selected at AppleScript runtime via the empty parent name check.
+    assert.match(script, /if "" is "" then/);
+    assert.match(script, /make new folder with properties \{name:"Work"\}/);
+    assert.match(script, /my jsonEscape\(folderId\)/);
+});
+test('addFolder nests under a parent folder with duplicate protection', () => {
+    const script = generateAppleScript({ name: 'Sub', parentFolderName: 'Parent' });
+    assert.match(script, /flattened folders where name = "Parent"/);
+    assert.match(script, /Ambiguous parent folder name: Parent/);
+    assert.match(script, /make new folder with properties \{name:"Sub"\} at end of folders of parentFolder/);
+});
+test('addFolder keeps apostrophes and doubles backslashes in the name', () => {
+    const script = generateAppleScript({ name: "Client's \\ Files" });
+    assert.match(script, /name:"Client's \\\\ Files"/);
+    assert.doesNotMatch(script, /\\'/);
+});
+test('addFolder escapes JSON response values through AppleScript helper', () => {
+    const script = generateAppleScript({ name: 'Work' });
+    assert.match(script, /on jsonEscape\(inputText\)/);
+    assert.match(script, /my jsonEscape\(folderId\)/);
+    assert.match(script, /my jsonEscape\(folderNameValue\)/);
+});