workflows-mcp-server

---

概述

一个由本地 YAML 文件支持的声明式工作流库，适用于大模型 Agent。存储、列出和检索命名且带版本的多步骤手册——每个手册都是一系列 MCP 服务/工具调用——供长期复用或一次性临时运行。系统会自动检测 YAML 文件的修改。

工具

工具	描述
workflow_list	列出索引中的所有永久工作流，可按关键词、类别和标签筛选。
workflow_get	按名称检索完整工作流定义，并在前面附加全局指令。
workflow_create	将新的永久工作流 YAML 写入库中。
workflow_create_temp	写入临时工作流草稿并将其编入索引，但不纳入列表结果；该草稿会保留至删除。
workflow_delete	按名称和可选版本删除永久工作流或临时草稿；删除前需由用户确认已解析的目标。

功能参考

workflow_list _工具

• 可选的 query（名称和描述）、category（子串）和 tags（必须全部匹配）筛选条件均不区分大小写；临时草稿不会列出
• 按名称排序，同名时按版本从高到低排序；结果为空时会附带 notice，回显已应用的筛选条件
• 设置 includeTools: true 后，会添加每个工作流中唯一的 server/tool 对

---

workflow_get _工具

• 使用 name 和可选的 semver version；省略 version 时返回可用的最高版本，包含草稿
• 返回完整工作流、其 source（permanent 或 temp），以及来自 global_instructions.md 的 globalInstructions（文件不存在时为 null）；失败时返回 not_found 或 version_not_found
• 模板占位符（如 {{input.foo}}）会原样返回——服务端不会对其进行插值

---

workflow_create _工具

• name、语义化版本 version、description、author、category 和 steps（以及可选的 tags）；每个 name@version 存储为 categories/<category>/ 下的一个文件，并记录创建和更新日期
• 返回 key（name@version）和 filePath；如果永久工作流或草稿已占用该键，则失败并返回 already_exists，也可能返回 invalid_input 或 write_failed

---

workflow_create_temp _工具

• 包含 workflow_create 的字段，但不含 category；存储在 temp/ 下，可通过 workflow_get 获取，从不列出，并一直保留到 workflow_delete 将其删除
• status 为 created；若替换了同一键的草稿，则为 overwritten（并保留该草稿的 created_date）；如果永久工作流已占用该键，则失败并返回 already_exists

---

workflow_delete _工具

• name，以及可选的 version（省略时，取永久工作流和草稿中的最高版本）；用户必须确认解析出的 name@version、来源和文件，然后才会执行删除，因此不支持征询的客户端无法删除
• 返回已删除工作流的 source；如果另一个声明相同键的文件现在取代了它，则还会返回 notice；可能因 cancelled、confirmation_invalid（从未发出提示、已答复、超过 10 分钟，或由另一个调用方发出）、target_changed（用户查看后文件或其内容发生了变化）或 not_found 而失败

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、结构化日志记录和可选的 OpenTelemetry 跟踪。

工作流库：

• categories/ 和 temp/ 下的 YAML 文件会在建立索引时进行验证；无效文件会被跳过并记录日志，不会导致服务崩溃
• 内存索引以 name@version 为键，从各文件内容而非文件名读取数据，并通过经过防抖处理的递归监视器保持最新；同一键对应的永久工作流优先于草稿
• 版本在所有地方都采用规范的 semver：会去掉前导 v、首尾空格和构建元数据，因此 v1.0.0+build.5 会以 1.0.0 存储、作为键并用于查找
• 创建和删除操作依次执行，因此每次存在性检查都会持续到写入完成；文件名包含 name@version 的哈希值，因此 slug 相同的键不会共用文件
• 每次重建索引时都会写入 _index.json 快照，供外部工具使用和调试

便于 Agent 使用的输出：

• 区分明确的输出 — 每个 workflow_get 响应都包含 source: "permanent" | "temp"，失败时会返回类型化的 reason 代码（not_found、version_not_found、already_exists、cancelled、confirmation_invalid、target_changed、index_unavailable、…），调用方可依据数据分支，而不必解析错误字符串
• 无需额外往返 — workflow_get 始终在同一响应中连同工作流定义一起返回 globalInstructions
• 响应整形 — workflow_list 的可选 includeTools 标志会预先导出工作流使用的唯一 server/tool 对；如果结果为空，则会返回已应用的筛选条件和扩大筛选范围的提示，而非空响应

---

开始使用

无需 API 密钥。默认情况下，服务会从本地 workflows-yaml/ 目录读取数据。

将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "workflows-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/workflows-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "WORKFLOWS_DIR": "/absolute/path/to/your/workflows-yaml"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "workflows-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/workflows-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "WORKFLOWS_DIR": "/absolute/path/to/your/workflows-yaml"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "workflows-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-v", "/absolute/path/to/your/workflows-yaml:/workflows-yaml",
        "-e", "WORKFLOWS_DIR=/workflows-yaml",
        "ghcr.io/cyanheads/workflows-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

初始化工作流

仓库附带一个 workflows-yaml/ 目录，其中包含按 categories/ 组织的示例工作流，可直接用作起点。workflows-yaml/global_instructions.md 文件包含服务在每个 workflow_get 响应前置的指令 — 编辑该文件即可为 Agent 设置全局指导。

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 一个包含 YAML 工作流文件的本地目录（或使用捆绑的 workflows-yaml/ 示例数据）。

安装

1. 克隆仓库：

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

2. 进入目录：

cd workflows-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if needed — most settings have defaults

---

配置

变量	描述	默认值
WORKFLOWS_DIR	工作流根目录的绝对或相对路径。	./workflows-yaml
GLOBAL_INSTRUCTIONS_PATH	全局说明 Markdown 文件的路径。未设置时根据 WORKFLOWS_DIR 推导。	<WORKFLOWS_DIR>/global_instructions.md
WATCHER_DEBOUNCE_MS	文件系统变更事件触发索引重建前的防抖时间，单位为毫秒（0–2147483647）。	500
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_SESSION_MODE	HTTP 会话：auto 或 stateful。workflow_delete 的确认提示词需要活动会话，因此使用 stateless 启动 HTTP 会导致配置错误。使用 stdio 时忽略此项。	stateful，在 src/index.ts 中声明
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_REQUEST_STATE_KEY	用于密封确认轮次携带的 requestState（≥ 32 字节，每个实例必须相同，例如 openssl rand -base64 32）；服务器未密封的任何状态都会在处理程序运行前被拒绝。workflow_delete 的轮次携带其确认 ID，因此 HTTP 部署时请设置此项。	未设置
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败工具调用的参数和结果，按键名脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）字节。自由格式值中的密钥不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩（跨度、指标、完成日志）。	false

完整的可选覆盖项列表请参见 .env.example。

---

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t workflows-mcp-server .
docker run --rm \
  -v /path/to/workflows-yaml:/workflows-yaml \
  -e WORKFLOWS_DIR=/workflows-yaml \
  -p 3010:3010 \
  workflows-mcp-server

Dockerfile 默认使用 HTTP 传输、有状态会话模式（必需，见上文的 MCP_SESSION_MODE），并将日志写入 /var/log/workflows-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

---

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具并初始化工作流索引服务。
src/config/	使用 Zod 解析并验证服务专用环境变量。
src/mcp-server/tools/	工具定义（*.tool.ts）。
src/services/workflow-index/	WorkflowIndexService——YAML 解析、索引构建、监视器、semver 查找、写入辅助函数。
tests/	与 src/ 对应的单元测试和集成测试。
workflows-yaml/	示例工作流库——categories/ 用于永久工作流，temp/ 用于临时草稿，global_instructions.md 用于面向 Agent 的全局指导。

---

开发指南

开发指南和架构规则请参见 CLAUDE.md。简要概括如下：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志
• 通过 src/mcp-server/tools/definitions/index.ts 中的 barrel 文件注册新工具
• 文件系统操作应通过 WorkflowIndexService 执行，不要直接写在工具处理程序中

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache-2.0——详情请参见 LICENSE。