AutoProbeMCP - 你的代理浏览器

一个使用Playwright提供浏览器自动化功能的模型上下文协议（MCP）服务器。该服务器使AI助手能够通过标准化接口与网页进行交互。

非常适合使用AI助手进行的Web自动化、测试和调试工作流程，包括：

• Chat.fans代理 - 在VS Code中赋予AI代理与Web交互的能力
• GitHub Copilot Chat - 使用浏览器自动化增强开发工作流程
• 任何兼容MCP的AI助手 - 通用的AI工具浏览器自动化

功能

• 多浏览器支持：Chromium、Firefox 和 WebKit
• 全面自动化：导航、点击、输入、截图等
• JavaScript执行：在浏览器环境中运行自定义脚本
• 元素交互：等待元素出现、获取文本内容、与表单交互
• 截图能力：捕获全页或视口截图
• 类型安全：使用TypeScript构建，并通过Zod进行运行时验证

安装

npm install
npm run build

确保安装了Playwright浏览器：

npx playwright install

对于系统依赖项（Linux）：

sudo npx playwright install-deps

使用方法

VS Code集成

在VS Code中配置MCP服务器，添加到您的settings.json或工作区配置：

"mcp": {
    "servers": {
      "browser-automation": {
        "command": "node",
        "args": [
          "/home/yourUserName/mcp-browser-server/build/index.js"
        ],
        "env": {}
      }
    }
  }

配置完成后，Chat.fans代理和GitHub Copilot Chat可以使用浏览器自动化工具进行Web测试、抓取和自动化任务。

可用的VS Code任务

• 构建：Ctrl+Shift+P → "Tasks: 运行任务" → "build"
• 开发模式：Ctrl+Shift+P → "Tasks: 运行任务" → "dev"
• 测试MCP服务器：Ctrl+Shift+P → "Tasks: 运行任务" → "test-mcp-server"

可用工具

1. 启动浏览器 - 启动新的浏览器实例
2. 导航 - 转到特定URL
3. 点击元素 - 点击页面元素
4. 输入文本 - 将文本输入到表单字段中
5. 截图 - 捕获页面截图
6. 获取元素文本 - 从元素中提取文本
7. 等待元素 - 等待元素出现/消失
8. 执行JavaScript - 运行自定义JavaScript
9. 获取控制台日志 - 获取浏览器控制台日志（log、info、warn、error、debug）
10. 分析截图 - 使用Gemma3进行AI驱动的截图分析（需要Ollama）
11. 获取页面信息 - 获取当前页面信息
12. 关闭浏览器 - 关闭浏览器实例
13. 滚动 - 在指定方向上滚动页面（上/下/左/右）
14. 检查可滚动性 - 检查页面是否可以在特定方向上滚动

示例：Web应用程序测试

// 以有头模式启动浏览器进行视觉调试
await launch_browser({ browser: "chromium", headless: false });

// 导航至登录页面
await navigate({ url: "http://localhost:3000/login" });

// 填写凭证
await type_text({ selector: "input[type='email']", text: "user@example.com" });
await type_text({ selector: "input[type='password']", text: "password123" });

// 提交表单
await click_element({ selector: "button[type='submit']" });

// 等待成功登录
await wait_for_element({ selector: ".dashboard", timeout: 10000 });

// 检查登录期间是否有任何控制台错误
await get_console_logs({ level: "error" });

// 对仪表板截图
await screenshot({ fullPage: true, path: "dashboard.png" });

// 获取所有控制台日志用于调试
await get_console_logs();

// 向下滚动以查看更多内容
await scroll({ direction: "down", pixels: 500, behavior: "smooth" });

// 检查页面是否可以垂直滚动
await check_scrollability({ direction: "vertical" });

// 向上滚动回到顶部
await scroll({ direction: "up", pixels: 500 });

页面滚动和导航

MCP浏览器服务器包括全面的滚动工具，用于导航长页面并检查滚动能力：

滚动工具

scroll工具允许您以细粒度控制的方式在任何方向上滚动页面：

// 默认向下滚动（100像素）
await scroll();

// 在特定方向上滚动自定义距离
await scroll({ direction: "down", pixels: 300, behavior: "smooth" });
await scroll({ direction: "up", pixels: 200, behavior: "auto" });
await scroll({ direction: "left", pixels: 150 });
await scroll({ direction: "right", pixels: 150 });

// 平滑滚动以获得更好的用户体验
await scroll({ direction: "down", pixels: 500, behavior: "smooth" });

参数：

• direction: "up", "down", "left", "right"（默认："down"）
• pixels: 要滚动的像素数（默认：100）
• behavior: "auto" 或 "smooth"（默认："auto"）

滚动能力检查工具

check_scrollability工具确定页面是否可以在特定方向上滚动：

// 检查垂直和水平滚动能力
await check_scrollability({ direction: "both" });

// 仅检查垂直滚动
await check_scrollability({ direction: "vertical" });

// 仅检查水平滚动
await check_scrollability({ direction: "horizontal" });

响应包括：

• 当前滚动位置
• 最大滚动距离
• 每个方向上的滚动是否可能
• 详细的位置信息

AI驱动的截图分析

analyze_screenshot工具使用本地Gemma3模型通过Ollama提供AI驱动的网页分析。此功能可以根据上下文描述页面上可见的内容，分析页面结构，并查找特定元素。

先决条件

1. 安装Ollama：从ollama.ai下载
2. 安装Gemma3模型：

   ollama pull gemma3:4b
   

3. 启动Ollama服务：

   ollama serve
   

使用示例

基本截图分析

// 使用AI进行截图和分析
await analyze_screenshot({ 
  fullPage: true,
  model: "gemma3:4b"
});

详细的结构分析

// 获取页面结构的详细分析
await analyze_screenshot({ 
  detailed: true,
  pretext: "关注导航元素和表单字段"
});

上下文特定分析

// 查找特定元素或问题
await analyze_screenshot({ 
  pretext: "检查是否存在任何错误消息或布局损坏",
  path: "error-check.png"
});

参数

• fullPage (布尔值)：捕获整个可滚动页面还是仅视口
• path (字符串)：可选文件路径以保存截图
• pretext (字符串)：给AI的附加上下文或具体指令
• model (字符串)：要使用的AI模型（默认："gemma3:4b"）
• detailed (布尔值)：请求详细的结构分析

支持的模型

• gemma3:4b（默认，速度和质量的良好平衡）
• 您的Ollama安装中可用的任何其他具有视觉能力的模型

开发与测试

快速设置

# 单命令设置（安装依赖项、浏览器并构建）
npm run setup

# 或逐步操作：
npm install
npx playwright install
npm run build

开发命令

# 构建项目
npm run build

# 在开发模式下运行
npm run dev

# 启动服务器
npm run start

# 开发辅助程序（显示所有可用命令）
npm run dev-helper help

测试

项目包括在tests/目录中的全面测试：

# 运行基本通信测试
npm run test

# 运行浏览器自动化演示
npm run test:demo

# 运行AI分析测试（需要Ollama）
npm run test:ai-simple

# 检查系统状态
npm run test:status

# 运行所有测试
npm run test:all

开发辅助程序

使用开发辅助程序进行常见任务：

# 显示所有可用命令
npm run dev-helper help

# 从零开始快速设置
npm run dev-helper setup

# 运行全面测试
npm run dev-helper test

# 清理生成的文件
npm run dev-helper clean

有关更多测试详情，请参阅tests/README.md。

项目结构

mcp-browser-server/
├── src/                 # TypeScript源代码
│   └── index.ts        # 主MCP服务器实现
├── build/              # 编译的JavaScript输出
├── tests/              # 测试脚本和文档
│   ├── README.md       # 测试文档
│   ├── simple-test.mjs # 基本通信测试
│   ├── demo-test.mjs   # 浏览器自动化演示
│   └── *.mjs          # 额外的测试文件
├── screenshots/        # 测试生成的截图
├── package.json        # 项目配置
└── README.md          # 此文件

许可证

双重许可证：

• 个人用途：免费用于个人、教育和非商业用途
• 商业用途：需要单独的商业许可证

详见LICENSE中的完整条款。对于商业许可咨询，请联系我们。