@josephyan/qingflow-app-user-mcp 0.2.0-beta.35 → 0.2.0-beta.37

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.35",
+  "version": "0.2.0-beta.37",
   "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.0b35"
+version = "0.2.0b37"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -31,6 +31,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 app is known but the available data range is unclear, call `app_get` first and inspect `accessible_views`
 - If the task is about browsing, reading, creating, updating, deleting, attachments, relations, subtable writes, or member/department-field candidate lookup, switch to `$qingflow-record-crud`
 - If the task is about todo discovery, task context, approval actions, rollback or transfer, associated report review, or workflow log review, 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

@@ -9,13 +9,15 @@ metadata:
 
 This skill is for final statistical conclusions only.
 Assumes MCP is connected, authenticated, and on the correct workspace.
-Analysis tasks must start with `record_schema_get`. Read top-level `fields` and `suggested_*`, then build field_id-based DSLs only.
+Analysis tasks must start with `app_get`, then `record_schema_get(schema_mode="browse", view_id=...)`. Read top-level `fields` and `suggested_*`, then build field_id-based DSLs only.
+Analysis tasks must start with `record_schema_get`.
+If `app_get.accessible_views` marks a view with `analysis_supported=false`, do not use that view for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
 
-## Step 1: `record_schema_get` → Step 2: build DSL → Step 3: `record_analyze`
+## Step 1: `app_get` → Step 2: `record_schema_get(schema_mode="browse", view_id=...)` → Step 3: build DSL → Step 4: `record_analyze`
 
-This is the ONLY execution order. Never skip step 1. Never call `record_analyze` without a schema.
+This is the ONLY execution order. Never skip `app_get` when the browse range is unclear. Never call `record_analyze` without a browse schema.
 
-Core tools: `record_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for post-analysis samples; task/comment work stays in [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md).
+Core tools: `app_get`, `record_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for post-analysis samples; task/comment work stays in [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md).
 
 ---
 
@@ -105,7 +107,8 @@ Top-level arguments:
 - `dimensions`: `[]` = whole-table summary; `[{...}]` = grouped.
 - `strict_full`: `true` for final conclusions. `false` allows partial results.
 - `limit`: limits returned rows only, not scan scope.
-- `view_key`/`view_name`: optional scope narrowing.
+- `view_id`: the canonical browse selector. Prefer choosing it from `app_get.accessible_views`.
+- Prefer `view_id` entries where `analysis_supported=true`. If a view is `boardView` or `ganttView`, switch to a system or table-style custom view before calling `record_analyze`.
 - `bucket` in dimensions: only for `suggested_time_fields`. Values: `day`/`week`/`month`/`quarter`/`year`/`null`.
 
 ---

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

@@ -16,9 +16,9 @@ Assumes MCP is connected, authenticated, and on the correct workspace.
 
 Use exactly one of these default paths:
 
-1. Browse records: `record_schema_get -> record_list`
-2. Read one record: `record_schema_get -> record_get`
-3. Write records: `record_schema_get -> record_write`
+1. Browse records: `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list`
+2. Read one record: `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_get`
+3. Write records: `record_schema_get(schema_mode="applicant") -> record_write`
 
 ## Core Tools
 
@@ -27,12 +27,15 @@ Use exactly one of these default paths:
 - `record_get`
 - `record_write`
 
-`record_schema_get` only exposes the current user's applicant-node visible fields. Read top-level `fields` and `suggested_*`; if a field is missing, treat it as unavailable in the current permission scope.
+`record_schema_get(schema_mode="applicant")` exposes the current user's applicant-node visible write/create fields.
+`record_schema_get(schema_mode="browse", view_id=...)` exposes browse-schema fields for the selected accessible view.
+Read top-level `fields` and `suggested_*`; if a field is missing, treat it as unavailable in the current permission scope.
 
 ## Supporting Tools
 
 - `app_list`
 - `app_search`
+- `app_get`
 - `record_member_candidates`
 - `record_department_candidates`
 - `directory_search`
@@ -50,7 +53,9 @@ Use `record_member_candidates` / `record_department_candidates` as the default l
 2. Ensure workspace is selected
 3. Confirm target app and whether the task is browse / detail / write / analysis
 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
+5. If browse/read range is unclear, run `app_get` and choose from `accessible_views`
+6. Run `record_schema_get(schema_mode="browse", view_id=...)` before browse/read
+7. Run `record_schema_get(schema_mode="applicant")` before 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
@@ -60,6 +65,7 @@ Use `record_member_candidates` / `record_department_candidates` as the default l
 ## Record Read Rules
 
 - Use `record_list` for browse/export/sample inspection only
+- Prefer choosing a `view_id` from `app_get.accessible_views`
 - For `columns`, use `[{ "field_id": 12 }]`
 - For `where`, use `{ "field_id": 12, "op": "eq", "value": "进行中" }`
 - For `order_by`, use `{ "field_id": 18, "direction": "desc" }`
@@ -73,7 +79,7 @@ Use `record_write` as the only default write tool.
 
 ### Write workflow
 
-1. Run `record_schema_get`
+1. Run `record_schema_get(schema_mode="applicant")`
 2. Decide whether the task is `insert`, `update`, or `delete`
 3. For relation fields, read `target_app_key / target_app_name` from schema first
 4. For member fields with unknown ids, run `record_member_candidates`

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/config.py

@@ -13,6 +13,7 @@ DEFAULT_RECORD_LIST_TYPE = 8
 ATTACHMENT_QUESTION_TYPE = 13
 DEFAULT_BASE_URL = "https://qingflow.com/api"
 DEFAULT_FEEDBACK_APP_KEY = "e0d017kju002"
+DEFAULT_FEEDBACK_QSOURCE_TOKEN = "mcp-feedback-7755d14748fc"
 
 
 def get_mcp_home() -> Path:
@@ -142,7 +143,7 @@ def get_feedback_qsource_token() -> str | None:
     value = get_config_value(
         "feedback.qsource_token",
         env_var="QINGFLOW_MCP_FEEDBACK_QSOURCE_TOKEN",
-        default=None,
+        default=DEFAULT_FEEDBACK_QSOURCE_TOKEN,
     )
     if value is None:
         return None

package/src/qingflow_mcp/list_type_labels.py

@@ -20,6 +20,18 @@ RECORD_LIST_TYPE_LABELS: dict[int, str] = {
     16: "我发起的-已结束",
 }
 
+SYSTEM_VIEW_DEFINITIONS: tuple[tuple[str, int, str], ...] = (
+    ("system:all", 8, "全部数据"),
+    ("system:initiated", 14, "我发起的"),
+    ("system:todo", 1, "待办"),
+    ("system:done", 2, "已办"),
+    ("system:cc", 12, "抄送我的"),
+)
+
+SYSTEM_VIEW_ID_TO_LIST_TYPE: dict[str, int] = {view_id: list_type for view_id, list_type, _ in SYSTEM_VIEW_DEFINITIONS}
+SYSTEM_VIEW_ID_TO_NAME: dict[str, str] = {view_id: name for view_id, _, name in SYSTEM_VIEW_DEFINITIONS}
+SYSTEM_LIST_TYPE_TO_VIEW_ID: dict[int, str] = {list_type: view_id for view_id, list_type, _ in SYSTEM_VIEW_DEFINITIONS}
+
 TASK_TYPE_LABELS: dict[int, str] = {
     1: "待办",
     2: "我发起的",
@@ -40,6 +52,18 @@ def get_record_list_type_label(list_type: int | None) -> str | None:
     return RECORD_LIST_TYPE_LABELS.get(list_type)
 
 
+def get_system_view_id(list_type: int | None) -> str | None:
+    if list_type is None:
+        return None
+    return SYSTEM_LIST_TYPE_TO_VIEW_ID.get(list_type)
+
+
+def get_system_view_name(view_id: str | None) -> str | None:
+    if view_id is None:
+        return None
+    return SYSTEM_VIEW_ID_TO_NAME.get(view_id)
+
+
 def get_task_type_label(type_value: int | None) -> str | None:
     if type_value is None:
         return None

package/src/qingflow_mcp/server.py

@@ -47,17 +47,21 @@ All resource tools operate with the logged-in user's Qingflow permissions.
 ## App Discovery
 
 If `app_key` is unknown, use `app_list` or `app_search` first.
+If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
+If an accessible view has `analysis_supported=false`, do not use it for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
 
 ## Schema-First Rule
 
-Always call `record_schema_get` before `record_list`, `record_get`, `record_write`, or `record_analyze`.
+Call `record_schema_get(schema_mode="applicant")` before `record_write`.
+Call `app_get` first when the data range is unclear, then use `record_schema_get(schema_mode="browse", view_id=...)` before `record_list`, `record_get`, or `record_analyze`.
 
 - All `field_id` values must come from the schema response.
 - Never guess field names or ids.
 
 ## Schema Scope
 
-`record_schema_get` returns the current user's applicant-node visible fields only.
+`record_schema_get(schema_mode="applicant")` returns the current user's applicant-node visible fields for write/create.
+`record_schema_get(schema_mode="browse", view_id=...)` returns browse-schema fields for the selected accessible view.
 
 - Hidden fields are omitted.
 - Missing fields mean the field is not visible in the current permission scope.
@@ -65,7 +69,9 @@ Always call `record_schema_get` before `record_list`, `record_get`, `record_writ
 
 ## Analytics Path
 
-`record_schema_get -> record_analyze`
+`app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_analyze`
+
+Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
 
 Use this DSL shape:
 
@@ -86,7 +92,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 ## Record CRUD Path
 
-`record_schema_get -> record_list / record_get / record_write`
+`app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list / record_get`
+`record_schema_get(schema_mode="applicant") -> record_write`
 
 - Use `columns` as `[{{field_id}}]`
 - Use `where` items as `{{field_id, op, value}}`

package/src/qingflow_mcp/server_app_user.py

@@ -27,6 +27,8 @@ def build_user_server() -> FastMCP:
 ## App Discovery
 
 If `app_key` is unknown, use `app_list` or `app_search` first.
+If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
+If an accessible view has `analysis_supported=false`, do not use it for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
 
 ## Shared Helper
 
@@ -38,14 +40,16 @@ If `app_key` is unknown, use `app_list` or `app_search` first.
 
 ## Schema-First Rule
 
-Always call `record_schema_get` before `record_list`, `record_get`, `record_write`, or `record_analyze`.
+Call `record_schema_get(schema_mode="applicant")` before `record_write`.
+Call `app_get` first when the data range is unclear, then use `record_schema_get(schema_mode="browse", view_id=...)` before `record_list`, `record_get`, or `record_analyze`.
 
 - All `field_id` values must come from the schema response.
 - Never guess field names or ids.
 
 ## Schema Scope
 
-`record_schema_get` returns the current user's applicant-node visible fields only.
+`record_schema_get(schema_mode="applicant")` returns the current user's applicant-node visible fields for write/create.
+`record_schema_get(schema_mode="browse", view_id=...)` returns browse-schema fields for the selected accessible view.
 
 - Hidden fields are omitted.
 - Missing fields mean the field is not visible in the current permission scope.
@@ -53,7 +57,9 @@ Always call `record_schema_get` before `record_list`, `record_get`, `record_writ
 
 ## Analytics Path
 
-`record_schema_get -> record_analyze`
+`app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_analyze`
+
+Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
 
 Use this DSL shape:
 
@@ -74,7 +80,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 ## Record CRUD Path
 
-`record_schema_get -> record_list / record_get / record_write`
+`app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list / record_get`
+`record_schema_get(schema_mode="applicant") -> record_write`
 
 - Use `columns` as `[{{field_id}}]`
 - Use `where` items as `{{field_id, op, value}}`
@@ -201,6 +208,10 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     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 app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return apps.app_get(profile=profile, app_key=app_key)
+
     @server.tool()
     def file_get_upload_info(
         profile: str = DEFAULT_PROFILE,

package/src/qingflow_mcp/tools/app_tools.py

@@ -9,7 +9,7 @@ from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
-from ..list_type_labels import get_app_publish_status_label
+from ..list_type_labels import SYSTEM_VIEW_DEFINITIONS, get_app_publish_status_label
 from .base import ToolBase
 
 
@@ -23,6 +23,10 @@ class AppTools(ToolBase):
         def app_search(profile: str = DEFAULT_PROFILE, keyword: str = "", page_num: int = 1, page_size: int = 50) -> JSONObject:
             return self.app_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
 
+        @mcp.tool()
+        def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
+            return self.app_get(profile=profile, app_key=app_key)
+
         @mcp.tool()
         def app_get_base(profile: str = DEFAULT_PROFILE, app_key: str = "", include_raw: bool = False) -> JSONObject:
             return self.app_get_base(profile=profile, app_key=app_key, include_raw=include_raw)
@@ -132,6 +136,50 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    def app_get(self, *, profile: str, app_key: str) -> JSONObject:
+        self._require_app_key(app_key)
+
+        def runner(session_profile, context):
+            warnings: list[JSONObject] = []
+            app_name = app_key
+
+            try:
+                base_info = self.backend.request("GET", context, f"/app/{app_key}/baseInfo")
+                if isinstance(base_info, dict):
+                    app_name = (
+                        str(base_info.get("formTitle") or base_info.get("title") or base_info.get("appName") or app_key).strip()
+                        or app_key
+                    )
+            except QingflowApiError as exc:
+                if exc.backend_code not in {40002, 40027}:
+                    raise
+                warnings.append(
+                    {
+                        "code": "APP_BASE_INFO_UNAVAILABLE",
+                        "message": f"app_get could not load base info for {app_key}; using app_key as app_name.",
+                    }
+                )
+
+            can_create = self._probe_create_access(context, app_key)
+            accessible_views = self._resolve_accessible_system_views(context, app_key)
+            accessible_views.extend(self._resolve_accessible_custom_views(context, app_key))
+
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "request_route": {"base_url": context.base_url, "qf_version": context.qf_version},
+                "warnings": warnings,
+                "data": {
+                    "app_key": app_key,
+                    "app_name": app_name,
+                    "can_create": can_create,
+                    "accessible_views": accessible_views,
+                },
+            }
+
+        return self._run(profile, runner)
+
     def app_get_base(self, *, profile: str, app_key: str, include_raw: bool = False) -> JSONObject:
         self._require_app_key(app_key)
 
@@ -313,6 +361,67 @@ class AppTools(ToolBase):
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
+    def _probe_create_access(self, context: BackendRequestContext, app_key: str) -> bool:
+        try:
+            self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/form",
+                params={"type": 2, "beingApply": True},
+            )
+            return True
+        except QingflowApiError as exc:
+            if exc.backend_code in {40002, 40027}:
+                return False
+            raise
+
+    def _probe_list_type_access(self, context: BackendRequestContext, app_key: str, list_type: int) -> bool:
+        try:
+            self.backend.request(
+                "POST",
+                context,
+                f"/app/{app_key}/apply/filter",
+                json_body={"type": list_type, "pageNum": 1, "pageSize": 1},
+            )
+            return True
+        except QingflowApiError as exc:
+            if exc.backend_code in {40002, 40027}:
+                return False
+            raise
+
+    def _resolve_accessible_system_views(self, context: BackendRequestContext, app_key: str) -> list[JSONObject]:
+        items: list[JSONObject] = []
+        for view_id, list_type, name in SYSTEM_VIEW_DEFINITIONS:
+            if not self._probe_list_type_access(context, app_key, list_type):
+                continue
+            items.append({"view_id": view_id, "name": name, "kind": "system", "analysis_supported": True})
+        return items
+
+    def _resolve_accessible_custom_views(self, context: BackendRequestContext, app_key: str) -> list[JSONObject]:
+        try:
+            payload = self.backend.request("GET", context, f"/app/{app_key}/view/viewList")
+        except QingflowApiError as exc:
+            if exc.backend_code in {40002, 40027}:
+                return []
+            raise
+
+        items: list[JSONObject] = []
+        for item in _normalize_view_list(payload):
+            view_key = str(item.get("viewKey") or "").strip()
+            if not view_key:
+                continue
+            normalized: JSONObject = {
+                "view_id": f"custom:{view_key}",
+                "name": str(item.get("viewName") or view_key).strip() or view_key,
+                "kind": "custom",
+            }
+            view_type = str(item.get("viewType") or item.get("viewgraphType") or "").strip()
+            if view_type:
+                normalized["view_type"] = view_type
+            normalized["analysis_supported"] = _analysis_supported_for_view_type(view_type or None)
+            items.append(normalized)
+        return items
+
     def _compact_base_info(self, result: dict[str, Any]) -> JSONObject:
         publish_status = result.get("appPublishStatus")
         auth = result.get("auth") if isinstance(result.get("auth"), dict) else {}
@@ -562,6 +671,29 @@ def _normalize_form_type(value: int | str) -> int:
     raise_tool_error(QingflowApiError.config_error("form_type must be a positive integer or one of: default, form, schema, new, draft, edit"))
 
 
+def _normalize_view_list(payload: Any) -> list[JSONObject]:
+    if not isinstance(payload, list):
+        return []
+    flattened: list[JSONObject] = []
+    for group in payload:
+        if not isinstance(group, dict):
+            continue
+        view_list = group.get("viewList")
+        if not isinstance(view_list, list):
+            continue
+        for item in view_list:
+            if isinstance(item, dict) and item.get("viewKey"):
+                flattened.append(item)
+    return flattened
+
+
+def _analysis_supported_for_view_type(view_type: str | None) -> bool:
+    normalized = str(view_type or "").strip().lower()
+    if not normalized:
+        return True
+    return normalized not in {"boardview", "ganttview"}
+
+
 def _coerce_positive_int(value: Any) -> int | None:
     try:
         number = int(value)