workflows-mcp

Instructions

Implementation Reference

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

  The primary handler function for the 'run_workflow_step' tool. It parses input, manages workflow session state, stores step results in variables, handles workflow completion and branching logic, and generates instructions for the next step using helper methods.
  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 defining the input structure for the run_workflow_step tool: execution_id (string), step_result (any, optional), next_step_needed (boolean). Used for validation in the handler.
  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 the 'run_workflow_step' tool's name, detailed description, and input schema (converted from Zod 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)

  Registration in the CallToolRequestSchema handler's switch statement, routing calls to 'run_workflow_step' to the runWorkflowStep method.
  case 'run_workflow_step': return await this.runWorkflowStep(args);
• src/index.ts:732-864 (helper)

  Helper method called by the handler to generate detailed step-by-step execution instructions, including variable resolution, dependency management, change tracking, and upcoming step previews.
  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'); }