workflows-mcp

Instructions

Implementation Reference

• src/index.ts:309-356 (handler)

  The core handler function for the 'create_workflow' tool. Parses input arguments using the defined schema, generates a unique ID and metadata, constructs the Workflow object, validates it, persists it to storage, and returns a success response containing the new workflow ID.

  private async createWorkflow(args: unknown) {
    const parsed = CreateWorkflowSchema.parse(args);
    
    // Generate ID and add metadata
    const id = await this.storage.generateId();
    const now = new Date().toISOString();
    
    const workflow: Workflow = {
      id,
      name: parsed.workflow.name,
      description: parsed.workflow.description,
      goal: parsed.workflow.goal,
      version: parsed.workflow.version || '1.0.0',
      tags: parsed.workflow.tags || [],
      inputs: parsed.workflow.inputs || {},
      outputs: parsed.workflow.outputs,
      required_tools: parsed.workflow.required_tools,
      steps: parsed.workflow.steps,
      metadata: {
        created_at: now,
        updated_at: now,
        times_run: 0,
      },
      is_deleted: false,
    };
  
    // Validate the complete workflow
    const validation = WorkflowValidator.validateWorkflow(workflow);
    if (!validation.success) {
      throw new Error(`Validation failed: ${validation.error}`);
    }
  
    // Save to storage
    await this.storage.save(workflow);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            workflow_id: id,
            message: `Workflow "${workflow.name}" created successfully`,
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:17-34 (schema)

  Zod schema defining the expected input structure for the create_workflow tool, validating the workflow definition object containing name, description, goal, optional version/tags/inputs/outputs/required_tools, and required steps array.

  const CreateWorkflowSchema = z.object({
    workflow: z.object({
      name: z.string().describe('Descriptive name for the workflow'),
      description: z.string().describe('What this workflow accomplishes'),
      goal: z.string().describe('The end result or desired outcome'),
      version: z.string().optional().describe('Semantic version (default: "1.0.0")'),
      tags: z.array(z.string()).optional().describe('Categories for organization'),
      inputs: z.record(z.object({
        type: z.enum(['string', 'number', 'boolean', 'array', 'object']),
        description: z.string(),
        required: z.boolean().default(true),
        default: z.any().optional()
      })).optional().describe('Input parameters the workflow accepts'),
      outputs: z.array(z.string()).optional().describe('Names of output variables'),
      required_tools: z.array(z.string()).optional().describe('MCP tools needed'),
      steps: z.array(z.any()).describe('Workflow steps with actions'),
    }).describe('Complete workflow definition'),
  });

• src/index.ts:158-256 (registration)

  Registers the 'create_workflow' tool in the MCP tools list returned by getTools(), providing the tool name, comprehensive usage description including workflow structure and actions, and the converted JSON input schema.

        {
          name: 'create_workflow',
          description: `Create a new workflow with specified steps and configuration.
  
  WORKFLOW STRUCTURE:
  - name: Descriptive workflow name
  - description: What the workflow accomplishes
  - goal: The end result or outcome
  - version: Semantic version (default: "1.0.0")
  - tags: Array of categorization tags
  - inputs: Object defining input parameters with type, description, required, and optional default
  - outputs: Array of expected output variable names
  - required_tools: Array of MCP tools this workflow needs
  - steps: Array of workflow steps (see below)
  - strict_dependencies: Boolean to enable strict dependency mode (default: false)
    * false: Steps without dependencies see all variables (backward compatible)
    * true: Steps without dependencies see NO variables (must explicitly declare dependencies)
  
  AVAILABLE ACTIONS:
  - tool_call: Execute an MCP tool (requires tool_name and parameters)
  - analyze: Analyze data and extract insights
  - consider: Evaluate options or possibilities  
  - research: Gather information on a topic
  - validate: Check data quality or correctness
  - summarize: Create a summary of information
  - decide: Make a decision based on criteria
  - wait_for_input: Request user input (requires prompt)
  - transform: Transform data (requires transformation description)
  - extract: Extract specific information
  - compose: Create new content
  - branch: Conditional branching (requires conditions array)
  - checkpoint: Save progress checkpoint
  - notify: Send a notification (requires message)
  - assert: Verify a condition (requires condition)
  - retry: Retry a previous step (requires step_id)
  
  STEP STRUCTURE:
  {
    "id": 1, // Sequential number starting from 1
    "action": "action_type",
    "description": "What this step does",
    "save_result_as": "variable_name", // Optional: save result
    "error_handling": "stop|continue|retry", // Default: "stop"
    "dependencies": [1, 3], // Optional: only show outputs from these step IDs
    "show_all_variables": true, // Optional: override to show all variables
    
    // For tool_call:
    "tool_name": "mcp_tool_name",
    "parameters": { "param": "value" },
    
    // For cognitive actions (analyze, consider, research, etc):
    "input_from": ["variable1", "variable2"], // Input variables
    "criteria": "Specific criteria or focus", // Optional
    
    // For branch:
    "conditions": [
      { "if": "variable.property > value", "goto_step": 5 }
    ],
    
    // For wait_for_input:
    "prompt": "Question for the user",
    "input_type": "text|number|boolean|json",
    
    // For transform:
    "transformation": "Description of transformation"
  }
  
  TEMPLATE VARIABLES:
  Use {{variable_name}} in any string field to reference:
  - Input parameters from workflow inputs
  - Results saved from previous steps via save_result_as
  - Any variables in the workflow state
  
  EXAMPLES:
  - "path": "output_{{format}}.txt"
  - "prompt": "Process {{count}} items?"
  - "description": "Analyzing {{filename}}"
  
  DEPENDENCY MANAGEMENT:
  - Use "dependencies" array to specify which previous steps' outputs are needed
  - In strict_dependencies mode, steps without dependencies see NO variables
  - Steps with dependencies only see outputs from those specific steps + workflow inputs
  - Use "show_all_variables": true to override and see all variables for a specific step
  
  PERFORMANCE FEATURES:
  - Only relevant variables are shown based on dependencies (reduces token usage)
  - Variable changes are highlighted (+ for new, ~ for modified)
  - Only next 3 steps are previewed (progressive loading)
  
  BEST PRACTICES:
  1. Each step should have a single, clear responsibility
  2. Use descriptive variable names for save_result_as
  3. Consider error handling for each step (stop, continue, or retry)
  4. Branch conditions should cover all cases
  5. Order steps logically with proper dependencies
  6. Use strict_dependencies for workflows with large/verbose outputs
  7. Explicitly declare dependencies to minimize context and improve performance`,
          inputSchema: zodToJsonSchema(CreateWorkflowSchema),
        },