list_subtasks
Break down complex projects into actionable subtasks with detailed visibility and flexible filtering. Ideal for sprint planning, daily standups, and tracking progress across project hierarchies.
Instructions
Navigate your detailed work breakdown with granular subtask visibility and flexible filtering options. Perfect for sprint planning, daily standups, and detailed progress tracking across the complete project hierarchy from high-level goals to specific implementation steps.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | No | Filter subtasks to only those in this project (optional) | |
| taskId | No | Filter subtasks to only those belonging to this task (optional) | |
| workingDirectory | Yes | The full absolute path to the working directory where data is stored. MUST be an absolute path, never relative. Windows: "C:\Users\username\project" or "D:\projects\my-app". Unix/Linux/macOS: "/home/username/project" or "/Users/username/project". Do NOT use: ".", "..", "~", "./folder", "../folder" or any relative paths. Ensure the path exists and is accessible before calling this tool. NOTE: When server is started with --claude flag, this parameter is ignored and a global user directory is used instead. |
Implementation Reference
- Main execution logic for the list_subtasks tool. Validates inputs, fetches subtasks from storage, formats them hierarchically with status indicators, counts completed ones, and returns formatted text output or errors.handler: async ({ taskId, projectId }: { taskId?: string; projectId?: string }) => { try { // Validate task exists if taskId is provided if (taskId) { const task = await storage.getTask(taskId); if (!task) { return { content: [{ type: 'text' as const, text: `Error: Task with ID "${taskId}" not found. Use list_tasks to see all available tasks.` }], isError: true }; } } // Validate project exists if projectId is provided if (projectId) { const project = await storage.getProject(projectId); if (!project) { return { content: [{ type: 'text' as const, text: `Error: Project with ID "${projectId}" not found. Use list_projects to see all available projects.` }], isError: true }; } } const subtasks = await storage.getSubtasks(taskId, projectId); if (subtasks.length === 0) { let message = 'No subtasks found.'; if (taskId) { message = `No subtasks found for the specified task. Create your first subtask using create_subtask.`; } else if (projectId) { message = `No subtasks found in the specified project. Create your first subtask using create_subtask.`; } else { message = `No subtasks found. Create your first subtask using create_subtask.`; } return { content: [{ type: 'text' as const, text: message }] }; } // Get additional context for display const tasks = await storage.getTasks(); const projects = await storage.getProjects(); const taskMap = new Map(tasks.map(t => [t.id, t.name])); const projectMap = new Map(projects.map(p => [p.id, p.name])); let subtaskList: string; if (taskId) { // Show subtasks for a specific task subtaskList = subtasks.map(subtask => { const status = subtask.completed ? '✅' : '⏳'; return `${status} **${subtask.name}** (ID: ${subtask.id}) Details: ${subtask.details} Status: ${subtask.completed ? 'Completed' : 'Pending'} Created: ${new Date(subtask.createdAt).toLocaleString()} Updated: ${new Date(subtask.updatedAt).toLocaleString()}`; }).join('\n\n'); } else { // Group by task when showing multiple tasks' subtasks const subtasksByTask = subtasks.reduce((acc, subtask) => { const taskName = taskMap.get(subtask.taskId) || 'Unknown Task'; const projectName = projectMap.get(subtask.projectId) || 'Unknown Project'; const key = `${projectName} > ${taskName}`; if (!acc[key]) acc[key] = []; acc[key].push(subtask); return acc; }, {} as Record<string, typeof subtasks>); subtaskList = Object.entries(subtasksByTask).map(([taskPath, taskSubtasks]) => { const subtaskItems = taskSubtasks.map(subtask => { const status = subtask.completed ? '✅' : '⏳'; return ` ${status} **${subtask.name}** (ID: ${subtask.id}) - ${subtask.details}`; }).join('\n'); return `**${taskPath}**\n${subtaskItems}`; }).join('\n\n'); } const completedCount = subtasks.filter(s => s.completed).length; let headerText = `Found ${subtasks.length} subtask(s) (${completedCount} completed):`; if (taskId) { const task = await storage.getTask(taskId); const taskName = task ? task.name : 'Unknown Task'; headerText = `Found ${subtasks.length} subtask(s) in task "${taskName}" (${completedCount} completed):`; } else if (projectId) { const project = await storage.getProject(projectId); const projectName = project ? project.name : 'Unknown Project'; headerText = `Found ${subtasks.length} subtask(s) in project "${projectName}" (${completedCount} completed):`; } return { content: [{ type: 'text' as const, text: `${headerText}\n\n${subtaskList}` }] }; } catch (error) { return { content: [{ type: 'text' as const, text: `Error listing subtasks: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } }
- Zod-based input schema defining optional taskId and projectId parameters for filtering subtasks.inputSchema: { taskId: z.string().optional(), projectId: z.string().optional() },
- src/features/task-management/tools/subtasks/list.ts:11-135 (registration)Tool registration object defining name, description, schema, and handler for the list_subtasks MCP tool, returned by createListSubtasksTool.return { name: 'list_subtasks', description: 'View subtasks, optionally filtered by task ID or project ID', inputSchema: { taskId: z.string().optional(), projectId: z.string().optional() }, handler: async ({ taskId, projectId }: { taskId?: string; projectId?: string }) => { try { // Validate task exists if taskId is provided if (taskId) { const task = await storage.getTask(taskId); if (!task) { return { content: [{ type: 'text' as const, text: `Error: Task with ID "${taskId}" not found. Use list_tasks to see all available tasks.` }], isError: true }; } } // Validate project exists if projectId is provided if (projectId) { const project = await storage.getProject(projectId); if (!project) { return { content: [{ type: 'text' as const, text: `Error: Project with ID "${projectId}" not found. Use list_projects to see all available projects.` }], isError: true }; } } const subtasks = await storage.getSubtasks(taskId, projectId); if (subtasks.length === 0) { let message = 'No subtasks found.'; if (taskId) { message = `No subtasks found for the specified task. Create your first subtask using create_subtask.`; } else if (projectId) { message = `No subtasks found in the specified project. Create your first subtask using create_subtask.`; } else { message = `No subtasks found. Create your first subtask using create_subtask.`; } return { content: [{ type: 'text' as const, text: message }] }; } // Get additional context for display const tasks = await storage.getTasks(); const projects = await storage.getProjects(); const taskMap = new Map(tasks.map(t => [t.id, t.name])); const projectMap = new Map(projects.map(p => [p.id, p.name])); let subtaskList: string; if (taskId) { // Show subtasks for a specific task subtaskList = subtasks.map(subtask => { const status = subtask.completed ? '✅' : '⏳'; return `${status} **${subtask.name}** (ID: ${subtask.id}) Details: ${subtask.details} Status: ${subtask.completed ? 'Completed' : 'Pending'} Created: ${new Date(subtask.createdAt).toLocaleString()} Updated: ${new Date(subtask.updatedAt).toLocaleString()}`; }).join('\n\n'); } else { // Group by task when showing multiple tasks' subtasks const subtasksByTask = subtasks.reduce((acc, subtask) => { const taskName = taskMap.get(subtask.taskId) || 'Unknown Task'; const projectName = projectMap.get(subtask.projectId) || 'Unknown Project'; const key = `${projectName} > ${taskName}`; if (!acc[key]) acc[key] = []; acc[key].push(subtask); return acc; }, {} as Record<string, typeof subtasks>); subtaskList = Object.entries(subtasksByTask).map(([taskPath, taskSubtasks]) => { const subtaskItems = taskSubtasks.map(subtask => { const status = subtask.completed ? '✅' : '⏳'; return ` ${status} **${subtask.name}** (ID: ${subtask.id}) - ${subtask.details}`; }).join('\n'); return `**${taskPath}**\n${subtaskItems}`; }).join('\n\n'); } const completedCount = subtasks.filter(s => s.completed).length; let headerText = `Found ${subtasks.length} subtask(s) (${completedCount} completed):`; if (taskId) { const task = await storage.getTask(taskId); const taskName = task ? task.name : 'Unknown Task'; headerText = `Found ${subtasks.length} subtask(s) in task "${taskName}" (${completedCount} completed):`; } else if (projectId) { const project = await storage.getProject(projectId); const projectName = project ? project.name : 'Unknown Project'; headerText = `Found ${subtasks.length} subtask(s) in project "${projectName}" (${completedCount} completed):`; } return { content: [{ type: 'text' as const, text: `${headerText}\n\n${subtaskList}` }] }; } catch (error) { return { content: [{ type: 'text' as const, text: `Error listing subtasks: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } } };