@josephyan/qingflow-cli 0.2.0-beta.1000

package/src/qingflow_mcp/server_app_user.py

@@ -0,0 +1,386 @@
+from __future__ import annotations
+
+import json
+from datetime import date
+
+from mcp.server.fastmcp import FastMCP
+
+from .backend_client import BackendClient
+from .config import DEFAULT_PROFILE
+from .response_trim import USER_SERVER_METHOD_MAP, trim_error_response, trim_public_response, wrap_trimmed_methods
+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.directory_tools import DirectoryTools
+from .tools.feedback_tools import FeedbackTools
+from .tools.file_tools import FileTools
+from .tools.import_tools import ImportTools
+from .tools.resource_read_tools import ResourceReadTools
+from .tools.task_context_tools import TaskContextTools
+from .tools.workspace_tools import WorkspaceTools
+
+
+def build_user_server() -> FastMCP:
+    today = date.today()
+    current_year = today.year
+    server = FastMCP(
+        "Qingflow App User MCP",
+        instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
+
+## 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.
+
+## 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.
+
+## 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`.
+Inside `optional_fields`, any field with `may_become_required=true` is still writable, but may become required when linked visibility or option-driven runtime rules activate.
+`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`
+`portal_list -> portal_get -> chart_get / view_get`
+`portal_get -> view_get -> record_list`
+
+- 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.
+- When candidate browsing must match a real update/write scope, pass `record_id`, `workflow_node_id`, and any pending `fields` context to the candidate tool; otherwise the candidate result is only a static applicant-node preview.
+- 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`
+
+- `task_list` returns task-card summaries keyed by `task_id`.
+- Prefer `task_get(task_id=...)` for detail reads; MCP resolves the current todo locator internally.
+- `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
+- `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
+- 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`.
+- Treat `task_action_execute` as the tool-level action enum surface; the current task's real actions are only the ones listed in `task_get.capabilities.available_actions`.
+- Use `task_action_execute(action="save_only", fields=...)` when the user wants to save editable field changes on the current node without advancing the workflow.
+- `save_only` is exposed only when the backend current-node `editableQueIds` signal returns a non-empty result; MCP no longer infers `save_only` from local schema reconstruction.
+
+## 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()
+    auth = wrap_trimmed_methods(AuthTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    apps = wrap_trimmed_methods(AppTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    workspace = wrap_trimmed_methods(WorkspaceTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    file_tools = wrap_trimmed_methods(FileTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    imports = wrap_trimmed_methods(ImportTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    resources = wrap_trimmed_methods(ResourceReadTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    feedback = FeedbackTools(backend, mcp_side="App User MCP")
+    code_block_tools = wrap_trimmed_methods(CodeBlockTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    task_context_tools = wrap_trimmed_methods(TaskContextTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    directory_tools = wrap_trimmed_methods(DirectoryTools(sessions, backend), USER_SERVER_METHOD_MAP)
+
+    @server.tool()
+    def auth_use_credential(
+        profile: str = DEFAULT_PROFILE,
+        base_url: str | None = None,
+        qf_version: str | None = None,
+        credential: str = "",
+        persist: bool = False,
+    ) -> dict:
+        return auth.auth_use_credential(
+            profile=profile,
+            base_url=base_url,
+            qf_version=qf_version,
+            credential=credential,
+            persist=persist,
+        )
+
+    @server.tool()
+    def auth_whoami(profile: str = DEFAULT_PROFILE) -> dict:
+        return auth.auth_whoami(profile=profile)
+
+    @server.tool()
+    def auth_logout(profile: str = DEFAULT_PROFILE, forget_persisted: bool = False) -> dict:
+        return auth.auth_logout(profile=profile, forget_persisted=forget_persisted)
+
+    @server.tool()
+    def workspace_list(
+        profile: str = DEFAULT_PROFILE,
+        page_num: int = 1,
+        page_size: int = 20,
+        include_external: bool = False,
+    ) -> dict:
+        return workspace.workspace_list(
+            profile=profile,
+            page_num=page_num,
+            page_size=page_size,
+            include_external=include_external,
+        )
+
+    @server.tool()
+    def workspace_get(
+        profile: str = DEFAULT_PROFILE,
+        ws_id: int | None = None,
+    ) -> dict:
+        return workspace.workspace_get(
+            profile=profile,
+            ws_id=ws_id,
+        )
+
+    @server.tool()
+    def workspace_select(
+        profile: str = DEFAULT_PROFILE,
+        ws_id: int = 0,
+    ) -> dict:
+        return workspace.workspace_select(
+            profile=profile,
+            ws_id=ws_id,
+        )
+
+    @server.tool()
+    def app_list(profile: str = DEFAULT_PROFILE) -> dict:
+        return apps.app_list(profile=profile)
+
+    @server.tool()
+    def app_search(profile: str = DEFAULT_PROFILE, keyword: str = "", page_num: int = 1, page_size: int = 50) -> dict:
+        return apps.app_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+
+    @server.tool()
+    def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
+        return apps.app_get(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def portal_list(profile: str = DEFAULT_PROFILE) -> dict:
+        return resources.portal_list(profile=profile)
+
+    @server.tool()
+    def portal_get(profile: str = DEFAULT_PROFILE, dash_key: str = "") -> dict:
+        return resources.portal_get(profile=profile, dash_key=dash_key)
+
+    @server.tool()
+    def view_get(profile: str = DEFAULT_PROFILE, view_id: str = "") -> dict:
+        return resources.view_get(profile=profile, view_id=view_id)
+
+    @server.tool()
+    def chart_get(profile: str = DEFAULT_PROFILE, chart_id: str = "") -> dict:
+        return resources.chart_get(profile=profile, chart_id=chart_id)
+
+    @server.tool()
+    def file_get_upload_info(
+        profile: str = DEFAULT_PROFILE,
+        upload_kind: str = "attachment",
+        file_name: str = "",
+        file_size: int = 0,
+        upload_mark: str | None = None,
+        content_type: str | None = None,
+        bucket_type: str | None = None,
+        path_id: int | None = None,
+        file_related_url: str | None = None,
+    ) -> dict:
+        return file_tools.file_get_upload_info(
+            profile=profile,
+            upload_kind=upload_kind,
+            file_name=file_name,
+            file_size=file_size,
+            upload_mark=upload_mark,
+            content_type=content_type,
+            bucket_type=bucket_type,
+            path_id=path_id,
+            file_related_url=file_related_url,
+        )
+
+    @server.tool()
+    def file_upload_local(
+        profile: str = DEFAULT_PROFILE,
+        upload_kind: str = "attachment",
+        file_path: str = "",
+        upload_mark: str | None = None,
+        content_type: str | None = None,
+        bucket_type: str | None = None,
+        path_id: int | None = None,
+        file_related_url: str | None = None,
+    ) -> dict:
+        return file_tools.file_upload_local(
+            profile=profile,
+            upload_kind=upload_kind,
+            file_path=file_path,
+            upload_mark=upload_mark,
+            content_type=content_type,
+            bucket_type=bucket_type,
+            path_id=path_id,
+            file_related_url=file_related_url,
+        )
+
+    imports.register(server)
+
+    @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(
+                "user: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
+
+    code_block_tools.register(server)
+    task_context_tools.register(server)
+    directory_tools.register(server)
+
+    return server
+
+
+mcp = build_user_server()
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()