harvest-mcp-server

Instructions

Implementation Reference

• src/tools/time-entries.ts:23-39 (handler)

  The handler implementation for the 'list_time_entries' tool. It validates input using TimeEntryQuerySchema and executes the Harvest API call via config.harvestClient.getTimeEntries.

  class ListTimeEntriesHandler implements ToolHandler {
    constructor(private readonly config: BaseToolConfig) {}
  
    async execute(args: Record<string, any>): Promise<CallToolResult> {
      try {
        const validatedArgs = validateInput(TimeEntryQuerySchema, args, 'time entries query');
        logger.info('Listing time entries from Harvest API');
        const timeEntries = await this.config.harvestClient.getTimeEntries(validatedArgs);
        
        return {
          content: [{ type: 'text', text: JSON.stringify(timeEntries, null, 2) }],
        };
      } catch (error) {
        return handleMCPToolError(error, 'list_time_entries');
      }
    }
  }

• src/tools/time-entries.ts:173-196 (registration)

  The registration of the 'list_time_entries' tool, which associates the name, description, input schema, and the handler class.

  {
    tool: {
      name: 'list_time_entries',
      description: 'Retrieve a list of time entries with optional filtering. Supports filtering by user, client, project, task, billing status, date ranges, and more. Returns paginated results.',
      inputSchema: {
        type: 'object',
        properties: {
          user_id: { type: 'number', description: 'Filter by user ID' },
          client_id: { type: 'number', description: 'Filter by client ID' },
          project_id: { type: 'number', description: 'Filter by project ID' },
          task_id: { type: 'number', description: 'Filter by task ID' },
          is_billed: { type: 'boolean', description: 'Filter by billing status' },
          is_running: { type: 'boolean', description: 'Filter by running timer status' },
          updated_since: { type: 'string', format: 'date-time', description: 'Filter by entries updated since this timestamp' },
          from: { type: 'string', format: 'date', description: 'Start date for date range filter (YYYY-MM-DD)' },
          to: { type: 'string', format: 'date', description: 'End date for date range filter (YYYY-MM-DD)' },
          page: { type: 'number', minimum: 1, description: 'Page number for pagination' },
          per_page: { type: 'number', minimum: 1, maximum: 2000, description: 'Number of entries per page (max 2000)' },
        },
        additionalProperties: false,
      },
    },
    handler: new ListTimeEntriesHandler(config),
  },