OmniFocus-MCP

Instructions

Implementation Reference

• src/tools/definitions/batchRemoveItems.ts:13-80 (handler)

  MCP tool handler that validates input params, calls the batchRemoveItems primitive function, processes results, and returns formatted text response with success/failure details.

  export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) {
    try {
      // Validate that each item has at least an ID or name
      for (const item of args.items) {
        if (!item.id && !item.name) {
          return {
            content: [{
              type: "text" as const,
              text: "Each item must have either id or name provided to remove it."
            }],
            isError: true
          };
        }
      }
      
      // Call the batchRemoveItems function
      const result = await batchRemoveItems(args.items as BatchRemoveItemsParams[]);
      
      if (result.success) {
        const successCount = result.results.filter(r => r.success).length;
        const failureCount = result.results.filter(r => !r.success).length;
        
        let message = `✅ Successfully removed ${successCount} items.`;
        
        if (failureCount > 0) {
          message += ` ⚠️ Failed to remove ${failureCount} items.`;
        }
        
        // Include details about removed items
        const details = result.results.map((item, index) => {
          if (item.success) {
            const itemType = args.items[index].itemType;
            return `- ✅ ${itemType}: "${item.name}"`;
          } else {
            const itemType = args.items[index].itemType;
            const identifier = args.items[index].id || args.items[index].name;
            return `- ❌ ${itemType}: ${identifier} - Error: ${item.error}`;
          }
        }).join('\n');
        
        return {
          content: [{
            type: "text" as const,
            text: `${message}\n\n${details}`
          }]
        };
      } else {
        // Batch operation failed completely
        return {
          content: [{
            type: "text" as const,
            text: `Failed to process batch removal: ${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 processing batch removal: ${error.message}`
        }],
        isError: true
      };
    }
  } 

• src/tools/definitions/batchRemoveItems.ts:5-11 (schema)

  Zod schema defining the input structure: array of items each with optional id/name and required itemType (task/project).

  export const schema = z.object({
    items: z.array(z.object({
      id: z.string().optional().describe("The ID of the task or project to remove"),
      name: z.string().optional().describe("The name of the task or project to remove (as fallback if ID not provided)"),
      itemType: z.enum(['task', 'project']).describe("Type of item to remove ('task' or 'project')")
    })).describe("Array of items (tasks or projects) to remove")
  });

• src/server.ts:67-72 (registration)

  Registers the batch_remove_items tool on the MCP server, providing name, description, schema, and handler from the definitions module.

  server.tool(
    "batch_remove_items",
    "Remove multiple tasks or projects from OmniFocus in a single operation",
    batchRemoveItemsTool.schema.shape,
    batchRemoveItemsTool.handler
  );

• src/tools/primitives/batchRemoveItems.ts:24-64 (helper)

  Core batch removal logic: iterates over items, calls removeItem for each, collects individual results into BatchResult, handles per-item and overall errors.

  export async function batchRemoveItems(items: BatchRemoveItemsParams[]): Promise<BatchResult> {
    try {
      // Results array to track individual operation outcomes
      const results: ItemResult[] = [];
      
      // Process each item in sequence
      for (const item of items) {
        try {
          // Remove item
          const itemResult = await removeItem(item);
          results.push({
            success: itemResult.success,
            id: itemResult.id,
            name: itemResult.name,
            error: itemResult.error
          });
        } catch (itemError: any) {
          // Handle individual item errors
          results.push({
            success: false,
            error: itemError.message || "Unknown error processing item"
          });
        }
      }
      
      // Determine overall success (true if at least one item was removed successfully)
      const overallSuccess = results.some(result => result.success);
      
      return {
        success: overallSuccess,
        results: results
      };
    } catch (error: any) {
      console.error("Error in batchRemoveItems:", error);
      return {
        success: false,
        results: [],
        error: error.message || "Unknown error in batchRemoveItems"
      };
    }
  }