OmniFocus-MCP

Instructions

Implementation Reference

• src/tools/definitions/dumpDatabase.ts:10-36 (handler)

  MCP tool handler for 'dump_database' that fetches the OmniFocus database using dumpDatabase() and formats it into a compact text report with options to hide completed tasks and recurring duplicates.

  export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) {
    try {
      // Get raw database
      const database = await dumpDatabase();
  
      // Format as compact report
      const formattedReport = formatCompactReport(database, {
        hideCompleted: args.hideCompleted !== false, // Default to true
        hideRecurringDuplicates: args.hideRecurringDuplicates !== false // Default to true
      });
  
      return {
        content: [{
          type: "text" as const,
          text: formattedReport
        }]
      };
    } catch (err: unknown) {
      return {
        content: [{
          type: "text" as const,
          text: `Error generating report. Please ensure OmniFocus is running and try again.`
        }],
        isError: true
      };
    }
  }

• src/tools/definitions/dumpDatabase.ts:5-8 (schema)

  Zod schema defining optional parameters for the dump_database tool: hideCompleted and hideRecurringDuplicates.

  export const schema = z.object({
    hideCompleted: z.boolean().optional().describe("Set to false to show completed and dropped tasks (default: true)"),
    hideRecurringDuplicates: z.boolean().optional().describe("Set to true to hide duplicate instances of recurring tasks (default: true)")
  });

• src/server.ts:25-30 (registration)

  Registration of the 'dump_database' tool in the MCP server, specifying name, description, schema, and handler.

  server.tool(
    "dump_database",
    "Gets the current state of your OmniFocus database",
    dumpDatabaseTool.schema.shape,
    dumpDatabaseTool.handler
  );

• src/tools/dumpDatabase.ts:69-195 (helper)

  Core helper function that executes an OmniFocus AppleScript to dump the full database (tasks, projects, folders, tags) and processes it into a structured OmnifocusDatabase object. Called by the tool handler.

  export async function dumpDatabase(): Promise<OmnifocusDatabase> {
    
    try {
      // Execute the OmniFocus script
      const data = await executeOmniFocusScript('@omnifocusDump.js') as OmnifocusDumpData;
      // wait 1 second
      await new Promise(resolve => setTimeout(resolve, 1000));
   
      // Create an empty database if no data returned
      if (!data) {
        return {
          exportDate: new Date().toISOString(),
          tasks: [],
          projects: {},
          folders: {},
          tags: {}
        };
      }
      
      // Initialize the database object
      const database: OmnifocusDatabase = {
        exportDate: data.exportDate,
        tasks: [],
        projects: {},
        folders: {},
        tags: {}
      };
      
      // Process tasks
      if (data.tasks && Array.isArray(data.tasks)) {
        // Convert the tasks to our OmnifocusTask format
        database.tasks = data.tasks.map((task: OmnifocusDumpTask) => {
          // Get tag names from the tag IDs
          const tagNames = (task.tags || []).map(tagId => {
            return data.tags[tagId]?.name || 'Unknown Tag';
          });
          
          return {
            id: String(task.id),
            name: String(task.name),
            note: String(task.note || ""),
            flagged: Boolean(task.flagged),
            completed: task.taskStatus === "Completed",
            completionDate: null, // Not available in the new format
            dropDate: null, // Not available in the new format
            taskStatus: String(task.taskStatus),
            active: task.taskStatus !== "Completed" && task.taskStatus !== "Dropped",
            dueDate: task.dueDate,
            deferDate: task.deferDate,
            estimatedMinutes: task.estimatedMinutes ? Number(task.estimatedMinutes) : null,
            tags: task.tags || [],
            tagNames: tagNames,
            parentId: task.parentTaskID || null,
            containingProjectId: task.projectID || null,
            projectId: task.projectID || null,
            childIds: task.children || [],
            hasChildren: (task.children && task.children.length > 0) || false,
            sequential: Boolean(task.sequential),
            completedByChildren: Boolean(task.completedByChildren),
            isRepeating: false, // Not available in the new format
            repetitionMethod: null, // Not available in the new format 
            repetitionRule: null, // Not available in the new format
            attachments: [], // Default empty array
            linkedFileURLs: [], // Default empty array
            notifications: [], // Default empty array
            shouldUseFloatingTimeZone: false // Default value
          };
        });
      }
      
      // Process projects
      if (data.projects) {
        for (const [id, project] of Object.entries(data.projects)) {
          database.projects[id] = {
            id: String(project.id),
            name: String(project.name),
            status: String(project.status),
            folderID: project.folderID || null,
            sequential: Boolean(project.sequential),
            effectiveDueDate: project.effectiveDueDate,
            effectiveDeferDate: project.effectiveDeferDate,
            dueDate: project.dueDate,
            deferDate: project.deferDate,
            completedByChildren: Boolean(project.completedByChildren),
            containsSingletonActions: Boolean(project.containsSingletonActions),
            note: String(project.note || ""),
            tasks: project.tasks || [],
            flagged: false, // Default value
            estimatedMinutes: null // Default value
          };
        }
      }
      
      // Process folders
      if (data.folders) {
        for (const [id, folder] of Object.entries(data.folders)) {
          database.folders[id] = {
            id: String(folder.id),
            name: String(folder.name),
            parentFolderID: folder.parentFolderID || null,
            status: String(folder.status),
            projects: folder.projects || [],
            subfolders: folder.subfolders || []
          };
        }
      }
      
      // Process tags
      if (data.tags) {
        for (const [id, tag] of Object.entries(data.tags)) {
          database.tags[id] = {
            id: String(tag.id),
            name: String(tag.name),
            parentTagID: tag.parentTagID || null,
            active: Boolean(tag.active),
            allowsNextAction: Boolean(tag.allowsNextAction),
            tasks: tag.tasks || []
          };
        }
      }
      
      return database;
    } catch (error) {
      console.error("Error in dumpDatabase:", error);
      throw error;
    }
  }

• src/tools/definitions/dumpDatabase.ts:47-272 (helper)

  Helper function called by the handler to format the raw database into a human-readable compact report with hierarchy, legends, filtering options, and abbreviated tags.

  function formatCompactReport(database: any, options: { hideCompleted: boolean, hideRecurringDuplicates: boolean }): string {
    const { hideCompleted, hideRecurringDuplicates } = options;
  
    // Get current date for the header
    const today = new Date();
    const dateStr = today.toISOString().split('T')[0];
  
    let output = `# OMNIFOCUS [${dateStr}]\n\n`;
  
    // Add legend
    output += `FORMAT LEGEND:
  F: Folder | P: Project | •: Task | 🚩: Flagged
  Dates: [M/D] | Duration: (30m) or (2h) | Tags: <tag1,tag2>
  Status: #next #avail #block #due #over #compl #drop\n\n`;
  
    // Map of folder IDs to folder objects for quick lookup
    const folderMap = new Map();
    Object.values(database.folders).forEach((folder: any) => {
      folderMap.set(folder.id, folder);
    });
  
    // Get all tag names to compute minimum unique prefixes
    const allTagNames = Object.values(database.tags).map((tag: any) => tag.name);
    const tagPrefixMap = computeMinimumUniquePrefixes(allTagNames);
  
    // Function to get folder hierarchy path
    function getFolderPath(folderId: string): string[] {
      const path = [];
      let currentId = folderId;
  
      while (currentId) {
        const folder = folderMap.get(currentId);
        if (!folder) break;
  
        path.unshift(folder.name);
        currentId = folder.parentFolderID;
      }
  
      return path;
    }
  
    // Get root folders (no parent)
    const rootFolders = Object.values(database.folders).filter((folder: any) => !folder.parentFolderID);
  
    // Process folders recursively
    function processFolder(folder: any, level: number): string {
      const indent = '   '.repeat(level);
      let folderOutput = `${indent}F: ${folder.name}\n`;
  
      // Process subfolders
      if (folder.subfolders && folder.subfolders.length > 0) {
        for (const subfolderId of folder.subfolders) {
          const subfolder = database.folders[subfolderId];
          if (subfolder) {
            folderOutput += `${processFolder(subfolder, level + 1)}`;
          }
        }
      }
  
      // Process projects in this folder
      if (folder.projects && folder.projects.length > 0) {
        for (const projectId of folder.projects) {
          const project = database.projects[projectId];
          if (project) {
            folderOutput += processProject(project, level + 1);
          }
        }
      }
  
      return folderOutput;
    }
  
    // Process a project
    function processProject(project: any, level: number): string {
      const indent = '   '.repeat(level);
  
      // Skip if it's completed or dropped and we're hiding completed items
      if (hideCompleted && (project.status === 'Done' || project.status === 'Dropped')) {
        return '';
      }
  
      // Format project status info
      let statusInfo = '';
      if (project.status === 'OnHold') {
        statusInfo = ' [OnHold]';
      } else if (project.status === 'Dropped') {
        statusInfo = ' [Dropped]';
      }
  
      // Add due date if present
      if (project.dueDate) {
        const dueDateStr = formatCompactDate(project.dueDate);
        statusInfo += statusInfo ? ` [DUE:${dueDateStr}]` : ` [DUE:${dueDateStr}]`;
      }
  
      // Add flag if present
      const flaggedSymbol = project.flagged ? ' 🚩' : '';
  
      let projectOutput = `${indent}P: ${project.name}${flaggedSymbol}${statusInfo}\n`;
  
      // Process tasks in this project
      const projectTasks = database.tasks.filter((task: any) =>
        task.projectId === project.id && !task.parentId
      );
  
      if (projectTasks.length > 0) {
        for (const task of projectTasks) {
          projectOutput += processTask(task, level + 1);
        }
      }
  
      return projectOutput;
    }
  
    // Process a task
    function processTask(task: any, level: number): string {
      const indent = '   '.repeat(level);
  
      // Skip if it's completed or dropped and we're hiding completed items
      if (hideCompleted && (task.completed || task.taskStatus === 'Completed' || task.taskStatus === 'Dropped')) {
        return '';
      }
  
      // Flag symbol
      const flagSymbol = task.flagged ? '🚩 ' : '';
  
      // Format dates
      let dateInfo = '';
      if (task.dueDate) {
        const dueDateStr = formatCompactDate(task.dueDate);
        dateInfo += ` [DUE:${dueDateStr}]`;
      }
      if (task.deferDate) {
        const deferDateStr = formatCompactDate(task.deferDate);
        dateInfo += ` [defer:${deferDateStr}]`;
      }
  
      // Format duration
      let durationStr = '';
      if (task.estimatedMinutes) {
        // Convert to hours if >= 60 minutes
        if (task.estimatedMinutes >= 60) {
          const hours = Math.floor(task.estimatedMinutes / 60);
          durationStr = ` (${hours}h)`;
        } else {
          durationStr = ` (${task.estimatedMinutes}m)`;
        }
      }
  
      // Format tags
      let tagsStr = '';
      if (task.tagNames && task.tagNames.length > 0) {
        // Use minimum unique prefixes for tag names
        const abbreviatedTags = task.tagNames.map((tag: string) => {
          return tagPrefixMap.get(tag) || tag;
        });
  
        tagsStr = ` <${abbreviatedTags.join(',')}>`;
      }
  
      // Format status
      let statusStr = '';
      switch (task.taskStatus) {
        case 'Next':
          statusStr = ' #next';
          break;
        case 'Available':
          statusStr = ' #avail';
          break;
        case 'Blocked':
          statusStr = ' #block';
          break;
        case 'DueSoon':
          statusStr = ' #due';
          break;
        case 'Overdue':
          statusStr = ' #over';
          break;
        case 'Completed':
          statusStr = ' #compl';
          break;
        case 'Dropped':
          statusStr = ' #drop';
          break;
      }
  
      let taskOutput = `${indent}• ${flagSymbol}${task.name}${dateInfo}${durationStr}${tagsStr}${statusStr}\n`;
  
      // Process subtasks
      if (task.childIds && task.childIds.length > 0) {
        const childTasks = database.tasks.filter((t: any) => task.childIds.includes(t.id));
  
        for (const childTask of childTasks) {
          taskOutput += processTask(childTask, level + 1);
        }
      }
  
      return taskOutput;
    }
  
    // Process all root folders
    for (const folder of rootFolders) {
      output += processFolder(folder, 0);
    }
  
    // Process projects not in any folder (if any)
    const rootProjects = Object.values(database.projects).filter((project: any) => !project.folderID);
  
    for (const project of rootProjects) {
      output += processProject(project, 0);
    }
  
    // Process tasks in the Inbox (not in any project)
    const inboxTasks = database.tasks.filter(function (task: any) {
      return !task.projectId;
    });
  
    if (inboxTasks.length > 0) {
      output += `\nP: Inbox\n`;
      for (const task of inboxTasks) {
        output += processTask(task, 0);
      }
    }
  
    return output;
  }