@josephyan/qingflow-app-builder-mcp 0.2.0-beta.39 → 0.2.0-beta.40

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.39
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.40
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.39 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.40 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.39",
+  "version": "0.2.0-beta.40",
   "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.0b39"
+version = "0.2.0b40"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -48,8 +48,8 @@ Default modeling rules:
 
 - Authentication and workspace: `auth_*`, `workspace_*`
 - File upload: `file_upload_local`
-- Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `member_search`, `role_search`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`
-- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `chart_apply`, `portal_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`, `role_create`
+- Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `member_search`, `role_search`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`, `app_read_charts_summary`, `portal_read_summary`
+- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `app_charts_apply`, `portal_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`, `role_create`
 - Publish and verify: `app_publish_verify`
 
 Note:
@@ -57,8 +57,10 @@ Note:
 - Do not rely on low-level `view_*`, `workflow_*`, `qingbi_report_*`, or `portal_*` write payloads from public builder flows.
 - Public builder work should stay on the resource path: `resolve -> summary read -> apply -> attach -> publish_verify`.
 - `app_schema_apply` / `app_layout_apply` / `app_flow_apply` / `app_views_apply` publish by default; pass `publish=false` only when you intentionally want to leave changes in draft.
-- `chart_apply` is immediate-live and does not publish.
-- `portal_apply` uses replace semantics for sections; remove a section by omitting it from the next full sections list.
+- `app_charts_apply` is immediate-live and does not publish; it resolves targets by `chart_id` first and then exact unique chart name.
+- `portal_apply` uses replace semantics for sections; remove a section by omitting it from the next full sections list. `publish=false` only guarantees draft/base-info updates, and `chart_ref/view_ref` resolve by `id/key` first and exact unique name second.
+- `app_read_charts_summary` is the compact discovery path for current chart inventory; use it before `app_charts_apply` when you need exact `chart_id` values.
+- `portal_read_summary` is the compact discovery path for portal draft/live summaries; it returns section summaries, not the raw dash payload.
 - `app_schema_apply` / `app_layout_apply` / `app_flow_apply` / `app_views_apply` now perform planning, normalization, and dependency checks internally; when prechecks block, read the returned blocking issues and `suggested_next_call` directly from the apply result.
 - If you are unsure about a public builder tool's keys, aliases, presets, or minimal legal shape, call `builder_tool_contract` instead of guessing.
 - For views, always write the canonical key `columns`. Do not emit `column_names`; treat `fields` only as a tolerated legacy alias, not the preferred shape.
@@ -94,7 +96,7 @@ For builder work:
    - one app: continue with `app_resolve`
    - multi-app package/system: create or resolve the package, then create each app separately before adding relations
 3. Resolve the target app with `app_resolve` if the request is an update.
-4. Read only the smallest summary you need: `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`.
+4. Read only the smallest summary you need: `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`, `app_read_charts_summary`, `portal_read_summary`.
 5. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands; noop schema requests do not publish.
 6. If the app must belong to a package, use `package_attach_app` explicitly after schema work unless readback already shows the target `tag_id`.
 7. Use `app_layout_apply` only when the user is explicitly changing layout. Prefer the default `mode=merge`; use `mode=replace` only when you intend to place every field explicitly. It publishes by default after the patch lands; noop layout requests do not publish.
@@ -130,8 +132,10 @@ For flow work, keep the order strict:
 10. When a node must edit specific fields, declare `permissions.editable_fields`
 11. `app_flow_apply`
 12. `app_read_flow_summary` after apply whenever the user asked for verification or apply returns `partial_success`
-13. Use `chart_apply` for QingBI chart creation and updates, not raw `qingbi_report_*` writes
-14. Use `portal_apply` for builder-side portal work; treat sections as a full replacement list
+13. Use `app_read_charts_summary` before chart work whenever exact current `chart_id` values matter
+14. Use `app_charts_apply` for QingBI chart creation and updates, not raw `qingbi_report_*` writes
+15. Use `portal_read_summary` before portal work whenever exact current draft/live section inventory matters
+16. Use `portal_apply` for builder-side portal work; treat sections as a full replacement list
 
 For additive work on existing systems:
 
@@ -174,6 +178,9 @@ For additive work on existing systems:
 
 - low-level list totals from the backend may report `0` while rows are present; prefer summary or aggregate readbacks for final conclusions
 - `app_publish_verify` is the publish source of truth.
+- All public builder tools expose top-level `warnings`, `verification`, and `verified`. Read them before deciding whether a run is fully done.
+- For read tools, `status=success` can still pair with `verified=false` when some optional readback is unavailable; in that case prefer `warnings` and `verification` over the bare status code.
+- For `app_charts_apply`, `portal_apply`, and `app_publish_verify`, treat `success` as “write and verification completed” and `partial_success` as “write executed but verification is incomplete”.
 - If readback mismatches the UI, compare `request_route` and do not assume the builder hit the same `qf_version` as the browser
 - Treat post-write readback as the source of truth, not just write status codes
 - For views, a top-level `VIEW_APPLY_FAILED` does not prove all requested views failed. Read back the view list and verify which views actually landed.
@@ -200,6 +207,8 @@ For additive work on existing systems:
 - Read layout summary: `app_read_layout_summary`
 - Read views summary: `app_read_views_summary`
 - Read flow summary: `app_read_flow_summary`
+- Read chart summary: `app_read_charts_summary`
+- Read portal summary: `portal_read_summary`
 - Search members for workflow assignees: `member_search`
 - Search roles for workflow assignees: `role_search`
 - Create reusable workflow role: `role_create`
@@ -207,7 +216,7 @@ For additive work on existing systems:
 - Merge or replace layout: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
 - Upsert/remove views: `app_views_apply`
-- Upsert/remove/reorder QingBI charts: `chart_apply`
+- Upsert/remove/reorder QingBI charts: `app_charts_apply`
 - Create or replace-update portal pages: `portal_apply`
 - Attach one app to a package: `package_attach_app`
 - Release your own stale edit lock: `app_release_edit_lock_if_mine`

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -36,6 +36,8 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 - `app_read_layout_summary`: sections, rows, unplaced fields
 - `app_read_views_summary`: current view names, types, columns, group-by
 - `app_read_flow_summary`: workflow enabled state, nodes, transitions
+- `app_read_charts_summary`: current chart ids, names, types, order
+- `portal_read_summary`: current draft/live portal metadata and compact section inventory
 
 ## Apply tools
 
@@ -45,8 +47,8 @@ These execute normalized patches and publish by default unless `publish=false`.
 - `app_layout_apply`: merge or replace layout
 - `app_flow_apply`: replace workflow
 - `app_views_apply`: upsert or remove views
-- `chart_apply`: upsert/remove/reorder QingBI charts; charts are immediate-live and do not publish
-- `portal_apply`: create or replace-update portal pages; sections are replace-only and omission deletes old sections
+- `app_charts_apply`: upsert/remove/reorder QingBI charts; charts are immediate-live and do not publish; use `chart_id` when names are not unique
+- `portal_apply`: create or replace-update portal pages; sections are replace-only and omission deletes old sections; `publish=false` only guarantees draft/base-info updates
 
 ## Explicit post-apply tools
 
@@ -70,9 +72,9 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Add views:
   `builder_tool_contract -> app_read_fields -> app_read_views_summary -> app_views_apply -> app_read_views_summary`
 - Add QingBI charts:
-  `builder_tool_contract -> app_read_fields -> chart_apply`
+  `builder_tool_contract -> app_read_fields -> app_read_charts_summary -> app_charts_apply -> app_read_charts_summary`
 - Create or update a portal:
-  `builder_tool_contract -> portal_apply`
+  `builder_tool_contract -> portal_read_summary -> portal_apply -> portal_read_summary`
 
 ## Avoid
 

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/builder_facade/models.py

@@ -794,6 +794,25 @@ class AppFlowReadResponse(StrictModel):
     transitions: list[dict[str, Any]] = Field(default_factory=list)
 
 
+class AppChartsReadResponse(StrictModel):
+    app_key: str
+    charts: list[dict[str, Any]] = Field(default_factory=list)
+    chart_count: int = 0
+
+
+class PortalReadSummaryResponse(StrictModel):
+    dash_key: str
+    being_draft: bool = True
+    dash_name: str | None = None
+    package_tag_ids: list[int] = Field(default_factory=list)
+    dash_icon: str | None = None
+    hide_copyright: bool | None = None
+    config_keys: list[str] = Field(default_factory=list)
+    dash_global_config_keys: list[str] = Field(default_factory=list)
+    section_count: int = 0
+    sections: list[dict[str, Any]] = Field(default_factory=list)
+
+
 class SchemaPlanRequest(StrictModel):
     app_key: str = ""
     package_tag_id: int | None = None