get-upnify-activity-report

Instructions

Implementation Reference

• handlers/reports.ts:90-123 (handler)

  Core handler function that authenticates the user, constructs the API query with agrupacion and periodo parameters, fetches the activity report from the Upnify API endpoint, handles errors, and returns a standardized success response with the data.

  async getActivityReport(tkIntegracion: string, params: ActivityReportParams) {
      try {
          const { token, userInfo } = await this.auth.getTokenAndUserInfo(tkIntegracion);
          
          const queryParams = new URLSearchParams({
              agrupacion: params.agrupacion.toString(),
              periodo: params.periodo.toString()
          });
          
          const response = await fetch(`${API_URLS.UPNIFY_BASE}${ENDPOINTS.REPORTS.ACTIVITIES}?${queryParams}`, {
              method: 'GET',
              headers: {
                  'token': token,
                  'Content-Type': 'application/json',
              }
          });
          
          if (!response.ok) {
              const errorText = await response.text();
              throw new Error(`Error al obtener reporte de actividades: ${response.status} ${response.statusText}. ${errorText}`);
          }
          
          const result = await response.json();
          return {
              success: true,
              message: 'Reporte de actividades obtenido exitosamente',
              data: result,
              parameters: params,
              tkEmpresa: userInfo.tkEmpresa
          };
      } catch (error) {
          throw new Error(`Error al obtener reporte de actividades de Upnify: ${error instanceof Error ? error.message : error}`);
      }
  }

• main.ts:427-441 (registration)

  Tool dispatch logic in the CallToolRequest handler that validates input parameters, calls the reportsHandler.getActivityReport method, and formats success/error responses.

  } else if (name === 'get-upnify-activity-report') {
      const params = args as any;
      if (!validateActivityReportParams(params)) {
          return createErrorResponse(
              new Error('Se requieren todos los parámetros: agrupacion, periodo'),
              'Validación de parámetros'
          );
      }
  
      try {
          const result = await reportsHandler.getActivityReport(tkIntegracion, params);
          return createSuccessResponse(result);
      } catch (error) {
          return createErrorResponse(error, 'Error al obtener reporte de actividades de Upnify');
      }

• main.ts:254-274 (registration)

  Tool registration in the ListToolsRequest handler, defining the tool name, description, and MCP input schema with properties, enums, defaults, and required fields.

      name: 'get-upnify-activity-report',
      description: 'Get activity report from Upnify by group or executive and period',
      inputSchema: {
          type: 'object',
          properties: {
              agrupacion: {
                  type: 'integer',
                  description: 'Group by: 1=Executive, 2=Group',
                  enum: [1, 2],
                  default: 2
              },
              periodo: {
                  type: 'integer',
                  description: 'Period for report filtering. Options: 1=Today, 2=Yesterday, 3=Current week, 4=Last week, 5=Current month, 6=Last month, 8=Current year, 10=Last year, 13=Current semester, 14=Last semester, 17=Current quarter, 18=Last quarter.',
                  enum: [1, 2, 3, 4, 5, 6, 8, 10, 13, 14, 17, 18],
                  default: 17
              }
          },
          required: ['agrupacion', 'periodo']
      }
  },

• types/interfaces.ts:44-47 (schema)

  TypeScript interface defining the input parameters for the activity report (agrupacion and periodo).

  export interface ActivityReportParams {
      agrupacion: number;
      periodo: number;
  }

• utils/validators.ts:40-45 (helper)

  Validation helper function that checks if the required parameters (agrupacion, periodo) are present before calling the handler.

  export function validateActivityReportParams(params: any): params is ActivityReportParams {
      return (
          params.agrupacion !== undefined &&
          params.periodo !== undefined
      );
  }