{"id":29654423,"url":"https://github.com/cyanheads/workflows-mcp-server","last_synced_at":"2026-04-18T01:34:39.504Z","repository":{"id":300354085,"uuid":"1001430600","full_name":"cyanheads/workflows-mcp-server","owner":"cyanheads","description":"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.","archived":false,"fork":false,"pushed_at":"2025-07-22T11:34:18.000Z","size":347,"stargazers_count":23,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-19T14:34:25.046Z","etag":null,"topics":["agent-automation","ai-agents","mcp","mcp-server","modelcontextprotocol","workflow","workflow-automation"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/workflows-mcp-server","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyanheads.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"cyanheads","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"cyanheads","thanks_dev":null,"custom":null}},"created_at":"2025-06-13T11:15:52.000Z","updated_at":"2025-09-29T18:08:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"689465fc-0e06-47c5-ab58-2424e8bcf6a5","html_url":"https://github.com/cyanheads/workflows-mcp-server","commit_stats":null,"previous_names":["cyanheads/workflows-mcp-server"],"tags_count":2,"template":false,"template_full_name":"cyanheads/mcp-ts-template","purl":"pkg:github/cyanheads/workflows-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Fworkflows-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Fworkflows-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Fworkflows-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Fworkflows-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyanheads","download_url":"https://codeload.github.com/cyanheads/workflows-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Fworkflows-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31953515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"ssl_error","status_checked_at":"2026-04-18T00:39:20.671Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-automation","ai-agents","mcp","mcp-server","modelcontextprotocol","workflow","workflow-automation"],"created_at":"2025-07-22T07:31:35.029Z","updated_at":"2026-04-18T01:34:39.498Z","avatar_url":"https://github.com/cyanheads.png","language":"TypeScript","readme":"# MCP Workflow Orchestration Server\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)\n[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://modelcontextprotocol.io/)\n[![Version](https://img.shields.io/badge/Version-1.0.5-blue.svg)](./CHANGELOG.md)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Status](https://img.shields.io/badge/Status-Active-green.svg)](https://github.com/cyanheads/workflows-mcp-server/issues)\n[![GitHub](https://img.shields.io/github/stars/cyanheads/workflows-mcp-server?style=social)](https://github.com/cyanheads/workflows-mcp-server)\n\n**Empower your AI agents with a powerful, declarative workflow engine.**\n\nAn 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.\n\nBuilt 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.\n\n## 🚀 Core Capabilities: Workflow Tools 🛠️\n\nThis server equips your AI with specialized tools to interact with the workflow engine:\n\n| Tool Name                                                                         | Description                                                                 | Key Features                                                                                                                                                                              |\n| :-------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [`workflow_return_list`](./src/mcp-server/tools/workflowLister/)                  | Discovers and lists available workflows.                                    | - `category`: Filter by a specific category.\u003cbr/\u003e- `tags`: Filter by a list of tags.\u003cbr/\u003e- `includeTools`: Optionally include a list of tools used in each workflow.                      |\n| [`workflow_get_instructions`](./src/mcp-server/tools/workflowInstructionsGetter/) | Retrieves the complete definition for a single workflow.                    | - `name`: The exact name of the workflow.\u003cbr/\u003e- `version`: The specific version to retrieve (defaults to latest).\u003cbr/\u003e- Dynamically injects global instructions for consistent execution. |\n| [`workflow_create_new`](./src/mcp-server/tools/workflowCreator/)                  | Creates a new, permanent workflow YAML file.                                | - Takes a structured JSON object matching the workflow schema.\u003cbr/\u003e- Automatically categorizes and re-indexes workflows.                                                                  |\n| [`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.\u003cbr/\u003e- Can be passed to other agents by name.                                                                                     |\n\n---\n\n## Table of Contents\n\n| [Overview](#overview) | [Features](#features) | [Installation](#installation) |\n| [Configuration](#configuration) | [Project Structure](#project-structure) |\n| [Tools](#tools) | [Development](#development) | [License](#license) |\n\n## Overview\n\nThe 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.\n\nIt'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.\n\nInstead of hard-coding multi-step logic, your tools can leverage this server to:\n\n- **Automate complex processes**: Define a sequence of tool calls in a simple YAML file and execute it with a single command.\n- **Promote reusability**: Create a library of common workflows that can be used across different agents and applications.\n- **Improve agent reliability**: Provide agents with a clear, structured plan to follow, reducing errors and improving predictability.\n- **Dynamically guide agent behavior**: Use global instructions to provide up-to-date, high-level strategy to all workflows without modifying them individually.\n\n\u003e **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.\n\n## Features\n\n### Core Utilities\n\nLeverages the robust utilities provided by the `mcp-ts-template`:\n\n- **Logging**: Structured, configurable logging with sensitive data redaction.\n- **Error Handling**: Centralized error processing and standardized error types (`McpError`).\n- **Configuration**: Environment variable loading (`dotenv`) with comprehensive validation using Zod.\n- **Input Validation/Sanitization**: Uses `zod` for schema validation.\n- **Request Context**: Tracking and correlation of operations via unique request IDs.\n- **Type Safety**: Strong typing enforced by TypeScript and Zod schemas.\n- **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management and robust authentication.\n- **Authentication**: Modular authentication layer supporting JWT and OAuth 2.1.\n\n### Workflow Engine\n\n- **YAML-based Workflows**: Define complex, multi-step workflows in a simple, human-readable format.\n- **Dynamic Indexing**: Automatically discovers and indexes all workflow files on startup and watches for changes.\n- **Global Instructions**: Dynamically injects a central set of instructions into every workflow, allowing for global strategy updates.\n- **Temporary Workflows**: Create \"hidden\" workflows on the fly for complex tasks or for passing structured plans between agents.\n\n## Installation\n\n### Prerequisites\n\n- [Node.js (\u003e=20.0.0)](https://nodejs.org/)\n- [npm](https://www.npmjs.com/) (comes with Node.js)\n\n### MCP Client Settings\n\nAdd 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"workflows-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"workflows-mcp-server\"],\n      \"env\": {\n        \"MCP_LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\n## If running manually (not via MCP client) for development or testing\n\n### Install via npm\n\n```bash\nnpm install workflows-mcp-server\n```\n\n### Alternatively Install from Source\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/cyanheads/workflows-mcp-server.git\n   cd workflows-mcp-server\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   npm install\n   ```\n\n3. Build the project:\n   ```bash\n   npm run build\n   ```\n\n## Configuration\n\n### Environment Variables\n\nConfigure the server using environment variables. These can be set in a `.env` file or directly in your shell.\n\n| Variable              | Description                                                                      | Default       |\n| :-------------------- | :------------------------------------------------------------------------------- | :------------ |\n| `MCP_TRANSPORT_TYPE`  | Transport mechanism: `stdio` or `http`.                                          | `stdio`       |\n| `MCP_HTTP_PORT`       | Port for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                         | `3010`        |\n| `MCP_HTTP_HOST`       | Host address for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                 | `127.0.0.1`   |\n| `MCP_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`). | (none)        |\n| `MCP_LOG_LEVEL`       | Logging level (`debug`, `info`, `warning`, `error`).                             | `debug`       |\n| `MCP_AUTH_MODE`       | Authentication mode for HTTP: `jwt` or `oauth`.                                  | `jwt`         |\n| `MCP_AUTH_SECRET_KEY` | **Required for `jwt` auth in production.** Minimum 32-character secret key.      | (none)        |\n| `NODE_ENV`            | Runtime environment (`development`, `production`).                               | `development` |\n\n## Project Structure\n\nThe codebase follows a modular structure within the `src/` directory:\n\n```\nsrc/\n├── index.ts              # Entry point: Initializes and starts the server\n├── config/               # Configuration loading (env vars, package info)\n│   └── index.ts\n├── mcp-server/           # Core MCP server logic and capability registration\n│   ├── server.ts         # Server setup, capability registration\n│   ├── transports/       # Transport handling (stdio, http)\n│   └── tools/            # MCP Tool implementations (subdirs per tool)\n├── services/             # External service integrations\n│   └── workflow-indexer/ # Discovers and indexes workflow YAML files\n├── types-global/         # Shared TypeScript type definitions\n└── utils/                # Common utility functions (logger, error handler, etc.)\n```\n\nFor a detailed file tree, run `npm run tree` or see [docs/tree.md](docs/tree.md).\n\n## Tools\n\nThe server provides a suite of tools for managing and executing workflows.\n\n| Tool Name                   | Description                             | Key Arguments                         |\n| :-------------------------- | :-------------------------------------- | :------------------------------------ |\n| `workflow_return_list`      | Lists available workflows.              | `category?`, `tags?`, `includeTools?` |\n| `workflow_get_instructions` | Retrieves a workflow definition.        | `name`, `version?`                    |\n| `workflow_create_new`       | Creates a new, permanent workflow.      | A structured JSON object.             |\n| `workflow_create_temporary` | Creates a temporary, unlisted workflow. | A structured JSON object.             |\n\n## Development\n\n### Build and Test\n\n```bash\n# Build the project (compile TS to JS in dist/ and make executable)\nnpm run build\n\n# Test the server locally using the MCP inspector tool (stdio transport)\nnpm run inspector\n\n# Clean build artifacts\nnpm run clean\n\n# Generate a file tree representation for documentation\nnpm run tree\n\n# Clean build artifacts and then rebuild the project\nnpm run rebuild\n\n# Format code with Prettier\nnpm run format\n\n# Start the server using stdio (default)\nnpm start\n\n# Start the server using HTTP transport\nnpm run start:http\n```\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\nBuilt with the \u003ca href=\"https://modelcontextprotocol.io/\"\u003eModel Context Protocol\u003c/a\u003e\n\u003c/div\u003e\n","funding_links":["https://github.com/sponsors/cyanheads","https://buymeacoffee.com/cyanheads"],"categories":["📚 Projects (1974 total)"],"sub_categories":["MCP Servers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyanheads%2Fworkflows-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyanheads%2Fworkflows-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyanheads%2Fworkflows-mcp-server/lists"}