OmniFocus MCP Enhanced

Instructions

Implementation Reference

• src/tools/definitions/getInboxTasks.ts:9-31 (handler)

  MCP tool handler function that validates input, calls the primitive getInboxTasks, and returns the result in MCP content format or error.

  export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) {
    try {
      const result = await getInboxTasks({
        hideCompleted: args.hideCompleted !== false // Default to true
      });
      
      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 getting inbox tasks: ${errorMessage}`
        }],
        isError: true
      };
    }
  }

• src/tools/definitions/getInboxTasks.ts:5-7 (schema)

  Zod schema defining the input parameters for the get_inbox_tasks tool.

  export const schema = z.object({
    hideCompleted: z.boolean().optional().describe("Set to false to show completed tasks in inbox (default: true)")
  });

• src/server.ts:99-104 (registration)

  Registration of the 'get_inbox_tasks' tool on the MCP server using server.tool() with name, description, schema, and handler.

  server.tool(
    "get_inbox_tasks",
    "Get tasks from OmniFocus inbox perspective",
    getInboxTasksTool.schema.shape,
    getInboxTasksTool.handler
  );

• src/tools/primitives/getInboxTasks.ts:7-62 (helper)

  Core helper function implementing the logic to execute OmniFocus script for inbox tasks and format the markdown output.

  export async function getInboxTasks(options: GetInboxTasksOptions = {}): Promise<string> {
    const { hideCompleted = true } = options;
    
    try {
      // Execute the inbox script
      const result = await executeOmniFocusScript('@inboxTasks.js', { 
        hideCompleted: hideCompleted 
      });
      
      if (typeof result === 'string') {
        return result;
      }
      
      // If result is an object, format it
      if (result && typeof result === 'object') {
        const data = result as any;
        
        if (data.error) {
          throw new Error(data.error);
        }
        
        // Format the inbox tasks
        let output = `# INBOX TASKS\n\n`;
        
        if (data.tasks && Array.isArray(data.tasks)) {
          if (data.tasks.length === 0) {
            output += "📪 Inbox is empty - well done!\n";
          } else {
            output += `📥 Found ${data.tasks.length} task${data.tasks.length === 1 ? '' : 's'} in inbox:\n\n`;
            
            data.tasks.forEach((task: any, index: number) => {
              const flagSymbol = task.flagged ? '🚩 ' : '';
              const dueDateStr = task.dueDate ? ` [DUE: ${new Date(task.dueDate).toLocaleDateString()}]` : '';
              const statusStr = task.taskStatus !== 'Available' ? ` (${task.taskStatus})` : '';
              
              output += `${index + 1}. ${flagSymbol}${task.name}${dueDateStr}${statusStr}\n`;
              
              if (task.note && task.note.trim()) {
                output += `   📝 ${task.note.trim()}\n`;
              }
            });
          }
        } else {
          output += "No inbox data available\n";
        }
        
        return output;
      }
      
      return "Unexpected result format from OmniFocus";
      
    } catch (error) {
      console.error("Error in getInboxTasks:", error);
      throw new Error(`Failed to get inbox tasks: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }