get_expense_report

Generate detailed expense reports from Harvest data by filtering date ranges, users, clients, projects, categories, and billing status. Group results for analysis.

Instructions

Generate comprehensive expense reports with filtering by date range, users, clients, projects, and categories. Supports grouping and billing status filtering.

Input Schema

TableJSON Schema

Name	Required	Description
`from`	Yes	Start date for report (YYYY-MM-DD) (required)
`to`	Yes	End date for report (YYYY-MM-DD) (required)
`user_id`	No	Filter by specific user ID
`client_id`	No	Filter by specific client ID
`project_id`	No	Filter by specific project ID
`expense_category_id`	No	Filter by specific expense category ID
`billable`	No	Filter by billable status
`is_billed`	No	Filter by billed status
`updated_since`	No	Filter by expenses updated since this timestamp
`group_by`	No	Group report results by specified dimension

Implementation Reference

src/tools/reports.ts:38-54 (handler)

The GetExpenseReportHandler class implements the execute method for the 'get_expense_report' tool. It validates inputs against ExpenseReportQuerySchema, calls the Harvest client, and handles potential errors.

class GetExpenseReportHandler implements ToolHandler {
  constructor(private readonly config: BaseToolConfig) {}

  async execute(args: Record<string, any>): Promise<CallToolResult> {
    try {
      const validatedArgs = validateInput(ExpenseReportQuerySchema, args, 'expense report query');
      logger.info('Generating expense report from Harvest API');
      const report = await this.config.harvestClient.getExpenseReport(validatedArgs);
      
      return {
        content: [{ type: 'text', text: JSON.stringify(report, null, 2) }],
      };
    } catch (error) {
      return handleMCPToolError(error, 'get_expense_report');
    }
  }
}

src/tools/reports.ts:119-142 (registration)

The tool 'get_expense_report' is registered within registerReportTools in src/tools/reports.ts, defining its schema and associating it with the GetExpenseReportHandler.

{
  tool: {
    name: 'get_expense_report',
    description: 'Generate comprehensive expense reports with filtering by date range, users, clients, projects, and categories. Supports grouping and billing 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' },
        expense_category_id: { type: 'number', description: 'Filter by specific expense category ID' },
        billable: { type: 'boolean', description: 'Filter by billable status' },
        is_billed: { type: 'boolean', description: 'Filter by billed status' },
        updated_since: { type: 'string', format: 'date-time', description: 'Filter by expenses updated since this timestamp' },
        group_by: { type: 'string', enum: ['user', 'client', 'project', 'expense_category', 'date'], description: 'Group report results by specified dimension' },
      },
      required: ['from', 'to'],
      additionalProperties: false,
    },
  },
  handler: new GetExpenseReportHandler(config),
},

harvest-mcp-server