MCP Server: Weather & Upnify Integration

Instructions

Implementation Reference

• handlers/reports.ts:8-47 (handler)

  The main handler function that authenticates with Upnify, constructs the API query parameters, fetches the sales report from the Upnify API endpoint, and returns the formatted response.
  async getSalesReport(tkIntegracion: string, reportParams: ReportParams) { try { const { token, userInfo } = await this.auth.getTokenAndUserInfo(tkIntegracion); // Construir URL con parámetros de query const queryParams = new URLSearchParams({ agrupacion: reportParams.agrupacion.toString(), periodicidad: reportParams.periodicidad.toString(), anio: reportParams.anio!.toString(), impuestos: reportParams.impuestos!.toString() }); const response = await fetch(`${API_URLS.UPNIFY_BASE}${ENDPOINTS.REPORTS.SALES}?${queryParams}`, { method: 'GET', headers: { 'token': token, 'Content-Type': 'application/json', } }); if (!response.ok) { const errorText = await response.text(); console.error('Parámetros enviados:', reportParams); console.error('Token usado:', token); console.error('Respuesta del servidor:', errorText); throw new Error(`Error al obtener reporte de ventas: ${response.status} ${response.statusText}. ${errorText}`); } const result = await response.json(); return { success: true, message: 'Reporte de ventas obtenido exitosamente', data: result, parameters: reportParams, tkEmpresa: userInfo.tkEmpresa }; } catch (error) { throw new Error(`Error al obtener reporte de ventas de Upnify: ${error instanceof Error ? error.message : error}`); } }
• main.ts:127-156 (schema)

  MCP tool input schema defining parameters for grouping, periodicity, year, and taxes inclusion with enums, defaults, and required fields.
  inputSchema: { type: 'object', properties: { agrupacion: { type: 'integer', description: 'Group by: 1=Executive, 2=Group, 3=Line, 17=Industry, 4=Origin, 5=Country, 6=Region', enum: [1, 2, 3, 17, 4, 5, 6], default: 17 }, periodicidad: { type: 'integer', description: 'Period: 4=Monthly, 3=Bimonthly, 2=Quarterly, 1=Semiannual, 5=Biweekly, 6=Weekly', enum: [1, 2, 3, 4, 5, 6], default: 6 }, anio: { type: 'integer', description: 'Year (2009-2025)', minimum: 2009, maximum: 2025, default: 2025 }, impuestos: { type: 'integer', description: 'Taxes: 0=Exclude, 1=Include', enum: [0, 1], default: 0 } }, required: ['agrupacion', 'periodicidad', 'anio', 'impuestos']
• main.ts:327-348 (registration)

  Tool dispatch registration in the CallToolRequestSchema handler that validates parameters, calls the reportsHandler.getSalesReport, formats response, and handles errors.
  } else if (name === 'get-upnify-sales-report') { const reportParams = args as any; if (!validateReportParams(reportParams)) { return createErrorResponse( new Error('Se requieren todos los parámetros: agrupacion, periodicidad, anio, impuestos'), 'Validación de parámetros' ); } try { const result = await reportsHandler.getSalesReport(tkIntegracion, reportParams); const parametersDescription = formatReportParameters(reportParams); return createSuccessResponse({ success: true, message: 'Reporte de ventas obtenido exitosamente', parameters: parametersDescription, data: result.data }); } catch (error) { return createErrorResponse(error, 'Error al obtener reporte de ventas de Upnify'); }
• types/interfaces.ts:37-42 (schema)

  TypeScript interface defining the shape of ReportParams used in the handler for type safety.
  export interface ReportParams { agrupacion: number; periodicidad: number; anio?: number; impuestos?: number; }
• utils/validators.ts:31-38 (helper)

  Validation function ensuring all required report parameters are present before calling the handler.
  export function validateReportParams(params: any): params is ReportParams { return ( params.agrupacion !== undefined && params.periodicidad !== undefined && params.anio !== undefined && params.impuestos !== undefined ); }