workflows-mcp

Instructions

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'); }