@josephyan/qingflow-app-user-mcp 1.0.9 → 1.1.2

package/skills/qingflow-app-builder-code-integrations/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: qingflow-app-builder-code-integrations
+description: Configure Qingflow code block and Q-Linker fields through the builder surface when the task involves input field insertion, alias parsing, target field binding, or troubleshooting broken code/q-linker form configurations. Use after MCP is connected and authenticated, especially for CRM-style scoring, lookup, and enrichment forms.
+metadata:
+  short-description: Configure Qingflow code blocks and Q-Linkers safely
+---
+
+# Qingflow App Builder Code Integrations
+
+Use this skill when the user wants to build or repair:
+- `code_block` fields
+- `q_linker` fields
+- output alias parsing
+- target field binding
+- form configurations that depend on code block or Q-Linker relations
+
+Do not use this skill for MCP setup, generic field CRUD, or runtime execution debugging unless those are strictly supporting code block or Q-Linker configuration work.
+
+## Core Rule
+
+Treat code blocks and Q-Linkers as **integration fields**, not ordinary fields.
+
+For both of them, the public builder request may look like one step, but the real backend form structure has multiple layers. Never invent a new backend meaning. Only compile into the backend structures that already exist.
+
+## Mental Model
+
+### Code block
+
+There are three conceptual layers:
+
+1. Code block field itself
+2. Parsed output aliases
+3. Target field bindings
+
+Current builder support:
+- configure the code block field itself
+- configure input insertion into code content
+- configure alias parsing
+
+Important:
+- keep `qf_output = {...}` as a plain assignment
+- do not emit `const qf_output =` or `let qf_output =`
+
+### Q-Linker
+
+There are two conceptual layers:
+
+1. Q-Linker field itself via `remoteLookupConfig`
+2. Target field bindings via relation-default + `questionRelations(relationType=Q_LINKER)`
+
+Current builder support:
+- one-step high-level config through `q_linker_binding`
+- internal compilation into existing backend payloads
+
+## Operating Order
+
+For code block or Q-Linker work, use this order:
+
+1. Resolve the app and read fields:
+   - `app_resolve`
+   - `app_read_fields`
+2. Confirm the target field set already exists.
+3. Apply schema updates with `app_schema_apply`.
+4. Read fields again and verify:
+   - field type
+   - alias config
+   - target field binding shape
+5. For page-safety checks, use user-side schema or insert checks:
+   - `record_insert_schema_get`
+   - optional safe `record_insert`
+
+Do not treat raw apply success as enough. Always re-read the field config.
+
+## Code Block Rules
+
+Read [references/code-block.md](references/code-block.md) before changing a code block field.
+
+Use builder high-level config only for:
+- input field insertion
+- code content
+- alias parsing
+- auto trigger
+- custom button text
+
+When binding outputs to target fields, do not guess payload shape from memory. Follow the current builder implementation and the readback shape.
+
+Hard rules:
+- target fields must already exist
+- keep target field types business-compatible
+- if a page starts hanging on “关联中”, inspect whether the target field default type or relation config was written incorrectly
+
+## Q-Linker Rules
+
+Read [references/q-linker.md](references/q-linker.md) before changing a Q-Linker field.
+
+First-stage stable support is only:
+- custom mode
+- request config
+- alias parsing
+- target field binding
+- auto trigger / button text
+
+Do not generate:
+- template mode
+- openApp/light-wing branches
+- subtable table-match bindings
+
+Hard rules:
+- `outputs[*].target_field` is required
+- use only supported target field types
+- on rebinding, old target fields must be restored from relation-default to safe default type
+- `resultFormatPath` must preserve backend-required alias metadata
+
+## Verification Checklist
+
+After each code block or Q-Linker change, verify all of these:
+
+- `app_read_fields` shows the intended field type
+- the high-level config is readable and stable
+- target fields still have valid types
+- insert schema can be opened
+- record insert does not get blocked by malformed integration config
+
+If the task explicitly includes runtime verification, keep it separate from configuration verification.
+
+## Common Pitfalls
+
+- Writing code block code with `const qf_output =`
+- Treating a Q-Linker or code block binding as a plain field default
+- Forgetting to restore old target fields after unbinding
+- Using unsupported target field types
+- Assuming apply success means the form page can open
+
+## References
+
+- Code block details: [references/code-block.md](references/code-block.md)
+- Q-Linker details: [references/q-linker.md](references/q-linker.md)

package/skills/qingflow-app-builder-code-integrations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow Code Integrations"
+  short_description: "Configure Qingflow code block and Q-Linker fields safely"
+  default_prompt: "Use $qingflow-app-builder-code-integrations when configuring Qingflow code block or Q-Linker fields, especially when input insertion, alias parsing, target field binding, or page-safety verification matter."

package/skills/qingflow-app-builder-code-integrations/references/code-block.md

@@ -0,0 +1,66 @@
+# Code Block Builder Notes
+
+## What Builder Should Configure
+
+- code block field type
+- code content
+- inserted input fields inside code content
+- alias parsing
+- auto trigger
+- custom button text
+
+## Stable Writing Rules
+
+- Always emit `qf_output = {...}`
+- Never emit `const qf_output = {...}`
+- Never emit `let qf_output = {...}`
+
+## Useful CRM Pattern
+
+Inputs:
+- customer name
+- source
+- budget
+- timing
+- decision-maker flag
+
+Outputs:
+- score
+- level
+- priority
+- summary
+- next follow date
+
+## Target Field Rules
+
+Required:
+- every `outputs[*].target_field` must point to an existing field
+
+Allowed target field types:
+- text
+- long text
+- number
+- amount
+- date
+- datetime
+- single select
+- multi select
+- boolean
+
+Do not bind code block outputs to:
+- q_linker
+- code_block
+- relation
+- subtable
+- attachment
+- member
+- department
+- address
+
+## Safe Verification
+
+- `app_read_fields`
+- `record_insert_schema_get`
+- optional `record_code_block_run`
+
+Treat configuration verification and runtime verification as separate checks.

package/skills/qingflow-app-builder-code-integrations/references/q-linker.md

@@ -0,0 +1,77 @@
+# Q-Linker Builder Notes
+
+## What Builder Should Configure
+
+- `remoteLookupConfig`
+- alias parsing
+- target field binding
+- auto trigger
+- custom button text
+
+## Current Supported Scope
+
+- custom mode only
+- standard request fields
+- alias path parsing
+- target field binding to existing ordinary fields
+
+## Recommended Public APIs For Samples
+
+### Httpbin
+
+- URL: `https://httpbin.org/get`
+- Good for:
+  - query echo
+  - request URL echo
+
+Useful paths:
+- `$.args.keyword`
+- `$.url`
+
+### Open-Meteo Geocoding
+
+- URL: `https://geocoding-api.open-meteo.com/v1/search`
+- Good for:
+  - place normalization
+  - country
+  - lat/lng summary
+
+Useful paths:
+- `$.results[0].name`
+- `$.results[0].country`
+- `$.results[0].latitude`
+- `$.results[0].longitude`
+
+## Target Field Rules
+
+Required:
+- every `outputs[*].target_field` must point to an existing field
+
+Prefer:
+- text
+- long text
+- number
+- amount
+- date
+- datetime
+- single select
+- multi select
+- boolean
+
+Avoid:
+- q_linker
+- code_block
+- relation
+- subtable
+- attachment
+- member
+- department
+- address
+
+## Safe Verification
+
+- `app_read_fields`
+- `record_insert_schema_get`
+- `record_insert`
+
+This verifies that the configuration does not break the form page, even before runtime execution is tested.

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

@@ -54,7 +54,7 @@ Route to exactly one of these specialized paths:
 - If the task involves member, department, or relation fields and the user only has natural names/titles, keep the same route; direct write now supports backend-native auto resolution and may return `needs_confirmation` with candidates instead of failing blind
 - If the task involves linked visibility, upstream/downstream field dependencies, reference-driven auto fill, or formula-driven defaulting, keep the same insert/update route and read field-level `linkage` from the schema before composing payloads
 - If the task is about subtable writes, still route to the matching insert/update skill, but shape the payload as parent subtable field -> row array; do not route users toward top-level leaf selectors
-- If the task is insert-focused and readback consistency matters, keep the same route and prefer `record_get / record_list` with `output_profile="normalized"` after the write
+- If the task is insert-focused and readback/detail context matters, keep the same route and prefer the single-record detail readback after the write; use normalized list readback only when batch row shape is needed
 - If the user sounds like an ordinary workflow assignee rather than a system operator, prefer `$qingflow-task-ops` over direct record mutation whenever both paths could fit
 - If the task is about task discovery by natural language query, still route to `$qingflow-task-ops`; `task_list --query` now uses backend search first and only falls back to local matching when backend returns zero rows
 - If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
@@ -68,6 +68,7 @@ Route to exactly one of these specialized paths:
 - if the task can stay read-only, do not write or act
 - if the task involves a user-uploaded import file, do not modify the file unless the user explicitly authorizes repair or normalization
 - if the task involves record import, call `app_get` first and inspect `data.import_capability` before template download, file repair, or import start
+- if a record detail includes images or attachments, prefer the single-record detail tool's local paths: images from `media_assets.items[].local_path`, documents/tables from `file_assets.items[].local_path` and `extraction.text_path`; remote Qingflow file URLs are not stable direct-read targets
 - if the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation
 
 ## Shared Helper

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

@@ -6,17 +6,18 @@ For final statistics, grouped distributions, rankings, trends, or insight-style
 
 - For analysis-style reads, use `record_access` through [$qingflow-record-analysis](../../qingflow-record-analysis/SKILL.md)
 - `record_list` is for browsing and sample inspection only
-- `record_get` is for one exact record
+- `record_get` is for one exact record and downloads readable detail-page images into `media_assets.items[].local_path` plus attachments/documents/tables into `file_assets.items[].local_path`
 - Use `record_browse_schema_get` when field titles are uncertain instead of guessing ids
 - Do not present paged browse output as if it were a grouped or full-population conclusion
 - Use `record_export_direct` only when the user explicitly asks for export/download/Excel output
 
 ## Direct Writes
 
-- `record_insert` is schema-first through `record_insert_schema_get`
+- `record_insert` is schema-first through `record_insert_schema_get`; default to `items=[{"fields": {...}}]`
 - `record_update` is schema-first through `record_update_schema_get`
 - `record_delete` does not need a schema-get step
-- If a direct-write tool returns `ok=false`, the write was blocked and not executed
+- For batch insert, `partial_success` means some rows were created; use `created_record_ids`, failed `row_number`, and `failed_fields` to repair only failed rows
+- If a direct-write tool returns `write_executed=false`, the write was blocked and not executed for that item
 - Prefer `verify_write=true` for complex, relation-heavy, subtable, or production writes
 
 ## Lookup Fields
@@ -29,3 +30,4 @@ For final statistics, grouped distributions, rankings, trends, or insight-style
 
 - Subtable payloads stay under the parent table field as a row array
 - Attachment fields are two-step: upload first, then write the returned upload payload
+- For reads, attachment/rich-text images returned by `record_get` should be opened from local `media_assets` paths, and non-image files should be read from `file_assets` local paths or `extraction.text_path`, instead of remote file URLs

package/skills/qingflow-app-user/references/public-surface-sync.md

@@ -8,12 +8,12 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 ### User data
 
 - Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
-- Treat `record_browse_schema_get.fields` as the selected Qingflow table view header schema; `record_access.fields` and `schema.json` must stay aligned with it.
+- Treat `record_browse_schema_get.fields` as the selected Qingflow table view header schema; `record_access.fields` and `record_list` field selectors must stay aligned with it.
 - Standard flows:
   - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
   - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`
   - explicit export/download/Excel: `view_get -> record_export_*` or `record_export_direct`
-  - insert: `record_insert_schema_get -> record_insert`
+  - insert: `record_insert_schema_get -> record_insert(items)`
   - update: `record_update_schema_get -> record_update`
 
 ### Tasks
@@ -39,11 +39,14 @@ It is not a user-facing product spec. It exists to prevent skill drift.
   - `app_layout_apply`
   - `app_flow_apply`
   - `app_views_apply`
+  - `app_custom_buttons_apply`
+  - `app_associated_resources_apply`
   - `app_charts_apply`
   - `portal_apply`
   - `app_publish_verify`
 - `portal_apply` edit mode may omit `sections` for base-info-only updates
 - `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
+- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
 - `app_get.editability` uses:
   - `can_edit_app_base`
   - `can_edit_form`
@@ -57,7 +60,7 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 - Package public tools: do not regress to `package_create` / `package_attach_app` as the public default story
 - App editability: do not let `can_edit_form` imply app base-info writes
 - Portal and chart visibility: keep the public story on `portal_apply` / `app_charts_apply`, not low-level internal writes
-- Analysis path: standard path stays `record_access -> Python`; `record_analyze` is a lightweight non-default helper
+- Analysis path: standard path stays `record_access -> Python`
 
 ## Release Checklist For Skill Maintenance
 

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

@@ -10,6 +10,14 @@ Use `record_browse_schema_get -> record_list` when:
 - the target `record_id` is unknown
 - a delete target still needs confirmation
 - the user needs sample rows or a small export
+- the user gives fuzzy text such as a company, project, bug, or contract name
+
+For fuzzy lookup, pass `query` and optional `query_fields`. `record_list` returns at most 10 `data.items`, plus `data.pagination.total_count` and `lookup.next_action`.
+
+- `lookup.next_action="record_get"`: read the single returned item with `record_get`
+- `lookup.next_action="ask_user"`: ask the user to choose from returned `data.items`
+- `lookup.next_action="refine_query"`: ask for a narrower keyword or add `query_fields`
+- `lookup.next_action="broaden_query"`: remove overly narrow fields or ask for another clue
 
 ## Detail Pattern
 
@@ -18,16 +26,18 @@ Use `record_browse_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
+- the user needs images or attachments shown on the detail page; read downloaded images from `media_assets.items[].local_path`, and read documents/tables from `file_assets.items[].local_path` or `extraction.text_path`
 
 ## Insert Pattern
 
-Use `record_insert_schema_get -> record_insert`.
+Use `record_insert_schema_get -> record_insert(items)`.
 
 1. Confirm the target app
 2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`
-3. Build a field-title keyed `fields` map
-4. If lookup fields are ambiguous, stop and ask for confirmation
-5. Run `record_insert`
+3. Build `items` as `[{"fields": {...}}]`; a single record is one item
+4. Write member, department, and relation fields with natural strings first when the user provided names
+5. If lookup fields are ambiguous, stop and ask for confirmation
+6. On `partial_success`, keep `created_record_ids` and only repair failed `row_number` / `failed_fields`
 
 ## Update Pattern
 

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

@@ -0,0 +1,111 @@
+---
+name: qingflow-mcp-setup
+description: Install, connect, authenticate, and troubleshoot the Qingflow MCP server in local AI clients such as Claude Desktop or any stdio-compatible MCP client. Use when the user wants to configure the MCP, verify local startup, log in with token/password, select a workspace, or fix connection/authentication issues.
+metadata:
+  short-description: Install and connect the Qingflow MCP locally
+---
+
+# Qingflow MCP Setup
+
+## Overview
+
+This skill sets up the local Qingflow MCP server, connects it to a local AI client, and verifies authentication and workspace selection. Use it for installation, client configuration, token login, and connection troubleshooting.
+
+## Workflow
+
+Follow these steps in order.
+
+`feedback_submit` is also available as a cross-cutting helper when setup or MCP capability gaps still block the user after reasonable troubleshooting. It does not require Qingflow login or workspace selection, and should be called only after explicit user confirmation.
+
+Before configuration or live calls, identify the target environment explicitly as `test` or `prod`, then read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
+
+### Step 1: Verify the local project path
+
+Resolve the repository root first. In this repo, the MCP server should live at:
+
+- `<repo_root>/qingflow-support/mcp-server`
+
+Key entrypoint:
+
+- `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+
+If the path differs, stop and update all client config snippets before proceeding.
+If the skill is installed under `$CODEX_HOME/skills` instead of the repo-local `.codex/skills`, set `QINGFLOW_MCP_ROOT=<repo_root>/qingflow-support/mcp-server` before running `scripts/check_local_server.sh`.
+
+### Step 2: Install local dependencies
+
+Run:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+python3 -m venv .venv
+./.venv/bin/pip install -e '.[dev]'
+```
+
+Use `scripts/check_local_server.sh` to verify the entrypoint and virtualenv. The script will first try `QINGFLOW_MCP_ROOT`, then the current git repo, then a repo-local `.codex/skills` layout.
+
+### Step 3: Configure the local AI client
+
+For any stdio-compatible MCP client, map these values:
+
+- `command`: `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+- `args`: `[]`
+- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: the target backend URL for the active environment
+- `env.QINGFLOW_MCP_DEFAULT_QF_VERSION`: set this when the environment must route to a specific version such as `canary`
+
+Client-specific snippets:
+
+- Claude Desktop: read [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio MCP clients: read [references/generic-stdio.md](references/generic-stdio.md)
+
+When both test and production are in play, keep separate config snippets or clearly labeled `env` blocks so the user can switch without ambiguity.
+
+### Step 4: Validate startup
+
+The server is a stdio MCP process. A direct terminal launch may print nothing and wait for a client. That is normal.
+
+Manual startup command:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+./qingflow-mcp
+```
+
+Prefer validating through the client after config is added.
+
+### Step 5: Authenticate and select workspace
+
+Recommended order inside the client:
+
+1. `auth_use_token` or `auth_login`
+2. `workspace_list`
+3. `workspace_select`
+4. Only then use business tools
+
+If the user already knows the target workspace, prefer `auth_use_token(..., ws_id=<id>)`.
+After auth, prefer one read-only tool call that returns `request_route` so you can confirm the live `base_url` and `qf_version` before proceeding.
+`auth_use_token` is a tool call, not a custom HTTP header. The runtime injects `token`, `wsId`, and when needed `Cookie: qfVersion=...` after the session is established.
+Do not skip `workspace_select` on production paths. If `/user` does not return a version lane, the session now falls back to the workspace `systemVersion`.
+
+### Step 6: Troubleshoot in the right layer
+
+- If the client cannot launch the server, check path, execute permission, and `.venv`
+- If tools return `auth required`, re-run `auth_use_token` or `auth_login`
+- If tools return `workspace not selected`, call `workspace_list` and `workspace_select`
+- If calls fail after a working session, assume token expiry and re-authenticate
+- If the browser shows data but MCP does not, compare `request_route` against the browser environment and check whether `qf_version` should be `canary`
+
+## Guardrails
+
+- Never write tokens into the skill files
+- Never assume a workspace is selected until `auth_whoami` or `workspace_select` confirms it
+- When debugging, distinguish server startup issues from Qingflow auth issues
+- When the user mentions production, restate the exact `base_url`, `qf_version`, and workspace before any live validation
+- If setup is complete but the current MCP capability is still unsupported or the user's need still cannot be satisfied, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation
+
+## Resources
+
+- Environment switching: [references/environments.md](references/environments.md)
+- Claude Desktop config: [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio config: [references/generic-stdio.md](references/generic-stdio.md)
+- Local checks: [scripts/check_local_server.sh](scripts/check_local_server.sh)

package/skills/qingflow-mcp-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow MCP Setup"
+  short_description: "Install and connect the Qingflow MCP locally"
+  default_prompt: "Use $qingflow-mcp-setup to install and connect the Qingflow MCP in a local AI client, and to verify the active base_url, qf_version, auth state, and workspace selection."

package/skills/qingflow-mcp-setup/references/claude-desktop.md

@@ -0,0 +1,34 @@
+# Claude Desktop
+
+Use this when the user wants to install Qingflow MCP in Claude Desktop.
+
+## Config snippet
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp",
+      "args": [],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "<QINGFLOW_BASE_URL>"
+      }
+    }
+  }
+}
+```
+
+## Environment examples
+
+- `prod` (default): set `QINGFLOW_MCP_DEFAULT_BASE_URL` to `https://qingflow.com/api`
+- `test`: if needed, set `QINGFLOW_MCP_DEFAULT_BASE_URL` to the explicitly provided non-production backend
+
+Keep separate snippets for `test` and `prod` so switching environments does not require editing values in-place under pressure.
+
+## Notes
+
+- After updating the config, restart Claude Desktop
+- Replace `<ABSOLUTE_PATH_TO_REPO>` with the real checkout path on the current machine
+- If the server path changes, update the `command` field
+- The server is local stdio MCP, so no remote URL is required
+- Do not store Qingflow token in Claude Desktop config; pass it through `auth_use_token` inside the chat

package/skills/qingflow-mcp-setup/references/environments.md

@@ -0,0 +1,61 @@
+# Environment Switching
+
+Use this reference before any setup, authentication, or live validation flow.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the user is targeting:
+
+- `test`: for smoke tests, trial setup, DSL validation, mock data, and integration debugging
+- `prod`: for real business usage in the formal environment
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Default characteristics:
+
+- preferred for first-time setup and local MCP validation
+- mock or smoke data is acceptable when the user asks for it
+- use read/write verification freely inside the intended test workspace
+
+Known values in the current workspace:
+
+- use an explicitly provided non-production backend
+- common test workspace example: `ws_id=2`
+- `qf_version`: usually unset unless the user explicitly needs a routed version
+
+Setup behavior:
+
+- prefer this environment for Claude Desktop or local MCP client onboarding
+- use `auth_use_token` or `auth_login`, then `workspace_list`, then `workspace_select`
+- if the user asks to verify installation, a real read-only smoke path is acceptable
+
+## Production Environment
+
+Production is the default environment when the user does not specify one. If the user explicitly says `test`, switch to the dedicated non-production backend they provide.
+
+Expected behavior:
+
+- default `base_url`: `https://qingflow.com/api`
+- confirm the production `qf_version` explicitly when browser traffic depends on routed versions such as `canary`
+- confirm the exact workspace before any live validation
+- prefer read-only checks first
+- avoid mock data, smoke writes, or destructive tests unless the user explicitly asks for them
+
+Production guardrails:
+
+- do not store credentials in skill files or examples
+- do not assume the same workspace ids as test
+- treat startup verification and auth verification as separate steps
+- when sharing snippets, label them as `prod` and `test` clearly
+- when MCP and browser results diverge, compare `request_route` with the browser route before blaming the query logic
+
+## Reporting Rule
+
+When you give setup instructions, always state:
+
+- active environment
+- selected `base_url`
+- selected `qf_version` when relevant
+- whether the next step is read-only or write-impacting

package/skills/qingflow-mcp-setup/references/generic-stdio.md

@@ -0,0 +1,31 @@
+# Generic Stdio MCP Clients
+
+Use this for any local AI client that supports MCP over stdio.
+
+## Required mapping
+
+- `command`: `<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp`
+- `args`: `[]`
+- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: backend base URL for the active environment
+
+Environment examples:
+
+- `prod` (default): `https://qingflow.com/api`
+- `test`: use the explicitly provided non-production backend
+
+Keep separate client entries or separate config snippets for `test` and `prod`.
+
+## Validation sequence
+
+1. Start the client
+2. Confirm the `qingflow` MCP server is visible
+3. Run `auth_use_token`
+4. Run `workspace_list`
+5. Run `workspace_select`
+6. Run a read-only tool such as `app_list`
+
+## Common failures
+
+- Launch failure: bad `command` path or missing `.venv`
+- Auth failure: invalid or expired token
+- Business tool failure before setup: workspace not selected