Qingflow MCP Server

基于用户态 token 与 wsId 的 Qingflow MCP 适配层，覆盖表单数据、文件、应用、流程、视图、报表、门户、导航，以及高层解决方案搭建能力。

特性

• 用户账号登录，复用现有 Qingflow 权限模型
• 支持直接注入用户 token 建立 MCP 会话
• 显式工作区选择，避免误用默认工作区
• 覆盖表单数据增查改删
• 覆盖内部成员 / 内部部门 / 外部联系人查询
• 覆盖应用 CRUD、表单结构读写、应用发布
• 覆盖应用包（Tag）CRUD
• 覆盖顶层 Navigation 导航配置
• 覆盖评论、通过、拒绝、回退、转交、改派、加签
• 覆盖门户 CRUD、门户发布
• 覆盖文件上传凭证获取与本地文件上传
• 覆盖流程设计与流程调试
• 覆盖视图设计与视图子类型配置
• 覆盖报表设计与图表排序/配置
• 覆盖 solution_design_session 任务级设计会话，支持分阶段 DSL 设计与 finalize
• 覆盖 staged 高层搭建工具与统一入口：solution_schema_example、solution_build_app、solution_build_flow、solution_build_all、solution_build_views、solution_build_analytics_portal、solution_build_navigation

不支持

• 外部部门查询
• 应用包分组管理
• 应用包内导航项配置
• 签名图片、eSign
• 外部成员候选查询（转交/加签）
• 短信验证码、多因素登录挑战
• OpenAPI accessToken / serviceToken

安装

cd <repo_root>/qingflow-support/mcp-server
python3 -m venv .venv
./.venv/bin/pip install -e '.[dev]'

本地智能体安装（npm）

如果你要给本地 agent / gateway 安装这套 MCP，而不是手动管理 Python 环境，可以直接用 npm：

cd <repo_root>/qingflow-support/mcp-server
npm install -g .

或只在当前目录安装：

cd <repo_root>/qingflow-support/mcp-server
npm install

如果你想把当前版本封装成可分发的 npm 安装包：

cd <repo_root>/qingflow-support/mcp-server
npm run pack:npm

产物会输出到：

dist/npm/josephyan-qingflow-mcp-<version>.tgz

另一台机器可直接安装这个 tgz：

npm install /absolute/path/to/dist/npm/josephyan-qingflow-mcp-<version>.tgz

安装时会自动创建 .npm-python/，并在里面执行 pip install .。

如果你是全局安装，完成后本机可直接使用这两个入口：

qingflow-app-user-mcp
qingflow-app-builder-mcp

如果你只是对当前源码 checkout 执行了 npm install，请直接运行：

node ./npm/bin/qingflow-app-user-mcp.mjs
node ./npm/bin/qingflow-app-builder-mcp.mjs

适合这类本地 stdio MCP 客户端：

• Claude Desktop
• Cline / Cursor
• OpenClaw 风格的本地 agent / gateway
• 其它支持 command + args + env 的本地智能体

详细说明见：

• docs/local-agent-install.md

运行

cd <repo_root>/qingflow-support/mcp-server
./qingflow-app-user-mcp

或：

qingflow-app-user-mcp
qingflow-app-builder-mcp

配置

• QINGFLOW_MCP_DEFAULT_BASE_URL：默认 Qingflow 后端地址
• QINGFLOW_MCP_DEFAULT_QF_VERSION：默认 qfVersion 路由值
• QINGFLOW_MCP_HOME：本地会话目录，默认 ~/.qingflow-mcp
• QINGFLOW_MCP_DESIGN_HOME：solution_design_session 本地设计会话目录，默认 ~/.qingflow-mcp/design-sessions
• QINGFLOW_MCP_BUILD_HOME：分阶段 build assembly 目录，默认 ~/.qingflow-mcp/build-assemblies
• QINGFLOW_MCP_BOOTSTRAP_HOME：solution_bootstrap 运行记录目录，默认 ~/.qingflow-mcp/bootstrap-runs
• QINGFLOW_MCP_TIMEOUT_SECONDS：HTTP 超时秒数，默认 30

会话元数据写入 ~/.qingflow-mcp/profiles.json。

配置文件会按下面的顺序查找第一个存在的文件：

1. QINGFLOW_MCP_CONFIG_PATH
2. 当前工作目录 qingflow-mcp.config.json
3. ~/.qingflow-mcp/config.json
4. /etc/qingflow-mcp/config.json

auth_login / auth_use_token 的路由优先级是：

1. 工具参数里显式传入的 base_url / qf_version
2. 全局默认 QINGFLOW_MCP_DEFAULT_BASE_URL / QINGFLOW_MCP_DEFAULT_QF_VERSION 或配置文件里的 default_base_url / default_qf_version（同层里环境变量优先）

敏感 token 优先写入系统 keychain；如果当前环境没有可用 keychain，会自动退回仅内存会话。

示例配置文件：

{
  "default_base_url": "https://qingflow.com/api",
  "default_qf_version": "canary"
}

会话模型

1. 调用 auth_login 或 auth_use_token
2. 调用 workspace_list
3. 调用 workspace_select
4. 再调用业务工具

未选择工作区前，除 auth_* 和 workspace_* 外的工具都会报错。

说明：

• auth_use_token 是 MCP 工具，不是额外的 HTTP 请求头。业务请求真正发送的是 token、wsId，以及必要时的 Cookie: qfVersion=...
• 生产环境如果 /user 响应里没有返回版本路由，workspace_select 会用工作区的 systemVersion 兜底到当前会话；因此不要跳过 workspace_select

工具清单

认证与工作区

• auth_login
• auth_use_token
• auth_whoami
• auth_logout
• workspace_list
• workspace_select
• workspace_set_plugin_status

表单数据

• record_field_resolve
• record_query_plan
• record_write_plan
• record_query
• record_aggregate
• record_create
• record_get
• record_update
• record_delete

说明：

• record_query 是推荐的统一读入口，按 query_mode 路由到列表、单条详情或汇总分析
• record_query(list) 默认返回扁平宽表行，适合浏览、导出和分析；当选列超过后端单次字段上限时，工具会自动分批查询并按 apply_id 合并；单条完整详情请用 record_get
• record_write_plan 用于复杂写入前的静态预检，支持 fields 这种更友好的写法；每个字段都会返回 write_format.support_level，区分 full、restricted、unsupported
• record_create 和 record_update 都支持 verify_write=true，会在写入后读回记录并检测字段是否被静默丢弃、清空或数量不足
• 子表字段现在支持行对象写法，例如 {"明细": [{"产品名称": "企业版", "数量": 2}]}；更新既有子表行时可额外传 rowId / row_id / __row_id__
• record_get / record_create / record_update 继续保留，用于精确详情读取和明确写入

文件

• file_get_upload_info
• file_upload_local

应用

• package_list

• package_get

• package_get_base

• package_create

• package_update

• package_delete

• navigation_list_published

• navigation_list_draft_page

• navigation_list_draft_all

• navigation_get_detail

• navigation_get_status

• navigation_set_visible

• navigation_create

• navigation_update

• navigation_delete

• navigation_publish

• navigation_reorder

说明：

• workspace_set_plugin_status 会调用工作区插件安装接口，可用于安装或卸载指定插件。

• staged 高层 build 在创建导航时如果遇到 50004 插件未安装，会先尝试自动安装导航插件，再重试一次导航创建。

• record_comment_add

• record_comment_list

• record_comment_mention_candidates

• record_comment_mark_read

• record_comment_stats

• task_statistics

• task_list

• task_list_grouped

• task_urge

• task_approve

• task_reject

• task_rollback_candidates

• task_rollback

• task_transfer

• task_transfer_candidates

• app_list

• app_get_base

• app_update_base

• app_get_form_schema

• app_create

• app_delete

• app_publish

说明：

• app_get_base 和 app_get_form_schema 默认返回紧凑摘要，适合智能体消费；如果需要完整原始 baseInfo/form schema，显式传 include_raw=true
• 原始表单 schema 写入接口 app_update_form_schema 已不再对外暴露；对外应优先使用 solution_* 或更高层的 builder 流程，而不是直接拼接原生 schema

流程

• workflow_list_nodes
• workflow_get_node_detail
• workflow_get_global_settings
• workflow_get_future_nodes
• workflow_get_future_nodes_app
• workflow_get_qsource_active
• workflow_get_qsource_passive
• workflow_get_editable_question_ids
• workflow_get_print_nodes

说明：

• workflow_* 的低层写接口已不再对外暴露；对外应优先使用 solution_build_flow

视图

• view_list
• view_list_flat
• view_get_config
• view_get_base_info
• view_list_questions
• view_list_associations
• view_board_get_lane_base_info
• view_get_future_nodes
• view_get_workflow_status

说明：

• view_* 的低层写接口已不再对外暴露；对外应优先使用 solution_build_views

报表

• qingbi_report_list
• qingbi_report_get_base
• qingbi_report_get_config
• qingbi_report_get_data
• qingbi_report_delete
• qingbi_report_reorder
• qingbi_report_list_fields
• qingbi_report_list_field_options

说明：

• qingbi_report_* 的原始创建和配置写入接口已不再对外暴露；对外应优先使用 solution_build_analytics_portal

门户

• portal_list
• portal_get
• portal_create
• portal_update
• portal_delete
• portal_publish

通讯录

• directory_search
• directory_list_internal_users
• directory_list_all_internal_users
• directory_list_internal_departments
• directory_list_all_departments
• directory_list_sub_departments
• directory_list_external_members

解决方案编排

• solution_design_session
• solution_schema_example
• solution_build_all
• solution_build_app
• solution_build_flow
• solution_build_views
• solution_build_analytics_portal
• solution_build_navigation
• solution_build_status

solution_design_session 用来承接上层 AI 的分阶段设计过程：

• start：创建或读取一个 task-scoped 设计会话；未传 session_id 时会自动生成并返回
• submit_stage：提交 discover/design/experience 阶段 patch，返回当前 gate 状态和缺失项
• get：读取当前设计会话快照
• finalize：把分阶段 patch 合并成完整 SolutionSpec，并返回可执行 execution_plan
• 这是纯本地设计会话工具，不调用 Qingflow 后端，也不会影响智能体处理其他任务

公开高层搭建入口已经改成 staged build：

• solution_schema_example

  • 返回指定 stage 的精确 DSL 示例、必填字段、常见错误和建议的下一次调用
  • 复杂 payload 生成前应先调用

• solution_build_all

  • 负责把完整 SolutionSpec 自动拆分到 app_flow/views/analytics_portal/navigation
  • 支持 preflight/plan/apply/repair
  • preflight/plan 未传 build_id 时会自动生成，并返回 build_id 与 suggested_next_call
  • verify=true 时会在成功后自动做回读校验
  • repair 时如果未传 solution_spec，会优先复用 build_id 已落盘的 manifest

• solution_build_app

  • 负责应用包、应用、字段、表单布局、角色、模拟数据
  • 支持 preflight/plan/apply/repair
  • preflight/plan 未传 build_id 时会自动生成，并返回 build_id 与 suggested_next_call
  • target.package_tag_id 可选；传入后会复用已有应用包

• solution_build_flow

  • 负责流程、生命周期阶段与相关角色
  • 支持 preflight/plan/apply/repair
  • preflight/plan 未传 build_id 时会自动生成，并返回 build_id 与 suggested_next_call

• solution_build_views

  • 负责视图创建、排序、子类型配置、应用发布
  • 支持 preflight/plan/apply/repair
  • preflight/plan 未传 build_id 时会自动生成，并返回 build_id 与 suggested_next_call

• solution_build_analytics_portal

  • 负责 Qingbi 报表、门户布局、筛选器、宫格入口、发布
  • 支持 preflight/plan/apply/repair
  • preflight/plan 未传 build_id 时会自动生成，并返回 build_id 与 suggested_next_call

• solution_build_navigation

  • 负责导航创建、排序与发布
  • 支持 preflight/plan/apply/repair
  • preflight/plan 未传 build_id 时会自动生成，并返回 build_id 与 suggested_next_call

• solution_build_status

  • 纯本地读取 build_id 对应的 assembly 状态
  • 返回 stage_statuses、ready_stages、next_recommended_stage、missing_prerequisites

设计边界：

• AI 负责生成每个阶段的显式 DSL
• MCP 只做校验、归一化、原生接口转译和执行
• 支持 staged DSL，也支持通过 solution_build_all 直接提交完整 SolutionSpec

示例 MCP client 配置

见 examples/claude_desktop_config.json。

如果通过 npm 安装到本机，也可以直接配成：

{
  "mcpServers": {
    "qingflow": {
      "command": "qingflow-app-user-mcp",
      "args": [],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
      }
    }
  }
}

示例调用顺序

见 examples/transcript.md。

设计文档

• 工具矩阵与后续扩展方案：docs/tool-matrix.md

典型用法

1. 登录

{
  "profile": "default",
  "base_url": "https://qingflow.example.com",
  "email": "[email protected]",
  "password": "******",
  "persist": true
}

1b. 直接注入 token

{
  "profile": "default",
  "base_url": "https://qingflow.example.com/api",
  "token": "<user-token>",
  "ws_id": 10001,
  "persist": false
}

2. 查询工作区

{
  "profile": "default",
  "page_num": 1,
  "page_size": 20,
  "include_external": false
}

3. 选择工作区

{
  "profile": "default",
  "ws_id": 10001
}

4. 新增记录

{
  "profile": "default",
  "app_key": "APP_xxx",
  "submit_type": 1,
  "answers": [
    {
      "queId": 1001,
      "queType": 2,
      "values": [{ "value": "hello" }],
      "tableValues": []
    }
  ]
}

5. 搜索内部成员

{
  "profile": "default",
  "keyword": "张",
  "page_num": 1,
  "page_size": 20,
  "contain_disable": false
}

6. 拉取全部内部成员

{
  "profile": "default",
  "page_size": 200,
  "max_pages": 100,
  "contain_disable": false
}

7. 拉取全部部门树

{
  "profile": "default",
  "parent_dept_id": null,
  "max_depth": 20,
  "max_items": 2000
}

返回约定

• 成功时返回结构化 JSON
• Qingflow 后端报错会原样透出主要错误信息
• token 失效时会自动清除当前 profile 的本地会话，并提示重新登录