createProject
Initiate a new project workspace in the MCP Task Manager Server database, assigning a unique UUID. Optionally specify a custom name or use a default timestamped name. Used by AI agents to start structured task management.
Instructions
Creates a new, empty project entry in the Task Management Server database. This tool is used by clients (e.g., AI agents) to initiate a new workspace for tasks. It returns the unique identifier (UUID) assigned to the newly created project. An optional name can be provided; otherwise, a default name including a timestamp will be generated.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectName | No | Optional human-readable name for the new project (max 255 chars). If omitted, a default name like 'New Project [timestamp]' will be used. |
Implementation Reference
- src/tools/createProjectTool.ts:18-44 (handler)The asynchronous handler function for the createProject tool. It processes the input args, calls ProjectService.createProject, formats the response with project_id, and handles errors.const processRequest = async (args: CreateProjectArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to create the project const newProject = await projectService.createProject(args.projectName); // Format the successful response according to MCP standards const responsePayload = { project_id: newProject.project_id }; logger.info(`[${TOOL_NAME}] Project created successfully: ${newProject.project_id}`); return { content: [{ type: "text" as const, // Required type assertion text: JSON.stringify(responsePayload) }] }; } catch (error: unknown) { // Handle potential errors from the service layer logger.error(`[${TOOL_NAME}] Error processing request:`, error); // Basic error mapping: Assume internal error unless a specific known error type is caught // TODO: Add more specific error mapping if ProjectService throws custom errors // (e.g., catch (error instanceof ValidationError) { throw new McpError(ErrorCode.InvalidParams, ...)}) const message = error instanceof Error ? error.message : 'An unknown error occurred during project creation.'; throw new McpError(ErrorCode.InternalError, message); } };
- Defines the input schema using Zod for the createProject tool parameters (projectName: optional string), TOOL_NAME, TOOL_DESCRIPTION, and the inferred CreateProjectArgs type.// Define the shape of the parameters for the server.tool method export const TOOL_PARAMS = { projectName: z.string() .max(255, "Project name cannot exceed 255 characters.") // Max length constraint .optional() // Optional parameter .describe("Optional human-readable name for the new project (max 255 chars). If omitted, a default name like 'New Project [timestamp]' will be used."), // Detailed description }; // Create a Zod schema object from the shape for validation and type inference const toolParamsSchema = z.object(TOOL_PARAMS); // Define the expected type for arguments based on the Zod schema export type CreateProjectArgs = z.infer<typeof toolParamsSchema>;
- src/tools/createProjectTool.ts:15-50 (registration)The createProjectTool function that defines and registers the MCP tool with the server using server.tool(), including the handler, schema, and description.export const createProjectTool = (server: McpServer, projectService: ProjectService): void => { // Define the asynchronous function that handles the actual tool logic const processRequest = async (args: CreateProjectArgs) => { logger.info(`[${TOOL_NAME}] Received request with args:`, args); try { // Call the service method to create the project const newProject = await projectService.createProject(args.projectName); // Format the successful response according to MCP standards const responsePayload = { project_id: newProject.project_id }; logger.info(`[${TOOL_NAME}] Project created successfully: ${newProject.project_id}`); return { content: [{ type: "text" as const, // Required type assertion text: JSON.stringify(responsePayload) }] }; } catch (error: unknown) { // Handle potential errors from the service layer logger.error(`[${TOOL_NAME}] Error processing request:`, error); // Basic error mapping: Assume internal error unless a specific known error type is caught // TODO: Add more specific error mapping if ProjectService throws custom errors // (e.g., catch (error instanceof ValidationError) { throw new McpError(ErrorCode.InvalidParams, ...)}) const message = error instanceof Error ? error.message : 'An unknown error occurred during project creation.'; throw new McpError(ErrorCode.InternalError, message); } }; // Register the tool with the server server.tool(TOOL_NAME, TOOL_DESCRIPTION, TOOL_PARAMS, processRequest); logger.info(`[${TOOL_NAME}] Tool registered successfully.`); };
- src/tools/index.ts:53-53 (registration)Calls the createProjectTool registration function during overall tools registration.createProjectTool(server, projectService);
- src/services/ProjectService.ts:38-56 (helper)The ProjectService.createProject method that performs the actual database insertion of a new project via the repository.public async createProject(projectName?: string): Promise<ProjectData> { const projectId = uuidv4(); const now = new Date().toISOString(); const finalProjectName = projectName?.trim() || `New Project ${now}`; const newProject: ProjectData = { project_id: projectId, name: finalProjectName, created_at: now, }; logger.info(`[ProjectService] Attempting to create project: ${projectId} with name "${finalProjectName}"`); try { this.projectRepository.create(newProject); logger.info(`[ProjectService] Successfully created project: ${projectId}`); return newProject; } catch (error) { logger.error(`[ProjectService] Error creating project ${projectId}:`, error); throw error; } }