visual-hunt-mcp

visual-hunt-mcp es un servidor MCP local en TypeScript para macOS que se conecta a tu sesión de Chrome existente a través de CDP y ayuda a Codex / Claude a encontrar candidatos de imágenes visualmente potentes para pósteres, fondos de pantalla y tableros de inspiración.

v0.4.0 · 11 herramientas · auditado de extremo a extremo · 15/15 pruebas de comportamiento superadas · 108 imágenes descargadas en una prueba de estrés del mundo real con 10 temas · se entrega con suite de evaluación y arnés de pruebas completo.

Está diseñado para:

• utilizar el @modelcontextprotocol/sdk oficial con McpServer y registerTool

• conectarse a una instancia local de Chrome mediante chromium.connectOverCDP(...)

• reutilizar tu perfil de navegador local con sesión iniciada cuando elijas realizar una revisión asistida manualmente

• evitar eludir muros de pago, muros de inicio de sesión, CAPTCHA o controles de plataforma

• devolver metadatos de candidatos y, opcionalmente, descargar archivos de imagen en una carpeta de proyecto creada bajo el directorio de trabajo actual del servidor MCP

Por qué CDP

Este proyecto utiliza el Protocolo de DevTools de Chrome en lugar de iniciar un navegador de automatización nuevo, para que el servidor MCP pueda reutilizar un perfil local de Chrome que tú controlas. Esto hace que los flujos de trabajo de Instagram y Xiaohongshu sean más prácticos porque la sesión del navegador ya puede tener la sesión iniciada, mientras que el servidor MCP permanece local en tu Mac.

Por qué Instagram / Xiaohongshu son asistidos manualmente

Instagram y Xiaohongshu a menudo requieren inicio de sesión, pueden cambiar el diseño con frecuencia y pueden restringir el contenido detrás de controles de plataforma. Este MCP abre deliberadamente esas páginas en tu Chrome local conectado y solo extrae candidatos de imágenes públicas visibles cuando están disponibles. No intenta eludir el inicio de sesión, los límites de velocidad ni las restricciones de acceso.

Alcance de la descarga

Este proyecto ahora puede descargar archivos de imagen para fuentes como Unsplash, Pexels, Pixabay, sitios de fondos de pantalla y URLs de imágenes visibles que surgen de la navegación social asistida manualmente cuando tu sesión de Chrome conectada tiene acceso. Aún se aplican algunas medidas de seguridad:

• Las vistas previas alojadas en Google y las imágenes de Google Maps permanecen bloqueadas

• Instagram y Xiaohongshu aún dependen del estado de inicio de sesión de tu Chrome conectado y de las URLs de imágenes visibles que la página realmente expone

• sigues siendo responsable de verificar las licencias antes de reutilizarlas

• save_candidates_json sigue siendo solo de metadatos, mientras que download_candidate_images escribe archivos de imagen además de un manifiesto de descarga

Características

Herramientas MCP (11)

Conjunto de fuentes predeterminado (v0.4.0 curado)

La lista de fuentes predeterminada de search_wallpaper_sites se redujo en la v0.4.0 de 13 fuentes a las 6 que devolvieron candidatos descargables en >80% de los temas en pruebas de estrés del mundo real:

1. Unsplash — fotografía editorial moderna

2. Pexels — fotografía editorial moderna

3. Pixabay — fotografía editorial moderna

4. Wikimedia Commons — monumentos, arquitectura, dominio público

5. Wallhaven — mejores fondos de pantalla 4K/8K gratuitos

6. Alpha Coders / Wallpaper Abyss — mejores fondos de pantalla 4K/8K gratuitos

Los adaptadores para las fuentes eliminadas todavía se incluyen; pásalos explícitamente cuando los necesites: sites: ["openverse.org", "loc.gov", "images.nasa.gov", "rawpixel.com", "publicdomainpictures.net", "wallpaperscraft.com", "hdqwalls.com"].

Puntuación de candidatos

Cada candidato obtiene un scoreHint ligero basado en:

• tamaño de la imagen

• proximidad de la relación de aspecto a las relaciones comunes de pósteres / fondos de pantalla

• palabras clave en el título o texto alternativo como poster, cinematic, wallpaper, 4k, 8k, travel, film y landscape

Instalación

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

Iniciar Chrome para MCP

npm run chrome:debug

Este asistente vincula la depuración remota de Chrome solo a 127.0.0.1. No expone el puerto CDP públicamente.

Si prefieres el script sin procesar:

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

Flujo de trabajo de validación

Ejecuta la prueba de humo determinista de MCP después de que Chrome esté activo:

npm run smoke

Para un barrido de comportamiento integral que cubra las 11 herramientas (coerción de esquema, optimización de consultas, ciclo de vida de la página manual, supresión de muros de inicio de sesión, filtros de falsos positivos, guardias de seguridad):

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

Lo que valida npm run smoke:

• el servidor MCP local se inicia sobre stdio desde la salida actual de dist/

• tools/list expone el conjunto de herramientas esperado

• open_url_and_extract_images puede extraer candidatos visibles de una página de prueba local

• extract_manual_page_candidates y close_manual_page se exponen para flujos de seguimiento asistidos manualmente

• save_candidates_json escribe metadatos de candidatos en una raíz de salida temporal

• download_candidate_images descarga una imagen local permitida y omite un candidato alojado en Google bloqueado con una razón clara

La prueba de humo utiliza una VISUAL_HUNT_OUTPUT_ROOT temporal y la limpia al tener éxito. Para mantener los artefactos para su inspección:

npm run smoke -- --keep-output

Para una aprobación de mayor confianza que también acceda a Google Images en vivo y flujos de búsqueda de fondos de pantalla a través de tu sesión de Chrome conectada:

npm run smoke:live

Usa npm run validate como el comando de validación predeterminado estable. Ahora ejecuta npm run build primero y luego la prueba de humo determinista.

Ejecutar MCP localmente

npm run dev

Para uso de estilo de producción:

npm run build
node dist/index.js

Configuración de 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"
      }
    }
  }
}

Ejemplos de prompts

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.

Notas

• Los registros se escriben solo en stderr para que el JSON-RPC de MCP en stdout permanezca limpio.

• Chrome ya debe estar ejecutándose con la depuración remota habilitada.

• Las carpetas de salida se crean bajo el directorio de trabajo actual del servidor MCP de forma predeterminada. Ejemplo: /path/to/visual-hunt-mcp/<project>/images.

• Anula la raíz de salida con VISUAL_HUNT_OUTPUT_ROOT si deseas las descargas en otro lugar.

• save_candidates_json escribe metadatos en <output-root>/<project>/candidates.json.

• download_candidate_images escribe archivos de imagen en <output-root>/<project>/images y un manifiesto en <output-root>/<project>/downloads.json.

• scripts/smoke-test.mjs es la forma más rápida de validar el contrato MCP de extremo a extremo contra un proceso de servidor local.

• scripts/smoke-test.mjs valida el servidor local a través de la salida actual de dist/ y utiliza una raíz de salida temporal para los artefactos.

• El servidor no almacena credenciales.

• El servidor no ejecuta comandos de shell arbitrarios.

Variables de entorno

Comprobaciones manuales más allá del humo

Cuando desees verificar las partes en vivo/asistidas manualmente del producto, estos son los seguimientos de mayor valor después de npm run smoke:

• npm run smoke:live

• open_instagram_visual_search con el mismo perfil de Chrome que planeas usar día a día

• open_xiaohongshu_visual_search con ese mismo perfil si se requiere inicio de sesión

• open_google_maps_visual_search para confirmar que la nota de revisión manual y el comportamiento de no elusión siguen pareciendo correctos

Comandos exactos para Mac

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