@josephyan/qingflow-app-builder-mcp 0.2.0-beta.23 → 0.2.0-beta.25

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.23
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.25
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.23 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.25 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.23",
+  "version": "0.2.0-beta.25",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b23"
+version = "0.2.0b25"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b23"
+__version__ = "0.2.0b25"

package/src/qingflow_mcp/server.py

@@ -28,6 +28,7 @@ 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"
+            "If app_key is unknown, use app_list or app_search first to discover current-user visible apps in the selected workspace. "
             "For analytics, use record_schema_get first, let the model build field_id-based DSL, "
             "then call record_analyze. record_analyze returns compact business-first output as query/result/ranking/ratios/completeness/presentation; use verbose only for route/debug details. "
             "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "

package/src/qingflow_mcp/server_app_user.py

@@ -6,6 +6,7 @@ from .backend_client import BackendClient
 from .config import DEFAULT_PROFILE
 from .session_store import SessionStore
 from .tools.approval_tools import ApprovalTools
+from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
 from .tools.directory_tools import DirectoryTools
 from .tools.file_tools import FileTools
@@ -19,6 +20,7 @@ def build_user_server() -> FastMCP:
         "Qingflow App User MCP",
         instructions=(
             "Use this server for Qingflow operational workflows with a schema-first path. "
+            "If app_key is unknown, use app_list or app_search first to discover current-user visible apps in the selected workspace. "
             "For records, start with record_schema_get, then choose record_list, record_get, or record_write. "
             "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
             "For analytics, switch to record_schema_get and record_analyze; its default output is compact query/result/ranking/ratios/completeness/presentation, with route/debug only in verbose mode. "
@@ -29,6 +31,7 @@ def build_user_server() -> FastMCP:
     sessions = SessionStore()
     backend = BackendClient()
     auth = AuthTools(sessions, backend)
+    apps = AppTools(sessions, backend)
     workspace = WorkspaceTools(sessions, backend)
     files = FileTools(sessions, backend)
     approvals = ApprovalTools(sessions, backend)
@@ -96,6 +99,14 @@ def build_user_server() -> FastMCP:
     def workspace_select(profile: str = DEFAULT_PROFILE, ws_id: int = 0) -> dict:
         return workspace.workspace_select(profile=profile, ws_id=ws_id)
 
+    @server.tool()
+    def app_list(profile: str = DEFAULT_PROFILE) -> dict:
+        return apps.app_list(profile=profile)
+
+    @server.tool()
+    def app_search(profile: str = DEFAULT_PROFILE, keyword: str = "", page_num: int = 1, page_size: int = 50) -> dict:
+        return apps.app_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+
     @server.tool()
     def file_get_upload_info(
         profile: str = DEFAULT_PROFILE,

package/src/qingflow_mcp/tools/app_tools.py

@@ -76,14 +76,20 @@ class AppTools(ToolBase):
             return self.app_publish(profile=profile, app_key=app_key, payload=payload or {})
 
     def app_list(self, *, profile: str, ship_auth: bool = False) -> JSONObject:
-        """Get all apps with full hierarchy from tag/apps endpoint."""
+        """List current-user visible apps in the selected workspace."""
         def runner(session_profile, context):
             result = self.backend.request("GET", context, "/tag/apps")
-            return {
+            items, source_shape = self._extract_visible_apps(result)
+            response = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
-                "items": result,
+                "items": items,
+                "count": len(items),
+                "source_shape": source_shape,
             }
+            if ship_auth:
+                response["raw"] = result
+            return response
 
         return self._run(profile, runner)
 
@@ -98,19 +104,20 @@ class AppTools(ToolBase):
             
             result = self.backend.request("GET", context, "/app/item", params=params)
             
-            # Extract app list from the response
             apps = []
             if isinstance(result, dict):
                 items = result.get("list", [])
                 for item in items:
                     if isinstance(item, dict):
-                        apps.append({
-                            "app_key": item.get("appKey"),
-                            "title": item.get("title") or item.get("formTitle"),
-                            "form_id": item.get("formId"),
-                            "tag_id": item.get("tagId"),
-                            "group_id": item.get("groupId"),
-                        })
+                        normalized = self._normalize_visible_app(
+                            item,
+                            package_tag_id=_coerce_positive_int(item.get("tagId")),
+                            package_name=str(item.get("tagName") or "").strip() or None,
+                            group_id=_coerce_positive_int(item.get("groupId")),
+                            group_name=str(item.get("groupName") or "").strip() or None,
+                        )
+                        if normalized is not None:
+                            apps.append(normalized)
             
             return {
                 "profile": profile,
@@ -119,6 +126,7 @@ class AppTools(ToolBase):
                 "page_num": page_num,
                 "page_size": page_size,
                 "total": result.get("total") if isinstance(result, dict) else len(apps),
+                "items": apps,
                 "apps": apps,
             }
 
@@ -424,6 +432,88 @@ class AppTools(ToolBase):
         }
         return {key: value for key, value in compact.items() if value is not None}
 
+    def _extract_visible_apps(self, result: Any) -> tuple[list[JSONObject], str]:
+        apps: list[JSONObject] = []
+        seen: set[str] = set()
+
+        def walk(
+            node: Any,
+            *,
+            package_tag_id: int | None = None,
+            package_name: str | None = None,
+            group_id: int | None = None,
+            group_name: str | None = None,
+        ) -> None:
+            if isinstance(node, list):
+                for item in node:
+                    walk(
+                        item,
+                        package_tag_id=package_tag_id,
+                        package_name=package_name,
+                        group_id=group_id,
+                        group_name=group_name,
+                    )
+                return
+            if not isinstance(node, dict):
+                return
+
+            next_package_tag_id = _coerce_positive_int(node.get("tagId")) or package_tag_id
+            next_package_name = str(node.get("tagName") or "").strip() or package_name
+            next_group_id = _coerce_positive_int(node.get("groupId")) or group_id
+            next_group_name = str(node.get("groupName") or node.get("groupTitle") or "").strip() or group_name
+
+            normalized = self._normalize_visible_app(
+                node,
+                package_tag_id=next_package_tag_id,
+                package_name=next_package_name,
+                group_id=next_group_id,
+                group_name=next_group_name,
+            )
+            if normalized is not None:
+                app_key = str(normalized.get("app_key") or "").strip()
+                if app_key and app_key not in seen:
+                    seen.add(app_key)
+                    apps.append(normalized)
+
+            for value in node.values():
+                if isinstance(value, (list, dict)):
+                    walk(
+                        value,
+                        package_tag_id=next_package_tag_id,
+                        package_name=next_package_name,
+                        group_id=next_group_id,
+                        group_name=next_group_name,
+                    )
+
+        walk(result)
+        return apps, type(result).__name__
+
+    def _normalize_visible_app(
+        self,
+        item: dict[str, Any],
+        *,
+        package_tag_id: int | None,
+        package_name: str | None,
+        group_id: int | None,
+        group_name: str | None,
+    ) -> JSONObject | None:
+        app_key = str(item.get("appKey") or item.get("app_key") or "").strip()
+        if not app_key:
+            return None
+        title = str(item.get("title") or item.get("formTitle") or item.get("appName") or item.get("name") or app_key).strip() or app_key
+        tag_ids = item.get("tagIds") if isinstance(item.get("tagIds"), list) else []
+        compact = {
+            "app_key": app_key,
+            "title": title,
+            "form_id": item.get("formId"),
+            "tag_id": package_tag_id,
+            "package_name": package_name,
+            "group_id": group_id,
+            "group_name": group_name,
+            "tag_ids": [value for value in (_coerce_positive_int(tag_id) for tag_id in tag_ids) if value is not None],
+        }
+        return {key: value for key, value in compact.items() if value not in (None, [], "", {})}
+
     def _count_auth_members(self, auth_payload: Any, member_key: str) -> int:
         if not isinstance(auth_payload, dict):
             return 0
@@ -470,3 +560,11 @@ def _normalize_form_type(value: int | str) -> int:
     if text in FORM_TYPE_ALIASES:
         return FORM_TYPE_ALIASES[text]
     raise_tool_error(QingflowApiError.config_error("form_type must be a positive integer or one of: default, form, schema, new, draft, edit"))
+
+
+def _coerce_positive_int(value: Any) -> int | None:
+    try:
+        number = int(value)
+    except (TypeError, ValueError):
+        return None
+    return number if number > 0 else None

package/src/qingflow_mcp/tools/record_tools.py

@@ -38,6 +38,7 @@ ATTACHMENT_QUE_TYPES = {13}
 RELATION_QUE_TYPES = {25}
 SUBTABLE_QUE_TYPES = {18}
 VERIFY_UNSUPPORTED_WRITE_QUE_TYPES = {14, 34, 35, 36}
+LAYOUT_ONLY_QUE_TYPES = {24}
 DEPARTMENT_MEMBER_JUDGE_PREFIX = "deptId_"
 JUDGE_EQUAL = 0
 JUDGE_UNEQUAL = 1
@@ -1131,10 +1132,12 @@ class RecordTools(ToolBase):
             self._ensure_allowed_analyze_keys(
                 item,
                 location=f"metrics[{idx}]",
-                allowed_keys={"op", "field_id", "fieldId", "alias"},
+                allowed_keys={"op", "type", "agg", "aggregation", "field_id", "fieldId", "alias"},
                 example="{'op': 'sum', 'field_id': 7, 'alias': '总金额'}",
             )
-            op = _normalize_optional_text(item.get("op"))
+            op = _normalize_optional_text(
+                item.get("op") or item.get("type") or item.get("agg") or item.get("aggregation")
+            )
             if op not in supported_ops:
                 raise RecordInputError(
                     message=f"metrics[{idx}] uses unsupported op '{op}'",
@@ -1156,7 +1159,7 @@ class RecordTools(ToolBase):
                 raise RecordInputError(
                     message=f"metrics[{idx}] with op 'count' must not include field_id",
                     error_code="INVALID_ANALYZE_METRIC",
-                    fix_hint="Remove field_id from count metrics.",
+                    fix_hint="For count, omit field_id and use only {'op': 'count', 'alias': '记录数'}.",
                     details={"location": f"metrics[{idx}]", "op": op},
                 )
             alias = _normalize_optional_text(item.get("alias"))
@@ -3995,16 +3998,19 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
         *[(question, False) for question in _flatten_questions(schema.get("formQues"))],
     ]
     for question, is_base_question in all_questions:
+        if not _should_index_question(question):
+            continue
         que_id = _coerce_count(question.get("queId"))
         title = _stringify_json(question.get("queTitle")).strip()
         if que_id is None or que_id < 0 or not title:
             continue
+        can_edit = question.get("canEdit")
         field = FormField(
             que_id=que_id,
             que_title=title,
             que_type=_coerce_count(question.get("queType")),
             required=bool(question.get("required") or question.get("beingRequired")),
-            readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question),
+            readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question or can_edit is False),
             system=bool(question.get("system") or question.get("beingSystem") or is_base_question),
             options=_extract_question_options(question),
             aliases=[],
@@ -4023,16 +4029,35 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
 def _flatten_questions(payload: JSONValue) -> list[JSONObject]:
     flattened: list[JSONObject] = []
     if isinstance(payload, dict):
-        if "queId" in payload or "queTitle" in payload:
+        is_question = "queId" in payload or "queTitle" in payload
+        if is_question:
             flattened.append(payload)
-        for value in payload.values():
-            flattened.extend(_flatten_questions(value))
+        for key in ("subQuestions", "innerQuestions", "subQues"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                flattened.extend(_flatten_questions(value))
+        if not is_question:
+            for key in ("baseQues", "formQues"):
+                value = payload.get(key)
+                if isinstance(value, list):
+                    flattened.extend(_flatten_questions(value))
     elif isinstance(payload, list):
         for item in payload:
             flattened.extend(_flatten_questions(item))
     return flattened
 
 
+def _should_index_question(question: JSONObject) -> bool:
+    if bool(question.get("beingHide") or question.get("hidden")):
+        return False
+    if _coerce_count(question.get("quoteId")) is not None:
+        return False
+    que_type = _coerce_count(question.get("queType"))
+    if que_type in LAYOUT_ONLY_QUE_TYPES:
+        return False
+    return True
+
+
 def _extract_question_options(question: JSONObject) -> list[str]:
     options = question.get("options")
     if not isinstance(options, list):