generate_custom_report

Instructions

Implementation Reference

• src/tools/analytics-insights.ts:424-468 (handler)

  The main handler function for the generate_custom_report tool. Validates input via Zod schema, collects data from each requested source (projects, tasks, documents, conversations, team_members, automations), calculates summary statistics, formats output (json/csv/summary), and optionally sets up scheduling.

  export const generateCustomReport = requireAuth(async (args: any) => {
    const { report_name, data_sources, metrics_config, output_format, schedule } = GenerateCustomReportSchema.parse(args)
    
    logger.info('Generating custom report', { report_name, data_sources, output_format })
  
    const report: any = {
      name: report_name,
      generated_at: new Date().toISOString(),
      data_sources,
      metrics_config: metrics_config || {},
      data: {}
    }
  
    // Collect data from each source
    for (const source of data_sources) {
      try {
        report.data[source] = await collectReportData(source, metrics_config)
      } catch (error) {
        logger.error(`Failed to collect data from ${source}:`, error)
        report.data[source] = { error: 'Data collection failed' }
      }
    }
  
    // Calculate summary statistics
    report.summary = calculateReportSummary(report.data, metrics_config)
  
    // Format output based on requested format
    if (output_format === 'csv') {
      report.csv_data = convertToCSV(report.data)
    } else if (output_format === 'summary') {
      return {
        report_name,
        summary: report.summary,
        key_insights: generateReportInsights(report.data),
        generated_at: report.generated_at
      }
    }
  
    // Set up scheduling if requested
    if (schedule) {
      report.schedule_id = await scheduleReport(report_name, args, schedule)
    }
  
    return report
  })

• src/tools/analytics-insights.ts:409-422 (schema)

  Zod validation schema for the tool's input parameters: report_name (required), data_sources (required, enum), metrics_config (optional with time_grouping/aggregation_method/filters), output_format (default: json), and schedule (optional with frequency/recipients).

  const GenerateCustomReportSchema = z.object({
    report_name: z.string().min(1),
    data_sources: z.array(z.enum(['projects', 'tasks', 'documents', 'conversations', 'team_members', 'automations'])).min(1),
    metrics_config: z.object({
      time_grouping: z.enum(['day', 'week', 'month']).default('week'),
      aggregation_method: z.enum(['sum', 'average', 'count']).default('count'),
      filters: z.record(z.any()).optional()
    }).optional(),
    output_format: z.enum(['json', 'csv', 'summary']).default('json'),
    schedule: z.object({
      frequency: z.enum(['once', 'daily', 'weekly', 'monthly']),
      recipients: z.array(z.string())
    }).optional()
  })

• src/tools/analytics-insights.ts:363-407 (registration)

  The MCPTool definition object that registers the tool with name 'generate_custom_report', description, and JSON Schema input definition. This is what the MCP protocol uses to expose the tool to clients.

  export const generateCustomReportTool: MCPTool = {
    name: 'generate_custom_report',
    description: 'Generate a custom analytics report with specified metrics and visualizations',
    inputSchema: {
      type: 'object',
      properties: {
        report_name: {
          type: 'string',
          description: 'Name for the custom report'
        },
        data_sources: {
          type: 'array',
          items: {
            type: 'string',
            enum: ['projects', 'tasks', 'documents', 'conversations', 'team_members', 'automations']
          },
          description: 'Data sources to include in the report'
        },
        metrics_config: {
          type: 'object',
          properties: {
            time_grouping: { type: 'string', enum: ['day', 'week', 'month'], default: 'week' },
            aggregation_method: { type: 'string', enum: ['sum', 'average', 'count'], default: 'count' },
            filters: { type: 'object' }
          },
          description: 'Configuration for metrics calculation'
        },
        output_format: {
          type: 'string',
          enum: ['json', 'csv', 'summary'],
          default: 'json',
          description: 'Output format for the report'
        },
        schedule: {
          type: 'object',
          properties: {
            frequency: { type: 'string', enum: ['once', 'daily', 'weekly', 'monthly'] },
            recipients: { type: 'array', items: { type: 'string' } }
          },
          description: 'Optional scheduling configuration'
        }
      },
      required: ['report_name', 'data_sources']
    }
  }

• src/tools/analytics-insights.ts:778-791 (registration)

  Exports the tool and handler in the analyticsInsightsTools and analyticsInsightsHandlers objects, mapping the name 'generate_custom_report' to the generateCustomReport handler function.

  // Export all analytics tools
  export const analyticsInsightsTools = {
    getProjectAnalyticsTool,
    getTeamProductivityTool,
    getWorkspaceHealthTool,
    generateCustomReportTool
  }
  
  export const analyticsInsightsHandlers = {
    get_project_analytics: getProjectAnalytics,
    get_team_productivity: getTeamProductivity,
    get_workspace_health: getWorkspaceHealth,
    generate_custom_report: generateCustomReport
  }

• src/tools/analytics-insights.ts:738-757 (helper)

  Helper functions used by the handler: collectReportData (fetches data per source), calculateReportSummary (computes summary stats), generateReportInsights (produces insight strings), convertToCSV (formats as CSV), and scheduleReport (creates scheduled report). All are placeholder implementations.

  async function collectReportData(source: string, config?: any): Promise<any> {
    // Placeholder for data collection
    return { count: 10, trend: 'positive' }
  }
  
  function calculateReportSummary(data: any, config?: any): any {
    return { total_items: 100, growth_rate: 5.2 }
  }
  
  function generateReportInsights(data: any): string[] {
    return ['Strong growth in documentation', 'Task completion trending upward']
  }
  
  function convertToCSV(data: any): string {
    return 'header1,header2\nvalue1,value2' // Placeholder
  }
  
  async function scheduleReport(name: string, config: any, schedule: any): Promise<string> {
    return 'schedule_123' // Placeholder
  }