create_task
Break down complex projects into structured, actionable tasks with dependencies, priorities, and complexity estimates. Manage workflows with unlimited hierarchy depth for efficient project execution.
Instructions
Transform project goals into actionable, trackable tasks with advanced features including dependencies, priorities, complexity estimation, and workflow management. Build structured workflows that break down complex projects into manageable components with unlimited hierarchy depth.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| complexity | No | Estimated complexity/effort (1-10, where 10 is most complex) | |
| dependsOn | No | Array of task IDs that must be completed before this task | |
| details | Yes | Detailed description of what the task involves | |
| estimatedHours | No | Estimated time to complete in hours | |
| name | Yes | The name/title of the new task | |
| parentId | No | Parent task ID for unlimited nesting (optional - creates top-level task if not specified) | |
| priority | No | Task priority level (1-10, where 10 is highest priority) | |
| projectId | Yes | The ID of the project this task belongs to | |
| status | No | Initial task status (defaults to pending) | |
| tags | No | Tags for categorization and filtering | |
| 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
- Executes the core logic of the create_task tool: validates all inputs (name, details, projectId, parentId, etc.), verifies project and parent task existence, checks for duplicate names in scope, validates dependencies, constructs Task object, calls storage.createTask(), and returns rich formatted response with hierarchy path, details, and next steps.handler: async ({ name, details, projectId, parentId, dependsOn, priority, complexity, status, tags, estimatedHours }: { name: string; details: string; projectId: string; parentId?: string; dependsOn?: string[]; priority?: number; complexity?: number; status?: 'pending' | 'in-progress' | 'blocked' | 'done'; tags?: string[]; estimatedHours?: number; }) => { try { // Validate inputs if (!name || name.trim().length === 0) { return { content: [{ type: 'text' as const, text: 'Error: Task name is required.' }], isError: true }; } if (name.trim().length > 100) { return { content: [{ type: 'text' as const, text: 'Error: Task name must be 100 characters or less.' }], isError: true }; } if (!details || details.trim().length === 0) { return { content: [{ type: 'text' as const, text: 'Error: Task details are required.' }], isError: true }; } if (details.trim().length > 2000) { return { content: [{ type: 'text' as const, text: 'Error: Task details must be 2000 characters or less.' }], isError: true }; } if (!projectId || projectId.trim().length === 0) { return { content: [{ type: 'text' as const, text: 'Error: Project ID is required.' }], isError: true }; } // Validate that project exists const project = await storage.getProject(projectId.trim()); 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 }; } let parentTask = null; let taskLevel = 0; // Validate parent task exists if parentId is provided if (parentId) { parentTask = await storage.getTask(parentId.trim()); if (!parentTask) { return { content: [{ type: 'text' as const, text: `Error: Parent task with ID "${parentId}" not found. Use list_tasks to see available tasks.` }], isError: true }; } // Ensure parent belongs to the same project if (parentTask.projectId !== projectId) { return { content: [{ type: 'text' as const, text: `Error: Parent task belongs to a different project. Tasks can only be nested within the same project.` }], isError: true }; } taskLevel = (parentTask.level || 0) + 1; } // Check for duplicate task names within the same parent scope const siblingTasks = await storage.getTasks(projectId, parentId); const nameExists = siblingTasks.some(t => t.name.toLowerCase() === name.toLowerCase()); if (nameExists) { const scopeDescription = parentTask ? `under parent task "${parentTask.name}"` : `at the top level of project "${project.name}"`; return { content: [{ type: 'text' as const, text: `Error: A task with the name "${name}" already exists ${scopeDescription}. Please choose a different name.` }], isError: true }; } // Validate dependencies exist if provided if (dependsOn && dependsOn.length > 0) { for (const depId of dependsOn) { const depTask = await storage.getTask(depId); if (!depTask) { return { content: [{ type: 'text' as const, text: `Error: Dependency task with ID "${depId}" not found.` }], isError: true }; } } } const now = new Date().toISOString(); const task: Task = { id: randomUUID(), name: name.trim(), details: details.trim(), projectId, parentId: parentId?.trim() || undefined, completed: false, createdAt: now, updatedAt: now, dependsOn: dependsOn || [], priority: priority || 5, complexity: complexity, status: status || 'pending', tags: tags || [], estimatedHours: estimatedHours, level: taskLevel }; const createdTask = await storage.createTask(task); const hierarchyPath = parentTask ? `${project.name} → ${parentTask.name} → ${createdTask.name}` : `${project.name} → ${createdTask.name}`; const levelIndicator = ' '.repeat(taskLevel) + '→'; return { content: [{ type: 'text' as const, text: `✅ Task created successfully! **${levelIndicator} ${createdTask.name}** (ID: ${createdTask.id}) ${parentTask ? `Parent: ${parentTask.name} (${parentTask.id})` : 'Top-level task'} Project: ${project.name} Level: ${taskLevel} ${taskLevel === 0 ? '(Top-level)' : `(${taskLevel} level${taskLevel > 1 ? 's' : ''} deep)`} Path: ${hierarchyPath} 📋 **Task Details:** • Details: ${createdTask.details} • Priority: ${createdTask.priority}/10 • Complexity: ${createdTask.complexity || 'Not set'}/10 • Status: ${createdTask.status} • Tags: ${createdTask.tags?.join(', ') || 'None'} • Dependencies: ${createdTask.dependsOn?.length ? createdTask.dependsOn.join(', ') : 'None'} • Estimated Hours: ${createdTask.estimatedHours || 'Not set'} • Created: ${new Date(createdTask.createdAt).toLocaleString()} 🎯 **Next Steps:** ${taskLevel === 0 ? '• Break down into smaller tasks using create_task with parentId for complex work' : '• Add even more granular tasks if needed using create_task with this task as parentId' } • Use \`get_next_task_recommendation\` to see if this task is ready to work on • Update progress using \`update_task\` as you work • Use \`list_tasks\` with projectId and parentId to see the task hierarchy` }] }; } catch (error) { return { content: [{ type: 'text' as const, text: `Error creating task: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } }
- Zod-based input schema defining parameters for create_task tool with validation rules for all fields.inputSchema: { name: z.string(), details: z.string(), projectId: z.string(), parentId: z.string().optional(), dependsOn: z.array(z.string()).optional(), priority: z.number().min(1).max(10).optional(), complexity: z.number().min(1).max(10).optional(), status: z.enum(['pending', 'in-progress', 'blocked', 'done']).optional(), tags: z.array(z.string()).optional(), estimatedHours: z.number().min(0).optional() },
- src/features/task-management/tools/tasks/index.ts:235-245 (registration)Registers the create_task tool by including createCreateTaskTool(storage) in the createTaskTools export, which aggregates all task-related MCP tools.export function createTaskTools(storage: Storage) { return { create_task: createCreateTaskTool(storage), delete_task: createDeleteTaskTool(storage), get_task: createGetTaskTool(storage), list_tasks: createListTasksTool(storage), update_task: createUpdateTaskTool(storage), migrate_subtasks: createMigrateSubtasksTool(storage), move_task: createMoveTaskTool(storage) }; }
- src/features/task-management/tools/tasks/index.ts:237-237 (registration)Specific registration line mapping 'create_task' key to the tool creator function.create_task: createCreateTaskTool(storage),
- Calls the underlying storage layer to persist the new task.const createdTask = await storage.createTask(task); const hierarchyPath = parentTask ? `${project.name} → ${parentTask.name} → ${createdTask.name}` : `${project.name} → ${createdTask.name}`;