MCP Browser Server

🚀 MCP Browser Server

Model Context Protocol (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を使用したAIによるスクリーンショット分析（Ollamaが必要）
11. get_page_info - 現在のページ情報を取得
12. close_browser - ブラウザーインスタンスを閉じる
13. scroll - 指定された方向（上/下/左/右）にページをスクロール
14. check_scrollability - ページが特定の方向にスクロール可能かどうかを確認

基本的な使用法

// Launch browser in headed mode for visual debugging
await launch_browser({ browser: "chromium", headless: false });

// Navigate to login page
await navigate({ url: "http://localhost:3000/login" });

// Fill in credentials
await type_text({ selector: "input[type='email']", text: "user@example.com" });
await type_text({ selector: "input[type='password']", text: "password123" });

// Submit form
await click_element({ selector: "button[type='submit']" });

// Wait for successful login
await wait_for_element({ selector: ".dashboard", timeout: 10000 });

// Check for any console errors during login
await get_console_logs({ level: "error" });

// Take screenshot of dashboard
await screenshot({ fullPage: true, path: "dashboard.png" });

// Get all console logs for debugging
await get_console_logs();

// Scroll down to see more content
await scroll({ direction: "down", pixels: 500, behavior: "smooth" });

// Check if page can be scrolled vertically
await check_scrollability({ direction: "vertical" });

// Scroll back to top
await scroll({ direction: "up", pixels: 500 });

ページのスクロールとナビゲート

MCP Browser Serverには、長いページをナビゲートし、スクロール機能を確認するための包括的なスクロールツールが含まれています。

スクロールツール

scrollツールを使用すると、細かい制御でページを任意の方向にスクロールできます。

// Scroll down by default amount (100px)
await scroll();

// Scroll in specific directions with custom distances
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 });

// Smooth scrolling for better user experience
await scroll({ direction: "down", pixels: 500, behavior: "smooth" });

パラメーター:

• direction: "up", "down", "left", "right"（デフォルト: "down"）
• pixels: スクロールするピクセル数（デフォルト: 100）
• behavior: "auto" または "smooth"（デフォルト: "auto"）

スクロール可能性確認ツール

check_scrollabilityツールは、ページが特定の方向にスクロール可能かどうかを判断します。

// Check both vertical and horizontal scrollability
await check_scrollability({ direction: "both" });

// Check only vertical scrolling
await check_scrollability({ direction: "vertical" });

// Check only horizontal scrolling  
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

使用例

基本的なスクリーンショット分析

// Take and analyze a screenshot with AI
await analyze_screenshot({ 
  fullPage: true,
  model: "gemma3:4b"
});

詳細な構造分析

// Get detailed analysis of page structure
await analyze_screenshot({ 
  detailed: true,
  pretext: "Focus on navigation elements and form fields"
});

コンテキスト固有の分析

// Look for specific elements or issues
await analyze_screenshot({ 
  pretext: "Check if there are any error messages or broken layouts",
  path: "error-check.png"
});

パラメーター

• fullPage (boolean): 全スクロール可能ページをキャプチャするか、ビューポートのみをキャプチャするか
• path (string): スクリーンショットを保存するオプションのファイルパス
• pretext (string): AIに対する追加のコンテキストまたは特定の指示
• model (string): 使用するAIモデル（デフォルト: "gemma3:4b"）
• detailed (boolean): 詳細な構造分析を要求する

サポートされるモデル

• gemma3:4b（デフォルト、速度と品質のバランスが良い）
• Ollamaインストールで利用可能な他の任意のビジョン対応モデル

開発とテスト

クイックセットアップ

# One-command setup (installs dependencies, browsers, and builds)
npm run setup

# Or step by step:
npm install
npx playwright install
npm run build

開発コマンド

# Build the project
npm run build

# Run in development mode
npm run dev

# Start the server
npm run start

# Development helper (shows all available commands)
npm run dev-helper help

テスト

プロジェクトにはtests/ディレクトリに包括的なテストが含まれています。

# Run basic communication test
npm run test

# Run browser automation demo
npm run test:demo

# Run AI analysis test (requires Ollama)
npm run test:ai-simple

# Check system status
npm run test:status

# Run all tests
npm run test:all

開発ヘルパー

一般的なタスクには開発ヘルパーを使用します。

# Show all available commands
npm run dev-helper help

# Quick setup from scratch
npm run dev-helper setup

# Run comprehensive tests
npm run dev-helper test

# Clean generated files
npm run dev-helper clean

テストの詳細については、tests/README.mdを参照してください。

プロジェクト構造

mcp-browser-server/
├── src/                 # TypeScript source code
│   └── index.ts        # Main MCP server implementation
├── build/              # Compiled JavaScript output
├── tests/              # Test scripts and documentation
│   ├── README.md       # Testing documentation
│   ├── simple-test.mjs # Basic communication test
│   ├── demo-test.mjs   # Browser automation demo
│   └── *.mjs          # Additional test files
├── screenshots/        # Generated screenshots from tests
├── package.json        # Project configuration
└── README.md          # This file

📄 ライセンス

二重ライセンス:

• 個人使用：個人、教育、非商用目的での使用は無料
• 商用使用：個別の商用ライセンスが必要

詳細な条件については、LICENSEを参照してください。商用ライセンスに関する問い合わせは、お問い合わせください。