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):

npm start

SSE Mode:

npm run start:sse
# or
TRANSPORT_TYPE=sse PORT=3001 npm start

Custom Workflows Path:

# 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:

{
  "tool": "get_workflows",
  "arguments": {}
}

execute_workflow

Executes a workflow with initial inputs:

{
  "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:

{
  "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

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

Troubleshooting

Common Issues

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

Debug Mode

Enable detailed logging:

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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

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