list_tasks
Retrieve and filter tasks by project ID or state (open, pending_approval, completed, all) for structured task management. Includes recommendations to guide task completion.
Instructions
List all tasks, optionally filtered by project ID and/or state (open, pending_approval, completed, all). Tasks may include tool and rule recommendations to guide their completion.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | No | The ID of the project to list tasks from. If omitted, list all tasks. | |
| state | No | Filter tasks by state. 'open' (not started/in progress), 'pending_approval', 'completed', or 'all' to skip filtering. |
Implementation Reference
- src/server/toolExecutors.ts:393-412 (handler)The ToolExecutor for 'list_tasks': validates optional projectId and state args, delegates to TaskManager.listTasks(), and registers in toolExecutorMap.
const listTasksToolExecutor: ToolExecutor = { name: "list_tasks", async execute(taskManager, args) { // 1. Argument Validation const projectId = args.projectId !== undefined ? validateProjectId(args.projectId) : undefined; const state = validateOptionalStateParam(args.state, [ "open", "pending_approval", "completed", "all", ]); // 2. Core Logic Execution const resultData = await taskManager.listTasks(projectId, state as any); // 3. Return raw success data return resultData; }, }; toolExecutorMap.set(listTasksToolExecutor.name, listTasksToolExecutor); - src/server/tools.ts:234-252 (schema)MCP Tool definition for 'list_tasks' including input schema (optional projectId, state with enum).
const listTasksTool: Tool = { name: "list_tasks", description: "List all tasks, optionally filtered by project ID and/or state (open, pending_approval, completed, all). Tasks may include tool and rule recommendations to guide their completion.", inputSchema: { type: "object", properties: { projectId: { type: "string", description: "The ID of the project to list tasks from. If omitted, list all tasks.", }, state: { type: "string", enum: ["open", "pending_approval", "completed", "all"], description: "Filter tasks by state. 'open' (not started/in progress), 'pending_approval', 'completed', or 'all' to skip filtering.", }, }, required: [], // Neither projectId nor state is required, both are optional filters }, }; - src/server/index.ts:29-33 (registration)Registers all tools (including 'list_tasks' via ALL_TOOLS) for MCP listTools request.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: ALL_TOOLS }; }); - src/server/TaskManager.ts:425-465 (helper)Core implementation in TaskManager that retrieves, filters (by project/state), and returns list of tasks.
public async listTasks(projectId?: string, state?: TaskState): Promise<ListTasksSuccessData> { await this.ensureInitialized(); await this.reloadFromDisk(); if (state && !["all", "open", "completed", "pending_approval"].includes(state)) { throw new AppError(`Invalid state filter: ${state}`, AppErrorCode.InvalidState); } let allTasks: Task[] = []; if (projectId) { const proj = this.data.projects.find((p) => p.projectId === projectId); if (!proj) { throw new AppError(`Project ${projectId} not found`, AppErrorCode.ProjectNotFound); } allTasks = [...proj.tasks]; } else { // Collect tasks from all projects allTasks = this.data.projects.flatMap((p) => p.tasks); } if (state && state !== "all") { allTasks = allTasks.filter((task) => { switch (state) { case "open": return !task.approved; case "completed": return task.status === "done" && task.approved; case "pending_approval": return task.status === "done" && !task.approved; default: return true; } }); } return { message: `Tasks in the system${projectId ? ` for project ${projectId}` : ""}:\n${allTasks.length} tasks found.`, tasks: allTasks, }; } - src/types/response.ts:45-48 (schema)Type definition for the output data structure of list_tasks.
export interface ListTasksSuccessData { message: string; tasks: Task[]; // Use the full Task type }