MCP OmniFocus

Instructions

Implementation Reference

• src/mcp_omnifocus/server.py:129-144 (handler)

  MCP tool handler and registration for 'list_tasks_by_project'. Includes input schema via Annotated Fields and Pydantic, defaults task_status, and delegates execution to omnifocus utility.

  @mcp.tool
  def list_tasks_by_project(
      project_id: Annotated[str, Field(description="The ID of the project to list tasks for")],
      task_status: Annotated[
          list[omnifocus.TaskStatus] | None,
          Field(
              description="The status of the tasks to list. If None, it is the equivelant "
              "of requesting available and unblocked tasks ['Available', 'Next', 'Overdue', 'DueSoon']."
          ),
      ] = None,
  ) -> list[dict[str, str]]:
      """List all tasks in a specific project."""
      if task_status is None:
          task_status = ["Available", "Next", "Overdue", "DueSoon"]
      return omnifocus.list_tasks_by_project(project_id, task_status=task_status)

• src/mcp_omnifocus/utils/omnifocus.py:517-559 (helper)

  Core implementation of listing tasks by project using JavaScript evaluation in OmniFocus, filtering by task_status, formatting results with helper functions.

  def list_tasks_by_project(project_id: str, task_status: list[TaskStatus] | None = None) -> list[dict[str, str]]:
      """List all tasks in a specific project in OmniFocus.
  
      Args:
          project_id: The ID of the project to filter tasks by.
          task_status: A list of task statuses to filter by. If None, all tasks are returned.
  
      Returns:
          A list of dictionaries containing task names, ids, project ids, and tag ids.
      """
      script = Template(
          dedent("""
      ${__common_functions__}
      
      (() => {
          let project = Project.byIdentifier("${project_id}");
          const allowedStatuses = ${task_status};
  
          if (!project) {
              throw "Could not find project: " + project_id.toString();
          }
  
          return project.tasks
              .filter(task => taskStatusFilter(task, allowedStatuses))
              .map((task) => {
                  try {
                      return formatTask(task);
                  } catch (e) {
                      return null;
                  }
              }).filter(Boolean);
      })();
      """)
      )
  
      return evaluate_javascript(
          script.substitute(
              __common_functions__=__common_functions__,
              project_id=project_id,
              task_status=f"[{', '.join([f'"{status}"' for status in task_status])}]" if task_status else "null",
          )
      )

• src/mcp_omnifocus/utils/omnifocus.py:7-7 (schema)

  Pydantic/Literal type definition for valid task statuses used in the tool's input parameter.

  TaskStatus = Literal["Available", "Blocked", "Completed", "Dropped", "DueSoon", "Next", "Overdue"]