MCP Browser Server

🚀 MCP瀏覽器服務器

MCP瀏覽器服務器是一個基於模型上下文協議（MCP）的服務器，藉助Playwright實現瀏覽器自動化功能。該服務器能讓AI助手通過標準化接口與網頁進行交互，在網頁自動化、測試和調試工作流中表現出色。

它適用於各類AI助手，包括：

• Chat.fans 代理：為VS Code中的AI代理賦予網頁交互能力。
• 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即可使用瀏覽器自動化工具進行網頁測試、數據抓取和自動化任務。

可用的VS Code任務

• 構建：按下 Ctrl+Shift+P，選擇 "Tasks: Run Task"，然後選擇 "build"。
• 開發模式：按下 Ctrl+Shift+P，選擇 "Tasks: Run Task"，然後選擇 "dev"。
• 測試MCP服務器：按下 Ctrl+Shift+P，選擇 "Tasks: Run Task"，然後選擇 "test-mcp-server"。

可用工具

1. launch_browser：啟動一個新的瀏覽器實例。
2. navigate：跳轉到指定URL。
3. click_element：點擊頁面元素。
4. type_text：在表單字段中輸入文本。
5. screenshot：捕獲頁面截圖。
6. get_element_text：從元素中提取文本。
7. wait_for_element：等待元素出現或消失。
8. evaluate_javascript：運行自定義JavaScript代碼。
9. get_console_logs：獲取瀏覽器控制檯日誌（包括log、info、warn、error、debug）。
10. analyze_screenshot：使用Gemma3（需要Ollama）進行AI截圖分析。
11. get_page_info：獲取當前頁面信息。
12. close_browser：關閉瀏覽器實例。
13. scroll：按指定方向（上/下/左/右）滾動頁面。
14. check_scrollability：檢查頁面在特定方向上是否可滾動。

基礎用法

以下是一個網頁應用測試的示例：

// 以有頭模式啟動瀏覽器，便於可視化調試
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 工具允許你以細粒度控制頁面在任何方向上滾動：

// 默認向下滾動100px
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 工具通過Ollama使用本地Gemma3模型對網頁進行AI分析。該功能可以描述頁面上可見的內容、分析頁面結構，並根據上下文查找特定元素。

前提條件

1. 安裝Ollama：從 ollama.ai 下載。
2. 安裝Gemma3模型：

ollama pull gemma3:4b

3. 啟動Ollama服務：

ollama serve

使用示例

// 基本截圖分析
await analyze_screenshot({ 
  fullPage: true,
  model: "gemma3:4b"
});

// 詳細結構分析
await analyze_screenshot({ 
  detailed: true,
  pretext: "Focus on navigation elements and form fields"
});

// 特定上下文分析
await analyze_screenshot({ 
  pretext: "Check if there are any error messages or broken layouts",
  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。如需商業許可諮詢，請聯繫我們。