@josephyan/qingflow-app-user-mcp 0.2.0-beta.24 → 0.2.0-beta.26

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.24",
+  "version": "0.2.0-beta.26",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/skills/qingflow-app-user/SKILL.md

@@ -41,6 +41,7 @@ Route to exactly one of these specialized paths:
 
 ## Routing Rules
 
+- If the user does not know the target `app_key`, discover apps first with `app_list` or `app_search`, then route to the specialized skill
 - If the task is about browsing, reading, creating, updating, deleting, attachments, relations, or subtable writes, switch to `$qingflow-record-crud`
 - If the task is about inbox, todo, cc, task-center workload, comments, approval, reject, rollback, transfer, urge, or directory lookup, switch to `$qingflow-task-ops`
 - If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`

package/skills/qingflow-record-analysis/SKILL.md

@@ -7,15 +7,21 @@ metadata:
 
 # Qingflow Record Analysis
 
+Analysis tasks must start with `record_schema_get`.
+Use field_id-based DSLs only.
+
 ## Step 1: `record_schema_get` → Step 2: build DSL → Step 3: `record_analyze`
 
 This is the ONLY execution order. Never skip step 1. Never call `record_analyze` without a schema.
 
-Tools: `record_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for sample rows AFTER analysis.
+Tools: `record_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for sample rows AFTER analysis, and treat those read paths as belonging to [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md).
+Comments, approvals, rollback, transfer, urge, and directory lookup stay in [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md), not in this analysis skill.
 
 ---
 
-## DSL FORMAT (CRITICAL — read this FIRST)
+## DSL Contract
+
+### DSL FORMAT (CRITICAL — read this FIRST)
 
 ### ✅ Correct vs ❌ Wrong — learn from these before building ANY DSL
 
@@ -130,6 +136,20 @@ More templates:
 
 ## RULES
 
+- Normalize relative time phrases into explicit legal date ranges.
+- 渗透率 / 转化率 / 占比类结论必须先定义分子和分母。
+- Do not claim a metric you did not query.
+- Derived ratios must be computed outside the DSL.
+- Before choosing a DSL shape, first decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`.
+- If a field is still ambiguous after `record_schema_get`, do not guess; ask the user to confirm from a short candidate list.
+- Rankings must come from structured sorted results.
+- For partial answers, explicitly disclose which parts are complete and which parts remain unresolved.
+- Complex answers should default to `先结构、后解读`.
+- `between`: pass a two-item array.
+- Sort entries must reference an alias already defined in `dimensions` or `metrics`.
+- Final wording should stay as close as possible to schema titles.
+- Do not pass field titles, aliases, or guessed ids.
+- If `completeness.statement_scope=returned_groups_only` or `completeness.rows_truncated=true`, downgrade wording to returned groups only.
 - All `field_id` MUST come from `record_schema_get`. Never guess or use field titles.
 - One DSL per question. Multiple small DSLs > one overloaded request.
 - Normalize relative dates to concrete ranges BEFORE building DSL. Never send impossible dates (e.g. `2026-02-29`).

package/skills/qingflow-record-crud/SKILL.md

@@ -63,6 +63,8 @@ Use exactly one of these default paths:
 
 ## Supporting Tools
 
+- `app_list`
+- `app_search`
 - `directory_search`
 - `directory_list_internal_users`
 - `directory_list_internal_departments`
@@ -75,12 +77,13 @@ Use exactly one of these default paths:
 1. Ensure auth exists
 2. Ensure workspace is selected
 3. Confirm target app and whether the task is browse / detail / write / analysis
-4. Run `record_schema_get` before any non-trivial record read or write
-5. If the request is analysis-like, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
-6. If the request is write-like, decide `insert / update / delete` before building any payload
-7. If fields are still ambiguous after `record_schema_get`, ask the user to confirm from a short candidate list instead of guessing
-8. For high-risk writes or production changes, read the current state first whenever practical
-9. After actions, report the affected `record_id`, counts, or returned item count
+4. If `app_key` is unknown, use `app_list` or `app_search` first
+5. Run `record_schema_get` before any non-trivial record read or write
+6. If the request is analysis-like, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+7. If the request is write-like, decide `insert / update / delete` before building any payload
+8. If fields are still ambiguous after `record_schema_get`, ask the user to confirm from a short candidate list instead of guessing
+9. For high-risk writes or production changes, read the current state first whenever practical
+10. After actions, report the affected `record_id`, counts, or returned item count
 
 ## Record Read Rules
 

package/src/qingflow_mcp/__init__.py

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

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/directory_tools.py

@@ -303,15 +303,57 @@ class DirectoryTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> dict[str, Any]:
-        if not keyword:
-            raise_tool_error(QingflowApiError.config_error("keyword is required"))
+        if page_num <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
+        if page_size <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+        normalized_keyword = keyword.strip()
+
+        if not normalized_keyword:
+            def runner(session_profile, context):
+                fetch_limit = max((page_num + 1) * page_size + 1, page_size + 1)
+                items, truncated, deepest_depth = self._walk_department_tree(
+                    context,
+                    parent_dept_id=None,
+                    max_depth=20,
+                    max_items=fetch_limit,
+                )
+                start = (page_num - 1) * page_size
+                page_items = items[start : start + page_size]
+                reported_total = None if truncated else len(items)
+                page_amount = None if truncated else ((len(items) + page_size - 1) // page_size if items else 0)
+                if truncated and page_items:
+                    page_amount = max(page_num + 1, (start + len(page_items) + page_size - 1) // page_size)
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "request_route": self._request_route_payload(context),
+                    "items": page_items,
+                    "pagination": {
+                        "page": page_num,
+                        "page_size": page_size,
+                        "returned_items": len(page_items),
+                        "reported_total": reported_total,
+                        "page_amount": page_amount,
+                        "depth_scanned": deepest_depth + 1 if page_items else 0,
+                    },
+                }
+
+            raw = self._run(profile, runner)
+            items = [item for item in raw.get("items", []) if isinstance(item, dict)]
+            return self._public_directory_response(
+                raw,
+                items=items,
+                pagination=raw.get("pagination", {}),
+                selection={"keyword": None},
+            )
 
         def runner(session_profile, context):
             result = self.backend.request(
                 "GET",
                 context,
                 "/contact/deptByPage",
-                params={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
+                params={"keyword": normalized_keyword, "pageNum": page_num, "pageSize": page_size},
             )
             return {
                 "profile": profile,
@@ -332,7 +374,7 @@ class DirectoryTools(ToolBase):
                 "reported_total": _coerce_int(_payload_value(raw.get("page"), "total")),
                 "page_amount": _coerce_int(_payload_value(raw.get("page"), "pageAmount")),
             },
-            selection={"keyword": keyword},
+            selection={"keyword": normalized_keyword},
         )
 
     def directory_list_all_departments(

package/src/qingflow_mcp/tools/record_tools.py

@@ -1156,8 +1156,12 @@ class RecordTools(ToolBase):
                         details={"location": f"metrics[{idx}]", "field": _field_ref_payload(field), "op": op},
                     )
             elif item.get("field_id", item.get("fieldId")) is not None:
-                # LLM 经常给 count 传 field_id，静默忽略而非报错
-                pass
+                raise RecordInputError(
+                    message=f"metrics[{idx}] with op 'count' must not include field_id",
+                    error_code="INVALID_ANALYZE_METRIC",
+                    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"))
             if alias is None:
                 if op == "count":
@@ -1682,6 +1686,9 @@ class RecordTools(ToolBase):
         support_matrix = _summarize_write_support(resolved_fields)
         invalid_fields: list[JSONObject] = []
         normalized_answers: list[JSONObject] = []
+        validation_warnings = [
+            "record_write performs static preflight from form metadata before apply; runtime visibility and dynamic linkage can still reject writes."
+        ]
         try:
             normalized_answers = self._resolve_answers(
                 profile,
@@ -1702,6 +1709,16 @@ class RecordTools(ToolBase):
                     "received_value": error.details.get("received_value") if error.details else None,
                 }
             )
+        validation_answers = normalized_answers
+        if operation == "update" and apply_id is not None and not invalid_fields:
+            try:
+                existing_answers = self._load_record_answers_for_preflight(context, app_key=app_key, apply_id=apply_id)
+            except QingflowApiError:
+                validation_warnings.append(
+                    "update preflight could not load the current record; required-field completeness was not revalidated."
+                )
+            else:
+                validation_answers = self._merge_record_answers(existing_answers, normalized_answers)
         readonly_or_system_fields = [
             {
                 "que_id": entry.get("que_id"),
@@ -1717,8 +1734,9 @@ class RecordTools(ToolBase):
         ]
         provided_field_ids = {
             str(answer.get("queId"))
-            for answer in normalized_answers
+            for answer in validation_answers
             if isinstance(answer.get("queId"), int) and int(answer["queId"]) > 0
+            and _answer_has_meaningful_content(answer)
         }
         missing_required_fields = []
         for field in index.by_id.values():
@@ -1734,9 +1752,6 @@ class RecordTools(ToolBase):
             )
         question_relations = _collect_question_relations(schema)
         option_links = _collect_option_links(resolved_fields)
-        validation_warnings = [
-            "record_write performs static preflight from form metadata before apply; runtime visibility and dynamic linkage can still reject writes."
-        ]
         if question_relations:
             validation_warnings.append(
                 "form contains questionRelations; linked visibility and runtime required rules may differ at submit time."
@@ -1791,6 +1806,39 @@ class RecordTools(ToolBase):
             "recommended_next_actions": actions,
         }
 
+    def _load_record_answers_for_preflight(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+    ) -> list[JSONObject]:
+        record = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/apply/{apply_id}",
+            params={"role": 1, "listType": DEFAULT_RECORD_LIST_TYPE},
+        )
+        answers = record.get("answers") if isinstance(record, dict) else None
+        return [item for item in answers if isinstance(item, dict)] if isinstance(answers, list) else []
+
+    def _merge_record_answers(
+        self,
+        existing_answers: list[JSONObject],
+        patch_answers: list[JSONObject],
+    ) -> list[JSONObject]:
+        merged_by_id: dict[int, JSONObject] = {}
+        order: list[int] = []
+        for source in (existing_answers, patch_answers):
+            for item in source:
+                que_id = _coerce_count(item.get("queId")) if isinstance(item, dict) else None
+                if que_id is None or que_id <= 0:
+                    continue
+                if que_id not in merged_by_id:
+                    order.append(que_id)
+                merged_by_id[que_id] = item
+        return [merged_by_id[que_id] for que_id in order]
+
     def record_query(
         self,
         *,
@@ -3942,6 +3990,26 @@ def _normalize_audit_nodes(payload: JSONValue) -> list[JSONObject]:
     return []
 
 
+def _answer_has_meaningful_content(answer: JSONObject) -> bool:
+    table_values = answer.get("tableValues")
+    if isinstance(table_values, list) and table_values:
+        for row in table_values:
+            if isinstance(row, list) and any(_answer_has_meaningful_content(item) for item in row if isinstance(item, dict)):
+                return True
+        return False
+    values = answer.get("values")
+    if not isinstance(values, list) or not values:
+        return False
+    for item in values:
+        if isinstance(item, dict):
+            if any(value not in (None, "", [], {}) for value in item.values()):
+                return True
+            continue
+        if item not in (None, "", [], {}):
+            return True
+    return False
+
+
 def _extract_applicant_node(payload: JSONValue) -> WorkflowNodeRef | None:
     for item in _normalize_audit_nodes(payload):
         node_type = _coerce_count(item.get("type"))