mcp-uof 0.1.0__py3-none-any.whl

mcp_uof/__init__.py

@@ -0,0 +1,4 @@
+"""UOF MCP server package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

mcp_uof/_log.py

@@ -0,0 +1,15 @@
+"""共用診斷輸出：一律走 stderr。
+
+stdio MCP 下 stdout 專供 JSON-RPC，任何混入 stdout 的文字都會破壞協定。診斷/log 訊息一律經
+本模組輸出到 stderr。這條規則只在這裡有單一實作——各模組 `from .._log import eprint`，不要再各自
+複製一份（複製就會在某處漏改而污染 stdout）。
+"""
+from __future__ import annotations
+
+import sys
+
+
+def eprint(*args, **kwargs) -> None:
+    """print 到 stderr（呼叫端可覆寫 file）。"""
+    kwargs.setdefault("file", sys.stderr)
+    print(*args, **kwargs)

mcp_uof/auth/__init__.py

@@ -0,0 +1,68 @@
+"""
+UOF MCP Server — Authentication package.
+
+Two providers coexist behind a common ABC:
+
+- TokenAuthProvider  — RSA-encrypted account/password → SOAP GetToken → bearer token
+                       (works against UOF deployments with PublicAPI module installed)
+- SessionAuthProvider — Login.aspx form post → ASPXFORMSAUTH cookie + storage state
+                       (works against UOF deployments without PublicAPI; web-only)
+
+There is no user-selectable mode: which mechanism (SOAP/token vs web/session) a tool uses is
+a per-tool decision baked into ops.router. Both providers coexist and are built lazily from the
+same identity (one process = one UOF_ACCOUNT). See docs/architecture.md.
+"""
+
+from .base import (
+    AuthMode,
+    AuthProvider,
+    get_provider,
+    get_session_provider,
+    get_token_provider,
+    require_auth,
+)
+from .token import TokenAuthProvider
+
+# Kept for backwards compatibility with existing imports that did `from .auth import get_token`.
+# Returns the SOAP identity's bearer token; tools/mechanisms should prefer their own provider.
+def get_token() -> str:
+    return get_token_provider().fetch_token()
+
+
+def rsa_encrypt(public_key_base64: str, plaintext: str) -> str:
+    """Compatibility shim — RSA-encrypt with the token provider's helper.
+
+    Only meaningful in token mode (session mode never RSA-encrypts). Kept so existing
+    callers/tests that did `from mcp_uof.auth import rsa_encrypt` keep working after the
+    auth package split.
+    """
+    from .token import _rsa_encrypt
+    return _rsa_encrypt(public_key_base64, plaintext)
+
+
+def read_credentials():
+    """Compatibility shim used by domains/system/tools.py."""
+    provider = get_provider()
+    if not hasattr(provider, "read_credentials"):
+        return None
+    return provider.read_credentials()
+
+
+def credentials_file() -> str:
+    """Compatibility shim — returns the active provider's persistence file."""
+    return get_provider().credentials_file()
+
+
+__all__ = [
+    "AuthMode",
+    "AuthProvider",
+    "TokenAuthProvider",
+    "credentials_file",
+    "get_provider",
+    "get_session_provider",
+    "get_token",
+    "get_token_provider",
+    "read_credentials",
+    "require_auth",
+    "rsa_encrypt",
+]

mcp_uof/auth/base.py

@@ -0,0 +1,176 @@
+"""
+Auth provider base + the two per-mechanism providers.
+
+`AuthProvider` defines the minimal surface every concrete provider must satisfy. There are
+two: `get_token_provider()` (SOAP/PublicAPI — RSA + GetToken) and `get_session_provider()`
+(web — Login.aspx cookie). Each is cached per process so it can hold long-lived state
+(token cache, browser session). `require_auth` validates whichever the tool's bound
+mechanism needs; `get_provider()` remains as a token-provider alias for compat shims.
+"""
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from enum import Enum
+from functools import wraps
+from typing import Any, Callable, Optional
+
+
+class AuthMode(str, Enum):
+    """認證機制描述符：token = RSA + GetToken（SOAP 機制用）；session = Login.aspx cookie（web 機制用）。
+
+    這只是各 UOF 機制標記自己用哪種認證，不是使用者可選的模式。
+    """
+    TOKEN = "token"
+    SESSION = "session"
+
+
+class AuthProvider(ABC):
+    """Abstract auth provider; both token + session implementations live behind this."""
+
+    mode: AuthMode  # set by subclass
+
+    @abstractmethod
+    def ensure_valid(self) -> None:
+        """Refresh credentials if needed. Raises RuntimeError on hard auth failure."""
+
+    @abstractmethod
+    def status_report(self) -> str:
+        """Human-readable check_auth output. Triggers a refresh if needed."""
+
+    @abstractmethod
+    def credentials_file(self) -> str:
+        """Path to the on-disk credential/cookie cache for this identity."""
+
+    @abstractmethod
+    def clear(self, all_identities: bool = False) -> None:
+        """Wipe cached credentials (memory + disk)."""
+
+    def required_env_help(self) -> str:
+        """Bullet list of env vars this provider requires — shown when auth fails."""
+        return (
+            "- `UOF_BASE_URL`\n"
+            "- `UOF_ACCOUNT`\n"
+            "- `UOF_PASSWORD`"
+        )
+
+
+def auth_failure_message(detail: str = "") -> str:
+    """
+    登入／憑證失敗時給介接 AI 的固定訊息。
+
+    目的：帳號密碼失效或登入有誤時，要讓介接的 AI 對使用者清楚、固定地說明這是設定層級
+    的登入問題，而不是讓 AI 自行猜測或沿用對話記憶中的帳號資訊臆測。
+    """
+    account = os.getenv("UOF_ACCOUNT", "(未設定)")
+    base_url = os.getenv("UOF_BASE_URL", "(未設定)")
+    detail_line = f"原因：{detail}\n" if detail else ""
+    return (
+        f"🔒 UOF 登入失敗：無法以帳號「{account}」取得有效憑證。\n"
+        f"{detail_line}"
+        f"連線目標：{base_url}\n\n"
+        "這是設定層級的問題，需要由設定這個 MCP 的人處理，無法在對話中自行解決。常見原因：\n"
+        "- UOF_ACCOUNT 或 UOF_PASSWORD 不正確，或密碼已在 UOF 變更\n"
+        "- 該帳號在 UOF 被停用，或未設定部門/職級\n"
+        "- 此 UOF 站台未提供 PublicAPI，SOAP 認證無法運作\n\n"
+        "請直接、明確告訴使用者：「UOF 登入失敗，請檢查 MCP 設定中的帳號、密碼與連線設定是否正確」。\n"
+        "不要猜測其他原因、不要沿用先前對話記得的帳號或密碼、也不要假設已經解決。"
+    )
+
+
+_token_provider: Optional[AuthProvider] = None
+_session_provider: Optional[AuthProvider] = None
+
+
+def get_token_provider() -> AuthProvider:
+    """SOAP 機制用的認證（RSA 帳密 → GetToken token）。惰性建立、單例。"""
+    global _token_provider
+    if _token_provider is None:
+        from .token import TokenAuthProvider
+        _token_provider = TokenAuthProvider()
+    return _token_provider
+
+
+def get_session_provider() -> AuthProvider:
+    """web 機制用的認證（Login.aspx 登入 → cookie / storage state）。惰性建立、單例。"""
+    global _session_provider
+    if _session_provider is None:
+        from .session import SessionAuthProvider
+        _session_provider = SessionAuthProvider()
+    return _session_provider
+
+
+def get_provider() -> AuthProvider:
+    """相容入口 = SOAP 身份（token）的認證 provider。
+
+    現在機制是每工具綁定的（見 ops.router）：SOAP 工具用 token、web 工具用 session，各自取得
+    所需 provider。此函式保留為 token provider 的別名，給仍以單一身份語意呼叫的相容 shim
+    （get_token / credentials_file / domains.system）。"""
+    return get_token_provider()
+
+
+def reset_provider_for_tests() -> None:
+    """Test hook — drop cached providers so the next getter rebuilds them."""
+    global _token_provider, _session_provider
+    _token_provider = None
+    _session_provider = None
+
+
+def _provider_for(mechanism: str) -> AuthProvider:
+    """機制 → 它需要的認證 provider。soap→token、web→session。"""
+    if mechanism == "web":
+        return get_session_provider()
+    return get_token_provider()  # "soap" 與未知值都用 token（與舊行為一致）
+
+
+def _mechanisms_for_call(op: str, args: tuple, kwargs: dict) -> list:
+    """依本次呼叫參數決定認證機制。
+
+    `BINDING` 是工具層預設；起單相關工具還有表單層分派：registry 命中的表單會走 web_apply，
+    因此入口認證也要驗 session，不能先被 SOAP token 擋下。
+    """
+    from ..ops.router import mechanisms_for
+
+    key = None
+    if op in ("get_form_structure_by_id",):
+        key = kwargs.get("form_id") if "form_id" in kwargs else (args[0] if args else None)
+    elif op in ("get_form_structure", "preview_workflow", "apply_form"):
+        key = kwargs.get("form_version_id") if "form_version_id" in kwargs else (args[0] if args else None)
+
+    if key:
+        from ..ops import web_apply
+        if web_apply.resolve(str(key)):
+            return ["web"]
+        if op in ("get_form_structure", "preview_workflow", "apply_form"):
+            return ["web"]
+    return mechanisms_for(op)
+
+
+def require_auth(func: Callable[..., Any]) -> Callable[..., Any]:
+    """工具入口的認證閘——依「該工具設計上綁定的機制」驗證對應認證，而非一律驗 SOAP token。
+
+    一個工具可走多條機制時（fallback，SOAP 優先）採 **OR**：任一機制的認證通過就放行；
+    只有當它所有可走機制的認證**都**不過，才回固定的失敗訊息（對使用者只有「通過與否」）。
+    驗證集中在這一道入口閘，工具內部不再重複驗證；機制本身的失效重試（token 自動刷新、
+    web session 重登）仍各自在 backend 處理。失敗回字串而非 raise，避免 MCP client 收到 isError。
+    """
+    op = func.__name__.removeprefix("uof_custom_")
+    # fail-loud（裝飾期）：op 必須在 BINDING 有登錄機制綁定。漏綁、工具改名、或裝飾順序錯誤
+    # （@require_auth 被放到 @mcp.tool 外層導致 __name__ 變 wrapper）都會讓 op 解析不到綁定，
+    # 在 import server 時就立刻爆，而非讓 web 工具在執行期靜默回歸成被 SOAP token 擋。
+    from ..ops.router import mechanisms_for as _validate_op
+    _validate_op(op)
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        errors = []
+        for mech in _mechanisms_for_call(op, args, kwargs):
+            try:
+                _provider_for(mech).ensure_valid()
+            except Exception as e:
+                errors.append(f"{mech}: {' '.join(str(e).split())[:120]}")
+                continue
+            return func(*args, **kwargs)   # 任一機制認證通過即放行；工具本體例外不包成登入失敗
+        # 所有可走機制都認證不過 → 才是真正不可用
+        return auth_failure_message("；".join(errors))
+    return wrapper

mcp_uof/auth/session.py

@@ -0,0 +1,152 @@
+"""
+SessionAuthProvider — UOF Login.aspx form post + cookie jar.
+
+For UOF deployments without PublicAPI module (the SOAP/ASMX backend is absent), the only
+way to drive operations is to log in as a real user would and reuse the session. This
+provider:
+
+  1. Performs the ASP.NET WebForms login (handles __VIEWSTATE round-trip)
+  2. Stores the authenticated `.ASPXFORMSAUTH_UOF` cookie via Playwright's storage_state
+     so the cookie jar can be reused by the Web ops backend (which drives Telerik UI)
+     and survives process restarts.
+  3. Re-logs in transparently when the session expires (typical ASP.NET idle timeout ~20m).
+
+NOTE: The actual browser/Playwright is owned by `ops.web.WebBackend` — this provider only
+*requests* a session refresh and reads identity from the resulting page. We keep the
+Playwright lifecycle in one place to avoid two parallel browsers fighting for the same
+storage_state file.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+import time
+from pathlib import Path
+from typing import Optional
+
+from .base import AuthMode, AuthProvider
+
+
+from .._log import eprint as _eprint  # 診斷一律走 stderr（共用，勿在各檔複製）
+
+
+CREDENTIALS_DIR = Path(os.path.expanduser("~")) / ".uof"
+DEFAULT_SESSION_TTL = 20 * 60  # ASP.NET 預設 idle timeout = 20 min
+
+
+def _ensure_dir() -> None:
+    if not CREDENTIALS_DIR.exists():
+        CREDENTIALS_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+
+class SessionAuthProvider(AuthProvider):
+    mode = AuthMode.SESSION
+
+    def __init__(self) -> None:
+        self._last_validated: float = 0.0
+        self._identity_cached: Optional[str] = None
+        # Logged-in user's display info, populated after successful login.
+        self.logged_in_display_name: Optional[str] = None
+
+    # ── Identity helpers ────────────────────────────────────────────
+    def _identity_key(self) -> str:
+        return "|".join(
+            [
+                os.getenv("UOF_BASE_URL", ""),
+                os.getenv("UOF_ACCOUNT", ""),
+            ]
+        )
+
+    def credentials_file(self) -> str:
+        """Path to the Playwright storage_state JSON for this identity."""
+        account = os.getenv("UOF_ACCOUNT", "anonymous")
+        safe_account = re.sub(r"[^A-Za-z0-9_.-]", "_", account) or "anonymous"
+        digest = hashlib.sha256(self._identity_key().encode("utf-8")).hexdigest()[:8]
+        return str(CREDENTIALS_DIR / f"storage_state-{safe_account}-{digest}.json")
+
+    def required_env_help(self) -> str:
+        return (
+            "- `UOF_BASE_URL`\n"
+            "- `UOF_ACCOUNT`\n"
+            "- `UOF_PASSWORD`"
+        )
+
+    # ── AuthProvider surface ────────────────────────────────────────
+    def ensure_valid(self) -> None:
+        """Trigger the web backend to verify or re-establish the browser session."""
+        # Avoid hammering the server: re-validate at most once per 30s.
+        if time.time() - self._last_validated < 30 and self._identity_cached == self._identity_key():
+            return
+        self._validate_env()
+        # Delegate to ops.web.WebBackend, which owns the Playwright runtime.
+        from ..ops.web import get_web_runtime
+        runtime = get_web_runtime()
+        display_name = runtime.ensure_logged_in()
+        self.logged_in_display_name = display_name
+        self._last_validated = time.time()
+        self._identity_cached = self._identity_key()
+
+    def status_report(self) -> str:
+        account = os.getenv("UOF_ACCOUNT", "(未設定)")
+        base_url = os.getenv("UOF_BASE_URL", "(未設定)")
+        try:
+            self.ensure_valid()
+        except RuntimeError as e:
+            from .base import auth_failure_message
+            return auth_failure_message(str(e))
+        display = self.logged_in_display_name or account
+        return (
+            f"✅ Session 有效，目前以 **{account}**（{display}）的身份操作"
+            f"（認證：網頁 session）。\n"
+            f"🔗 Base URL: {base_url}\n"
+            f"📂 Storage state: `{self.credentials_file()}`\n"
+            f"⚠️ 網頁機制：操作走 Playwright 驅動 UOF 頁面，並非所有工具皆已實作。"
+        )
+
+    def clear(self, all_identities: bool = False) -> None:
+        _ensure_dir()
+        if all_identities:
+            for path in CREDENTIALS_DIR.glob("storage_state-*.json"):
+                path.unlink(missing_ok=True)
+                _eprint(f"[auth.session] 🗑️ 已清除 storage state: {path}")
+        else:
+            p = Path(self.credentials_file())
+            if p.exists():
+                p.unlink()
+                _eprint(f"[auth.session] 🗑️ 已清除 storage state: {p}")
+        # Force web runtime to reset on next call
+        from ..ops.web import reset_web_runtime
+        reset_web_runtime()
+        self._last_validated = 0.0
+        self._identity_cached = None
+
+    # ── Internal ────────────────────────────────────────────────────
+    def _validate_env(self) -> None:
+        missing = [
+            k for k in ("UOF_BASE_URL", "UOF_ACCOUNT", "UOF_PASSWORD")
+            if not os.getenv(k)
+        ]
+        if missing:
+            raise RuntimeError(
+                "UOF_BASE_URL、UOF_ACCOUNT、UOF_PASSWORD 必須全部設定。"
+                f"目前缺少: {', '.join(missing)}"
+            )
+
+    # ── Storage-state metadata sidecar (account, timestamps) ────────
+    def write_metadata(self) -> None:
+        """Write a small JSON next to storage_state recording who logged in + when."""
+        _ensure_dir()
+        meta_path = self.credentials_file() + ".meta"
+        data = {
+            "account": os.getenv("UOF_ACCOUNT", ""),
+            "base_url": os.getenv("UOF_BASE_URL", ""),
+            "identity": self._identity_key(),
+            "logged_in_at": time.time(),
+            "display_name": self.logged_in_display_name or "",
+        }
+        with open(meta_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+        os.chmod(meta_path, stat.S_IRUSR | stat.S_IWUSR)

mcp_uof/auth/token.py

@@ -0,0 +1,256 @@
+"""
+TokenAuthProvider — RSA + SOAP GetToken.
+
+This is the original mcp-uof authentication path, preserved verbatim and adapted to the
+AuthProvider interface. Token is cached in memory and persisted to
+`~/.uof/credentials-<account>-<hash>.json` keyed by identity so multiple deployments don't
+poison each other's cache.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import re
+import stat
+import time
+from typing import Optional
+
+from Crypto.Cipher import PKCS1_v1_5
+from Crypto.PublicKey import RSA
+
+from .base import AuthMode, AuthProvider
+
+
+from .._log import eprint as _eprint  # 診斷一律走 stderr（共用，勿在各檔複製）
+
+
+CREDENTIALS_DIR = os.path.join(os.path.expanduser("~"), ".uof")
+DEFAULT_TOKEN_TTL = 14 * 24 * 60 * 60  # 14 days
+
+# Pre-package single-file credential layout (kept for cleanup compatibility).
+_LEGACY_CREDENTIALS_FILE = os.path.join(CREDENTIALS_DIR, "credentials.json")
+
+
+def _ensure_credentials_dir() -> None:
+    if not os.path.exists(CREDENTIALS_DIR):
+        os.makedirs(CREDENTIALS_DIR, mode=0o700, exist_ok=True)
+        _eprint(f"[auth.token] 已建立憑證目錄: {CREDENTIALS_DIR}")
+
+
+def _rsa_encrypt(public_key_base64: str, plaintext: str) -> str:
+    public_key_xml = base64.b64decode(public_key_base64).decode("utf-8")
+    key = _import_rsa_xml_key(public_key_xml)
+    cipher = PKCS1_v1_5.new(key)
+    encrypted = cipher.encrypt(plaintext.encode("utf-8"))
+    return base64.b64encode(encrypted).decode("ascii")
+
+
+def _import_rsa_xml_key(xml_string: str) -> RSA.RsaKey:
+    from lxml import etree
+
+    root = etree.fromstring(xml_string.encode("utf-8"))
+    modulus_elem = root.find("Modulus")
+    exponent_elem = root.find("Exponent")
+    if modulus_elem is None or exponent_elem is None:
+        raise ValueError("RSA XML 格式錯誤：缺少 Modulus 或 Exponent 元素")
+    n = int.from_bytes(base64.b64decode(modulus_elem.text.strip()), byteorder="big")
+    e = int.from_bytes(base64.b64decode(exponent_elem.text.strip()), byteorder="big")
+    return RSA.construct((n, e))
+
+
+class TokenAuthProvider(AuthProvider):
+    mode = AuthMode.TOKEN
+
+    def __init__(self) -> None:
+        self._token: Optional[str] = None
+        self._expires_at: float = 0.0
+        self._identity: Optional[str] = None
+
+    # ── Identity helpers ────────────────────────────────────────────
+    def _identity_key(self) -> str:
+        return "|".join(
+            [
+                os.getenv("UOF_BASE_URL", ""),
+                os.getenv("UOF_APP_NAME", ""),
+                os.getenv("UOF_ACCOUNT", ""),
+            ]
+        )
+
+    def credentials_file(self) -> str:
+        account = os.getenv("UOF_ACCOUNT", "anonymous")
+        safe_account = re.sub(r"[^A-Za-z0-9_.-]", "_", account) or "anonymous"
+        digest = hashlib.sha256(self._identity_key().encode("utf-8")).hexdigest()[:8]
+        return os.path.join(CREDENTIALS_DIR, f"credentials-{safe_account}-{digest}.json")
+
+    def required_env_help(self) -> str:
+        return (
+            "- `UOF_BASE_URL`\n"
+            "- `UOF_APP_NAME`\n"
+            "- `UOF_RSA_PUBLIC_KEY`\n"
+            "- `UOF_ACCOUNT`\n"
+            "- `UOF_PASSWORD`"
+        )
+
+    # ── AuthProvider surface ────────────────────────────────────────
+    def ensure_valid(self) -> None:
+        self.fetch_token()
+
+    def status_report(self) -> str:
+        account = os.getenv("UOF_ACCOUNT", "(未設定)")
+        base_url = os.getenv("UOF_BASE_URL", "(未設定)")
+        # 實際向 UOF 重新取得一次 Token 來「真正驗證」登入，而非只看本地快取 TTL——
+        # UOF Token 的伺服器端有效期可能短於本地 TTL，只看快取會誤報為有效。
+        try:
+            self.fetch_token(force_refresh=True)
+            return (
+                f"✅ 已成功登入 UOF，目前以「{account}」的身份操作。\n"
+                f"🔗 連線目標：{base_url}\n"
+                f"Token 由系統自動管理，過期時會在工具呼叫時自動更新，使用者不需手動處理。\n"
+                f"💡 要改以其他人的身份操作，請切換 MCP 設定（一份設定 = 一個身份）。"
+            )
+        except RuntimeError as e:
+            from .base import auth_failure_message
+            return auth_failure_message(str(e))
+
+    def clear(self, all_identities: bool = False) -> None:
+        targets = []
+        if all_identities:
+            if os.path.isdir(CREDENTIALS_DIR):
+                for name in os.listdir(CREDENTIALS_DIR):
+                    if name.startswith("credentials") and name.endswith(".json"):
+                        targets.append(os.path.join(CREDENTIALS_DIR, name))
+        else:
+            targets.append(self.credentials_file())
+            if os.path.exists(_LEGACY_CREDENTIALS_FILE):
+                targets.append(_LEGACY_CREDENTIALS_FILE)
+        for path in targets:
+            if os.path.exists(path):
+                os.remove(path)
+                _eprint(f"[auth.token] 🗑️ 已清除憑證: {path}")
+        self._token = None
+        self._expires_at = 0.0
+        self._identity = None
+
+    # ── Token-specific API ──────────────────────────────────────────
+    def fetch_token(self, force_refresh: bool = False) -> str:
+        """取得有效 Token。
+
+        force_refresh=True 時略過記憶體與磁碟快取，強制重新向 UOF 取得——用於
+        「快取 Token 已被伺服器端判定失效」時的刷新重試（UOF Token 伺服器端有效期
+        可能短於本地 TTL，失效時 Wkf.asmx 回 HTTP 500 而無明確過期訊息）。
+        """
+        identity = self._identity_key()
+        if not force_refresh:
+            # 1. memory cache
+            if (
+                self._token
+                and self._identity == identity
+                and time.time() < (self._expires_at - 60)
+            ):
+                return self._token
+            # 2. disk cache
+            creds = self.read_credentials()
+            if creds:
+                self._token = creds["token"]
+                self._expires_at = creds["expires_at"]
+                self._identity = identity
+                return self._token
+        # 3. SOAP GetToken
+        _eprint(
+            f"[auth.token] 🔄 正在以 {os.getenv('UOF_ACCOUNT', '?')} 身份呼叫 GetToken..."
+        )
+        token = self._call_get_token()
+        ttl_env = os.getenv("UOF_TOKEN_TTL")
+        ttl = int(ttl_env) if ttl_env else DEFAULT_TOKEN_TTL
+        self._write_credentials(token, ttl)
+        self._token = token
+        self._expires_at = time.time() + ttl
+        self._identity = identity
+        return token
+
+    def _call_get_token(self) -> str:
+        from ..soap_client import uof_client
+        from ..domains.system.endpoints import AUTH_ENDPOINT
+
+        app_name = os.getenv("UOF_APP_NAME", "")
+        public_key = os.getenv("UOF_RSA_PUBLIC_KEY", "")
+        account = os.getenv("UOF_ACCOUNT", "")
+        password = os.getenv("UOF_PASSWORD", "")
+        if not all([app_name, public_key, account, password]):
+            raise RuntimeError(
+                "UOF_APP_NAME、UOF_RSA_PUBLIC_KEY、UOF_ACCOUNT、UOF_PASSWORD "
+                "必須全部設定。請檢查 .env 檔案。"
+            )
+        encrypted_account = _rsa_encrypt(public_key, account)
+        encrypted_password = _rsa_encrypt(public_key, password)
+        # 登入失敗的回應型態不一致：有時回空 GetTokenResponse（200），有時直接 HTTP 500
+        # （如密碼錯誤導致伺服器端 RSADecrypt 失敗）。兩者都收斂為 RuntimeError，
+        # 讓上層以固定訊息回報，不把原始 500 堆疊丟給介接 AI。
+        try:
+            result = uof_client.call(
+                endpoint_path=AUTH_ENDPOINT,
+                method_name="GetToken",
+                params={
+                    "appName": app_name,
+                    "account": encrypted_account,
+                    "password": encrypted_password,
+                },
+            )
+        except Exception as e:
+            brief = " ".join(str(e).split()).split("For more information")[0].strip()[:160]
+            raise RuntimeError(
+                f"呼叫 GetToken 失敗（帳號「{account}」）：{brief or e.__class__.__name__}。"
+                "可能是帳號或密碼錯誤、RSA 公私鑰不相符，或 UOF 服務暫時無法連線。"
+            )
+        if not result:
+            raise RuntimeError(
+                f"GetToken 未回傳憑證（帳號「{account}」）：可能是帳號或密碼錯誤、密碼已變更、"
+                "帳號被停用，或 RSA 公私鑰不相符。"
+            )
+        return result.strip()
+
+    # ── Disk persistence ─────────────────────────────────────────────
+    def read_credentials(self) -> Optional[dict]:
+        path = self.credentials_file()
+        if not os.path.exists(path):
+            return None
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError) as e:
+            _eprint(f"[auth.token] ❌ 讀取憑證檔失敗: {e}")
+            return None
+        token = data.get("token")
+        expires_at = data.get("expires_at", 0)
+        if not token:
+            return None
+        if data.get("identity") and data.get("identity") != self._identity_key():
+            return None
+        if time.time() >= (expires_at - 60):
+            _eprint(
+                f"[auth.token] ⏰ Token 已過期 "
+                f"(expires_at={expires_at}, now={time.time():.0f})"
+            )
+            return None
+        return data
+
+    def _write_credentials(self, token: str, ttl: int) -> None:
+        _ensure_credentials_dir()
+        path = self.credentials_file()
+        now = time.time()
+        data = {
+            "token": token,
+            "expires_at": now + ttl,
+            "ttl": ttl,
+            "issued_at": now,
+            "account": os.getenv("UOF_ACCOUNT", ""),
+            "app_name": os.getenv("UOF_APP_NAME", ""),
+            "base_url": os.getenv("UOF_BASE_URL", ""),
+            "identity": self._identity_key(),
+        }
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+        os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+        _eprint(f"[auth.token] ✅ 憑證已寫入 {path} (ttl={ttl}s)")

mcp_uof/domains/__init__.py

@@ -0,0 +1,2 @@
+# UOF MCP Server — Domain 模組
+# 依據 DDD 概念，每個 Domain 對應一個 ASMX WebService 的業務邊界

mcp_uof/domains/dms/__init__.py

@@ -0,0 +1,2 @@
+# Domain: DMS — 文件管理 + 檔案服務
+# 暫不實作，待 WKF Domain 驗證通過後再展開