MCP Task Manager Server

Instructions

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);