harvest-mcp-server

Instructions

Implementation Reference

• src/tools/time-entries.ts:117-133 (handler)

  The handler implementation for the 'start_timer' tool, which uses Harvest API to initiate a timer.

  class StartTimerHandler implements ToolHandler {
    constructor(private readonly config: BaseToolConfig) {}
  
    async execute(args: Record<string, any>): Promise<CallToolResult> {
      try {
        const validatedArgs = validateInput(StartTimerSchema, args, 'start timer');
        logger.info('Starting timer via Harvest API');
        const timeEntry = await this.config.harvestClient.startTimer(validatedArgs);
        
        return {
          content: [{ type: 'text', text: JSON.stringify(timeEntry, null, 2) }],
        };
      } catch (error) {
        return handleMCPToolError(error, 'start_timer');
      }
    }
  }

• src/tools/time-entries.ts:290-317 (registration)

  Registration of the 'start_timer' tool within the time entries module.

  {
    tool: {
      name: 'start_timer',
      description: 'Start a timer for a new time entry. Creates a running time entry that tracks time automatically.',
      inputSchema: {
        type: 'object',
        properties: {
          project_id: { type: 'number', description: 'The project ID to start the timer for' },
          task_id: { type: 'number', description: 'The task ID to start the timer for' },
          spent_date: { type: 'string', format: 'date', description: 'Date for the timer (YYYY-MM-DD format)' },
          notes: { type: 'string', maxLength: 2000, description: 'Initial notes for the timer' },
          external_reference: {
            type: 'object',
            properties: {
              id: { type: 'string' },
              group_id: { type: 'string' },
              account_id: { type: 'string' },
              permalink: { type: 'string', format: 'uri' },
            },
            additionalProperties: false,
          },
        },
        required: ['project_id', 'task_id', 'spent_date'],
        additionalProperties: false,
      },
    },
    handler: new StartTimerHandler(config),
  },