list_tasks_by_tag
Filter and retrieve OmniFocus tasks by a specific tag ID using MCP OmniFocus. Optionally filter by task status to manage tasks efficiently.
Instructions
List all tasks with a specific tag.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | The ID of the tag to list tasks for | |
| task_status | No | The status of the tasks to list. If None, it is the equivelant of requesting available and unblocked tasks ['Available', 'Next', 'Overdue', 'DueSoon']. |
Implementation Reference
- src/mcp_omnifocus/server.py:146-161 (handler)MCP tool handler and registration for 'list_tasks_by_tag'. Defines input schema via Annotated Fields and delegates execution to the omnifocus utility.
@mcp.tool def list_tasks_by_tag( tag_id: Annotated[str, Field(description="The ID of the tag 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 with a specific tag.""" if task_status is None: task_status = ["Available", "Next", "Overdue", "DueSoon"] return omnifocus.list_tasks_by_tag(tag_id, task_status=task_status) - Core helper function that generates and evaluates JavaScript to retrieve tasks associated with a specific tag from OmniFocus, applying status filters.
def list_tasks_by_tag(tag_id: str, task_status: list[TaskStatus] | None = None) -> list[dict[str, str]]: """List all tasks with a specific tag in OmniFocus. Args: tag_id: The ID of the tag 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 tag = Tag.byIdentifier("${tag_id}"); const allowedStatuses = ${task_status}; if (!tag) { throw "Could not find tag: " + tag_id.toString(); } return tag.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__, tag_id=tag_id, task_status=f"[{', '.join([f'"{status}"' for status in task_status])}]" if task_status else "null", ) ) - Type alias defining valid TaskStatus values used in the tool's input schema for filtering tasks.
TaskStatus = Literal["Available", "Blocked", "Completed", "Dropped", "DueSoon", "Next", "Overdue"]