AI导哈

表单自动化工具

UCL学生会表单自动化工具，可作为MCP服务器与Claude Desktop交互或作为轮询工作器与收据收集器Web应用集成，支持自动填写和手动审核表单。

  • by MaybeItsAdam
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 MaybeItsAdam/suu-mcp

使用说明

口 车

[！注意] 此项目正在合并到 suu-cli. 表单填充器现在仍然有效 在那里 suu forms …, suu mcp …，以及 suu poll，在数据抓取器旁边，在一个 安装。suu-cli的显著变化：MCP服务器以 suu mcp run （以及 suu mcp setup 自动配置您的AI应用程序）；登录信息保存在 ~/.suu 而不是 forms/ 或 ~/.suu-auto。此回购将作为参考，直到 suu-cli 完全 验证后，将存档。

伦敦大学学院学生会表单自动化——作为一个 MCP服务器 适用于Claude Desktop或作为 投票站工作人员 用于收据收集器web应用程序。

不隶属于伦敦大学学院或伦敦大学学院学生会。

模式

命令 描述
suu-auto mcp MCP服务器——Claude调用工具以交互方式填写表单
suu-auto poll 轮询工作者-从receipt-gather API读取排队作业并自动填写表单

两种模式使用相同的 FormExecutor 引擎盖下的发动机。形式是 从未自动提交 --浏览器保持打开状态以供查看。

支持的表单

表单ID 描述 用例
payment_request 付款申请单 报销（偿还会员）。请勿用于发票。
purchase_request 采购申请表 向供应商支付发票或要求工会购买东西。

安装

git clone <repo_url> suu-auto
cd suu-auto
pip install -e .
playwright install chromium

认证

[！警告] 永不承诺 auth.json 文件夹。 它们包含实时会话Cookie。这 .gitignore 排除 forms/*_auth.json.

保存会话一次（打开浏览器进行手动登录）：

python scripts/save_auth.py

这写道 forms/default_auth.json （MCP模式）或 ~/.suu-auto/auth.json （投票模式）。

MCP模式--克劳德桌面

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "suu-auto": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/suu-auto",
        "run",
        "suu-auto",
        "mcp"
      ]
    }
  }
}

克劳德会打电话的 list_available_forms() 然后 run_form_automation(form_id, data).

轮询模式——收据收集器集成

配置 .env:

APP_URL=https://your-receipt-gatherer-app.example.com
WORKER_AUTH_TOKEN=your-shared-secret          # must match the server's WORKER_AUTH_TOKEN
SUU_AUTO_HOME=~/.suu-auto                     # optional, default shown
WORKER_DEFAULT_FORM_ID=payment_request        # optional, default shown
AUTH_MAX_AGE_DAYS=7                           # optional; rejects stale auth.json
WORKER_POLL_INTERVAL_SECONDS=5                # optional
WORKER_HEARTBEAT_INTERVAL_SECONDS=15          # optional

然后运行：

suu-auto poll

工人向 /api/worker/poll，下载收据图像，填写表单，并报告完成/失败。作业有效载荷 form_id 字段选择要填写的表单；它默认为 payment_request.

手动运行表单

python scripts/run_form.py payment_request --data examples/my_data.json
python scripts/run_form.py purchase_request --data examples/my_data.json

录制新表单

python scripts/record_form_def.py "https://studentsunionucl.org/forms/your-form" --id new_form_id

项目结构

src/
  cli.py        Entry point — dispatches to mcp or poll
  server.py     MCP server (FastMCP tools)
  worker.py     Polling worker loop
  payload.py    Maps receipt-gatherer job payload → form field data
  executor.py   Playwright form automation engine
  schema.py     Pydantic models (FormDefinition, FormField)
  recorder.py   Interactive form recorder
forms/
  payment_request.json
  purchase_request.json
scripts/
  save_auth.py          Save browser session (one-time login)
  run_form.py           Run a form manually from the CLI
  record_form_def.py    Record a new form definition interactively

相关 MCP