@josephyan/qingflow-app-user-mcp 0.2.0-beta.2 → 0.2.0-beta.21

package/src/qingflow_mcp/server.py

@@ -28,14 +28,16 @@ def build_server() -> FastMCP:
         instructions=(
             "Use auth_login first, then workspace_list and workspace_select. "
             "All resource tools operate with the logged-in user's Qingflow permissions.\n\n"
+            "For analytics, use record_schema_get first, let the model build field_id-based DSL, "
+            "then call record_analyze. For operational record reads, use record_schema_get first, then record_list or record_get. "
+            "For writes, use record_schema_get and then record_write with mode=plan or apply.\n\n"
             "Task Center (待办/已办) handling:\n"
-            "- Use task_statistics to get counts of pending tasks (todo_count), timeouts, urged, etc.\n"
-            "- Use task_list to query tasks. Type values: 1=todo (待办), 2=initiated (我发起的), 3=cc (抄送), 5=done (已办).\n"
-            "- Use task_list_grouped to get tasks grouped by form/worksheet.\n"
+            "- Use task_summary to get headline counts.\n"
+            "- Use task_list for flat task browsing with task_box and flow_status.\n"
+            "- Use task_facets when worksheet or workflow-node buckets matter.\n"
             "- Use task_mark_read to mark a specific task as read.\n"
             "- Use task_urge to send an urgent reminder for a pending task.\n"
-            "- Process status values: 1=all, 2=processing, 3=passed, 4=refused, 5=need_supply, 6=urged, 7=timeout, 8=pre_timeout, 9=unread.\n"
-            "- After identifying the exact task node and record, use record_approve, record_reject, record_rollback, record_transfer, record_reassign, or record_countersign as needed."
+            "- After identifying the exact task node and record, use task_approve, task_reject, task_rollback, or task_transfer as needed."
         ),
     )
     sessions = SessionStore()

package/src/qingflow_mcp/server_app_builder.py

@@ -17,11 +17,15 @@ def build_builder_server() -> FastMCP:
         instructions=(
             "Use this server for AI-native Qingflow builder workflows. "
             "Follow the resource path resolve -> summary read -> plan -> apply -> attach -> publish_verify. "
-            "Use package_resolve/package_list and app_resolve to locate resources, "
+            "Use builder_tool_contract when you need a machine-readable contract, aliases, allowed enums, or a minimal valid example for a public builder tool. "
+            "If creating a new package may be appropriate, ask the user to confirm package creation before calling package_create; otherwise use package_resolve/package_list and app_resolve to locate resources, "
             "app_read_summary/app_read_fields/app_read_layout_summary/app_read_views_summary/app_read_flow_summary for compact reads, "
+            "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
             "app_schema_plan/app_layout_plan/app_flow_plan/app_views_plan before writes when the target patch is non-trivial, "
-            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply to execute normalized patches, "
-            "package_attach_app to attach apps to packages, and app_publish_verify to publish and verify. "
+            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply to execute normalized patches; these apply tools publish by default unless publish=false. "
+            "Use package_attach_app to attach apps to packages, and app_publish_verify for explicit final publish verification. "
+            "For workflow edits, prefer preset plus explicit patching over generating a full custom graph from scratch, and declare node assignees and editable fields explicitly. "
+            "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
             "Do not handcraft internal solution payloads or rely on build_id/stage/repair."
         ),
     )
@@ -124,6 +128,57 @@ def build_builder_server() -> FastMCP:
     def package_resolve(profile: str = DEFAULT_PROFILE, package_name: str = "") -> dict:
         return ai_builder.package_resolve(profile=profile, package_name=package_name)
 
+    @server.tool()
+    def builder_tool_contract(tool_name: str = "") -> dict:
+        return ai_builder.builder_tool_contract(tool_name=tool_name)
+
+    @server.tool()
+    def package_create(profile: str = DEFAULT_PROFILE, package_name: str = "") -> dict:
+        return ai_builder.package_create(profile=profile, package_name=package_name)
+
+    @server.tool()
+    def member_search(
+        profile: str = DEFAULT_PROFILE,
+        query: str = "",
+        page_num: int = 1,
+        page_size: int = 20,
+        contain_disable: bool = False,
+    ) -> dict:
+        return ai_builder.member_search(
+            profile=profile,
+            query=query,
+            page_num=page_num,
+            page_size=page_size,
+            contain_disable=contain_disable,
+        )
+
+    @server.tool()
+    def role_search(
+        profile: str = DEFAULT_PROFILE,
+        keyword: str = "",
+        page_num: int = 1,
+        page_size: int = 20,
+    ) -> dict:
+        return ai_builder.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+
+    @server.tool()
+    def role_create(
+        profile: str = DEFAULT_PROFILE,
+        role_name: str = "",
+        member_uids: list[int] | None = None,
+        member_emails: list[str] | None = None,
+        member_names: list[str] | None = None,
+        role_icon: str = "ex-user-outlined",
+    ) -> dict:
+        return ai_builder.role_create(
+            profile=profile,
+            role_name=role_name,
+            member_uids=member_uids or [],
+            member_emails=member_emails or [],
+            member_names=member_names or [],
+            role_icon=role_icon,
+        )
+
     @server.tool()
     def package_attach_app(
         profile: str = DEFAULT_PROFILE,
@@ -133,6 +188,20 @@ def build_builder_server() -> FastMCP:
     ) -> dict:
         return ai_builder.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title)
 
+    @server.tool()
+    def app_release_edit_lock_if_mine(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        lock_owner_email: str = "",
+        lock_owner_name: str = "",
+    ) -> dict:
+        return ai_builder.app_release_edit_lock_if_mine(
+            profile=profile,
+            app_key=app_key,
+            lock_owner_email=lock_owner_email,
+            lock_owner_name=lock_owner_name,
+        )
+
     @server.tool()
     def app_resolve(
         profile: str = DEFAULT_PROFILE,
@@ -242,6 +311,7 @@ def build_builder_server() -> FastMCP:
         app_name: str = "",
         app_title: str = "",
         create_if_missing: bool = False,
+        publish: bool = True,
         add_fields: list[dict] | None = None,
         update_fields: list[dict] | None = None,
         remove_fields: list[dict] | None = None,
@@ -253,6 +323,7 @@ def build_builder_server() -> FastMCP:
             app_name=app_name,
             app_title=app_title,
             create_if_missing=create_if_missing,
+            publish=publish,
             add_fields=add_fields or [],
             update_fields=update_fields or [],
             remove_fields=remove_fields or [],
@@ -263,15 +334,17 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
         mode: str = "merge",
+        publish: bool = True,
         sections: list[dict] | None = None,
     ) -> dict:
-        return ai_builder.app_layout_apply(profile=profile, app_key=app_key, mode=mode, sections=sections or [])
+        return ai_builder.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [])
 
     @server.tool()
     def app_flow_apply(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
         mode: str = "replace",
+        publish: bool = True,
         nodes: list[dict] | None = None,
         transitions: list[dict] | None = None,
     ) -> dict:
@@ -279,6 +352,7 @@ def build_builder_server() -> FastMCP:
             profile=profile,
             app_key=app_key,
             mode=mode,
+            publish=publish,
             nodes=nodes or [],
             transitions=transitions or [],
         )
@@ -287,12 +361,14 @@ def build_builder_server() -> FastMCP:
     def app_views_apply(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
+        publish: bool = True,
         upsert_views: list[dict] | None = None,
         remove_views: list[str] | None = None,
     ) -> dict:
         return ai_builder.app_views_apply(
             profile=profile,
             app_key=app_key,
+            publish=publish,
             upsert_views=upsert_views or [],
             remove_views=remove_views or [],
         )

package/src/qingflow_mcp/server_app_user.py

@@ -18,8 +18,11 @@ def build_user_server() -> FastMCP:
     server = FastMCP(
         "Qingflow App User MCP",
         instructions=(
-            "Use this server for Qingflow record queries, record writes, task center operations, "
-            "directory lookups, and approval actions. Avoid builder-side app or schema changes here."
+            "Use this server for Qingflow operational workflows with a schema-first path. "
+            "For records, start with record_schema_get, then choose record_list, record_get, or record_write. "
+            "For analytics, switch to record_schema_get and record_analyze. "
+            "For task center, use task_summary, task_list, and task_facets before any explicit task action. "
+            "Avoid builder-side app or schema changes here."
         ),
     )
     sessions = SessionStore()
@@ -136,189 +139,12 @@ def build_user_server() -> FastMCP:
             bucket_type=bucket_type,
             path_id=path_id,
             file_related_url=file_related_url,
-        )
+    )
 
     RecordTools(sessions, backend).register(server)
     DirectoryTools(sessions, backend).register(server)
-
-    @server.tool()
-    def record_comment_add(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_comment_add(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
-
-    @server.tool()
-    def record_comment_list(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        page_size: int = 20,
-        list_type: int | None = None,
-        page_num: int | None = 1,
-    ) -> dict:
-        return approvals.record_comment_list(
-            profile=profile,
-            app_key=app_key,
-            apply_id=apply_id,
-            page_size=page_size,
-            list_type=list_type,
-            page_num=page_num,
-        )
-
-    @server.tool()
-    def record_comment_mention_candidates(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        page_size: int = 20,
-        page_num: int = 1,
-        list_type: int | None = None,
-        keyword: str | None = None,
-    ) -> dict:
-        return approvals.record_comment_mention_candidates(
-            profile=profile,
-            app_key=app_key,
-            apply_id=apply_id,
-            page_size=page_size,
-            page_num=page_num,
-            list_type=list_type,
-            keyword=keyword,
-        )
-
-    @server.tool()
-    def record_comment_mark_read(profile: str = DEFAULT_PROFILE, app_key: str = "", apply_id: int = 0) -> dict:
-        return approvals.record_comment_mark_read(profile=profile, app_key=app_key, apply_id=apply_id)
-
-    @server.tool()
-    def record_comment_stats(profile: str = DEFAULT_PROFILE, app_key: str = "", apply_id: int = 0) -> dict:
-        return approvals.record_comment_stats(profile=profile, app_key=app_key, apply_id=apply_id)
-
-    @server.tool()
-    def task_list(
-        profile: str = DEFAULT_PROFILE,
-        type: int = 1,
-        process_status: int = 1,
-        app_key: str | None = None,
-        node_id: int | None = None,
-        search_key: str | None = None,
-        page_num: int = 1,
-        page_size: int = 20,
-        create_time_asc: bool | None = None,
-    ) -> dict:
-        return tasks.task_list(
-            profile=profile,
-            type=type,
-            process_status=process_status,
-            app_key=app_key,
-            node_id=node_id,
-            search_key=search_key,
-            page_num=page_num,
-            page_size=page_size,
-            create_time_asc=create_time_asc,
-        )
-
-    @server.tool()
-    def task_list_grouped(
-        profile: str = DEFAULT_PROFILE,
-        type: int = 1,
-        process_status: int = 1,
-        app_key: str | None = None,
-        node_id: int | None = None,
-        search_key: str | None = None,
-        page_num: int = 1,
-        page_size: int = 20,
-    ) -> dict:
-        return tasks.task_list_grouped(
-            profile=profile,
-            type=type,
-            process_status=process_status,
-            app_key=app_key,
-            node_id=node_id,
-            search_key=search_key,
-            page_num=page_num,
-            page_size=page_size,
-        )
-
-    @server.tool()
-    def task_statistics(profile: str = DEFAULT_PROFILE, app_key: str | None = None) -> dict:
-        return tasks.task_statistics(profile=profile, app_key=app_key)
-
-    @server.tool()
-    def task_urge(profile: str = DEFAULT_PROFILE, app_key: str = "", row_record_id: int = 0) -> dict:
-        return tasks.task_urge(profile=profile, app_key=app_key, row_record_id=row_record_id)
-
-    @server.tool(description=approvals._high_risk_tool_description(operation="approve", target="workflow task"))
-    def task_approve(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_approve(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
-
-    @server.tool(description=approvals._high_risk_tool_description(operation="reject", target="workflow task"))
-    def task_reject(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_reject(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
-
-    @server.tool()
-    def task_rollback_candidates(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        audit_node_id: int = 0,
-    ) -> dict:
-        return approvals.record_rollback_candidates(
-            profile=profile,
-            app_key=app_key,
-            apply_id=apply_id,
-            audit_node_id=audit_node_id,
-        )
-
-    @server.tool()
-    def task_rollback(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_rollback(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
-
-    @server.tool()
-    def task_transfer_candidates(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        page_size: int = 20,
-        page_num: int = 1,
-        audit_node_id: int = 0,
-        keyword: str | None = None,
-    ) -> dict:
-        return approvals.record_transfer_candidates(
-            profile=profile,
-            app_key=app_key,
-            apply_id=apply_id,
-            page_size=page_size,
-            page_num=page_num,
-            audit_node_id=audit_node_id,
-            keyword=keyword,
-        )
-
-    @server.tool()
-    def task_transfer(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_transfer(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
+    approvals.register(server)
+    tasks.register(server)
 
     return server
 

package/src/qingflow_mcp/solution/compiler/form_compiler.py

@@ -249,7 +249,7 @@ def build_question(field: dict[str, Any], temp_id: int) -> tuple[dict[str, Any],
             sub_question, next_temp_id = build_question(subfield, next_temp_id)
             sub_questions.append(sub_question)
         question["subQuestions"] = sub_questions
-        question["innerQuestions"] = deepcopy(sub_questions)
+        question["innerQuestions"] = [deepcopy(sub_questions)]
         question["queDefaultValues"] = {"queId": temp_id, "queTitle": field["label"], "queType": que_type, "values": [], "tableValues": []}
     return question, next_temp_id
 

package/src/qingflow_mcp/solution/compiler/workflow_compiler.py

@@ -36,6 +36,11 @@ def compile_workflow(entity: EntitySpec) -> dict[str, Any] | None:
     actions: list[dict[str, Any]] = []
     seen_node_ids: set[str] = set()
     created_extra_branch_lanes: set[str] = set()
+    start_node_ids = {
+        node.node_id
+        for node in workflow.nodes
+        if node.node_type == WorkflowNodeType.start
+    }
     for node in workflow.nodes:
         if node.node_type == WorkflowNodeType.start:
             seen_node_ids.add(node.node_id)
@@ -69,7 +74,7 @@ def compile_workflow(entity: EntitySpec) -> dict[str, Any] | None:
                     "auditNodeName": node.name,
                     "type": WORKFLOW_TYPE_MAP[node.node_type]["type"],
                     "dealType": WORKFLOW_TYPE_MAP[node.node_type]["dealType"],
-                    "prevNodeRef": _prev_node_ref(node, branch_lane_ref),
+                    "prevNodeRef": _prev_node_ref(node, branch_lane_ref, start_node_ids),
                     "auditUserInfos": _build_audit_user_infos(node)
                     if node.node_type in {WorkflowNodeType.audit, WorkflowNodeType.fill, WorkflowNodeType.copy}
                     else None,
@@ -100,17 +105,31 @@ def _build_audit_user_infos(node) -> dict[str, Any]:
     role_refs = assignees.get("role_refs") or []
     if role_refs:
         audit_user_infos["role_refs"] = [role_ref for role_ref in role_refs if role_ref]
+    role_entries = assignees.get("role_entries") or []
+    if role_entries:
+        audit_user_infos["role"] = [
+            {
+                "roleId": int(entry.get("roleId") or entry.get("role_id")),
+                "roleName": entry.get("roleName") or entry.get("role_name") or str(entry.get("roleId") or entry.get("role_id")),
+                "roleIcon": entry.get("roleIcon") or entry.get("role_icon") or "ex-user-outlined",
+                "beingFrontendConfig": True,
+            }
+            for entry in role_entries
+            if isinstance(entry, dict) and isinstance(entry.get("roleId") or entry.get("role_id"), int) and int(entry.get("roleId") or entry.get("role_id")) > 0
+        ]
     include_sub_departs = assignees.get("include_sub_departs")
     if include_sub_departs is not None:
         audit_user_infos["includeSubDeparts"] = bool(include_sub_departs)
     return audit_user_infos
 
 
-def _prev_node_ref(node, branch_lane_ref: str | None) -> str:
+def _prev_node_ref(node, branch_lane_ref: str | None, start_node_ids: set[str]) -> str:
     if branch_lane_ref:
         if node.parent_node_id and node.parent_node_id != node.branch_parent_id:
             return node.parent_node_id
         return branch_lane_ref
+    if node.parent_node_id in start_node_ids:
+        return "__applicant__"
     return node.parent_node_id or "__applicant__"
 
 

package/src/qingflow_mcp/solution/executor.py

@@ -415,13 +415,13 @@ class SolutionExecutor:
         current_nodes = _coerce_workflow_nodes(existing_nodes)
         existing_nodes_by_name = {
             node.get("auditNodeName"): int(node_id)
-            for node_id, node in existing_nodes.items()
+            for node_id, node in current_nodes.items()
             if isinstance(node, dict) and node.get("auditNodeName")
         }
         applicant_node_id = next(
             (
                 int(node_id)
-                for node_id, node in existing_nodes.items()
+                for node_id, node in current_nodes.items()
                 if isinstance(node, dict) and node.get("type") == 0 and node.get("dealType") == 3
             ),
             None,
@@ -429,11 +429,24 @@ class SolutionExecutor:
         if applicant_node_id is not None:
             node_artifacts.setdefault("__applicant__", applicant_node_id)
 
-        current_global_settings = self.workflow_tools.workflow_get_global_settings(profile=profile, app_key=app_key).get("result") or {}
-        global_settings = deepcopy(current_global_settings if isinstance(current_global_settings, dict) else {})
-        global_settings.update(entity.workflow_plan["global_settings"])
-        global_settings["editVersionNo"] = workflow_edit_version_no or global_settings.get("editVersionNo") or 1
-        self.workflow_tools.workflow_update_global_settings(profile=profile, app_key=app_key, payload=global_settings)
+        desired_global_settings = deepcopy(entity.workflow_plan["global_settings"])
+        explicit_global_settings = _has_explicit_workflow_global_settings(desired_global_settings)
+        current_global_settings: dict[str, Any] = {}
+        if explicit_global_settings:
+            current_global_settings = self.workflow_tools.workflow_get_global_settings(profile=profile, app_key=app_key).get("result") or {}
+        else:
+            try:
+                current_global_settings = self.workflow_tools.workflow_get_global_settings(profile=profile, app_key=app_key).get("result") or {}
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = QingflowApiError(**_coerce_nested_error_payload(error))
+                if api_error.http_status != 404:
+                    raise
+                current_global_settings = {}
+        if explicit_global_settings:
+            global_settings = deepcopy(current_global_settings if isinstance(current_global_settings, dict) else {})
+            global_settings.update(desired_global_settings)
+            global_settings["editVersionNo"] = workflow_edit_version_no or global_settings.get("editVersionNo") or 1
+            self.workflow_tools.workflow_update_global_settings(profile=profile, app_key=app_key, payload=global_settings)
         for action in entity.workflow_plan["actions"]:
             if action["action"] == "create_sub_branch" and node_artifacts.get(action["node_id"]) is not None:
                 continue
@@ -2046,6 +2059,20 @@ def _find_created_sub_branch_lane_id(
     return candidates[0] if candidates else None
 
 
+def _has_explicit_workflow_global_settings(global_settings: dict[str, Any] | None) -> bool:
+    if not isinstance(global_settings, dict):
+        return False
+    for key, value in global_settings.items():
+        if key == "editVersionNo":
+            continue
+        if value is None:
+            continue
+        if isinstance(value, (list, dict)) and not value:
+            continue
+        return True
+    return False
+
+
 def _is_navigation_plugin_unavailable(error: QingflowApiError) -> bool:
     try:
         backend_code = int(error.backend_code)