MCP Task Manager Server

Instructions

Implementation Reference

• src/tools/getNextTaskTool.ts:16-49 (handler)

  The handler function 'processRequest' that executes the core logic of the 'getNextTask' tool: validates input, calls TaskService.getNextTask(project_id), handles errors, and returns the task as JSON string or null.
  const processRequest = async (args: GetNextTaskArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to get the next task const nextTask = await taskService.getNextTask(args.project_id); // Format the successful response if (nextTask) { logger.info(`[${TOOL_NAME}] Next task found: ${nextTask.task_id} in project ${args.project_id}`); } else { logger.info(`[${TOOL_NAME}] No ready task found for project ${args.project_id}`); } return { content: [{ type: "text" as const, // Return the full task object or null text: JSON.stringify(nextTask) }] }; } catch (error: unknown) { // Handle potential errors logger.error(`[${TOOL_NAME}] Error processing request:`, error); if (error instanceof NotFoundError) { // Project not found throw new McpError(ErrorCode.InvalidParams, error.message); } else { // Generic internal error const message = error instanceof Error ? error.message : 'An unknown error occurred while getting the next task.'; throw new McpError(ErrorCode.InternalError, message); } } };
• src/tools/getNextTaskParams.ts:3-21 (schema)

  Schema definitions: TOOL_NAME, TOOL_DESCRIPTION, TOOL_PARAMS (Zod schema for project_id: UUID), and GetNextTaskArgs type.
  export const TOOL_NAME = "getNextTask"; export const TOOL_DESCRIPTION = ` Identifies and returns the next actionable task within a specified project. A task is considered actionable if its status is 'todo' and all its dependencies (if any) have a status of 'done'. If multiple tasks are ready, the one with the highest priority ('high' > 'medium' > 'low') is chosen. If priorities are equal, the task created earliest is chosen. Returns the full details of the next task, or null if no task is currently ready. `; // Zod schema for the parameters, matching FR-007 and getNextTaskTool.md spec 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 find the next task for."), // Required, UUID format }); // Define the expected type for arguments based on the Zod schema export type GetNextTaskArgs = z.infer<typeof TOOL_PARAMS>;
• src/tools/getNextTaskTool.ts:14-55 (registration)

  Registration function getNextTaskTool that defines the handler and registers it with the MCP server using server.tool().
  export const getNextTaskTool = (server: McpServer, taskService: TaskService): void => { const processRequest = async (args: GetNextTaskArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to get the next task const nextTask = await taskService.getNextTask(args.project_id); // Format the successful response if (nextTask) { logger.info(`[${TOOL_NAME}] Next task found: ${nextTask.task_id} in project ${args.project_id}`); } else { logger.info(`[${TOOL_NAME}] No ready task found for project ${args.project_id}`); } return { content: [{ type: "text" as const, // Return the full task object or null text: JSON.stringify(nextTask) }] }; } catch (error: unknown) { // Handle potential errors logger.error(`[${TOOL_NAME}] Error processing request:`, error); if (error instanceof NotFoundError) { // Project not found throw new McpError(ErrorCode.InvalidParams, error.message); } else { // Generic internal error const message = error instanceof Error ? error.message : 'An unknown error occurred while getting the next 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:59-59 (registration)

  Central registration point where getNextTaskTool is invoked during overall tool registration.
  getNextTaskTool(server, taskService);
• src/services/TaskService.ts:294-327 (helper)

  TaskService.getNextTask: Finds the next ready task (todo status, deps done), prioritizes by priority then creation date, returns full task details or null.
  public async getNextTask(projectId: string): Promise<FullTaskData | null> { logger.info(`[TaskService] Attempting to get next task for project ${projectId}`); // 1. Validate Project Existence const projectExists = this.projectRepository.findById(projectId); if (!projectExists) { logger.warn(`[TaskService] Project not found: ${projectId}`); throw new NotFoundError(`Project with ID ${projectId} not found.`); } // 2. Find ready tasks using the repository method try { const readyTasks = this.taskRepository.findReadyTasks(projectId); if (readyTasks.length === 0) { logger.info(`[TaskService] No ready tasks found for project ${projectId}`); return null; // No task is ready } // 3. The first task in the list is the highest priority one due to repo ordering const nextTask = readyTasks[0]; logger.info(`[TaskService] Next task identified: ${nextTask.task_id}`); // 4. Fetch full details (dependencies, subtasks) for the selected task // We could potentially optimize this if findReadyTasks returned more details, // but for separation of concerns, we call getTaskById logic (or similar). // Re-using getTaskById logic: return await this.getTaskById(projectId, nextTask.task_id); } catch (error) { logger.error(`[TaskService] Error getting next task for project ${projectId}:`, error); throw error; // Re-throw repository or other errors } }