run_workflow_step

Execute the next step in an active workflow session by following provided instructions precisely to advance structured multi-step processes.

Instructions

Execute the next step in an active workflow session.

IMPORTANT: When executing workflow steps, follow these rules:

DO NOT provide commentary between workflow steps unless explicitly requested
Simply execute each step according to the workflow instructions
Move immediately to the next step after completing the current one
Only provide output when the workflow specifically requires it (e.g., notify actions, final results)
Focus solely on executing the workflow actions as defined

The tool will provide step-by-step instructions that should be followed exactly.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`execution_id`	Yes
`step_result`	No
`next_step_needed`	Yes

Implementation Reference

src/index.ts:544-648 (handler)

The core handler function for the 'run_workflow_step' tool. It processes the input arguments, manages the workflow session state, stores step results, handles branching logic, determines the next step, generates execution instructions, or completes the workflow if finished.

private async runWorkflowStep(args: unknown) {
  const parsed = RunWorkflowStepSchema.parse(args);
  
  const session = this.sessions.get(parsed.execution_id);
  if (!session) {
    throw new Error(`No active workflow session found: ${parsed.execution_id}`);
  }

  const workflow = await this.storage.get(session.workflow_id);
  if (!workflow) {
    throw new Error(`Workflow not found: ${session.workflow_id}`);
  }

  // Store result from previous step if provided
  if (parsed.step_result !== undefined && session.current_step_index > 0) {
    const previousStep = workflow.steps[session.current_step_index - 1];
    if (previousStep.save_result_as) {
      // Store in step outputs for dependency tracking
      session.step_outputs[previousStep.id] = {
        variable_name: previousStep.save_result_as,
        value: parsed.step_result
      };
      
      // Update previous_variables to track what was before this change
      session.previous_variables = { ...session.variables };
      
      // Update current variables
      session.variables[previousStep.save_result_as] = parsed.step_result;
    }
  }

  // Check if workflow is complete
  if (!parsed.next_step_needed || session.current_step_index >= workflow.steps.length) {
    session.status = 'completed';
    this.sessions.delete(parsed.execution_id);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            status: 'completed',
            execution_id: parsed.execution_id,
            message: `Workflow "${workflow.name}" completed successfully`,
            final_variables: session.variables,
          }, null, 2),
        },
      ],
    };
  }

  // Check if the current step was a branch step
  const currentStep = workflow.steps[session.current_step_index];
  let nextStepIndex = session.current_step_index + 1;
  
  // Handle branching logic
  if (currentStep.action === 'branch' && parsed.step_result) {
    // Parse the branch result to find the target step
    const branchResult = parsed.step_result.toString();
    const gotoMatch = branchResult.match(/step (\d+)/i);
    if (gotoMatch) {
      const targetStep = parseInt(gotoMatch[1]);
      // Find the index of the target step (steps are 1-indexed, array is 0-indexed)
      nextStepIndex = workflow.steps.findIndex(s => s.id === targetStep);
      if (nextStepIndex === -1) {
        throw new Error(`Branch target step ${targetStep} not found`);
      }
    }
  }
  
  // Update session with next step
  session.current_step_index = nextStepIndex;
  
  if (session.current_step_index >= workflow.steps.length) {
    session.status = 'completed';
    this.sessions.delete(parsed.execution_id);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            status: 'completed',
            execution_id: parsed.execution_id,
            message: `Workflow "${workflow.name}" completed successfully`,
            final_variables: session.variables,
          }, null, 2),
        },
      ],
    };
  }

  // Generate instructions for the next step
  const nextStep = workflow.steps[session.current_step_index];
  const stepInstructions = this.generateStepInstructions(workflow, nextStep, session);

  return {
    content: [
      {
        type: 'text',
        text: stepInstructions,
      },
    ],
  };
}

src/index.ts:70-74 (schema)
Zod schema validating the input for run_workflow_step: execution_id (string), step_result (any, optional), next_step_needed (boolean). Used in handler and tool registration.
```
const RunWorkflowStepSchema = z.object({
  execution_id: z.string(),
  step_result: z.any().optional(),
  next_step_needed: z.boolean(),
});
```

src/index.ts:282-295 (registration)

Tool registration in the getTools() method, defining name 'run_workflow_step', its description, and input schema converted to JSON schema.

      {
        name: 'run_workflow_step',
        description: `Execute the next step in an active workflow session.

IMPORTANT: When executing workflow steps, follow these rules:
1. DO NOT provide commentary between workflow steps unless explicitly requested
2. Simply execute each step according to the workflow instructions
3. Move immediately to the next step after completing the current one
4. Only provide output when the workflow specifically requires it (e.g., notify actions, final results)
5. Focus solely on executing the workflow actions as defined

The tool will provide step-by-step instructions that should be followed exactly.`,
        inputSchema: zodToJsonSchema(RunWorkflowStepSchema),
      },

src/index.ts:134-135 (registration)
Dispatcher case in the central CallToolRequestSchema handler that routes 'run_workflow_step' calls to the runWorkflowStep method.
```
case 'run_workflow_step':
  return await this.runWorkflowStep(args);
```

src/index.ts:732-864 (helper)

Key helper function called by the handler to generate detailed step-by-step execution instructions, including template variable resolution, dependency-based visible variables, change highlighting, and upcoming steps preview.

private generateStepInstructions(workflow: Workflow, step: Step, session: WorkflowSession): string {
  const lines: string[] = [];
  
  lines.push('=== WORKFLOW STEP EXECUTION ===');
  lines.push('');
  lines.push(`Workflow: ${workflow.name} (${session.execution_id})`);
  lines.push(`Step ${session.current_step_index + 1} of ${session.total_steps}`);
  lines.push('');
  lines.push(`Action: ${step.action.toUpperCase()}`);
  lines.push(`Description: ${this.resolveTemplateVariables(step.description, session.variables)}`);
  lines.push('');
  
  // Step-specific instructions
  if (step.action === 'tool_call' && 'tool_name' in step && 'parameters' in step) {
    lines.push('Execute the following tool:');
    lines.push(`Tool: ${step.tool_name}`);
    // Resolve template variables in parameters
    const resolvedParams = this.resolveTemplateInObject(step.parameters, session.variables);
    lines.push(`Parameters: ${JSON.stringify(resolvedParams, null, 2)}`);
  } else if (step.action === 'analyze' || step.action === 'consider' || step.action === 'research' || 
             step.action === 'validate' || step.action === 'summarize' || step.action === 'decide' ||
             step.action === 'extract' || step.action === 'compose') {
    lines.push(`Perform the cognitive action: ${step.action}`);
    if ('input_from' in step && step.input_from) {
      lines.push('Using input from:');
      for (const varName of step.input_from) {
        if (session.variables[varName] !== undefined) {
          lines.push(`  ${varName}: ${JSON.stringify(session.variables[varName])}`);
        }
      }
    }
    if ('criteria' in step && step.criteria) {
      lines.push(`Criteria: ${this.resolveTemplateVariables(step.criteria, session.variables)}`);
    }
  } else if (step.action === 'wait_for_input' && 'prompt' in step) {
    lines.push('Request input from the user:');
    lines.push(`Prompt: ${this.resolveTemplateVariables(step.prompt, session.variables)}`);
    if ('input_type' in step) {
      lines.push(`Expected type: ${step.input_type}`);
    }
  } else if (step.action === 'transform' && 'transformation' in step) {
    lines.push('Apply transformation:');
    lines.push(this.resolveTemplateVariables(step.transformation, session.variables));
    if ('input_from' in step && step.input_from) {
      lines.push('To variables:');
      for (const varName of step.input_from) {
        if (session.variables[varName] !== undefined) {
          lines.push(`  ${varName}: ${JSON.stringify(session.variables[varName])}`);
        }
      }
    }
  } else if (step.action === 'branch' && 'conditions' in step) {
    lines.push('Evaluate conditions and determine next step:');
    lines.push('');
    for (const condition of step.conditions) {
      lines.push(`IF ${condition.if} THEN GOTO step ${condition.goto_step}`);
    }
    lines.push('');
    lines.push('Evaluate the conditions using the current variables and respond with:');
    lines.push('- Which condition is true');
    lines.push('- The step number to jump to (e.g., "Branching to step 8")');
  } else if (step.action === 'notify' && 'message' in step) {
    lines.push('Send notification:');
    lines.push(`Message: ${this.resolveTemplateVariables(step.message, session.variables)}`);
    if ('channel' in step && step.channel) {
      lines.push(`Channel: ${this.resolveTemplateVariables(step.channel, session.variables)}`);
    }
  }
  
  if (step.save_result_as) {
    lines.push('');
    lines.push(`Save the result as: ${step.save_result_as}`);
  }
  
  // Get visible variables based on dependencies
  const visibleVariables = this.getVisibleVariables(workflow, step, session);
  
  // Show variable changes if we have previous state
  if (session.current_step_index > 0 && Object.keys(session.previous_variables).length > 0) {
    const changes = this.getChangedVariables(session);
    
    if (changes.added.length > 0 || changes.modified.length > 0) {
      lines.push('');
      lines.push('Variable changes:');
      
      for (const varName of changes.added) {
        if (varName in visibleVariables) {
          lines.push(`  + ${varName}: ${JSON.stringify(session.variables[varName])}`);
        }
      }
      
      for (const varName of changes.modified) {
        if (varName in visibleVariables) {
          lines.push(`  ~ ${varName}: ${JSON.stringify(session.variables[varName])}`);
        }
      }
    }
  }
  
  // Show current visible variables
  lines.push('');
  lines.push('Available variables:');
  const visibleVarNames = Object.keys(visibleVariables);
  if (visibleVarNames.length === 0) {
    lines.push('  (none - use dependencies to access previous step outputs)');
  } else {
    for (const [key, value] of Object.entries(visibleVariables)) {
      lines.push(`  ${key}: ${JSON.stringify(value)}`);
    }
  }
  
  // Show upcoming steps (progressive loading)
  if (session.current_step_index < workflow.steps.length - 1) {
    lines.push('');
    lines.push('Upcoming steps:');
    const maxPreview = Math.min(session.current_step_index + 3, workflow.steps.length);
    for (let i = session.current_step_index + 1; i < maxPreview; i++) {
      const upcomingStep = workflow.steps[i];
      lines.push(`  ${i + 1}. ${upcomingStep.action}: ${upcomingStep.description}`);
    }
    if (maxPreview < workflow.steps.length) {
      lines.push(`  ... and ${workflow.steps.length - maxPreview} more steps`);
    }
  }
  
  lines.push('');
  lines.push('After completing this step, call run_workflow_step with:');
  lines.push('- execution_id: ' + session.execution_id);
  lines.push('- step_result: <the result of this step, if any>');
  lines.push('- next_step_needed: true (or false if the workflow should end)');
  
  return lines.join('\n');
}

workflows-mcp