关键词

网页自动化LLM交互UI桥接Playwright无障碍访问

项目简介

MCP UI 桥接服务器（'mcp-ui-bridge'）是一个创新的开源项目，旨在通过统一的开发流程，使网页应用能够原生且平等地被人类用户和大型语言模型（LLMs）访问和交互。它扮演着一个“桥梁”的角色，使用Playwright控制浏览器，解析带有特定语义化属性（'data-mcp-*'）的网页DOM结构，并将网页的当前状态（上下文）和可执行操作（工具）以标准化的Model Context Protocol (MCP) 格式暴露给LLM客户端。核心理念是“一次编码，服务所有”，开发者在构建人类用户界面时，只需添加少量语义标注，即可使其同时对LLM可用，无需维护单独的API。

主要功能点

  • 网页UI语义化解析: 扫描网页DOM，识别带有 'data-mcp-*' 属性的元素，理解其角色、目的和状态。
  • Playwright驱动的浏览器控制: 利用Playwright强大的自动化能力，精确执行点击、输入、选择等用户界面操作。
  • MCP工具暴露: 将网页的可交互元素和通用操作（如滚动、分页）转化为LLM可以通过'send_command'调用的标准化工具。
  • 网页状态上下文提供: 通过'get_current_screen_data'工具向LLM提供结构化的网页视图，包括交互元素、显示数据、区域信息和加载状态。
  • 可定制性: 支持注册自定义的HTML属性读取器（'CustomAttributeReader'）和自定义动作处理器（'CustomActionHandler'），以适应特定的应用场景和复杂交互。
  • 跨平台/语言支持: 提供TypeScript/Node.js和Python两种实现版本。
  • 多种传输协议支持: 利用FastMCP库，支持Server-Sent Events (SSE) / HTTP Stream 等MCP标准传输协议。
  • 会话管理与能力声明: 通过FastMCP提供基本的MCP服务器能力，包括服务器信息、工具列表、以及可选的客户端认证。

安装步骤

该仓库包含TypeScript和Python两种实现，以及示例应用。通常您需要运行目标前端应用、可选的后端（如果前端依赖）以及MCP UI桥接服务器本身。

  1. 克隆仓库:

    git clone https://github.com/SDCalvo/mcp-ui-bridge.git
cd mcp-ui-bridge

  2. 安装前端示例依赖并运行: (可选，如果您想使用仓库自带的TodoMVC示例)

    cd frontend
npm install
npm run dev
# 前端通常运行在 http://localhost:5173

  3. 安装后端示例依赖并运行: (可选，如果前端示例需要)

    cd backend
pip install -r requirements.txt # 需要安装pipenv或使用pip安装requirements.txt
# 运行方式可能多样，例如使用uvicorn (参考 backend/app/main.py 中的注释)
# pipenv run uvicorn app.main:app --reload 
# 或检查 package.json 或其他文档找到正确的启动命令

  4. 安装并运行MCP UI桥接服务器: 选择TypeScript或Python实现。推荐运行示例外部服务器，它们是预配置的使用桥接库的应用。

    • TypeScript版本: 
      cd mcp-external-server
npm install
npm run dev
# 服务器通常运行在 http://localhost:8070
    • Python版本: 
      cd mcp-external-server-python
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
python src/main.py
# 服务器通常运行在 http://localhost:8080 或 http://localhost:8070 (取决于配置和代码)
    • 运行服务器时，需要通过环境变量 'MCP_TARGET_URL' 或其他配置方式指定目标网页的URL（例如：'http://localhost:5173'）。可以通过 'MCP_HEADLESS_BROWSER=false' 环境变量以非无头模式运行浏览器，方便调试。端口可以通过 'MCP_PORT' 设置。

服务器配置 (为MCP客户端准备)

MCP服务器启动后，MCP客户端（如Cursor）需要连接到它才能使用提供的工具。您需要在MCP客户端中配置服务器信息。所需的关键信息如下（请注意，实际端口和路径取决于您启动服务器时的配置）：

  • 服务器名称: 您启动服务器时指定的名称 (例如: "MCP External Server Example with Custom Handlers" 或 "MCP UI Bridge Server (Python)")。客户端配置时可以自定义显示名称。
  • 传输协议 (transport): 根据服务器实现和配置，可能是 "sse" 或 "streamable-http"。对于此项目，通常是 "sse" 或等效的基于HTTP Stream的传输。
  • 连接URL: MCP服务器监听的地址和路径。格式通常是 'http://<host>:<port><endpoint_path>'。
    • 例如，如果服务器在本地运行在8070端口，SSE端点路径是'/mcp'，则URL可能是 'http://localhost:8070/mcp'。
    • 参考 README 中的 Cursor 配置示例: 如果您使用 'mcp-external-server' 或 'react-cli-mcp' 默认配置，URL可能是 'http://localhost:3000/mcp/sse' 或 'http://localhost:8070/sse' 或 'http://localhost:8080/mcp' 等。请务必查看您启动服务器时控制台输出的实际地址和端口信息。
  • 描述 (description): 服务器的能力描述或使用说明，LLM可能会参考。

您将需要在MCP客户端的用户界面或配置文件中输入这些信息，以便客户端能够发现并连接到运行中的MCP UI桥接服务器。

基本使用方法

  1. 确保目标网页应用和MCP UI桥接服务器都已成功启动。
  2. 打开您的MCP客户端软件（例如Cursor或其他支持MCP的工具）。
  3. 在客户端中添加或启用指向您运行的MCP UI桥接服务器的配置（使用上面提到的连接URL、传输协议等信息）。
  4. 一旦客户端连接成功，它应该能够通过MCP协议发现并使用服务器提供的工具，例如：
    • 调用 'get_current_screen_data' 获取网页当前状态的结构化数据。
    • 调用 'get_current_screen_actions' 获取当前页面上可执行的操作列表和命令提示。
    • 调用 'send_command' 发送具体的指令来操作网页，例如 'send_command {"command_string": "click #submit-button"}' 或 'send_command {"command_string": "type #username-field "testuser""}'。

通过这些工具，LLM客户端就可以“看到”网页、理解可进行的交互，并自动化执行任务。

信息

分类

AI与计算

访问项目