Helios-9 MCP Server

Instructions

Implementation Reference

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

  The main handler function that parses input arguments using the schema, collects data from specified sources, computes summaries, handles different output formats, and optionally schedules the report.

  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 schema defining the input structure and validation for the generate_custom_report tool, including required fields like report_name and data_sources.

  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)

  MCPTool object definition registering the generate_custom_report tool with its name, description, and input schema.

  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:786-791 (registration)

  Export mapping handler names to functions, registering generate_custom_report to its handler.

  export const analyticsInsightsHandlers = {
    get_project_analytics: getProjectAnalytics,
    get_team_productivity: getTeamProductivity,
    get_workspace_health: getWorkspaceHealth,
    generate_custom_report: generateCustomReport
  }

• src/tools/analytics-insights.ts:779-784 (registration)

  Export grouping all tool definitions, including generateCustomReportTool.

  export const analyticsInsightsTools = {
    getProjectAnalyticsTool,
    getTeamProductivityTool,
    getWorkspaceHealthTool,
    generateCustomReportTool
  }