list_tasks
Retrieve tasks from the task-mcp server with filtering options for status, project, tags, or priority. View claim metadata including owner agent and lease details for each task.
Instructions
List tasks, optionally filtered by status, project, tags, or priority. Returns claim metadata (owner_agent, lease_until, claimed_at, last_renewed_at) for each task.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by status (default: pending) | |
| project | No | Filter by project name | |
| tags | Yes | Tags to add | |
| priority | No | Priority: H, M, or L | |
| due_before | No | Date in any format Taskwarrior accepts (e.g. 2024-12-25, tomorrow, eow) | |
| due_after | No | Date in any format Taskwarrior accepts (e.g. 2024-12-25, tomorrow, eow) |
Implementation Reference
- src/index.ts:62-76 (handler)The handler logic for the 'list_tasks' MCP tool in src/index.ts.
async (params) => { try { const tasks = await exportTasks({ status: params.status as TaskStatus | 'all' | undefined, project: params.project, tags: params.tags, priority: params.priority as Priority | undefined, dueBefore: params.due_before, dueAfter: params.due_after, }); return { content: [{ type: 'text', text: JSON.stringify(tasks, null, 2) }] }; } catch (err) { return { content: [{ type: 'text', text: (err as Error).message }], isError: true }; } }, - src/taskwarrior.ts:95-103 (helper)The implementation of exportTasks which performs the task listing by calling the taskwarrior CLI.
export async function exportTasks(filter: FilterParams = {}): Promise<Task[]> { try { const filterArgs = buildFilterArgs(filter); const output = await runCommand('task', [...filterArgs, 'export']); return JSON.parse(output) as Task[]; } catch (err) { throw new Error(`Failed to export tasks: ${(err as Error).message}`); } } - src/index.ts:48-77 (registration)Registration of the 'list_tasks' tool.
server.tool( 'list_tasks', 'List tasks, optionally filtered by status, project, tags, or priority. Returns claim metadata (owner_agent, lease_until, claimed_at, last_renewed_at) for each task.', { status: z .enum(['pending', 'completed', 'deleted', 'waiting', 'recurring', 'all']) .optional() .describe('Filter by status (default: pending)'), project: z.string().optional().describe('Filter by project name'), tags: tagsParam, priority: priorityParam, due_before: dateParam, due_after: dateParam, }, async (params) => { try { const tasks = await exportTasks({ status: params.status as TaskStatus | 'all' | undefined, project: params.project, tags: params.tags, priority: params.priority as Priority | undefined, dueBefore: params.due_before, dueAfter: params.due_after, }); return { content: [{ type: 'text', text: JSON.stringify(tasks, null, 2) }] }; } catch (err) { return { content: [{ type: 'text', text: (err as Error).message }], isError: true }; } }, );