@josephyan/qingflow-app-builder-mcp 0.2.0-beta.68 → 0.2.0-beta.69

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.68
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.69
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.68 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.69 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -23,6 +23,7 @@ This package bootstraps a local Python runtime on first install and then starts
 Bundled skills:
 
 - `skills/qingflow-app-builder`
+- `skills/qingflow-app-builder-code-integrations`
 
 Note:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.68",
+  "version": "0.2.0-beta.69",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

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,40 @@
+# 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
+
+## 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,74 @@
+# 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
+
+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.