mcp-uof 0.1.0__tar.gz

mcp_uof-0.1.0/.env.example

@@ -0,0 +1,63 @@
+# ──────────────────────────────────────────────
+# UOF MCP Server — 環境變數範本
+# 複製本檔案為 .env 並填入實際值
+# 詳細說明見 docs/configuration.md
+# ──────────────────────────────────────────────
+
+# 沒有「模式」要設定：每個工具用哪種機制（SOAP/PublicAPI 或網頁）取得資料，是 server 內部、
+# 開發期決定且對使用者透明的實作細節。你只需填好下列身份與連線設定。
+# 註：清單/搜尋類工具（query_forms）內部以網頁取得（UOF PublicAPI 無此 API），
+#     需先執行一次：uv run playwright install chromium
+# （舊版的 UOF_OPS_MODE / UOF_AUTH_MODE 已不再使用；即使保留也會被忽略，不影響運作。）
+
+# UOF WebService 基礎 URL（必填）
+# 格式：https://your-uof-domain.com/VirtualPath（不含尾斜線）
+# 範例：https://your-uof-host.example.com/UOF
+UOF_BASE_URL=https://your-uof-domain.com
+
+# 外部系統代號（在 UOF「一般組態設定 → 整合服務 → API」設定）
+UOF_APP_NAME=your_app_name
+
+# RSA 公鑰（Base64 編碼，用於加密帳號密碼）
+# 建議以 scripts/generate_no_plus_key.py 產生不含 + 號的 key pair，
+# 避免 UOF Web UI 將 + 存成空白導致 GetToken 解密失敗
+UOF_RSA_PUBLIC_KEY=your_rsa_public_key_base64
+
+# MCP Server 執行時的操作帳號與密碼（明文，程式會自動 RSA 加密後送出）
+UOF_ACCOUNT=your_account
+UOF_PASSWORD=your_password
+
+# SSL 憑證驗證（true = 嚴格驗證；只有本機或自簽憑證測試環境才建議設 false）
+UOF_VERIFY_SSL=true
+
+# SSE Server 啟動設定（預設 127.0.0.1:8001，避免與 UOFX 8000 衝突）
+MCP_SSE_HOST=127.0.0.1
+MCP_SSE_PORT=8001
+
+# ──────────────────────────────────────────────
+# 以下為測試專用（僅 tests/manual/ 使用，正式環境可忽略）
+# 三個測試角色共用 UOF_PASSWORD；測試範圍限定這三個帳號與採購單情境
+# ──────────────────────────────────────────────
+
+# 管理員（強制結案）
+UOF_ACCOUNT_USER1=admin
+# 簽核主管（第一站簽核者；單站流程可透過 terminate_task 在 MCP 簽核）
+UOF_ACCOUNT_USER2=manager_account
+# 申請人（起單、查詢、撤單）
+UOF_ACCOUNT_USER3=applicant_account
+
+# 採購單（WKF 測試唯一允許的表單）
+UOF_TEST_FORM_VERSION_ID=
+UOF_TEST_FORM_ID=
+
+# 需改走網頁起單的採購單表單識別碼（逗號分隔，可放 formId 與 recentVersionId）
+# 留空時不啟用採購單 web_apply 靜態分派；工具仍可由 runtime 反查支援已設定的表單。
+UOF_WEB_APPLY_PURCHASE_ORDER_IDS=
+UOF_WEB_APPLY_PURCHASE_ORDER_NAME=採購單
+
+# 測試用 DMS 資料夾 ID（dms domain 實作後使用；DMSRoot 為文管根目錄）
+UOF_TEST_FOLDER_ID=DMSRoot
+
+# SSE 本機驗證用 Bearer Token 與模擬使用者
+MCP_SSE_TEST_TOKEN=your_local_test_token
+MCP_SSE_TEST_USER=test_user

mcp_uof-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,77 @@
+name: Bug Report
+description: Report a reproducible problem with the MCP server.
+title: "bug: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Do not include accounts, passwords, RSA keys, tokens, or private UOF data.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What went wrong?
+      placeholder: Describe the observed behavior and why it is a problem.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps To Reproduce
+      description: Provide the smallest set of steps that reproduces the issue.
+      placeholder: |
+        1. Configure ...
+        2. Run ...
+        3. Call tool ...
+        4. Observe ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What happened instead? Include sanitized logs if helpful.
+    validations:
+      required: true
+  - type: dropdown
+    id: mode
+    attributes:
+      label: Runtime Mode
+      options:
+        - stdio
+        - SSE
+        - manual test script
+        - other
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version Or Commit
+      description: Package version, git commit, or branch name.
+      placeholder: v0.1.0 or main@abcdef0
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, uv version, and relevant sanitized configuration.
+      placeholder: |
+        OS: macOS 15
+        Python: 3.12.x
+        uv: 0.x.x
+        UOF_VERIFY_SSL: true
+    validations:
+      required: true
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other sanitized context that may help diagnose the issue.

mcp_uof-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security Vulnerability
+    url: https://github.com/asgard-ai-platform/mcp-uof/security/policy
+    about: Please report security issues privately using the security policy.

mcp_uof-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,53 @@
+name: Feature Request
+description: Suggest an improvement or new capability.
+title: "feat: "
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement. Do not include private UOF data, credentials, or customer-specific details.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user or integration problem should this solve?
+      placeholder: Describe the current limitation or workflow pain point.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Solution
+      description: What should change?
+      placeholder: Describe the behavior, tool, configuration, or documentation change you want.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Workflow (WKF) tools
+        - Document management (DMS) tools
+        - EIP tools
+        - UChat tools
+        - System tools
+        - Ops routing (SOAP / web)
+        - Authentication
+        - SSE transport
+        - Documentation
+        - Packaging
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Are there existing workarounds or alternative designs?
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any sanitized examples, links, or constraints that help explain the request.

mcp_uof-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.pull_request.author_association)
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run smoke tests
+        run: uv run python tests/run.py smoke
+
+      - name: Compile Python files
+        run: uv run python -m compileall src tests
+
+      - name: Build package
+        run: uv build

mcp_uof-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

mcp_uof-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Environment & Secrets
+.env
+*.pem
+*.key
+
+# WSDL 快照含真實主機名，不入庫；需要時以 scripts/fetch_all_wsdls.py 重新抓取
+references/wsdl/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual Environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+.claude/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# uv
+.python-version
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Credentials
+.uof/

mcp_uof-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+感謝對 `mcp-uof` 的貢獻。本專案是 UOF（一代）平台的 MCP Server，以 Python 撰寫，採用 DDD（Domain-Driven Design）概念依業務邊界分層。
+
+## 開發環境
+
+需求：Python 3.10+、[uv](https://docs.astral.sh/uv/)
+
+```bash
+uv sync
+cp .env.example .env
+```
+
+請在 `.env` 填入實際連線設定與測試帳號。`.env`、憑證、Token、真實主機名稱與本機快取不得提交。
+
+## 執行
+
+```bash
+uv run mcp-uof
+uv run mcp-uof-sse
+```
+
+## 測試
+
+```bash
+uv run python tests/run.py smoke
+uv run python -m compileall src tests
+uv run python tests/run.py e2e
+uv run python tests/run.py mounted
+```
+
+測試原則：
+
+- `smoke` 為離線測試，應可在 CI 執行。
+- `e2e` 與 `mounted` 需要真實測試環境與 `.env`。
+- 真實層測試只使用 `.env` 中設定的測試帳號。
+- WKF 實測以採購單情境為主；其他表單需後台流程設定，API 無法保證完整覆蓋。
+
+## 架構原則
+
+- 對外只暴露 MCP tools，使用者不選擇 SOAP 或 web 模式。
+- 工具底層實作由 `src/mcp_uof/ops/router.py` 的 binding 決定。
+- SOAP 能完成的操作優先使用 SOAP/PublicAPI；PublicAPI 無法支援的能力才使用 web/Playwright 補足。
+- 所有異動必須經過 UOF 既有 API 或 UI 流程，不得提供直接修改資料庫的能力。
+
+## 程式慣例
+
+- 使用 Python 3.10+ type hints。
+- 依賴管理使用 `uv`，不要直接以 `pip` 修改專案依賴。
+- MCP tool 名稱使用全小寫 snake_case，並加上 `uof_custom_` 前綴。
+- 不做 API 的 1:1 包裝；tool 應提供清楚的業務語意。
+- SOAP 呼叫使用 `lxml + httpx` 輕量封裝，不使用 `zeep`。
+
+## 文件
+
+主要文件位於 `docs/`：
+
+- `docs/architecture.md`：架構與身份模型
+- `docs/configuration.md`：環境變數與 RSA 設定
+- `docs/design.md`：工具設計與新增工具流程
+- `docs/tools.md`：工具規格與能力邊界
+- `docs/testing.md`：三層測試法
+- `docs/form-requirements.md`：表單可被 MCP 操作的後台前提

mcp_uof-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asgard AI Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_uof-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: mcp-uof
+Version: 0.1.0
+Summary: MCP server wrapping UOF SOAP/ASMX services into AI Agent-callable workflow tools
+Project-URL: Homepage, https://github.com/asgard-ai-platform/mcp-uof
+Project-URL: Repository, https://github.com/asgard-ai-platform/mcp-uof
+Project-URL: Issues, https://github.com/asgard-ai-platform/mcp-uof/issues
+Author: Asgard AI Platform
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,claude,mcp,soap,uof,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.136.3
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: pycryptodome>=3.20.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: sse-starlette>=3.4.4
+Requires-Dist: uvicorn>=0.48.0
+Description-Content-Type: text/markdown
+
+# MCP UOF
+
+[![PyPI version](https://img.shields.io/pypi/v/mcp-uof.svg)](https://pypi.org/project/mcp-uof/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mcp-uof.svg)](https://pypi.org/project/mcp-uof/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/asgard-ai-platform/mcp-uof.svg)](https://github.com/asgard-ai-platform/mcp-uof/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/asgard-ai-platform/mcp-uof.svg)](https://github.com/asgard-ai-platform/mcp-uof/issues)
+[![GitHub last commit](https://img.shields.io/github/last-commit/asgard-ai-platform/mcp-uof.svg)](https://github.com/asgard-ai-platform/mcp-uof/commits/main)
+[![MCP compatible](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io/)
+
+[繁體中文](README.zh-TW.md)
+
+An open-source [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that wraps UOF (U-Office Force) SOAP/ASMX services into AI-callable tools for workflow 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, and close workflow tasks through natural language.
+
+## What This Does
+
+- **12 ready-to-use tools** for UOF workflow operations, including authentication checks, form discovery, schema lookup, workflow preview, form submission, task status, task result, and task closure.
+- **MCP server** over stdio for local AI clients, plus an optional SSE server for HTTP integrations.
+- **Tool-first interface**: users call the same tools regardless of whether the implementation uses SOAP/PublicAPI or browser automation internally.
+- **Single identity model**: one server process represents one UOF account configured through environment variables.
+- **SOAP and web support**: SOAP is used where PublicAPI supports the operation; Playwright-backed web automation fills gaps such as form listing and selected custom form submission flows.
+
+## API Reference
+
+This project targets UOF first-generation SOAP/ASMX services and selected web flows.
+
+- Authentication: UOF account/password encrypted with the configured RSA public key for SOAP token access; web flows reuse a browser session.
+- Base URL: configured with `UOF_BASE_URL`, for example `https://your-uof-domain.com/VirtualPath`.
+- Required UOF settings: see [docs/configuration.md](docs/configuration.md).
+
+## Quick Start
+
+### Install
+
+```bash
+pip install mcp-uof
+```
+
+Or use uvx:
+
+```bash
+uvx --from mcp-uof mcp-uof
+```
+
+For local development from source:
+
+```bash
+git clone https://github.com/asgard-ai-platform/mcp-uof.git
+cd mcp-uof
+uv sync
+cp .env.example .env
+uv run playwright install chromium
+```
+
+Set the required environment variables:
+
+```bash
+export UOF_BASE_URL=https://your-uof-domain.com/VirtualPath
+export UOF_APP_NAME=your_app_name
+export UOF_RSA_PUBLIC_KEY=your_rsa_public_key_base64
+export UOF_ACCOUNT=your_account
+export UOF_PASSWORD=your_password
+```
+
+### Use with Claude Code
+
+Add the server via the Claude CLI:
+
+```bash
+claude mcp add --transport stdio uof -- mcp-uof
+```
+
+Or with environment variables inline:
+
+```bash
+claude mcp add --transport stdio uof \
+  -e UOF_BASE_URL=https://your-uof-domain.com/VirtualPath \
+  -e UOF_APP_NAME=your_app_name \
+  -e UOF_RSA_PUBLIC_KEY=your_rsa_public_key_base64 \
+  -e UOF_ACCOUNT=your_account \
+  -e UOF_PASSWORD=your_password \
+  -- mcp-uof
+```
+
+If you clone the repo locally, run it through `uv`:
+
+```bash
+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`:
+
+```json
+{
+  "mcpServers": {
+    "uof": {
+      "command": "mcp-uof",
+      "env": {
+        "UOF_BASE_URL": "https://your-uof-domain.com/VirtualPath",
+        "UOF_APP_NAME": "your_app_name",
+        "UOF_RSA_PUBLIC_KEY": "your_rsa_public_key_base64",
+        "UOF_ACCOUNT": "your_account",
+        "UOF_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+Or with a local checkout:
+
+```json
+{
+  "mcpServers": {
+    "uof": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/mcp-uof", "run", "mcp-uof"],
+      "env": {
+        "UOF_BASE_URL": "https://your-uof-domain.com/VirtualPath",
+        "UOF_APP_NAME": "your_app_name",
+        "UOF_RSA_PUBLIC_KEY": "your_rsa_public_key_base64",
+        "UOF_ACCOUNT": "your_account",
+        "UOF_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+See [docs/integration.md](docs/integration.md) and [examples/](examples/) for more client configuration examples.
+
+## Tools (12)
+
+All tool names use the `uof_custom_` prefix.
+
+| Domain | Tools |
+|--------|-------|
+| System | `check_auth` |
+| WKF Workflow | `get_form_list`, `get_external_form_list`, `query_forms`, `get_form_structure`, `get_form_structure_by_id`, `preview_workflow`, `apply_form`, `get_task_data`, `get_task_result`, `terminate_task`, `sign_next` |
+
+Important behavior and constraints:
+
+- UOF first-generation PublicAPI does not provide an inbox or pending-task list API. Users must provide a TaskId from the UOF UI or notification email.
+- UOF does not provide a general per-step approval API. Single-step free-flow approvals can be represented through `terminate_task` with `Adopt` or `Reject` when used by the current signer.
+- `terminate_task` can overwrite already-closed results at the API layer; this server checks task status first and blocks repeated closure.
+- Some form submissions use web automation when SOAP intermediary fields cannot represent the full form body.
+
+See [docs/tools.md](docs/tools.md) for full tool specs, role model, examples, and operational boundaries.
+
+## Project Structure
+
+```text
+mcp-uof/
+├── src/mcp_uof/                 # MCP server, auth, routing, SOAP/web backends
+├── docs/                        # Architecture, configuration, integration, tools, testing
+├── examples/                    # Claude Desktop and VS Code MCP config examples
+├── scripts/                     # RSA key and WSDL helper scripts
+├── tests/                       # smoke / e2e / mounted test layers
+├── .env.example                 # Environment variable template
+├── README.zh-TW.md              # Traditional Chinese README
+└── pyproject.toml
+```
+
+## Development
+
+```bash
+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`:
+
+```bash
+uv run python tests/run.py e2e
+uv run python tests/run.py mounted
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/testing.md](docs/testing.md) for development and testing guidelines.
+
+## License
+
+MIT