visual-hunt-mcp

visual-hunt-mcpは、macOS向けのローカルTypeScript MCPサーバーです。CDP経由で既存のChromeセッションに接続し、CodexやClaudeがポスター、壁紙、インスピレーションボード用の強力な画像候補を見つけるのを支援します。

v0.4.0 · 11個のツール · エンドツーエンド監査済み · 15/15の動作テストをパス · 10トピックの現実的なストレステストで108枚の画像をダウンロード · 評価スイートとフルテストハーネスを同梱

設計目的:

• 公式の@modelcontextprotocol/sdkとMcpServerおよびregisterToolを使用する

• chromium.connectOverCDP(...)経由でローカルのChromeインスタンスに接続する

• 手動支援によるレビューを選択した際に、ローカルでログイン済みのブラウザプロファイルを再利用する

• ペイウォール、ログインウォール、CAPTCHA、プラットフォーム制御の回避を避ける

• 候補のメタデータを返し、オプションでMCPサーバーの現在の作業ディレクトリ下に作成されたプロジェクトフォルダに画像ファイルをダウンロードする

CDPを採用した理由

このプロジェクトは、新しい自動化ブラウザを起動する代わりにChrome DevTools Protocolを使用することで、MCPサーバーがユーザーが管理するローカルのChromeプロファイルを再利用できるようにしています。これにより、Instagramや小紅書（Xiaohongshu）のワークフローがより実用的になります。ブラウザセッションはすでにログイン状態を維持でき、MCPサーバーはMac上でローカルに動作し続けるためです。

Instagram / 小紅書（Xiaohongshu）が手動支援型である理由

Instagramや小紅書はログインが必要なことが多く、レイアウトが頻繁に変更され、プラットフォームの制御によってコンテンツが制限される場合があります。このMCPは、接続されたローカルのChromeでそれらのページを意図的に開き、利用可能な場合にのみ表示されている公開画像候補を抽出します。ログイン、レート制限、アクセス制限を回避しようとはしません。

ダウンロードの範囲

このプロジェクトでは、Unsplash、Pexels、Pixabay、壁紙サイト、および接続されたChromeセッションがアクセス可能な場合に手動支援によるソーシャルブラウジングから表示される画像URLなどのソースから画像ファイルをダウンロードできます。いくつかのガードレールが適用されます:

• GoogleホストのプレビューおよびGoogleマップの画像はブロックされたままです

• Instagramと小紅書は、接続されたChromeのログイン状態と、ページが実際に公開している表示可能な画像URLに依存します

• 再利用前のライセンス確認はユーザーの責任となります

• save_candidates_jsonはメタデータのみを扱い、download_candidate_imagesは画像ファイルとダウンロードマニフェストを書き込みます

機能

MCPツール (11)

デフォルトのソースセット (v0.4.0で厳選)

デフォルトのsearch_wallpaper_sitesソースリストは、v0.4.0で13ソースから、現実的なストレステストにおいて80%以上のトピックでダウンロード可能な候補を返した6ソースに絞り込まれました:

1. Unsplash — モダンなエディトリアル写真

2. Pexels — モダンなエディトリアル写真

3. Pixabay — モダンなエディトリアル写真

4. Wikimedia Commons — ランドマーク、建築、パブリックドメイン

5. Wallhaven — 無料のトップ4K/8K壁紙

6. Alpha Coders / Wallpaper Abyss — 無料のトップ4K/8K壁紙

除外されたソース用のアダプターも同梱されています。必要な場合は明示的に渡してください: sites: ["openverse.org", "loc.gov", "images.nasa.gov", "rawpixel.com", "publicdomainpictures.net", "wallpaperscraft.com", "hdqwalls.com"]。

候補のスコアリング

各候補には、以下に基づく軽量なscoreHintが付与されます:

• 画像サイズ

• 一般的なポスター/壁紙比率へのアスペクト比の近さ

• poster, cinematic, wallpaper, 4k, 8k, travel, film, landscapeなどのタイトルまたはaltテキストのキーワード

インストール

cd /Users/lanston/Desktop/Codex/visual-hunt-mcp
npm install

MCP用Chromeの起動

npm run chrome:debug

このヘルパーは、Chromeのリモートデバッグを127.0.0.1のみにバインドします。CDPポートを公開することはありません。

生のスクリプトを好む場合:

chmod +x scripts/start-chrome-mcp.sh
./scripts/start-chrome-mcp.sh

検証ワークフロー

Chrome起動後に決定論的なMCPスモークテストを実行します:

npm run smoke

11個のツールすべてを網羅する包括的な動作スイート（スキーマ強制、クエリ最適化、手動ページライフサイクル、ログインウォール抑制、偽陽性フィルター、セキュリティガード）:

node scripts/full-test.mjs              # 15 cases including live Chrome paths
node scripts/full-test.mjs --skip-live  # 10 cases, fast, no browser deps

npm run smokeが検証する内容:

• ローカルMCPサーバーが現在のdist/出力からstdio経由で起動すること

• tools/listが期待されるツールセットを公開すること

• open_url_and_extract_imagesがローカルのフィクスチャページから表示可能な候補を抽出できること

• extract_manual_page_candidatesとclose_manual_pageが手動支援フォローアップフローのために公開されていること

• save_candidates_jsonが候補のメタデータを一時的な出力ルートに書き込むこと

• download_candidate_imagesが許可されたローカル画像をダウンロードし、ブロックされたGoogleホストの候補を明確な理由とともにスキップすること

スモークテストは一時的なVISUAL_HUNT_OUTPUT_ROOTを使用し、成功時にクリーンアップします。検査のためにアーティファクトを保持するには:

npm run smoke -- --keep-output

接続されたChromeセッションを通じて、ライブのGoogle画像検索や壁紙検索フローも実行する高信頼性パス:

npm run smoke:live

安定したデフォルトの検証コマンドとしてnpm run validateを使用してください。これは最初にnpm run buildを実行し、その後に決定論的なスモークテストを実行します。

MCPをローカルで実行

npm run dev

本番環境のような使用方法:

npm run build
node dist/index.js

Claude Desktopの設定

{
  "mcpServers": {
    "visual-hunt": {
      "command": "node",
      "args": [
        "/Users/lanston/Desktop/Codex/visual-hunt-mcp/dist/index.js"
      ],
      "env": {
        "CHROME_CDP_ENDPOINT": "http://127.0.0.1:9222"
      }
    }
  }
}

プロンプト例

Use visual-hunt to search_google_images for "cinematic Oahu Hawaii sunset travel poster 8k", limit 10.

Use visual-hunt to search_wallpaper_sites for "dark luxury black gold abstract 8k wallpaper", limit 15.

Use visual-hunt to open_xiaohongshu_visual_search for "夏威夷 绝美 海报 壁纸 旅行 摄影", limit 10.

Use visual-hunt to download_candidate_images for project "oahu-poster-board" using the candidates from the last search, limit 5.

Use visual-hunt to extract_manual_page_candidates for the manualPageId from the Xiaohongshu search after I log in or scroll more.

メモ

• ログはstderrのみに書き込まれるため、stdout上のMCP JSON-RPCはクリーンに保たれます。

• Chromeはリモートデバッグを有効にしてすでに実行されている必要があります。

• 出力フォルダはデフォルトでMCPサーバーの現在の作業ディレクトリ下に作成されます。例: /path/to/visual-hunt-mcp/<project>/images。

• 他の場所にダウンロードしたい場合は、VISUAL_HUNT_OUTPUT_ROOTで出力ルートを上書きしてください。

• save_candidates_jsonはメタデータを<output-root>/<project>/candidates.jsonに書き込みます。

• download_candidate_imagesは画像ファイルを<output-root>/<project>/imagesに、マニフェストを<output-root>/<project>/downloads.jsonに書き込みます。

• scripts/smoke-test.mjsは、ローカルサーバープロセスに対してMCPコントラクトをエンドツーエンドで検証する最も迅速な方法です。

• scripts/smoke-test.mjsは、現在のdist/出力を通じてローカルサーバーを検証し、アーティファクト用に一時的な出力ルートを使用します。

• サーバーは認証情報を保存しません。

• サーバーは任意のシェルコマンドを実行しません。

環境変数

スモークテスト以外の手動チェック

製品のライブ/手動支援部分を健全性チェックしたい場合、npm run smokeの後に実行する価値の高いフォローアップは以下の通りです:

• npm run smoke:live

• 日常的に使用する予定のChromeプロファイルでopen_instagram_visual_searchを実行

• ログインが必要な場合は、同じプロファイルでopen_xiaohongshu_visual_searchを実行

• open_google_maps_visual_searchを実行し、手動レビューの注意書きと非バイパス動作が正しく見えるか確認

正確なMacコマンド

cd /Users/lanston/Desktop/Codex/visual-hunt-mcp
npm install
npm run chrome:debug
npm run smoke
npm run smoke:live