OmniFocus-MCP

Instructions

Implementation Reference

• src/server.ts:39-44 (registration)

  Registers the 'add_project' MCP tool, providing the name, description, input schema, and handler function.

  server.tool(
    "add_project",
    "Add a new project to OmniFocus",
    addProjectTool.schema.shape,
    addProjectTool.handler
  );

• src/tools/definitions/addProject.ts:5-15 (schema)

  Zod schema defining the input parameters for the add_project tool.

  export const schema = z.object({
    name: z.string().describe("The name of the project"),
    note: z.string().optional().describe("Additional notes for the project"),
    dueDate: z.string().optional().describe("The due date of the project in ISO format (YYYY-MM-DD or full ISO date)"),
    deferDate: z.string().optional().describe("The defer date of the project in ISO format (YYYY-MM-DD or full ISO date)"),
    flagged: z.boolean().optional().describe("Whether the project is flagged or not"),
    estimatedMinutes: z.number().optional().describe("Estimated time to complete the project, in minutes"),
    tags: z.array(z.string()).optional().describe("Tags to assign to the project"),
    folderName: z.string().optional().describe("The name of the folder to add the project to (will add to root if not specified)"),
    sequential: z.boolean().optional().describe("Whether tasks in the project should be sequential (default: false)")
  });

• src/tools/definitions/addProject.ts:17-67 (handler)

  The main handler function for the add_project tool. Validates input via schema, calls the primitive addProject function, and formats success/error responses.

  export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) {
    try {
      // Call the addProject function 
      const result = await addProject(args as AddProjectParams);
      
      if (result.success) {
        // Project was added successfully
        let locationText = args.folderName 
          ? `in folder "${args.folderName}"` 
          : "at the root level";
          
        let tagText = args.tags && args.tags.length > 0
          ? ` with tags: ${args.tags.join(', ')}`
          : "";
          
        let dueDateText = args.dueDate
          ? ` due on ${new Date(args.dueDate).toLocaleDateString()}`
          : "";
          
        let sequentialText = args.sequential
          ? " (sequential)"
          : " (parallel)";
          
        return {
          content: [{
            type: "text" as const,
            text: `✅ Project "${args.name}" created successfully ${locationText}${dueDateText}${tagText}${sequentialText}.`
          }]
        };
      } else {
        // Project creation failed
        return {
          content: [{
            type: "text" as const,
            text: `Failed to create project: ${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 project: ${error.message}`
        }],
        isError: true
      };
    }
  } 

• src/tools/primitives/addProject.ts:116-156 (helper)

  Core implementation of project addition: generates AppleScript to interact with OmniFocus via osascript and parses the result.

  export async function addProject(params: AddProjectParams): Promise<{success: boolean, projectId?: string, error?: string}> {
    try {
      // Generate AppleScript
      const script = generateAppleScript(params);
      
      console.error("Executing AppleScript directly...");
      
      // Execute AppleScript directly
      const { stdout, stderr } = await execAsync(`osascript -e '${script}'`);
      
      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,
          projectId: result.projectId,
          error: result.error
        };
      } 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 addProject:", error);
      return {
        success: false,
        error: error?.message || "Unknown error in addProject"
      };
    }
  } 

• src/tools/primitives/addProject.ts:7-17 (schema)

  TypeScript interface defining parameters for the primitive addProject function, matching the tool schema.

  export interface AddProjectParams {
    name: string;
    note?: string;
    dueDate?: string; // ISO date string
    deferDate?: string; // ISO date string
    flagged?: boolean;
    estimatedMinutes?: number;
    tags?: string[]; // Tag names
    folderName?: string; // Folder name to add project to
    sequential?: boolean; // Whether tasks should be sequential or parallel
  }