mcp-workflow-server

slzcdhd/mcp-workflow-server

3.2

If you are the rightful owner of mcp-workflow-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Workflow Server is a robust orchestration server designed for the Model Context Protocol (MCP), enabling the integration and management of multiple MCP tool calls into cohesive workflows.

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