GUI2MCP

将只能通过浏览器使用的旧版软件转化为 AI 可调用的工具。

观看 27 秒演示（MP4）

在 Canva 上查看 GUI2MCP 推介文稿

旧版 GUI -> GUI2MCP -> 生成的 MCP 服务器 -> Codex 像使用原生 API 一样使用它

问题

许多公司仍然依赖没有可用 API 的内部软件和旧版软件。人类可以通过浏览器搜索记录、创建客户、提交发票，但 AI 代理每次都必须推理整个界面才能访问这些能力。

重新构建供应商软件成本高昂。编写和维护一次性自动化脚本则无法扩展。

核心洞察

GUI 本身就是软件能力的机器可读描述。

GUI2MCP 观察该界面，发现有用的操作，将它们编译为类型化的 MCP 工具，并通过 Playwright 操作原始 GUI 来执行每次调用。

对于随附的无 API CRM，GUI2MCP 生成：

search_customer(customer_name)
create_customer(name, email, company)
create_invoice(customer, amount_jpy, description)

Codex 不再需要查找菜单、检查 DOM 或决定按下哪个按钮。它只需调用一个领域级工具：

{
  "name": "create_invoice",
  "arguments": {
    "customer": "Aiko Tanaka",
    "amount_jpy": 120000,
    "description": "AI integration workshop"
  }
}

GUI2MCP 会打开真实的发票界面，填写字段，提交表单，验证可见结果，并连同截图返回 INV-0001。

为什么不直接调用 Playwright？

Playwright 是执行器。GUI2MCP 是界面编译器。

对于一次性任务，直接使用 Playwright 就够了。GUI2MCP 适用于需要变得可复用、可审查并可供所有 MCP 客户端使用的重复性操作。

工作原理

flowchart LR
    A[Legacy web GUI<br/>No JSON API] -->|Observe DOM and forms| B[GUI Inspector]
    B -->|Compile labels, fields, actions| C[generated/tools.json]
    C --> D[Generic STDIO<br/>MCP server]
    D -->|tools/list and tools/call| E[Codex]
    E -->|Typed business action| D
    D -->|Replay through Playwright| A
    A -->|Visible result + evidence| D

1. 观察： Playwright 爬取一组受限的同源页面。

2. 理解： 提取标题、标签、必填字段、输入类型、选项和提交操作。

3. 编译： GUI 操作变为 MCP 名称、描述、JSON Schema 和安全注解。

4. 执行： 通用 MCP 运行时加载生成的规范，并通过 GUI 重放调用。

5. 验证： 可见的提示和结果表格作为结构化输出连同截图一并返回。

生成的 MCP 运行时中不包含任何 CRM 专用处理器。其行为来自 generated/tools.json。

90 秒评委演示

1. 打开 Legacy CRM，并指出它只暴露浏览器页面。

2. 打开 GUI2MCP Studio，点击 Discover tools。

3. 展示三个生成的工具及其类型化参数。

4. 向 Codex 提问：

   搜索 Acme 客户，然后为一场 AI 集成工作坊创建一张 JPY 120,000 的发票。

5. Codex 调用 search_customer，接着调用 create_invoice。

6. 打开 CRM 的发票登记簿，展示通过原始 GUI 创建的 INV-0001。

该演示特意使用相互独立的源：

• GUI2MCP 控制平面：http://127.0.0.1:4310

• 未修改的旧版目标：http://127.0.0.1:4311/legacy

• http://127.0.0.1:4311/api/health 返回 404

端口 4310 上的 JSON 端点属于 GUI2MCP Studio，而非旧版应用。

本地运行

前置要求：Node.js 20+ 和 pnpm。

corepack pnpm install
corepack pnpm exec playwright install chromium
corepack pnpm dev

打开：

• GUI2MCP Studio：http://127.0.0.1:4310

• Legacy CRM：http://127.0.0.1:4311/legacy

在 Studio 中，点击 Discover tools，选择任意生成的工具卡片，提供参数，然后选择 Run via Playwright。

Studio 支持通过右上角的 EN / JP 控件切换英语和日语。

连接 Codex

先在 Studio 中生成工具规范。保持 Studio 和旧版目标运行，然后构建并注册 STDIO 服务器：

corepack pnpm build
codex mcp add gui2mcp -- node "C:\absolute\path\to\GUI2MCP\dist\src\mcp.js"
codex mcp list

重启 Codex 并提问：

Search for the Acme customer, then create a JPY 120,000 invoice
for an AI integration workshop.

项目级配置也可在 .codex/config.toml.example 中找到。

CLI 工作流

在演示服务器运行时：

corepack pnpm discover -- --url http://127.0.0.1:4311/legacy
corepack pnpm mcp

实用的环境变量：

• GUI2MCP_SPEC：加载另一个生成的工具规范。

• GUI2MCP_HEADFUL=1：在 MCP 工具执行时显示浏览器。

• PORT：更改 GUI2MCP Studio 的端口。

• LEGACY_PORT：更改演示目标的端口。

技术亮点

• 服务器启动时生成的动态 MCP tools/list

• 从真实表单控件推断出的 JSON Schema

• MCP 安全注解，如 readOnlyHint 和 idempotentHint

• 以标签优先的字段解析，并以 name 和 ID 作为回退

• 对可见表格和成功提示的结构化提取

• 为每次完成的工具调用提供证据截图

• 在随附的 Chromium、Edge 和 Chrome 之间自动回退

• 英语/日语 Studio 界面

• 确定性的发现与重放无需模型 API 密钥

验证

该仓库包含单元测试和端到端 MCP 检查：

corepack pnpm check
corepack pnpm test
corepack pnpm build
node dist/tests/mcp-smoke.js

冒烟测试会启动生成的 STDIO MCP 服务器，运行 tools/list，调用 search_customer，并验证结果中包含 Acme Industries。

原型范围

这个两小时构建的原型旨在提供令人信服的端到端验证，而非面向任意站点的自动化。

它目前针对传统的服务端渲染表单。CAPTCHA、复杂的 SPA、iframe 工作流、任意身份验证和选择器自愈均有意不在范围内。

下一个产品步骤是 Teach Workflow：

人类只需演示一次多页面操作；GUI2MCP 就会将该演示、其参数及其成功条件转化为一个受治理的 MCP 工具。

这将把产品从表单发现推进到持久的业务工作流编译。

仓库结构

src/discovery.ts       GUI inspection and tool compilation
src/executor.ts        Playwright-based generated tool runtime
src/mcp.ts             Generic STDIO MCP server
src/legacy-crm.ts      Separate-origin, API-less demo target
public/                GUI2MCP Studio
generated/tools.json   Generated machine interface
tests/                 Unit and MCP smoke tests
Plan.md                Japanese implementation plan and demo script

重新录制演示

corepack pnpm record:demo

这会在 artifacts/ 中生成带英文字幕的 WebM 和 H.264 MP4 版本。

API 不再需要由软件供应商来构建。AI 可以从已有的 GUI 中推导出一个机器接口。