get-time-report

Instructions

Implementation Reference

• src/tools/reporting/reports.ts:6-40 (handler)

  The main handler for the 'get-time-report' tool. Calls floatApi.getPaginated('/reports/time', ...) to fetch time tracking report data with filters.

  export const getTimeReport = createTool(
    'get-time-report',
    'Get time tracking report with various filters',
    z.object({
      start_date: z.string().describe('Start date for report (YYYY-MM-DD)'),
      end_date: z.string().describe('End date for report (YYYY-MM-DD)'),
      people_id: z.number().optional().describe('Filter by person ID'),
      project_id: z.number().optional().describe('Filter by project ID'),
      client_id: z.number().optional().describe('Filter by client ID'),
      department_id: z.number().optional().describe('Filter by department ID'),
      billable: z
        .number()
        .optional()
        .describe('Filter by billable status (0=non-billable, 1=billable)'),
      format: z.enum(['json', 'csv']).optional().describe('Report format (default: json)'),
    }),
    async (params) => {
      const response = await floatApi.getPaginated(
        '/reports/time',
        params,
        z.array(
          z.object({
            people_id: z.number().optional(),
            project_id: z.number().optional(),
            task_id: z.number().optional(),
            date: z.string().optional(),
            hours: z.number().optional(),
            billable: z.number().optional(),
            notes: z.string().nullable().optional(),
          })
        )
      );
      return response;
    }
  );

• src/tools/reporting/reports.ts:9-21 (schema)

  Input schema for the get-time-report tool, defining all filter parameters (start_date, end_date, people_id, project_id, client_id, department_id, billable) and format option.

  z.object({
    start_date: z.string().describe('Start date for report (YYYY-MM-DD)'),
    end_date: z.string().describe('End date for report (YYYY-MM-DD)'),
    people_id: z.number().optional().describe('Filter by person ID'),
    project_id: z.number().optional().describe('Filter by project ID'),
    client_id: z.number().optional().describe('Filter by client ID'),
    department_id: z.number().optional().describe('Filter by department ID'),
    billable: z
      .number()
      .optional()
      .describe('Filter by billable status (0=non-billable, 1=billable)'),
    format: z.enum(['json', 'csv']).optional().describe('Report format (default: json)'),
  }),

• src/tools/index.ts:311-315 (registration)

  Registration of getTimeReport in the legacyTools array, which is exported and combined with optimizedTools to form the final tools export.

    // Reporting tools
    getTimeReport,
    getProjectReport,
    getPeopleUtilizationReport,
  ];

• src/tools/index.ts:167-172 (registration)

  Import of getTimeReport from the reporting module into the tools index file.

  // Reporting tools
  import {
    getTimeReport,
    getProjectReport,
    getPeopleUtilizationReport,
  } from './reporting/reports.js';

• src/tools/base.ts:50-104 (helper)

  The createTool helper function that wraps a handler with validation and error handling. Used by getTimeReport to build the tool object with name, description, inputSchema, and handler.

  export const createTool = <T, P extends z.ZodType>(
    name: string,
    description: string,
    schema: P,
    handler: (params: z.infer<P>) => Promise<T>
  ): {
    name: string;
    description: string;
    inputSchema: P;
    handler: (params: unknown) => Promise<ToolResponse<T>>;
  } => {
    return {
      name,
      description,
      inputSchema: schema,
      handler: async (params: unknown): Promise<ToolResponse<T>> => {
        try {
          const validatedParams = schema.parse(params);
          const result = await handler(validatedParams);
  
          // Extract format from params if available
          const responseFormat =
            ((validatedParams as Record<string, unknown>).format as ResponseFormat) || 'json';
  
          return { success: true, data: result, format: responseFormat };
        } catch (error) {
          logger.error(`Error in ${name} tool:`, error);
  
          // Handle Float API errors with enhanced formatting
          if (error instanceof FloatApiError) {
            return FloatErrorHandler.formatErrorForMcp(error) as ToolResponse<T>;
          }
  
          // Handle parameter validation errors
          if (error instanceof z.ZodError) {
            return {
              success: false,
              error: `Parameter validation failed: ${error.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ')}`,
              errorCode: 'PARAMETER_VALIDATION_ERROR',
              details: {
                validationErrors: error.errors,
              },
            } as ToolResponse<T>;
          }
  
          // Handle other errors
          return {
            success: false,
            error: error instanceof Error ? error.message : 'Unknown error occurred',
            errorCode: 'UNKNOWN_ERROR',
          } as ToolResponse<T>;
        }
      },
    };
  };