addTask
Creates a new task within a specified project by submitting a description, project ID, and optional details like dependencies, priority, and status. Returns the full task details.
Instructions
Adds a new task to a specified project within the Task Management Server. Requires the project ID and a description for the task. Optionally accepts a list of dependency task IDs, a priority level, and an initial status. Returns the full details of the newly created task upon success.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dependencies | No | An optional list of task IDs (strings) that must be completed before this task can start (max 50). | |
| description | Yes | The textual description of the task to be performed (1-1024 characters). | |
| priority | No | Optional task priority. Defaults to 'medium' if not specified. | medium |
| project_id | Yes | The unique identifier (UUID) of the project to add the task to. This project must already exist. | |
| status | No | Optional initial status of the task. Defaults to 'todo' if not specified. | todo |
Implementation Reference
- src/tools/addTaskTool.ts:17-55 (handler)The main execution handler for the addTask tool. It processes the input arguments, calls the TaskService to add the task, returns the created task as JSON, and handles errors appropriately by throwing MCP-standard errors.const processRequest = async (args: AddTaskArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to add the task // The Zod schema handles basic type/format/length validation const newTask = await taskService.addTask({ project_id: args.project_id, description: args.description, dependencies: args.dependencies, // Pass optional fields priority: args.priority, status: args.status, }); // Format the successful response according to MCP standards // Return the full details of the created task as per spec FR-FS-011 logger.info(`[${TOOL_NAME}] Task added successfully: ${newTask.task_id}`); return { content: [{ type: "text" as const, text: JSON.stringify(newTask) // Return the full task object }] }; } catch (error: unknown) { // Handle potential errors from the service layer logger.error(`[${TOOL_NAME}] Error processing request:`, error); if (error instanceof NotFoundError) { // Specific error if the project wasn't found - map to InvalidParams as project_id is invalid throw new McpError(ErrorCode.InvalidParams, error.message); } else if (error instanceof ValidationError) { // Specific error for validation issues within the service (e.g., dependency check if implemented) throw new McpError(ErrorCode.InvalidParams, error.message); } else { // Generic internal error for database issues or unexpected problems const message = error instanceof Error ? error.message : 'An unknown error occurred while adding the task.'; throw new McpError(ErrorCode.InternalError, message); } } };
- src/tools/addTaskParams.ts:17-41 (schema)Zod schema (TOOL_PARAMS) defining the input parameters for the addTask tool, including validation rules, descriptions, defaults, and enums for priority and status.export const TOOL_PARAMS = z.object({ project_id: z.string() .uuid("The project_id must be a valid UUID.") .describe("The unique identifier (UUID) of the project to add the task to. This project must already exist."), // Required, UUID format description: z.string() .min(1, "Task description cannot be empty.") .max(1024, "Task description cannot exceed 1024 characters.") .describe("The textual description of the task to be performed (1-1024 characters)."), // Required, length limits dependencies: z.array(z.string().describe("A task ID that this new task depends on.")) // Allow any string for now, existence checked in service (or deferred) .max(50, "A task cannot have more than 50 dependencies.") .optional() .describe("An optional list of task IDs (strings) that must be completed before this task can start (max 50)."), // Optional, array of strings, count limit priority: TaskPriorityEnum .optional() .default('medium') // Default value .describe("Optional task priority. Defaults to 'medium' if not specified."), // Optional, enum, default status: TaskStatusEnum .optional() .default('todo') // Default value .describe("Optional initial status of the task. Defaults to 'todo' if not specified."), // Optional, enum, default });
- src/tools/addTaskTool.ts:14-61 (registration)The addTaskTool function that registers the tool with the MCP server using server.tool(), providing name, description, schema shape, and handler. This function is invoked from tools/index.ts.export const addTaskTool = (server: McpServer, taskService: TaskService): void => { // Define the asynchronous function that handles the actual tool logic const processRequest = async (args: AddTaskArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to add the task // The Zod schema handles basic type/format/length validation const newTask = await taskService.addTask({ project_id: args.project_id, description: args.description, dependencies: args.dependencies, // Pass optional fields priority: args.priority, status: args.status, }); // Format the successful response according to MCP standards // Return the full details of the created task as per spec FR-FS-011 logger.info(`[${TOOL_NAME}] Task added successfully: ${newTask.task_id}`); return { content: [{ type: "text" as const, text: JSON.stringify(newTask) // Return the full task object }] }; } catch (error: unknown) { // Handle potential errors from the service layer logger.error(`[${TOOL_NAME}] Error processing request:`, error); if (error instanceof NotFoundError) { // Specific error if the project wasn't found - map to InvalidParams as project_id is invalid throw new McpError(ErrorCode.InvalidParams, error.message); } else if (error instanceof ValidationError) { // Specific error for validation issues within the service (e.g., dependency check if implemented) throw new McpError(ErrorCode.InvalidParams, error.message); } else { // Generic internal error for database issues or unexpected problems const message = error instanceof Error ? error.message : 'An unknown error occurred while adding the task.'; throw new McpError(ErrorCode.InternalError, message); } } }; // Register the tool with the server, passing the shape of the Zod object server.tool(TOOL_NAME, TOOL_DESCRIPTION, TOOL_PARAMS.shape, processRequest); logger.info(`[${TOOL_NAME}] Tool registered successfully.`); };
- src/services/TaskService.ts:64-95 (helper)TaskService.addTask helper method that validates the project exists, generates task ID and timestamps, prepares task data, and delegates persistence to the TaskRepository.public async addTask(input: AddTaskInput): Promise<TaskData> { logger.info(`[TaskService] Attempting to add task to project: ${input.project_id}`); const projectExists = this.projectRepository.findById(input.project_id); if (!projectExists) { logger.warn(`[TaskService] Project not found: ${input.project_id}`); throw new NotFoundError(`Project with ID ${input.project_id} not found.`); } const taskId = uuidv4(); const now = new Date().toISOString(); const newTaskData: TaskData = { task_id: taskId, project_id: input.project_id, parent_task_id: null, description: input.description, status: input.status ?? 'todo', priority: input.priority ?? 'medium', created_at: now, updated_at: now, }; // TODO: Validate Dependency Existence try { this.taskRepository.create(newTaskData, input.dependencies); logger.info(`[TaskService] Successfully added task ${taskId} to project ${input.project_id}`); return newTaskData; } catch (error) { logger.error(`[TaskService] Error adding task to project ${input.project_id}:`, error); throw error; } }
- src/tools/index.ts:54-54 (registration)Invocation of addTaskTool during overall tools registration in the central index file, passing the server and taskService instance.addTaskTool(server, taskService);