Skip to main content
Glama

MCP UOF

PyPI version Python versions License GitHub stars GitHub issues GitHub last commit MCP compatible

繁體中文

An open-source MCP (Model Context Protocol) server that turns UOF (U-Office Force) workflow operations into AI-callable tools, driven entirely through httpx web automation.

Built for Claude Code, Claude Desktop, VS Code, and any MCP-compatible client. It lets AI agents query workflow forms, inspect form schemas, submit forms, track workflow progress, sign off, and close workflow tasks through natural language.

What This Does

  • 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.

Related MCP server: mcp2ws

API Reference

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.

Quick Start

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.

Tools (19)

All tool names use the uof_custom_ prefix.

Domain

Tools

System

check_auth, login, logout

WKF Workflow

get_form_list, get_external_form_list, query_forms, get_pending_sign_list, search_users, get_form_structure, get_form_structure_by_id, get_dialog_structure, search_dialog_options, operate_dialog, preview_workflow, apply_form, get_task_data, get_task_result, sign_next, terminate_task

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.

Project Structure

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

Development

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.

License

MIT

Available Tools

13 tools
uof_custom_apply_formA

正式起單,成功回傳 TaskId(後續查詢與結案都要用到,務必保存)。

何時使用:已用 get_form_structure_by_id 確認這張表單要帶哪些欄位後,要正式送出時。 呼叫端只要挑表單、填內容即可——這張表單背後怎麼起(系統內部用哪種方式)不需要你管。

限制:起單不會驗證網頁必填欄位,缺欄位仍可能起單成功但內容不完整;附檔、多站/並簽會簽尚未支援。

Inputs: fields (required), form_version_id (required), applicant_account (required), first_signer_account (required), +2 more. Returns: result

uof_custom_check_authA

確認目前以哪個 UOF 帳號身份操作,並檢查 Token / Session 是否有效。

何時使用:對話開始時、或任何工具回報認證錯誤時,用來確認身份與連線。 每個 Server 程序只代表一個固定帳號(由設定綁定)。

Inputs: no named parameters. Returns: result

uof_custom_get_external_form_listA

列出被標記為「非線上使用」的表單。

何時使用:少數需要查詢非線上表單的情況。注意:此清單不等於可外部起單的表單 (採購單就不在其中卻能起單)。要判斷能否起單,請改看 get_form_list 的 recentVersionId。

Inputs: no named parameters. Returns: result

uof_custom_get_form_listA

列出所有表單類別與表單,含 formId 與表單版本代號(recentVersionId)。

何時使用:使用者問「系統有哪些表單」,或要起單但還不知道目標表單的 formId / formVersionId 時。這是起單流程的第一步。有 recentVersionId 的表單才可外部起單。

Inputs: no named parameters. Returns: result

uof_custom_get_form_structureA

以表單版本代號取得欄位結構(只有 fieldId 與名稱,無型別)。

何時使用:手上只有 formVersionId 時。一般建議改用 get_form_structure_by_id(資訊較完整)。

Inputs: form_version_id (required). Returns: result

uof_custom_get_form_structure_by_idA

以表單代號取得欄位結構,含每個欄位的型別與填寫方式,並附上起單提示。

何時使用:要起單前,先用本工具查清楚這張表單要填哪些欄位、怎麼填。 建議優先用本工具(比 get_form_structure 多回 fieldType 與填寫指引)。 注意:回傳的是表單對外開放的「中介欄位」,可能少於 UOF 網頁上的完整表單。

Inputs: form_id (required). Returns: result

uof_custom_get_task_dataA

查詢一張單的摘要:申請者、目前結果(簽核中/同意/否決/作廢)、結案日期。

何時使用:想快速知道某張單目前的狀態時。需要逐站簽核歷程請改用 get_task_result。 系統沒有待簽清單 API,TaskId 必須由使用者提供。

Inputs: task_id (required). Returns: result

uof_custom_get_task_resultA

查詢一張單的逐站簽核歷程(每一站的簽核者、結果、意見、時間)。

何時使用:想看簽核走到哪一站、誰簽了什麼意見時。站點顯示「待簽」代表表單停在該站。 只要摘要狀態用 get_task_data 即可。

Inputs: task_id (required), include_form_data. Returns: result

uof_custom_preview_workflowA

模擬簽核流程走向,不會真的起單。參數與 apply_form 完全相同。

何時使用:呼叫 apply_form 正式起單之前,用相同參數先驗證流程與簽核路徑是否正確。 註:網頁起單的表單(如採購單)改以「試填到送出前」的填寫驗證代替(其簽核路徑於送出時的確認視窗呈現)。

Inputs: form_version_id (required), applicant_account (required), first_signer_account (required), fields, +2 more. Returns: result

uof_custom_query_formsA

搜尋 UOF 表單(依日期範圍 + 關鍵字),回傳含 TaskId 的清單。

何時使用:使用者沒有 TaskId、但想列出自己最近的單或搜尋特定關鍵字時。 本工具是補上「UOF 一代沒有待簽清單 API」這個缺口最直接的入口; 取得 TaskId 後可丟給 get_task_data / get_task_result 看單張詳情。

限制:

  • 範圍是「目前帳號可看到的單」,等同於使用者在 UOF 網頁「查詢表單」頁所看到的範圍。

  • 只取第一頁結果;極端情況需要更精確過濾請縮日期範圍或加關鍵字。

Inputs: date_to, keyword, date_from, max_results. Returns: result

uof_custom_search_usersA

依姓名或帳號關鍵字查詢 UOF 人員,回傳姓名、帳號與 UserGuid。

何時使用:需要指定 apply_form 的 first_signer_account(第一簽核者帳號)時, 先用本工具確認對方在 UOF 的正確帳號,避免帳號輸錯導致起單失敗。

限制:回傳範圍為目前帳號可看到的 UOF 人員(同 ChoiceCenter 選人清單)。

Inputs: keyword (required). Returns: result

uof_custom_sign_nextA

將固定流程的表單推進到下一站並指定簽核者。

何時使用:僅適用於後台設計好的固定流程表單。 自由流程(如採購單)不支援本工具;要在自由流程上同意/否決請改用 terminate_task。 site_id/node_seq/signer_guid 無法由查詢 API 取得,需由表單流程設計提供。

Inputs: site_id (required), task_id (required), node_seq (required), signer_guid (required). Returns: result

uof_custom_terminate_taskA

結案一張單。可作為申請人撤單(Cancel)、或主管/管理員核准否決(Adopt/Reject)。

何時使用:

  • 申請人要撤回自己的單 → result=Cancel

  • 主管要同意/否決停在自己這站的單 → result=Adopt/Reject(單站自由流程中等同簽核)

  • 管理員要強制結案卡住的單 → 任一動作 操作者固定為本 Server 綁定的身份(UOF_ACCOUNT),不由呼叫端指定。 注意:這是「整張單終結」,多站流程會跳過後續站點;對已結案的單會被擋下。

Inputs: reason (required), result (required), task_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose. Overlaps like get_form_structure vs get_form_structure_by_id are clarified by descriptions, and get_task_data vs get_task_result serve different detail levels. No ambiguity.

    Naming Consistency5/5

    All tools follow a consistent pattern: 'uof_custom_' prefix + verb_noun in snake_case (e.g., apply_form, check_auth, sign_next). The naming is uniform and predictable.

    Tool Count5/5

    13 tools cover the necessary operations for a form/approval system without being excessive. Each tool serves a logical need in the workflow, from listing forms to applying, querying, and managing tasks.

    Completeness4/5

    The tool set covers core form lifecycle (list, get structure, apply, preview, query, task details, termination). Minor gaps exist: no pending task list API (acknowledged limitation) and no file attachment support, but the essential operations are present.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Wraps IBM Maximo API services as MCP tools, enabling AI applications like Dify Agent to manage assets, work orders, and inventory through natural language interactions with enterprise asset management systems.
      -
    • A
      license
      C
      quality
      D
      maintenance
      Exposes SOAP-based web services as MCP servers by parsing WSDL files. Enables AI assistants to interact with legacy SOAP/WS-\* web services through the Model Context Protocol.
      21
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes SOAP web services as Model Context Protocol (MCP) servers, allowing AI models to interact with legacy SOAP services through automatic method discovery and type mapping.
      MIT