@josephyan/qingflow-cli 0.2.0-beta.55

package/src/qingflow_mcp/server_app_user.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+from datetime import date
+
+from mcp.server.fastmcp import FastMCP
+
+from .backend_client import BackendClient
+from .config import DEFAULT_PROFILE
+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.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`
+
+- 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.
+- In workflow context, pass `role=3` and the exact `workflow_node_id`.
+- After execution, inspect `outputs.alias_results`, `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()
+    auth = AuthTools(sessions, backend)
+    apps = AppTools(sessions, backend)
+    workspace = WorkspaceTools(sessions, backend)
+    files = FileTools(sessions, backend)
+    imports = ImportTools(sessions, backend)
+    feedback = FeedbackTools(backend, mcp_side="App User MCP")
+
+    @server.tool()
+    def auth_login(
+        profile: str = DEFAULT_PROFILE,
+        base_url: str | None = None,
+        qf_version: str | None = None,
+        email: str = "",
+        password: str = "",
+        persist: bool = True,
+    ) -> dict:
+        return auth.auth_login(
+            profile=profile,
+            base_url=base_url,
+            qf_version=qf_version,
+            email=email,
+            password=password,
+            persist=persist,
+        )
+
+    @server.tool()
+    def auth_use_token(
+        profile: str = DEFAULT_PROFILE,
+        base_url: str | None = None,
+        qf_version: str | None = None,
+        token: str = "",
+        ws_id: int | None = None,
+        persist: bool = False,
+    ) -> dict:
+        return auth.auth_use_token(
+            profile=profile,
+            base_url=base_url,
+            qf_version=qf_version,
+            token=token,
+            ws_id=ws_id,
+            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_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 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 files.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 files.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)
+
+    feedback.register(server)
+    CodeBlockTools(sessions, backend).register(server)
+    TaskContextTools(sessions, backend).register(server)
+    DirectoryTools(sessions, backend).register(server)
+
+    return server
+
+
+mcp = build_user_server()
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

package/src/qingflow_mcp/session_store.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    import keyring
+except ImportError:
+    keyring = None
+
+from .config import get_profiles_path, normalize_base_url
+from .json_types import JSONObject, KeyringBackend
+
+
+KEYRING_SERVICE_NAME = "qingflow-mcp"
+_UNSET = object()
+
+
+def _utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass(slots=True)
+class SessionProfile:
+    profile: str
+    base_url: str
+    qf_version: str | None
+    qf_version_source: str | None
+    uid: int
+    email: str | None
+    nick_name: str | None
+    selected_ws_id: int | None
+    selected_ws_name: str | None
+    persisted: bool
+    created_at: str
+    updated_at: str
+
+    @classmethod
+    def from_dict(cls, value: JSONObject) -> "SessionProfile":
+        return cls(
+            profile=value["profile"],
+            base_url=value["base_url"],
+            qf_version=value.get("qf_version"),
+            qf_version_source=value.get("qf_version_source"),
+            uid=value["uid"],
+            email=value.get("email"),
+            nick_name=value.get("nick_name"),
+            selected_ws_id=value.get("selected_ws_id"),
+            selected_ws_name=value.get("selected_ws_name"),
+            persisted=bool(value.get("persisted", False)),
+            created_at=value.get("created_at", _utcnow()),
+            updated_at=value.get("updated_at", _utcnow()),
+        )
+
+
+@dataclass(slots=True)
+class BackendSession:
+    token: str
+    login_token: str | None
+    profile: str
+    base_url: str
+    qf_version: str | None
+    qf_version_source: str | None = None
+
+
+class SessionStore:
+    def __init__(self, base_dir: Path | None = None, keyring_backend: KeyringBackend | None = None) -> None:
+        profiles_path = get_profiles_path() if base_dir is None else Path(base_dir) / "profiles.json"
+        self._profiles_path = profiles_path
+        self._profiles_path.parent.mkdir(parents=True, exist_ok=True)
+        self._keyring = keyring_backend if keyring_backend is not None else keyring
+        self._memory_sessions: dict[str, BackendSession] = {}
+        self._logged_out_profiles: set[str] = set()
+
+    def save_session(
+        self,
+        *,
+        profile: str,
+        base_url: str,
+        qf_version: str | None,
+        qf_version_source: str | None = None,
+        token: str,
+        login_token: str | None,
+        uid: int,
+        email: str | None,
+        nick_name: str | None,
+        persist: bool,
+    ) -> SessionProfile:
+        now = _utcnow()
+        previous = self.get_profile(profile)
+        persisted = False
+        if persist:
+            persisted = self._set_secret(self._token_key(profile), token)
+            if login_token:
+                self._set_secret(self._login_token_key(profile), login_token)
+            else:
+                self._delete_secret(self._login_token_key(profile))
+        else:
+            self._delete_secret(self._token_key(profile))
+            self._delete_secret(self._login_token_key(profile))
+        session_profile = SessionProfile(
+            profile=profile,
+            base_url=normalize_base_url(base_url) or base_url,
+            qf_version=(str(qf_version).strip() or None) if qf_version is not None else None,
+            qf_version_source=(str(qf_version_source).strip() or None) if qf_version_source is not None else None,
+            uid=uid,
+            email=email,
+            nick_name=nick_name,
+            selected_ws_id=None,
+            selected_ws_name=None,
+            persisted=persisted,
+            created_at=previous.created_at if previous else now,
+            updated_at=now,
+        )
+        self._memory_sessions[profile] = BackendSession(
+            token=token,
+            login_token=login_token,
+            profile=profile,
+            base_url=session_profile.base_url,
+            qf_version=session_profile.qf_version,
+            qf_version_source=session_profile.qf_version_source,
+        )
+        self._logged_out_profiles.discard(profile)
+        self._upsert_profile(session_profile)
+        return session_profile
+
+    def get_profile(self, profile: str) -> SessionProfile | None:
+        payload = self._load_profiles()
+        raw_profile = payload.get("profiles", {}).get(profile)
+        if not raw_profile:
+            return None
+        return SessionProfile.from_dict(raw_profile)
+
+    def get_backend_session(self, profile: str) -> BackendSession | None:
+        if profile in self._logged_out_profiles:
+            return None
+        memory_session = self._memory_sessions.get(profile)
+        session_profile = self.get_profile(profile)
+        if memory_session:
+            if session_profile is not None:
+                memory_session.base_url = session_profile.base_url
+                memory_session.qf_version = session_profile.qf_version
+                memory_session.qf_version_source = session_profile.qf_version_source
+            return memory_session
+        if not session_profile or not session_profile.persisted:
+            return None
+        token = self._get_secret(self._token_key(profile))
+        if not token:
+            return None
+        backend_session = BackendSession(
+            token=token,
+            login_token=self._get_secret(self._login_token_key(profile)),
+            profile=profile,
+            base_url=session_profile.base_url,
+            qf_version=session_profile.qf_version,
+            qf_version_source=session_profile.qf_version_source,
+        )
+        self._memory_sessions[profile] = backend_session
+        return backend_session
+
+    def select_workspace(self, profile: str, ws_id: int, ws_name: str | None) -> SessionProfile:
+        session_profile = self.get_profile(profile)
+        if session_profile is None:
+            raise KeyError(profile)
+        session_profile.selected_ws_id = ws_id
+        session_profile.selected_ws_name = ws_name
+        session_profile.updated_at = _utcnow()
+        self._upsert_profile(session_profile)
+        return session_profile
+
+    def update_route(self, profile: str, *, qf_version: str | None, qf_version_source: str | None) -> SessionProfile:
+        session_profile = self.get_profile(profile)
+        if session_profile is None:
+            raise KeyError(profile)
+        session_profile.qf_version = (str(qf_version).strip() or None) if qf_version is not None else None
+        session_profile.qf_version_source = (str(qf_version_source).strip() or None) if qf_version_source is not None else None
+        session_profile.updated_at = _utcnow()
+        self._upsert_profile(session_profile)
+        backend_session = self._memory_sessions.get(profile)
+        if backend_session is not None:
+            backend_session.qf_version = session_profile.qf_version
+            backend_session.qf_version_source = session_profile.qf_version_source
+        return session_profile
+
+    def update_profile_metadata(
+        self,
+        profile: str,
+        *,
+        uid: int | object = _UNSET,
+        email: str | None | object = _UNSET,
+        nick_name: str | None | object = _UNSET,
+        selected_ws_id: int | None | object = _UNSET,
+        selected_ws_name: str | None | object = _UNSET,
+    ) -> SessionProfile:
+        session_profile = self.get_profile(profile)
+        if session_profile is None:
+            raise KeyError(profile)
+        if uid is not _UNSET:
+            session_profile.uid = int(uid)
+        if email is not _UNSET:
+            session_profile.email = email if isinstance(email, str) or email is None else session_profile.email
+        if nick_name is not _UNSET:
+            session_profile.nick_name = nick_name if isinstance(nick_name, str) or nick_name is None else session_profile.nick_name
+        if selected_ws_id is not _UNSET:
+            session_profile.selected_ws_id = (
+                int(selected_ws_id)
+                if isinstance(selected_ws_id, int) and not isinstance(selected_ws_id, bool)
+                else None
+            )
+        if selected_ws_name is not _UNSET:
+            session_profile.selected_ws_name = (
+                selected_ws_name
+                if isinstance(selected_ws_name, str) or selected_ws_name is None
+                else session_profile.selected_ws_name
+            )
+        session_profile.updated_at = _utcnow()
+        self._upsert_profile(session_profile)
+        return session_profile
+
+    def logout(self, profile: str, forget_persisted: bool = False) -> None:
+        self._memory_sessions.pop(profile, None)
+        if forget_persisted:
+            self.invalidate(profile)
+            return
+        if self.get_profile(profile):
+            self._logged_out_profiles.add(profile)
+
+    def invalidate(self, profile: str) -> None:
+        self._memory_sessions.pop(profile, None)
+        self._logged_out_profiles.discard(profile)
+        self._delete_secret(self._token_key(profile))
+        self._delete_secret(self._login_token_key(profile))
+        payload = self._load_profiles()
+        profiles = payload.get("profiles", {})
+        if profile in profiles:
+            profiles.pop(profile)
+            self._save_profiles(payload)
+
+    def has_profile(self, profile: str) -> bool:
+        return self.get_profile(profile) is not None
+
+    def _token_key(self, profile: str) -> str:
+        return f"{profile}:token"
+
+    def _login_token_key(self, profile: str) -> str:
+        return f"{profile}:login-token"
+
+    def _upsert_profile(self, profile: SessionProfile) -> None:
+        payload = self._load_profiles()
+        payload.setdefault("profiles", {})[profile.profile] = asdict(profile)
+        self._save_profiles(payload)
+
+    def _load_profiles(self) -> JSONObject:
+        if not self._profiles_path.exists():
+            return {"profiles": {}}
+        with self._profiles_path.open("r", encoding="utf-8") as handle:
+            return json.load(handle)
+
+    def _save_profiles(self, payload: JSONObject) -> None:
+        self._profiles_path.parent.mkdir(parents=True, exist_ok=True)
+        with self._profiles_path.open("w", encoding="utf-8") as handle:
+            json.dump(payload, handle, ensure_ascii=False, indent=2)
+
+    def _set_secret(self, key: str, value: str) -> bool:
+        if self._keyring is None:
+            return False
+        try:
+            self._keyring.set_password(KEYRING_SERVICE_NAME, key, value)
+            return True
+        except Exception:
+            return False
+
+    def _get_secret(self, key: str) -> str | None:
+        if self._keyring is None:
+            return None
+        try:
+            return self._keyring.get_password(KEYRING_SERVICE_NAME, key)
+        except Exception:
+            return None
+
+    def _delete_secret(self, key: str) -> None:
+        if self._keyring is None:
+            return
+        try:
+            self._keyring.delete_password(KEYRING_SERVICE_NAME, key)
+        except Exception:
+            return

package/src/qingflow_mcp/solution/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .normalizer import normalize_solution_spec
+from .spec_models import SolutionSpec
+
+__all__ = ["SolutionSpec", "normalize_solution_spec"]