Helios-9 MCP Server

Instructions

Implementation Reference

• src/tools/tasks.ts:866-913 (handler)

  The main handler function for the get_task_workflow_status tool. It validates input using the schema, retrieves tasks from the project, calculates progress metrics, dependencies, critical path, bottlenecks, and returns a comprehensive workflow status report.

  export const getTaskWorkflowStatus = requireAuth(async (args: any) => {
    const { project_id, workflow_name } = GetTaskWorkflowStatusSchema.parse(args)
    
    logger.info('Getting workflow status', { project_id, workflow_name })
  
    // Get workflow tasks (metadata_filter not available)
    const tasks = await supabaseService.getTasks({
      project_id
      // metadata_filter not available as metadata doesn't exist in database schema
    })
  
    if (tasks.length === 0) {
      throw new Error(`Workflow "${workflow_name}" not found`)
    }
  
    // Calculate progress
    const totalTasks = tasks.length
    const completedTasks = tasks.filter(t => t.status === 'done').length
    const inProgressTasks = tasks.filter(t => t.status === 'in_progress').length
    const todoTasks = tasks.filter(t => t.status === 'todo').length
  
    // Get dependencies for this workflow
    const dependencies = await supabaseService.getProjectDependencies(project_id)
    const workflowDependencies = dependencies.filter(d => 
      tasks.some(t => t.id === d.task_id) && tasks.some(t => t.id === d.depends_on_task_id)
    )
  
    // Calculate critical path
    const criticalPath = calculateCriticalPath(tasks, workflowDependencies)
    
    // Identify bottlenecks
    const bottlenecks = identifyWorkflowBottlenecks(tasks, workflowDependencies)
  
    return {
      workflow_name,
      progress: {
        total_tasks: totalTasks,
        completed_tasks: completedTasks,
        in_progress_tasks: inProgressTasks,
        todo_tasks: todoTasks,
        completion_percentage: Math.round((completedTasks / totalTasks) * 100)
      },
      critical_path: criticalPath,
      bottlenecks,
      next_actions: getNextWorkflowActions(tasks, workflowDependencies),
      estimated_completion: estimateWorkflowCompletion(tasks, workflowDependencies)
    }
  })

• src/tools/tasks.ts:861-864 (schema)

  Zod schema for input validation of the get_task_workflow_status tool, requiring project_id and workflow_name.

  const GetTaskWorkflowStatusSchema = z.object({
    project_id: z.string().min(1),
    workflow_name: z.string().min(1)
  })

• src/tools/tasks.ts:842-859 (registration)

  MCPTool registration object defining the tool's name, description, and input schema structure for the MCP protocol.

  export const getTaskWorkflowStatusTool: MCPTool = {
    name: 'get_task_workflow_status',
    description: 'Get status and progress of a task workflow',
    inputSchema: {
      type: 'object',
      properties: {
        project_id: {
          type: 'string',
          description: 'ID of the project'
        },
        workflow_name: {
          type: 'string',
          description: 'Name of the workflow'
        }
      },
      required: ['project_id', 'workflow_name']
    }
  }

• src/tools/tasks.ts:1157-1167 (registration)

  Central registry mapping tool names to their handler functions, including get_task_workflow_status.

  export const taskHandlers = {
    list_tasks: listTasks,
    create_task: createTask,
    get_task: getTask,
    update_task: updateTask,
    add_task_dependency: addTaskDependency,
    get_task_dependencies: getTaskDependencies,
    create_task_workflow: createTaskWorkflow,
    bulk_update_tasks: bulkUpdateTasks,
    get_task_workflow_status: getTaskWorkflowStatus
  }

• src/tools/tasks.ts:1059-1096 (helper)

  Helper function used by the handler to identify bottlenecks in the workflow such as high-dependency tasks and overdue blockers.

  function identifyWorkflowBottlenecks(tasks: any[], dependencies: any[]): any[] {
    const bottlenecks = []
    
    // Tasks with many dependencies
    const dependencyCounts = new Map()
    dependencies.forEach(dep => {
      dependencyCounts.set(dep.task_id, (dependencyCounts.get(dep.task_id) || 0) + 1)
    })
    
    // High-dependency tasks
    const highDependencyTasks = tasks.filter(task => 
      (dependencyCounts.get(task.id) || 0) > 2
    )
    
    bottlenecks.push(...highDependencyTasks.map(task => ({
      task_id: task.id,
      title: task.title,
      type: 'high_dependencies',
      dependency_count: dependencyCounts.get(task.id) || 0
    })))
    
    // Overdue tasks that block others
    const overdueBlockers = tasks.filter(task => 
      task.due_date && 
      new Date(task.due_date) < new Date() && 
      task.status !== 'done' &&
      dependencies.some(d => d.depends_on_task_id === task.id)
    )
    
    bottlenecks.push(...overdueBlockers.map(task => ({
      task_id: task.id,
      title: task.title,
      type: 'overdue_blocker',
      days_overdue: Math.ceil((Date.now() - new Date(task.due_date!).getTime()) / (1000 * 60 * 60 * 24))
    })))
    
    return bottlenecks
  }