MCP Task Manager Server

Instructions

Implementation Reference

• src/tools/exportProjectParams.ts:1-26 (schema)

  Defines TOOL_NAME, TOOL_DESCRIPTION, TOOL_PARAMS Zod schema for input validation, and ExportProjectArgs type for the exportProject tool.

  import { z } from 'zod';
  
  export const TOOL_NAME = "exportProject";
  
  export const TOOL_DESCRIPTION = `
  Exports the complete data set for a specified project as a JSON string.
  This includes project metadata, all tasks (hierarchically structured), and their dependencies.
  Requires the project ID. The format is fixed to JSON for V1.
  Returns the JSON string representing the project data.
  `;
  
  // Zod schema for the parameters, matching FR-009 and exportProjectTool.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 export."), // Required, UUID format
  
      format: z.literal('json') // Only allow 'json' for V1
          .optional()
          .default('json')
          .describe("Optional format for the export. Currently only 'json' is supported (default)."), // Optional, enum (fixed), default
  });
  
  // Define the expected type for arguments based on the Zod schema
  export type ExportProjectArgs = z.infer<typeof TOOL_PARAMS>;

• src/tools/exportProjectTool.ts:16-43 (handler)

  The handler function for the exportProject tool. Processes arguments, calls ProjectService.exportProject, handles errors, and returns the JSON string in MCP format.

  const processRequest = async (args: ExportProjectArgs) => {
      logger.info(`[${TOOL_NAME}] Received request with args:`, args);
      try {
          // Zod schema ensures format is 'json' if provided, or defaults to 'json'
          const jsonString = await projectService.exportProject(args.project_id);
  
          // Format the successful response
          logger.info(`[${TOOL_NAME}] Successfully exported project ${args.project_id}`);
          return {
              content: [{
                  type: "text" as const,
                  text: jsonString // Return the JSON string directly
              }]
          };
      } 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 exporting the project.';
              throw new McpError(ErrorCode.InternalError, message);
          }
      }
  };

• src/tools/exportProjectTool.ts:14-49 (registration)

  Registers the exportProject tool with the MCP server using server.tool(), providing name, description, params schema, and handler.

  export const exportProjectTool = (server: McpServer, projectService: ProjectService): void => {
  
      const processRequest = async (args: ExportProjectArgs) => {
          logger.info(`[${TOOL_NAME}] Received request with args:`, args);
          try {
              // Zod schema ensures format is 'json' if provided, or defaults to 'json'
              const jsonString = await projectService.exportProject(args.project_id);
  
              // Format the successful response
              logger.info(`[${TOOL_NAME}] Successfully exported project ${args.project_id}`);
              return {
                  content: [{
                      type: "text" as const,
                      text: jsonString // Return the JSON string directly
                  }]
              };
          } 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 exporting the project.';
                  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/services/ProjectService.ts:80-135 (helper)

  Core logic for exporting project data: fetches project metadata, tasks, dependencies, builds hierarchical structure with subtasks and deps, returns formatted JSON string.

  public async exportProject(projectId: string): Promise<string> {
      logger.info(`[ProjectService] Attempting to export project: ${projectId}`);
      const projectMetadata = this.projectRepository.findById(projectId);
      if (!projectMetadata) {
          logger.warn(`[ProjectService] Project not found for export: ${projectId}`);
          throw new NotFoundError(`Project with ID ${projectId} not found.`);
      }
  
      try {
          const allTasks = this.taskRepository.findAllTasksForProject(projectId);
          const allDependencies = this.taskRepository.findAllDependenciesForProject(projectId);
  
          const taskMap: Map<string, ExportTask> = new Map();
          const rootTasks: ExportTask[] = [];
          const dependencyMap: Map<string, string[]> = new Map();
  
          for (const dep of allDependencies) {
              if (!dependencyMap.has(dep.task_id)) {
                  dependencyMap.set(dep.task_id, []);
              }
              dependencyMap.get(dep.task_id)!.push(dep.depends_on_task_id);
          }
  
          for (const task of allTasks) {
              taskMap.set(task.task_id, {
                  ...task,
                  dependencies: dependencyMap.get(task.task_id) || [],
                  subtasks: [],
              });
          }
  
          for (const task of allTasks) {
              const exportTask = taskMap.get(task.task_id)!;
              if (task.parent_task_id && taskMap.has(task.parent_task_id)) {
                  const parent = taskMap.get(task.parent_task_id)!;
                  if (!parent.subtasks) parent.subtasks = [];
                  parent.subtasks.push(exportTask);
              } else if (!task.parent_task_id) {
                  rootTasks.push(exportTask);
              }
          }
  
          const exportData: ExportData = {
              project_metadata: projectMetadata,
              tasks: rootTasks,
          };
  
          const jsonString = JSON.stringify(exportData, null, 2);
          logger.info(`[ProjectService] Successfully prepared export data for project ${projectId}`);
          return jsonString;
  
      } catch (error) {
          logger.error(`[ProjectService] Error exporting project ${projectId}:`, error);
          throw error;
      }
  }

• src/tools/index.ts:60-60 (registration)

  Calls exportProjectTool to register the exportProject tool during overall tools registration.

  exportProjectTool(server, projectService);