omnifocus-mcp-enhanced 1.7.0 → 1.8.0

package/README.md

@@ -44,6 +44,7 @@ Want to see where the project is heading next? See the [roadmap](docs/roadmap/20
 
 ## 🆕 Latest Release
 
+- **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 +66,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 +514,15 @@ 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
+
 ### 📊 Analytics & Tracking
-18. **get_today_completed_tasks** - View today's completed tasks
+23. **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 +632,29 @@ 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"}
+```
+
 ## 🔧 Configuration
 
 ### Claude Code

package/dist/server.js

@@ -25,10 +25,16 @@ 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';
 // Create an MCP server
 const server = new McpServer({
     name: "OmniFocus MCP",
-    version: "1.6.9"
+    version: "1.8.0"
 });
 // Register tools
 server.tool("dump_database", "Gets the current state of your OmniFocus database", dumpDatabaseTool.schema.shape, dumpDatabaseTool.handler);
@@ -54,6 +60,12 @@ 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);
 // 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/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\)/);
+});

package/dist/tools/primitives/editFolder.js

@@ -0,0 +1,196 @@
+import { executeAppleScript } from '../../utils/scriptExecution.js';
+import { buildAppleScriptJsonHelpers } from '../../utils/appleScriptJson.js';
+import { escapeAppleScriptString } from '../../utils/appleScriptString.js';
+/**
+ * Validate edit parameters before script generation.
+ */
+export function validateEditFolderParams(params) {
+    if (!params.id && !params.name) {
+        return {
+            valid: false,
+            error: 'Either id or name must be provided'
+        };
+    }
+    if (params.newName === undefined && params.newParentFolderName === undefined) {
+        return {
+            valid: false,
+            error: 'Nothing to update: provide newName and/or newParentFolderName.'
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Generate pure AppleScript for folder editing
+ */
+export function generateAppleScript(params) {
+    const id = params.id ? escapeAppleScriptString(params.id) : '';
+    const name = params.name ? escapeAppleScriptString(params.name) : '';
+    const jsonHelpers = buildAppleScriptJsonHelpers();
+    if (!id && !name) {
+        return `return "{\\\"success\\\":false,\\\"error\\\":\\\"Either id or name must be provided\\\"}"`;
+    }
+    let script = `
+${jsonHelpers}
+  try
+    tell application "OmniFocus"
+      tell front document
+        -- Find the folder to edit
+        set foundFolder to missing value
+`;
+    if (id) {
+        script += `
+        -- Try to find by ID first
+        try
+          set foundFolder to first flattened folder where id = "${id}"
+        end try
+`;
+    }
+    if (name) {
+        script += `
+        -- Resolve by name with duplicate protection
+        if foundFolder is missing value then
+          set nameMatches to (flattened folders where name = "${name}")
+          set nameMatchCount to count of nameMatches
+
+          if nameMatchCount = 1 then
+            set foundFolder to item 1 of nameMatches
+          else if nameMatchCount > 1 then
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Ambiguous folder name: ${name}. Multiple matches found; please use id.") & "\\\"}"
+          end if
+        end if
+`;
+    }
+    script += `
+        -- If we found the folder, edit it
+        if foundFolder is not missing value then
+          set folderName to name of foundFolder
+          set folderId to id of foundFolder as string
+          set changedProperties to {}
+`;
+    // Move to a new parent folder (or root when empty string)
+    if (params.newParentFolderName !== undefined) {
+        if (params.newParentFolderName === '') {
+            script += `
+          -- Move folder to the root level
+          move foundFolder to end of folders
+          set end of changedProperties to "parent (root)"
+`;
+        }
+        else {
+            const destName = escapeAppleScriptString(params.newParentFolderName);
+            script += `
+          -- Resolve destination parent folder with duplicate protection
+          set destMatches to (flattened folders where name = "${destName}")
+          set destMatchCount to count of destMatches
+
+          if destMatchCount = 0 then
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Destination parent folder not found: ${destName}") & "\\\"}"
+          else if destMatchCount > 1 then
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Ambiguous destination parent folder name: ${destName}. Multiple matches found; please rename or use a unique folder.") & "\\\"}"
+          end if
+
+          set destFolder to item 1 of destMatches
+
+          -- Prevent cycles: destination cannot be this folder or any of its descendants
+          set cursorFolder to destFolder
+          repeat while cursorFolder is not missing value
+            if (id of cursorFolder as string) is folderId then
+              return "{\\\"success\\\":false,\\\"error\\\":\\\"Invalid move target: cannot move a folder into itself or its descendants.\\\"}"
+            end if
+
+            set nextCursorFolder to missing value
+            try
+              set cursorContainer to container of cursorFolder
+              if class of cursorContainer is folder then
+                set nextCursorFolder to cursorContainer
+              end if
+            end try
+            set cursorFolder to nextCursorFolder
+          end repeat
+
+          -- Move folder under destination parent
+          move foundFolder to end of folders of destFolder
+          set end of changedProperties to "parent"
+`;
+        }
+    }
+    if (params.newName !== undefined) {
+        script += `
+          -- Update name
+          set name of foundFolder to "${escapeAppleScriptString(params.newName)}"
+          set end of changedProperties to "name"
+`;
+    }
+    script += `
+          -- Prepare the changed properties as a string
+          set changedPropsText to ""
+          repeat with i from 1 to count of changedProperties
+            set changedPropsText to changedPropsText & item i of changedProperties
+            if i < count of changedProperties then
+              set changedPropsText to changedPropsText & ", "
+            end if
+          end repeat
+
+          -- Re-read the (possibly updated) name and id
+          set folderName to name of foundFolder
+          set folderId to id of foundFolder as string
+
+          return "{\\\"success\\\":true,\\\"id\\\":\\"" & my jsonEscape(folderId) & "\\",\\\"name\\\":\\"" & my jsonEscape(folderName) & "\\",\\\"changedProperties\\\":\\"" & my jsonEscape(changedPropsText) & "\\\"}"
+        else
+          return "{\\\"success\\\":false,\\\"error\\\":\\\"Folder not found\\\"}"
+        end if
+      end tell
+    end tell
+  on error errorMessage
+    return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape(errorMessage) & "\\\"}"
+  end try
+  `;
+    return script;
+}
+/**
+ * Edit a folder in OmniFocus
+ */
+export async function editFolder(params) {
+    try {
+        const validation = validateEditFolderParams(params);
+        if (!validation.valid) {
+            return {
+                success: false,
+                error: validation.error
+            };
+        }
+        const script = generateAppleScript(params);
+        console.error('Executing AppleScript for folder editing...');
+        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,
+                id: result.id,
+                name: result.name,
+                changedProperties: result.changedProperties
+            };
+        }
+        catch (parseError) {
+            console.error('Error parsing AppleScript result:', parseError);
+            return {
+                success: false,
+                error: `Failed to parse result: ${stdout}`
+            };
+        }
+    }
+    catch (error) {
+        console.error('Error in editFolder execution:', error);
+        return {
+            success: false,
+            error: error?.message || 'Unknown error in editFolder'
+        };
+    }
+}

package/dist/tools/primitives/getFolder.js

@@ -0,0 +1,27 @@
+import { executeOmniFocusScript } from '../../utils/scriptExecution.js';
+function parseGetFolderResult(result) {
+    const data = typeof result === 'string' ? JSON.parse(result) : result;
+    if (!data || typeof data !== 'object') {
+        throw new Error('Invalid get_folder response');
+    }
+    const response = data;
+    if (response.success !== true) {
+        throw new Error(response.error || 'Unable to get OmniFocus folder');
+    }
+    if (!response.folder || typeof response.folder !== 'object') {
+        throw new Error('Invalid get_folder response: folder is missing');
+    }
+    return {
+        success: true,
+        folder: response.folder
+    };
+}
+export async function getFolder(params) {
+    const result = await executeOmniFocusScript('@getFolder.js', {
+        folderId: params.id || null,
+        folderName: params.name || null
+    });
+    const data = parseGetFolderResult(result);
+    return data.folder;
+}
+export { parseGetFolderResult };