@josephyan/qingflow-app-user-mcp 0.2.0-beta.2 → 0.2.0-beta.21

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.2
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.21
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.2 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.21 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -19,3 +19,13 @@ 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 skills:
+
+- `skills/qingflow-app-user`
+- `skills/qingflow-record-analysis`
+
+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.2",
+  "version": "0.2.0-beta.21",
   "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.0b2"
+version = "0.2.0b21"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -0,0 +1,230 @@
+---
+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 browse, read, write, comment on, or act on existing business records and task-center work. Do not use this skill for schema design or final statistical analysis.
+metadata:
+  short-description: Schema-first operational use of Qingflow apps
+---
+
+# Qingflow App User
+
+## Overview
+
+This skill is for **operational usage** inside existing Qingflow apps.
+
+Use it for:
+
+- record browsing
+- record detail lookup
+- record create / update / delete
+- task-center usage
+- record comments
+- approval / reject / rollback / transfer
+- directory lookup
+
+Do **not** keep grouped analysis, ratios, rankings, trends, or final statistical conclusions inside this skill.  
+For those, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md).
+
+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`.
+
+## Default Paths
+
+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(mode="plan") -> record_write(mode="apply")`
+
+4. Work task center  
+   `task_summary / task_list / task_facets`
+
+5. Analysis  
+   Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+
+## Tool Scope
+
+Primary record tools:
+
+- `record_schema_get`
+- `record_list`
+- `record_get`
+- `record_write`
+
+Directory tools:
+
+- `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`
+
+Task-center tools:
+
+- `task_summary`
+- `task_list`
+- `task_facets`
+- `task_mark_read`
+- `task_mark_all_cc_read`
+- `task_urge`
+
+Comments and workflow usage actions:
+
+- `record_comment_write`
+- `record_comment_list`
+- `record_comment_mentions`
+- `record_comment_mark_read`
+- `task_approve`
+- `task_reject`
+- `task_rollback_candidates`
+- `task_rollback`
+- `task_transfer_candidates`
+- `task_transfer`
+
+Do not use builder-side tools here.
+
+## Standard Operating Order
+
+1. Ensure auth exists
+2. Ensure workspace is selected
+3. Confirm target app and whether the task is browse / detail / write / task / 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, task actions, or production changes, read the current state first whenever practical
+9. After actions, report the affected `record_id`, `task_id`, counts, or returned item count
+
+## Record Read Rules
+
+- Use `record_list` for browse/export/sample inspection only
+- Use `record_get` when `record_id` is known
+- `record_list` accepts:
+  - `columns`
+  - `where`
+  - `order_by`
+  - `limit`
+  - `page`
+- `record_list` is **not** an analysis tool
+- If a request turns into grouped distributions, ratios, rankings, trends, or final statistical conclusions, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+
+## Record Write Rules
+
+Use `record_write` as the only default write tool.
+
+### Write workflow
+
+1. Run `record_schema_get`
+2. Decide whether the task is `insert`, `update`, or `delete`
+3. Build SQL-like JSON clauses
+4. Run `record_write(mode="plan")`
+5. If blockers are empty, run `record_write(mode="apply")`
+6. For important writes, keep `verify_write=true`
+
+### SQL-like JSON DSL
+
+The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
+
+#### Insert
+
+```json
+{
+  "operation": "insert",
+  "mode": "plan",
+  "values": [
+    { "field_id": 12, "value": "测试客户" },
+    { "field_id": 18, "value": 1000 }
+  ],
+  "submit_type": "submit",
+  "verify_write": true
+}
+```
+
+#### Update
+
+```json
+{
+  "operation": "update",
+  "mode": "plan",
+  "record_id": 123,
+  "set": [
+    { "field_id": 18, "value": 2000 }
+  ],
+  "verify_write": true
+}
+```
+
+#### Delete
+
+```json
+{
+  "operation": "delete",
+  "mode": "plan",
+  "record_ids": [123, 124]
+}
+```
+
+### Write discipline
+
+- `insert` uses `values`
+- `update` uses `set`
+- `delete` uses `record_id` or `record_ids`
+- Do not send raw SQL text
+- Do not invent formulas or expressions
+- Do not use free-form `WHERE` updates or deletes
+- Do not auto-fill missing fields
+- Do not auto-resolve relation targets without first querying them
+
+## Task-Center Rules
+
+- Use `task_summary` for headline counts
+- Use `task_list` for flat browsing
+- Use `task_facets` for grouped worksheet or workflow-node buckets
+- `task_box` must be one of:
+  - `todo`
+  - `initiated`
+  - `cc`
+  - `done`
+- `flow_status` must be one of:
+  - `all`
+  - `in_progress`
+  - `approved`
+  - `rejected`
+  - `pending_fix`
+  - `urged`
+  - `overdue`
+  - `due_soon`
+  - `unread`
+  - `ended`
+- Find the exact task or record first, then use `task_approve`, `task_reject`, `task_rollback`, or `task_transfer`
+- Do not guess `workflow_node_id`
+
+## Directory and Comments
+
+- Use `directory_search` for fuzzy member/department lookup
+- Use `directory_list_all_internal_users` and `directory_list_all_departments` only when the user explicitly wants a complete export
+- Use `record_comment_write` after the exact `record_id` is known
+- Use `record_comment_mentions` to resolve mention candidates before building complex comment payloads
+
+## Response Interpretation
+
+- `record_list` returns browse/sample data, not final analysis conclusions
+- `record_write(mode="plan")` is static preflight, not runtime execution
+- `record_write(mode="apply")` may still surface verification failures
+- Treat `request_route` as the source of truth for live route debugging
+- Prefer canonical schema titles and aliases in your final wording
+- If only part of the requested work is completed, explicitly disclose which parts are done and which are not
+
+## 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)
+- Dedicated analysis workflow: [qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.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 for ordinary Qingflow record, task, comment, and directory operations. If the task shifts into grouped analysis, insight generation, ranking, trend, or final statistical conclusions, switch to $qingflow-record-analysis instead of keeping the logic here."

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

@@ -0,0 +1,49 @@
+# Data Gotchas
+
+For final statistics, grouped distributions, rankings, trends, or insight-style conclusions, use [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md) instead of keeping that reasoning inside `$qingflow-app-user`.
+
+## Record Reads
+
+- `record_list` is for browsing, export, and sample inspection only
+- `record_get` is for one exact record
+- Do not present paged browse output as if it were a grouped or full-population conclusion
+- If the browser and MCP disagree, compare `request_route.base_url` and `request_route.qf_version` first
+
+## Write Preflight
+
+- `record_write(mode="plan")` is static preflight only; linked visibility and runtime required rules can still reject writes
+- Use `record_schema_get` when field titles are uncertain instead of guessing ids
+- Prefer `verify_write=true` for complex, relation-heavy, subtable, or production writes
+- `record_write(mode="apply")` may still surface verification failures; do not report success before checking them
+
+## Write Semantics
+
+- `insert` uses `values`
+- `update` uses `set`
+- `delete` uses `record_id` or `record_ids`
+- Do not send raw SQL strings
+- Do not fake formula or expression fields
+- Do not perform free-form bulk updates or deletes
+- Do not guess relation targets from display text; resolve the real `record_id` first
+
+## 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 row ids if the source record returns them
+- 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_write(operation="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,110 @@
+# Record Patterns
+
+If the task shifts into grouped analysis, ratio, ranking, trend, or any final statistical conclusion, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md).
+
+## Browse Pattern
+
+Use `record_schema_get -> record_list` when:
+
+- the user wants to browse records
+- the target `record_id` is unknown
+- a delete or update target still needs confirmation
+- the user needs sample rows or a small export
+
+Keep the browse DSL simple:
+
+- `columns`: field ids only
+- `where`: flat AND filters only
+- `order_by`: field sorting only
+- `limit` and `page`: browsing intent only
+
+Do not use `record_list` for grouped conclusions, ratios, rankings, trends, or any final statistical claim.
+
+## Detail Pattern
+
+Use `record_schema_get -> record_get` when:
+
+- the exact `record_id` is known
+- the user needs one record in detail
+- a write target needs verification before action
+
+Prefer passing explicit `columns` when the user only needs a subset of fields.
+
+## Write Pattern
+
+Use `record_schema_get -> record_write(mode="plan") -> record_write(mode="apply")`.
+
+1. Confirm the target app
+2. Resolve fields with `record_schema_get`
+3. Decide whether the task is `insert`, `update`, or `delete`
+4. Build SQL-like JSON clauses
+5. Run `record_write(mode="plan")`
+6. If blockers are empty, run `record_write(mode="apply")`
+7. For important writes, keep `verify_write=true`
+
+### Insert
+
+```json
+{
+  "operation": "insert",
+  "mode": "plan",
+  "values": [
+    { "field_id": 12, "value": "测试客户" },
+    { "field_id": 18, "value": 1000 }
+  ],
+  "submit_type": "submit",
+  "verify_write": true
+}
+```
+
+### Update
+
+```json
+{
+  "operation": "update",
+  "mode": "plan",
+  "record_id": 123,
+  "set": [
+    { "field_id": 18, "value": 2000 }
+  ],
+  "verify_write": true
+}
+```
+
+### Delete
+
+```json
+{
+  "operation": "delete",
+  "mode": "plan",
+  "record_ids": [123, 124]
+}
+```
+
+## Write Anti-Patterns
+
+Do not do this:
+
+- do not send raw SQL text
+- do not build free-form `WHERE` updates or deletes
+- do not invent formulas or expressions
+- do not auto-fill missing required fields
+- do not guess relation targets without first resolving them
+- do not skip `mode="plan"` on non-trivial writes
+
+## 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(mode="plan")` and explain that the tool does not support a reliable direct write for those fields yet.
+
+## Relation, Attachment, and Subtable Rules
+
+- Relation fields are record-id based. Resolve the referenced target first, then write the relation field with the real `record_id`.
+- Attachment fields are two-step: upload first with `file_upload_local`, then reuse the returned attachment payload in `record_write`.
+- Subtable writes require the current schema shape; when updating existing subtable rows, preserve row ids if the current record exposes them.

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

@@ -0,0 +1,26 @@
+# 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 task
+- list todo, initiated, done, or cc tasks
+- inspect workload by worksheet or workflow node
+- urge a pending task
+
+Rules:
+
+- if the user starts from inbox, todo, workload, cc, or bottleneck language, use `task_*` first
+- use `task_summary` for headline counts
+- use `task_list` for flat browsing
+- use `task_facets` when worksheet or workflow-node buckets matter
+- treat task counts as task-center counts, not record counts
+- switch to `record_*` only after locating the exact business record behind a task
+- identify the exact target first
+- for approve or reject, identify the exact `workflow_node_id` first; prefer task-center results or current audit info, then use `task_approve` or `task_reject`
+- avoid usage-side workflow actions on ambiguous records
+- summarize the final action and target task ids or record ids