Puppeteer Vision Mcp Server

Puppeteer vision MCP サーバー

この Model Context Protocol（MCP）サーバーは、Puppeteer、Readability、Turndown を使用してウェブページをスクレイピングし、Markdown 形式に変換するツールを提供します。AI による操作機能を備えており、Cookie、CAPTCHA、その他のインタラクティブ要素に自動で対応します。

npx で手軽に実行できるようになりました！

機能

• ステルスモードで Puppeteer を使用してウェブページをスクレイピングします
• AI を活用した操作により、以下に自動で対応します：
  • Cookie の同意バナー
  • CAPTCHA
  • ニュースレターや購読のプロンプト
  • ペイウォールやログインウォール
  • 年齢確認のプロンプト
  • インタースティシャル広告
  • コンテンツを妨げるその他のあらゆるインタラクティブ要素
• Mozilla の Readability を使用してメインコンテンツを抽出します
• HTML を適切に書式設定された Markdown に変換します
• コードブロック、テーブル、その他の構造化コンテンツを特別に処理します
• Model Context Protocol 経由で利用できます
• ヘッドレスモードを無効にすると、ブラウザーの操作をリアルタイムで確認できます
• npx パッケージとして手軽に利用できます。

NPX ですぐに始める

このサーバーの利用には npx を使う方法を推奨します。リポジトリをクローンしたり手動でインストールしたりせずに、常に最新バージョンを実行できます。

1. 前提条件： Node.js と npm がインストールされていることを確認します。

2. 環境の設定： このサーバーには OPENAI_API_KEY が必要です。この変数とその他の任意の設定は、次の 2 つの方法で指定できます。

   • .env ファイル： npx コマンドを実行するディレクトリに .env ファイルを作成します。
   • シェル環境変数： ターミナルのセッションで変数をエクスポートします。

   .env ファイルまたはシェルでのエクスポート例：

   # 必須
   OPENAI_API_KEY=your_api_key_here
   
   # 任意（デフォルト値を表示）
   # VISION_MODEL=gpt-4.1
   # API_BASE_URL=https://api.openai.com/v1   # コメントを解除して上書き
   # TRANSPORT_TYPE=stdio                     # 選択肢：stdio、sse、http
   # USE_SSE=true                             # 非推奨：代わりに TRANSPORT_TYPE=sse を使用
   # PORT=3001                                # sse/http モードでのみ使用
   # DISABLE_HEADLESS=true                    # コメントを解除してブラウザーの動作を確認
   

3. サーバーの実行： ターミナルを開いて、次のコマンドを実行します：

   npx -y puppeteer-vision-mcp-server
   

   • -y フラグを指定すると、npx からの確認プロンプトに自動で同意します。
   • このコマンドは、サーバーをダウンロード（まだキャッシュされていない場合）して実行します。
   • デフォルトでは stdio モードで起動します。HTTP サーバーモードを使用するには、TRANSPORT_TYPE=sse または TRANSPORT_TYPE=http を設定します。

NPX を使用して MCP ツールとして利用する

このサーバーは、MCP 対応の LLM オーケストレーター内のツールとして統合できるように設計されています。設定例を以下に示します：

{
  "mcpServers": {
    "web-scraper": {
      "command": "npx",
      "args": ["-y", "puppeteer-vision-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        // Optional:
        // "VISION_MODEL": "gpt-4.1",
        // "API_BASE_URL": "https://api.example.com/v1",
        // "TRANSPORT_TYPE": "stdio", // or "sse" or "http"
        // "DISABLE_HEADLESS": "true" // To see the browser during operations
      }
    }
    // ... other MCP servers
  }
}

このように設定すると、MCP オーケストレーターが puppeteer-vision-mcp-server プロセスのライフサイクルを管理します。

環境設定の詳細

サーバーをどのように実行する場合（NPX またはローカル開発）でも、以下の環境変数を使用します。

• OPENAI_API_KEY：（必須）ビジョンモデルにアクセスするための API キーです。
• VISION_MODEL：（任意）ビジョン分析に使用するモデルです。
  • デフォルト：gpt-4.1
  • ビジョン機能を備えた任意のモデルを使用できます。
• API_BASE_URL：（任意）カスタム API エンドポイント URL です。
  • 代替の OpenAI 互換プロバイダー（Together.ai、Groq、Anthropic、ローカルデプロイなど）に接続する場合に使用します。
• TRANSPORT_TYPE：（任意）使用するトランスポートプロトコルです。
  • 選択肢：stdio（デフォルト）、sse、http
  • stdio：プロセス間の直接通信（ほとんどの用途で推奨）
  • sse：HTTP 経由の Server-Sent Events（レガシーモード）
  • http：セッション管理機能を備えたストリーミング可能な HTTP トランスポート
• USE_SSE：（任意、非推奨）HTTP 経由の SSE モードを有効にするには、true に設定します。
  • 非推奨：代わりに TRANSPORT_TYPE=sse を使用してください。
• PORT：（任意）SSE モードまたは HTTP モードでの HTTP サーバーのポートです。
  • デフォルト：3001。
• DISABLE_HEADLESS：（任意）ブラウザーを表示モードで実行するには、true に設定します。
  • デフォルト：false（ブラウザーはヘッドレスモードで実行されます）。

通信モード

サーバーは 3 つの通信モードに対応しています。

1. stdio（デフォルト）：標準入力／出力を介して通信します。
   • プロセスを管理する LLM ツールとの直接統合に最適です。
   • コマンドラインでの使用やスクリプトに最適です。
   • HTTP サーバーは起動しません。これがデフォルトのモードです。
2. SSE モード：HTTP 経由の Server-Sent Events を介して通信します。
   • 環境で TRANSPORT_TYPE=sse を設定すると有効になります。
   • 指定した PORT（デフォルト：3001）で HTTP サーバーを起動します。
   • ネットワーク経由でツールに接続する必要がある場合に使用します。
   • 接続先：http://localhost:3001/sse
3. HTTP モード：セッション管理機能を備えたストリーミング可能な HTTP トランスポートを介して通信します。
   • 環境で TRANSPORT_TYPE=http を設定すると有効になります。
   • 指定した PORT（デフォルト：3001）で HTTP サーバーを起動します。
   • 完全なセッション管理と再開可能な接続に対応しています。
   • 接続先：http://localhost:3001/mcp

ツールの使用方法（MCP の呼び出し）

サーバーは scrape-webpage ツールを提供します。

ツールのパラメーター：

• url（文字列、必須）：スクレイピングするウェブページの URL です。
• autoInteract（ブール値、任意、デフォルト：true）：インタラクティブ要素を自動的に処理するかどうかを指定します。
• maxInteractionAttempts（数値、任意、デフォルト：3）：AI によるインタラクションの最大試行回数です。
• waitForNetworkIdle（ブール値、任意、デフォルト：true）：処理前にネットワークがアイドル状態になるまで待機するかどうかを指定します。

レスポンス形式：

ツールは、結果を構造化形式で返します。

• content：スクレイピングしたウェブページの生の Markdown を含む、単一のテキストオブジェクトを格納した配列です。
• metadata：追加情報を含みます。
  • message：ステータスメッセージです。
  • success：成功したかどうかを示すブール値です。
  • contentSize：コンテンツの文字数です（成功時）。

成功時のレスポンス例：

{
  "content": [
    {
      "type": "text",
      "text": "# Page Title\n\nThis is the content..."
    }
  ],
  "metadata": {
    "message": "Scraping successful",
    "success": true,
    "contentSize": 8734
  }
}

エラー時のレスポンス例：

{
  "content": [
    {
      "type": "text",
      "text": ""
    }
  ],
  "metadata": {
    "message": "Error scraping webpage: Failed to load the URL",
    "success": false
  }
}

仕組み

AI によるインタラクション

このシステムでは、ビジョン機能を備えた AI モデル（VISION_MODEL と API_BASE_URL で設定可能）を使用してウェブページのスクリーンショットを分析し、オーバーレイや同意フォームを回避するためのクリック、入力、スクロールなどの操作を決定します。この処理は maxInteractionAttempts 回まで繰り返されます。

コンテンツの抽出

インタラクションの後、Mozilla の Readability がメインコンテンツを抽出します。その後、コードブロックやテーブル用のカスタムルールを適用した Turndown を使用して、コンテンツをサニタイズし、Markdown に変換します。

インストールと開発（コードを変更する場合）

コントリビュートする場合、サーバーを変更する場合、またはローカルの開発バージョンを実行する場合は、次の手順に従ってください。

1. リポジトリをクローンします：

   git clone https://github.com/djannot/puppeteer-vision-mcp.git
   cd puppeteer-vision-mcp
   

2. 依存関係をインストールします：

   npm install
   

3. プロジェクトをビルドします：

   npm run build
   

4. 環境を設定します： プロジェクトのルートディレクトリに .env ファイルを作成し、OPENAI_API_KEY と必要なその他の設定を記述します（上記の「環境設定の詳細」を参照してください）。

5. 開発用に実行します：

   npm start # ローカルビルドを使用してサーバーを起動します
   

   または、変更時に自動で再ビルドするには、次を実行します：

   npm run dev
   

カスタマイズ（開発者向け）

スクレイパーの動作は、次のファイルを編集して変更できます。

• src/ai/vision-analyzer.ts（analyzePageWithAI 関数）：AI プロンプトをカスタマイズします。
• src/ai/page-interactions.ts（executeAction 関数）：新しいアクションの種類を追加します。
• src/scrapers/webpage-scraper.ts（visitWebPage 関数）：Puppeteer のオプションを変更します。
• src/utils/markdown-formatters.ts：Markdown 変換用の Turndown ルールを調整します。

依存関係

主な依存関係は次のとおりです。

• @modelcontextprotocol/sdk
• puppeteer、puppeteer-extra
• @mozilla/readability、jsdom
• turndown、sanitize-html
• openai（またはビジョンモデル向けの互換 API）
• express（SSE モード用）
• zod