MCP Task Manager Server

Instructions

Implementation Reference

• src/tools/listTasksTool.ts:16-47 (handler)

  The handler function that executes the listTasks tool: logs request, calls TaskService.listTasks with args, returns JSON-stringified tasks or throws MCP errors.
  const processRequest = async (args: ListTasksArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to list tasks const tasks = await taskService.listTasks({ project_id: args.project_id, status: args.status, include_subtasks: args.include_subtasks, }); // Format the successful response logger.info(`[${TOOL_NAME}] Found ${tasks.length} tasks for project ${args.project_id}`); return { content: [{ type: "text" as const, text: JSON.stringify(tasks) // Return the array of task objects }] }; } catch (error: unknown) { // Handle potential errors logger.error(`[${TOOL_NAME}] Error processing request:`, error); if (error instanceof NotFoundError) { // Specific error if the project wasn't found throw new McpError(ErrorCode.InvalidParams, error.message); // Map NotFound to InvalidParams for project_id } else { // Generic internal error const message = error instanceof Error ? error.message : 'An unknown error occurred while listing tasks.'; throw new McpError(ErrorCode.InternalError, message); } } };
• src/tools/listTasksParams.ts:13-32 (schema)

  Zod schema (TOOL_PARAMS) and type (ListTasksArgs) for listTasks tool inputs: required project_id UUID, optional status enum, optional include_subtasks bool (default false). Includes TOOL_NAME = 'listTasks'.
  const TaskStatusEnum = z.enum(['todo', 'in-progress', 'review', 'done']); // Zod schema for the parameters, matching FR-003 and listTasksTool.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 whose tasks are to be listed. This project must exist."), // Required, UUID format status: TaskStatusEnum .optional() .describe("Optional filter to return only tasks matching the specified status."), // Optional, enum include_subtasks: z.boolean() .optional() .default(false) // Default value .describe("Optional flag (default false). If true, the response will include subtasks nested within their parent tasks."), // Optional, boolean, default }); // Define the expected type for arguments based on the Zod schema export type ListTasksArgs = z.infer<typeof TOOL_PARAMS>;
• src/tools/listTasksTool.ts:14-53 (registration)

  The registration function listTasksTool that defines the handler and calls server.tool to register 'listTasks' with MCP server.
  export const listTasksTool = (server: McpServer, taskService: TaskService): void => { const processRequest = async (args: ListTasksArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to list tasks const tasks = await taskService.listTasks({ project_id: args.project_id, status: args.status, include_subtasks: args.include_subtasks, }); // Format the successful response logger.info(`[${TOOL_NAME}] Found ${tasks.length} tasks for project ${args.project_id}`); return { content: [{ type: "text" as const, text: JSON.stringify(tasks) // Return the array of task objects }] }; } catch (error: unknown) { // Handle potential errors logger.error(`[${TOOL_NAME}] Error processing request:`, error); if (error instanceof NotFoundError) { // Specific error if the project wasn't found throw new McpError(ErrorCode.InvalidParams, error.message); // Map NotFound to InvalidParams for project_id } else { // Generic internal error const message = error instanceof Error ? error.message : 'An unknown error occurred while listing tasks.'; 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:13-55 (registration)

  Imports and invokes listTasksTool during overall tool registration in the tools index.
  import { listTasksTool } from "./listTasksTool.js"; import { showTaskTool } from "./showTaskTool.js"; import { setTaskStatusTool } from "./setTaskStatusTool.js"; import { expandTaskTool } from "./expandTaskTool.js"; import { getNextTaskTool } from "./getNextTaskTool.js"; import { exportProjectTool } from "./exportProjectTool.js"; import { importProjectTool } from "./importProjectTool.js"; import { updateTaskTool } from "./updateTaskTool.js"; // Import the new tool import { deleteTaskTool } from "./deleteTaskTool.js"; // Import deleteTask tool import { deleteProjectTool } from "./deleteProjectTool.js"; // Import deleteProject tool // import { yourTool } from "./yourTool.js"; // Add other new tool imports here /** * Register all defined tools with the MCP server instance. * This function centralizes tool registration logic. * It also instantiates necessary services and repositories. */ export function registerTools(server: McpServer): void { logger.info("Registering tools..."); const configManager = ConfigurationManager.getInstance(); // --- Instantiate Dependencies --- // Note: Consider dependency injection frameworks for larger applications try { const dbManager = DatabaseManager.getInstance(); const db = dbManager.getDb(); // Get the initialized DB connection // Instantiate Repositories const projectRepository = new ProjectRepository(db); const taskRepository = new TaskRepository(db); // Instantiate TaskRepository // Instantiate Services const projectService = new ProjectService(db, projectRepository, taskRepository); // Pass db and both repos const taskService = new TaskService(db, taskRepository, projectRepository); // Instantiate TaskService, passing db and repos // --- Register Tools --- // Register each tool, passing necessary services // exampleTool(server, configManager.getExampleServiceConfig()); // Example commented out createProjectTool(server, projectService); addTaskTool(server, taskService); listTasksTool(server, taskService);
• src/services/TaskService.ts:100-136 (helper)

  TaskService.listTasks method: validates project, fetches tasks from repo, filters top-level or builds nested structure with subtasks if requested.
  public async listTasks(options: ListTasksOptions): Promise<TaskData[] | StructuredTaskData[]> { logger.info(`[TaskService] Attempting to list tasks for project: ${options.project_id}`, options); const projectExists = this.projectRepository.findById(options.project_id); if (!projectExists) { logger.warn(`[TaskService] Project not found: ${options.project_id}`); throw new NotFoundError(`Project with ID ${options.project_id} not found.`); } try { const allTasks = this.taskRepository.findByProjectId(options.project_id, options.status); if (!options.include_subtasks) { const topLevelTasks = allTasks.filter(task => !task.parent_task_id); logger.info(`[TaskService] Found ${topLevelTasks.length} top-level tasks for project ${options.project_id}`); return topLevelTasks; } else { const taskMap: Map<string, StructuredTaskData> = new Map(); const rootTasks: StructuredTaskData[] = []; for (const task of allTasks) { taskMap.set(task.task_id, { ...task, subtasks: [] }); } for (const task of allTasks) { if (task.parent_task_id && taskMap.has(task.parent_task_id)) { const parent = taskMap.get(task.parent_task_id)!; parent.subtasks!.push(taskMap.get(task.task_id)!); } else if (!task.parent_task_id) { rootTasks.push(taskMap.get(task.task_id)!); } } logger.info(`[TaskService] Found ${rootTasks.length} structured root tasks for project ${options.project_id}`); return rootTasks; } } catch (error) { logger.error(`[TaskService] Error listing tasks for project ${options.project_id}:`, error); throw error; } }