Supports workflows for code review and analysis from Git repositories.
Available on GitHub for source code access and contributions.
Available as an npm package for easy installation and integration into existing projects.
Provides full TypeScript support with type-safe workflow definitions and execution.
Incorporates Zod validation for ensuring workflow integrity and type safety throughout the execution process.
workflows-mcp
🤖 Co-authored with - 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)
From npm
From Source
🏃 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):
Using global install:
Using local build:
Development Mode
For development with hot reload:
📖 Workflow Structure
Workflows are JSON documents that define a series of steps for an LLM to execute:
🎯 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 instructionsExecute the step following the provided instructions
Continue to next step with
run_workflow_step
, passing:The
execution_id
from start_workflowAny
step_result
from the current stepnext_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:
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 variablesUnchanged 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 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
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:
🏗️ Architecture
🧪 Development
📝 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
andrun_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
Core workflow engine
Basic action types
Workflow validation
Example workflows
Step-by-step execution
Variable interpolation
Branching logic
Import/export system
Advanced error handling and retry logic
Loop and parallel execution
Workflow marketplace
Visual workflow builder
Performance optimizations
Workflow versioning and rollback
🤝 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.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A Model Context Protocol implementation that enables LLMs to execute complex, multi-step workflows combining tool usage with cognitive reasoning, providing structured, reusable paths through tasks with advanced control flow.
- 🌟 Overview
- 🚀 Key Features
- 📦 Installation
- 🏃 Configuration
- 📖 Workflow Structure
- 🎯 Action Types
- 🛠️ Available Tools
- 🔄 Step-by-Step Execution
- 🎯 Dependency Management & Performance Optimization
- 📚 Example Workflows
- 📁 Manual Workflow Import
- 🏗️ Architecture
- 🧪 Development
- 📝 Changelog
- 🔮 Roadmap
- 🤝 Contributing
- 📄 License
- 🙏 Acknowledgments
Related MCP Servers
- -securityAlicense-qualityA comprehensive toolkit that enhances LLM capabilities through the Model Context Protocol, allowing LLMs to interact with external services including command-line operations, file management, Figma integration, and audio processing.Last updated -24Apache 2.0
- -securityFlicense-qualityAllows LLM tools like Claude Desktop and Cursor AI to access and summarize code files through a Model Context Protocol server, providing structured access to codebase content without manual copying.Last updated -2
- -securityAlicense-qualityA Model Context Protocol (MCP) server that implements AI-First Development framework principles, allowing LLMs to interact with context-first documentation tools and workflows for preserving knowledge and intent alongside code.Last updated -337AGPL 3.0
- -securityFlicense-qualityTypeScript implementation of the Model Context Protocol that standardizes how LLMs connect to data sources and tools, eliminating vendor lock-in and simplifying AI integration.Last updated -52