workflows-mcp

🤖 Co-authored with Claude Code - Building workflows so LLMs can finally follow a recipe without burning the kitchen! 🔥

A powerful Model Context Protocol (MCP) implementation that enables LLMs to execute complex, multi-step workflows with cognitive actions and tool integrations.

🌟 Overview

workflows-mcp transforms how AI assistants handle complex tasks by providing structured, reusable workflows that combine tool usage with cognitive reasoning. Instead of ad-hoc task execution, workflows provide deterministic, reproducible paths through multi-step processes.

🚀 Key Features

📋 Structured Workflows: Define clear, step-by-step instructions for LLMs
🧠 Cognitive Actions: Beyond tool calls - analyze, consider, validate, and reason
🔀 Advanced Control Flow: Branching, loops, parallel execution
💾 State Management: Track variables and results across workflow steps
🔍 Comprehensive Validation: Ensure workflow integrity before execution
📊 Execution Tracking: Monitor success rates and performance metrics
🛡️ Type-Safe: Full TypeScript support with Zod validation
🎯 Dependency Management: Control variable visibility to reduce token usage
⚡ Performance Optimized: Differential updates and progressive step loading

📦 Installation

Using npx (recommended)

npx @fiveohhwon/workflows-mcp

From npm

npm install -g @fiveohhwon/workflows-mcp

From Source

git clone https://github.com/FiveOhhWon/workflows-mcp.git
cd workflows-mcp
npm install
npm run build

🏃 Configuration

Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (recommended):

{
  "mcpServers": {
    "workflows": {
      "command": "npx",
      "args": ["-y", "@fiveohhwon/workflows-mcp"]
    }
  }
}

Using global install:

{
  "mcpServers": {
    "workflows": {
      "command": "workflows-mcp"
    }
  }
}

Using local build:

{
  "mcpServers": {
    "workflows": {
      "command": "node",
      "args": ["/absolute/path/to/workflows-mcp/dist/index.js"]
    }
  }
}

Development Mode

For development with hot reload:

npm run dev

📖 Workflow Structure

Workflows are JSON documents that define a series of steps for an LLM to execute:

{
  "name": "Code Review Workflow",
  "description": "Automated code review with actionable feedback",
  "goal": "Perform comprehensive code review",
  "version": "1.0.0",
  "inputs": {
    "file_path": {
      "type": "string",
      "description": "Path to code file",
      "required": true
    }
  },
  "steps": [
    {
      "id": 1,
      "action": "tool_call",
      "tool_name": "read_file",
      "parameters": {"path": "{{file_path}}"},
      "save_result_as": "code_content"
    },
    {
      "id": 2,
      "action": "analyze",
      "description": "Analyze code quality",
      "input_from": ["code_content"],
      "save_result_as": "analysis"
    }
  ]
}

🎯 Action Types

Tool Actions

tool_call: Execute a specific tool with parameters

Cognitive Actions

analyze: Examine data and identify patterns
consider: Evaluate options before deciding
research: Gather information from sources
validate: Check conditions or data integrity
summarize: Condense information to key points
decide: Make choices based on criteria
extract: Pull specific information from content
compose: Generate new content

Control Flow

branch: Conditional execution paths
loop: Iterate over items or conditions
parallel: Execute multiple steps simultaneously
wait_for_input: Pause for user input

Utility Actions

transform: Convert data formats
checkpoint: Save workflow state
notify: Send updates
assert: Ensure conditions are met
retry: Attempt previous step again

🛠️ Available Tools

Workflow Management

create_workflow - Create a new workflow

{
  "workflow": {
    "name": "My Workflow",
    "description": "What it does",
    "goal": "Desired outcome",
    "steps": [...]
  }
}

list_workflows - List all workflows with filtering

{
  "filter": {
    "tags": ["automation"],
    "name_contains": "review"
  },
  "sort": {
    "field": "created_at",
    "order": "desc"
  }
}

get_workflow - Retrieve a specific workflow
```
{
  "id": "workflow-uuid"
}
```

update_workflow - Modify existing workflow

{
  "id": "workflow-uuid",
  "updates": {
    "description": "Updated description"
  },
  "increment_version": true
}

delete_workflow - Soft delete (recoverable)
```
{
  "id": "workflow-uuid"
}
```
start_workflow - Start a workflow execution session
```
{
  "id": "workflow-uuid",
  "inputs": {
    "param1": "value1"
  }
}
```
Returns execution instructions for the first step and an execution_id.

run_workflow_step - Execute the next step in the workflow

{
  "execution_id": "execution-uuid",
  "step_result": "result from previous step",
  "next_step_needed": true
}

Call this after completing each step to proceed through the workflow.

get_workflow_versions - List all available versions of a workflow
```
{
  "workflow_id": "workflow-uuid"
}
```
Returns list of all saved versions for version history tracking.

rollback_workflow - Rollback a workflow to a previous version

{
  "workflow_id": "workflow-uuid",
  "target_version": "1.0.0",
  "reason": "Reverting breaking changes"
}

Restores a previous version as the active workflow.

🔄 Step-by-Step Execution

The workflow system supports interactive, step-by-step execution similar to the sequential thinking tool:

Start a workflow with start_workflow - returns the first step instructions
Execute the step following the provided instructions
Continue to next step with run_workflow_step, passing:
- The execution_id from start_workflow
- Any step_result from the current step
- next_step_needed: true to continue (or false to end early)
Repeat until the workflow completes

Each step provides:

Clear instructions for what to do
Current variable state
Expected output format
Next step guidance

Template Variables

The workflow system supports template variable substitution using {{variable}} syntax:

In parameters: "path": "output_{{format}}.txt" → "path": "output_csv.txt"
In descriptions: "Processing {{count}} records" → "Processing 100 records"
In prompts: "Enter value for {{field}}" → "Enter value for email"
In transformations: Variables are automatically substituted

Template variables are resolved from the current workflow session variables, including:

Initial inputs provided to start_workflow
Results saved from previous steps via save_result_as
Any variables set during workflow execution

🎯 Dependency Management & Performance Optimization

The workflow system includes advanced features to minimize token usage and improve performance for complex workflows:

Dependency-Based Variable Filtering

Control which variables are visible to each step to dramatically reduce context size:

{
  "name": "Optimized Workflow",
  "strict_dependencies": true,  // Enable strict mode
  "steps": [
    {
      "id": 1,
      "action": "tool_call",
      "tool_name": "read_large_file",
      "save_result_as": "large_data"
    },
    {
      "id": 2,
      "action": "analyze",
      "input_from": ["large_data"],
      "save_result_as": "summary",
      "dependencies": []  // In strict mode, sees NO previous variables
    },
    {
      "id": 3,
      "action": "compose",
      "dependencies": [2],  // Only sees 'summary' from step 2
      "save_result_as": "report"
    },
    {
      "id": 4,
      "action": "validate",
      "show_all_variables": true,  // Override to see everything
      "save_result_as": "validation"
    }
  ]
}

Workflow-Level Settings

strict_dependencies (boolean, default: false)
- false: Steps without dependencies see all variables (backward compatible)
- true: Steps without dependencies see NO variables (must explicitly declare)

Step-Level Settings

dependencies (array of step IDs)
- Lists which previous steps' outputs this step needs
- Step only sees outputs from listed steps plus workflow inputs
- Empty array in strict mode means NO variables visible
show_all_variables (boolean)
- Override for specific steps that need full visibility
- Useful for validation or debugging steps

Performance Features

Differential State Updates: Only shows variables that changed
- + variable_name: Newly added variables
- ~ variable_name: Modified variables
- Unchanged variables are not displayed
Progressive Step Loading: Only shows next 3 upcoming steps
- Reduces context for long workflows
- Shows "... and X more steps" for remaining
Selective Variable Display: Based on dependencies
- Dramatically reduces tokens for workflows with verbose outputs
- Maintains full state internally for branching/retry

Best Practices for Token Optimization

Use strict_dependencies: true for workflows with large intermediate outputs
Explicitly declare dependencies to minimize variable visibility
Place verbose outputs early in the workflow and filter them out in later steps
Use meaningful variable names to make dependencies clear
Group related steps to minimize cross-dependencies

Example: Data Processing with Filtering

{
  "name": "Large Data Processing",
  "strict_dependencies": true,
  "inputs": {
    "file_path": { "type": "string", "required": true }
  },
  "steps": [
    {
      "id": 1,
      "action": "tool_call",
      "tool_name": "read_csv",
      "parameters": { "path": "{{file_path}}" },
      "save_result_as": "raw_data"
    },
    {
      "id": 2,
      "action": "transform",
      "transformation": "Extract key metrics only",
      "dependencies": [1],  // Only sees raw_data
      "save_result_as": "metrics"
    },
    {
      "id": 3,
      "action": "analyze",
      "criteria": "Identify trends and anomalies",
      "dependencies": [2],  // Only sees metrics, not raw_data
      "save_result_as": "analysis"
    },
    {
      "id": 4,
      "action": "compose",
      "criteria": "Create executive summary",
      "dependencies": [2, 3],  // Sees metrics and analysis only
      "save_result_as": "report"
    }
  ]
}

In this example:

Step 2 processes large raw data but only outputs key metrics
Step 3 analyzes metrics without seeing the large raw data
Step 4 creates a report from metrics and analysis only
Token usage is minimized by filtering out verbose intermediate data

📚 Example Workflows

Code Review Workflow

Analyzes code quality, identifies issues, and provides improvement suggestions.

Sample data: /workflows/examples/sample-data/sample-code-for-review.js

Data Processing Pipeline

ETL workflow with validation, quality checks, and conditional branching.

Sample data: /workflows/examples/sample-data/sample-data.csv

Research Assistant

Gathers information, validates sources, and produces comprehensive reports.

Simple File Processor

Basic example showing file operations, branching, and transformations.

See the /workflows/examples directory for complete workflow definitions.

📁 Manual Workflow Import

You can manually add workflows by placing JSON files in the imports directory:

Navigate to ~/.workflows-mcp/imports/
Place your workflow JSON files there (any filename ending in .json)
Start or restart the MCP server
The workflows will be automatically imported with:
- A new UUID assigned if missing or invalid
- Metadata created if not present
- Original files moved to imports/processed/ after successful import

Example workflow file structure:

{
  "name": "My Custom Workflow",
  "description": "A manually created workflow",
  "goal": "Accomplish something specific",
  "version": "1.0.0",
  "steps": [
    {
      "id": 1,
      "action": "tool_call",
      "description": "First step",
      "tool_name": "example_tool",
      "parameters": {}
    }
  ]
}

🏗️ Architecture

workflows-mcp/
├── src/
│   ├── types/          # TypeScript interfaces and schemas
│   ├── services/       # Core services (storage, validation)
│   ├── utils/          # Utility functions
│   └── index.ts        # MCP server implementation
├── workflows/
│   └── examples/       # Example workflows
│       └── sample-data/  # Sample data files for testing
└── tests/              # Test suite

🧪 Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

📝 Changelog

v0.3.3 (Latest)

⚡ Added dependency-based variable filtering for token optimization
✨ Added strict_dependencies workflow flag for explicit variable control
✨ Added dependencies array to steps for selective variable visibility
✨ Added show_all_variables step override for full visibility when needed
🎯 Implemented differential state updates (shows only changed variables)
📊 Added progressive step loading (shows only next 3 steps)
🐛 Fixed UUID validation error in update_workflow tool
📝 Added explicit instructions to prevent commentary during workflow execution

v0.3.0

✨ Added workflow versioning with automatic version history
✨ Added get_workflow_versions tool to list all versions
✨ Added rollback_workflow tool to restore previous versions
📁 Version history stored in ~/.workflows-mcp/versions/

v0.2.1

✨ Added template variable resolution ({{variable}} syntax)
✨ Fixed branching logic to properly handle conditional steps
✨ Enhanced create_workflow tool with comprehensive embedded documentation
🐛 Fixed ES module import issues
📁 Improved file organization with sample-data folder

v0.2.0

✨ Implemented step-by-step workflow execution
✨ Added start_workflow and run_workflow_step tools
✨ Session management for workflow state
🔄 Replaced run_workflow with interactive execution

v0.1.0

🎉 Initial release
✨ Core workflow engine
✨ 16 action types
✨ Import/export functionality
✨ Example workflows

🔮 Roadmap

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built on the Model Context Protocol specification by Anthropic.