\n\n[](https://github.com/cyanheads/workflows-mcp-server/releases/latest/download/workflows-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=workflows-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvd29ya2Zsb3dzLW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22workflows-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fworkflows-mcp-server%22%5D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nFive tools covering the full workflow library lifecycle — discovery, retrieval, creation, and deletion for both permanent and temporary workflows:\n\n| Tool | Description |\n|:-----|:------------|\n| `workflow_list` | List all permanent workflows in the index, with optional keyword, category, and tag filters. |\n| `workflow_get` | Retrieve a complete workflow definition by name, with global instructions prepended. |\n| `workflow_create` | Write a new permanent workflow YAML to the library. |\n| `workflow_create_temp` | Write a temporary one-shot workflow, indexed but excluded from list results. |\n| `workflow_delete` | Permanently remove a permanent workflow by name and optional version. |\n\n### `workflow_list`\n\nList permanent workflows from the in-memory index.\n\n- Optional keyword `query` filter (case-insensitive substring across workflow name and description)\n- Optional category filter (case-insensitive substring match)\n- Optional tag filter (AND match — all listed tags must be present)\n- Set `includeTools: true` to surface the unique `server/tool` pairs used across each workflow's steps\n- Temporary workflows are excluded; results sorted by name then version descending\n- Empty results echo the applied filters with a hint to broaden\n\n---\n\n### `workflow_get`\n\nRetrieve a complete workflow by name, including the global instructions document.\n\n- Semver-aware: omit `version` to get the highest available match; specify a version for an exact lookup\n- Returns the full workflow YAML structure with all steps and metadata\n- Injects the `global_instructions.md` content as `globalInstructions` — apply these when executing the workflow; `null` when the file is absent\n- Temporary workflows are accessible here even though excluded from `workflow_list`\n- Template placeholders (`{{input.foo}}`, `{{steps.X.output.Y}}`) are returned verbatim — the server never interpolates them\n\n---\n\n### `workflow_create`\n\nWrite a new permanent workflow to the library.\n\n- Workflow stored at `categories//--workflow.yaml` — one file per `name@version`, so multiple versions coexist\n- Rejects if `name@version` already exists — bump the version to create a new revision\n- Server stamps `created_date` and `last_updated_date` automatically\n- Index and snapshot rebuilt after write; filesystem watcher also fires (idempotent, debounced)\n\n---\n\n### `workflow_create_temp`\n\nWrite a throwaway workflow to the `temp/` directory.\n\n- No conflict check — temp workflows are intentionally ephemeral and overwriteable\n- Indexed and accessible via `workflow_get` but excluded from `workflow_list` results\n- Useful for one-shot plans, short-lived scaffolding, or session-specific orchestration steps\n\n---\n\n### `workflow_delete`\n\nPermanently remove a permanent workflow from the library.\n\n- Semver-aware: omit `version` to delete the highest available match; specify a version to target one exactly\n- Only permanent workflows can be deleted — temporary workflows are rejected (they expire on their own)\n- Irreversible: the file is removed and the workflow no longer appears in `workflow_list` or `workflow_get`\n\n---\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nWorkflow library:\n\n- In-memory index keyed by `name@version`, built at startup from `workflows-yaml/categories/` recursively\n- Semver-aware lookup — latest version returned when version is omitted\n- Filesystem watcher (Node.js `fs.watch` recursive) rebuilds the index on any add/change/remove; debounced to avoid thrash\n- YAML validated at index time — invalid files are skipped and logged, never crash the server\n- `_index.json` snapshot written on every rebuild for external tooling and debugging\n- Configurable `WORKFLOWS_DIR`, `GLOBAL_INSTRUCTIONS_PATH`, and debounce interval\n\nAgent-friendly output:\n\n- `workflow_get` always includes `globalInstructions` alongside the workflow — no second call needed\n- Discriminated `source` field (`permanent` | `temp`) on every `workflow_get` response\n- Typed error contracts with structured `reason` codes (`not_found`, `version_not_found`, `already_exists`, `temp_not_allowed`, `index_unavailable`) so callers can branch on error type rather than parsing messages\n- `workflow_list` with `includeTools: true` surfaces all MCP server/tool dependencies at a glance\n\n---\n\n## Getting started\n\nNo API keys required. The server reads from a local `workflows-yaml/` directory by default.\n\nAdd the following to your MCP client configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"workflows-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/workflows-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"WORKFLOWS_DIR\": \"/absolute/path/to/your/workflows-yaml\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"workflows-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/workflows-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"WORKFLOWS_DIR\": \"/absolute/path/to/your/workflows-yaml\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"workflows-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"-v\", \"/absolute/path/to/your/workflows-yaml:/workflows-yaml\",\n \"-e\", \"WORKFLOWS_DIR=/workflows-yaml\",\n \"ghcr.io/cyanheads/workflows-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Seed workflows\n\nThe repository ships a `workflows-yaml/` directory with example workflows organized under `categories/`. These are ready to use as a starting point. The `workflows-yaml/global_instructions.md` file contains instructions the server prepends to every `workflow_get` response — edit it to set global guidance for your agent.\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- A local directory containing YAML workflow files (or use the bundled `workflows-yaml/` seed).\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/workflows-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd workflows-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env if needed — most settings have defaults\n```\n\n---\n\n## Configuration\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `WORKFLOWS_DIR` | Absolute or relative path to the workflows root directory. | `./workflows-yaml` |\n| `GLOBAL_INSTRUCTIONS_PATH` | Path to the global instructions markdown file. Derives from `WORKFLOWS_DIR` when not set. | `/global_instructions.md` |\n| `WATCHER_DEBOUNCE_MS` | Milliseconds to debounce filesystem change events before rebuilding the index. | `500` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n---\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t workflows-mcp-server .\ndocker run --rm \\\n -v /path/to/workflows-yaml:/workflows-yaml \\\n -e WORKFLOWS_DIR=/workflows-yaml \\\n -p 3010:3010 \\\n workflows-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/workflows-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n---\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools and inits the workflow index service. |\n| `src/config/` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools/` | Tool definitions (`*.tool.ts`). |\n| `src/services/workflow-index/` | `WorkflowIndexService` — YAML parsing, index build, watcher, semver lookup, write helpers. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n| `workflows-yaml/` | Seed workflow library — `categories/` for permanent workflows, `temp/` for throwaway ones, `global_instructions.md` for agent-global guidance. |\n\n---\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging\n- Register new tools via the barrel in `src/mcp-server/tools/definitions/index.ts`\n- Filesystem operations go through `WorkflowIndexService`, not directly in tool handlers\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n---\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n",
"bytes": 12389,
"sha": "e563fb0c94659f3a5dec7fb229097ea6ef3fea393f178ef78e87f944c7e64186",
"repo_slug": "cyanheads/workflows-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_workflows_mcp_server_7acc242c/readme"
}