@josephyan/qingflow-app-user-mcp 0.2.0-beta.1 → 0.2.0-beta.10

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.1
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.10
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.1 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.10 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -19,3 +19,12 @@ Environment:
 - `QINGFLOW_MCP_HOME`
 
 This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-user-mcp` stdio MCP server.
+
+Bundled skill:
+
+- `skills/qingflow-app-user`
+
+Note:
+
+- The skill files are included in the npm package.
+- On install, the package copies them to `$CODEX_HOME/skills` (or `~/.codex/skills` if `CODEX_HOME` is unset).

package/npm/lib/runtime.mjs

@@ -29,6 +29,43 @@ export function getPackageRoot(metaUrl) {
   return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
 }
 
+export function getCodexHome() {
+  const configured = process.env.CODEX_HOME?.trim();
+  if (configured) {
+    return path.resolve(configured);
+  }
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error("Cannot resolve CODEX_HOME because HOME is not set.");
+  }
+  return path.join(home, ".codex");
+}
+
+export function installBundledSkills(packageRoot) {
+  const skillsSrc = path.join(packageRoot, "skills");
+  if (!fs.existsSync(skillsSrc)) {
+    return { installed: [], skipped: true, destination: null };
+  }
+
+  const codexHome = getCodexHome();
+  const skillsDestRoot = path.join(codexHome, "skills");
+  fs.mkdirSync(skillsDestRoot, { recursive: true });
+
+  const installed = [];
+  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const src = path.join(skillsSrc, entry.name);
+    const dest = path.join(skillsDestRoot, entry.name);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.cpSync(src, dest, { recursive: true });
+    installed.push(entry.name);
+  }
+
+  return { installed, skipped: false, destination: skillsDestRoot };
+}
+
 export function getVenvDir(packageRoot) {
   return path.join(packageRoot, ".npm-python");
 }

package/npm/scripts/postinstall.mjs

@@ -1,4 +1,4 @@
-import { ensurePythonEnv, getPackageRoot } from "../lib/runtime.mjs";
+import { ensurePythonEnv, getPackageRoot, installBundledSkills } from "../lib/runtime.mjs";
 
 const packageRoot = getPackageRoot(import.meta.url);
 
@@ -6,6 +6,10 @@ try {
   console.log("[qingflow-mcp] Bootstrapping Python runtime...");
   ensurePythonEnv(packageRoot, { commandName: "qingflow-app-user-mcp" });
   console.log("[qingflow-mcp] Python runtime is ready.");
+  const skills = installBundledSkills(packageRoot);
+  if (!skills.skipped) {
+    console.log(`[qingflow-mcp] Installed skills to ${skills.destination}: ${skills.installed.join(", ")}`);
+  }
 } catch (error) {
   console.error(`[qingflow-mcp] postinstall failed: ${error.message}`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.10",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "src/qingflow_mcp/py.typed",
     "qingflow-app-user-mcp",
     "npm/",
-    "docs/local-agent-install.md"
+    "docs/local-agent-install.md",
+    "skills/"
   ],
   "engines": {
     "node": ">=16.16.0"

package/pyproject.toml

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

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

@@ -0,0 +1,158 @@
+---
+name: qingflow-app-user
+description: Use Qingflow apps as an operational end user after the MCP is already connected and authenticated. Use when the user wants to create, search, read, update, or delete business records, inspect or manage task-center work, add comments, or perform workflow usage actions inside an existing app. Do not use this skill to design apps, modify schemas, or build a brand new SolutionSpec.
+metadata:
+  short-description: Use Qingflow apps for business data and task operations
+---
+
+# Qingflow App User
+
+## Overview
+
+This skill is for business-user operations inside existing Qingflow apps. It focuses on records, task-center usage, comments, and usage-side workflow actions, not app design or system configuration. If the task is about building or changing app structure, switch to `$qingflow-app-builder`.
+
+Before operating on data, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
+When the task is in `prod`, browser parity matters, or the user says "the page has data but MCP does not", restate the expected `base_url` and `qf_version`, then prefer tools that expose `request_route` so you can confirm the live route before concluding.
+
+## Tool Scope
+
+Primary record and data tools:
+
+- `record_query`
+- `record_query_plan`
+- `record_write_plan`
+- `record_field_resolve`
+- `record_aggregate`
+- `record_create`
+- `record_get`
+- `record_update`
+- `record_delete`
+
+Directory and organization lookup tools when the user is asking about internal members, departments, org structure, ownership, approver candidates, or wants full contact exports:
+
+- `directory_search`
+- `directory_list_internal_users`
+- `directory_list_all_internal_users`
+- `directory_list_internal_departments`
+- `directory_list_all_departments`
+- `directory_list_sub_departments`
+- `directory_list_external_members`
+
+Usage-side collaboration and flow tools when needed:
+
+- `record_comment_*`
+- `task_approve`
+- `task_reject`
+- `task_rollback*`
+- `task_transfer*`
+
+Task-center and inbox tools when the user is asking about pending work, processed work, cc, or workflow workload:
+
+- `task_list`
+- `task_list_grouped`
+- `task_statistics`
+- `task_urge`
+
+Do not use builder-side tools here:
+
+- `app_*`
+- `view_*`
+- `workflow_*`
+- `portal_*`
+- `navigation_*`
+- `package_*`
+- `solution_*`
+
+## Standard Operating Order
+
+1. Ensure auth exists
+2. Ensure workspace is selected
+3. Confirm target app, task scope, and operation type
+4. For org, member, department, approver, or ownership questions, start with `directory_*`
+5. For inbox, pending, processed, cc, or workload questions, start with `task_statistics`, `task_list`, or `task_list_grouped`
+6. When a task query identifies the target record, switch to `record_get` or `record_query` for business data details
+7. For non-trivial record reads, start with `record_query` and use `record_query_plan` first when field ids, filters, or scan scope are uncertain
+8. For non-trivial writes, start with `record_write_plan`, especially when using `fields`
+9. Prefer read-first when changing existing records
+10. Report the affected task ids, record ids, member ids, department ids, or counts after actions
+11. For `prod`, complex forms, attachments, or any unfamiliar schema, prefer `record_create(..., verify_write=true)` or read back immediately after create/update
+
+## Data Rules
+
+- Prefer `record_query` as the default read entry
+- Treat `record_query(list)` as the default wide-table browse and export endpoint; pass explicit `select_columns`, do not expect raw answer arrays there, and let the tool auto-batch columns when the backend per-request field cap is hit
+- Use `request_route` from tool responses to verify the active `base_url` and `qf_version` whenever route mismatches are plausible
+- Use `directory_search` for fuzzy internal lookup across both members and departments
+- Use `directory_list_all_internal_users` when the user explicitly wants a complete internal member list within the current workspace or within a specific department or role
+- Use `directory_list_all_departments` when the user explicitly wants the full department tree or all departments under a root
+- Use `directory_list_internal_departments` for keyword-based department search, not full exports
+- Use `task_statistics` before `task_list` when the user only needs counts
+- Use `task_list_grouped` when worksheet or group buckets matter
+- Use `task_urge` only when the user clearly wants a reminder sent for a pending task
+- Use `record_query_plan` before final statistics or when field selectors are ambiguous
+- For precise record lookup, use `record_get` when `apply_id` is known
+- Use `record_field_resolve` when the user gives field titles and you are not fully sure about the exact schema; do not guess ambiguous fields silently
+- Treat field selectors as schema-first and platform-generic. Prefer exact field titles, then neutral aliases such as `创建时间`, `新增时间`, `负责人`, `部门`, `时间`, or `阶段` only when the tool resolves them clearly. Do not assume CRM shorthand like `销售`, `商机阶段`, `客户全称`, or similar domain shortcuts apply across arbitrary Qingflow apps
+- For updates, inspect current data first unless the user already provided the exact target and patch
+- For deletes, confirm the exact record scope and report the deleted ids
+- When validating business data volume, use `effective_count` over raw backend totals
+- For summary or aggregate conclusions, prefer `strict_full=true`
+- In `prod`, prefer read-first even more strictly and avoid deletes unless the record scope is explicit in the conversation
+- For attachments, first run `file_upload_local`, then pass the returned `attachment_value` into `record_create` or `record_update`; do not try to write local file paths directly into attachment fields
+- For relation fields, first query the target app and resolve the referenced record `apply_id`; do not assume titles, numbers, or business keys can be written directly into a relation field
+- For subtable fields, write a list of row objects keyed by the subfield titles. When updating existing rows, include `rowId` / `row_id` / `__row_id__` only if the source record already exposes it
+- Treat `14/34/35/36` as unsupported direct-write field types in app-user flows:
+  - `14`: time range
+  - `34`: image recognition
+  - `35`: image generation
+  - `36`: document parsing
+- For those unsupported types, stop and explain the limitation instead of inventing payloads
+- Use `record_write_plan` to inspect `write_format.support_level` before non-trivial writes:
+  - `full`: generic scalar/select/date writes are directly supported
+  - `restricted`: member/department/attachment/relation/subtable writes need the documented presteps
+  - `unsupported`: stop and explain the limitation
+- For relation-heavy, attachment, subtable, or production writes, default to `verify_write=true` so field drops are surfaced immediately instead of being reported as success
+
+## Mock and Demo Data
+
+When the user asks for demo data, seed, smoke data, or mock data:
+
+- default to at least `5` records for the relevant entity unless the user asks for fewer
+- keep titles realistic and business-like
+- vary statuses, dates, and categories enough to make views and charts useful
+- if the task is `prod`, do not create mock or smoke data unless the user explicitly asks for it
+
+## Response Interpretation
+
+- low-level list totals from the backend may report `0` while rows are present; prefer `record_query(summary)` or `record_aggregate` for final conclusions
+- `record_query(summary)` and `record_aggregate` expose `completeness`; do not treat partial scans as final conclusions
+- `record_write_plan` is static preflight, not a guarantee that submit will pass runtime linkage or visibility checks
+- `record_create` now returns integer `apply_id`; you can pass that id directly into `record_get`, `record_update`, or `record_delete`
+- `verify_write=true` means the tool read the record back and compared the written fields; if it returns `status=verification_failed` or `ok=false`, do not report the create or update as successful
+- Relation writes are `apply_id`-based; if the user only gives a title, number, or business key, query the target app first and resolve the real record id before writing
+- Task counts and record counts are not interchangeable; a task query reflects task-center workload, not the underlying record total
+- When reporting task results, include the task dimension that was used, such as pending, processed, cc, node, or worksheet
+- Prefer summarizing titles and counts instead of dumping raw answer arrays
+- When records reference other entities, verify references are coherent before reporting success
+- `file_upload_local` may transparently change `effective_upload_kind` and `upload_protocol`; surface those fields when debugging production upload behavior instead of assuming all uploads are direct `PUT`
+
+## Practical Patterns
+
+- Bulk mock data creation: query current data first, run `record_write_plan`, then create missing records
+- Data correction: query, inspect, preflight, update, and re-read
+- Inbox triage: use `task_statistics` first, then `task_list` or `task_list_grouped`, then switch to `record_*` for the underlying record when needed
+- Bottleneck analysis: start with `task_statistics` and `task_list_grouped` before drilling into specific records
+- Workflow collaboration: comment, transfer, or reassign only after identifying the exact record
+- Approval actions: identify the exact record and current node first, then use `task_approve` or `task_reject`; do not guess `nodeId`
+- Demo validation: create at least `5` rows and confirm they are queryable
+- Org export: use `directory_list_all_internal_users` for full member exports and `directory_list_all_departments` for full org-tree exports before mapping owners or departments into record operations
+- Attachment write: upload first, write the returned URL object second, and prefer `verify_write=true`
+- Relation write: query the target app first, capture the referenced record `apply_id`, then write the relation field and verify the readback
+- Production discrepancy triage: compare the response `request_route` with the browser environment before assuming the data query is wrong
+
+## Resources
+
+- Environment switching: [references/environments.md](references/environments.md)
+- Record operation patterns: [references/record-patterns.md](references/record-patterns.md)
+- Workflow usage actions: [references/workflow-usage.md](references/workflow-usage.md)
+- Data gotchas: [references/data-gotchas.md](references/data-gotchas.md)

package/skills/qingflow-app-user/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow App User"
+  short_description: "Use Qingflow apps for business data and task operations"
+  default_prompt: "Use $qingflow-app-user to query members or departments, inspect workload, and safely create, query, update, validate, approve, reject, or otherwise operate records in an existing Qingflow app, paying attention to request_route, verify_write, nodeId accuracy, and attachment upload flows when needed."

package/skills/qingflow-app-user/references/data-gotchas.md

@@ -0,0 +1,49 @@
+# Data Gotchas
+
+## Counts
+
+- Prefer `effective_count`
+- For `record_query(summary)` and `record_aggregate`, inspect `completeness` before concluding
+- If the browser and MCP disagree, compare `request_route.base_url` and `request_route.qf_version` first
+
+## Record titles
+
+- Do not dump raw answer arrays to the user unless needed
+- Prefer concise business titles and counts
+
+## Preflight
+
+- `record_write_plan` is static preflight only; linked visibility and runtime required rules can still reject writes
+- `record_write_plan` now exposes `write_format.support_level`; check `full / restricted / unsupported` before attempting non-trivial writes
+- Use `record_field_resolve` when field titles are uncertain instead of guessing ids
+- Prefer `strict_full=true` for final statistics or business conclusions
+- `record_create` and `record_update` can do post-write verification with `verify_write=true`; use that for complex, subtable, or production writes
+- `apply_id` is normalized to an integer; pass it directly into later record tools
+
+## Mock data
+
+- Default to at least `5` rows per relevant entity unless the user asked for fewer
+- Avoid identical titles and identical statuses across all rows
+- Keep relation references valid
+
+## Attachments
+
+- Attachment fields are two-step: upload first, then write the returned URL object into the record
+- `file_upload_local` may report `effective_upload_kind=login` even when the requested kind was `attachment`; this is an implementation fallback, not necessarily an error
+- When debugging uploads, surface both `effective_upload_kind` and `upload_protocol`
+
+## Subtables
+
+- Subtable fields accept row objects keyed by subfield title, or native `tableValues`
+- Use the current form schema's subfield titles; do not guess nested ids
+- When updating existing subtable rows, preserve `rowId` if the source record returns it
+- Nested subtable writes are still unsupported
+
+## Unsupported direct-write fields
+
+- `14` time range
+- `34` image recognition
+- `35` image generation
+- `36` document parsing
+
+Do not fake values for these fields in app-user writes. Stop and explain the limitation.

package/skills/qingflow-app-user/references/environments.md

@@ -0,0 +1,63 @@
+# Environment Switching
+
+Use this reference before any data creation, update, delete, or workflow usage action.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the task targets:
+
+- `test`: demo, mock data, smoke usage validation, training scenarios
+- `prod`: real operational data and live workflow actions
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Use test for:
+
+- mock or smoke data entry
+- business flow walkthroughs
+- user acceptance demos
+- data correction rehearsals
+
+Test behavior:
+
+- creating demo data is acceptable
+- default to at least `5` records for mock or smoke datasets unless the user asks for fewer
+- destructive cleanup is acceptable only when the record scope is explicit
+
+Known current test backend:
+
+- use an explicitly provided non-production backend
+
+## Production Environment
+
+Use production for:
+
+- live data entry
+- live business record updates
+- comments and workflow actions on real records
+- controlled data correction or deletion
+
+Production behavior:
+
+- prefer search or get before any write
+- restate the exact app and record scope before update or delete
+- do not create mock, smoke, or demo data unless the user explicitly asks for it
+- for bulk changes, summarize the target count before execution and the affected ids after execution
+- destructive actions need explicit confirmation in the conversation context
+
+Production guardrails:
+
+- never assume a record id, app id, or workspace id
+- treat `record_delete` as high risk
+- if the task can be answered read-only, do not write
+
+## Reporting Rule
+
+For app-user operations, always report:
+
+- active environment
+- target app
+- operation type: read, create, update, delete, or workflow action
+- affected record count or ids

package/skills/qingflow-app-user/references/record-patterns.md

@@ -0,0 +1,69 @@
+# Record Patterns
+
+## Query first
+
+Use `record_query` first when:
+
+- the user only gives a title or business key
+- the target record id is unknown
+- updates or deletes need confirmation
+- summary analysis or final counts are needed
+
+Use `record_query_plan` first when:
+
+- field titles may be ambiguous
+- filters are still in natural-language shape
+- the result may be used as a final conclusion
+- scan scope or completeness is unclear
+
+## Create pattern
+
+1. Confirm target app
+2. Resolve fields with `record_field_resolve` if needed. Prefer exact schema titles first; only rely on platform-neutral aliases such as `创建时间`, `负责人`, or `部门` when they resolve cleanly, and do not assume business-domain shorthand like `销售` is portable across apps
+3. Run `record_write_plan` for non-trivial payloads or any `fields`-based write
+4. For relation fields, query the target app first and resolve the referenced record `apply_id`
+5. For attachments, call `file_upload_local` first and reuse the returned `attachment_value`
+6. For subtable fields, pass a list of row objects keyed by subfield title. When updating existing rows, include `rowId` / `row_id` / `__row_id__` only if the current record already exposes it
+7. Inspect `record_write_plan.data.support_matrix` or each field's `write_format.support_level` before submit:
+   - `full`: direct write is supported
+   - `restricted`: follow the documented presteps first
+   - `unsupported`: stop and explain the limitation
+8. For complex forms, production writes, attachments, relation-heavy payloads, or subtables, create with `verify_write=true`
+9. If verification fails, treat the write as not yet successful and inspect the missing or empty fields before reporting back
+10. Re-query or fetch the record when validation matters
+
+## Update pattern
+
+1. Query the target records
+2. Resolve exact `apply_id`
+3. Run `record_write_plan`
+4. Update only the intended fields
+5. Prefer `verify_write=true` for attachment, relation, subtable, or production updates
+6. Re-read the record if the change is important, attachment-related, subtable-related, or the form has linkage
+
+## Delete pattern
+
+1. Query or fetch the exact record first
+2. Confirm the target ids
+3. Delete
+4. Report affected ids and remaining count when relevant
+
+## Unsupported direct writes
+
+Do not attempt direct app-user writes for these field types:
+
+- `14` time range
+- `34` image recognition
+- `35` image generation
+- `36` document parsing
+
+If the payload includes them, stop at `record_write_plan` and explain that the tool does not build a reliable native payload for those fields yet.
+
+## Relation fields
+
+Relation fields are record-id based.
+
+- Query the referenced app first
+- Resolve the target record `apply_id`
+- Write the relation field with that id
+- Do not write relation fields with display titles, business keys, or guessed identifiers unless they have already been resolved to the real record id

package/skills/qingflow-app-user/references/workflow-usage.md

@@ -0,0 +1,24 @@
+# Workflow and Task Usage Actions
+
+Use these when the user is operating inside an existing process, not redesigning it.
+
+Examples:
+
+- add a comment to a record
+- approve or reject a workflow task
+- transfer a task
+- roll back a record
+- list pending, processed, or cc tasks
+- urge a pending task
+
+Rules:
+
+- if the user starts from inbox, todo, workload, cc, or bottleneck language, use `task_*` first
+- use `task_statistics` for counts and `task_list` or `task_list_grouped` for browsing
+- use `task_list_grouped` when grouped workload browsing matters
+- treat task counts as task-center counts, not record counts
+- switch to `record_*` after locating the exact business record behind a task
+- identify the exact record first
+- for approve or reject, identify the exact `nodeId` first; prefer task-center results or audit info, then use `task_approve` or `task_reject`
+- avoid usage-side flow actions on ambiguous records
+- summarize the final action and target task ids or record ids

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/builder_facade/models.py

@@ -43,6 +43,24 @@ FIELD_TYPE_ALIASES: dict[str, PublicFieldType] = {
     "departments": PublicFieldType.department,
 }
 
+FIELD_TYPE_ID_ALIASES: dict[int, PublicFieldType] = {
+    2: PublicFieldType.text,
+    3: PublicFieldType.long_text,
+    4: PublicFieldType.date,
+    5: PublicFieldType.member,
+    6: PublicFieldType.email,
+    7: PublicFieldType.phone,
+    8: PublicFieldType.number,
+    10: PublicFieldType.boolean,
+    11: PublicFieldType.single_select,
+    12: PublicFieldType.multi_select,
+    13: PublicFieldType.attachment,
+    18: PublicFieldType.subtable,
+    21: PublicFieldType.address,
+    22: PublicFieldType.department,
+    25: PublicFieldType.relation,
+}
+
 
 class PublicViewType(str, Enum):
     table = "table"
@@ -201,6 +219,10 @@ class ViewUpsertPatch(StrictModel):
         payload = dict(value)
         if "fields" in payload and "columns" not in payload:
             payload["columns"] = payload.pop("fields")
+        if "column_names" in payload and "columns" not in payload:
+            payload["columns"] = payload.pop("column_names")
+        if "columnNames" in payload and "columns" not in payload:
+            payload["columns"] = payload.pop("columnNames")
         raw_type = payload.get("type")
         if isinstance(raw_type, str):
             normalized = raw_type.strip().lower()
@@ -303,6 +325,17 @@ class FlowPlanRequest(StrictModel):
         payload = dict(value)
         if str(payload.get("mode") or "").strip().lower() == "overwrite":
             payload["mode"] = "replace"
+        raw_preset = payload.get("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,
+                "default_fill_then_approve": FlowPreset.basic_fill_then_approve.value,
+                "default-fill-then-approve": FlowPreset.basic_fill_then_approve.value,
+            }
+            if normalized_preset in preset_aliases:
+                payload["preset"] = preset_aliases[normalized_preset]
         return payload
 
 
@@ -332,7 +365,14 @@ def _normalize_field_payload(value: Any) -> Any:
     if not isinstance(value, dict):
         return value
     payload = dict(value)
+    if "fields" in payload and "subfields" not in payload:
+        payload["subfields"] = payload.pop("fields")
     raw_type = payload.get("type")
+    if isinstance(raw_type, int):
+        normalized_from_id = FIELD_TYPE_ID_ALIASES.get(raw_type)
+        if normalized_from_id is not None:
+            payload["type"] = normalized_from_id.value
+            return payload
     if isinstance(raw_type, str):
         normalized = FIELD_TYPE_ALIASES.get(raw_type.strip().lower())
         if normalized is not None: