Skip to content

Commit c3207c3

Browse files
JE-ChenJE-Chen
committed
Document WebDAV, SMB, fsspec, HTTP observability, Web UI, MCP in READMEs
Add feature bullets and usage sections for the six capabilities shipped in the recent feature series. Covers English, Traditional Chinese, and Simplified Chinese variants. Also adds the automation_file_mcp console script and python -m automation_file mcp subcommand to the CLI reference block.
1 parent c4d3ff3 commit c3207c3

3 files changed

Lines changed: 231 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,12 @@ facade.
4242
- **HTTPActionClient SDK** — typed Python client for the HTTP action server with shared-secret auth, loopback guard, and OPTIONS-based ping
4343
- **AES-256-GCM file encryption** — `encrypt_file` / `decrypt_file` with `generate_key()` / `key_from_password()` (PBKDF2-HMAC-SHA256); JSON actions `FA_encrypt_file` / `FA_decrypt_file`
4444
- **Prometheus metrics exporter** — `start_metrics_server()` exposes `automation_file_actions_total{action,status}` counters and `automation_file_action_duration_seconds{action}` histograms
45+
- **WebDAV backend** — `WebDAVClient` with `exists` / `upload` / `download` / `delete` / `mkcol` / `list_dir` on any RFC 4918 server; rejects private / loopback targets unless `allow_private_hosts=True`
46+
- **SMB / CIFS backend** — `SMBClient` over `smbprotocol`'s high-level `smbclient` API; UNC-based, encrypted sessions by default
47+
- **fsspec bridge** — drive any `fsspec`-backed filesystem (memory, local, s3, gcs, abfs, …) through the action registry with `get_fs` / `fsspec_upload` / `fsspec_download` / `fsspec_list_dir` etc.
48+
- **HTTP server observability** — `GET /healthz` / `GET /readyz` probes, `GET /openapi.json` spec, and `GET /progress` WebSocket stream of live transfer snapshots
49+
- **HTMX Web UI** — `start_web_ui()` serves a read-only dashboard (health, progress, registry) that polls HTML fragments; stdlib-only HTTP plus one CDN script with SRI
50+
- **MCP (Model Context Protocol) server** — `MCPServer` bridges the registry to any MCP host (Claude Desktop, MCP CLIs) over newline-delimited JSON-RPC 2.0 on stdio; every `FA_*` action becomes an MCP tool with an auto-generated input schema
4551
- PySide6 GUI (`python -m automation_file ui`) with a tab per backend, the JSON-action runner, and dedicated tabs for Triggers, Scheduler, and live Progress
4652
- Rich CLI with one-shot subcommands plus legacy JSON-batch flags
4753
- Project scaffolding (`ProjectBuilder`) for executor-based automations
@@ -624,6 +630,77 @@ Exports `automation_file_actions_total{action,status}` and
624630
`automation_file_action_duration_seconds{action}`. Non-loopback binds
625631
require `allow_non_loopback=True` explicitly.
626632

633+
### WebDAV, SMB/CIFS, fsspec
634+
Extra remote backends alongside the first-class S3 / Azure / Dropbox / SFTP:
635+
636+
```python
637+
from automation_file import WebDAVClient, SMBClient, fsspec_upload
638+
639+
# RFC 4918 WebDAV — loopback/private targets require opt-in.
640+
dav = WebDAVClient("https://files.example.com/remote.php/dav",
641+
username="alice", password="s3cr3t")
642+
dav.upload("/local/report.csv", "team/reports/report.csv")
643+
644+
# SMB / CIFS via smbprotocol's high-level smbclient API.
645+
with SMBClient("fileserver", "share", "alice", "s3cr3t") as smb:
646+
smb.upload("/local/report.csv", "reports/report.csv")
647+
648+
# Anything fsspec can address — memory, gcs, abfs, local, …
649+
fsspec_upload("/local/report.csv", "memory://reports/report.csv")
650+
```
651+
652+
### HTTP server observability
653+
`start_http_action_server()` additionally exposes liveness / readiness probes,
654+
an OpenAPI 3.0 spec, and a WebSocket stream of progress snapshots:
655+
656+
```bash
657+
curl http://127.0.0.1:9944/healthz # {"status": "ok"}
658+
curl http://127.0.0.1:9944/readyz # 200 when registry non-empty, 503 otherwise
659+
curl http://127.0.0.1:9944/openapi.json # OpenAPI 3.0 spec
660+
# Connect a WebSocket to ws://127.0.0.1:9944/progress for live progress frames.
661+
```
662+
663+
### HTMX Web UI
664+
A read-only observability dashboard built on stdlib HTTP + HTMX (loaded from
665+
a pinned CDN URL with SRI). Loopback-only by default; optional shared secret:
666+
667+
```python
668+
from automation_file import start_web_ui
669+
670+
server = start_web_ui(host="127.0.0.1", port=9955, shared_secret="s3cr3t")
671+
# Browse http://127.0.0.1:9955/ — health, progress, and registry fragments
672+
# auto-poll every few seconds. Write operations stay on the action servers.
673+
```
674+
675+
### MCP (Model Context Protocol) server
676+
Expose every registered `FA_*` action to an MCP host (Claude Desktop, MCP
677+
CLIs) over JSON-RPC 2.0 on stdio:
678+
679+
```python
680+
from automation_file import MCPServer
681+
682+
MCPServer().serve_stdio() # reads JSON-RPC from stdin, writes to stdout
683+
```
684+
685+
`pip install` exposes an `automation_file_mcp` console script (via
686+
`[project.scripts]`) so MCP hosts can launch the bridge without any Python
687+
glue. Three equivalent launch styles:
688+
689+
```bash
690+
automation_file_mcp # installed console script
691+
python -m automation_file mcp # CLI subcommand
692+
python examples/mcp/run_mcp.py # standalone launcher
693+
```
694+
695+
All three accept `--name`, `--version`, and `--allowed-actions` (comma-
696+
separated whitelist — strongly recommended since the default registry
697+
includes high-privilege actions like `FA_run_shell`). See
698+
[`examples/mcp/`](examples/mcp) for ready-to-copy Claude Desktop config.
699+
700+
Tool descriptors are generated on the fly by introspecting each action's
701+
signature — parameter names and types become a JSON schema, so hosts can
702+
render fields without any manual wiring.
703+
627704
### DAG action executor
628705
Run actions in dependency order; independent branches fan out across a
629706
thread pool. Each node is `{"id": ..., "action": [...], "depends_on":
@@ -709,6 +786,8 @@ python -m automation_file create-file hello.txt --content "hi"
709786
python -m automation_file server --host 127.0.0.1 --port 9943
710787
python -m automation_file http-server --host 127.0.0.1 --port 9944
711788
python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
789+
python -m automation_file mcp --allowed-actions FA_file_checksum,FA_fast_find
790+
automation_file_mcp --allowed-actions FA_file_checksum,FA_fast_find # installed console script
712791

713792
# Legacy flags (JSON action lists)
714793
python -m automation_file --execute_file actions.json

‎README.zh-CN.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,12 @@ TCP / HTTP 服务器执行的 JSON 驱动动作。内附 PySide6 GUI，每个功
4040
- **HTTPActionClient SDK** — HTTP 动作服务器的类型化 Python 客户端,具 shared-secret 认证、loopback 守护与 OPTIONS ping
4141
- **AES-256-GCM 文件加密** — `encrypt_file` / `decrypt_file` 搭配 `generate_key()` / `key_from_password()`(PBKDF2-HMAC-SHA256);JSON 动作 `FA_encrypt_file` / `FA_decrypt_file`
4242
- **Prometheus metrics 导出器** — `start_metrics_server()` 提供 `automation_file_actions_total{action,status}` 计数器与 `automation_file_action_duration_seconds{action}` 直方图
43+
- **WebDAV 后端** — `WebDAVClient` 提供 `exists` / `upload` / `download` / `delete` / `mkcol` / `list_dir`，适用于任何 RFC 4918 服务器；除非显式传入 `allow_private_hosts=True`，否则拒绝私有 / loopback 目标
44+
- **SMB / CIFS 后端** — `SMBClient` 基于 `smbprotocol` 的高阶 `smbclient` API；采用 UNC 路径，默认启用加密会话
45+
- **fsspec 桥接** — 通过 `get_fs` / `fsspec_upload` / `fsspec_download` / `fsspec_list_dir` 等函数，驱动任何 `fsspec` 支持的文件系统（memory、local、s3、gcs、abfs、…）
46+
- **HTTP 服务器观测端点** — `GET /healthz` / `GET /readyz` 探针、`GET /openapi.json` 规格，以及 `GET /progress`（通过 WebSocket 推送实时传输快照）
47+
- **HTMX Web UI** — `start_web_ui()` 启动只读观测仪表板（health、progress、registry），通过 HTML 片段轮询；仅用标准库 HTTP，搭配一个带 SRI 的 CDN 脚本
48+
- **MCP（Model Context Protocol）服务器** — `MCPServer` 通过 stdio 上的 JSON-RPC 2.0（换行分隔 JSON）将注册表桥接到任意 MCP 主机（Claude Desktop、MCP CLI）；每个 `FA_*` 动作都会自动生成输入 schema 并成为 MCP 工具
4349
- PySide6 GUI（`python -m automation_file ui`）每个后端一个页签，含 JSON 动作执行器，另有 Triggers、Scheduler、实时 Progress 专属页签
4450
- 功能丰富的 CLI，包含一次性子命令与旧式 JSON 批量标志
4551
- 项目脚手架（`ProjectBuilder`）协助构建以 executor 为核心的自动化项目
@@ -611,6 +617,74 @@ server = start_metrics_server(host="127.0.0.1", port=9945)
611617
`automation_file_action_duration_seconds{action}`。若要绑定非 loopback
612618
地址必须显式传入 `allow_non_loopback=True`。
613619

620+
### WebDAV、SMB/CIFS、fsspec
621+
在一等公民的 S3 / Azure / Dropbox / SFTP 之外，额外的远程后端：
622+
623+
```python
624+
from automation_file import WebDAVClient, SMBClient, fsspec_upload
625+
626+
# RFC 4918 WebDAV —— loopback / 私有目标需要显式开关。
627+
dav = WebDAVClient("https://files.example.com/remote.php/dav",
628+
username="alice", password="s3cr3t")
629+
dav.upload("/local/report.csv", "team/reports/report.csv")
630+
631+
# 通过 smbprotocol 的高阶 smbclient API 操作 SMB / CIFS。
632+
with SMBClient("fileserver", "share", "alice", "s3cr3t") as smb:
633+
smb.upload("/local/report.csv", "reports/report.csv")
634+
635+
# 任何 fsspec 能寻址的目标 —— memory、gcs、abfs、local、…
636+
fsspec_upload("/local/report.csv", "memory://reports/report.csv")
637+
```
638+
639+
### HTTP 服务器观测端点
640+
`start_http_action_server()` 额外提供 liveness / readiness 探针、OpenAPI 3.0
641+
规格，以及实时进度快照的 WebSocket 流：
642+
643+
```bash
644+
curl http://127.0.0.1:9944/healthz # {"status": "ok"}
645+
curl http://127.0.0.1:9944/readyz # 注册表非空时 200，否则 503
646+
curl http://127.0.0.1:9944/openapi.json # OpenAPI 3.0 规格
647+
# 使用 WebSocket 连接 ws://127.0.0.1:9944/progress 获取实时进度帧。
648+
```
649+
650+
### HTMX Web UI
651+
基于标准库 HTTP + HTMX（以带 SRI 的固定 CDN URL 加载）构建的只读观测仪表板。
652+
默认仅允许 loopback，可选 shared-secret：
653+
654+
```python
655+
from automation_file import start_web_ui
656+
657+
server = start_web_ui(host="127.0.0.1", port=9955, shared_secret="s3cr3t")
658+
# 浏览 http://127.0.0.1:9955/ —— health、progress、registry 片段每几秒
659+
# 自动轮询一次；写入操作仍然保留在动作服务器。
660+
```
661+
662+
### MCP（Model Context Protocol）服务器
663+
通过 stdio 上的 JSON-RPC 2.0 把每个已注册的 `FA_*` 动作暴露给 MCP 主机
664+
（Claude Desktop、MCP CLI）：
665+
666+
```python
667+
from automation_file import MCPServer
668+
669+
MCPServer().serve_stdio() # 从 stdin 读取 JSON-RPC，写入 stdout
670+
```
671+
672+
`pip install` 后，`[project.scripts]` 会提供 `automation_file_mcp` console
673+
script，MCP 主机无需编写 Python glue 即可启动桥接器。三种等价的启动方式：
674+
675+
```bash
676+
automation_file_mcp # 已安装的 console script
677+
python -m automation_file mcp # CLI 子命令
678+
python examples/mcp/run_mcp.py # 独立启动脚本
679+
```
680+
681+
三者都支持 `--name`、`--version`、`--allowed-actions`（逗号分隔白名单——
682+
强烈建议使用，因为默认注册表包含 `FA_run_shell` 等高权限动作）。可直接复制的
683+
Claude Desktop 示例配置请见 [`examples/mcp/`](examples/mcp)。
684+
685+
工具描述符在运行时由动作签名自动生成——参数名称与类型会转换为 JSON schema，
686+
主机无需任何手动配置即可渲染字段。
687+
614688
### DAG 动作执行器
615689
按依赖顺序执行动作；独立分支通过线程池并行展开。每个节点的形式为
616690
`{"id": ..., "action": [...], "depends_on": [...]}`：
@@ -693,6 +767,8 @@ python -m automation_file create-file hello.txt --content "hi"
693767
python -m automation_file server --host 127.0.0.1 --port 9943
694768
python -m automation_file http-server --host 127.0.0.1 --port 9944
695769
python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
770+
python -m automation_file mcp --allowed-actions FA_file_checksum,FA_fast_find
771+
automation_file_mcp --allowed-actions FA_file_checksum,FA_fast_find # 已安装的 console script
696772

697773
# 旧式标志（JSON 动作清单）
698774
python -m automation_file --execute_file actions.json

‎README.zh-TW.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,12 @@ TCP / HTTP 伺服器執行的 JSON 驅動動作。內附 PySide6 GUI，每個功
4040
- **HTTPActionClient SDK** — HTTP 動作伺服器的型別化 Python 客戶端，具 shared-secret 驗證、loopback 防護與 OPTIONS ping
4141
- **AES-256-GCM 檔案加密** — `encrypt_file` / `decrypt_file` 搭配 `generate_key()` / `key_from_password()`（PBKDF2-HMAC-SHA256）；JSON 動作 `FA_encrypt_file` / `FA_decrypt_file`
4242
- **Prometheus metrics 匯出器** — `start_metrics_server()` 提供 `automation_file_actions_total{action,status}` 計數器與 `automation_file_action_duration_seconds{action}` 直方圖
43+
- **WebDAV 後端** — `WebDAVClient` 提供 `exists` / `upload` / `download` / `delete` / `mkcol` / `list_dir`，適用於任何 RFC 4918 伺服器；除非顯式傳入 `allow_private_hosts=True`，否則拒絕私有 / loopback 目標
44+
- **SMB / CIFS 後端** — `SMBClient` 建構於 `smbprotocol` 的高階 `smbclient` API；採用 UNC 路徑，預設啟用加密連線
45+
- **fsspec 橋接** — 透過 `get_fs` / `fsspec_upload` / `fsspec_download` / `fsspec_list_dir` 等函式，驅動任何 `fsspec` 支援的檔案系統（memory、local、s3、gcs、abfs、…）
46+
- **HTTP 伺服器觀測端點** — `GET /healthz` / `GET /readyz` 探針、`GET /openapi.json` 規格、以及 `GET /progress`（以 WebSocket 推送即時傳輸快照）
47+
- **HTMX Web UI** — `start_web_ui()` 啟動唯讀觀測儀表板（health、progress、registry），以 HTML 片段輪詢；僅用標準函式庫 HTTP，搭配一支帶 SRI 的 CDN 腳本
48+
- **MCP（Model Context Protocol）伺服器** — `MCPServer` 透過 stdio 上的 JSON-RPC 2.0（行分隔 JSON）將登錄表橋接到任何 MCP 主機（Claude Desktop、MCP CLI）；每個 `FA_*` 動作都會自動生成輸入 schema 並成為 MCP 工具
4349
- PySide6 GUI（`python -m automation_file ui`）每個後端一個分頁，含 JSON 動作執行器，另有 Triggers、Scheduler、即時 Progress 專屬分頁
4450
- 功能豐富的 CLI，包含一次性子指令與舊式 JSON 批次旗標
4551
- 專案鷹架（`ProjectBuilder`）協助建立以 executor 為核心的自動化專案
@@ -611,6 +617,74 @@ server = start_metrics_server(host="127.0.0.1", port=9945)
611617
`automation_file_action_duration_seconds{action}`。若要綁定非 loopback
612618
位址必須明確傳入 `allow_non_loopback=True`。
613619

620+
### WebDAV、SMB/CIFS、fsspec
621+
在一等公民的 S3 / Azure / Dropbox / SFTP 之外，另有額外的遠端後端：
622+
623+
```python
624+
from automation_file import WebDAVClient, SMBClient, fsspec_upload
625+
626+
# RFC 4918 WebDAV —— loopback / 私有目標需要顯式開關。
627+
dav = WebDAVClient("https://files.example.com/remote.php/dav",
628+
username="alice", password="s3cr3t")
629+
dav.upload("/local/report.csv", "team/reports/report.csv")
630+
631+
# 透過 smbprotocol 的高階 smbclient API 操作 SMB / CIFS。
632+
with SMBClient("fileserver", "share", "alice", "s3cr3t") as smb:
633+
smb.upload("/local/report.csv", "reports/report.csv")
634+
635+
# 任何 fsspec 能定址的目標 —— memory、gcs、abfs、local、…
636+
fsspec_upload("/local/report.csv", "memory://reports/report.csv")
637+
```
638+
639+
### HTTP 伺服器觀測端點
640+
`start_http_action_server()` 額外提供 liveness / readiness 探針、OpenAPI 3.0
641+
規格，以及即時進度快照的 WebSocket 串流：
642+
643+
```bash
644+
curl http://127.0.0.1:9944/healthz # {"status": "ok"}
645+
curl http://127.0.0.1:9944/readyz # 登錄表非空時 200，否則 503
646+
curl http://127.0.0.1:9944/openapi.json # OpenAPI 3.0 規格
647+
# 以 WebSocket 連線 ws://127.0.0.1:9944/progress 取得即時進度訊框。
648+
```
649+
650+
### HTMX Web UI
651+
建構於標準函式庫 HTTP + HTMX（以帶 SRI 的固定 CDN URL 載入）之上的唯讀觀測
652+
儀表板。預設僅允許 loopback，可選 shared-secret：
653+
654+
```python
655+
from automation_file import start_web_ui
656+
657+
server = start_web_ui(host="127.0.0.1", port=9955, shared_secret="s3cr3t")
658+
# 瀏覽 http://127.0.0.1:9955/ —— health、progress、registry 片段每數秒
659+
# 自動輪詢；寫入操作仍保留在動作伺服器。
660+
```
661+
662+
### MCP（Model Context Protocol）伺服器
663+
透過 stdio 上的 JSON-RPC 2.0 將登錄的每個 `FA_*` 動作暴露給 MCP 主機
664+
（Claude Desktop、MCP CLI）：
665+
666+
```python
667+
from automation_file import MCPServer
668+
669+
MCPServer().serve_stdio() # 從 stdin 讀取 JSON-RPC，寫入 stdout
670+
```
671+
672+
`pip install` 後，`[project.scripts]` 會提供 `automation_file_mcp` console
673+
script，MCP 主機不需要寫任何 Python glue 也能啟動橋接器。三種等價的啟動方式：
674+
675+
```bash
676+
automation_file_mcp # 已安裝的 console script
677+
python -m automation_file mcp # CLI 子指令
678+
python examples/mcp/run_mcp.py # 獨立啟動腳本
679+
```
680+
681+
三者皆支援 `--name`、`--version`、`--allowed-actions`（逗號分隔白名單——
682+
強烈建議使用，因為預設登錄表包含 `FA_run_shell` 等高權限動作）。可直接複製的
683+
Claude Desktop 範例設定請見 [`examples/mcp/`](examples/mcp)。
684+
685+
工具描述在執行時由動作簽章自動生成——參數名稱與型別會轉換為 JSON schema，
686+
主機無需任何手動設定即可渲染欄位。
687+
614688
### DAG 動作執行器
615689
依相依關係執行動作；獨立分支會透過執行緒池平行展開。每個節點形式為
616690
`{"id": ..., "action": [...], "depends_on": [...]}`：
@@ -693,6 +767,8 @@ python -m automation_file create-file hello.txt --content "hi"
693767
python -m automation_file server --host 127.0.0.1 --port 9943
694768
python -m automation_file http-server --host 127.0.0.1 --port 9944
695769
python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
770+
python -m automation_file mcp --allowed-actions FA_file_checksum,FA_fast_find
771+
automation_file_mcp --allowed-actions FA_file_checksum,FA_fast_find # 已安裝的 console script
696772

697773
# 舊式旗標（JSON 動作清單）
698774
python -m automation_file --execute_file actions.json

0 commit comments

Comments
 (0)