MCP OmniFocus

Instructions

Implementation Reference

• src/mcp_omnifocus/server.py:55-59 (handler)

  The handler function decorated with @mcp.tool that defines and registers the list_inbox tool. It delegates to omnifocus.list_perspective_tasks("Inbox").

  @mcp.tool
  def list_inbox() -> list[dict[str, str]]:
      """List all tasks in the OmniFocus Inbox."""
      return omnifocus.list_perspective_tasks("Inbox")

• src/mcp_omnifocus/utils/omnifocus.py:202-250 (helper)

  Core helper function implementing the logic to list tasks from a specific OmniFocus perspective ('Inbox' for list_inbox) using JXA script execution.

  def list_perspective_tasks(perspective_name: str) -> list[dict[str, str]]:
      """List all tasks in a specific perspective in OmniFocus.
  
      Args:
          perspective_name: The name of the perspective to filter tasks by.
  
      Returns:
          A list of dictionaries containing task names, ids, project ids, and tag ids.
      """
      script = Template(
          dedent("""
      ${__common_functions__}                            
  
      (() => {
          let perspective = getPerspectiveByName("${perspective_name}");
  
          if (!perspective) {
              throw "Could not find perspective: " + perspective_name.toString();
          }
  
          win = document.windows[0];
          win.perspective = perspective;
  
          if (perspective == Perspective.BuiltIn.Forecast) {
              var now = new Date();
              var today = Calendar.current.startOfDay(now);
              var dc = new DateComponents();
              dc.day = -1;
              var yesterday = Calendar.current.dateByAddingDateComponents(today, dc);
              win.selectForecastDays([win.forecastDayForDate(yesterday), win.forecastDayForDate(today)]);
          }
  
          return getLeafNodes(win.content.rootNode).map((l) => {
              const task = l.object;
              try {
                  return formatTask(task);
              } catch (e) {
                  return null;
              }
          }).filter(Boolean);
  
      })();
      """)
      )
  
      return evaluate_javascript(
          script.substitute(__common_functions__=__common_functions__, perspective_name=perspective_name)
      )

• src/mcp_omnifocus/utils/scripting.py:45-60 (helper)

  Utility function to evaluate JavaScript in OmniFocus via AppleScript JXA, used by list_perspective_tasks.

  def evaluate_javascript(script: str) -> Any:
      """Execute a JavaScript script in OmniFocus.
  
      See; https://www.omni-automation.com/omnifocus/index.html
  
      Args:
          script: The JavaScript code to execute.
  
      Returns:
          The output of the script as a string.
      """
      jxa_script = f'let script = `{script}`;\n(() => {{\n   return JSON.stringify(Application("OmniFocus").evaluateJavascript(script));\n}})();'
  
      output = run_jxa_script(jxa_script)
      return json.loads(output) if output else {}

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

  Common JavaScript functions used in the JXA scripts for task formatting, status mapping, perspective lookup, etc., injected into list_perspective_tasks script.

  __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));
  }
  """)