create_project

Instructions

Implementation Reference

• src/tools/projects.ts:63-79 (handler)

  CreateProjectHandler - The core handler class that executes the create_project tool logic. It validates input using CreateProjectSchema, calls harvestClient.createProject(), and returns the result.

  class CreateProjectHandler implements ToolHandler {
    constructor(private readonly config: BaseToolConfig) {}
  
    async execute(args: Record<string, any>): Promise<CallToolResult> {
      try {
        const validatedArgs = validateInput(CreateProjectSchema, args, 'create project');
        logger.info('Creating project via Harvest API');
        const project = await this.config.harvestClient.createProject(validatedArgs);
        
        return {
          content: [{ type: 'text', text: JSON.stringify(project, null, 2) }],
        };
      } catch (error) {
        return handleMCPToolError(error, 'create_project');
      }
    }
  }

• src/schemas/project.ts:61-82 (schema)

  CreateProjectSchema - Zod schema defining all input fields for creating a project (name, client_id, billing config, budget, dates, etc.) with validation constraints and defaults.

  export const CreateProjectSchema = z.object({
    name: z.string().min(1, 'Project name is required'),
    client_id: z.number().int().positive(),
    code: z.string().optional(),
    is_active: z.boolean().optional().default(true),
    is_billable: z.boolean().optional().default(true),
    is_fixed_fee: z.boolean().optional().default(false),
    bill_by: z.enum(['Project', 'Tasks', 'People', 'none']).optional().default('none'),
    hourly_rate: z.number().min(0).optional(),
    budget: z.number().min(0).optional(),
    budget_by: z.enum(['project', 'project_cost', 'task', 'task_fees', 'person', 'none']).optional(),
    budget_is_monthly: z.boolean().optional().default(false),
    notify_when_over_budget: z.boolean().optional().default(false),
    over_budget_notification_percentage: z.number().min(0).max(100).optional(),
    show_budget_to_all: z.boolean().optional().default(false),
    cost_budget: z.number().min(0).optional(),
    cost_budget_include_expenses: z.boolean().optional().default(false),
    fee: z.number().min(0).optional(),
    notes: z.string().optional(),
    starts_on: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format').optional(),
    ends_on: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format').optional(),
  });

• src/tools/projects.ts:239-272 (registration)

  Tool registration entry for 'create_project' in registerProjectTools(). Defines the tool name, description, JSON input schema, and binds the CreateProjectHandler instance.

  {
    tool: {
      name: 'create_project',
      description: 'Create a new project for a client. Requires project name and client ID. Supports extensive configuration including budget settings, billing preferences, and project timeline.',
      inputSchema: {
        type: 'object',
        properties: {
          name: { type: 'string', minLength: 1, description: 'Project name (required)' },
          client_id: { type: 'number', description: 'The client ID this project belongs to (required)' },
          code: { type: 'string', description: 'Project code for reference' },
          is_active: { type: 'boolean', description: 'Whether the project is active' },
          is_billable: { type: 'boolean', description: 'Whether the project is billable' },
          is_fixed_fee: { type: 'boolean', description: 'Whether the project uses fixed fee billing' },
          bill_by: { type: 'string', enum: ['Project', 'Tasks', 'People', 'none'], description: 'How to bill for this project' },
          hourly_rate: { type: 'number', minimum: 0, description: 'Default hourly rate for the project' },
          budget: { type: 'number', minimum: 0, description: 'Project budget amount' },
          budget_by: { type: 'string', enum: ['project', 'project_cost', 'task', 'task_fees', 'person', 'none'], description: 'How budget is calculated' },
          budget_is_monthly: { type: 'boolean', description: 'Whether budget resets monthly' },
          notify_when_over_budget: { type: 'boolean', description: 'Send notifications when over budget' },
          over_budget_notification_percentage: { type: 'number', minimum: 0, maximum: 100, description: 'Percentage threshold for budget notifications' },
          show_budget_to_all: { type: 'boolean', description: 'Show budget information to all team members' },
          cost_budget: { type: 'number', minimum: 0, description: 'Cost budget for the project' },
          cost_budget_include_expenses: { type: 'boolean', description: 'Include expenses in cost budget calculations' },
          fee: { type: 'number', minimum: 0, description: 'Fixed fee amount' },
          notes: { type: 'string', description: 'Project notes' },
          starts_on: { type: 'string', format: 'date', description: 'Project start date (YYYY-MM-DD)' },
          ends_on: { type: 'string', format: 'date', description: 'Project end date (YYYY-MM-DD)' },
        },
        required: ['name', 'client_id'],
        additionalProperties: false,
      },
    },
    handler: new CreateProjectHandler(config),
  },

• src/client/projects-client.ts:47-67 (helper)

  ProjectsClient.createProject() - Low-level HTTP client method that POSTs to /projects via Axios to create the project in the Harvest API.

  async createProject(input: any): Promise<any> {
    try {
      this.logger.debug('Creating project', {
        name: input.name,
        clientId: input.client_id
      });
      
      const response = await this.client.post('/projects', input);
      
      this.logger.info('Successfully created project', {
        projectId: response.data.id,
        projectName: response.data.name,
        clientId: response.data.client.id
      });
      
      return response.data;
    } catch (error) {
      this.logger.error('Failed to create project:', error);
      throw error;
    }
  }

• src/client/harvest-api.ts:143-145 (registration)

  HarvestAPIClient.createProject() - Facade method that delegates to projectsClient.createProject().

  async createProject(input: any): Promise<any> {
    return this.projectsClient.createProject(input);
  }