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

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.25
 ```
 
 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.25 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.25",
   "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.0b25"
 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.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

@@ -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":