MCP Workflow Server

A powerful orchestration server for the Model Context Protocol (MCP) that enables chaining multiple MCP tool calls into unified workflows.

Overview

MCP Workflow Server allows you to:

Chain multiple MCP tool calls into sequential workflows
Save and reuse workflows as templates for common tasks
Use JSONPath expressions to pass data between workflow steps
Support conditional execution with if/else logic
Manage multiple MCP servers from a single orchestration point

Features

🔗 Workflow Orchestration: Chain multiple MCP tool calls with data flow between steps
📦 Workflow Templates: Save and reuse common workflow patterns
🔀 Data Transformation: Use JSONPath expressions to extract and transform data between steps
⚡ Conditional Logic: Execute steps conditionally based on previous results
🌐 Multiple Transports: Support for both stdio and SSE (Server-Sent Events) transports
🔄 Hot Reload: Automatic configuration reloading when config files change
📊 Comprehensive Logging: Detailed execution logs for debugging

Installation

npm install
npm run build

Quick Start

1. Configure MCP Servers

Create a config.json file (use config.example.json as a template):

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "crawl4ai": {
      "type": "sse",
      "url": "http://localhost:11235/mcp/sse"
    }
  }
}

2. Start the Server

Stdio Mode (default): ``bash npm start ``

SSE Mode: ```bash npm run start:sse

or

TRANSPORT_TYPE=sse PORT=3001 npm start ```

Custom Workflows Path: ```bash

Use custom workflows file

npm start -- --workflows ./custom-workflows.json

Or with full options

node dist/main.js --config ./config.json --workflows ./my-workflows.json --transport sse --port 3001 ```

3. Use the Workflow Tools

The server provides three main tools:

`get_workflows`

Lists all available workflow templates: ``json { "tool": "get_workflows", "arguments": {} } ``

`execute_workflow`

Executes a workflow with initial inputs: ``json { "tool": "execute_workflow", "arguments": { "workflow_spec": { "description": "Search GitLab and open first result", "steps": [ { "server_name": "gitlab", "tool_name": "search_repositories", "outputs": { "url": "$.items[0].web_url" } }, { "server_name": "playwright", "tool_name": "browser_navigate", "inputs": { "url": "$.url" } } ] }, "initial_workflow_inputs": { "search": "react" } } } ``

`add_workflow`

Saves a new workflow template: ``json { "tool": "add_workflow", "arguments": { "name": "search_and_browse", "workflow_spec": { "description": "Search GitLab repositories and open the first result in browser", "steps": [...] } } } ``

Workflow Specification

Basic Structure

{
  "description": "Clear description of what the workflow does",
  "steps": [
    {
      "server_name": "target_mcp_server",
      "tool_name": "tool_to_call",
      "if": "optional_condition",
      "inputs": {
        "param1": "$.path.to.data",
        "param2": "static_value"
      },
      "outputs": {
        "variable_name": "$.result.path"
      }
    }
  ]
}

Step Properties

server_name (required): Name of the MCP server to call
tool_name (required): Name of the tool to invoke
if (optional): Boolean condition for conditional execution
inputs (optional): Input parameters with JSONPath expressions or static values
outputs (optional): Output mappings using JSONPath expressions

JSONPath Examples

Extract data from previous step results:

{
  "inputs": {
    "url": "$.items[0].web_url",           // First item's URL
    "names": "$.users[*].name",            // All user names
    "count": "$.items.length",             // Array length
    "first_user": "$.users[0]"             // First user object
  }
}

Conditional Execution

{
  "server_name": "some_server",
  "tool_name": "conditional_tool",
  "if": "items.length > 0",
  "inputs": {
    "data": "$.items[0]"
  }
}

Example Workflows

1. Search and Browse Workflow

{
  "search_and_browse": {
    "description": "Search GitLab repositories and open the first result in browser",
    "steps": [
      {
        "server_name": "gitlab",
        "tool_name": "search_repositories",
        "outputs": {
          "url": "$.items[0].web_url",
          "name": "$.items[0].name"
        }
      },
      {
        "server_name": "playwright",
        "tool_name": "browser_navigate",
        "inputs": {
          "url": "$.url"
        }
      }
    ]
  }
}

2. Web Scraping and Analysis

{
  "scrape_and_analyze": {
    "description": "Scrape a webpage and analyze its content",
    "steps": [
      {
        "server_name": "crawl4ai",
        "tool_name": "md",
        "outputs": {
          "content": "$.markdown"
        }
      },
      {
        "server_name": "analysis_server",
        "tool_name": "analyze_text",
        "inputs": {
          "text": "$.content"
        }
      }
    ]
  }
}

Configuration

Server Configuration

{
  "mcpServers": {
    "server_name": {
      "command": "path/to/executable",
      "args": ["arg1", "arg2"],
      "type": "stdio",
      "env": {
        "ENV_VAR": "value"
      },
      "disabled": false
    }
  }
}

Workflows Configuration

By default, workflows are stored in workflows.json in the current working directory. You can specify a custom path using the --workflows option:

# Use custom workflows file
node dist/main.js --workflows /path/to/my-workflows.json

# Relative path
node dist/main.js --workflows ./config/workflows.json

The workflows file structure remains the same regardless of location:

{
  "workflow_name": {
    "description": "Description of what the workflow does",
    "steps": [
      {
        "server_name": "server_name",
        "tool_name": "tool_name",
        "inputs": { "param": "value" },
        "outputs": { "result": "$.path" }
      }
    ]
  }
}

Transport Types

stdio: Standard input/output communication
sse: Server-Sent Events over HTTP
streamhttp: HTTP streaming

Configuration Options

command: Executable path (for stdio)
args: Command line arguments
type: Transport type (stdio, sse, streamhttp)
url: Server URL (for sse/streamhttp)
env: Environment variables
disabled: Skip server initialization

Command Line Options

node dist/main.js [options]

Options:
  -c, --config     Path to configuration file (default: config.json)
  -j, --jsonpath   JSONPath expression to select config section
  -w, --workflows  Path to workflows JSON file (default: workflows.json)
  -t, --transport  Transport type: stdio, sse (default: stdio)
  -p, --port       Port for SSE transport (default: 3001)
  -h, --help       Show help

Development

Project Structure

src/
├── main.ts              # CLI entry point
├── server.ts            # MCP server implementation
├── types.ts             # TypeScript type definitions
├── configLoader.ts      # Configuration loading and watching
├── mcpClient.ts         # MCP client management
├── workflowExecutor.ts  # Workflow execution engine
├── workflowLoader.ts    # Workflow template loading
└── workflowManager.ts   # Workflow CRUD operations

Development Scripts

npm run dev      # Run in development mode with hot reload
npm run watch    # Watch mode with automatic restart
npm run build    # Build TypeScript to JavaScript
npm start        # Start production server

Adding New Features

Extend Types: Add new interfaces in src/types.ts
Update Server: Register new tools in src/server.ts
Implement Logic: Add business logic in appropriate modules
Test: Create test workflows in workflows.json

Troubleshooting

Common Issues

Server not found: Check config.json server configuration
Tool call failed: Verify tool name and arguments
JSONPath errors: Validate JSONPath expressions
Permission denied: Check file permissions and environment variables

Debug Mode

Enable detailed logging: ``bash DEBUG=* npm start ``

Configuration Validation

The server validates:

Workflow structure and required fields
Server availability and tool existence
JSONPath expression syntax
Conditional logic expressions

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues and questions:

Check the troubleshooting section
Review example configurations
Open an issue on GitHub

MCP Workflow Server