OmniFocus-MCP

Instructions

Implementation Reference

• src/tools/definitions/editItem.ts:30-96 (handler)

  MCP tool handler function that validates input, calls the primitive editItem function, handles success/error responses.
  export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) { try { // Validate that either id or name is provided if (!args.id && !args.name) { return { content: [{ type: "text" as const, text: "Either id or name must be provided to edit an item." }], isError: true }; } // Call the editItem function const result = await editItem(args as EditItemParams); if (result.success) { // Item was edited successfully const itemTypeLabel = args.itemType === 'task' ? 'Task' : 'Project'; let changedText = ''; if (result.changedProperties) { changedText = ` (${result.changedProperties})`; } return { content: [{ type: "text" as const, text: `✅ ${itemTypeLabel} "${result.name}" updated successfully${changedText}.` }] }; } else { // Item editing failed let errorMsg = `Failed to update ${args.itemType}`; if (result.error) { if (result.error.includes("Item not found")) { errorMsg = `${args.itemType.charAt(0).toUpperCase() + args.itemType.slice(1)} 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" as const, text: errorMsg }], 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 updating ${args.itemType}: ${error.message}` }], isError: true }; } }
• src/tools/definitions/editItem.ts:5-28 (schema)

  Zod schema defining the input parameters and structure for the edit_item tool.
  export const schema = z.object({ id: z.string().optional().describe("The ID of the task or project to edit"), name: z.string().optional().describe("The name of the task or project to edit (as fallback if ID not provided)"), itemType: z.enum(['task', 'project']).describe("Type of item to edit ('task' or 'project')"), // Common editable fields newName: z.string().optional().describe("New name for the item"), newNote: z.string().optional().describe("New note for the item"), newDueDate: z.string().optional().describe("New due date in ISO format (YYYY-MM-DD or full ISO date); set to empty string to clear"), newDeferDate: z.string().optional().describe("New defer date in ISO format (YYYY-MM-DD or full ISO date); set to empty string to clear"), newFlagged: z.boolean().optional().describe("Set flagged status (set to false for no flag, true for flag)"), newEstimatedMinutes: z.number().optional().describe("New estimated minutes"), // Task-specific fields newStatus: z.enum(['incomplete', 'completed', 'dropped']).optional().describe("New status for tasks (incomplete, completed, dropped)"), addTags: z.array(z.string()).optional().describe("Tags to add to the task"), removeTags: z.array(z.string()).optional().describe("Tags to remove from the task"), replaceTags: z.array(z.string()).optional().describe("Tags to replace all existing tags with"), // Project-specific fields newSequential: z.boolean().optional().describe("Whether the project should be sequential"), newFolderName: z.string().optional().describe("New folder to move the project to"), newProjectStatus: z.enum(['active', 'completed', 'dropped', 'onHold']).optional().describe("New status for projects") });
• src/server.ts:53-58 (registration)

  Registration of the 'edit_item' tool with the MCP server using its schema and handler.
  server.tool( "edit_item", "Edit a task or project in OmniFocus", editItemTool.schema.shape, editItemTool.handler );
• src/tools/primitives/editItem.ts:426-507 (handler)

  Core primitive function that generates AppleScript and executes it via osascript to perform the actual editing in OmniFocus.
  export async function editItem(params: EditItemParams): Promise<{ success: boolean, id?: string, name?: string, changedProperties?: string, error?: string }> { let tempFile: string | undefined; try { // Generate AppleScript const script = generateAppleScript(params); console.error("Executing AppleScript for editing (V2)..."); console.error(`Item type: ${params.itemType}, ID: ${params.id || 'not provided'}, Name: ${params.name || 'not provided'}`); // Log a preview of the script for debugging (first few lines) const scriptPreview = script.split('\n').slice(0, 10).join('\n') + '\n...'; console.error("AppleScript preview:\n", scriptPreview); // Write script to temporary file to avoid shell escaping issues tempFile = join(tmpdir(), `edit_omnifocus_${Date.now()}.applescript`); writeFileSync(tempFile, script); // Execute AppleScript from file const { stdout, stderr } = await execAsync(`osascript ${tempFile}`); // Clean up temp file try { unlinkSync(tempFile); } catch (cleanupError) { console.error("Failed to clean up temp file:", cleanupError); } if (stderr) { console.error("AppleScript stderr:", stderr); } console.error("AppleScript stdout:", stdout); // Parse the result try { const result = JSON.parse(stdout); // Return the result return { success: result.success, id: result.id, name: result.name, changedProperties: result.changedProperties, error: result.error }; } catch (parseError) { console.error("Error parsing AppleScript result:", parseError); return { success: false, error: `Failed to parse result: ${stdout}` }; } } catch (error: any) { // Clean up temp file if it exists if (tempFile) { try { unlinkSync(tempFile); } catch (cleanupError) { // Ignore cleanup errors } } console.error("Error in editItem execution:", error); // Include more detailed error information if (error.message && error.message.includes('syntax error')) { console.error("This appears to be an AppleScript syntax error. Review the script generation logic."); } return { success: false, error: error?.message || "Unknown error in editItem" }; } }
• src/tools/primitives/editItem.ts:14-37 (helper)

  TypeScript interface defining parameters for the editItem primitive function.
  export interface EditItemParams { id?: string; // ID of the task or project to edit name?: string; // Name of the task or project to edit (as fallback if ID not provided) itemType: 'task' | 'project'; // Type of item to edit // Common editable fields newName?: string; // New name for the item newNote?: string; // New note for the item newDueDate?: string; // New due date in ISO format (empty string to clear) newDeferDate?: string; // New defer date in ISO format (empty string to clear) newFlagged?: boolean; // New flagged status (false to remove flag, true to add flag) newEstimatedMinutes?: number; // New estimated minutes // Task-specific fields newStatus?: TaskStatus; // New status for tasks (incomplete, completed, dropped) addTags?: string[]; // Tags to add to the task removeTags?: string[]; // Tags to remove from the task replaceTags?: string[]; // Tags to replace all existing tags with // Project-specific fields newSequential?: boolean; // Whether the project should be sequential newFolderName?: string; // New folder to move the project to newProjectStatus?: ProjectStatus; // New status for projects }