OmniFocus-MCP

Instructions

Implementation Reference

• src/server.ts:32-37 (registration)

  Registers the 'add_omnifocus_task' MCP tool using the schema and handler exported from src/tools/definitions/addOmniFocusTask.ts
  server.tool( "add_omnifocus_task", "Add a new task to OmniFocus", addOmniFocusTaskTool.schema.shape, addOmniFocusTaskTool.handler );
• src/tools/definitions/addOmniFocusTask.ts:5-18 (schema)

  Zod schema defining the input parameters for the add_omnifocus_task tool
  export const schema = z.object({ name: z.string().describe("The name of the task"), note: z.string().optional().describe("Additional notes for the task"), dueDate: z.string().optional().describe("The due date of the task in ISO format (YYYY-MM-DD or full ISO date)"), deferDate: z.string().optional().describe("The defer date of the task in ISO format (YYYY-MM-DD or full ISO date)"), flagged: z.boolean().optional().describe("Whether the task is flagged or not"), estimatedMinutes: z.number().optional().describe("Estimated time to complete the task, in minutes"), tags: z.array(z.string()).optional().describe("Tags to assign to the task"), projectName: z.string().optional().describe("The name of the project to add the task to (will add to inbox if not specified)"), // Hierarchy support parentTaskId: z.string().optional().describe("ID of the parent task (preferred for accuracy)"), parentTaskName: z.string().optional().describe("Name of the parent task (used if ID not provided; matched within project or globally if no project)"), hierarchyLevel: z.number().int().min(0).optional().describe("Explicit level indicator for ordering in batch workflows (0=root) - ignored in single add") });
• src/tools/definitions/addOmniFocusTask.ts:20-80 (handler)

  The MCP tool handler for 'add_omnifocus_task'. Validates input via schema, calls the primitive implementation, and formats the success/error response.
  export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) { try { // Call the addOmniFocusTask function const result = await addOmniFocusTask(args as AddOmniFocusTaskParams); console.error('[add_omnifocus_task] args:', JSON.stringify(args)); console.error('[add_omnifocus_task] result:', JSON.stringify(result)); if (result.success) { // Determine actual placement const placement = (result as any).placement as 'parent' | 'project' | 'inbox' | undefined; let locationText = ''; if (placement === 'parent') { locationText = 'under the parent task'; } else if (placement === 'project') { locationText = args.projectName ? `in project "${args.projectName}"` : 'in a project'; } else { locationText = 'in your inbox'; } const tagText = args.tags && args.tags.length > 0 ? ` with tags: ${args.tags.join(', ')}` : ''; const dueDateText = args.dueDate ? ` due on ${new Date(args.dueDate).toLocaleDateString()}` : ''; // Warning if parent requested but not used let placementWarning = ''; if ((args.parentTaskId || args.parentTaskName) && placement && placement !== 'parent') { placementWarning = `\n⚠️ Parent not found; task created ${placement === 'project' ? 'in project' : 'in inbox'}.`; } return { content: [{ type: "text" as const, text: `✅ Task "${args.name}" created successfully ${locationText}${dueDateText}${tagText}.${placementWarning}` }] }; } else { // Task creation failed return { content: [{ type: "text" as const, text: `Failed to create task: ${result.error}` }], isError: true }; } } catch (err: unknown) { const error = err as Error; console.error(`Tool execution error: ${error.message}`); return { content: [{ type: "text" as const, text: `Error creating task: ${error.message}` }], isError: true }; } }
• src/tools/primitives/addOmniFocusTask.ts:205-252 (helper)

  Core implementation function that generates and executes AppleScript to add task to OmniFocus via osascript, handles temp file, parses JSON result.
  export async function addOmniFocusTask(params: AddOmniFocusTaskParams): Promise<{success: boolean, taskId?: string, error?: string, placement?: 'parent' | 'project' | 'inbox'}> { try { // Generate AppleScript const script = generateAppleScript(params); console.error("Executing AppleScript via temp file..."); // Write to a temporary AppleScript file to avoid shell escaping issues const tempFile = join(tmpdir(), `omnifocus_add_${Date.now()}.applescript`); writeFileSync(tempFile, script, { encoding: 'utf8' }); // Execute AppleScript from file const { stdout, stderr } = await execAsync(`osascript ${tempFile}`); if (stderr) { console.error("AppleScript stderr:", stderr); } console.error("AppleScript stdout:", stdout); // Cleanup temp file try { unlinkSync(tempFile); } catch {} // Parse the result try { const result = JSON.parse(stdout); // Return the result return { success: result.success, taskId: result.taskId, error: result.error, placement: result.placement }; } catch (parseError) { console.error("Error parsing AppleScript result:", parseError); return { success: false, error: `Failed to parse result: ${stdout}` }; } } catch (error: any) { console.error("Error in addOmniFocusTask:", error); return { success: false, error: error?.message || "Unknown error in addOmniFocusTask" }; } }
• src/tools/primitives/addOmniFocusTask.ts:28-200 (helper)

  Generates the AppleScript code used to interact with OmniFocus application to create tasks, handle hierarchy (parent/project/inbox), dates, tags, etc.
  function generateAppleScript(params: AddOmniFocusTaskParams): string { // Sanitize and prepare parameters for AppleScript const name = params.name.replace(/['"\\]/g, '\\$&'); // Escape quotes and backslashes const note = params.note?.replace(/['"\\]/g, '\\$&') || ''; const dueDate = params.dueDate || ''; const deferDate = params.deferDate || ''; const flagged = params.flagged === true; const estimatedMinutes = params.estimatedMinutes?.toString() || ''; const tags = params.tags || []; const projectName = params.projectName?.replace(/['"\\]/g, '\\$&') || ''; const parentTaskId = params.parentTaskId?.replace(/['"\\]/g, '\\$&') || ''; const parentTaskName = params.parentTaskName?.replace(/['"\\]/g, '\\$&') || ''; // Generate date constructions outside tell blocks let datePreScript = ''; let dueDateVar = ''; let deferDateVar = ''; if (dueDate) { dueDateVar = `dueDate${Math.random().toString(36).substr(2, 9)}`; datePreScript += createDateOutsideTellBlock(dueDate, dueDateVar) + '\n\n'; } if (deferDate) { deferDateVar = `deferDate${Math.random().toString(36).substr(2, 9)}`; datePreScript += createDateOutsideTellBlock(deferDate, deferDateVar) + '\n\n'; } // Construct AppleScript with error handling let script = datePreScript + ` try tell application "OmniFocus" tell front document -- Resolve parent task if provided set newTask to missing value set parentTask to missing value set placement to "" if "${parentTaskId}" is not "" then try set parentTask to first flattened task where id = "${parentTaskId}" end try if parentTask is missing value then try set parentTask to first inbox task where id = "${parentTaskId}" end try end if -- If projectName provided, ensure parent is within that project if parentTask is not missing value and "${projectName}" is not "" then try set pproj to containing project of parentTask if pproj is missing value or name of pproj is not "${projectName}" then set parentTask to missing value end try end if end if if parentTask is missing value and "${parentTaskName}" is not "" then if "${projectName}" is not "" then -- Find by name but constrain to the specified project try set parentTask to first flattened task where name = "${parentTaskName}" end try if parentTask is not missing value then try set pproj to containing project of parentTask if pproj is missing value or name of pproj is not "${projectName}" then set parentTask to missing value end try end if else -- No project specified; allow global or inbox match by name try set parentTask to first flattened task where name = "${parentTaskName}" end try if parentTask is missing value then try set parentTask to first inbox task where name = "${parentTaskName}" end try end if end if end if if parentTask is not missing value then -- Create task under parent task set newTask to make new task with properties {name:"${name}"} at end of tasks of parentTask else if "${projectName}" is not "" then -- Create under specified project try set theProject to first flattened project where name = "${projectName}" set newTask to make new task with properties {name:"${name}"} at end of tasks of theProject on error return "{\\\"success\\\":false,\\\"error\\\":\\\"Project not found: ${projectName}\\\"}" end try else -- Fallback to inbox set newTask to make new inbox task with properties {name:"${name}"} end if -- Set task properties ${note ? `set note of newTask to "${note}"` : ''} ${dueDate ? ` -- Set due date set due date of newTask to ` + dueDateVar : ''} ${deferDate ? ` -- Set defer date set defer date of newTask to ` + deferDateVar : ''} ${flagged ? `set flagged of newTask to true` : ''} ${estimatedMinutes ? `set estimated minutes of newTask to ${estimatedMinutes}` : ''} -- Derive placement from container; distinguish real parent vs project root task try set placement to "inbox" set ctr to container of newTask set cclass to class of ctr as string set ctrId to id of ctr as string if cclass is "project" then set placement to "project" else if cclass is "task" then if parentTask is not missing value then set parentId to id of parentTask as string if ctrId is equal to parentId then set placement to "parent" else -- Likely the project's root task; treat as project set placement to "project" end if else -- No explicit parent requested; container is root task -> treat as project set placement to "project" end if else set placement to "inbox" end if on error -- If container access fails (e.g., inbox), default based on projectName if "${projectName}" is not "" then set placement to "project" else set placement to "inbox" end if end try -- Get the task ID set taskId to id of newTask as string -- Add tags if provided ${tags.length > 0 ? tags.map(tag => { const sanitizedTag = tag.replace(/['"\\]/g, '\\$&'); return ` try set theTag to first flattened tag where name = "${sanitizedTag}" add theTag to tags of newTask on error -- Tag might not exist, try to create it try set theTag to make new tag with properties {name:"${sanitizedTag}"} add theTag to tags of newTask on error -- Could not create or add tag end try end try`; }).join('\n') : ''} -- Return success with task ID and placement return "{\\\"success\\\":true,\\\"taskId\\\":\\"" & taskId & "\\",\\\"name\\\":\\"${name}\\\",\\\"placement\\\":\\"" & placement & "\\"}" end tell end tell on error errorMessage return "{\\\"success\\\":false,\\\"error\\\":\\"" & errorMessage & "\\"}" end try `; return script; }