MCP Task Manager Server

Instructions

Implementation Reference

• src/tools/expandTaskTool.ts:16-52 (handler)

  The main handler function for the 'expandTask' MCP tool. It processes the input arguments, calls TaskService.expandTask, formats the response as MCP content (JSON of updated task), and handles errors by throwing appropriate McpError types.
  const processRequest = async (args: ExpandTaskArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to expand the task const updatedParentTask = await taskService.expandTask({ project_id: args.project_id, task_id: args.task_id, subtask_descriptions: args.subtask_descriptions, force: args.force, }); // Format the successful response logger.info(`[${TOOL_NAME}] Successfully expanded task ${args.task_id} in project ${args.project_id}`); return { content: [{ type: "text" as const, // Return the updated parent task details, including new subtasks text: JSON.stringify(updatedParentTask) }] }; } catch (error: unknown) { // Handle potential errors logger.error(`[${TOOL_NAME}] Error processing request:`, error); if (error instanceof NotFoundError) { // Project or parent task not found throw new McpError(ErrorCode.InvalidParams, error.message); } else if (error instanceof ConflictError) { // Subtasks exist and force=false - map to InvalidParams as the request is invalid without force=true throw new McpError(ErrorCode.InvalidParams, error.message); } else { // Generic internal error const message = error instanceof Error ? error.message : 'An unknown error occurred while expanding the task.'; throw new McpError(ErrorCode.InternalError, message); } } };
• src/tools/expandTaskParams.ts:13-37 (schema)

  Zod schema definition for the 'expandTask' tool parameters (TOOL_PARAMS), including validation, descriptions, and types for project_id, task_id, subtask_descriptions, and force.
  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 containing the parent task."), // Required, UUID format task_id: z.string() // Add .uuid() if task IDs are also UUIDs .min(1, "Parent task ID cannot be empty.") .describe("The unique identifier of the parent task to be expanded."), // Required, string (or UUID) subtask_descriptions: z.array( z.string() .min(1, "Subtask description cannot be empty.") .max(512, "Subtask description cannot exceed 512 characters.") .describe("A textual description for one of the new subtasks (1-512 characters).") ) .min(1, "At least one subtask description must be provided.") .max(20, "Cannot create more than 20 subtasks per call.") .describe("An array of descriptions (1-20) for the new subtasks to be created under the parent task."), // Required, array of strings, limits force: z.boolean() .optional() .default(false) .describe("Optional flag (default false). If true, any existing subtasks of the parent task will be deleted before creating the new ones. If false and subtasks exist, the operation will fail."), // Optional, boolean, default });
• src/tools/expandTaskTool.ts:14-58 (registration)

  The expandTaskTool function that registers the 'expandTask' tool on the MCP server using server.tool(), providing name, description, params schema, and the processRequest handler.
  export const expandTaskTool = (server: McpServer, taskService: TaskService): void => { const processRequest = async (args: ExpandTaskArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to expand the task const updatedParentTask = await taskService.expandTask({ project_id: args.project_id, task_id: args.task_id, subtask_descriptions: args.subtask_descriptions, force: args.force, }); // Format the successful response logger.info(`[${TOOL_NAME}] Successfully expanded task ${args.task_id} in project ${args.project_id}`); return { content: [{ type: "text" as const, // Return the updated parent task details, including new subtasks text: JSON.stringify(updatedParentTask) }] }; } catch (error: unknown) { // Handle potential errors logger.error(`[${TOOL_NAME}] Error processing request:`, error); if (error instanceof NotFoundError) { // Project or parent task not found throw new McpError(ErrorCode.InvalidParams, error.message); } else if (error instanceof ConflictError) { // Subtasks exist and force=false - map to InvalidParams as the request is invalid without force=true throw new McpError(ErrorCode.InvalidParams, error.message); } else { // Generic internal error const message = error instanceof Error ? error.message : 'An unknown error occurred while expanding the task.'; throw new McpError(ErrorCode.InternalError, message); } } }; // Register the tool with the server server.tool(TOOL_NAME, TOOL_DESCRIPTION, TOOL_PARAMS.shape, processRequest); logger.info(`[${TOOL_NAME}] Tool registered successfully.`); };
• src/tools/index.ts:58-58 (registration)

  Invocation of expandTaskTool during overall tool registration in the central registerTools function, passing the MCP server and TaskService instance.
  expandTaskTool(server, taskService);
• src/services/TaskService.ts:207-283 (helper)

  Core business logic for expanding a task: validates inputs, uses DB transaction to optionally delete existing subtasks (if force=true), creates new subtasks with given descriptions, constructs and returns FullTaskData with dependencies and subtasks.
  public async expandTask(input: ExpandTaskInput): Promise<FullTaskData> { const { project_id, task_id: parentTaskId, subtask_descriptions, force = false } = input; logger.info(`[TaskService] Attempting to expand task ${parentTaskId} in project ${project_id} with ${subtask_descriptions.length} subtasks (force=${force})`); // Use a transaction for the entire operation const expandTransaction = this.db.transaction(() => { // 1. Validate Parent Task Existence (within the transaction) const parentTask = this.taskRepository.findById(project_id, parentTaskId); if (!parentTask) { logger.warn(`[TaskService] Parent task ${parentTaskId} not found in project ${project_id}`); throw new NotFoundError(`Parent task with ID ${parentTaskId} not found in project ${project_id}.`); } // 2. Check for existing subtasks const existingSubtasks = this.taskRepository.findSubtasks(parentTaskId); // 3. Handle existing subtasks based on 'force' flag if (existingSubtasks.length > 0) { if (!force) { logger.warn(`[TaskService] Conflict: Task ${parentTaskId} already has subtasks and force=false.`); throw new ConflictError(`Task ${parentTaskId} already has subtasks. Use force=true to replace them.`); } else { logger.info(`[TaskService] Force=true: Deleting ${existingSubtasks.length} existing subtasks for parent ${parentTaskId}.`); this.taskRepository.deleteSubtasks(parentTaskId); // Note: Dependencies of deleted subtasks are implicitly handled by ON DELETE CASCADE in schema } } // 4. Create new subtasks const now = new Date().toISOString(); const createdSubtasks: TaskData[] = []; for (const description of subtask_descriptions) { const subtaskId = uuidv4(); const newSubtaskData: TaskData = { task_id: subtaskId, project_id: project_id, parent_task_id: parentTaskId, description: description, // Assuming length validation done by Zod status: 'todo', // Default status priority: 'medium', // Default priority created_at: now, updated_at: now, }; // Use the repository's create method (which handles its own transaction part for task+deps, but is fine here) // We pass an empty array for dependencies as expandTask doesn't set them for new subtasks this.taskRepository.create(newSubtaskData, []); createdSubtasks.push(newSubtaskData); } // 5. Fetch updated parent task details (including new subtasks and existing dependencies) // We re-fetch to get the consistent state after the transaction commits. // Note: This requires the transaction function to return the necessary data. // Alternatively, construct the FullTaskData manually here. Let's construct manually. const dependencies = this.taskRepository.findDependencies(parentTaskId); // Fetch parent's dependencies const finalParentData: FullTaskData = { ...parentTask, // Use data fetched at the start of transaction updated_at: now, // Update timestamp conceptually (though not saved unless status changes) dependencies: dependencies, subtasks: createdSubtasks, // Return the newly created subtasks }; return finalParentData; }); try { // Execute the transaction const result = expandTransaction(); logger.info(`[TaskService] Successfully expanded task ${parentTaskId} with ${subtask_descriptions.length} new subtasks.`); return result; } catch (error) { logger.error(`[TaskService] Error expanding task ${parentTaskId}:`, error); // Re-throw specific errors or generic internal error if (error instanceof NotFoundError || error instanceof ConflictError) { throw error; } throw new Error(`Failed to expand task: ${error instanceof Error ? error.message : 'Unknown error'}`); } }