# 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

```bash
npm install
npm run build
```

## Quick Start

### 1. Configure MCP Servers

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

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

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

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

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

## Example Workflows

### 1. Search and Browse Workflow

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

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

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

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

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

```bash
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

```bash
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:
```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

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