mcp-uof 0.4.1

MCP server turning UOF workflow operations into AI Agent-callable tools via httpx web automation

MCP UOF

繁體中文

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.

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