@qingflow-tech/qingflow-app-user-mcp 1.0.43 → 1.1.0

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-user-mcp@1.0.43
+npm install @qingflow-tech/qingflow-app-user-mcp@1.1.0
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.43 qingflow-app-user-mcp
+npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.1.0 qingflow-app-user-mcp
 ```
 
 Environment:

package/npm/bin/qingflow-app-user-mcp.mjs

@@ -1,7 +1,36 @@
 #!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { getPackageRoot, spawnServer } from "../lib/runtime.mjs";
+const PKG_BY_BIN = {
+  qingflow: "qingflow-cli",
+  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
+  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
+};
 
-const packageRoot = getPackageRoot(import.meta.url);
+function resolvePackageModule(metaUrl, ...segments) {
+  const scriptPath = fileURLToPath(metaUrl);
+  const scriptDir = path.dirname(scriptPath);
+  const direct = path.join(scriptDir, ...segments);
+  if (fs.existsSync(direct)) {
+    return pathToFileURL(direct).href;
+  }
+  if (path.basename(scriptDir) === ".bin") {
+    const binName = path.basename(scriptPath);
+    const pkgName = PKG_BY_BIN[binName];
+    if (!pkgName) {
+      throw new Error(`Unknown qingflow command: ${binName}`);
+    }
+    const scope = process.env.QINGFLOW_NPM_SCOPE || "@qingflow-tech";
+    const fromBin = path.join(scriptDir, "..", scope, pkgName, "npm", ...segments);
+    if (fs.existsSync(fromBin)) {
+      return pathToFileURL(fromBin).href;
+    }
+  }
+  throw new Error(`Cannot locate ${segments.join("/")} from ${scriptPath}`);
+}
 
+const { getPackageRoot, spawnServer } = await import(resolvePackageModule(import.meta.url, "lib", "runtime.mjs"));
+const packageRoot = getPackageRoot(import.meta.url);
 spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-user-mcp", { allowRuntimeBootstrap: false });

package/npm/lib/runtime.mjs

@@ -5,6 +5,12 @@ import { fileURLToPath } from "node:url";
 
 const WINDOWS = process.platform === "win32";
 
+const PKG_BY_BIN = {
+  qingflow: "qingflow-cli",
+  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
+  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
+};
+
 function runChecked(command, args, options = {}) {
   const result = spawnSync(command, args, {
     encoding: "utf8",
@@ -28,7 +34,18 @@ function commandWorks(command, args) {
 }
 
 export function getPackageRoot(metaUrl) {
-  return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
+  const scriptPath = fileURLToPath(metaUrl);
+  const scriptDir = path.dirname(scriptPath);
+  if (path.basename(scriptDir) === ".bin") {
+    const binName = path.basename(scriptPath);
+    const pkgName = PKG_BY_BIN[binName];
+    if (!pkgName) {
+      throw new Error(`Unknown qingflow command: ${binName}`);
+    }
+    const scope = process.env.QINGFLOW_NPM_SCOPE || "@qingflow-tech";
+    return path.join(scriptDir, "..", scope, pkgName);
+  }
+  return path.resolve(scriptDir, "..", "..");
 }
 
 export function getCodexHome() {
@@ -480,6 +497,17 @@ function getVenvPip(packageRoot) {
     : path.join(getVenvDir(packageRoot), "bin", "pip");
 }
 
+function findOfflineProjectWheel(findLinksDir) {
+  const wheels = fs
+    .readdirSync(findLinksDir)
+    .filter((name) => /^qingflow_mcp-.*\.whl$/i.test(name))
+    .sort();
+  if (wheels.length === 0) {
+    throw new Error(`Offline install expected a qingflow_mcp wheel in ${findLinksDir}`);
+  }
+  return path.join(findLinksDir, wheels[wheels.length - 1]);
+}
+
 export function findPython() {
   const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
   const candidates = preferred
@@ -528,7 +556,20 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   }
 
   const pip = getVenvPip(packageRoot);
-  runChecked(pip, ["install", "--disable-pip-version-check", "."], { cwd: packageRoot });
+  const pipArgs = ["install", "--disable-pip-version-check"];
+  const offlineFindLinks = process.env.QINGFLOW_MCP_PIP_FIND_LINKS?.trim();
+  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1") {
+    pipArgs.push("--no-index");
+  }
+  if (offlineFindLinks) {
+    pipArgs.push("--find-links", offlineFindLinks);
+  }
+  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1" && offlineFindLinks) {
+    pipArgs.push(findOfflineProjectWheel(offlineFindLinks));
+  } else {
+    pipArgs.push(".");
+  }
+  runChecked(pip, pipArgs, { cwd: packageRoot });
 
   fs.writeFileSync(
     stampPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-user-mcp",
-  "version": "1.0.43",
+  "version": "1.1.0",
   "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 = "1.0.43"
+version = "1.1.0"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow App User
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Overview
 

package/skills/qingflow-mcp-setup/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow MCP Setup
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Overview
 

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Record Analysis
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 Use this skill only for final statistical conclusions: counts, distributions, ratios, averages, rankings, trends, comparisons, and analysis reports.
 

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Record Delete
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Default Path
 

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Record Import
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Default Path
 

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

@@ -8,7 +8,7 @@ metadata:
 
 # Qingflow Record Insert
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Default Path
 
@@ -84,7 +84,7 @@ Without `record_id` / `workflow_node_id` / `fields-file`, the result is a static
 ## Working Rules
 
 1. Start with `record_insert_schema_get`
-2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`
+2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, `payload_template`, field-level `expected_format`, `example_value`, and `options`
 3. Inside every field bucket, read field-level `linkage` first when present; it is the canonical static hint for linked visibility, reference-driven auto fill, or formula-driven fields
 4. Inside `optional_fields`, pay special attention to any field with `may_become_required=true`; these are writable fields that can become required when linked visibility or option-driven rules activate
 5. Build `items` as `[{"fields": {...}}]`, where each `fields` map uses field titles from the insert schema
@@ -102,6 +102,8 @@ Without `record_id` / `workflow_node_id` / `fields-file`, the result is a static
 17. Treat nested schema shape as guidance, not a brittle contract; do not hard-code transient implementation details like optional nested `field_id` shape when composing inserts
 18. For `partial_success`, read `created_record_ids`, then repair only the failed `items[].row_number` using `failed_fields`; never retry the whole batch after any row has `write_executed=true`
 19. Do not put Qingflow system fields in `fields`: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are generated by the platform and can be read after creation, not manually inserted.
+20. When the user asks to add sample records after system setup, still generate values from schema: required fields first, select values from `options`, scalar/date/amount values from `expected_format` and `example_value`; do not invent values outside the insert schema.
+21. For ratio, completion-rate, score, and percentage-like fields, obey the schema's `expected_format/example_value`. If the field was modeled as money/amount or otherwise only accepts integers, do not invent decimal percentages; either use an integer value that matches the schema or report that the field should be modeled as `number` for decimal ratios.
 
 ## Field Notes
 
@@ -146,6 +148,7 @@ qingflow --json record insert --app-key APP_KEY --items-file records.json
 - Do not fill platform system fields such as `数据ID`, `编号`, `申请人`, `创建时间`, or `更新时间`
 - Do not flatten subtable leaf fields to the top level
 - Do not invent member / department / relation candidates outside schema or candidate scope
+- Do not invent select option labels outside schema `options`
 - Do not pre-query or silently guess member / department / relation ids when a natural string is enough
 - Do not retry a whole batch after `created_record_ids` is non-empty
 - Do not bind logic to a transient nested schema serialization detail when the field title and parent table already identify the legal payload shape

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Record Update
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Default Path
 

package/skills/qingflow-task-ops/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Task Ops
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Overview
 

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b1017"
+_FALLBACK_VERSION = "0.2.0b1099"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/builder_facade/models.py

@@ -203,10 +203,6 @@ class LayoutPreset(str, Enum):
     single_section = "single_section"
 
 
-class FlowPreset(str, Enum):
-    basic_approval = "basic_approval"
-    basic_fill_then_approve = "basic_fill_then_approve"
-
 
 class ViewsPreset(str, Enum):
     default_table = "default_table"
@@ -2342,7 +2338,6 @@ AppReadSummaryResponse = AppGetResponse
 AppFieldsReadResponse = AppGetFieldsResponse
 AppLayoutReadResponse = AppGetLayoutResponse
 AppViewsReadResponse = AppGetViewsResponse
-AppFlowReadResponse = AppGetFlowResponse
 AppChartsReadResponse = AppGetChartsResponse
 
 
@@ -2432,40 +2427,6 @@ class LayoutPlanRequest(StrictModel):
         return payload
 
 
-class FlowPlanRequest(StrictModel):
-    app_key: str
-    mode: str = "replace"
-    nodes: list[FlowNodePatch] = Field(default_factory=list)
-    transitions: list[FlowTransitionPatch] = Field(default_factory=list)
-    preset: FlowPreset | None = None
-
-    @model_validator(mode="before")
-    @classmethod
-    def normalize_mode_alias(cls, value: Any) -> Any:
-        if not isinstance(value, dict):
-            return value
-        payload = dict(value)
-        if str(payload.get("mode") or "").strip().lower() == "overwrite":
-            payload["mode"] = "replace"
-        raw_preset = payload.get("preset")
-        if raw_preset is None and isinstance(payload.get("base_preset"), str):
-            raw_preset = payload["base_preset"]
-            payload["preset"] = raw_preset
-        if isinstance(raw_preset, str):
-            normalized_preset = raw_preset.strip().lower()
-            preset_aliases = {
-                "default_approval": FlowPreset.basic_approval.value,
-                "approval": FlowPreset.basic_approval.value,
-                "basic approval": FlowPreset.basic_approval.value,
-                "default_fill_then_approve": FlowPreset.basic_fill_then_approve.value,
-                "default-fill-then-approve": FlowPreset.basic_fill_then_approve.value,
-                "fill_then_approve": FlowPreset.basic_fill_then_approve.value,
-            }
-            if normalized_preset in preset_aliases:
-                payload["preset"] = preset_aliases[normalized_preset]
-        return payload
-
-
 class ViewsPlanRequest(StrictModel):
     app_key: str
     upsert_views: list[ViewUpsertPatch] = Field(default_factory=list)