visual-hunt-mcp

visual-hunt-mcp — это локальный TypeScript MCP-сервер для macOS, который подключается к вашему текущему сеансу Chrome через CDP и помогает Codex / Claude находить визуально сильные изображения для плакатов, обоев и досок вдохновения.

v0.4.0 · 11 инструментов · сквозной аудит · 15/15 пройденных поведенческих тестов · 108 изображений загружено в ходе стресс-теста по 10 темам · поставляется с набором для оценки и полной тестовой обвязкой.

Он разработан для того, чтобы:

• использовать официальный @modelcontextprotocol/sdk с McpServer и registerTool

• подключаться к локальному экземпляру Chrome через chromium.connectOverCDP(...)

• повторно использовать ваш локальный профиль браузера, когда вы выбираете ручной просмотр

• избегать обхода платных стен, экранов входа, CAPTCHA или ограничений платформы

• возвращать метаданные кандидатов и при необходимости загружать файлы изображений в папку проекта, созданную в текущей рабочей директории MCP-сервера

Зачем нужен CDP

Этот проект использует протокол Chrome DevTools вместо запуска отдельного браузера для автоматизации, поэтому MCP-сервер может повторно использовать локальный профиль Chrome, который вы контролируете. Это делает рабочие процессы в Instagram и Xiaohongshu более практичными, так как сеанс браузера может быть уже авторизован, в то время как MCP-сервер остается локальным на вашем Mac.

Почему Instagram / Xiaohongshu требуют ручного участия

Instagram и Xiaohongshu часто требуют входа в систему, могут часто менять макет и скрывать контент за элементами управления платформы. Этот MCP намеренно открывает эти страницы в вашем подключенном локальном Chrome и извлекает только видимые общедоступные изображения, когда они доступны. Он не пытается обойти вход в систему, ограничения по частоте запросов или ограничения доступа.

Область загрузки

Этот проект теперь может загружать файлы изображений из таких источников, как Unsplash, Pexels, Pixabay, сайты с обоями, а также видимые URL-адреса изображений, полученные в ходе ручного просмотра, когда ваш подключенный сеанс Chrome имеет к ним доступ. По-прежнему действуют некоторые ограничения:

• превью, размещенные на Google, и изображения Google Maps остаются заблокированными

• Instagram и Xiaohongshu по-прежнему зависят от состояния вашего входа в Chrome и от того, какие URL-адреса изображений фактически отображаются на странице

• вы по-прежнему несете ответственность за проверку лицензирования перед повторным использованием

• save_candidates_json по-прежнему работает только с метаданными, в то время как download_candidate_images записывает файлы изображений и манифест загрузки

Функции

Инструменты MCP (11)

Набор источников по умолчанию (v0.4.0)

Список источников по умолчанию для search_wallpaper_sites был сокращен в v0.4.0 с 13 до 6, которые возвращали загружаемых кандидатов для более чем 80% тем в ходе стресс-тестирования:

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, основанный на:

• размере изображения

• близости соотношения сторон к распространенным форматам плакатов / обоев

• ключевых словах в заголовке или alt-тексте, таких как poster, cinematic, wallpaper, 4k, 8k, travel, film и landscape

Установка

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

Запуск Chrome для MCP

npm run chrome:debug

Этот помощник привязывает удаленную отладку Chrome только к 127.0.0.1. Он не открывает порт CDP публично.

Если вы предпочитаете исходный скрипт:

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

Рабочий процесс проверки

Запустите детерминированный дымовой тест MCP после запуска Chrome:

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-сервер запускается через stdio из текущего вывода dist/

• 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

Для более уверенного прохождения, которое также затрагивает реальные потоки Google Images и поиска обоев через ваш подключенный сеанс Chrome:

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, чтобы JSON-RPC MCP в stdout оставался чистым.

• 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

• open_instagram_visual_search с тем же профилем Chrome, который вы планируете использовать ежедневно

• 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