UOF UOF

• 19 exposed tools for UOF workflow operations. preview_workflow and get_external_form_list currently return capability guidance rather than live data.
• MCP server over stdio for local AI clients.
• Tool-first interface: users call the same tools without ever choosing a mechanism — how each tool talks to UOF is an internal, developer-time decision.
• Browser sign-in: uof_custom_login opens the real UOF login page in the user's own browser and captures the session. The local MCP proxy relays the login form to UOF, so the password transits the server process in memory but is never parsed, logged, persisted, written to a config file, or returned to the AI. An unattended username/password fallback stays available for CI.
• Single identity model: one server process represents one UOF identity, and the session persists across restarts.
• httpx web automation: operations use HTTPS requests (httpx + lxml) against UOF's aspx/ashx endpoints, without a browser runtime. On Alpine Linux or musl, ensure binary wheels or native build dependencies are available.

Install

Install from PyPI:

pip install mcp-uof

Or run without installing:

uvx --from mcp-uof mcp-uof

To install and run the current source instead:

git clone https://github.com/asgard-ai-platform/mcp-uof.git
cd mcp-uof
uv sync
cp .env.example .env

Set the connection URL — that is the only required variable:

export UOF_BASE_URL=https://your-uof-domain.com/VirtualPath

Sign in by calling the uof_custom_login tool in your chat: it opens the real UOF login page in your default browser, and the session is handed back to the server once you log in. Credentials are relayed as-is by the local proxy — never parsed, logged, persisted, or returned to the AI, and never written to a config file. See docs/configuration.md for the unattended (username/password) fallback used by CI.

Use with Claude Code

Add the server via the Claude CLI:

claude mcp add --transport stdio uof -- mcp-uof

Or with environment variables inline:

claude mcp add --transport stdio uof \
  -e UOF_BASE_URL=https://your-uof-domain.com/VirtualPath \
  -- mcp-uof

If you clone the repo locally, run it through uv:

claude mcp add --transport stdio uof -- uv --directory /absolute/path/to/mcp-uof run mcp-uof

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "uof": {
      "command": "mcp-uof",
      "env": {
        "UOF_BASE_URL": "https://your-uof-domain.com/VirtualPath"
      }
    }
  }
}

Or with a local checkout:

{
  "mcpServers": {
    "uof": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-uof", "run", "mcp-uof"],
      "env": {
        "UOF_BASE_URL": "https://your-uof-domain.com/VirtualPath"
      }
    }
  }
}

See docs/integration.md and examples/ for more client configuration examples.

This project targets UOF first-generation web flows, driven over httpx.

• Authentication: a Login.aspx cookie session, obtained either through browser sign-in or the credential fallback.
• Base URL: configured with UOF_BASE_URL, for example https://your-uof-domain.com/VirtualPath.
• Required UOF settings: see docs/configuration.md.

All tool names use the uof_custom_ prefix.

Important behavior and constraints:

• get_pending_sign_list returns every form awaiting the current identity's signature (with TaskId/SiteId/NodeSeq), sourced from the Homepage pending-sign widget. query_forms is a different set — the forms you submitted or signed, by date range (query_mode = apply/sign). Ask "what do I need to sign?" → get_pending_sign_list.
• Composite fields (line items, vendor pickers, expense details) live inside dialogs. Use get_dialog_structure to see a dialog field's inner controls, search_dialog_options to look up real picker candidates (never fabricate codes), and pass them into apply_form via the _lookups / _fill_before / _press_after / _rows reserved keys. operate_dialog is a probe only — it cannot accumulate rows.
• sign_next performs approval for the current pending step and can close the flow or route to a designated next signer. It does not accept a signing comment; return, parallel/countersign, and fixed-flow stepping still require the Web UI.
• terminate_task closes a task: Cancel voids an in-flight form (via the web recall page), Adopt/Reject approve/reject through the web sign flow. It checks task status first and blocks repeated closure of an already-closed task.
• preview_workflow (flow simulation) is not available over httpx and directs the user to the Web UI; you can still submit directly with apply_form and inspect the real signing route afterward with get_task_result.
• apply_form always submits as the identity this server process is signed in as (the browser-login user, or the configured UOF_ACCOUNT when the credential fallback is used). Its applicant_account and first_signer_account parameters are currently retained for interface compatibility but do not change the submitted identity or routing.

See docs/tools.md for full tool specs, role model, examples, and operational boundaries.

uv sync
uv run python tests/run.py smoke
uv run python -m compileall src tests

Tests that connect to a real UOF test environment require .env:

uv run python tests/run.py mounted

See CONTRIBUTING.md and docs/testing.md for development and testing guidelines.

MIT

mcp-uof/
├── src/mcp_uof/                 # MCP server, auth (web session), routing, httpx web backend
├── docs/                        # Architecture, configuration, integration, tools, testing
├── examples/                    # Claude Desktop and VS Code MCP config examples
├── tests/                       # smoke / mounted test layers
├── .env.example                 # Environment variable template
├── README.zh-TW.md              # Traditional Chinese README
└── pyproject.toml

本版本提供**電子簽核（WKF）**模組，透過 stdio 連線供 Claude Desktop、VS Code 等 MCP 客戶端使用，涵蓋表單查詢、流程預覽、起單、進度追蹤、簽核與結案。

機制對使用者透明（工具是唯一面向）

對外只有一組固定工具，底層以 httpx + lxml 操作 UOF 網頁端點，不需要瀏覽器 runtime。MCP Server 提供表單清單、欄位解析、通用起單、查詢、簽核與結案；特定表單的填寫 SOP 與業務驗證由部署端私有 skill 組合。詳見 docs/architecture.md。

其他特點：

• 不需瀏覽器 runtime：全部以 httpx + lxml 實作；在 musl/Alpine 環境部署時，仍需確認相依套件有 binary wheel 或備妥原生建置工具。
• 瀏覽器登入：呼叫 uof_custom_login，會在使用者自己的瀏覽器開啟真實的 UOF 登入頁，登入後 session 自動交回 MCP。密碼由本機代理原樣轉送給 UOF，不解析、不記錄、不落地，也不會回傳給 AI，更不必寫進設定檔；session 存到 UOF_SESSION_DIR（預設 ~/.uof），重啟免重登。無人值守情境（CI）仍可用帳密自動登入備援。
• 單一身份模型：一個 Server 程序代表一位 UOF 使用者（見身份模型）。
• 認證失敗訊息分流：「尚未登入」會要求 AI 去開登入頁；「設定錯誤」才要使用者檢查設定。

起單能力範圍

起單由同一個 apply_form 完成，支援通用欄位型別（文字、自動編號、可空欄位、日期、單選/下拉、通用 dataGrid 明細）。實際申請身份固定為本 Server 目前登入的身份；目前工具簽名中的 applicant_account 與 first_signer_account 尚未改變身份或派單路徑，需要指定首站簽核者時請使用 UOF Web UI。本 repo 不內建特定表單的業務 SOP，欄位組合與檢查應由部署端的私有 skill 依表單結構與業務規則決定。

重要：一般網頁起單可填的欄位以 get_form_structure_by_id 回傳者為準；若某欄位漏掉，應先視為解析器待修問題。通用 dataGrid 明細已支援，附件上傳、多站/並簽會簽尚未支援。

所有 Tool 名稱使用 uof_custom_ 前綴。

完整工具規格、人員角色模型、使用情境與能力邊界，請見 docs/tools.md（導入前必讀）。

幾個關鍵邊界先說在前面：

• 待簽清單用 get_pending_sign_list（回「目前輪到本帳號待簽」的單，含 TaskId/SiteId/NodeSeq）；query_forms 則查「自己送出/簽過」的單（依日期，query_mode 選 apply/sign），兩者是不同集合
• 複合欄位（明細、供應商挑選等）藏在對話框裡：用 get_dialog_structure 看內部控制項、search_dialog_options 查真實候選（勿捏造代碼），再經 apply_form 的 _lookups/_rows 等保留鍵帶入；operate_dialog 僅供探測、不能累積明細列
• terminate_task：Cancel 撤單作廢（走網頁表單取回頁）、Adopt/Reject 走網頁簽核流程同意/否決；對已結案的單會被工具層攔截、不重複結案
• preview_workflow（流程模擬）目前不提供 httpx 版，會提示改於網頁操作；可直接 apply_form 起單後用 get_task_result 看實際簽核路徑
• get_external_form_list 目前只回傳能力說明，不會列出後台的「非線上使用」表單

兩層測試法（smoke / mounted），統一入口：

uv run python tests/run.py smoke     # 離線：import 探索、工具→機制綁定（CI 可跑）
uv run python tests/run.py mounted   # 真實掛載 MCP：真 stdio 子程序、多身份（需 .env）
uv run python tests/run.py all       # 兩層依序（缺 .env 時真實層自動 skip）

各層定義與測試紀律見 docs/testing.md。

• 安裝與綁定教學 — Claude Desktop / VS Code Chat 手動綁定、身份切換
• 實際操作對話 — 一段模擬工具呼叫與回應範例
• 表單需具備的系統設定 — 表單要能被 MCP 完整操作的後台前提
• 設定 — 環境變數
• 架構 — Domain 分層、httpx 網頁機制、身份模型
• 實作設計 — 每個工具背後怎麼做、認證、新增工具步驟（持續更新）
• 工具參考 — 17 個工具規格、使用情境、能力邊界
• 測試 — 兩層測試法與測試紀律