@josephyan/qingflow-app-user-mcp 0.2.0-beta.989 → 0.2.0-beta.990

package/README.md

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

package/docs/local-agent-install.md

@@ -20,6 +20,13 @@
 
 `auth_use_credential` 是本地唯一鉴权主路径。
 
+补充说明：
+
+- 对 stdio MCP 来说，主路径仍然只有 `auth_use_credential`。
+- 如果你是在终端里直接使用 `qingflow` CLI，可以额外使用 `qingflow auth login` 作为“人类登录”入口；默认会提示轻流邮箱和隐藏密码，拿到 `token` 后建立本地 CLI 会话。
+- 如果需要浏览器 Authorization Code + PKCE 或 Device Flow，请显式使用 `qingflow auth login --browser` 或 `qingflow auth login --device`；这条 OAuth 路径最终拿到 `credential` 后再复用 `auth_use_credential` 建会话。
+- 也就是说，这次新增的是 CLI 的登录入口，不是给 MCP 增加第二套会话模型。
+
 ## npm 安装器适用场景
 
 适合这类本地 agent / gateway：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.989",
+  "version": "0.2.0-beta.990",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b989"
+version = "0.2.0b990"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b989"
+_FALLBACK_VERSION = "0.2.0b990"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/cli/commands/auth.py

@@ -1,8 +1,13 @@
 from __future__ import annotations
 
 import argparse
+import getpass
+import sys
 
+from ...errors import QingflowApiError
 from ..context import CliContext
+from ..oauth_login import login_with_cli_oauth
+from ..qingflow_login import login_with_qingflow_password
 from .common import read_secret_arg
 
 
@@ -10,6 +15,23 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     parser = subparsers.add_parser("auth", help="认证与会话")
     auth_subparsers = parser.add_subparsers(dest="auth_command", required=True)
 
+    login = auth_subparsers.add_parser("login", help="登录 CLI：默认轻流账号密码交互；--browser 使用 OAuth")
+    login.add_argument("--base-url")
+    login.add_argument("--qf-version")
+    login.add_argument("--client-id")
+    login.add_argument("--authorization-endpoint")
+    login.add_argument("--token-endpoint")
+    login.add_argument("--device-authorization-endpoint")
+    login.add_argument("--scope")
+    login.add_argument("--credential-field")
+    login.add_argument("--browser", action="store_true", help="使用浏览器 OAuth 登录；无浏览器时可配合 --device")
+    login.add_argument("--device", action="store_true", help="使用 OAuth Device Flow（隐含 --browser）")
+    login.add_argument("--email", help="轻流账号邮箱；不传时在交互终端提示输入")
+    login.add_argument("--password", help="轻流账号密码；建议仅用于本地调试，脚本请优先使用 --password-stdin")
+    login.add_argument("--password-stdin", action="store_true", help="从标准输入读取轻流账号密码")
+    login.add_argument("--persist", action=argparse.BooleanOptionalAction, default=True)
+    login.set_defaults(handler=_handle_login, format_hint="auth_whoami")
+
     use_credential = auth_subparsers.add_parser("use-credential", help="直接注入 credential")
     use_credential.add_argument("--base-url")
     use_credential.add_argument("--qf-version")
@@ -26,6 +48,112 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     logout.set_defaults(handler=_handle_logout, format_hint="")
 
 
+def _handle_login(args: argparse.Namespace, context: CliContext) -> dict:
+    login_summary: dict[str, str | None]
+    if _should_use_browser_login(args):
+        if _has_account_login_inputs(args):
+            raise QingflowApiError.config_error(
+                "Choose either account/password login or --browser OAuth login; do not combine both."
+            )
+        oauth_result = login_with_cli_oauth(
+            base_url=args.base_url,
+            client_id=args.client_id,
+            authorization_endpoint=args.authorization_endpoint,
+            token_endpoint=args.token_endpoint,
+            device_authorization_endpoint=args.device_authorization_endpoint,
+            scope=args.scope,
+            credential_field=args.credential_field,
+            force_device=bool(args.device),
+        )
+        result = context.auth.auth_use_credential(
+            profile=args.profile,
+            base_url=args.base_url,
+            qf_version=args.qf_version,
+            credential=oauth_result.credential,
+            persist=bool(args.persist),
+        )
+        login_summary = {
+            "flow": oauth_result.flow,
+            "authorize_url": oauth_result.authorize_url,
+            "verification_uri": oauth_result.verification_uri,
+            "user_code": oauth_result.user_code,
+        }
+    else:
+        email = _resolve_login_email(args)
+        password = _resolve_login_password(args)
+        login_result = login_with_qingflow_password(
+            base_url=args.base_url,
+            email=email,
+            password=password,
+        )
+        result = context.auth.auth_use_token(
+            profile=args.profile,
+            base_url=args.base_url,
+            qf_version=args.qf_version,
+            token=login_result.token,
+            login_token=login_result.login_token,
+            user_info=login_result.user_info,
+            persist=bool(args.persist),
+        )
+        login_summary = {
+            "flow": login_result.flow,
+            "authorize_url": None,
+            "verification_uri": None,
+            "user_code": None,
+        }
+    warnings = list(result.get("warnings") or []) if isinstance(result, dict) else []
+    if isinstance(result, dict):
+        result["cli_auth"] = {key: value for key, value in login_summary.items() if value}
+        if warnings:
+            result["warnings"] = warnings
+    return result
+
+
+def _should_use_browser_login(args: argparse.Namespace) -> bool:
+    return any(
+        bool(getattr(args, name, None))
+        for name in (
+            "browser",
+            "device",
+            "client_id",
+            "authorization_endpoint",
+            "token_endpoint",
+            "device_authorization_endpoint",
+            "scope",
+            "credential_field",
+        )
+    )
+
+
+def _has_account_login_inputs(args: argparse.Namespace) -> bool:
+    return bool(args.email or args.password or bool(args.password_stdin))
+
+
+def _resolve_login_email(args: argparse.Namespace) -> str:
+    email = str(args.email or "").strip()
+    if email:
+        return email
+    if sys.stdin.isatty():
+        return input("Qingflow email: ").strip()
+    raise QingflowApiError.config_error(
+        "qingflow auth login needs an interactive terminal, or pass --email with --password-stdin, or use --browser."
+    )
+
+
+def _resolve_login_password(args: argparse.Namespace) -> str:
+    if args.password or bool(args.password_stdin):
+        return read_secret_arg(
+            args.password,
+            stdin_enabled=bool(args.password_stdin),
+            label="password",
+        )
+    if sys.stdin.isatty():
+        return getpass.getpass("Qingflow password: ")
+    raise QingflowApiError.config_error(
+        "qingflow auth login needs an interactive terminal, --password-stdin, or --browser."
+    )
+
+
 def _handle_use_credential(args: argparse.Namespace, context: CliContext) -> dict:
     credential = (
         read_secret_arg(args.credential, stdin_enabled=bool(args.credential_stdin), label="credential")

package/src/qingflow_mcp/cli/formatters.py

@@ -40,6 +40,13 @@ def _format_whoami(result: dict[str, Any]) -> str:
         f"Workspace: {result.get('selected_ws_name') or '-'} ({result.get('selected_ws_id') or '-'})",
         f"Workspace QF Version: {result.get('qf_version') or '-'}",
     ]
+    cli_auth = result.get("cli_auth") if isinstance(result.get("cli_auth"), dict) else {}
+    if cli_auth:
+        lines.append(f"Login Flow: {cli_auth.get('flow') or '-'}")
+        if cli_auth.get("verification_uri"):
+            lines.append(f"Verification URL: {cli_auth.get('verification_uri')}")
+        if cli_auth.get("user_code"):
+            lines.append(f"User Code: {cli_auth.get('user_code')}")
     request_route = result.get("request_route") if isinstance(result.get("request_route"), dict) else {}
     route_qf_version = request_route.get("qf_version")
     if route_qf_version and route_qf_version != result.get("qf_version"):

package/src/qingflow_mcp/cli/oauth_login.py

@@ -0,0 +1,626 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import sys
+import threading
+import time
+import webbrowser
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urljoin, urlparse
+from uuid import uuid4
+
+import httpx
+
+from ..config import get_config_value, get_timeout_seconds
+from ..errors import QingflowApiError
+
+
+_DEFAULT_SCOPE = "openid profile email"
+_DEFAULT_CALLBACK_HOST = "127.0.0.1"
+_DEFAULT_CALLBACK_PATH = "/callback"
+_DEFAULT_BROWSER_TIMEOUT_SECONDS = 180.0
+_DEFAULT_DEVICE_INTERVAL_SECONDS = 5.0
+_SUCCESS_HTML = """<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Qingflow CLI Login Complete</title>
+</head>
+<body>
+  <p>Qingflow CLI login complete. You can return to the terminal.</p>
+</body>
+</html>
+"""
+
+
+@dataclass(slots=True)
+class CliOAuthConfig:
+    client_id: str
+    authorization_endpoint: str
+    token_endpoint: str
+    device_authorization_endpoint: str | None
+    scope: str
+    callback_host: str
+    callback_port: int
+    callback_path: str
+    browser_timeout_seconds: float
+    credential_field: str
+
+
+@dataclass(slots=True)
+class CliOAuthCredential:
+    credential: str
+    flow: str
+    authorize_url: str | None = None
+    verification_uri: str | None = None
+    user_code: str | None = None
+    warnings: list[str] | None = None
+
+
+class _LoopbackAuthServer:
+    def __init__(
+        self,
+        *,
+        host: str,
+        port: int,
+        callback_path: str,
+        timeout_seconds: float,
+        status_stream,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._callback_path = callback_path
+        self._timeout_seconds = timeout_seconds
+        self._status_stream = status_stream
+        self._event = threading.Event()
+        self._params: dict[str, str] | None = None
+        self._error: str | None = None
+        self._server = self._build_server()
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+
+    @property
+    def redirect_uri(self) -> str:
+        return f"http://{self._host}:{self._server.server_port}{self._callback_path}"
+
+    def start(self) -> None:
+        self._thread.start()
+
+    def wait(self) -> dict[str, str]:
+        if not self._event.wait(timeout=self._timeout_seconds):
+            raise QingflowApiError.config_error(
+                f"timed out waiting for browser callback after {int(self._timeout_seconds)} seconds"
+            )
+        if self._error:
+            raise QingflowApiError(category="auth", message=self._error)
+        if self._params is None:
+            raise QingflowApiError(category="auth", message="browser callback did not return any parameters")
+        return self._params
+
+    def close(self) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+        self._thread.join(timeout=1)
+
+    def _build_server(self) -> HTTPServer:
+        parent = self
+
+        class CallbackServer(HTTPServer):
+            allow_reuse_address = True
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:  # noqa: N802
+                parsed = urlparse(self.path)
+                if parsed.path != parent._callback_path:
+                    self.send_error(404)
+                    return
+                query = {
+                    key: values[0]
+                    for key, values in parse_qs(parsed.query, keep_blank_values=True).items()
+                    if values
+                }
+                parent._params = query
+                parent._event.set()
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(_SUCCESS_HTML.encode("utf-8"))
+
+            def log_message(self, format: str, *args: object) -> None:  # noqa: A003
+                return
+
+        try:
+            return CallbackServer((self._host, self._port), Handler)
+        except OSError as exc:
+            raise QingflowApiError.config_error(f"failed to start local callback server: {exc}") from exc
+
+
+class CliOAuthLoginHelper:
+    def __init__(
+        self,
+        *,
+        http_client: httpx.Client | None = None,
+        browser_opener=webbrowser.open,
+        sleep_fn=time.sleep,
+        status_stream=None,
+    ) -> None:
+        self._owns_client = http_client is None
+        self._http_client = http_client or httpx.Client(
+            timeout=get_timeout_seconds(),
+            follow_redirects=True,
+            trust_env=False,
+        )
+        self._browser_opener = browser_opener
+        self._sleep = sleep_fn
+        self._status_stream = status_stream or sys.stderr
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http_client.close()
+
+    def login(
+        self,
+        *,
+        base_url: str | None,
+        client_id: str | None = None,
+        authorization_endpoint: str | None = None,
+        token_endpoint: str | None = None,
+        device_authorization_endpoint: str | None = None,
+        scope: str | None = None,
+        credential_field: str | None = None,
+        force_device: bool = False,
+    ) -> CliOAuthCredential:
+        config = load_cli_oauth_config(
+            base_url=base_url,
+            client_id=client_id,
+            authorization_endpoint=authorization_endpoint,
+            token_endpoint=token_endpoint,
+            device_authorization_endpoint=device_authorization_endpoint,
+            scope=scope,
+            credential_field=credential_field,
+        )
+        if force_device:
+            return self._device_flow(config)
+        try:
+            return self._authorization_code_flow(config)
+        except _BrowserUnavailableError as exc:
+            if not config.device_authorization_endpoint:
+                raise QingflowApiError.config_error(
+                    "browser auth is unavailable and no device_authorization_endpoint is configured"
+                ) from exc
+            self._write_status("Browser unavailable, switching to device flow.")
+            return self._device_flow(config)
+
+    def _authorization_code_flow(self, config: CliOAuthConfig) -> CliOAuthCredential:
+        state = uuid4().hex
+        code_verifier = _generate_code_verifier()
+        code_challenge = _code_challenge_s256(code_verifier)
+        server = _LoopbackAuthServer(
+            host=config.callback_host,
+            port=config.callback_port,
+            callback_path=config.callback_path,
+            timeout_seconds=config.browser_timeout_seconds,
+            status_stream=self._status_stream,
+        )
+        try:
+            server.start()
+            authorize_url = self._build_authorize_url(
+                config=config,
+                redirect_uri=server.redirect_uri,
+                state=state,
+                code_challenge=code_challenge,
+            )
+            self._write_status(f"Opening browser for Qingflow login: {authorize_url}")
+            opened = False
+            try:
+                opened = bool(self._browser_opener(authorize_url))
+            except Exception as exc:  # pragma: no cover - depends on local browser runtime
+                raise _BrowserUnavailableError(str(exc)) from exc
+            if not opened:
+                raise _BrowserUnavailableError("system browser refused to open authorization URL")
+            callback_params = server.wait()
+        finally:
+            server.close()
+
+        if callback_params.get("error"):
+            error_description = callback_params.get("error_description") or callback_params["error"]
+            raise QingflowApiError(category="auth", message=f"authorization failed: {error_description}")
+        returned_state = str(callback_params.get("state") or "")
+        if returned_state != state:
+            raise QingflowApiError(category="auth", message="authorization callback state mismatch")
+        credential = self._extract_credential(callback_params, credential_field=config.credential_field)
+        if credential:
+            return CliOAuthCredential(
+                credential=credential,
+                flow="authorization_code",
+                authorize_url=authorize_url,
+            )
+        code = str(callback_params.get("code") or "").strip()
+        if not code:
+            raise QingflowApiError(category="auth", message="authorization callback did not return a code")
+        token_payload = self._post_form(
+            config.token_endpoint,
+            {
+                "grant_type": "authorization_code",
+                "client_id": config.client_id,
+                "code": code,
+                "redirect_uri": server.redirect_uri,
+                "code_verifier": code_verifier,
+            },
+        )
+        credential = self._extract_credential(token_payload, credential_field=config.credential_field)
+        if not credential:
+            raise QingflowApiError(
+                category="auth",
+                message=(
+                    "token exchange succeeded but did not return a Qingflow credential; "
+                    "configure cli_auth.credential_field if your broker uses a custom field"
+                ),
+            )
+        return CliOAuthCredential(
+            credential=credential,
+            flow="authorization_code",
+            authorize_url=authorize_url,
+        )
+
+    def _device_flow(self, config: CliOAuthConfig) -> CliOAuthCredential:
+        if not config.device_authorization_endpoint:
+            raise QingflowApiError.config_error("device_authorization_endpoint is required for device flow")
+        start_payload = self._post_form(
+            config.device_authorization_endpoint,
+            {
+                "client_id": config.client_id,
+                "scope": config.scope,
+            },
+        )
+        device_code = str(start_payload.get("device_code") or "").strip()
+        if not device_code:
+            raise QingflowApiError(category="auth", message="device authorization did not return device_code")
+        verification_uri = (
+            str(start_payload.get("verification_uri_complete") or "").strip()
+            or str(start_payload.get("verification_uri") or "").strip()
+        )
+        user_code = str(start_payload.get("user_code") or "").strip() or None
+        interval_seconds = _coerce_positive_float(start_payload.get("interval")) or _DEFAULT_DEVICE_INTERVAL_SECONDS
+        expires_in_seconds = _coerce_positive_float(start_payload.get("expires_in")) or config.browser_timeout_seconds
+        if verification_uri:
+            self._write_status(f"Open this URL to continue Qingflow login: {verification_uri}")
+        if user_code:
+            self._write_status(f"Device code: {user_code}")
+        deadline = time.monotonic() + expires_in_seconds
+        interval = interval_seconds
+        while time.monotonic() < deadline:
+            payload, status_code = self._post_form_with_status(
+                config.token_endpoint,
+                {
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "device_code": device_code,
+                    "client_id": config.client_id,
+                },
+            )
+            if 200 <= status_code < 300:
+                credential = self._extract_credential(payload, credential_field=config.credential_field)
+                if not credential:
+                    raise QingflowApiError(
+                        category="auth",
+                        message=(
+                            "device token exchange succeeded but did not return a Qingflow credential; "
+                            "configure cli_auth.credential_field if your broker uses a custom field"
+                        ),
+                    )
+                return CliOAuthCredential(
+                    credential=credential,
+                    flow="device_code",
+                    verification_uri=verification_uri or None,
+                    user_code=user_code,
+                )
+            error_code = str(payload.get("error") or "").strip()
+            if error_code == "authorization_pending":
+                self._sleep(interval)
+                continue
+            if error_code == "slow_down":
+                interval += interval_seconds
+                self._sleep(interval)
+                continue
+            if error_code:
+                error_description = str(payload.get("error_description") or error_code).strip()
+                raise QingflowApiError(category="auth", message=f"device flow failed: {error_description}")
+            raise QingflowApiError(
+                category="auth",
+                message=f"device flow token polling failed with HTTP {status_code}",
+            )
+        raise QingflowApiError(
+            category="auth",
+            message="device flow expired before authorization completed",
+        )
+
+    def _build_authorize_url(
+        self,
+        *,
+        config: CliOAuthConfig,
+        redirect_uri: str,
+        state: str,
+        code_challenge: str,
+    ) -> str:
+        query = urlencode(
+            {
+                "response_type": "code",
+                "client_id": config.client_id,
+                "redirect_uri": redirect_uri,
+                "scope": config.scope,
+                "state": state,
+                "code_challenge": code_challenge,
+                "code_challenge_method": "S256",
+            }
+        )
+        separator = "&" if "?" in config.authorization_endpoint else "?"
+        return f"{config.authorization_endpoint}{separator}{query}"
+
+    def _post_form(self, url: str, form: dict[str, str]) -> dict[str, Any]:
+        payload, status_code = self._post_form_with_status(url, form)
+        if status_code >= 400:
+            error_text = str(payload.get("error_description") or payload.get("message") or payload.get("error") or "")
+            raise QingflowApiError(category="auth", message=error_text or f"HTTP {status_code}")
+        return payload
+
+    def _post_form_with_status(self, url: str, form: dict[str, str]) -> tuple[dict[str, Any], int]:
+        try:
+            response = self._http_client.post(
+                url,
+                data=form,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc)) from exc
+        return _parse_response_payload(response), response.status_code
+
+    def _extract_credential(self, payload: dict[str, Any], *, credential_field: str) -> str | None:
+        if not payload:
+            return None
+        candidate = _extract_nested_field(payload, credential_field)
+        if candidate:
+            return candidate
+        for alias in ("credential", "qingflow_credential", "x-qingflow-client-id"):
+            candidate = _extract_nested_field(payload, alias)
+            if candidate:
+                return candidate
+        return None
+
+    def _write_status(self, message: str) -> None:
+        self._status_stream.write(message.rstrip() + "\n")
+        self._status_stream.flush()
+
+
+class _BrowserUnavailableError(RuntimeError):
+    pass
+
+
+def login_with_cli_oauth(
+    *,
+    base_url: str | None,
+    client_id: str | None = None,
+    authorization_endpoint: str | None = None,
+    token_endpoint: str | None = None,
+    device_authorization_endpoint: str | None = None,
+    scope: str | None = None,
+    credential_field: str | None = None,
+    force_device: bool = False,
+) -> CliOAuthCredential:
+    helper = CliOAuthLoginHelper()
+    try:
+        return helper.login(
+            base_url=base_url,
+            client_id=client_id,
+            authorization_endpoint=authorization_endpoint,
+            token_endpoint=token_endpoint,
+            device_authorization_endpoint=device_authorization_endpoint,
+            scope=scope,
+            credential_field=credential_field,
+            force_device=force_device,
+        )
+    finally:
+        helper.close()
+
+
+def load_cli_oauth_config(
+    *,
+    base_url: str | None,
+    client_id: str | None = None,
+    authorization_endpoint: str | None = None,
+    token_endpoint: str | None = None,
+    device_authorization_endpoint: str | None = None,
+    scope: str | None = None,
+    credential_field: str | None = None,
+) -> CliOAuthConfig:
+    resolved_base_url = str(base_url or "").strip() or None
+    resolved_client_id = _first_text(
+        client_id,
+        os.getenv("QINGFLOW_CLI_AUTH_CLIENT_ID"),
+        get_config_value("cli_auth.client_id", default=None),
+    )
+    resolved_authorization_endpoint = _resolve_endpoint(
+        authorization_endpoint,
+        resolved_base_url,
+        env_var="QINGFLOW_CLI_AUTH_AUTHORIZATION_ENDPOINT",
+        config_key="cli_auth.authorization_endpoint",
+    )
+    resolved_token_endpoint = _resolve_endpoint(
+        token_endpoint,
+        resolved_base_url,
+        env_var="QINGFLOW_CLI_AUTH_TOKEN_ENDPOINT",
+        config_key="cli_auth.token_endpoint",
+    )
+    resolved_device_endpoint = _resolve_endpoint(
+        device_authorization_endpoint,
+        resolved_base_url,
+        env_var="QINGFLOW_CLI_AUTH_DEVICE_AUTHORIZATION_ENDPOINT",
+        config_key="cli_auth.device_authorization_endpoint",
+        required=False,
+    )
+    resolved_scope = _first_text(
+        scope,
+        os.getenv("QINGFLOW_CLI_AUTH_SCOPE"),
+        get_config_value("cli_auth.scope", default=None),
+        fallback=_DEFAULT_SCOPE,
+    )
+    callback_host = _first_text(
+        os.getenv("QINGFLOW_CLI_AUTH_CALLBACK_HOST"),
+        get_config_value("cli_auth.callback_host", default=None),
+        fallback=_DEFAULT_CALLBACK_HOST,
+    )
+    callback_path = _normalize_callback_path(
+        _first_text(
+            os.getenv("QINGFLOW_CLI_AUTH_CALLBACK_PATH"),
+            get_config_value("cli_auth.callback_path", default=None),
+            fallback=_DEFAULT_CALLBACK_PATH,
+        )
+    )
+    callback_port = _coerce_port(
+        os.getenv("QINGFLOW_CLI_AUTH_CALLBACK_PORT")
+        or get_config_value("cli_auth.callback_port", default=0)
+    )
+    browser_timeout_seconds = _coerce_positive_float(
+        os.getenv("QINGFLOW_CLI_AUTH_BROWSER_TIMEOUT_SECONDS")
+        or get_config_value("cli_auth.browser_timeout_seconds", default=_DEFAULT_BROWSER_TIMEOUT_SECONDS)
+    ) or _DEFAULT_BROWSER_TIMEOUT_SECONDS
+    resolved_credential_field = _first_text(
+        credential_field,
+        os.getenv("QINGFLOW_CLI_AUTH_CREDENTIAL_FIELD"),
+        get_config_value("cli_auth.credential_field", default=None),
+        fallback="credential",
+    )
+
+    missing: list[str] = []
+    if not resolved_client_id:
+        missing.append("cli_auth.client_id / QINGFLOW_CLI_AUTH_CLIENT_ID")
+    if not resolved_authorization_endpoint:
+        missing.append("cli_auth.authorization_endpoint / QINGFLOW_CLI_AUTH_AUTHORIZATION_ENDPOINT")
+    if not resolved_token_endpoint:
+        missing.append("cli_auth.token_endpoint / QINGFLOW_CLI_AUTH_TOKEN_ENDPOINT")
+    if missing:
+        raise QingflowApiError.config_error(
+            "CLI auth login requires OAuth config: " + ", ".join(missing)
+        )
+
+    return CliOAuthConfig(
+        client_id=resolved_client_id,
+        authorization_endpoint=resolved_authorization_endpoint,
+        token_endpoint=resolved_token_endpoint,
+        device_authorization_endpoint=resolved_device_endpoint,
+        scope=resolved_scope,
+        callback_host=callback_host,
+        callback_port=callback_port,
+        callback_path=callback_path,
+        browser_timeout_seconds=browser_timeout_seconds,
+        credential_field=resolved_credential_field,
+    )
+
+
+def _resolve_endpoint(
+    override: str | None,
+    base_url: str | None,
+    *,
+    env_var: str,
+    config_key: str,
+    required: bool = True,
+) -> str | None:
+    value = _first_text(
+        override,
+        os.getenv(env_var),
+        get_config_value(config_key, default=None),
+    )
+    if not value:
+        return None if not required else ""
+    parsed = urlparse(value)
+    if parsed.scheme and parsed.netloc:
+        return value
+    if not base_url:
+        raise QingflowApiError.config_error(
+            f"{config_key} is relative, but no base_url was provided to resolve it"
+        )
+    return urljoin(base_url.rstrip("/") + "/", value)
+
+
+def _first_text(*values: Any, fallback: str | None = None) -> str | None:
+    for value in values:
+        text = str(value or "").strip()
+        if text:
+            return text
+    return fallback
+
+
+def _normalize_callback_path(value: str) -> str:
+    normalized = str(value or "").strip() or _DEFAULT_CALLBACK_PATH
+    return normalized if normalized.startswith("/") else f"/{normalized}"
+
+
+def _coerce_positive_float(value: Any) -> float | None:
+    if value in (None, ""):
+        return None
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError):
+        return None
+    return parsed if parsed > 0 else None
+
+
+def _coerce_port(value: Any) -> int:
+    if value in (None, ""):
+        return 0
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        raise QingflowApiError.config_error("cli_auth.callback_port must be an integer") from None
+    if parsed < 0 or parsed > 65535:
+        raise QingflowApiError.config_error("cli_auth.callback_port must be between 0 and 65535")
+    return parsed
+
+
+def _generate_code_verifier() -> str:
+    random_bytes = os.urandom(32)
+    return base64.urlsafe_b64encode(random_bytes).decode("ascii").rstrip("=")
+
+
+def _code_challenge_s256(code_verifier: str) -> str:
+    digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+    return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+
+
+def _parse_response_payload(response: httpx.Response) -> dict[str, Any]:
+    if not response.content:
+        return {}
+    content_type = str(response.headers.get("Content-Type") or "").lower()
+    if "application/json" in content_type:
+        payload = response.json()
+        return payload if isinstance(payload, dict) else {"value": payload}
+    if "application/x-www-form-urlencoded" in content_type:
+        return {
+            key: values[0]
+            for key, values in parse_qs(response.text, keep_blank_values=True).items()
+            if values
+        }
+    try:
+        payload = response.json()
+    except ValueError:
+        try:
+            return json.loads(response.text)
+        except (TypeError, ValueError):
+            return {"message": response.text}
+    return payload if isinstance(payload, dict) else {"value": payload}
+
+
+def _extract_nested_field(payload: dict[str, Any], key: str) -> str | None:
+    value = payload.get(key)
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    for container_key in ("data", "result", "payload"):
+        nested = payload.get(container_key)
+        if isinstance(nested, dict):
+            nested_value = nested.get(key)
+            if isinstance(nested_value, str) and nested_value.strip():
+                return nested_value.strip()
+    return None

package/src/qingflow_mcp/cli/qingflow_login.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from typing import Any
+
+from Crypto.Cipher import PKCS1_v1_5
+from Crypto.PublicKey import RSA
+
+from ..backend_client import BackendClient
+from ..config import get_default_base_url, get_timeout_seconds, normalize_base_url
+from ..errors import QingflowApiError
+
+
+@dataclass(slots=True)
+class QingflowNativeLoginResult:
+    token: str
+    user_info: dict[str, Any]
+    login_token: str | None = None
+    flow: str = "qingflow_password"
+
+
+class QingflowNativeLoginHelper:
+    def __init__(self, *, backend: BackendClient | None = None) -> None:
+        self._owns_backend = backend is None
+        self._backend = backend or BackendClient(timeout=get_timeout_seconds())
+
+    def close(self) -> None:
+        if self._owns_backend:
+            self._backend.close()
+
+    def login_with_password(
+        self,
+        *,
+        base_url: str | None,
+        email: str,
+        password: str,
+    ) -> QingflowNativeLoginResult:
+        normalized_base_url = normalize_base_url(base_url) or get_default_base_url()
+        normalized_email = str(email or "").strip()
+        normalized_password = str(password or "")
+        if not normalized_base_url:
+            raise QingflowApiError.config_error("base_url is required or configure default_base_url")
+        if not normalized_email:
+            raise QingflowApiError.config_error("email is required for Qingflow account login")
+        if not normalized_password:
+            raise QingflowApiError.config_error("password is required for Qingflow account login")
+
+        pubkey_payload = self._backend.public_request("GET", normalized_base_url, "/user/pubkey", qf_version=None)
+        pubkey = self._extract_pubkey(pubkey_payload)
+        encrypted_password = _encrypt_password(normalized_password, pubkey)
+        login_payload = self._backend.public_request(
+            "POST",
+            normalized_base_url,
+            "/user/login",
+            json_body={"email": normalized_email, "password": encrypted_password},
+            qf_version=None,
+        )
+        if not isinstance(login_payload, dict):
+            raise QingflowApiError(category="auth", message="Qingflow login did not return a valid response")
+
+        token = str(login_payload.get("token") or "").strip()
+        login_token = str(login_payload.get("loginToken") or "").strip() or None
+        if not token:
+            if login_token:
+                raise QingflowApiError(
+                    category="auth",
+                    message=(
+                        "Qingflow account login requires additional security verification. "
+                        "CLI password login currently does not complete the loginToken verification step."
+                    ),
+                    details={"login_token_present": True},
+                )
+            raise QingflowApiError(
+                category="auth",
+                message="Qingflow login succeeded but did not return a token",
+            )
+
+        user_info = login_payload.get("userInfo")
+        if not isinstance(user_info, dict):
+            user_info = {}
+        return QingflowNativeLoginResult(
+            token=token,
+            login_token=login_token,
+            user_info=user_info,
+        )
+
+    def _extract_pubkey(self, payload: Any) -> str:
+        if not isinstance(payload, dict):
+            raise QingflowApiError(category="auth", message="Qingflow pubkey response is invalid")
+        pubkey = str(payload.get("pubkey") or "").strip()
+        if not pubkey:
+            raise QingflowApiError(category="auth", message="Qingflow pubkey response did not include pubkey")
+        return pubkey
+
+
+def login_with_qingflow_password(
+    *,
+    base_url: str | None,
+    email: str,
+    password: str,
+) -> QingflowNativeLoginResult:
+    helper = QingflowNativeLoginHelper()
+    try:
+        return helper.login_with_password(base_url=base_url, email=email, password=password)
+    finally:
+        helper.close()
+
+
+def _encrypt_password(password: str, pubkey: str) -> str:
+    public_key = RSA.import_key(
+        "-----BEGIN PUBLIC KEY-----\n" + pubkey.strip() + "\n-----END PUBLIC KEY-----\n"
+    )
+    cipher = PKCS1_v1_5.new(public_key)
+    encrypted = cipher.encrypt(password.encode("utf-8"))
+    return base64.b64encode(encrypted).decode("ascii")

package/src/qingflow_mcp/errors.py

@@ -43,14 +43,14 @@ class QingflowApiError(Exception):
     def auth_required(cls, profile: str) -> "QingflowApiError":
         return cls(
             category="auth",
-            message=f"Profile '{profile}' is not logged in. Run auth_use_credential first.",
+            message=f"Profile '{profile}' is not logged in. Run auth login or auth_use_credential first.",
         )
 
     @classmethod
     def workspace_not_selected(cls, profile: str) -> "QingflowApiError":
         return cls(
             category="workspace",
-            message=f"WORKSPACE_NOT_SELECTED: profile '{profile}' has no workspace from auth context. Re-run auth_use_credential.",
+            message=f"WORKSPACE_NOT_SELECTED: profile '{profile}' has no workspace from auth context. Re-run auth login or auth_use_credential.",
         )
 
     @classmethod

package/src/qingflow_mcp/public_surface.py

@@ -30,6 +30,7 @@ def tool_key(domain: str, tool_name: str) -> str:
 
 
 USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
+    PublicToolSpec(USER_DOMAIN, "auth_login", cli_route=("auth", "login"), mcp_public=False),
     PublicToolSpec(USER_DOMAIN, "auth_use_credential", ("auth_use_credential",), ("auth", "use-credential")),
     PublicToolSpec(USER_DOMAIN, "auth_whoami", ("auth_whoami",), ("auth", "whoami")),
     PublicToolSpec(USER_DOMAIN, "auth_logout", ("auth_logout",), ("auth", "logout")),

package/src/qingflow_mcp/tools/auth_tools.py

@@ -164,6 +164,136 @@ class AuthTools(ToolBase):
             ),
         }
 
+    def auth_use_token(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        base_url: str | None = None,
+        qf_version: str | None = None,
+        token: str | None = None,
+        login_token: str | None = None,
+        persist: bool = False,
+        user_info: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """使用已获得的 Qingflow token 建立本地会话。"""
+        normalized_base_url = self._normalize_base_url(base_url)
+        normalized_qf_version, qf_version_source = self._resolve_qf_version_input(qf_version)
+        normalized_token = self._normalize_text(token)
+        normalized_login_token = self._normalize_text(login_token)
+        if not normalized_token:
+            raise_tool_error(QingflowApiError.config_error("token is required"))
+
+        resolved_user_info = user_info if isinstance(user_info, dict) else None
+        response_qf_version: str | None = None
+        if resolved_user_info is None:
+            resolved_user_info, response_qf_version = self._fetch_user_info(
+                normalized_base_url,
+                normalized_token,
+                None,
+                qf_version=normalized_qf_version,
+                qf_version_source=qf_version_source,
+            )
+
+        last_workspace = resolved_user_info.get("lastWsInfo")
+        selected_ws_id = self._coerce_positive_int(
+            last_workspace.get("wsId") if isinstance(last_workspace, dict) else None
+        )
+        selected_ws_name = self._normalize_text(
+            (last_workspace.get("wsName") if isinstance(last_workspace, dict) else None)
+            or (last_workspace.get("workspaceName") if isinstance(last_workspace, dict) else None)
+            or (last_workspace.get("remark") if isinstance(last_workspace, dict) else None)
+        )
+        workspace_qf_version = (
+            self._workspace_system_version(last_workspace) if isinstance(last_workspace, dict) else None
+        )
+        if selected_ws_id is None:
+            fallback_workspace, fallback_qf_version = self._fetch_first_workspace(
+                normalized_base_url,
+                normalized_token,
+                qf_version=normalized_qf_version,
+                qf_version_source=qf_version_source,
+            )
+            if isinstance(fallback_workspace, dict):
+                selected_ws_id = self._coerce_positive_int(fallback_workspace.get("wsId"))
+                selected_ws_name = self._normalize_text(
+                    fallback_workspace.get("workspaceName")
+                    or fallback_workspace.get("wsName")
+                    or fallback_workspace.get("remark")
+                ) or selected_ws_name
+                workspace_qf_version = self._workspace_system_version(fallback_workspace) or fallback_qf_version
+        elif selected_ws_name is None or workspace_qf_version is None:
+            workspace = self._fetch_workspace_with_name_fallback(
+                normalized_base_url,
+                normalized_token,
+                selected_ws_id,
+                qf_version=normalized_qf_version,
+                qf_version_source=qf_version_source,
+            )
+            if isinstance(workspace, dict):
+                selected_ws_name = self._normalize_text(
+                    workspace.get("workspaceName")
+                    or workspace.get("wsName")
+                    or workspace.get("remark")
+                ) or selected_ws_name
+                workspace_qf_version = self._workspace_system_version(workspace) or workspace_qf_version
+
+        if workspace_qf_version is not None:
+            resolved_qf_version, resolved_qf_version_source = workspace_qf_version, "workspace_system_version"
+        else:
+            resolved_qf_version, resolved_qf_version_source = self._resolve_backend_qf_version(
+                response_qf_version,
+                fallback_qf_version=normalized_qf_version,
+                fallback_source=qf_version_source,
+            )
+
+        uid = self._coerce_positive_int(resolved_user_info.get("uid"))
+        if uid is None:
+            raise_tool_error(QingflowApiError(category="auth", message="Token validation did not return valid user info"))
+
+        session_profile = self.sessions.save_session(
+            profile=profile,
+            base_url=normalized_base_url,
+            qf_version=resolved_qf_version,
+            qf_version_source=resolved_qf_version_source,
+            token=normalized_token,
+            login_token=normalized_login_token,
+            credential=None,
+            uid=uid,
+            email=self._normalize_text(resolved_user_info.get("email")),
+            nick_name=self._normalize_text(
+                resolved_user_info.get("nickName")
+                or resolved_user_info.get("displayName")
+                or resolved_user_info.get("name")
+            ),
+            persist=persist,
+        )
+        if selected_ws_id is not None:
+            session_profile = self.sessions.select_workspace(profile, ws_id=selected_ws_id, ws_name=selected_ws_name)
+
+        return {
+            "profile": session_profile.profile,
+            "base_url": session_profile.base_url,
+            "qf_version": session_profile.qf_version,
+            "qf_version_source": session_profile.qf_version_source,
+            "uid": session_profile.uid,
+            "email": session_profile.email,
+            "nick_name": session_profile.nick_name,
+            "selected_ws_id": session_profile.selected_ws_id,
+            "selected_ws_name": session_profile.selected_ws_name,
+            "suggested_ws_id": session_profile.selected_ws_id,
+            "suggested_ws_name": session_profile.selected_ws_name,
+            "persisted": session_profile.persisted,
+            "request_route": self._request_route_payload(
+                BackendRequestContext(
+                    base_url=session_profile.base_url,
+                    token=normalized_token,
+                    ws_id=session_profile.selected_ws_id,
+                    qf_version=session_profile.qf_version,
+                    qf_version_source=session_profile.qf_version_source,
+                )
+            ),
+        }
+
     def _resolve_mcporter_auth_inputs(self, *, base_url: str | None, credential: str | None) -> tuple[str | None, str]:
         """从参数或 mcporter 配置解析登录所需 base_url 与 credential。"""
         normalized_base_url = self._normalize_text(base_url)

package/src/qingflow_mcp/tools/base.py

@@ -100,7 +100,7 @@ class ToolBase:
             self.sessions.invalidate(profile)
             error = QingflowApiError(
                 category="auth",
-                message=f"Qingflow session for profile '{profile}' has expired. Run auth_use_credential again.",
+                message=f"Qingflow session for profile '{profile}' has expired. Run auth login or auth_use_credential again.",
                 backend_code=error.backend_code,
                 request_id=error.request_id,
                 http_status=error.http_status,