OmniFocus MCP Enhanced

Instructions

Implementation Reference

• src/tools/definitions/filterTasks.ts:68-88 (handler)

  MCP tool handler: calls the filterTasks primitive with validated args and returns formatted text response or error.

  export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) {
    try {
      const result = await filterTasks(args);
      
      return {
        content: [{
          type: "text" as const,
          text: result
        }]
      };
    } catch (err: unknown) {
      const errorMessage = err instanceof Error ? err.message : 'Unknown error occurred';
      return {
        content: [{
          type: "text" as const,
          text: `Error filtering tasks: ${errorMessage}`
        }],
        isError: true
      };
    }
  }

• src/tools/definitions/filterTasks.ts:19-66 (schema)

  Zod schema defining all input parameters for the filter_tasks tool with descriptions.

  export const schema = z.object({
    // 🎯 任务状态过滤
    taskStatus: z.array(TaskStatusEnum).optional().describe("Filter by task status. Can specify multiple statuses"),
    
    // 📍 透视范围  
    perspective: PerspectiveEnum.optional().describe("Limit search to specific perspective: inbox, flagged, all tasks"),
    
    // 📁 项目/标签过滤
    projectFilter: z.string().optional().describe("Filter by project name (partial match)"),
    tagFilter: z.union([z.string(), z.array(z.string())]).optional().describe("Filter by tag name(s). Can be single tag or array of tags"),
    exactTagMatch: z.boolean().optional().describe("Set to true for exact tag name match, false for partial (default: false)"),
    
    // 📅 截止日期过滤
    dueBefore: z.string().optional().describe("Show tasks due before this date (ISO format: YYYY-MM-DD)"),
    dueAfter: z.string().optional().describe("Show tasks due after this date (ISO format: YYYY-MM-DD)"),
    dueToday: z.boolean().optional().describe("Show tasks due today"),
    dueThisWeek: z.boolean().optional().describe("Show tasks due this week"),
    dueThisMonth: z.boolean().optional().describe("Show tasks due this month"),
    overdue: z.boolean().optional().describe("Show overdue tasks only"),
    
    // 🚀 推迟日期过滤
    deferBefore: z.string().optional().describe("Show tasks with defer date before this date (ISO format: YYYY-MM-DD)"),
    deferAfter: z.string().optional().describe("Show tasks with defer date after this date (ISO format: YYYY-MM-DD)"),
    deferToday: z.boolean().optional().describe("Show tasks deferred to today"),
    deferThisWeek: z.boolean().optional().describe("Show tasks deferred to this week"),
    deferAvailable: z.boolean().optional().describe("Show tasks whose defer date has passed (now available)"),
    
    // ✅ 完成日期过滤
    completedBefore: z.string().optional().describe("Show tasks completed before this date (ISO format: YYYY-MM-DD)"),
    completedAfter: z.string().optional().describe("Show tasks completed after this date (ISO format: YYYY-MM-DD)"),
    completedToday: z.boolean().optional().describe("Show tasks completed today"),
    completedThisWeek: z.boolean().optional().describe("Show tasks completed this week"),
    completedThisMonth: z.boolean().optional().describe("Show tasks completed this month"),
    
    // 🚩 其他维度
    flagged: z.boolean().optional().describe("Filter by flagged status"),
    searchText: z.string().optional().describe("Search in task names and notes"),
    hasEstimate: z.boolean().optional().describe("Filter tasks that have time estimates"),
    estimateMin: z.number().optional().describe("Minimum estimated minutes"),
    estimateMax: z.number().optional().describe("Maximum estimated minutes"),
    hasNote: z.boolean().optional().describe("Filter tasks that have notes"),
    inInbox: z.boolean().optional().describe("Filter tasks in inbox"),
    
    // 📊 输出控制
    limit: z.number().max(1000).optional().describe("Maximum number of tasks to return (default: 100)"),
    sortBy: z.enum(["name", "dueDate", "deferDate", "completedDate", "flagged", "project"]).optional().describe("Sort results by field"),
    sortOrder: z.enum(["asc", "desc"]).optional().describe("Sort order (default: asc)")
  });

• src/server.ts:128-133 (registration)

  Registers the filter_tasks tool on the MCP server using its schema and handler.

  server.tool(
    "filter_tasks",
    "Advanced task filtering with unlimited perspective combinations - status, dates, projects, tags, search, and more",
    filterTasksTool.schema.shape,
    filterTasksTool.handler
  );

• src/tools/primitives/filterTasks.ts:57-155 (helper)

  Core helper function that executes the OmniFocus filtering script, processes results, formats output grouped by project with rich details.

  export async function filterTasks(options: FilterTasksOptions = {}): Promise<string> {
    try {
      // 设置默认值
      const {
        perspective = "all",
        exactTagMatch = false,
        limit = 100,
        sortBy = "name",
        sortOrder = "asc"
      } = options;
      
      
      // 执行常规过滤脚本
      const result = await executeOmniFocusScript('@filterTasks.js', {
        ...options,
        perspective,
        exactTagMatch,
        limit,
        sortBy,
        sortOrder
      });
      
      if (typeof result === 'string') {
        return result;
      }
      
      // 如果结果是对象，格式化它
      if (result && typeof result === 'object') {
        const data = result as any;
        
        if (data.error) {
          throw new Error(data.error);
        }
        
        // 格式化过滤结果
        let output = `# 🔍 FILTERED TASKS\n\n`;
        
        // 显示过滤条件摘要
        const filterSummary = buildFilterSummary(options);
        if (filterSummary) {
          output += `**Filter**: ${filterSummary}\n\n`;
        }
        
        if (data.tasks && Array.isArray(data.tasks)) {
          if (data.tasks.length === 0) {
            output += "🎯 No tasks match your filter criteria.\n";
            
            // 提供一些建议
            output += "\n**Tips**:\n";
            output += "- Try broadening your search criteria\n";
            output += "- Check if tasks exist in the specified project/tags\n";
            output += "- Use `get_inbox_tasks` or `get_flagged_tasks` for basic views\n";
          } else {
            const taskCount = data.tasks.length;
            const totalCount = data.totalCount || taskCount;
            
            output += `Found ${taskCount} task${taskCount === 1 ? '' : 's'}`;
            if (taskCount < totalCount) {
              output += ` (showing first ${taskCount} of ${totalCount})`;
            }
            output += `:\n\n`;
            
            // 按项目分组显示任务
            const tasksByProject = groupTasksByProject(data.tasks);
            
            tasksByProject.forEach((tasks, projectName) => {
              if (tasksByProject.size > 1) {
                output += `## 📁 ${projectName}\n`;
              }
              
              tasks.forEach((task: any) => {
                output += formatTask(task);
                output += '\n';
              });
              
              if (tasksByProject.size > 1) {
                output += '\n';
              }
            });
            
            // 显示排序信息
            if (data.sortedBy) {
              output += `\n📊 **Sorted by**: ${data.sortedBy} (${data.sortOrder || 'asc'})\n`;
            }
          }
        } else {
          output += "No task data available\n";
        }
        
        return output;
      }
      
      return "Unexpected result format from OmniFocus";
      
    } catch (error) {
      console.error("Error in filterTasks:", error);
      throw new Error(`Failed to filter tasks: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }