@qingflow-tech/qingflow-cli 1.1.35 → 1.1.38

package/README.md

@@ -1,35 +1,63 @@
 # Qingflow CLI
 
-Install:
+## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.35
+npm install @qingflow-tech/qingflow-cli@1.1.38
 ```
 
-Run:
+推荐从官网复制这一条一键安装 Qingflow CLI：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.35 qingflow
+npx qingflow-cli@latest install
 ```
 
-Environment:
+如果你只想直接安装当前 npm 包，也可以使用上面的 `npm install` 命令。
+
+## 运行
+
+```bash
+npx -y -p @qingflow-tech/qingflow-cli@1.1.38 qingflow
+```
+
+全局安装后可以直接运行：
+
+```bash
+qingflow
+```
+
+## 常用环境变量
 
 - `QINGFLOW_MCP_DEFAULT_BASE_URL`
 - `QINGFLOW_MCP_DEFAULT_QF_VERSION`
 - `QINGFLOW_MCP_HOME`
 
-This package bootstraps a local Python runtime on first install and then starts the `qingflow` command line interface.
+首次安装时会自动初始化本地 Python 运行环境，随后提供 `qingflow` 命令行入口。
 
-Bundled skills:
+## 内置 Skills
 
 - `skills/qingflow-cli`
 - `skills/qingflow-mcp-setup`
 
-Note:
+## Skills 安装
+
+包内已包含上面列出的 skill 文件，但安装 npm 包不会自动覆盖本机 agent skills。需要挂载到本地 agent 时，请显式执行：
+
+```bash
+qingflow-skills list
+qingflow-skills install --agent codex --scope user
+```
+
+如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
+
+```bash
+npx -y -p @qingflow-tech/qingflow-cli@1.1.38 qingflow-skills install --agent codex --scope user --copy
+```
+
+`qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。
+
+## 排障
 
-- The skill files are included in the npm package.
-- Installing the npm package does not overwrite agent skills automatically.
-- To mount bundled skills from an installed package, run `qingflow-skills install --agent codex --scope user`.
-- For one-shot `npx -p` installs, prefer `--copy` because symlinks would point into the npm execution cache.
-- Use `qingflow-skills list` to inspect bundled skills. The installer defaults to symlinks for stable package installs and refuses to overwrite existing skills unless `--force` is provided.
-- If a stdio MCP client reports `Transport closed`, delete `.npm-python`, reinstall the package, and make sure CLI/user/builder packages are on the same version. The stdio entrypoints refuse runtime bootstrap so install logs never corrupt MCP stdout.
+- 如果 npm 全局目录没有权限，推荐使用 `npx qingflow-cli@latest install`，安装器会自动 fallback 到用户目录。
+- 如果本地 MCP 客户端报 `Transport closed`，优先删除安装目录里的 `.npm-python` 后重新安装，并确认 CLI/user/builder 包版本一致。
+- stdio MCP 入口不会在启动瞬间重建 Python 运行时，避免安装日志写入 stdout 破坏 MCP 握手。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.35",
+  "version": "1.1.38",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.35"
+version = "1.1.38"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -31,6 +31,8 @@ dependencies = [
   "pycryptodome>=3.20,<4.0",
   "pypdf>=5.0,<6.0",
   "python-socketio[client]>=5.11,<6.0",
+  "redis>=5.0,<6.0",
+  "uvicorn>=0.30,<1.0",
 ]
 
 [project.optional-dependencies]

package/src/qingflow_mcp/builder_facade/service.py

@@ -10734,7 +10734,12 @@ class AiBuilderFacade:
             failed["suggested_next_call"] = suggested_next_call
             return finish(failed)
         flow_readback_started_at = time.perf_counter()
-        verified_nodes, verified_nodes_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
+        verified_nodes, verified_nodes_unavailable = self._load_workflow_result(
+            profile=profile,
+            app_key=app_key,
+            tolerate_404=True,
+            legacy_fallback=True,
+        )
         flow_readback_ms += _duration_ms(flow_readback_started_at)
         workflow_structure_verified = bool(verified_nodes) and _workflow_nodes_semantically_equal(
             current_workflow=verified_nodes,
@@ -14845,8 +14850,25 @@ class AiBuilderFacade:
         app_key: str,
         tolerate_404: bool,
         tolerate_permission_restricted: bool = False,
+        legacy_fallback: bool = False,
         include_error: bool = False,
     ) -> tuple[Any, bool] | tuple[Any, bool, QingflowApiError | None]:
+        def legacy_result() -> tuple[Any, bool, QingflowApiError | None]:
+            try:
+                legacy_workflow = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key)
+            except (QingflowApiError, RuntimeError) as legacy_error:
+                legacy_api_error = _coerce_api_error(legacy_error)
+                if tolerate_404 and (
+                    legacy_api_error.http_status == 404
+                    or (tolerate_permission_restricted and _is_permission_restricted_api_error(legacy_api_error))
+                ):
+                    return [], True, legacy_api_error
+                raise
+            legacy_payload = legacy_workflow.get("result") if isinstance(legacy_workflow, dict) and "result" in legacy_workflow else legacy_workflow
+            if not legacy_fallback and not _summarize_workflow_nodes(legacy_payload):
+                return [], True, None
+            return legacy_payload, False, None
+
         try:
             workflow = self._with_backend_context(
                 profile,
@@ -14862,9 +14884,21 @@ class AiBuilderFacade:
                 api_error.http_status == 404
                 or (tolerate_permission_restricted and _is_permission_restricted_api_error(api_error))
             ):
-                return ([], True, api_error) if include_error else ([], True)
+                if not legacy_fallback:
+                    return ([], True, api_error) if include_error else ([], True)
+                legacy_workflow, legacy_unavailable, legacy_error = legacy_result()
+                if not legacy_unavailable:
+                    return (legacy_workflow, False, None) if include_error else (legacy_workflow, False)
+                return ([], True, legacy_error or api_error) if include_error else ([], True)
             raise
         result = workflow if _looks_like_workflow_spec_payload(workflow) else []
+        if not result:
+            if not legacy_fallback:
+                return ([], True, None) if include_error else ([], True)
+            legacy_workflow, legacy_unavailable, legacy_error = legacy_result()
+            if not legacy_unavailable:
+                return (legacy_workflow, False, None) if include_error else (legacy_workflow, False)
+            return ([], True, legacy_error) if include_error else ([], True)
         return (result, False, None) if include_error else (result, False)
 
     def _load_app_state(self, *, profile: str, app_key: str) -> dict[str, Any]:

package/src/qingflow_mcp/cloud_auth.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from time import sleep, time
+from typing import Any
+
+from .backend_client import BackendClient, BackendResponse
+from .cloud_context import CloudMcpContext
+from .cloud_redis import CloudAuthCache, RedisCloudAuthCache
+from .config import (
+    get_cloud_auth_context_lock_seconds,
+    get_cloud_auth_context_lock_wait_seconds,
+    get_cloud_auth_context_negative_ttl_seconds,
+    get_cloud_auth_context_ttl_seconds,
+    get_cloud_redis_url,
+    get_default_base_url,
+    get_default_qf_version,
+    normalize_base_url,
+)
+from .errors import QingflowApiError, is_auth_like_error
+from .json_types import JSONObject
+
+
+AUTH_CONTEXT_KEY_PREFIX = "mcp:auth:context"
+AUTH_CONTEXT_LOCK_KEY_PREFIX = "mcp:auth:context:lock"
+AUTH_CONTEXT_NEGATIVE_KEY_PREFIX = "mcp:auth:context:negative"
+
+
+@dataclass(slots=True)
+class CloudAuthBroker:
+    cache: CloudAuthCache
+    backend: BackendClient
+    base_url: str
+    qf_version: str | None = None
+    ttl_seconds: int = 604800
+    lock_seconds: int = 10
+    negative_ttl_seconds: int = 30
+    lock_wait_seconds: float = 5.0
+
+    @classmethod
+    def from_config(cls, backend: BackendClient | None = None) -> "CloudAuthBroker":
+        redis_url = get_cloud_redis_url()
+        if not redis_url:
+            raise QingflowApiError.config_error("cloud.redis_url is required for Cloud MCP mode")
+        base_url = get_default_base_url()
+        if not base_url:
+            raise QingflowApiError.config_error(
+                "default_base_url is required for Cloud MCP mode"
+            )
+        return cls(
+            cache=RedisCloudAuthCache.from_url(redis_url),
+            backend=backend or BackendClient(),
+            base_url=base_url,
+            qf_version=get_default_qf_version(),
+            ttl_seconds=get_cloud_auth_context_ttl_seconds(),
+            lock_seconds=get_cloud_auth_context_lock_seconds(),
+            negative_ttl_seconds=get_cloud_auth_context_negative_ttl_seconds(),
+            lock_wait_seconds=get_cloud_auth_context_lock_wait_seconds(),
+        )
+
+    @classmethod
+    def from_env(cls, backend: BackendClient | None = None) -> "CloudAuthBroker":
+        return cls.from_config(backend=backend)
+
+    def resolve(self, credential: str, *, force_refresh: bool = False) -> CloudMcpContext:
+        normalized_credential = str(credential or "").strip()
+        if not normalized_credential:
+            raise QingflowApiError(category="auth", message="MCP credential is required")
+
+        credential_hash = self.credential_hash(normalized_credential)
+        auth_key = self._auth_key(credential_hash)
+        negative_key = self._negative_key(credential_hash)
+        if force_refresh:
+            self.cache.delete(auth_key)
+
+        cached = None if force_refresh else self.cache.get_json(auth_key)
+        if cached is not None:
+            return self._context_from_cache(credential_hash, normalized_credential, cached)
+        if self.cache.exists(negative_key):
+            raise QingflowApiError(category="auth", message="MCP credential is invalid or expired")
+
+        lock = self.cache.acquire_lock(self._lock_key(credential_hash), self.lock_seconds)
+        if not lock.acquired:
+            return self._wait_for_peer_context(credential_hash, normalized_credential)
+
+        try:
+            cached = None if force_refresh else self.cache.get_json(auth_key)
+            if cached is not None:
+                return self._context_from_cache(credential_hash, normalized_credential, cached)
+            if self.cache.exists(negative_key):
+                raise QingflowApiError(category="auth", message="MCP credential is invalid or expired")
+            payload = self._fetch_auth_context(normalized_credential, credential_hash)
+            self.cache.set_json(auth_key, payload, self.ttl_seconds)
+            return self._context_from_cache(credential_hash, normalized_credential, payload)
+        finally:
+            lock.release()
+
+    def refresh(self, context: CloudMcpContext) -> CloudMcpContext:
+        self.invalidate(context.credential_hash)
+        return self.resolve(context.credential, force_refresh=True)
+
+    def invalidate(self, credential_hash: str) -> None:
+        self.cache.delete(self._auth_key(credential_hash))
+
+    @staticmethod
+    def credential_hash(credential: str) -> str:
+        return sha256(credential.encode("utf-8")).hexdigest()
+
+    def _wait_for_peer_context(self, credential_hash: str, credential: str) -> CloudMcpContext:
+        auth_key = self._auth_key(credential_hash)
+        negative_key = self._negative_key(credential_hash)
+        deadline = time() + self.lock_wait_seconds
+        while time() < deadline:
+            cached = self.cache.get_json(auth_key)
+            if cached is not None:
+                return self._context_from_cache(credential_hash, credential, cached)
+            if self.cache.exists(negative_key):
+                raise QingflowApiError(category="auth", message="MCP credential is invalid or expired")
+            sleep(0.05)
+
+        lock = self.cache.acquire_lock(self._lock_key(credential_hash), self.lock_seconds)
+        if lock.acquired:
+            try:
+                cached = self.cache.get_json(auth_key)
+                if cached is not None:
+                    return self._context_from_cache(credential_hash, credential, cached)
+                payload = self._fetch_auth_context(credential, credential_hash)
+                self.cache.set_json(auth_key, payload, self.ttl_seconds)
+                return self._context_from_cache(credential_hash, credential, payload)
+            finally:
+                lock.release()
+        raise QingflowApiError(category="cache", message="Timed out waiting for MCP auth context cache")
+
+    def _fetch_auth_context(self, credential: str, credential_hash: str) -> JSONObject:
+        try:
+            response = self.backend.public_request_with_meta(
+                "POST",
+                self.base_url,
+                "/mcp/auth/context",
+                json_body={"credential": credential},
+                qf_version=self.qf_version,
+            )
+        except QingflowApiError as error:
+            if is_auth_like_error(error):
+                self.cache.set_json(
+                    self._negative_key(credential_hash),
+                    {"message": error.message, "createdAt": int(time())},
+                    self.negative_ttl_seconds,
+                )
+            raise
+
+        payload = self._unwrap_payload(response)
+        token = self._normalize_text(payload.get("token"))
+        uid = self._coerce_positive_int(payload.get("uid"))
+        ws_id = self._coerce_positive_int(payload.get("wsId") or payload.get("ws_id"))
+        if not token or uid is None or ws_id is None:
+            raise QingflowApiError(category="auth", message="Credential context did not return token, uid, and wsId")
+
+        base_url = normalize_base_url(self._normalize_text(payload.get("baseUrl"))) or self.base_url
+        qf_version = self._normalize_text(payload.get("qfVersion")) or response.qf_response_version or self.qf_version
+        qf_version_source = "backend_response" if qf_version else None
+        return {
+            "credentialId": self._coerce_positive_int(payload.get("credentialId") or payload.get("credential_id") or payload.get("id")),
+            "token": token,
+            "uid": uid,
+            "wsId": ws_id,
+            "baseUrl": base_url,
+            "qfVersion": qf_version,
+            "qfVersionSource": qf_version_source,
+            "email": self._normalize_text(payload.get("email")),
+            "nickName": self._normalize_text(
+                payload.get("nickName") or payload.get("displayName") or payload.get("name")
+            ),
+            "wsName": self._normalize_text(payload.get("wsName") or payload.get("workspaceName")),
+            "createdAt": int(time()),
+        }
+
+    def _context_from_cache(self, credential_hash: str, credential: str, payload: JSONObject) -> CloudMcpContext:
+        token = self._normalize_text(payload.get("token"))
+        uid = self._coerce_positive_int(payload.get("uid"))
+        ws_id = self._coerce_positive_int(payload.get("wsId") or payload.get("ws_id"))
+        base_url = normalize_base_url(self._normalize_text(payload.get("baseUrl"))) or self.base_url
+        if not token or uid is None or ws_id is None:
+            self.cache.delete(self._auth_key(credential_hash))
+            raise QingflowApiError(category="auth", message="Cached MCP auth context is incomplete")
+        context = CloudMcpContext(
+            credential_hash=credential_hash,
+            credential=credential,
+            credential_id=self._coerce_positive_int(
+                payload.get("credentialId") or payload.get("credential_id") or payload.get("id")
+            ),
+            token=token,
+            uid=uid,
+            ws_id=ws_id,
+            base_url=base_url,
+            qf_version=self._normalize_text(payload.get("qfVersion") or payload.get("qf_version")),
+            qf_version_source=self._normalize_text(payload.get("qfVersionSource") or payload.get("qf_version_source")),
+            email=self._normalize_text(payload.get("email")),
+            nick_name=self._normalize_text(payload.get("nickName") or payload.get("nick_name")),
+            ws_name=self._normalize_text(payload.get("wsName") or payload.get("ws_name")),
+        )
+        context.refresh_context = lambda: self.refresh(context)
+        return context
+
+    def _unwrap_payload(self, response: BackendResponse) -> JSONObject:
+        data = response.data
+        if not isinstance(data, dict):
+            raise QingflowApiError(category="auth", message="Credential context did not return a valid result")
+        for key in ("data", "result"):
+            nested = data.get(key)
+            if isinstance(nested, dict):
+                return nested
+        return data
+
+    def _auth_key(self, credential_hash: str) -> str:
+        return f"{AUTH_CONTEXT_KEY_PREFIX}:{credential_hash}"
+
+    def _lock_key(self, credential_hash: str) -> str:
+        return f"{AUTH_CONTEXT_LOCK_KEY_PREFIX}:{credential_hash}"
+
+    def _negative_key(self, credential_hash: str) -> str:
+        return f"{AUTH_CONTEXT_NEGATIVE_KEY_PREFIX}:{credential_hash}"
+
+    def _normalize_text(self, value: Any) -> str | None:
+        if value is None:
+            return None
+        text = str(value).strip()
+        return text or None
+
+    def _coerce_positive_int(self, value: Any) -> int | None:
+        if isinstance(value, bool) or value is None:
+            return None
+        try:
+            parsed = int(value)
+        except (TypeError, ValueError):
+            return None
+        return parsed if parsed > 0 else None

package/src/qingflow_mcp/cloud_context.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Callable
+
+from .backend_client import BackendRequestContext
+from .session_store import BackendSession, SessionProfile
+
+
+CLOUD_PROFILE_NAME = "__cloud_mcp__"
+
+
+@dataclass(slots=True)
+class CloudMcpContext:
+    credential_hash: str
+    credential: str
+    token: str
+    uid: int
+    ws_id: int
+    base_url: str
+    qf_version: str | None = None
+    qf_version_source: str | None = None
+    credential_id: int | None = None
+    email: str | None = None
+    nick_name: str | None = None
+    ws_name: str | None = None
+    refresh_context: Callable[[], "CloudMcpContext"] | None = field(default=None, repr=False, compare=False)
+
+    def as_tool_context(self, profile: str) -> tuple[SessionProfile, BackendSession, BackendRequestContext]:
+        session_profile = SessionProfile(
+            profile=profile or CLOUD_PROFILE_NAME,
+            base_url=self.base_url,
+            qf_version=self.qf_version,
+            qf_version_source=self.qf_version_source,
+            token=self.token,
+            login_token=None,
+            credential=self.credential,
+            uid=self.uid,
+            email=self.email,
+            nick_name=self.nick_name,
+            selected_ws_id=self.ws_id,
+            selected_ws_name=self.ws_name,
+            persisted=False,
+            created_at="cloud-request",
+            updated_at="cloud-request",
+        )
+        backend_session = BackendSession(
+            token=self.token,
+            login_token=None,
+            credential=self.credential,
+            profile=session_profile.profile,
+            base_url=self.base_url,
+            qf_version=self.qf_version,
+            qf_version_source=self.qf_version_source,
+        )
+        request_context = BackendRequestContext(
+            base_url=self.base_url,
+            token=self.token,
+            ws_id=self.ws_id,
+            qf_version=self.qf_version,
+            qf_version_source=self.qf_version_source,
+        )
+        return session_profile, backend_session, request_context
+
+
+current_cloud_context: ContextVar[CloudMcpContext | None] = ContextVar(
+    "qingflow_mcp_current_cloud_context",
+    default=None,
+)

package/src/qingflow_mcp/cloud_redis.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Protocol
+from uuid import uuid4
+
+from .errors import QingflowApiError
+from .json_types import JSONObject
+
+
+class CloudAuthLock(Protocol):
+    acquired: bool
+
+    def release(self) -> None:
+        ...
+
+
+class CloudAuthCache(Protocol):
+    def get_json(self, key: str) -> JSONObject | None:
+        ...
+
+    def set_json(self, key: str, value: JSONObject, ttl_seconds: int) -> None:
+        ...
+
+    def exists(self, key: str) -> bool:
+        ...
+
+    def delete(self, key: str) -> None:
+        ...
+
+    def acquire_lock(self, key: str, ttl_seconds: int) -> CloudAuthLock:
+        ...
+
+
+@dataclass(slots=True)
+class RedisCloudAuthLock:
+    cache: "RedisCloudAuthCache"
+    key: str
+    token: str
+    acquired: bool
+
+    def release(self) -> None:
+        if not self.acquired:
+            return
+        self.cache.release_lock(self.key, self.token)
+
+
+class RedisCloudAuthCache:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    @classmethod
+    def from_url(cls, redis_url: str) -> "RedisCloudAuthCache":
+        try:
+            import redis
+        except ImportError as exc:
+            raise QingflowApiError.config_error(
+                "Cloud MCP mode requires the 'redis' Python package. Install qingflow-mcp with cloud dependencies."
+            ) from exc
+        return cls(redis.Redis.from_url(redis_url, decode_responses=False))
+
+    def get_json(self, key: str) -> JSONObject | None:
+        raw_value = self._client.get(key)
+        if raw_value is None:
+            return None
+        if isinstance(raw_value, bytes):
+            raw_value = raw_value.decode("utf-8")
+        try:
+            value = json.loads(str(raw_value))
+        except json.JSONDecodeError as exc:
+            raise QingflowApiError(category="cache", message=f"invalid Redis JSON for key '{key}': {exc}") from exc
+        return value if isinstance(value, dict) else None
+
+    def set_json(self, key: str, value: JSONObject, ttl_seconds: int) -> None:
+        self._client.set(key, json.dumps(value, ensure_ascii=False), ex=max(1, int(ttl_seconds)))
+
+    def exists(self, key: str) -> bool:
+        return bool(self._client.exists(key))
+
+    def delete(self, key: str) -> None:
+        self._client.delete(key)
+
+    def acquire_lock(self, key: str, ttl_seconds: int) -> RedisCloudAuthLock:
+        token = uuid4().hex
+        acquired = bool(self._client.set(key, token, nx=True, ex=max(1, int(ttl_seconds))))
+        return RedisCloudAuthLock(cache=self, key=key, token=token, acquired=acquired)
+
+    def release_lock(self, key: str, token: str) -> None:
+        script = (
+            "if redis.call('get', KEYS[1]) == ARGV[1] then "
+            "return redis.call('del', KEYS[1]) "
+            "else return 0 end"
+        )
+        self._client.eval(script, 1, key, token)

package/src/qingflow_mcp/config.py

@@ -23,6 +23,13 @@ DEFAULT_REPOSITORY_AUTHOR_EMAIL = "qingflow-mcp@local.invalid"
 DEFAULT_REPOSITORY_INTERNAL_SHARE_TOKEN_KEY = "tokenKey"
 DEFAULT_CREDIT_USAGE_RECORD_PATH = "/user/credit/usage"
 DEFAULT_MCPORTER_CONFIG_PATH = "~/.openclaw/workspace/config/mcporter.json"
+DEFAULT_CLOUD_AUTH_CONTEXT_TTL_SECONDS = 604800
+DEFAULT_CLOUD_AUTH_CONTEXT_LOCK_SECONDS = 10
+DEFAULT_CLOUD_AUTH_CONTEXT_NEGATIVE_TTL_SECONDS = 30
+DEFAULT_CLOUD_AUTH_CONTEXT_LOCK_WAIT_SECONDS = 5.0
+DEFAULT_CLOUD_HTTP_HOST = "0.0.0.0"
+DEFAULT_CLOUD_HTTP_PORT = 8000
+DEFAULT_CLOUD_HTTP_ALLOWED_HOSTS = ("127.0.0.1", "localhost")
 
 
 def get_mcp_home() -> Path:
@@ -234,7 +241,7 @@ def get_credit_usage_base_url() -> str | None:
         default=None,
     )
     normalized = normalize_base_url(value)
-    return normalized or None
+    return normalized or get_default_base_url()
 
 
 def get_credit_usage_path() -> str:
@@ -247,6 +254,99 @@ def get_credit_usage_path() -> str:
     return normalized or DEFAULT_CREDIT_USAGE_RECORD_PATH
 
 
+def get_cloud_redis_url() -> str | None:
+    value = get_config_value(
+        "cloud.redis_url",
+        env_var="QINGFLOW_MCP_REDIS_URL",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_cloud_auth_context_ttl_seconds() -> int:
+    return _get_positive_int_config(
+        "cloud.auth_context_ttl_seconds",
+        "QINGFLOW_MCP_AUTH_CONTEXT_TTL_SECONDS",
+        DEFAULT_CLOUD_AUTH_CONTEXT_TTL_SECONDS,
+    )
+
+
+def get_cloud_auth_context_lock_seconds() -> int:
+    return _get_positive_int_config(
+        "cloud.auth_context_lock_seconds",
+        "QINGFLOW_MCP_AUTH_CONTEXT_LOCK_SECONDS",
+        DEFAULT_CLOUD_AUTH_CONTEXT_LOCK_SECONDS,
+    )
+
+
+def get_cloud_auth_context_negative_ttl_seconds() -> int:
+    return _get_positive_int_config(
+        "cloud.auth_context_negative_ttl_seconds",
+        "QINGFLOW_MCP_AUTH_CONTEXT_NEGATIVE_TTL_SECONDS",
+        DEFAULT_CLOUD_AUTH_CONTEXT_NEGATIVE_TTL_SECONDS,
+    )
+
+
+def get_cloud_auth_context_lock_wait_seconds() -> float:
+    value = get_config_value(
+        "cloud.auth_context_lock_wait_seconds",
+        env_var="QINGFLOW_MCP_AUTH_CONTEXT_LOCK_WAIT_SECONDS",
+        default=DEFAULT_CLOUD_AUTH_CONTEXT_LOCK_WAIT_SECONDS,
+    )
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError):
+        return DEFAULT_CLOUD_AUTH_CONTEXT_LOCK_WAIT_SECONDS
+    return parsed if parsed > 0 else DEFAULT_CLOUD_AUTH_CONTEXT_LOCK_WAIT_SECONDS
+
+
+def get_cloud_http_host() -> str:
+    value = get_config_value(
+        "cloud.http.host",
+        env_var="QINGFLOW_MCP_HTTP_HOST",
+        default=DEFAULT_CLOUD_HTTP_HOST,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_CLOUD_HTTP_HOST
+
+
+def get_cloud_http_port() -> int:
+    value = get_config_value(
+        "cloud.http.port",
+        env_var="QINGFLOW_MCP_HTTP_PORT",
+        default=DEFAULT_CLOUD_HTTP_PORT,
+    )
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return DEFAULT_CLOUD_HTTP_PORT
+    return parsed if 0 < parsed < 65536 else DEFAULT_CLOUD_HTTP_PORT
+
+
+def get_cloud_http_allowed_hosts() -> list[str]:
+    value = get_config_value(
+        "cloud.http.allowed_hosts",
+        env_var="QINGFLOW_MCP_HTTP_ALLOWED_HOSTS",
+        default=",".join(DEFAULT_CLOUD_HTTP_ALLOWED_HOSTS),
+    )
+    if isinstance(value, (list, tuple, set)):
+        raw_hosts = value
+    else:
+        raw_hosts = str(value or "").split(",")
+    hosts = [str(host or "").strip().lower() for host in raw_hosts]
+    return [host for host in hosts if host] or list(DEFAULT_CLOUD_HTTP_ALLOWED_HOSTS)
+
+
+def _get_positive_int_config(key: str, env_var: str, default: int) -> int:
+    value = get_config_value(key, env_var=env_var, default=default)
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return default
+    return parsed if parsed > 0 else default
+
+
 def get_repository_default_group() -> str | None:
     value = get_config_value(
         "repository.default_group",

package/src/qingflow_mcp/server_cloud.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import anyio
+import uvicorn
+
+from .backend_client import BackendClient
+from .cloud_auth import CloudAuthBroker
+from .cloud_context import current_cloud_context
+from .config import get_cloud_http_allowed_hosts, get_cloud_http_host, get_cloud_http_port
+from .errors import QingflowApiError, is_auth_like_error
+from .server_app_user import build_user_server
+
+
+ASGIApp = Callable[
+    [
+        dict[str, Any],
+        Callable[[], Awaitable[dict[str, Any]]],
+        Callable[[dict[str, Any]], Awaitable[None]],
+    ],
+    Awaitable[None],
+]
+
+
+class CloudMcpAuthApp:
+    def __init__(
+        self,
+        app: ASGIApp,
+        broker: CloudAuthBroker,
+        *,
+        allowed_hosts: list[str] | None = None,
+        internal_host: str | None = None,
+    ) -> None:
+        self._app = app
+        self._broker = broker
+        self._allowed_hosts = [
+            host.strip().lower()
+            for host in (allowed_hosts if allowed_hosts is not None else get_cloud_http_allowed_hosts())
+            if host.strip()
+        ]
+        self._internal_host = internal_host or f"127.0.0.1:{get_cloud_http_port()}"
+
+    async def __call__(
+        self,
+        scope: dict[str, Any],
+        receive: Callable[[], Awaitable[dict[str, Any]]],
+        send: Callable[[dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        if scope.get("type") != "http":
+            await self._app(scope, receive, send)
+            return
+
+        host = _extract_host(scope)
+        if not _is_allowed_host(host, self._allowed_hosts):
+            await self._plain_response(send, 421, "Invalid Host header")
+            return
+        scope = _rewrite_host(scope, self._internal_host)
+
+        path = str(scope.get("path") or "")
+        if path in {"/health", "/healthz", "/readyz"}:
+            await self._json_response(send, 200, {"status": "ok"})
+            return
+
+        credential = self._extract_credential(scope)
+        if credential is None:
+            await self._json_response(
+                send,
+                401,
+                {
+                    "error": "missing_mcp_credential",
+                    "message": "Authorization: Bearer <mcp_credential> is required",
+                },
+            )
+            return
+
+        try:
+            cloud_context = await anyio.to_thread.run_sync(self._broker.resolve, credential)
+        except QingflowApiError as error:
+            status = 401 if is_auth_like_error(error) else 500
+            await self._json_response(
+                send,
+                status,
+                {
+                    "error": error.category,
+                    "message": error.message,
+                    "request_id": error.request_id,
+                    "backend_code": error.backend_code,
+                },
+            )
+            return
+
+        token = current_cloud_context.set(cloud_context)
+        try:
+            await self._app(scope, receive, send)
+        finally:
+            current_cloud_context.reset(token)
+
+    def _extract_credential(self, scope: dict[str, Any]) -> str | None:
+        headers = {
+            key.decode("latin1").lower(): value.decode("latin1")
+            for key, value in scope.get("headers", [])
+        }
+        authorization = headers.get("authorization", "")
+        if authorization.lower().startswith("bearer "):
+            credential = authorization[7:].strip()
+            return credential or None
+        credential = headers.get("x-qingflow-client-id", "").strip()
+        return credential or None
+
+    async def _json_response(
+        self,
+        send: Callable[[dict[str, Any]], Awaitable[None]],
+        status: int,
+        payload: dict[str, Any],
+    ) -> None:
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status,
+                "headers": [
+                    (b"content-type", b"application/json; charset=utf-8"),
+                    (b"content-length", str(len(body)).encode("ascii")),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})
+
+    async def _plain_response(
+        self,
+        send: Callable[[dict[str, Any]], Awaitable[None]],
+        status: int,
+        text: str,
+    ) -> None:
+        body = text.encode("utf-8")
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status,
+                "headers": [
+                    (b"content-type", b"text/plain; charset=utf-8"),
+                    (b"content-length", str(len(body)).encode("ascii")),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})
+
+
+class LazyCloudApp:
+    def __init__(self) -> None:
+        self._app: CloudMcpAuthApp | None = None
+
+    async def __call__(
+        self,
+        scope: dict[str, Any],
+        receive: Callable[[], Awaitable[dict[str, Any]]],
+        send: Callable[[dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        if self._app is None:
+            self._app = build_cloud_user_app()
+        await self._app(scope, receive, send)
+
+
+def build_cloud_user_app() -> CloudMcpAuthApp:
+    server = build_user_server()
+    broker = CloudAuthBroker.from_config(backend=BackendClient())
+    return CloudMcpAuthApp(server.streamable_http_app(), broker)
+
+
+def _extract_host(scope: dict[str, Any]) -> str:
+    for key, value in scope.get("headers", []):
+        if key.lower() == b"host":
+            return value.decode("latin1").strip().lower()
+    server = scope.get("server")
+    if isinstance(server, tuple) and len(server) >= 2:
+        return f"{server[0]}:{server[1]}".lower()
+    return ""
+
+
+def _is_allowed_host(host: str, allowed_hosts: list[str]) -> bool:
+    normalized_host = host.strip().lower().rstrip(".")
+    host_without_port = _strip_port(normalized_host)
+    for allowed in allowed_hosts:
+        normalized_allowed = allowed.strip().lower().rstrip(".")
+        if normalized_allowed == "*":
+            return True
+        if normalized_allowed.startswith("*."):
+            suffix = normalized_allowed[1:]
+            if host_without_port.endswith(suffix) and host_without_port != normalized_allowed[2:]:
+                return True
+            continue
+        if normalized_host == normalized_allowed or host_without_port == normalized_allowed:
+            return True
+    return False
+
+
+def _strip_port(host: str) -> str:
+    if host.startswith("["):
+        end = host.find("]")
+        return host[1:end] if end > 0 else host
+    if host.count(":") == 1:
+        return host.split(":", 1)[0]
+    return host
+
+
+def _rewrite_host(scope: dict[str, Any], internal_host: str) -> dict[str, Any]:
+    rewritten = dict(scope)
+    headers = []
+    host_seen = False
+    for key, value in scope.get("headers", []):
+        if key.lower() == b"host":
+            headers.append((key, internal_host.encode("latin1")))
+            host_seen = True
+        else:
+            headers.append((key, value))
+    if not host_seen:
+        headers.append((b"host", internal_host.encode("latin1")))
+    rewritten["headers"] = headers
+    return rewritten
+
+
+app = LazyCloudApp()
+
+
+def main() -> None:
+    uvicorn.run(build_cloud_user_app(), host=get_cloud_http_host(), port=get_cloud_http_port())
+
+
+if __name__ == "__main__":
+    main()

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -3619,7 +3619,7 @@ class AiBuilderTools(ToolBase):
                 normalized_args=normalized_args,
                 suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
             ))
-        if nodes or transitions:
+        if nodes is not None or transitions is not None:
             effective_nodes = nodes or []
             effective_transitions = transitions or []
             result = self._app_flow_apply_once(
@@ -3644,12 +3644,27 @@ class AiBuilderTools(ToolBase):
             )
             return _attach_builder_apply_envelope("app_flow_apply", result)
         normalized_args = {"app_key": app_key, "publish": publish}
-        return _attach_builder_apply_envelope("app_flow_apply", _failed(
-            "FLOW_SPEC_OR_PATCH_REQUIRED",
-            "app_flow_apply requires spec for a complete WorkflowSpec write or patch_nodes for targeted edits.",
-            normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile}},
-        ))
+        return _attach_builder_apply_envelope(
+            "app_flow_apply",
+            {
+                "status": "failed",
+                "error_code": "FLOW_SPEC_OR_PATCH_REQUIRED",
+                "recoverable": True,
+                "message": "app_flow_apply requires spec for a complete WorkflowSpec write or patch_nodes for targeted edits.",
+                "normalized_args": normalized_args,
+                "missing_fields": ["spec"],
+                "allowed_values": {},
+                "details": {},
+                "suggested_next_call": {"tool_name": "app_flow_get_schema", "arguments": {"profile": profile}},
+                "request_id": None,
+                "backend_code": None,
+                "http_status": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {},
+                "verified": False,
+            },
+        )
 
     def _app_flow_apply_once(
         self,

package/src/qingflow_mcp/tools/auth_tools.py

@@ -7,6 +7,7 @@ import os
 from mcp.server.fastmcp import FastMCP
 
 from ..backend_client import BackendRequestContext, BackendResponse
+from ..cloud_context import current_cloud_context
 from ..config import (
     DEFAULT_PROFILE,
     get_default_base_url,
@@ -378,6 +379,7 @@ class AuthTools(ToolBase):
             backend_session,  # type: ignore[no-untyped-def]
             context: BackendRequestContext,
         ) -> dict[str, Any]:
+            cloud_context = current_cloud_context.get()
             workspace, workspace_qf_version = self._selected_workspace_snapshot(
                 session_profile=session_profile,
                 backend_session=backend_session,
@@ -389,7 +391,8 @@ class AuthTools(ToolBase):
                 else session_profile.qf_version_source
             )
             if (
-                workspace_qf_version is not None
+                cloud_context is None
+                and workspace_qf_version is not None
                 and (
                     workspace_qf_version != session_profile.qf_version
                     or session_profile.qf_version_source != "workspace_system_version"
@@ -408,7 +411,7 @@ class AuthTools(ToolBase):
                     qf_version=backend_session.qf_version,
                     qf_version_source=backend_session.qf_version_source,
                 )
-            if self._should_refresh_identity_metadata(session_profile):
+            if cloud_context is None and self._should_refresh_identity_metadata(session_profile):
                 refreshed_profile = self._refresh_identity_metadata(
                     profile=profile,
                     session_profile=session_profile,
@@ -443,13 +446,22 @@ class AuthTools(ToolBase):
         backend_session = None
         try:
             session_profile, backend_session, context = self._require_context(profile, require_workspace=False)
-            if backend_session.credential:
+            if backend_session.credential and current_cloud_context.get() is None:
                 self._probe_token_validity(
                     session_profile=session_profile,
                     backend_session=backend_session,
                 )
             return build_response(session_profile, backend_session, context)
         except QingflowApiError as error:
+            if error.looks_like_invalid_token() and self._refresh_current_cloud_context():
+                try:
+                    refreshed_profile, refreshed_backend_session, refreshed_context = self._require_context(
+                        profile,
+                        require_workspace=False,
+                    )
+                    return build_response(refreshed_profile, refreshed_backend_session, refreshed_context)
+                except QingflowApiError as refreshed_error:
+                    self._handle_error(profile, refreshed_error)
             if (
                 error.looks_like_invalid_token()
                 and session_profile is not None

package/src/qingflow_mcp/tools/base.py

@@ -5,6 +5,7 @@ from contextvars import ContextVar
 from typing import Any, Callable, TypeVar
 
 from ..backend_client import BackendRequestContext, BackendClient
+from ..cloud_context import current_cloud_context
 from ..config import (
     get_credit_meter_enabled,
     get_credit_usage_base_url,
@@ -36,6 +37,10 @@ class ToolBase:
         self.backend = backend
 
     def _require_context(self, profile: str, *, require_workspace: bool) -> tuple[SessionProfile, BackendSession, BackendRequestContext]:
+        cloud_context = current_cloud_context.get()
+        if cloud_context is not None:
+            return cloud_context.as_tool_context(profile)
+
         session_profile = self.sessions.get_profile(profile)
         if session_profile is None:
             raise QingflowApiError.auth_required(profile)
@@ -75,6 +80,12 @@ class ToolBase:
                 )
             return func(session_profile, context)
         except QingflowApiError as error:
+            if error.looks_like_invalid_token() and self._refresh_current_cloud_context():
+                try:
+                    refreshed_profile, _, refreshed_context = self._require_context(profile, require_workspace=require_workspace)
+                    return func(refreshed_profile, refreshed_context)
+                except QingflowApiError as refreshed_error:
+                    self._handle_error(profile, refreshed_error)
             if (
                 error.looks_like_invalid_token()
                 and session_profile is not None
@@ -97,6 +108,16 @@ class ToolBase:
 
     def _handle_error(self, profile: str, error: QingflowApiError) -> None:
         if error.looks_like_invalid_token():
+            cloud_context = current_cloud_context.get()
+            if cloud_context is not None:
+                refreshed_error = QingflowApiError(
+                    category="auth",
+                    message="Cloud MCP auth context expired and refresh failed. Retry with a valid MCP credential.",
+                    backend_code=error.backend_code,
+                    request_id=error.request_id,
+                    http_status=error.http_status,
+                )
+                raise_tool_error(refreshed_error)
             self.sessions.invalidate(profile)
             error = QingflowApiError(
                 category="auth",
@@ -107,6 +128,17 @@ class ToolBase:
             )
         raise_tool_error(error)
 
+    def _refresh_current_cloud_context(self) -> bool:
+        cloud_context = current_cloud_context.get()
+        if cloud_context is None or cloud_context.refresh_context is None:
+            return False
+        try:
+            refreshed_context = cloud_context.refresh_context()
+        except QingflowApiError:
+            return False
+        current_cloud_context.set(refreshed_context)
+        return True
+
     def _refresh_session_from_credential(
         self,
         profile: str,

package/src/qingflow_mcp/tools/workspace_tools.py

@@ -5,6 +5,7 @@ from typing import Any
 from mcp.server.fastmcp import FastMCP
 
 from ..backend_client import BackendRequestContext
+from ..cloud_context import current_cloud_context
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
 from .base import ToolBase, tool_cn_name
@@ -171,9 +172,35 @@ class WorkspaceTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("ws_id must be positive"))
 
         def runner(_, context):
+            cloud_context = current_cloud_context.get()
+            if cloud_context is not None and ws_id != cloud_context.ws_id:
+                raise_tool_error(
+                    QingflowApiError.config_error(
+                        "Cloud MCP workspace is bound to the configured MCP credential. Use a credential for the target workspace."
+                    )
+                )
             workspace = self._fetch_workspace_with_fallback(context, ws_id=ws_id)
             workspace, warnings = _strip_workspace_detail_warning(workspace)
             workspace_name = str(workspace.get("workspaceName") or workspace.get("wsName") or workspace.get("remark") or "").strip() or None
+            if cloud_context is not None:
+                system_version = self._workspace_system_version(workspace)
+                qf_version_source = "workspace_system_version" if system_version else "unverified"
+                return {
+                    "profile": profile,
+                    "ws_id": ws_id,
+                    "qf_version": system_version or cloud_context.qf_version,
+                    "qf_version_source": qf_version_source if system_version else cloud_context.qf_version_source,
+                    "workspace": workspace,
+                    "selected": {
+                        "ws_id": cloud_context.ws_id,
+                        "workspace_name": workspace_name or cloud_context.ws_name,
+                    },
+                    "warnings": warnings,
+                    "verification": {
+                        "workspace_detail_verified": not warnings,
+                        "workspace_list_fallback_used": bool(warnings),
+                    },
+                }
             selected = self.sessions.select_workspace(profile, ws_id=ws_id, ws_name=workspace_name)
             system_version = self._workspace_system_version(workspace)
             qf_version_source = "workspace_system_version" if system_version else "unverified"