@josephyan/qingflow-app-builder-mcp 0.2.0-beta.7 → 0.2.0-beta.71

package/src/qingflow_mcp/server.py

@@ -1,61 +1,203 @@
 from __future__ import annotations
 
+from datetime import date
+
 from mcp.server.fastmcp import FastMCP
 
 from .backend_client import BackendClient
 from .session_store import SessionStore
 from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
+from .tools.code_block_tools import CodeBlockTools
+from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
+from .tools.import_tools import ImportTools
 from .tools.package_tools import PackageTools
 from .tools.navigation_tools import NavigationTools
-from .tools.approval_tools import ApprovalTools
 from .tools.directory_tools import DirectoryTools
 from .tools.portal_tools import PortalTools
 from .tools.qingbi_report_tools import QingbiReportTools
-from .tools.record_tools import RecordTools
 from .tools.role_tools import RoleTools
 from .tools.solution_tools import SolutionTools
-from .tools.task_tools import TaskTools
+from .tools.task_context_tools import TaskContextTools
 from .tools.view_tools import ViewTools
 from .tools.workflow_tools import WorkflowTools
 from .tools.workspace_tools import WorkspaceTools
 
 
 def build_server() -> FastMCP:
+    today = date.today()
+    current_year = today.year
     server = FastMCP(
         "Qingflow MCP",
-        instructions=(
-            "Use auth_login first, then workspace_list and workspace_select. "
-            "All resource tools operate with the logged-in user's Qingflow permissions.\n\n"
-            "Task Center (待办/已办) handling:\n"
-            "- Use task_statistics to get counts of pending tasks (todo_count), timeouts, urged, etc.\n"
-            "- Use task_list to query tasks. Type values: 1=todo (待办), 2=initiated (我发起的), 3=cc (抄送), 5=done (已办).\n"
-            "- Use task_list_grouped to get tasks grouped by form/worksheet.\n"
-            "- Use task_mark_read to mark a specific task as read.\n"
-            "- Use task_urge to send an urgent reminder for a pending task.\n"
-            "- Process status values: 1=all, 2=processing, 3=passed, 4=refused, 5=need_supply, 6=urged, 7=timeout, 8=pre_timeout, 9=unread.\n"
-            "- After identifying the exact task node and record, use record_approve, record_reject, record_rollback, record_transfer, record_reassign, or record_countersign as needed."
-        ),
+        instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
+
+## Authentication
+
+Use `auth_login` first, then `workspace_list` and `workspace_select`.
+All resource tools operate with the logged-in user's Qingflow permissions.
+
+## Shared Helper
+
+`feedback_submit` is always available as a cross-cutting helper.
+
+- Use it when the current MCP capability is unsupported, awkward, or still cannot satisfy the user's need after reasonable use.
+- It does not require Qingflow login or workspace selection.
+- Call it only after the user explicitly confirms submission.
+
+## App Discovery
+
+If `app_key` is unknown, use `app_list` or `app_search` first.
+If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
+If an accessible view has `analysis_supported=false`, do not use it for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
+
+## Schema-First Rule
+
+Call `record_insert_schema_get` before `record_insert`.
+Call `record_update_schema_get` before `record_update`.
+Call `record_code_block_schema_get` before `record_code_block_run`.
+Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_list`, `record_get`, or `record_analyze`.
+Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
+
+- All `field_id` values must come from the schema response.
+- Never guess field names or ids.
+
+## Schema Scope
+
+`record_insert_schema_get` returns the current user's insert-ready applicant schema; read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`.
+`record_update_schema_get` returns the current record's overall update-ready writable field set across matched accessible views; read `writable_fields` and `payload_template`.
+`record_browse_schema_get(view_id=...)` returns browse-schema fields for the selected accessible view.
+`record_code_block_schema_get` returns code-block-ready schema for exact code block field selection.
+`record_import_schema_get` returns import-ready column metadata.
+
+- Hidden fields are omitted.
+- Missing fields mean the field is not visible in the current permission scope.
+- Read the top-level schema payload directly; do not guess missing writable fields.
+
+## Analytics Path
+
+`app_get -> record_browse_schema_get(view_id=...) -> record_analyze`
+
+Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
+
+Use this DSL shape:
+
+- `dimensions`: `{{field_id, alias, bucket}}`
+- `metrics`: `{{op, field_id, alias}}`
+- `filters`: `{{field_id, op, value}}`
+- `sort`: `{{by, order}}`
+
+Important key rules:
+
+- Use `op`
+- Do **not** use `type`
+- Do **not** use `agg`
+- Do **not** use `aggregation`
+- Do **not** use `operator`
+
+Analysis answers must include concrete numbers. When applicable, include percentages based on the returned totals.
+
+## Record CRUD Path
+
+`app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get`
+`record_insert_schema_get -> record_insert`
+`record_update_schema_get -> record_update`
+`record_list / record_get -> record_delete`
+`record_code_block_schema_get -> record_code_block_run`
+
+- Use `columns` as `[{{field_id}}]`
+- Use `where` items as `{{field_id, op, value}}`
+- Use `order_by` items as `{{field_id, direction}}`
+- Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
+
+- `record_insert` uses an applicant-node `fields` map keyed by field title.
+- `record_update` uses a field-title keyed `fields` map and internally selects the first accessible view that can execute the current payload.
+- For insert, `runtime_linked_required_fields` means required-but-not-directly-writable fields that are usually supplied by runtime linkage or upstream context.
+- For insert, fields marked `may_become_required=true` stay in `optional_fields`; they are still directly writable, but linked visibility or option-driven rules can make them required at runtime.
+- Read field-level `linkage` whenever present on `record_insert_schema_get` or `record_update_schema_get`; it is the static hint for linked visibility, reference-driven auto fill, and formula/default auto-fill behavior.
+- `linkage.sources` lists upstream field titles that influence the current field; `linkage.affects_fields` lists downstream fields that may change when the current field changes.
+- `linkage.kind=logic_visibility` means linked visibility or option-driven rules are involved; `linkage.kind=reference_fill` means reference/default matching logic is involved; `linkage.kind=formula_fill` means formula/default auto-fill logic is involved.
+- `record_update_schema_get` exposes the overall writable field set for the record, but not every field combination is guaranteed; `record_update` still needs one single matched accessible view that can cover the payload.
+- `record_delete` deletes by `record_id` or `record_ids`.
+- When readback shape matters after insert or update, prefer `record_get(..., output_profile="normalized")` or `record_list(..., output_profile="normalized")`.
+
+- Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
+- Member and department fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to `record_member_candidates` or `record_department_candidates` when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- If explicit candidate browsing is needed for default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
+
+## Code Block Path
+
+Use `record_code_block_run` when the user wants to execute a form code-block field against an existing record.
+
+- Always resolve the exact code-block field from `record_code_block_schema_get` first.
+- Treat code-block execution as write-capable, not read-only.
+- If the code block is bound to relation outputs, Qingflow may calculate target answers and write them back automatically.
+- For safe debugging, pass `apply_writeback=false` and inspect the parsed alias results plus `relation.calculated_answers_preview` before allowing any writeback.
+- In workflow context, pass `role=3` and the exact `workflow_node_id`.
+- After execution, inspect `outputs.configured_aliases`, `outputs.alias_results`, `outputs.alias_map`, `relation.target_fields`, and `writeback.verification` before claiming success.
+
+## Import Path
+
+`app_get -> record_import_schema_get -> record_import_template_get -> record_import_verify -> (optional authorized record_import_repair_local) -> record_import_start -> record_import_status_get`
+
+- Check `app_get.data.import_capability` before doing import work.
+- If `import_capability.can_import=false`, stop before template download, file repair, or import start.
+- Import must go through `verify -> start`; do not start directly from a raw file path.
+- `record_import_start` requires an explicit `being_enter_auditing` choice. Do not assume a default.
+- Do not modify user-uploaded files unless the user explicitly authorizes repair.
+- If repair is authorized, keep the original file and repair a copy, then run `record_import_verify` again before `record_import_start`.
+
+## Task Workflow Path
+
+`task_list -> task_get -> task_action_execute`
+
+- Use `task_associated_report_detail_get` for associated view or report details.
+- Use `task_workflow_log_get` for full workflow log history.
+- Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
+
+## Time Handling
+
+Normalize relative dates before building DSL.
+
+- If the user says `3月` without a year, use the current year: `{current_year}`
+- Convert month-only phrases into explicit legal date ranges
+- Never send impossible dates such as `2026-02-29`
+
+## Environment
+
+Default to `prod` unless the user explicitly specifies `test`.
+
+## Constraints
+
+Avoid builder-side app or schema changes here.
+
+## Feedback Path
+
+If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, offer to submit product feedback.
+
+- First summarize what is still not working
+- Ask the user whether to submit feedback
+- Call `feedback_submit` only after explicit user confirmation""",
     )
     sessions = SessionStore()
     backend = BackendClient()
     AuthTools(sessions, backend).register(server)
+    FeedbackTools(backend, mcp_side="通用").register(server)
     WorkspaceTools(sessions, backend).register(server)
     FileTools(sessions, backend).register(server)
-    RecordTools(sessions, backend).register(server)
+    ImportTools(sessions, backend).register(server)
+    CodeBlockTools(sessions, backend).register(server)
+    TaskContextTools(sessions, backend).register(server)
     RoleTools(sessions, backend).register(server)
     AppTools(sessions, backend).register(server)
     QingbiReportTools(sessions, backend).register(server)
     PackageTools(sessions, backend).register(server)
     NavigationTools(sessions, backend).register(server)
-    ApprovalTools(sessions, backend).register(server)
     PortalTools(sessions, backend).register(server)
     DirectoryTools(sessions, backend).register(server)
     WorkflowTools(sessions, backend).register(server)
     ViewTools(sessions, backend).register(server)
     SolutionTools(sessions, backend).register(server)
-    TaskTools(sessions, backend).register(server)
     return server
 
 

package/src/qingflow_mcp/server_app_builder.py

@@ -1,37 +1,57 @@
 from __future__ import annotations
 
+import json
+
 from mcp.server.fastmcp import FastMCP
 
 from .backend_client import BackendClient
 from .config import DEFAULT_PROFILE
+from .response_trim import BUILDER_SERVER_METHOD_MAP, trim_error_response, trim_public_response, wrap_trimmed_methods
 from .session_store import SessionStore
 from .tools.ai_builder_tools import AiBuilderTools
 from .tools.auth_tools import AuthTools
+from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.workspace_tools import WorkspaceTools
 
 
+def _config_failure(message: str, *, fix_hint: str) -> dict:
+    return {
+        "status": "failed",
+        "error_code": "CONFIG_ERROR",
+        "recoverable": True,
+        "message": message,
+        "details": {"fix_hint": fix_hint},
+        "verification": {},
+    }
+
+
 def build_builder_server() -> FastMCP:
     server = FastMCP(
         "Qingflow App Builder MCP",
         instructions=(
             "Use this server for AI-native Qingflow builder workflows. "
-            "Follow the resource path resolve -> summary read -> plan -> apply -> attach -> publish_verify. "
-            "Use package_resolve/package_list and app_resolve to locate resources, "
-            "app_read_summary/app_read_fields/app_read_layout_summary/app_read_views_summary/app_read_flow_summary for compact reads, "
-            "app_schema_plan/app_layout_plan/app_flow_plan/app_views_plan before writes when the target patch is non-trivial, "
-            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply to execute normalized patches; these apply tools publish by default unless publish=false. "
+            "`feedback_submit` is always available as a cross-cutting helper when the current capability is unsupported, awkward, or still cannot satisfy the user's need after reasonable use; it does not require Qingflow login or workspace selection, and it should be called only after explicit user confirmation. "
+            "Follow the resource path resolve -> summary read -> apply -> attach -> publish_verify. "
+            "Use builder_tool_contract when you need a machine-readable contract, aliases, allowed enums, or a minimal valid example for a public builder tool. "
+            "If creating a new package may be appropriate, ask the user to confirm package creation before calling package_create; otherwise use package_resolve/package_list and app_resolve to locate resources, "
+            "app_read_summary/app_read_fields/app_read_layout_summary/app_read_views_summary/app_read_flow_summary/app_read_charts_summary/portal_list/portal_get/portal_read_summary/view_get/chart_get for reads, "
+            "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
+            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates are replace-only and publish=false only guarantees draft/base-info updates, and flow should use publish=false whenever you only want draft/precheck behavior. "
             "Use package_attach_app to attach apps to packages, and app_publish_verify for explicit final publish verification. "
+            "For workflow edits, keep the public builder surface on stable linear flows only: start/approve/fill/copy/webhook/end. Branch and condition nodes are intentionally disabled because the backend workflow route is not front-end stable for those node types. Declare node assignees and editable fields explicitly. "
             "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
-            "Do not handcraft internal solution payloads or rely on build_id/stage/repair."
+            "Do not handcraft internal solution payloads or rely on build_id/stage/repair. "
+            "If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, first summarize the gap, ask whether to submit feedback, and call feedback_submit only after explicit user confirmation."
         ),
     )
     sessions = SessionStore()
     backend = BackendClient()
-    auth = AuthTools(sessions, backend)
-    workspace = WorkspaceTools(sessions, backend)
-    files = FileTools(sessions, backend)
-    ai_builder = AiBuilderTools(sessions, backend)
+    auth = wrap_trimmed_methods(AuthTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
+    workspace = wrap_trimmed_methods(WorkspaceTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
+    files = wrap_trimmed_methods(FileTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
+    ai_builder = wrap_trimmed_methods(AiBuilderTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
+    feedback = FeedbackTools(backend, mcp_side="App Builder MCP")
 
     @server.tool()
     def auth_login(
@@ -117,6 +137,46 @@ def build_builder_server() -> FastMCP:
             file_related_url=file_related_url,
         )
 
+    @server.tool()
+    def feedback_submit(
+        category: str = "",
+        title: str = "",
+        description: str = "",
+        expected_behavior: str | None = None,
+        actual_behavior: str | None = None,
+        impact_scope: str | None = None,
+        tool_name: str | None = None,
+        app_key: str | None = None,
+        record_id: str | int | None = None,
+        workflow_node_id: str | int | None = None,
+        note: str | None = None,
+    ) -> dict:
+        try:
+            return trim_public_response(
+                "feedback_submit",
+                feedback.feedback_submit(
+                    category=category,
+                    title=title,
+                    description=description,
+                    expected_behavior=expected_behavior,
+                    actual_behavior=actual_behavior,
+                    impact_scope=impact_scope,
+                    tool_name=tool_name,
+                    app_key=app_key,
+                    record_id=record_id,
+                    workflow_node_id=workflow_node_id,
+                    note=note,
+                ),
+            )
+        except RuntimeError as exc:
+            try:
+                payload = json.loads(str(exc))
+            except json.JSONDecodeError:
+                raise
+            if isinstance(payload, dict):
+                raise RuntimeError(json.dumps(trim_error_response(payload), ensure_ascii=False)) from None
+            raise
+
     @server.tool()
     def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all") -> dict:
         return ai_builder.package_list(profile=profile, trial_status=trial_status)
@@ -125,14 +185,69 @@ def build_builder_server() -> FastMCP:
     def package_resolve(profile: str = DEFAULT_PROFILE, package_name: str = "") -> dict:
         return ai_builder.package_resolve(profile=profile, package_name=package_name)
 
+    @server.tool()
+    def builder_tool_contract(tool_name: str = "") -> dict:
+        return ai_builder.builder_tool_contract(tool_name=tool_name)
+
+    @server.tool()
+    def package_create(
+        profile: str = DEFAULT_PROFILE,
+        package_name: str = "",
+        icon: str | None = None,
+        color: str | None = None,
+    ) -> dict:
+        return ai_builder.package_create(profile=profile, package_name=package_name, icon=icon, color=color)
+
+    @server.tool()
+    def member_search(
+        profile: str = DEFAULT_PROFILE,
+        query: str = "",
+        page_num: int = 1,
+        page_size: int = 20,
+        contain_disable: bool = False,
+    ) -> dict:
+        return ai_builder.member_search(
+            profile=profile,
+            query=query,
+            page_num=page_num,
+            page_size=page_size,
+            contain_disable=contain_disable,
+        )
+
+    @server.tool()
+    def role_search(
+        profile: str = DEFAULT_PROFILE,
+        keyword: str = "",
+        page_num: int = 1,
+        page_size: int = 20,
+    ) -> dict:
+        return ai_builder.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+
+    @server.tool()
+    def role_create(
+        profile: str = DEFAULT_PROFILE,
+        role_name: str = "",
+        member_uids: list[int] | None = None,
+        member_emails: list[str] | None = None,
+        member_names: list[str] | None = None,
+        role_icon: str = "ex-user-outlined",
+    ) -> dict:
+        return ai_builder.role_create(
+            profile=profile,
+            role_name=role_name,
+            member_uids=member_uids or [],
+            member_emails=member_emails or [],
+            member_names=member_names or [],
+            role_icon=role_icon,
+        )
+
     @server.tool()
     def package_attach_app(
         profile: str = DEFAULT_PROFILE,
         tag_id: int = 0,
         app_key: str = "",
-        app_title: str = "",
     ) -> dict:
-        return ai_builder.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title)
+        return ai_builder.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key)
 
     @server.tool()
     def app_release_edit_lock_if_mine(
@@ -155,8 +270,46 @@ def build_builder_server() -> FastMCP:
         app_name: str = "",
         package_tag_id: int | None = None,
     ) -> dict:
+        has_app_key = bool((app_key or "").strip())
+        has_app_name = bool((app_name or "").strip())
+        has_package_tag_id = package_tag_id is not None
+        if has_app_key and (has_app_name or has_package_tag_id):
+            return _config_failure(
+                "app_resolve accepts exactly one selector mode.",
+                fix_hint="Use only `app_key`, or use `app_name` together with `package_tag_id`.",
+            )
+        if not has_app_key and not (has_app_name and has_package_tag_id):
+            return _config_failure(
+                "app_resolve requires either app_key, or app_name together with package_tag_id.",
+                fix_hint="For an existing known app, pass `app_key`. For package-scoped lookup, pass both `app_name` and `package_tag_id`.",
+            )
         return ai_builder.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_tag_id)
 
+    @server.tool()
+    def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_custom_button_list(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def app_custom_button_get(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
+        return ai_builder.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id)
+
+    @server.tool()
+    def app_custom_button_create(profile: str = DEFAULT_PROFILE, app_key: str = "", payload: dict | None = None) -> dict:
+        return ai_builder.app_custom_button_create(profile=profile, app_key=app_key, payload=payload or {})
+
+    @server.tool()
+    def app_custom_button_update(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        button_id: int = 0,
+        payload: dict | None = None,
+    ) -> dict:
+        return ai_builder.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=payload or {})
+
+    @server.tool()
+    def app_custom_button_delete(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
+        return ai_builder.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+
     @server.tool()
     def app_read_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
         return ai_builder.app_read_summary(profile=profile, app_key=app_key)
@@ -178,75 +331,51 @@ def build_builder_server() -> FastMCP:
         return ai_builder.app_read_flow_summary(profile=profile, app_key=app_key)
 
     @server.tool()
-    def app_schema_plan(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        package_tag_id: int | None = None,
-        app_name: str = "",
-        create_if_missing: bool = False,
-        add_fields: list[dict] | None = None,
-        update_fields: list[dict] | None = None,
-        remove_fields: list[dict] | None = None,
-    ) -> dict:
-        return ai_builder.app_schema_plan(
-            profile=profile,
-            app_key=app_key,
-            package_tag_id=package_tag_id,
-            app_name=app_name,
-            create_if_missing=create_if_missing,
-            add_fields=add_fields or [],
-            update_fields=update_fields or [],
-            remove_fields=remove_fields or [],
-        )
+    def app_read_charts_summary(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return ai_builder.app_read_charts_summary(profile=profile, app_key=app_key)
 
     @server.tool()
-    def app_layout_plan(
+    def portal_list(profile: str = DEFAULT_PROFILE) -> dict:
+        return ai_builder.portal_list(profile=profile)
+
+    @server.tool()
+    def portal_get(
         profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        mode: str = "merge",
-        sections: list[dict] | None = None,
-        preset: str | None = None,
+        dash_key: str = "",
+        being_draft: bool = True,
     ) -> dict:
-        return ai_builder.app_layout_plan(
-            profile=profile,
-            app_key=app_key,
-            mode=mode,
-            sections=sections or [],
-            preset=preset,
-        )
+        return ai_builder.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
 
     @server.tool()
-    def app_flow_plan(
+    def portal_read_summary(
         profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        mode: str = "replace",
-        nodes: list[dict] | None = None,
-        transitions: list[dict] | None = None,
-        preset: str | None = None,
+        dash_key: str = "",
+        being_draft: bool = True,
     ) -> dict:
-        return ai_builder.app_flow_plan(
-            profile=profile,
-            app_key=app_key,
-            mode=mode,
-            nodes=nodes or [],
-            transitions=transitions or [],
-            preset=preset,
-        )
+        return ai_builder.portal_read_summary(profile=profile, dash_key=dash_key, being_draft=being_draft)
+
+    @server.tool()
+    def view_get(profile: str = DEFAULT_PROFILE, viewgraph_key: str = "") -> dict:
+        return ai_builder.view_get(profile=profile, viewgraph_key=viewgraph_key)
 
     @server.tool()
-    def app_views_plan(
+    def chart_get(
         profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        upsert_views: list[dict] | None = None,
-        remove_views: list[str] | None = None,
-        preset: str | None = None,
+        chart_id: str = "",
+        data_payload: dict | None = None,
+        page_num: int | None = None,
+        page_size: int | None = None,
+        page_num_y: int | None = None,
+        page_size_y: int | None = None,
     ) -> dict:
-        return ai_builder.app_views_plan(
+        return ai_builder.chart_get(
             profile=profile,
-            app_key=app_key,
-            upsert_views=upsert_views or [],
-            remove_views=remove_views or [],
-            preset=preset,
+            chart_id=chart_id,
+            data_payload=data_payload or {},
+            page_num=page_num,
+            page_size=page_size,
+            page_num_y=page_num_y,
+            page_size_y=page_size_y,
         )
 
     @server.tool()
@@ -256,18 +385,37 @@ def build_builder_server() -> FastMCP:
         package_tag_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
+        icon: str = "",
+        color: str = "",
         create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[dict] | None = None,
         update_fields: list[dict] | None = None,
         remove_fields: list[dict] | None = None,
     ) -> dict:
+        has_app_key = bool((app_key or "").strip())
+        has_app_name = bool((app_name or "").strip())
+        has_app_title = bool((app_title or "").strip())
+        has_package_tag_id = package_tag_id is not None
+        if has_app_key:
+            if create_if_missing or has_app_name or has_package_tag_id or has_app_title:
+                return _config_failure(
+                    "app_schema_apply edit mode only accepts app_key as the resource selector.",
+                    fix_hint="For existing apps, pass `app_key` only. For create mode, use `package_tag_id + app_name + create_if_missing=true`.",
+                )
+        elif not (create_if_missing and has_package_tag_id and has_app_name):
+            return _config_failure(
+                "app_schema_apply create mode requires package_tag_id, app_name, and create_if_missing=true.",
+                fix_hint="Use `app_key` for existing apps, or pass `package_tag_id + app_name + create_if_missing=true` to create a new app.",
+            )
         return ai_builder.app_schema_apply(
             profile=profile,
             app_key=app_key,
             package_tag_id=package_tag_id,
             app_name=app_name,
             app_title=app_title,
+            icon=icon,
+            color=color,
             create_if_missing=create_if_missing,
             publish=publish,
             add_fields=add_fields or [],
@@ -319,6 +467,65 @@ def build_builder_server() -> FastMCP:
             remove_views=remove_views or [],
         )
 
+    @server.tool()
+    def app_charts_apply(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        upsert_charts: list[dict] | None = None,
+        remove_chart_ids: list[str] | None = None,
+        reorder_chart_ids: list[str] | None = None,
+    ) -> dict:
+        return ai_builder.app_charts_apply(
+            profile=profile,
+            app_key=app_key,
+            upsert_charts=upsert_charts or [],
+            remove_chart_ids=remove_chart_ids or [],
+            reorder_chart_ids=reorder_chart_ids or [],
+        )
+
+    @server.tool()
+    def portal_apply(
+        profile: str = DEFAULT_PROFILE,
+        dash_key: str = "",
+        dash_name: str = "",
+        package_tag_id: int | None = None,
+        publish: bool = True,
+        sections: list[dict] | None = None,
+        auth: dict | None = None,
+        icon: str | None = None,
+        color: str | None = None,
+        hide_copyright: bool | None = None,
+        dash_global_config: dict | None = None,
+        config: dict | None = None,
+    ) -> dict:
+        has_dash_key = bool((dash_key or "").strip())
+        has_dash_name = bool((dash_name or "").strip())
+        has_package_tag_id = package_tag_id is not None
+        if has_dash_key and has_package_tag_id:
+            return _config_failure(
+                "portal_apply accepts exactly one selector mode.",
+                fix_hint="Use `dash_key` to update an existing portal, or use `package_tag_id + dash_name` to create a new portal.",
+            )
+        if not has_dash_key and not (has_package_tag_id and has_dash_name):
+            return _config_failure(
+                "portal_apply requires either dash_key, or package_tag_id together with dash_name.",
+                fix_hint="Use `dash_key` for an existing portal. For create mode, pass `package_tag_id + dash_name`.",
+            )
+        return ai_builder.portal_apply(
+            profile=profile,
+            dash_key=dash_key,
+            dash_name=dash_name,
+            package_tag_id=package_tag_id,
+            publish=publish,
+            sections=sections or [],
+            auth=auth,
+            icon=icon,
+            color=color,
+            hide_copyright=hide_copyright,
+            dash_global_config=dash_global_config,
+            config=config or {},
+        )
+
     @server.tool()
     def app_publish_verify(
         profile: str = DEFAULT_PROFILE,