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'}`); } }