@josephyan/qingflow-app-user-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-user-mcp@0.2.0-beta.23
+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.23 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.23",
+  "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.0b23"
+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,192 +7,87 @@ metadata:
 
 # Qingflow Record Analysis
 
-## Overview
+Analysis tasks must start with `record_schema_get`.
+Use field_id-based DSLs only.
 
-This skill is for record analysis inside existing Qingflow apps. Use it when the task is about `分析 / 洞察 / 分布 / 占比 / 平均 / 排名 / 趋势 / 所有 / 全部 / 全国 / 高价值` or any final statistical conclusion.
+## Step 1: `record_schema_get` → Step 2: build DSL → Step 3: `record_analyze`
 
-This skill assumes the MCP is already connected and authenticated. If not, switch to `$qingflow-mcp-setup` first. If the task is about creating, updating, or deleting records rather than analyzing them, switch to `$qingflow-record-crud`. If it is about task-center actions, comments, approvals, rollback, transfer, or directory-driven workflow work, switch to `$qingflow-task-ops`.
+This is the ONLY execution order. Never skip step 1. Never call `record_analyze` without a schema.
 
-Before running analysis in `prod`, confirm the intended environment. If browser parity or live route debugging matters, call `record_analyze` with `output_profile=\"verbose\"` and compare `debug.request_route` with the browser route.
+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.
 
-## Tool Scope
-
-Use these tools as the core analysis surface:
-
-- `record_schema_get`
-- `record_analyze`
+---
 
-Use `record_list` or `record_get` only when you need sample rows or a specific supporting example after the main analysis path.
+## DSL Contract
 
-`record_schema_get` now returns the **current user's applicant-node visible schema only**:
+### DSL FORMAT (CRITICAL — read this FIRST)
 
-- hidden fields are omitted entirely
-- absent fields should be interpreted as `当前用户在申请人节点下不可见/不可用`
-- do not treat the schema as a builder/full-field metadata dump
+### ✅ Correct vs ❌ Wrong — learn from these before building ANY DSL
 
-## Hard Rules
+**dimension item:**
+```
+✅ CORRECT:  { "field_id": 9500572, "alias": "报价类型" }
+❌ WRONG:    9500572                          ← bare integer, not a dict
+❌ WRONG:    "报价类型"                        ← string, not a dict
+❌ WRONG:    { "field_id": 9500572, "title": "报价类型" }  ← "title" is forbidden
+```
 
-- Analysis tasks must start with `record_schema_get`
-- Build one or more small DSLs, then run `record_analyze` separately for each question
-- DSL field references must use `field_id` only
-- Normalize relative time phrases into explicit legal date ranges before building the DSL
-- If the user asks for `最近一个完整自然月 / 上个月 / 最近30天 / 本季度 / 去年同期`, first convert that phrase into concrete dates, then verify the dates are legal before calling MCP
-- Never send impossible dates such as `2026-02-29`; if the intended month is February 2026, the legal upper bound is `2026-02-28`
-- If the schema still leaves multiple plausible fields, stop and ask the user to confirm from a short candidate list instead of guessing
-- Do not keep retrying different guessed field names in a loop
-- `record_list` is never the basis for a final statistical conclusion
-- If `record_list` is capped or paged, treat it as sample-only evidence
-- Do not mix full totals from `record_analyze` with sample-only list observations as one combined `全量结论`
-- Do not manually tune paging or scan-budget parameters for analysis; `record_analyze` hides them
-- For final conclusions, prefer `strict_full=true`
-- Before choosing a DSL shape, first decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`
-- Do not guess a metric just because the user said `数量`, `单量`, `人数`, or `金额`
-- If one business question depends on multiple metrics, split it into smaller structured questions and build multiple focused DSLs
-- `渗透率 / 转化率 / 占比类结论必须先定义分子和分母`
-- Do not claim a metric you did not query.
-- Derived ratios must be computed outside the DSL after trusted numerator and denominator queries complete; do not invent `div`, `formula`, or expression metrics inside `record_analyze`
-- If the requested business question requires unsupported derived math, split it into multiple DSLs and compute the final ratio only in the reasoning layer after the source metrics are confirmed
-- If the user asks for multiple conclusions and only part of them is completed reliably, explicitly disclose which parts are complete and which parts remain unresolved
-
-## Standard Operating Order
-
-For analysis:
-
-1. Confirm target app and environment
-2. Run `record_schema_get`
-3. Inspect fields, aliases, suggested dimensions, suggested metrics, and suggested time fields
-4. Generate one or more field_id-based DSLs
-5. Run `record_analyze` once per DSL
-6. Run `record_list` only if you still need sample rows, examples, or manual inspection
-7. Before answering, separate:
-   - `全量可信结论`
-   - `样本观察`
-   - `待验证假设`
-
-## Semantic Guardrails
-
-- If the user asks for penetration, conversion, share-of-total, win rate, non-standard ratio, or any `%` metric, first write down:
-  - numerator definition
-  - denominator definition
-  - whether each side needs its own DSL
-- If you cannot name the denominator from real schema fields and filters, do not use words like `渗透率`, `转化率`, `占比`, `比例`, or `%`
-- If a field is still ambiguous after `record_schema_get`, do not guess; either select one unique `field_id` from the schema or ask the user to confirm from a short candidate list
-- If a business field is absent from `record_schema_get`, do not infer or guess a hidden `field_id`; explain that the field is not visible in the current applicant-node permission scope
-- If a statement depends on `count`, query `count`
-- If a statement depends on total amount, query `sum`
-- If a statement depends on average level, query `avg` or derive it from trusted `sum + count`
-- If a statement depends on trend, query a time dimension with `bucket`
-- If a statement depends on a ratio that the DSL cannot express directly, run the numerator and denominator separately, then compute the ratio outside MCP only after both sides are complete and compatible
-- Rankings must come from structured sorted results, not from loose natural-language restatement
-- When grouped rows are truncated, describe them as `已返回分组中` or `主要分组`
-- If `completeness.rows_truncated=true` or `completeness.statement_scope=returned_groups_only`, do not use words like `各部门`、`所有分组`、`完整名单`、`全部渠道`
-- If grouped rows are truncated, explicitly downgrade the wording to `前 N 个分组` or `主要分组`, never `全部`
-- Complex answers should default to `先结构、后解读`: present the table / metrics / ordering first, then add concise interpretation
-- Final wording should stay as close as possible to schema titles, dimension aliases, and metric aliases; do not rename the business object or field title unless the user asked for a rewrite
+**metric item — the key is `op`, NOT `type`/`agg`/`aggregation`:**
+```
+✅ CORRECT:  { "op": "count", "alias": "记录数" }
+✅ CORRECT:  { "op": "sum", "field_id": 7, "alias": "总金额" }
+❌ WRONG:    { "type": "count" }               ← "type" is NOT a valid key
+❌ WRONG:    { "agg": "count" }                ← "agg" is NOT a valid key
+❌ WRONG:    { "aggregation": "count" }         ← "aggregation" is NOT a valid key
+```
 
-## DSL Contract
+**filter item — the key is `op`, NOT `operator`:**
+```
+✅ CORRECT:  { "field_id": 2, "op": "between", "value": ["2024-03-01", "2024-03-31"] }
+✅ CORRECT:  { "field_id": 5, "op": "eq", "value": "已完成" }
+❌ WRONG:    { "field_id": 2, "operator": "between", "value": [...] }  ← "operator" is forbidden
+❌ WRONG:    { "field_id": 2, "op": ">=", "value": "2024-03-01" }      ← ">=" is not valid, use "gte"
+```
 
-Use `record_schema_get` as the source of truth for every DSL field reference:
+**sort item:**
+```
+✅ CORRECT:  { "by": "记录数", "order": "desc" }     ← "by" references an alias
+❌ WRONG:    { "by": 9500572, "order": "desc" }       ← field_id not allowed in sort
+```
 
-- Use `fields[].field_id` in `dimensions[].field_id`, `metrics[].field_id`, and `filters[].field_id`
-- Treat `suggested_dimensions`, `suggested_metrics`, and `suggested_time_fields` as hints, not as executable DSL by themselves
-- Do not pass field titles, aliases, or guessed ids where `field_id` is required
+### Allowed keys per item (ANY other key = error)
 
-The `record_analyze` call should be built from this argument shape:
+| Item | Allowed keys only |
+|------|-------------------|
+| dimension | `field_id`, `alias`, `bucket` |
+| metric | `op`, `field_id`, `alias` |
+| filter | `field_id`, `op`, `value` |
+| sort | `by`, `order` |
 
-```json
-{
-  "app_key": "APP_1",
-  "dimensions": [],
-  "metrics": [],
-  "filters": [],
-  "sort": [],
-  "limit": 50,
-  "strict_full": true,
-  "view_key": null,
-  "view_name": null,
-  "output_profile": "normal"
-}
-```
+### `op` values
 
-Top-level argument rules:
-
-- `app_key`: required. The target Qingflow app.
-- `dimensions`: required list. Use `[]` for whole-table summary. Use one item per grouping dimension for grouped analysis.
-- `metrics`: optional list. If omitted or empty, `record_analyze` defaults to a single `count` metric.
-- `filters`: optional list. Filters restrict the analyzed dataset before results are interpreted.
-- `sort`: optional list. Sorting applies to result rows, not raw source rows.
-- `limit`: positive integer. It only limits returned result rows; it does not reduce the internal scan scope.
-- `strict_full`: boolean. Prefer `true` for final conclusions. If `true`, incomplete scans return an error; if `false`, incomplete scans return partial results.
-- `view_key` / `view_name`: optional. Use a view to narrow scope before analysis. Prefer `view_key` when both are available.
-- `output_profile`: `normal` or `verbose`. Prefer `normal` unless you are debugging completeness or route issues.
-
-Item contracts:
-
-- `dimensions` item:
-  - shape: `{ "field_id": 2, "alias": "状态", "bucket": null }`
-  - `field_id`: required integer from `record_schema_get`
-  - `alias`: optional but recommended; if omitted, the field title becomes the alias
-  - `bucket`: optional; allowed values are `day`, `week`, `month`, `quarter`, `year`, or omitted / `null`
-  - `bucket` may only be used on fields from `suggested_time_fields`
-- `metrics` item:
-  - shape: `{ "op": "sum", "field_id": 7, "alias": "总金额" }`
-  - `op`: one of `count`, `sum`, `avg`, `min`, `max`, `distinct_count`
-  - `field_id`: required for `sum`, `avg`, `min`, `max`, `distinct_count`; do not pass it for `count`
-  - `alias`: optional but strongly recommended because `sort.by` must reference aliases
-- `filters` item:
-  - shape: `{ "field_id": 2, "op": "eq", "value": "进行中" }`
-  - `field_id`: required integer from `record_schema_get`
-  - `op`: optional; defaults to `eq`
-  - supported ops: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between`, `contains`, `is_null`, `not_null`
-  - value rules:
-    - `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`: pass a single scalar value
-    - `in`, `not_in`: pass an array
-    - `between`: pass a two-item array like `[min, max]`
-    - `is_null`, `not_null`: omit `value`
-- `sort` item:
-  - shape: `{ "by": "记录数", "order": "desc" }`
-  - `by`: required and must reference an alias already defined in `dimensions` or `metrics`
-  - `order`: optional; use `asc` or `desc`; default is `asc`
-  - do not sort by raw field title or `field_id`
-
-Practical rules:
-
-- Keep one DSL focused on one question. Prefer multiple small DSLs over one overloaded request.
-- Always set explicit aliases for metrics you may sort by, compare, or quote in the final answer.
-- For trend analysis, use one time dimension with `bucket`, then sort by that time alias ascending.
-- For cross analysis, use multiple `dimensions` and a small set of metrics.
-- Do not attempt formulas, joins, having clauses, cohort analysis, or manual paging controls in this DSL.
-- Do not pass unsupported keys such as `formula`, `expr`, `numerator`, `denominator`, `left`, `right`, or `operator` inside metric items.
-
-## Minimal DSL Templates
-
-Summary:
+- metrics: `count`, `sum`, `avg`, `min`, `max`, `distinct_count`
+- filters: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between`, `contains`, `is_null`, `not_null`
+- For `count` metric: do NOT pass `field_id`. For all others: `field_id` is required.
+- If `metrics` is omitted or `[]`, defaults to `[{"op":"count","alias":"记录数"}]`.
 
-```json
-{
-  "dimensions": [],
-  "metrics": [
-    { "op": "count", "alias": "记录数" }
-  ],
-  "filters": [],
-  "sort": [],
-  "limit": 1,
-  "strict_full": true
-}
-```
+---
 
-Single-dimension distribution:
+## COMPLETE DSL TEMPLATE — copy, replace field_id, done
 
 ```json
 {
+  "app_key": "YOUR_APP_KEY",
   "dimensions": [
-    { "field_id": 2, "alias": "状态" }
+    { "field_id": FIELD_ID_FROM_SCHEMA, "alias": "维度名" }
   ],
   "metrics": [
     { "op": "count", "alias": "记录数" }
   ],
-  "filters": [],
+  "filters": [
+    { "field_id": TIME_FIELD_ID, "op": "between", "value": ["2024-03-01", "2024-03-31"] }
+  ],
   "sort": [
     { "by": "记录数", "order": "desc" }
   ],
@@ -201,67 +96,87 @@ Single-dimension distribution:
 }
 ```
 
-Time trend:
+More templates:
+
+**Whole-table count (no grouping):**
+```json
+{ "dimensions": [], "metrics": [{"op":"count","alias":"记录数"}], "strict_full": true }
+```
 
+**Monthly trend:**
 ```json
 {
-  "dimensions": [
-    { "field_id": 3, "alias": "月份", "bucket": "month" }
-  ],
-  "metrics": [
-    { "op": "count", "alias": "记录数" }
-  ],
-  "filters": [],
-  "sort": [
-    { "by": "月份", "order": "asc" }
-  ],
-  "limit": 24,
-  "strict_full": true
+  "dimensions": [{"field_id": 3, "alias": "月份", "bucket":"month"}],
+  "metrics": [{"op":"count","alias":"记录数"}],
+  "sort": [{"by":"月份","order":"asc"}],
+  "limit": 24, "strict_full": true
 }
 ```
 
-Two-dimensional cross analysis:
-
+**Cross analysis with sum:**
 ```json
 {
-  "dimensions": [
-    { "field_id": 2, "alias": "状态" },
-    { "field_id": 5, "alias": "负责人" }
-  ],
-  "metrics": [
-    { "op": "count", "alias": "记录数" },
-    { "op": "sum", "field_id": 7, "alias": "总金额" }
-  ],
-  "filters": [],
-  "sort": [
-    { "by": "记录数", "order": "desc" }
-  ],
-  "limit": 100,
-  "strict_full": true
+  "dimensions": [{"field_id": 2, "alias": "状态"}, {"field_id": 5, "alias": "负责人"}],
+  "metrics": [{"op":"count","alias":"记录数"}, {"op":"sum","field_id": 7, "alias":"总金额"}],
+  "sort": [{"by":"记录数","order":"desc"}],
+  "limit": 100, "strict_full": true
 }
 ```
 
-## Output Gate
-
-- Read aggregate rows from `result.rows`
-- Read overall totals from `result.totals.metric_totals`
-- Read sort intent from `query.sort`
-- Read ranked output from `ranking` when it is not `null`
-- Read ratio output from `ratios` when it is not `null`; `ratios=null` is normal when MCP did not produce a native ratio block
-- Read warning codes from `completeness.warnings`
-
-- Only write `全量可信结论` when the supporting `record_analyze` calls report `completeness.status=complete` and `safe_for_final_conclusion=true`
-- If any key analysis call is incomplete, downgrade the answer to `初步观察` or `部分结果`
-- Treat `safe_for_final_conclusion=true` as necessary but not sufficient when the metric definition is incomplete or grouped rows are truncated
-- If `completeness.statement_scope=returned_groups_only`, you may still give full-population conclusions about totals or ratios, but not a full grouped enumeration claim
-- If aggregate-style output is full but list evidence is sample-only, split the answer into:
-  - `全量可信结论`
-  - `样本观察（不作为最终结论）`
-  - optional `待验证假设`
-
-## Resources
-
-- Analysis patterns: [references/analysis-patterns.md](references/analysis-patterns.md)
-- Confidence reporting: [references/confidence-reporting.md](references/confidence-reporting.md)
-- Analysis gotchas: [references/analysis-gotchas.md](references/analysis-gotchas.md)
-- Shared environment guidance: [/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-app-user/references/environments.md](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-app-user/references/environments.md)
+### Top-level arguments
+
+- `app_key`: required.
+- `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.
+- `bucket` in dimensions: only for `suggested_time_fields`. Values: `day`/`week`/`month`/`quarter`/`year`/`null`.
+
+---
+
+## 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`).
+- If schema has ambiguous fields, ask user to pick from a short list. Do not guess.
+- `record_list` is NEVER the basis for final statistics.
+- Derived ratios: run numerator and denominator as separate DSLs, compute ratio in your reasoning.
+- Set `alias` for any metric you will sort by, compare, or quote.
+
+---
+
+## OUTPUT (CRITICAL — final answer must show concrete numbers)
+
+### 必须逐行列出数据（硬性要求）
+
+final_answer MUST include a table with every row from `result.rows`:
+
+| {维度别名} | {指标别名} | 占比 |
+|------------|-----------|------|
+| {row.dimensions.X} | {row.metrics.Y} | {Y / total * 100}% |
+
+- 占比 = 行指标值 / `result.totals.metric_totals` 总值, 保留一位小数
+- 如 `metric_totals` 不存在, 用各行之和作分母
+- 超过 20 行展示 Top 20 并注明
+- 不得只写"共 N 种类型"而省略明细
+
+### 结论分级
+
+- `safe_for_final_conclusion=true` → `全量可信结论`
+- 不完整 → `初步观察`
+- `rows_truncated=true` → 用 `前 N 个分组`, 不用 `全部`/`所有`

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

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