https://github.com/cyanheads/workflows-mcp-server

Model Context Protocol server that enables AI agents to discover, create, and execute complex, multi-step workflows defined in simple YAML files. Allow your AI agents to better organize their tool usage and provide a more structured way to handle complex multi-step tasks.
https://github.com/cyanheads/workflows-mcp-server

agent-automation ai-agents mcp mcp-server modelcontextprotocol workflow workflow-automation

Last synced: 10 days ago
JSON representation

Host: GitHub
URL: https://github.com/cyanheads/workflows-mcp-server
Owner: cyanheads
License: apache-2.0
Created: 2025-06-13T11:15:52.000Z (11 months ago)
Default Branch: main
Last Pushed: 2025-07-22T11:34:18.000Z (9 months ago)
Last Synced: 2025-10-19T14:34:25.046Z (6 months ago)
Topics: agent-automation, ai-agents, mcp, mcp-server, modelcontextprotocol, workflow, workflow-automation
Language: TypeScript
Homepage: https://www.npmjs.com/package/workflows-mcp-server
Size: 339 KB
Stars: 23
Watchers: 0
Forks: 3
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

# MCP Workflow Orchestration Server

[![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://modelcontextprotocol.io/)
[![Version](https://img.shields.io/badge/Version-1.0.5-blue.svg)](./CHANGELOG.md)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Status](https://img.shields.io/badge/Status-Active-green.svg)](https://github.com/cyanheads/workflows-mcp-server/issues)
[![GitHub](https://img.shields.io/github/stars/cyanheads/workflows-mcp-server?style=social)](https://github.com/cyanheads/workflows-mcp-server)

**Empower your AI agents with a powerful, declarative workflow engine.**

An MCP (Model Context Protocol) server that allows a Large Language Model (LLM) to discover, understand, and execute complex, multi-step workflows defined in simple YAML files.

Built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template), this server follows a modular architecture with robust error handling, logging, and security features.

## 🚀 Core Capabilities: Workflow Tools 🛠️

This server equips your AI with specialized tools to interact with the workflow engine:

| Tool Name | Description | Key Features |
| :-------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`workflow_return_list`](./src/mcp-server/tools/workflowLister/) | Discovers and lists available workflows. | - `category`: Filter by a specific category.
- `tags`: Filter by a list of tags.
- `includeTools`: Optionally include a list of tools used in each workflow. |
| [`workflow_get_instructions`](./src/mcp-server/tools/workflowInstructionsGetter/) | Retrieves the complete definition for a single workflow. | - `name`: The exact name of the workflow.
- `version`: The specific version to retrieve (defaults to latest).
- Dynamically injects global instructions for consistent execution. |
| [`workflow_create_new`](./src/mcp-server/tools/workflowCreator/) | Creates a new, permanent workflow YAML file. | - Takes a structured JSON object matching the workflow schema.
- Automatically categorizes and re-indexes workflows. |
| [`workflow_create_temporary`](./src/mcp-server/tools/workflowTemporaryCreator/) | Creates a temporary workflow that is not listed, but can be called by name. | - Ideal for defining multi-step plans for complex tasks.
- Can be passed to other agents by name. |

---

## Table of Contents

## Overview

The Workflow MCP Server acts as a powerful orchestration layer that helps your LLM agents manage complex workflows. This provides a structured way to perform 'short' multi-step tasks that would otherwise require hard-coded logic or extensive manual intervention.

It's as easy as telling your LLM "Use the workflows-mcp-server to create a new workflow that does X, Y, and Z, using the current tools you currently have access to" or "Find me a workflow that can help with task A". The server will handle the rest, allowing your agents to focus on higher-level reasoning and decision-making. The temporary workflows can be used to allow your LLM agent to "collect its thoughts" and create a structured temporary plan; even the act of defining a workflow can help the agent clarify its own understanding of the task at hand and improve tool use performance.

Instead of hard-coding multi-step logic, your tools can leverage this server to:

- **Automate complex processes**: Define a sequence of tool calls in a simple YAML file and execute it with a single command.
- **Promote reusability**: Create a library of common workflows that can be used across different agents and applications.
- **Improve agent reliability**: Provide agents with a clear, structured plan to follow, reducing errors and improving predictability.
- **Dynamically guide agent behavior**: Use global instructions to provide up-to-date, high-level strategy to all workflows without modifying them individually.

> **Developer Note**: This repository includes a [.clinerules](.clinerules) file that serves as a developer cheat sheet for your LLM coding agent with quick reference for the codebase patterns, file locations, and code snippets.

## Features

### Core Utilities

Leverages the robust utilities provided by the `mcp-ts-template`:

- **Logging**: Structured, configurable logging with sensitive data redaction.
- **Error Handling**: Centralized error processing and standardized error types (`McpError`).
- **Configuration**: Environment variable loading (`dotenv`) with comprehensive validation using Zod.
- **Input Validation/Sanitization**: Uses `zod` for schema validation.
- **Request Context**: Tracking and correlation of operations via unique request IDs.
- **Type Safety**: Strong typing enforced by TypeScript and Zod schemas.
- **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management and robust authentication.
- **Authentication**: Modular authentication layer supporting JWT and OAuth 2.1.

### Workflow Engine

- **YAML-based Workflows**: Define complex, multi-step workflows in a simple, human-readable format.
- **Dynamic Indexing**: Automatically discovers and indexes all workflow files on startup and watches for changes.
- **Global Instructions**: Dynamically injects a central set of instructions into every workflow, allowing for global strategy updates.
- **Temporary Workflows**: Create "hidden" workflows on the fly for complex tasks or for passing structured plans between agents.

## Installation

### Prerequisites

- [Node.js (>=20.0.0)](https://nodejs.org/)
- [npm](https://www.npmjs.com/) (comes with Node.js)

### MCP Client Settings

Add the following to your MCP client's configuration file (e.g., `cline_mcp_settings.json`). This configuration uses `npx` to run the server, which will automatically install the package if not already present:

```json
{
"mcpServers": {
"workflows-mcp-server": {
"command": "npx",
"args": ["workflows-mcp-server"],
"env": {
"MCP_LOG_LEVEL": "info"
}
}
}
}
```

## If running manually (not via MCP client) for development or testing

### Install via npm

```bash
npm install workflows-mcp-server
```

### Alternatively Install from Source

1. Clone the repository:

```bash
git clone https://github.com/cyanheads/workflows-mcp-server.git
cd workflows-mcp-server
```

2. Install dependencies:

```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Configuration

### Environment Variables

Configure the server using environment variables. These can be set in a `.env` file or directly in your shell.

## Project Structure

The codebase follows a modular structure within the `src/` directory:

```
src/
├── index.ts # Entry point: Initializes and starts the server
├── config/ # Configuration loading (env vars, package info)
│ └── index.ts
├── mcp-server/ # Core MCP server logic and capability registration
│ ├── server.ts # Server setup, capability registration
│ ├── transports/ # Transport handling (stdio, http)
│ └── tools/ # MCP Tool implementations (subdirs per tool)
├── services/ # External service integrations
│ └── workflow-indexer/ # Discovers and indexes workflow YAML files
├── types-global/ # Shared TypeScript type definitions
└── utils/ # Common utility functions (logger, error handler, etc.)
```

For a detailed file tree, run `npm run tree` or see [docs/tree.md](docs/tree.md).

## Tools

The server provides a suite of tools for managing and executing workflows.

## Development

### Build and Test

```bash
# Build the project (compile TS to JS in dist/ and make executable)
npm run build

# Test the server locally using the MCP inspector tool (stdio transport)
npm run inspector

# Clean build artifacts
npm run clean

# Generate a file tree representation for documentation
npm run tree

# Clean build artifacts and then rebuild the project
npm run rebuild

# Format code with Prettier
npm run format

# Start the server using stdio (default)
npm start

# Start the server using HTTP transport
npm run start:http
```

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

---

Built with the Model Context Protocol

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/cyanheads/workflows-mcp-server

Awesome Lists containing this project

README