Create and manage KPI dashboards

Instructions

Implementation Reference

• src/tools/realtime-tools.ts:188-311 (handler)

  Main handler function implementing the core logic for creating, listing, getting, and refreshing KPI dashboards using mock data and service integration.

  public async execute(args: z.infer<typeof this.inputSchema>): Promise<any> {
    logger.info('Managing KPI dashboard', { action: args.action, dashboardId: args.dashboardId });
  
    const service = getRealtimeService();
  
    try {
      switch (args.action) {
        case 'create':
          if (!args.dashboard) {
            throw new Error('Dashboard configuration is required for create action');
          }
  
          const dashboardId = `dashboard_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
  
          // Simulate dashboard creation
          const createdDashboard = {
            dashboardId,
            name: args.dashboard.name,
            description: args.dashboard.description || '',
            kpis: args.dashboard.kpis.map((kpi, index) => ({
              widgetId: `widget_${dashboardId}_${index}`,
              name: kpi.name,
              type: kpi.type,
              entityType: kpi.entityType,
              serviceId: kpi.serviceId,
              aggregation: kpi.aggregation,
              timeWindow: kpi.timeWindow,
              currentValue: this.generateMockKPIValue(kpi.type),
              trend: this.generateMockTrend(),
              status: 'active',
            })),
            layout: {
              columns: 12,
              rows: Math.ceil(args.dashboard.kpis.length / 3),
              responsive: true,
              theme: 'sap_horizon',
            },
            refreshInterval: args.dashboard.refreshInterval,
            created: new Date().toISOString(),
            status: 'active',
          };
  
          return {
            success: true,
            message: `KPI Dashboard '${args.dashboard.name}' created successfully`,
            dashboard: createdDashboard,
            capabilities: [
              'Real-time data visualization',
              'Automated threshold alerts',
              'Trend analysis and forecasting',
              'Interactive drill-down capabilities',
            ],
            nextSteps: [
              'Connect to real-time data stream for live updates',
              'Configure alert thresholds and notifications',
              'Customize visualization themes and layouts',
            ],
          };
  
        case 'list':
          const dashboards = service.getDashboards();
          return {
            success: true,
            dashboards: dashboards.map(d => ({
              dashboardId: d.dashboardId,
              name: d.name,
              description: d.description,
              widgetCount: d.kpis.length,
              owner: d.owner,
              created: d.created,
              status: d.isActive ? 'active' : 'inactive',
            })),
            total: dashboards.length,
            summary: `Found ${dashboards.length} KPI dashboards`,
          };
  
        case 'get':
          if (!args.dashboardId) {
            throw new Error('Dashboard ID is required for get action');
          }
  
          // Simulate dashboard retrieval
          const mockDashboard = this.generateMockDashboard(args.dashboardId);
  
          return {
            success: true,
            dashboard: mockDashboard,
            realTimeStatus: 'connected',
            lastUpdated: new Date().toISOString(),
          };
  
        case 'refresh':
          if (!args.dashboardId) {
            throw new Error('Dashboard ID is required for refresh action');
          }
  
          // Simulate data refresh
          const refreshedData = this.generateMockRefreshData();
  
          return {
            success: true,
            dashboardId: args.dashboardId,
            refreshed: new Date().toISOString(),
            updates: refreshedData,
            message: 'Dashboard data refreshed successfully',
          };
  
        default:
          throw new Error(`Unknown action: ${args.action}`);
      }
    } catch (error: any) {
      logger.error('KPI Dashboard error', { error: error.message });
      return {
        success: false,
        error: error.message,
        action: args.action,
        troubleshooting: [
          'Verify dashboard configuration is valid',
          'Ensure entity types and service IDs exist',
          'Check real-time data stream connectivity',
        ],
      };
    }
  }

• src/tools/realtime-tools.ts:166-184 (schema)

  Input schema using Zod for validating tool parameters including action type, dashboard ID, configuration, and data inclusion options.

  public readonly inputSchema = z
    .object({
      action: z.enum(['create', 'update', 'delete', 'list', 'get', 'refresh']),
      dashboardId: z
        .string()
        .optional()
        .describe('Dashboard ID (required for update/delete/get/refresh)'),
      dashboard: KPIDashboardSchema.optional().describe(
        'Dashboard configuration (required for create)'
      ),
      updates: z.record(z.any()).optional().describe('Fields to update (for update action)'),
      includeData: z
        .boolean()
        .optional()
        .default(false)
        .describe('Include current KPI data in response'),
    })
    .strict()
    .describe('KPI dashboard management');

• src/types/realtime-types.ts:269-286 (schema)

  Zod schema defining the structure of a KPI dashboard configuration used in the tool's input validation.

  export const KPIDashboardSchema = z.object({
    name: z.string().min(1),
    description: z.string().optional(),
    kpis: z.array(
      z.object({
        name: z.string().min(1),
        type: z.enum(['metric', 'chart', 'gauge', 'table', 'heatmap', 'forecast', 'comparison']),
        entityType: z.string().min(1),
        serviceId: z.string().min(1),
        aggregation: z.enum(['sum', 'count', 'avg', 'min', 'max', 'distinct']),
        timeWindow: z.object({
          period: z.enum(['minutes', 'hours', 'days', 'weeks', 'months']),
          size: z.number().positive(),
        }),
      })
    ),
    refreshInterval: z.number().positive().default(30000),
  });

• src/tools/realtime-tools.ts:1122-1127 (registration)

  Array exporting the instantiated KPIDashboardBuilderTool for registration in the MCP tool registry.

  export const realtimeAnalyticsTools = [
    new RealTimeDataStreamTool(),
    new KPIDashboardBuilderTool(),
    new PredictiveAnalyticsEngineTool(),
    new BusinessIntelligenceInsightsTool(),
  ];

• src/tools/realtime-tools.ts:357-384 (helper)

  Helper method generating mock dashboard data for retrieval and demonstration purposes.

  private generateMockDashboard(dashboardId: string): any {
    return {
      dashboardId,
      name: 'SAP Business Overview',
      description: 'Real-time business metrics and KPIs',
      widgets: [
        {
          widgetId: 'widget_1',
          name: 'Total Revenue',
          type: 'metric',
          currentValue: 1250000,
          trend: { direction: 'up', percentage: 12.5 },
          status: 'healthy',
        },
        {
          widgetId: 'widget_2',
          name: 'Sales Trend',
          type: 'chart',
          currentValue: [850, 920, 1100, 980, 1250, 1180, 1300],
          trend: { direction: 'up', percentage: 8.2 },
          status: 'healthy',
        },
      ],
      layout: { columns: 12, rows: 4, theme: 'sap_horizon' },
      refreshInterval: ANALYTICS_INTERVALS.DASHBOARD_REFRESH,
      lastUpdated: new Date().toISOString(),
    };
  }