workflow-code mcp

workflow-code mcp 会把一个 projectType: "workflow" 项目启动为标准 MCP Server。项目中的每个 entrypoint 对应一个 tool；Conversation、Kanban 和普通文件夹不会暴露 MCP。

Server 名称固定为 workflow-<package.json.id>，tool 名称直接使用 entrypoint ID，标题、描述和参数来自启动时的 structure report。连接建立后工具目录不会动态变化；修改项目、entrypoint、静态参数或 draft 后需要重新连接。

命令格式

workflow-code mcp <workflow-dir> [options]

workflow-dir 是必填的 Workflow 项目目录。项目必须在 package.json.id 中声明不可变 UUID。

MCP 客户端配置

安装了 workflow-code bin 后，可以使用通用 stdio 配置：

{
  "mcpServers": {
    "workflow-11111111-1111-4111-8111-111111111111": {
      "command": "workflow-code",
      "args": [
        "mcp",
        "/absolute/path/to/workflow"
      ]
    }
  }
}

Desktop 本地 Workflow 的 Dock 中也提供 MCP 页签。它复制的是精简客户端配置，而不是上述 CLI 长命令：发行版只包含 Workflow Code 可执行文件、--workflow-mcp 和 Desktop 项目 ID。AI 客户端会按需启动无窗口 Desktop 进程，再由启动器从 Desktop 注册表读取项目与关联项目，并在内部补齐 runtime、数据目录和已保存认证，因此无需手动运行启动命令，复制内容也不包含账户 API Key 或这些内部路径。开发版会额外包含开发应用入口和短 profile 参数。

{
  "mcpServers": {
    "workflow-<PROJECT_UUID>": {
      "command": "<WORKFLOW_CODE_EXECUTABLE>",
      "args": ["--workflow-mcp", "<DESKTOP_PROJECT_ID>"]
    }
  }
}

项目必须继续注册在生成配置的 Desktop 工作区中。项目源码、entrypoint、静态 params 或关联项目变化后，重新连接客户端。

选项

选项	说明
`--data-dir <绝对目录>`	本地 workflow 数据根目录；默认是 `~/.workflow-code`。
`--file-store-dir <绝对目录>`	MCP 文件参数导入后的 managed-file store。
`--kv-store-dir <绝对目录>`	当前项目的本地 KV store。
`--persistent-value-store-dir <绝对目录>`	PersistentValue 与本地知识库存储。
`--file-create-store-dir <绝对目录>`	本地 runtime 生成文件目录。
`--desktop-config-dir <绝对目录>`	Desktop 保存连接认证的目录。
`--auth-dir <绝对目录>`	CLI 保存 `workflow-auth.json` 的目录。
`--related-project <alias>=<绝对项目目录>`	绑定一个双方已确认的关联项目；可重复指定。

除 workflow-dir 外，上述目录参数都要求绝对路径。项目自己的 .env 仍由 Core 加载；显式的 WORKFLOW_SERVER_URL / WORKFLOW_SERVER_ADMIN_KEY 优先于已保存认证。

Tool 参数

MCP input schema 按 entrypoint 的静态 params 生成，并设置 additionalProperties: false：

Workflow 参数	MCP 输入
`string` / `positional`	`string`
`number`	`number`
`boolean`	`boolean`
`multiple: true` / `checkboxes`	对应类型的数组
`file`	绝对文件路径；multiple file 使用路径数组

required、默认值、描述、静态 options 和日期格式会进入 schema。resolveParams 不会动态重写 MCP schema；动态选项项目仍以静态 params 为公开合同。

本地 file 参数不接受相对路径、URL 或 Base64。host 会确认路径指向普通文件、检查 50 MB 上限，再把文件导入当前 managed-file store。

{
  "prompt": "分析附件",
  "documents": [
    "/absolute/path/to/spec.pdf",
    "/absolute/path/to/notes.md"
  ]
}

运行、交互与结果

MCP host 通过隔离的 worker 执行现有 structure / json 链路。stdio 的 stdout 只承载 JSON-RPC；项目日志和 worker 诊断写到 stderr。取消 tool call 会终止对应 worker。

当 workflow 进入 waiting_for_input 或等待工具审批时，支持 form elicitation 的客户端会在同一个 runId 上连续恢复。客户端不支持 elicitation、待输入表单包含 file 字段，或包含未配置静态 options 的任意数组字段时，tool 返回 interaction_required 错误以及 runId 和待输入字段摘要，不会自动批准。交互式多选字段需要配置静态 options，才能通过标准 MCP form 恢复。

成功结果同时写入 MCP 文本 content 和 structuredContent：

{
  "runId": "20260828-abcd",
  "status": "success",
  "entrypointId": "main",
  "entrypointTitle": "Main",
  "output": {}
}

output 只来自 report.result.data.output。失败、非零业务 errCode、取消或超时会增加精简 error 并设置 isError: true；不会返回完整 report、节点明细、stdout、stderr 或内部凭据。参数格式错误使用 MCP InvalidParams。

通过 Desktop MCP 页签生成的精简配置启动时，无窗口启动器会把每次 tool call 写入同一 Desktop 工作区的 SQLite。记录包含原始 MCP input、转换后的 CLI args、连续交互的已提交值、完整 report、stdout、stderr 和各阶段状态；running、waiting_for_input、恢复与最终结果使用同一个 runId 更新同一条记录。调用会出现在首页最近记录和项目运行历史中，并可继续查看 Output、Diagram 与 Logs。主窗口已经打开时会自动刷新；未打开时，下次启动 Desktop 即可看到记录。

直接手工运行通用 workflow-code mcp <workflow-dir> 不包含 Desktop 注册表或 userData 上下文，因此不会自动写入 Desktop SQLite。KV、PersistentValue、知识库和 managed files 仍使用命令传入或默认的数据目录。

命令格式​

MCP 客户端配置​

选项​

Tool 参数​

运行、交互与结果​

命令格式

MCP 客户端配置

选项

Tool 参数

运行、交互与结果