Puppeteer Vision MCP Server - Specify4IT Configuration

Puppeteer Vision MCP サーバー - Specify4IT 構成

これは、specify4it.com のスクレイピング専用にセットアップされた Puppeteer Vision MCP サーバーの構成済みバージョンです。このサイト特有の構造、アニメーション、インタラクティブ要素に対応するカスタム設定とスクリプトが含まれています。

主な機能

• specify4it.com の構造とコンテンツに合わせて構成済み
• 以下を抽出するカスタムスクリプト：
  • ページのコンテンツと構造
  • CSS アニメーションとトランジション
  • JavaScript のインタラクション
  • デザイン要素とアセット
• ウェブサイトを再現するための整理された出力構造

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 ファイルまたはシェルでのエクスポートの例：

   # Required
   OPENAI_API_KEY=your_api_key_here
   
   # Optional (defaults shown)
   # VISION_MODEL=gpt-4.1
   # API_BASE_URL=https://api.openai.com/v1   # Uncomment to override
   # USE_SSE=true                             # Uncomment to use SSE mode instead of stdio
   # PORT=3001                                # Only used in SSE mode
   # DISABLE_HEADLESS=true                    # Uncomment to see the browser in action
   

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

   npx -y puppeteer-vision-mcp-server
   

   • -y フラグを指定すると、npx からのプロンプトが自動的に承認されます。
   • このコマンドは、サーバーをダウンロード（まだキャッシュされていない場合）して実行します。
   • デフォルトでは stdio モードで起動します。環境変数に USE_SSE=true が設定されている場合は、SSE 通信用の 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",
        // "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 です。
  • Together.ai、Groq、Anthropic、ローカルデプロイなど、OpenAI 互換の代替プロバイダーに接続する場合に使用します。
• USE_SSE：（任意）true に設定すると、HTTP 経由の SSE モードが有効になります。
  • デフォルト：false（stdio モードを使用します）。
• PORT：（任意）SSE モードでの HTTP サーバーのポートです。
  • デフォルト：3001。
• DISABLE_HEADLESS：（任意）true に設定すると、ブラウザーを表示モードで実行します。
  • デフォルト：false（ブラウザーはヘッドレスモードで実行されます）。

通信モード

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

1. stdio（デフォルト）：標準入力／出力を介して通信します。
   • プロセスを管理する LLM ツールとの直接統合に最適です。
   • コマンドラインでの使用やスクリプトに適しています。
   • HTTP サーバーは起動しません。USE_SSE=true が設定されていない場合、npx で実行するとデフォルトでこのモードになります。
2. SSE モード：HTTP 上の Server-Sent Events を介して通信します。
   • 環境変数に USE_SSE=true を設定すると有効になります。
   • 指定した PORT（デフォルト：3001）で HTTP サーバーを起動します。
   • ネットワーク経由でツールに接続する必要がある場合に使用します。

ツールの使用（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