harvest-mcp-server

Instructions

Implementation Reference

• src/tools/reports.ts:20-36 (handler)

  The handler class that implements the logic for 'get_time_report'. It validates inputs using a schema and calls the harvest client.

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

• src/tools/reports.ts:94-118 (registration)

  The tool registration block for 'get_time_report', including input schema definition and instantiation of the handler.

  {
    tool: {
      name: 'get_time_report',
      description: 'Generate comprehensive time tracking reports with filtering by date range, users, clients, projects, and tasks. Supports grouping and billable status filtering.',
      inputSchema: {
        type: 'object',
        properties: {
          from: { type: 'string', format: 'date', description: 'Start date for report (YYYY-MM-DD) (required)' },
          to: { type: 'string', format: 'date', description: 'End date for report (YYYY-MM-DD) (required)' },
          user_id: { type: 'number', description: 'Filter by specific user ID' },
          client_id: { type: 'number', description: 'Filter by specific client ID' },
          project_id: { type: 'number', description: 'Filter by specific project ID' },
          task_id: { type: 'number', description: 'Filter by specific task ID' },
          billable: { type: 'boolean', description: 'Filter by billable status' },
          is_billed: { type: 'boolean', description: 'Filter by billed 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' },
          group_by: { type: 'string', enum: ['user', 'client', 'project', 'task', 'date'], description: 'Group report results by specified dimension' },
        },
        required: ['from', 'to'],
        additionalProperties: false,
      },
    },
    handler: new GetTimeReportHandler(config),
  },