Helios-9 MCP Server

Instructions

Implementation Reference

• src/tools/workflow-automation.ts:377-409 (handler)

  Main execution handler for the get_automation_analytics tool. Parses input, fetches rules and executions from Supabase, computes analytics using helper, and returns structured performance data.

  export const getAutomationAnalytics = requireAuth(async (args: any) => {
    const { project_id, time_range, include_inactive } = GetAutomationAnalyticsSchema.parse(args)
    
    logger.info('Getting automation analytics', { project_id, time_range })
  
    const [rules, executions] = await Promise.all([
      supabaseService.getWorkflowRules({ 
        project_id, 
        enabled: include_inactive ? undefined : true 
      }),
      supabaseService.getWorkflowExecutions({ 
        project_id, 
        time_range 
      })
    ])
  
    // Calculate analytics
    const analytics = calculateAutomationAnalytics(rules, executions, time_range)
  
    return {
      summary: {
        total_rules: rules.length,
        active_rules: rules.filter(r => r.enabled).length,
        total_executions: executions.length,
        successful_executions: executions.filter(e => e.success).length,
        time_range
      },
      performance: analytics.performance,
      top_performers: analytics.topPerformers,
      failure_analysis: analytics.failureAnalysis,
      recommendations: analytics.recommendations
    }
  })

• src/tools/workflow-automation.ts:371-375 (schema)

  Zod schema for validating input parameters: project_id (optional), time_range (enum with default 'week'), include_inactive (boolean default false).

  const GetAutomationAnalyticsSchema = z.object({
    project_id: z.string().optional(),
    time_range: z.enum(['day', 'week', 'month', 'quarter']).default('week'),
    include_inactive: z.boolean().default(false)
  })

• src/tools/workflow-automation.ts:346-369 (registration)

  MCPTool registration object defining name, description, and input schema for the tool.

  export const getAutomationAnalyticsTool: MCPTool = {
    name: 'get_automation_analytics',
    description: 'Get analytics and performance data for workflow automations',
    inputSchema: {
      type: 'object',
      properties: {
        project_id: {
          type: 'string',
          description: 'Project ID to filter analytics (optional)'
        },
        time_range: {
          type: 'string',
          enum: ['day', 'week', 'month', 'quarter'],
          default: 'week',
          description: 'Time range for analytics'
        },
        include_inactive: {
          type: 'boolean',
          default: false,
          description: 'Include disabled automations in analytics'
        }
      }
    }
  }

• src/tools/workflow-automation.ts:602-608 (registration)

  Export mapping tool names to their handler functions, registering get_automation_analytics to getAutomationAnalytics.

  export const workflowAutomationHandlers = {
    create_workflow_rule: createWorkflowRule,
    list_workflow_rules: listWorkflowRules,
    execute_workflow_rule: executeWorkflowRule,
    create_trigger_automation: createTriggerAutomation,
    get_automation_analytics: getAutomationAnalytics
  }

• src/tools/workflow-automation.ts:469-533 (helper)

  Key helper function called by the handler to compute detailed analytics including performance metrics, top performers, failure analysis, and recommendations.

  function calculateAutomationAnalytics(rules: any[], executions: any[], timeRange: string): any {
    const now = new Date()
    const timeRangeMs = getTimeRangeMs(timeRange)
    const recentExecutions = executions.filter(e => 
      new Date(e.executed_at).getTime() > now.getTime() - timeRangeMs
    )
  
    // Performance metrics
    const performance = {
      total_executions: recentExecutions.length,
      success_rate: recentExecutions.length > 0 ? 
        (recentExecutions.filter(e => e.success).length / recentExecutions.length) * 100 : 0,
      average_execution_time: calculateAverageExecutionTime(recentExecutions),
      executions_per_day: recentExecutions.length / getDaysInRange(timeRange)
    }
  
    // Top performing rules
    const rulePerformance = new Map()
    recentExecutions.forEach(exec => {
      const ruleId = exec.rule_id
      if (!rulePerformance.has(ruleId)) {
        rulePerformance.set(ruleId, { executions: 0, successes: 0 })
      }
      const stats = rulePerformance.get(ruleId)
      stats.executions++
      if (exec.success) stats.successes++
    })
  
    const topPerformers = Array.from(rulePerformance.entries())
      .map(([ruleId, stats]) => ({
        rule_id: ruleId,
        rule_name: rules.find(r => r.id === ruleId)?.name || 'Unknown',
        executions: stats.executions,
        success_rate: (stats.successes / stats.executions) * 100
      }))
      .sort((a, b) => b.executions - a.executions)
      .slice(0, 5)
  
    // Failure analysis
    const failures = recentExecutions.filter(e => !e.success)
    const failureReasons = new Map()
    failures.forEach(f => {
      const reason = f.error_message || 'Unknown error'
      failureReasons.set(reason, (failureReasons.get(reason) || 0) + 1)
    })
  
    const failureAnalysis = {
      total_failures: failures.length,
      failure_rate: recentExecutions.length > 0 ? (failures.length / recentExecutions.length) * 100 : 0,
      common_failures: Array.from(failureReasons.entries())
        .map(([reason, count]) => ({ reason, count }))
        .sort((a, b) => b.count - a.count)
        .slice(0, 3)
    }
  
    // Recommendations
    const recommendations = generateAutomationRecommendations(performance, failureAnalysis, rules)
  
    return {
      performance,
      topPerformers,
      failureAnalysis,
      recommendations
    }
  }