@qingflow-tech/qingflow-app-user-mcp 1.0.0

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

@@ -0,0 +1,29 @@
+---
+name: qingflow-record-delete
+description: Delete Qingflow records safely after the MCP is already connected and authenticated.
+metadata:
+  short-description: Qingflow record delete
+---
+
+# Qingflow Record Delete
+
+## Default Path
+
+`record_list / record_get -> record_delete`
+
+## Core Tools
+
+- `record_list`
+- `record_get`
+- `record_delete`
+
+## Working Rules
+
+1. Resolve the exact target `record_id` first
+2. Prefer reading the current state before delete when the request is high risk
+3. Call `record_delete` with `record_id` or `record_ids`
+
+## Do Not
+
+- Do not pass any `view_*` selector
+- Do not infer the target record id from a vague title if `record_list` can disambiguate it

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

@@ -0,0 +1,31 @@
+---
+name: qingflow-record-import
+description: Explain and operate Qingflow file-based bulk import after the MCP is already connected and authenticated.
+metadata:
+  short-description: Qingflow bulk import workflow and troubleshooting
+---
+
+# Qingflow Record Import
+
+## Default Path
+
+`app_get -> record_import_schema_get -> record_import_template_get -> record_import_verify -> (optional authorized repair) -> record_import_start -> record_import_status_get`
+
+## Core Tools
+
+- `app_get`
+- `record_import_schema_get`
+- `record_import_template_get`
+- `record_import_verify`
+- `record_import_repair_local`
+- `record_import_start`
+- `record_import_status_get`
+
+## Working Rules
+
+1. Inspect `app_get.data.import_capability` first
+2. Read `record_import_schema_get` before touching the file when column meaning is unclear
+3. Keep official headers unchanged
+4. Verify before start
+5. Only repair a file after explicit user authorization
+6. Read back one imported sample after success

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

@@ -0,0 +1,58 @@
+---
+name: qingflow-record-insert
+description: Create Qingflow records with a schema-first insert workflow after the MCP is already connected and authenticated.
+metadata:
+  short-description: Schema-first Qingflow record insert
+---
+
+# Qingflow Record Insert
+
+## Default Path
+
+`record_insert_schema_get -> (optional candidate lookup / confirmation) -> record_insert`
+
+## Core Tools
+
+- `record_insert_schema_get`
+- `record_insert`
+- `record_member_candidates`
+- `record_department_candidates`
+- `file_upload_local`
+
+## Working Rules
+
+1. Start with `record_insert_schema_get`
+2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`
+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 `fields` from the manually-supplied required/optional fields in that schema
+6. Treat `runtime_linked_required_fields` as required-but-not-directly-writable runtime/upstream dependencies, not as fields to hand-fill blindly
+7. For `linkage.kind=logic_visibility`, read `sources` as upstream trigger fields and treat `role=manual_input_after_activation` as "fill this only after the upstream condition is satisfied"
+8. For `linkage.kind=reference_fill`, prefer filling the source field first; treat target fields with `role=auto_fill_preferred` or `auto_fill_only` as reference-driven outputs rather than blind manual inputs
+9. For `linkage.kind=formula_fill`, treat the field as formula/default-auto-fill driven unless the user explicitly asks to override it and the field is still writable
+10. If insert succeeds and readback shape matters, prefer `record_get(..., output_profile="normalized")` or `record_list(..., output_profile="normalized")`
+11. Keep subtable payloads under the parent field as a row array
+12. Member / department / relation fields may accept natural strings directly
+13. If the write returns `status="needs_confirmation"`, stop and surface the candidates
+14. Retry with explicit ids / objects only after the user confirms
+15. Keep `verify_write=true` for production inserts
+
+## Field Notes
+
+- `searchable_fields` on relation fields defines the backend-native searchable columns
+- `accepts_natural_input=true` means the field may accept a natural string before explicit id fallback
+- `may_become_required=true` means the field is writable now, but may turn required after linked visibility or option rules activate
+- `linkage.kind=logic_visibility` means the field is statically tied to linked visibility or option-driven rules
+- `linkage.kind=reference_fill` means the field participates in reference-based auto fill or default matching logic
+- `linkage.kind=formula_fill` means the field usually comes from formula/default auto-fill logic
+- `linkage.sources` lists the upstream field titles that influence the current field
+- `linkage.affects_fields` lists downstream field titles that may change when this field changes
+- `linkage.role=auto_fill_only` means "normally do not hand-fill this unless the product explicitly requires it"
+- `requires_upload=true` means upload the file first, then write the returned value
+
+## Do Not
+
+- Do not skip `record_insert_schema_get`
+- Do not invent missing required fields
+- Do not flatten subtable leaf fields to the top level
+- Do not silently guess member / department / relation ids

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

@@ -0,0 +1,42 @@
+---
+name: qingflow-record-update
+description: Update Qingflow records with a schema-first record-specific workflow after the MCP is already connected and authenticated.
+metadata:
+  short-description: Schema-first Qingflow record update
+---
+
+# Qingflow Record Update
+
+## Default Path
+
+`record_update_schema_get -> record_update`
+
+## Core Tools
+
+- `record_update_schema_get`
+- `record_update`
+- `record_get`
+- `record_list`
+
+## Working Rules
+
+1. Start with `record_update_schema_get(app_key, record_id)`
+2. Use only `writable_fields` and `payload_template` from that response
+3. Read field-level `linkage` before composing updates; it is the static hint for whether a field is a linked source, linked target, reference-driven auto fill field, or formula-driven field
+4. Build `fields` as a field-title keyed map
+5. Build `fields` only from that returned field set; MCP will choose the first matched accessible view that can execute the payload
+6. If a field has `linkage.affects_fields`, treat it as a source field; changing it may also change how other fields are interpreted or auto-filled
+7. If a field has `linkage.sources`, treat those titles as upstream dependencies that explain why the field matters or why its validation can change
+8. For `linkage.kind=reference_fill`, prefer updating the source reference field first and treat `role=auto_fill_preferred` or `auto_fill_only` targets as outputs of that reference relationship
+9. For `linkage.kind=formula_fill`, treat the field as formula/default-auto-fill driven unless the field is still clearly writable and the user explicitly wants to override it
+10. Keep `verify_write=true` for production updates
+11. If the write returns `status="needs_confirmation"`, stop and surface the candidates
+12. Do not assume any arbitrary combination of writable fields will succeed; one single matched accessible view still has to cover the payload
+13. Do not look for any extra context bucket in update schema; lookup behavior stays inline on the field definitions themselves
+
+## Do Not
+
+- Do not pass any `view_*` selector
+- Do not update fields missing from `writable_fields`
+- Do not resolve lookup fields against a guessed record context
+- Do not ignore `linkage.affects_fields` when changing source-like fields on complex forms

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

@@ -0,0 +1,123 @@
+---
+name: qingflow-task-ops
+description: Use Qingflow todo discovery, workflow task context, associated approval context, workflow logs, and unified task actions after the MCP is already connected and authenticated. Do not use this skill for record CRUD or final statistical analysis.
+metadata:
+  short-description: Qingflow task workflow context and actions
+---
+
+# Qingflow Task Ops
+
+## Overview
+
+This skill is for task workflow operations only.
+Assumes MCP is connected, authenticated, and on the correct workspace.
+
+## Default Paths
+
+Use exactly one of these default paths:
+
+1. Find target todos  
+   `task_list`
+
+2. Read one task context  
+   `task_list -> exact target -> task_get`
+
+3. Read associated approval context  
+   `task_get -> task_associated_report_detail_get` or `task_workflow_log_get`
+
+4. Execute workflow action  
+   `task_list -> exact target -> task_get -> task_action_execute`
+
+## Core Tools
+
+- `task_list`
+- `task_get`
+- `task_action_execute`
+- `task_associated_report_detail_get`
+- `task_workflow_log_get`
+
+## Supporting Tools
+
+- `app_list`
+- `app_search`
+
+## Standard Operating Order
+
+1. Ensure auth exists
+2. Ensure workspace is selected
+3. Discover the exact target with `task_list`
+4. Read node context with `task_get`
+5. Before giving any approval recommendation, read `task_workflow_log_get`
+6. If `task_get` returns any `associated_reports`, read every visible report through `task_associated_report_detail_get`
+7. Give an approval recommendation only after reviewing the node context, workflow log, and associated report details
+8. Wait for explicit user confirmation before `task_action_execute`
+9. Execute through `task_action_execute`
+10. After actions, report the exact `app_key`, `record_id`, `workflow_node_id`, and executed action
+
+## Task-Center Rules
+
+- Use `task_list` for flat browsing
+- `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`
+- `task_list` is the only public task discovery path in this MCP surface
+- Treat `task_id` as a locator only; the action primary key is `app_key + record_id + workflow_node_id`
+- Default box usage:
+  - `todo`: `task_list -> task_get -> task_workflow_log_get / task_associated_report_detail_get -> recommendation -> explicit user confirmation -> task_action_execute`
+  - `initiated`: `task_list -> record_get`
+  - `done`: `task_list -> record_get`
+  - `cc`: `task_list -> record_get`
+- Treat `initiated`, `done`, and `cc` primarily as list-plus-record-detail flows, not task action flows
+
+## Workflow Usage Actions
+
+- `task_get.capabilities.available_actions` is the source of truth for v1 executable actions
+- Current public actions are:
+  - `approve`
+  - `reject`
+  - `rollback`
+  - `transfer`
+  - `urge`
+- Before any approve/reject/rollback/transfer recommendation, always review `task_workflow_log_get` when `task_get.visibility.audit_record_visible=true`
+- If `task_get` returns visible `associated_reports`, review each one with `task_associated_report_detail_get`; do not rely on report summary alone
+- Do not give an approval recommendation based only on `task_get`
+- Do not execute `task_action_execute` until the user explicitly confirms the chosen action
+- Avoid actions on ambiguous tasks or records
+- Summarize the final action and the exact `app_key / record_id / workflow_node_id`
+- `task_action_execute` now distinguishes action execution from workflow continuation. Read `verification.runtime_continuation_verified` before claiming the workflow actually moved on.
+- If `task_action_execute` returns `partial_success` with `WORKFLOW_CONTINUATION_UNVERIFIED`, report the action as sent but the downstream continuation as unverified.
+- If `task_action_execute` returns `TASK_CONTEXT_VISIBILITY_UNVERIFIED` after a `46001`-style context loss, do not claim the task was already processed unless the workflow log or record state proves it.
+
+## Feedback Escalation
+
+- If task capabilities, associated report detail, workflow log visibility, or action support still cannot satisfy the user's goal after reasonable use of this skill, summarize the exact gap in plain language.
+- Ask whether the user wants you to submit product feedback.
+- Only after explicit user confirmation, call `feedback_submit`.
+
+## Response Interpretation
+
+- `task_list` returns normalized todo rows and is the only default discovery path
+- `task_get` returns node context summary, not full historical report data
+- `task_associated_report_detail_get` may return either:
+  - `result_type=view_list`
+  - `result_type=chart_data`
+- `task_workflow_log_get` returns workflow log detail only when the node grants log visibility
+- Treat `request_route` as the source of truth for live route debugging
+- If only part of the requested work is completed, explicitly disclose which parts are done and which are not
+
+## Resources
+
+- Workflow and task usage actions: [references/workflow-usage.md](references/workflow-usage.md)

package/skills/qingflow-task-ops/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow Task Ops"
+  short_description: "Use Qingflow task center, comments, directory, and workflow actions"
+  default_prompt: "Use $qingflow-task-ops for Qingflow task-center browsing, workload facets, comments, directory lookup, and workflow usage actions. Locate the exact target first, then run the smallest explicit task or comment action."

package/skills/qingflow-task-ops/references/environments.md

@@ -0,0 +1,44 @@
+# Environment Switching
+
+Use this reference before any workflow usage action, comment, or task-center operation that might affect live work.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the task targets:
+
+- `test`: demo, mock data, smoke usage validation, training scenarios
+- `prod`: real operational tasks, comments, and workflow actions
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Use test for:
+
+- workflow walkthroughs
+- user acceptance demos
+- comment or transfer rehearsals
+
+## Production Environment
+
+Use production for:
+
+- live task-center operations
+- live comments on real business records
+- approve / reject / rollback / transfer / urge on real work
+
+Production guardrails:
+
+- never assume a task id, record id, or workflow node id
+- find the exact target first
+- if the task can be answered read-only, do not act
+
+## Reporting Rule
+
+For task ops, always report:
+
+- active environment
+- target app or task box
+- operation type: read, comment, approve, reject, rollback, transfer, urge, or mark_read
+- affected task ids or record ids
+

package/skills/qingflow-task-ops/references/workflow-usage.md

@@ -0,0 +1,27 @@
+# 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_get` 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
+

package/src/qingflow_mcp/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0b87"

package/src/qingflow_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for running qingflow_mcp as a module."""
+from qingflow_mcp.server import main
+
+if __name__ == "__main__":
+    main()