@josephyan/qingflow-app-user-mcp 0.1.0-beta.9

package/src/qingflow_mcp/backend_client.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import uuid4
+
+import httpx
+
+from .config import DEFAULT_USER_AGENT, get_default_qf_version, get_timeout_seconds, normalize_base_url
+from .errors import QingflowApiError
+from .json_types import JSONObject, JSONScalar, JSONValue
+
+
+@dataclass(slots=True)
+class BackendRequestContext:
+    base_url: str
+    token: str
+    ws_id: int | None
+    qf_request_id: str | None = None
+    qf_version: str | None = None
+    qf_version_source: str | None = None
+
+
+@dataclass(slots=True)
+class BackendResponse:
+    data: JSONValue
+    headers: dict[str, str]
+    request_id: str
+    http_status: int
+    qf_response_version: str | None = None
+
+
+class BackendClient:
+    def __init__(self, timeout: float | None = None, client: httpx.Client | None = None) -> None:
+        self._owns_client = client is None
+        self._default_qf_version = get_default_qf_version()
+        self._client = client or httpx.Client(
+            timeout=timeout or get_timeout_seconds(),
+            follow_redirects=True,
+            trust_env=False,
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def public_request(
+        self,
+        method: str,
+        base_url: str,
+        path: str,
+        *,
+        params: JSONObject | None = None,
+        json_body: JSONValue = None,
+        unwrap: bool = True,
+        qf_version: str | None = None,
+        ) -> JSONValue:
+        return self.public_request_with_meta(
+            method,
+            base_url,
+            path,
+            params=params,
+            json_body=json_body,
+            unwrap=unwrap,
+            qf_version=qf_version,
+        ).data
+
+    def public_request_with_meta(
+        self,
+        method: str,
+        base_url: str,
+        path: str,
+        *,
+        params: JSONObject | None = None,
+        json_body: JSONValue = None,
+        unwrap: bool = True,
+        qf_version: str | None = None,
+    ) -> BackendResponse:
+        return self._request_with_meta(
+            method,
+            self._build_url(base_url, path),
+            params=params,
+            json_body=json_body,
+            headers=self._base_headers(None, None, qf_version=qf_version),
+            unwrap=unwrap,
+        )
+
+    def request(
+        self,
+        method: str,
+        context: BackendRequestContext,
+        path: str,
+        *,
+        params: JSONObject | None = None,
+        json_body: JSONValue = None,
+        unwrap: bool = True,
+    ) -> JSONValue:
+        return self.request_with_meta(
+            method,
+            context,
+            path,
+            params=params,
+            json_body=json_body,
+            unwrap=unwrap,
+        ).data
+
+    def request_with_meta(
+        self,
+        method: str,
+        context: BackendRequestContext,
+        path: str,
+        *,
+        params: JSONObject | None = None,
+        json_body: JSONValue = None,
+        unwrap: bool = True,
+    ) -> BackendResponse:
+        return self._request_with_meta(
+            method,
+            self._build_url(context.base_url, path),
+            params=params,
+            json_body=json_body,
+            headers=self._base_headers(
+                context.token,
+                context.ws_id,
+                context.qf_request_id,
+                qf_version=context.qf_version,
+            ),
+            unwrap=unwrap,
+        )
+
+    def describe_route(self, context: BackendRequestContext) -> JSONObject:
+        qf_version, source = self._resolve_qf_version(context.qf_version)
+        if context.qf_version is not None and context.qf_version_source:
+            source = context.qf_version_source
+        return {
+            "base_url": normalize_base_url(context.base_url) or context.base_url,
+            "qf_version": qf_version,
+            "qf_version_source": source,
+        }
+
+    def upload_binary(
+        self,
+        url: str,
+        content: bytes,
+        *,
+        content_type: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> JSONObject:
+        request_headers = dict(headers or {})
+        if content_type:
+            request_headers.setdefault("Content-Type", content_type)
+        try:
+            response = self._client.put(url, content=content, headers=request_headers or None)
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc))
+        if response.status_code >= 400:
+            raise QingflowApiError(
+                category="http",
+                message=self._extract_message(response.text) or f"HTTP {response.status_code}",
+                http_status=response.status_code,
+            )
+        return {
+            "status_code": response.status_code,
+            "headers": dict(response.headers),
+        }
+
+    def upload_form_file(
+        self,
+        url: str,
+        *,
+        form_fields: dict[str, str],
+        file_field: str,
+        file_name: str,
+        content: bytes,
+        content_type: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> JSONObject:
+        try:
+            response = self._client.post(
+                url,
+                data=form_fields,
+                files={file_field: (file_name, content, content_type or "application/octet-stream")},
+                headers=headers or None,
+            )
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc))
+        if response.status_code >= 400:
+            raise QingflowApiError(
+                category="http",
+                message=self._extract_message(response.text) or f"HTTP {response.status_code}",
+                http_status=response.status_code,
+            )
+        body: JSONValue = None
+        if response.content:
+            try:
+                body = response.json()
+            except ValueError:
+                body = response.text
+        return {
+            "status_code": response.status_code,
+            "headers": dict(response.headers),
+            "body": body,
+        }
+
+    def _request_with_meta(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: JSONObject | None,
+        json_body: JSONValue,
+        headers: dict[str, str],
+        unwrap: bool,
+    ) -> BackendResponse:
+        attempts = 2 if method.upper() == "GET" else 1
+        last_error: QingflowApiError | None = None
+        for _ in range(attempts):
+            try:
+                response = self._client.request(method.upper(), url, params=params, json=json_body, headers=headers)
+                parsed = self._parse_response(response, headers["Qf-Request-Id"], unwrap=unwrap)
+                return BackendResponse(
+                    data=parsed,
+                    headers=dict(response.headers),
+                    request_id=headers["Qf-Request-Id"],
+                    http_status=response.status_code,
+                    qf_response_version=self._extract_response_qf_version(response.headers),
+                )
+            except httpx.RequestError as exc:
+                last_error = QingflowApiError(category="network", message=str(exc), request_id=headers["Qf-Request-Id"])
+        assert last_error is not None
+        raise last_error
+
+    def _parse_response(self, response: httpx.Response, request_id: str, *, unwrap: bool) -> JSONValue:
+        payload: JSONValue
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = response.text
+        if response.status_code >= 400:
+            raise QingflowApiError(
+                category="http",
+                message=self._extract_message(payload) or f"HTTP {response.status_code}",
+                backend_code=self._extract_code(payload),
+                request_id=request_id,
+                http_status=response.status_code,
+            )
+        if not unwrap:
+            return payload
+        return self._unwrap_payload(payload, request_id, response.status_code)
+
+    def _unwrap_payload(self, payload: JSONValue, request_id: str, http_status: int) -> JSONValue:
+        if not isinstance(payload, dict):
+            return payload
+        if "success" in payload:
+            if not bool(payload.get("success")):
+                raise QingflowApiError(
+                    category="backend",
+                    message=self._extract_message(payload) or "Qingflow request failed",
+                    backend_code=self._extract_code(payload),
+                    request_id=request_id,
+                    http_status=http_status,
+                )
+            return self._extract_success_data(payload)
+        code = self._extract_code(payload)
+        if code not in (None, 0, "0"):
+            raise QingflowApiError(
+                category="backend",
+                message=self._extract_message(payload) or "Qingflow request failed",
+                backend_code=code,
+                request_id=request_id,
+                http_status=http_status,
+            )
+        if code in (0, "0"):
+            return self._extract_success_data(payload)
+        return payload
+
+    def _extract_success_data(self, payload: JSONObject) -> JSONValue:
+        for key in ("result", "data", "page", "obj"):
+            if key in payload:
+                return payload[key]
+        return payload
+
+    def _extract_message(self, payload: JSONValue) -> str | None:
+        if not isinstance(payload, dict):
+            return str(payload) if payload else None
+        for key in ("message", "msg", "errMsg", "error", "detail"):
+            value = payload.get(key)
+            if value:
+                return str(value)
+        return None
+
+    def _extract_code(self, payload: JSONValue) -> JSONScalar:
+        if isinstance(payload, dict):
+            return payload.get("code", payload.get("errCode"))
+        return None
+
+    def _base_headers(
+        self,
+        token: str | None,
+        ws_id: int | None,
+        request_id: str | None = None,
+        *,
+        qf_version: str | None = None,
+    ) -> dict[str, str]:
+        headers = {
+            "User-Agent": DEFAULT_USER_AGENT,
+            "Qf-Request-Id": request_id or str(uuid4()),
+        }
+        resolved_qf_version, _ = self._resolve_qf_version(qf_version)
+        if resolved_qf_version:
+            headers["Cookie"] = f"qfVersion={resolved_qf_version}"
+        if token:
+            headers["token"] = token
+        if ws_id is not None:
+            headers["wsId"] = str(ws_id)
+        return headers
+
+    def _resolve_qf_version(self, explicit_qf_version: str | None) -> tuple[str | None, str]:
+        if explicit_qf_version is not None:
+            normalized = str(explicit_qf_version).strip() or None
+            return normalized, "context"
+        if self._default_qf_version:
+            return self._default_qf_version, "default_config"
+        return None, "unset"
+
+    def _extract_response_qf_version(self, headers: httpx.Headers) -> str | None:
+        value = headers.get("x-q-response-version")
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        return normalized or None
+
+    def _build_url(self, base_url: str, path: str) -> str:
+        normalized = normalize_base_url(base_url)
+        if not normalized:
+            raise QingflowApiError.config_error("base_url is required")
+        return f"{normalized}/{path.lstrip('/')}"

package/src/qingflow_mcp/config.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+DEFAULT_PROFILE = "default"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_USER_AGENT = "qingflow-mcp/1.0"
+DEFAULT_RECORD_LIST_TYPE = 8
+ATTACHMENT_QUESTION_TYPE = 13
+DEFAULT_BASE_URL = "https://qingflow.com/api"
+
+
+def get_mcp_home() -> Path:
+    custom_home = os.getenv("QINGFLOW_MCP_HOME")
+    return Path(custom_home).expanduser() if custom_home else Path.home() / ".qingflow-mcp"
+
+
+def get_profiles_path() -> Path:
+    return get_mcp_home() / "profiles.json"
+
+
+def get_config_file_paths() -> list[Path]:
+    """
+    获取可能的配置文件路径列表，按优先级排序：
+    1. 环境变量 QINGFLOW_MCP_CONFIG_PATH 指定的路径
+    2. 当前工作目录下的 qingflow-mcp.config.json
+    3. MCP home 目录下的 config.json
+    4. 系统级配置 (Linux/Mac: /etc/qingflow-mcp/config.json)
+    """
+    paths: list[Path] = []
+
+    # 1. 环境变量
+    env_config = os.getenv("QINGFLOW_MCP_CONFIG_PATH")
+    if env_config:
+        paths.append(Path(env_config).expanduser())
+
+    # 2. 当前工作目录
+    paths.append(Path.cwd() / "qingflow-mcp.config.json")
+
+    # 3. MCP home 目录
+    paths.append(get_mcp_home() / "config.json")
+
+    # 4. 系统级配置 (仅非 Windows)
+    if os.name != "nt":
+        paths.append(Path("/etc/qingflow-mcp/config.json"))
+
+    return paths
+
+
+def load_config_file() -> dict[str, Any]:
+    """
+    加载第一个存在的配置文件
+
+    Returns:
+        配置字典，如果没有找到配置文件则返回空字典
+    """
+    for path in get_config_file_paths():
+        if path.exists():
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                    # 移除 JSON 注释 (简单的行注释处理)
+                    lines = []
+                    for line in content.split("\n"):
+                        stripped = line.strip()
+                        if not stripped.startswith("//") and not stripped.startswith("#"):
+                            lines.append(line)
+                    return json.loads("\n".join(lines))
+            except (json.JSONDecodeError, IOError) as e:
+                # 配置文件存在但读取失败，记录警告但不中断
+                print(f"Warning: Failed to load config from {path}: {e}")
+                continue
+    return {}
+
+
+def get_config_value(key: str, env_var: str | None = None, default: Any = None) -> Any:
+    """
+    获取配置值，优先级：环境变量 > 配置文件 > 默认值
+
+    Args:
+        key: 配置文件中的键名 (支持点号分隔的嵌套键，如 "profiles.default.name")
+        env_var: 环境变量名
+        default: 默认值
+
+    Returns:
+        配置值
+    """
+    # 1. 环境变量
+    if env_var:
+        env_value = os.getenv(env_var)
+        if env_value is not None:
+            return env_value
+
+    # 2. 配置文件
+    config = load_config_file()
+    keys = key.split(".")
+    value = config
+    for k in keys:
+        if isinstance(value, dict) and k in value:
+            value = value[k]
+        else:
+            value = None
+            break
+
+    if value is not None:
+        return value
+
+    # 3. 默认值
+    return default
+
+
+def get_default_base_url() -> str | None:
+    """获取默认的 Qingflow 后端地址"""
+    value = get_config_value(
+        "default_base_url",
+        env_var="QINGFLOW_MCP_DEFAULT_BASE_URL",
+        default=DEFAULT_BASE_URL
+    )
+    return normalize_base_url(value) if value else None
+
+
+def get_default_qf_version() -> str | None:
+    """获取默认的 qfVersion 路由值"""
+    value = get_config_value(
+        "default_qf_version",
+        env_var="QINGFLOW_MCP_DEFAULT_QF_VERSION",
+        default=None,
+    )
+    if value is None:
+        return None
+    normalized = str(value).strip()
+    return normalized or None
+
+
+def get_timeout_seconds() -> float:
+    """获取 HTTP 超时秒数"""
+    value = get_config_value(
+        "timeout_seconds",
+        env_var="QINGFLOW_MCP_TIMEOUT_SECONDS",
+        default=DEFAULT_TIMEOUT_SECONDS
+    )
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return DEFAULT_TIMEOUT_SECONDS
+
+
+def get_log_level() -> str:
+    """获取日志级别"""
+    return get_config_value(
+        "log_level",
+        env_var="QINGFLOW_MCP_LOG_LEVEL",
+        default="INFO"
+    )
+
+
+def normalize_base_url(base_url: str | None) -> str | None:
+    """规范化 base URL"""
+    if base_url is None:
+        return None
+    normalized = base_url.strip()
+    if not normalized:
+        return None
+    normalized = normalized.rstrip("/")
+    try:
+        parsed = urlsplit(normalized)
+    except ValueError:
+        return normalized
+    if not parsed.scheme or not parsed.netloc:
+        return normalized
+
+    hostname = parsed.hostname or ""
+    if hostname.lower() == "www.qingflow.com":
+        netloc = "qingflow.com"
+        if parsed.port is not None:
+            netloc = f"{netloc}:{parsed.port}"
+        normalized = urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment))
+    return normalized

package/src/qingflow_mcp/errors.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+
+from .json_types import JSONObject, JSONScalar
+
+
+INVALID_TOKEN_MARKERS = (
+    "invalid token",
+    "token invalid",
+    "token失效",
+    "无效token",
+    "登录失效",
+    "login token invalid",
+    "access token invalid",
+)
+
+
+@dataclass(slots=True)
+class QingflowApiError(Exception):
+    category: str
+    message: str
+    backend_code: JSONScalar = None
+    request_id: str | None = None
+    http_status: int | None = None
+    details: JSONObject | None = None
+
+    def to_dict(self) -> JSONObject:
+        return asdict(self)
+
+    def as_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False)
+
+    def __str__(self) -> str:
+        return self.as_json()
+
+    def looks_like_invalid_token(self) -> bool:
+        text = self.message.lower()
+        return any(marker in text for marker in INVALID_TOKEN_MARKERS)
+
+    @classmethod
+    def auth_required(cls, profile: str) -> "QingflowApiError":
+        return cls(
+            category="auth",
+            message=f"Profile '{profile}' is not logged in. Run auth_login first.",
+        )
+
+    @classmethod
+    def workspace_not_selected(cls, profile: str) -> "QingflowApiError":
+        return cls(
+            category="workspace",
+            message=f"WORKSPACE_NOT_SELECTED: profile '{profile}' has no selected workspace. Run workspace_select first.",
+        )
+
+    @classmethod
+    def config_error(cls, message: str) -> "QingflowApiError":
+        return cls(category="config", message=message)
+
+    @classmethod
+    def not_supported(cls, message: str) -> "QingflowApiError":
+        return cls(category="not_supported", message=message)
+
+
+def raise_tool_error(error: QingflowApiError) -> None:
+    raise RuntimeError(error.as_json())

package/src/qingflow_mcp/json_types.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Protocol, Any
+
+# Use Any for JSON types to avoid Pydantic recursion issues
+# These are used for MCP tool signatures where exact typing is less critical
+JSONScalar = Any
+JSONValue = Any
+JSONObject = dict[str, Any]
+JSONArray = list[Any]
+
+
+class KeyringBackend(Protocol):
+    def set_password(self, service: str, key: str, value: str) -> None: ...
+
+    def get_password(self, service: str, key: str) -> str | None: ...
+
+    def delete_password(self, service: str, key: str) -> None: ...

package/src/qingflow_mcp/list_type_labels.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+
+RECORD_LIST_TYPE_LABELS: dict[int, str] = {
+    1: "待办",
+    2: "已办",
+    3: "我发起的-已通过",
+    4: "我发起的-已拒绝",
+    5: "我发起的-草稿",
+    6: "我发起的-待完善",
+    7: "我发起的-流程中",
+    8: "数据管理-全部数据",
+    9: "数据管理-已通过",
+    10: "数据管理-已拒绝",
+    11: "数据管理-流程中",
+    12: "抄送",
+    13: "图表分享者",
+    14: "我发起的",
+    15: "数据管理-已结束",
+    16: "我发起的-已结束",
+}
+
+TASK_TYPE_LABELS: dict[int, str] = {
+    1: "待办",
+    2: "我发起的",
+    3: "抄送",
+    5: "已办",
+}
+
+APP_PUBLISH_STATUS_LABELS: dict[int, str] = {
+    0: "未发布",
+    1: "已发布-有修改",
+    2: "已发布",
+}
+
+
+def get_record_list_type_label(list_type: int | None) -> str | None:
+    if list_type is None:
+        return None
+    return RECORD_LIST_TYPE_LABELS.get(list_type)
+
+
+def get_task_type_label(type_value: int | None) -> str | None:
+    if type_value is None:
+        return None
+    return TASK_TYPE_LABELS.get(type_value)
+
+
+def get_app_publish_status_label(status: int | None) -> str | None:
+    if status is None:
+        return None
+    return APP_PUBLISH_STATUS_LABELS.get(status)