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
      }
  }