MCP OmniFocus

Instructions

Implementation Reference

• src/mcp_omnifocus/utils/omnifocus.py:177-200 (handler)

  Core implementation of the list_tasks tool. Constructs a JavaScript template using common functions (including formatTask) and evaluates it via evaluate_javascript to fetch and format all flattened tasks from OmniFocus.

  def list_tasks() -> list[dict[str, str]]:
      """List all tasks in OmniFocus.
  
      Returns:
          A list of dictionaries containing task names, ids, project ids, and tag ids.
      """
      script = Template(
          dedent("""
      ${__common_functions__}
  
      (() => {
          return flattenedTasks.map((task) => {
              try {
                  return formatTask(task);
              } catch (e) {
                  return null;
              }
          }).filter(Boolean);
      })();
      """)
      )
  
      return evaluate_javascript(script.substitute(__common_functions__=__common_functions__))

• src/mcp_omnifocus/server.py:49-52 (registration)

  Registers the 'list_tasks' tool in the FastMCP server using @mcp.tool decorator. Serves as the MCP tool handler, delegating execution to the core omnifocus.list_tasks() implementation.

  @mcp.tool
  def list_tasks() -> list[dict[str, str]]:
      """List all tasks in OmniFocus. The task full name is the full heirarchy of the task, including parent tags."""
      return omnifocus.list_tasks()

• src/mcp_omnifocus/utils/omnifocus.py:9-102 (helper)

  Shared JavaScript functions injected into list_tasks script, including formatTask which structures task data into the output dict format, taskStatusToString for status mapping, and others used in task listing.

  __common_functions__ = dedent("""
  function projectStatusToString(status) {
      // Handle null/undefined cases
      if (!status) {
          return 'Unknown';
      }
      
      // Map of status objects to their string representations
      const statusMap = {
          [Project.Status.Active]: 'Active',
          [Project.Status.Done]: 'Done', 
          [Project.Status.Dropped]: 'Dropped',
          [Project.Status.OnHold]: 'OnHold',
      };
      
      // Return the corresponding string or 'Unknown' if not found
      return statusMap[status] || 'Unknown';
  }
                                
  function taskStatusToString(status) {
      // Handle null/undefined cases
      if (!status) {
          return 'Unknown';
      }
      
      // Map of status objects to their string representations
      const statusMap = {
          [Task.Status.Available]: 'Available',
          [Task.Status.Blocked]: 'Blocked', 
          [Task.Status.Completed]: 'Completed',
          [Task.Status.Dropped]: 'Dropped',
          [Task.Status.DueSoon]: 'DueSoon',
          [Task.Status.Next]: 'Next',
          [Task.Status.Overdue]: 'Overdue'
      };
      
      // Return the corresponding string or 'Unknown' if not found
      return statusMap[status] || 'Unknown';
  }
                                
  function getFullTagName(tag) {
      const names = [];
      let currentTag = tag;
      // Traverse up the hierarchy
      while (currentTag) {
          names.unshift(currentTag.name);
          try {
              currentTag = currentTag.parent;
          } catch (e) {
              break;  // If we can't access parent, stop traversing
          }
      }
      return names.join(' : ');
  };
                                
  function getLeafNodes(node) {
      if (!node.children || node.children.length === 0) {
          return [node];
      }
      return node.children.flatMap(getLeafNodes);
  }
  
  function getPerspectiveByName(name) {
      let perspectives = new Array()
      perspectives = perspectives.concat(Perspective.BuiltIn.all)
      perspectives = perspectives.concat(Perspective.Custom.all)
      perspectiveNames = perspectives.map(perspective => perspective.name.toUpperCase())
  
      return perspectives[perspectiveNames.indexOf(name.toUpperCase())] || null;
  }
                                
  function formatTask(task) {
      return {
          id: task.id.primaryKey,
          name: task.name,
          projectName: task.containingProject ? task.containingProject.name : null,
          status: taskStatusToString(task.taskStatus),
          flagged: task.flagged,
          deferDate: task.deferDate ? task.deferDate.toString() : null,
          dueDate: task.dueDate ? task.dueDate.toString() : null,
          dropped: task.dropped,
          completed: task.completed,
          tags: task.tags ? task.tags.map(tt => tt.name) : [],
          note: task.note
      };
  }
                                
  function taskStatusFilter(task, allowedStatuses) {
      if (!allowedStatuses || allowedStatuses.length === 0) {
          return true;
      }
      return allowedStatuses.includes(taskStatusToString(task.taskStatus));
  }
  """)

• src/mcp_omnifocus/server.py:49-50 (schema)

  Defines the output schema as list[dict[str, str]] for the list_tasks tool via type hint, used by FastMCP for validation.

  @mcp.tool
  def list_tasks() -> list[dict[str, str]]: