@josephyan/qingflow-mcp 0.1.0-beta.2

package/README.md

@@ -0,0 +1,517 @@
+# Qingflow MCP Server
+
+基于用户态 `token` 与 `wsId` 的 Qingflow MCP 适配层，覆盖表单数据、文件、应用、流程、视图、报表、门户、导航，以及高层解决方案搭建能力。
+
+## 特性
+
+- 用户账号登录，复用现有 Qingflow 权限模型
+- 支持直接注入用户 `token` 建立 MCP 会话
+- 显式工作区选择，避免误用默认工作区
+- 覆盖表单数据增查改删
+- 覆盖内部成员 / 内部部门 / 外部联系人查询
+- 覆盖应用 CRUD、表单结构读写、应用发布
+- 覆盖应用包（Tag）CRUD
+- 覆盖顶层 Navigation 导航配置
+- 覆盖评论、通过、拒绝、回退、转交、改派、加签
+- 覆盖门户 CRUD、门户发布
+- 覆盖文件上传凭证获取与本地文件上传
+- 覆盖流程设计与流程调试
+- 覆盖视图设计与视图子类型配置
+- 覆盖报表设计与图表排序/配置
+- 覆盖 `solution_design_session` 任务级设计会话，支持分阶段 DSL 设计与 finalize
+- 覆盖 staged 高层搭建工具与统一入口：`solution_build_all`、`solution_build_app_flow`、`solution_build_views`、`solution_build_analytics_portal`、`solution_build_navigation`
+
+## 不支持
+
+- 外部部门查询
+- 应用包分组管理
+- 应用包内导航项配置
+- 签名图片、eSign
+- 外部成员候选查询（转交/加签）
+- 短信验证码、多因素登录挑战
+- OpenAPI `accessToken` / `serviceToken`
+
+## 安装
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+python3 -m venv .venv
+./.venv/bin/pip install -e '.[dev]'
+```
+
+## 本地智能体安装（npm）
+
+如果你要给本地 agent / gateway 安装这套 MCP，而不是手动管理 Python 环境，可以直接用 npm：
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+npm install -g .
+```
+
+或只在当前目录安装：
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+npm install
+```
+
+如果你想把当前版本封装成可分发的 npm 安装包：
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+npm run pack:npm
+```
+
+产物会输出到：
+
+```bash
+dist/npm/qingflow-qingflow-mcp-<version>.tgz
+```
+
+另一台机器可直接安装这个 tgz：
+
+```bash
+npm install /absolute/path/to/dist/npm/qingflow-qingflow-mcp-<version>.tgz
+```
+
+安装时会自动创建 `.npm-python/`，并在里面执行 `pip install .`。
+
+如果你是全局安装，完成后本机可直接使用：
+
+```bash
+qingflow-mcp
+```
+
+如果你只是对当前源码 checkout 执行了 `npm install`，请直接运行：
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+node ./npm/bin/qingflow-mcp.mjs
+```
+
+适合这类本地 stdio MCP 客户端：
+
+- Claude Desktop
+- Cline / Cursor
+- OpenClaw 风格的本地 agent / gateway
+- 其它支持 `command + args + env` 的本地智能体
+
+详细说明见：
+
+- `docs/local-agent-install.md`
+
+## 运行
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+./qingflow-mcp
+```
+
+也可以直接：
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+PYTHONPATH=src python3 -m qingflow_mcp.server
+```
+
+如果你已经通过 `pip install -e '.[dev]'` 把脚本安装到当前 Python 环境，也可以直接运行：
+
+```bash
+qingflow-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，会自动退回仅内存会话。
+
+示例配置文件：
+
+```json
+{
+  "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_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`
+- `record_approve`
+- `record_reject`
+- `record_rollback_candidates`
+- `record_rollback`
+- `record_transfer`
+- `record_transfer_candidates`
+- `record_reassign_get`
+- `record_reassign`
+- `record_countersign_candidates`
+- `record_countersign`
+
+- `app_list`
+- `app_get_base`
+- `app_update_base`
+- `app_get_form_schema`
+- `app_update_form_schema`
+- `app_create`
+- `app_delete`
+- `app_publish`
+
+### 流程
+
+- `workflow_list_nodes`
+- `workflow_get_node_detail`
+- `workflow_add_node`
+- `workflow_update_node`
+- `workflow_delete_node`
+- `workflow_copy_paste_node`
+- `workflow_cut_paste_node`
+- `workflow_create_sub_branch`
+- `workflow_delete_sub_branch`
+- `workflow_get_global_settings`
+- `workflow_update_global_settings`
+- `workflow_publish`
+- `workflow_get_future_nodes`
+- `workflow_get_future_nodes_app`
+- `workflow_webhook_test`
+- `workflow_qsource_query`
+- `workflow_qsource_test`
+- `workflow_get_qsource_active`
+- `workflow_upsert_qsource_active`
+- `workflow_get_qsource_passive`
+- `workflow_upsert_qsource_passive`
+- `workflow_switch_qsource_status`
+- `workflow_delete_qsource`
+- `workflow_get_editable_question_ids`
+- `workflow_get_print_nodes`
+
+### 视图
+
+- `view_list`
+- `view_list_flat`
+- `view_reorder`
+- `view_set_column_width`
+- `view_create`
+- `view_get_config`
+- `view_get_base_info`
+- `view_update`
+- `view_delete`
+- `view_copy`
+- `view_list_questions`
+- `view_list_associations`
+- `view_update_member_config`
+- `view_update_apply_config`
+- `view_board_set_lane_config`
+- `view_board_get_lane_base_info`
+- `view_gantt_switch_auto_calibration`
+- `view_gantt_batch_update_time`
+- `view_get_future_nodes`
+- `view_get_workflow_status`
+
+### 报表
+
+- `qingbi_report_list`
+- `qingbi_report_create`
+- `qingbi_report_get_base`
+- `qingbi_report_update_base`
+- `qingbi_report_get_config`
+- `qingbi_report_update_config`
+- `qingbi_report_get_data`
+- `qingbi_report_delete`
+- `qingbi_report_reorder`
+- `qingbi_report_list_fields`
+- `qingbi_report_list_field_options`
+
+### 门户
+
+- `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_build_all`
+- `solution_build_app_flow`
+- `solution_build_views`
+- `solution_build_analytics_portal`
+- `solution_build_navigation`
+- `solution_build_status`
+
+`solution_design_session` 用来承接上层 AI 的分阶段设计过程：
+
+- `start`：创建或读取一个 task-scoped 设计会话
+- `submit_stage`：提交 `discover/design/experience` 阶段 patch，返回当前 gate 状态和缺失项
+- `get`：读取当前设计会话快照
+- `finalize`：把分阶段 patch 合并成完整 `SolutionSpec`，并返回可执行 `execution_plan`
+- 这是纯本地设计会话工具，不调用 Qingflow 后端，也不会影响智能体处理其他任务
+
+公开高层搭建入口已经改成 staged build：
+
+- `solution_build_all`
+  - 负责把完整 `SolutionSpec` 自动拆分到 `app_flow/views/analytics_portal/navigation`
+  - 支持 `preflight/plan/apply/repair`
+  - `verify=true` 时会在成功后自动做回读校验
+  - `repair` 时如果未传 `solution_spec`，会优先复用 `build_id` 已落盘的 manifest
+
+- `solution_build_app_flow`
+  - 负责应用包、应用、字段、表单布局、角色、流程、模拟数据
+  - 支持 `preflight/plan/apply/repair`
+  - `target.package_tag_id` 可选；传入后会复用已有应用包
+- `solution_build_views`
+  - 负责视图创建、排序、子类型配置、应用发布
+  - 支持 `preflight/plan/apply/repair`
+- `solution_build_analytics_portal`
+  - 负责 Qingbi 报表、门户布局、筛选器、宫格入口、发布
+  - 支持 `preflight/plan/apply/repair`
+- `solution_build_navigation`
+  - 负责导航创建、排序与发布
+  - 支持 `preflight/plan/apply/repair`
+- `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 安装到本机，也可以直接配成：
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "qingflow-mcp",
+      "args": [],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://stable732.oalite.com/api"
+      }
+    }
+  }
+}
+```
+
+## 示例调用顺序
+
+见 `examples/transcript.md`。
+
+## 设计文档
+
+- 工具矩阵与后续扩展方案：`docs/tool-matrix.md`
+
+## 典型用法
+
+### 1. 登录
+
+```json
+{
+  "profile": "default",
+  "base_url": "https://qingflow.example.com",
+  "email": "user@example.com",
+  "password": "******",
+  "persist": true
+}
+```
+
+### 1b. 直接注入 token
+
+```json
+{
+  "profile": "default",
+  "base_url": "https://qingflow.example.com/api",
+  "token": "<user-token>",
+  "ws_id": 10001,
+  "persist": false
+}
+```
+
+### 2. 查询工作区
+
+```json
+{
+  "profile": "default",
+  "page_num": 1,
+  "page_size": 20,
+  "include_external": false
+}
+```
+
+### 3. 选择工作区
+
+```json
+{
+  "profile": "default",
+  "ws_id": 10001
+}
+```
+
+### 4. 新增记录
+
+```json
+{
+  "profile": "default",
+  "app_key": "APP_xxx",
+  "submit_type": 1,
+  "answers": [
+    {
+      "queId": 1001,
+      "queType": 2,
+      "values": [{ "value": "hello" }],
+      "tableValues": []
+    }
+  ]
+}
+```
+
+### 5. 搜索内部成员
+
+```json
+{
+  "profile": "default",
+  "keyword": "张",
+  "page_num": 1,
+  "page_size": 20,
+  "contain_disable": false
+}
+```
+
+### 6. 拉取全部内部成员
+
+```json
+{
+  "profile": "default",
+  "page_size": 200,
+  "max_pages": 100,
+  "contain_disable": false
+}
+```
+
+### 7. 拉取全部部门树
+
+```json
+{
+  "profile": "default",
+  "parent_dept_id": null,
+  "max_depth": 20,
+  "max_items": 2000
+}
+```
+
+## 返回约定
+
+- 成功时返回结构化 JSON
+- Qingflow 后端报错会原样透出主要错误信息
+- token 失效时会自动清除当前 profile 的本地会话，并提示重新登录

package/docs/local-agent-install.md

@@ -0,0 +1,213 @@
+# 本地智能体安装
+
+这个目录下现在同时支持两种本地安装形态：
+
+1. 直接用 Python 运行 `qingflow-mcp`
+2. 通过 npm 安装一个本地 agent 友好的启动壳
+
+## npm 安装器适用场景
+
+适合这类本地 agent / gateway：
+
+- Claude Desktop
+- Cline / Roo / Cursor 这类本地 MCP 客户端
+- OpenClaw 风格的本地 agent 容器或本地 gateway
+- 任何支持 `command + args + env` 的 stdio MCP 客户端
+
+## 前置条件
+
+- Node.js >= 16.16
+- Python >= 3.11
+- 安装过程中可以访问 PyPI
+
+如果机器上没有默认 `python3` / `python`，可以先设置：
+
+```bash
+export QINGFLOW_MCP_PYTHON=/path/to/python3.11
+```
+
+## 安装方式
+
+### 方式 1：在源码目录预热运行环境
+
+```bash
+cd qingflow-support/mcp-server
+npm install
+```
+
+这个模式适合你已经有源码 checkout，只想让当前目录具备本地 agent 可调用的运行时。
+
+### 方式 2：全局安装到当前机器
+
+```bash
+cd qingflow-support/mcp-server
+npm install -g .
+```
+
+### 方式 3：安装到某个本地 agent workspace
+
+```bash
+npm install /absolute/path/to/qingflow-support/mcp-server
+```
+
+### 方式 4：离线分发 tgz 安装包
+
+先在源码目录打包：
+
+```bash
+cd qingflow-support/mcp-server
+npm run pack:npm
+```
+
+会生成：
+
+```bash
+dist/npm/qingflow-qingflow-mcp-<version>.tgz
+```
+
+然后在目标机器安装：
+
+```bash
+npm install /absolute/path/to/dist/npm/qingflow-qingflow-mcp-<version>.tgz
+```
+
+安装时会自动：
+
+1. 创建 `.npm-python/`
+2. 在其中建立 Python 虚拟环境
+3. 执行 `pip install .`
+4. 在安装位置暴露 `qingflow-mcp` 命令
+
+## 本地验证
+
+如果你在源码目录执行了 `npm install`，可直接这样启动：
+
+```bash
+cd qingflow-support/mcp-server
+node ./npm/bin/qingflow-mcp.mjs
+```
+
+如果你是全局安装：
+
+```bash
+qingflow-mcp
+```
+
+如果你是把包安装到了某个本地 agent workspace，命令通常位于：
+
+```bash
+/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-mcp
+```
+
+如果你是从 tgz 安装到某个空目录，命令通常位于：
+
+```bash
+/absolute/path/to/install-dir/node_modules/.bin/qingflow-mcp
+```
+
+这是 stdio MCP server，正常情况下不会输出欢迎信息，而是等待客户端连接。
+
+## 客户端配置
+
+### 通用 stdio MCP 客户端
+
+如果你直接使用源码 checkout：
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/qingflow-support/mcp-server/npm/bin/qingflow-mcp.mjs"
+      ],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://stable732.oalite.com/api",
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+      }
+    }
+  }
+}
+```
+
+如果你已经全局安装：
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "qingflow-mcp",
+      "args": [],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://stable732.oalite.com/api",
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+      }
+    }
+  }
+}
+```
+
+如果你把包安装到了某个本地 agent workspace：
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-mcp",
+      "args": [],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://stable732.oalite.com/api",
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+      }
+    }
+  }
+}
+```
+
+### 使用 npx
+
+如果不做全局安装，也可以直接让客户端运行 npm 包里的命令：
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@josephyan/qingflow-mcp"
+      ],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://stable732.oalite.com/api"
+      }
+    }
+  }
+}
+```
+
+说明：
+
+- 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow-mcp.mjs`
+- `npx` 方式适合临时安装或容器化本地 agent
+- 全局安装方式更适合长期固定使用的本机开发环境
+
+## 排障
+
+如果安装失败，优先检查：
+
+1. `node -v`
+2. `python3 --version`
+3. `pip` 是否能访问 PyPI
+4. 是否设置了错误的 `QINGFLOW_MCP_PYTHON`
+
+如果需要重装 Python 侧运行环境，可以删掉：
+
+```bash
+rm -rf .npm-python
+```
+
+然后重新执行：
+
+```bash
+npm install
+```