MCP Browser Automation

MCP 浏览器自动化

🌐 概述

Algonius Browser 是一个开源 MCP（Model Context Protocol）服务，为外部 AI 系统提供浏览器自动化功能。它通过 MCP 协议提供一套全面的浏览器控制工具，使 AI 助手和其他工具能够以编程方式浏览网站、与 DOM 元素交互并提取网页内容。

🎯 主要功能

• MCP 协议集成：为 AI 系统控制浏览器自动化提供标准接口
• Chrome 扩展程序：处理浏览器交互的后台服务工作线程
• 原生消息传递：基于 Go 的 MCP 主机，可连接 Chrome 扩展程序与外部工具
• 全面的工具集：5 个浏览器自动化工具 + 2 个 MCP 资源
• 类型安全：完整的 TypeScript 实现，并具备结构化错误处理
• 测试套件：针对所有功能的全面集成测试

🛠️ 可用的 MCP 工具

导航与标签页

• navigate_to：导航至 URL，并可配置超时处理
• manage_tabs：创建、关闭和切换浏览器标签页

DOM 交互

• get_dom_extra_elements：通过分页和筛选高级提取 DOM 元素
• click_element：使用 CSS 选择器或文本匹配点击 DOM 元素
• set_value：设置输入框、文本区域和表单元素中的值
• scroll_page：按自定义距离向上或向下滚动页面

📋 可用的 MCP 资源

浏览器状态资源

• browser://current/state：以便于 AI 使用的 Markdown 格式呈现完整的当前浏览器状态

  • 活动标签页信息
  • 包含 URL、标题和状态的所有浏览器标签页
  • 通过资源通知实时更新状态

• browser://dom/state：以 Markdown 格式概览当前 DOM 状态

  • 页面元数据（URL、标题、滚动位置）
  • 前 20 个交互式元素
  • 元素总数及“还有更多”提示
  • 简化的 DOM 结构
  • 页面发生变化时自动更新

🚀 快速开始

1. 安装 Chrome 扩展程序

从 Chrome 网上应用店安装（推荐）：

1. 点击 Chrome 网上应用店页面上的“添加至 Chrome”按钮
2. 按提示确认安装
3. 扩展程序将自动安装并可供使用

从源代码安装（开发）：

# Clone and build
git clone https://github.com/algonius/algonius-browser.git
cd algonius-browser
pnpm install
pnpm build

# Load in Chrome
# 1. Open chrome://extensions/
# 2. Enable "Developer mode"
# 3. Click "Load unpacked"
# 4. Select the 'dist' folder

⚠️ 重要：Chrome 扩展程序需要 MCP Host 后端服务才能正常运行。请继续执行第 2 步以完成安装。

2. 安装 MCP Host

一键安装（推荐）：

Linux/macOS：

curl -fsSL https://raw.githubusercontent.com/algonius/algonius-browser/master/install-mcp-host.sh | bash

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/algonius/algonius-browser/master/install-mcp-host.ps1 | iex

手动安装：

# Download latest release
wget https://github.com/algonius/algonius-browser/releases/latest/download/mcp-host-linux-x86_64.tar.gz

# Extract and install
tar -xzf mcp-host-linux-x86_64.tar.gz
cd mcp-host-linux-x86_64
./install.sh

3. 验证安装

# Test the MCP host installation
mcp-host-go --version

# The MCP host will be automatically started when needed by the Chrome extension
# You should see the extension icon in your Chrome toolbar

✅ 成功：两个组件现已安装！请求浏览器自动化时，Chrome 扩展程序将自动与 MCP Host 通信。

🔧 集成示例

与 AI 助手配合使用

安装完成后，AI 系统即可通过 MCP 协议使用浏览器自动化工具和资源：

工具用法：

{
  "method": "tools/call",
  "params": {
    "name": "navigate_to",
    "arguments": {
      "url": "https://example.com",
      "timeout": 30000
    }
  }
}

资源访问：

{
  "method": "resources/read",
  "params": {
    "uri": "browser://current/state"
  }
}

常见工作流

网页抓取：

1. navigate_to → 导航到目标网站
2. 读取 browser://dom/state → 获取页面概览
3. get_dom_extra_elements → 使用分页获取特定元素
4. click_element → 与元素交互
5. 读取 browser://dom/state → 提取更新后的内容

表单自动化：

1. navigate_to → 前往表单页面
2. 读取 browser://dom/state → 识别表单元素
3. set_value → 填写表单字段
4. click_element → 提交表单
5. 读取 browser://current/state → 验证是否完成

多标签页管理：

1. 读取 browser://current/state → 检查当前标签页
2. manage_tabs → 创建或切换标签页
3. navigate_to → 在每个标签页中加载内容
4. 读取 browser://current/state → 监控所有标签页的状态

通过滚动导航页面：

1. navigate_to → 前往目标页面
2. 读取 browser://dom/state → 获取初始页面状态
3. scroll_page → 滚动以加载更多内容
4. get_dom_extra_elements → 提取新加载的元素

🏗️ 架构

External AI System
       ↓ (MCP Protocol)
   MCP Host (Go)
       ↓ (Native Messaging)
Chrome Extension
       ↓ (Chrome APIs)
    Browser Tabs

组件

• MCP 主机：基于 Go 的原生消息主机，实现 MCP 协议
• Chrome 扩展：带有工具处理程序的后台服务工作线程
• 内容脚本：DOM 交互和数据提取工具
• 集成测试：涵盖所有工具的完整测试套件

🧪 开发

从源代码构建

先决条件：

• Node.js 22.12.0+
• pnpm 9.15.1+
• Go 1.21+（用于 MCP 主机）

构建扩展：

pnpm install
pnpm build

构建 MCP 主机：

cd mcp-host-go
make build

运行测试：

# Extension tests
pnpm test

# MCP host tests  
cd mcp-host-go
make test

开发模式

# Extension development
pnpm dev

# MCP host development
cd mcp-host-go
make dev

📊 支持的平台

MCP 主机：

• Linux x86_64
• macOS Intel（x86_64）和 Apple Silicon（arm64）
• Windows x86_64

Chrome 扩展：

• Chrome/Chromium 88+
• Microsoft Edge 88+

📚 文档

详细文档位于 docs/ 目录中：

• MCP 主机集成
• 点击元素工具
• 设置值工具
• 导航超时
• 集成测试

🤝 贡献

欢迎贡献！请参阅我们的 CONTRIBUTING.md 了解相关指南。

贡献方式：

• 报告错误并提出功能请求
• 提交拉取请求以改进项目
• 添加集成测试
• 改进文档
• 分享使用示例

🔒 安全

如需报告安全漏洞，请创建 GitHub Security Advisory，而不要公开提交问题。

💬 社区

• Discord - 与开发者和用户交流
• GitHub Discussions - 分享想法并提出问题

📄 许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

👏 致谢

本项目基于以下优秀的开源项目构建：

• Chrome 扩展脚手架
• Model Context Protocol

---

由 Algonius Browser 团队倾情打造 ❤️

如果本项目帮助你构建更出色的浏览器自动化工具，请给我们点个星 🌟！