visual-hunt-mcp

visual-hunt-mcp ist ein lokaler TypeScript-MCP-Server für macOS, der sich über CDP mit Ihrer bestehenden Chrome-Sitzung verbindet und Codex / Claude dabei hilft, visuell starke Bildkandidaten für Poster, Hintergrundbilder und Inspirationsboards zu finden.

v0.4.0 · 11 Tools · durchgehend geprüft · 15/15 Verhaltenstests bestanden · 108 Bilder in einem realen Stresstest mit 10 Themen heruntergeladen · wird mit Evaluierungssuite und vollständigem Test-Harness geliefert.

Er ist darauf ausgelegt:

• das offizielle @modelcontextprotocol/sdk mit McpServer und registerTool zu verwenden

• sich über chromium.connectOverCDP(...) mit einer lokalen Chrome-Instanz zu verbinden

• Ihr lokales, angemeldetes Browserprofil wiederzuverwenden, wenn Sie sich für eine manuell unterstützte Überprüfung entscheiden

• Paywalls, Login-Wände, CAPTCHAs oder Plattform-Kontrollen nicht zu umgehen

• Kandidaten-Metadaten zurückzugeben und optional Bilddateien in einen Projektordner herunterzuladen, der im aktuellen Arbeitsverzeichnis des MCP-Servers erstellt wird

Warum CDP

Dieses Projekt verwendet das Chrome DevTools Protocol, anstatt einen neuen Automatisierungsbrowser zu starten, damit der MCP-Server ein lokales Chrome-Profil wiederverwenden kann, das Sie kontrollieren. Das macht Workflows für Instagram und Xiaohongshu praktischer, da die Browsersitzung bereits angemeldet sein kann, während der MCP-Server weiterhin lokal auf Ihrem Mac bleibt.

Warum Instagram / Xiaohongshu manuell unterstützt werden

Instagram und Xiaohongshu erfordern oft eine Anmeldung, können das Layout häufig ändern und Inhalte hinter Plattform-Kontrollen verbergen. Dieser MCP öffnet diese Seiten bewusst in Ihrem verbundenen lokalen Chrome und extrahiert nur sichtbare öffentliche Bildkandidaten, sofern verfügbar. Er versucht nicht, Anmeldungen, Ratenbegrenzungen oder Zugriffsbeschränkungen zu umgehen.

Download-Umfang

Dieses Projekt kann jetzt Bilddateien für Quellen wie Unsplash, Pexels, Pixabay, Hintergrundbild-Websites und sichtbare Bild-URLs herunterladen, die bei manuellem, unterstütztem Social Browsing auftauchen, wenn Ihre verbundene Chrome-Sitzung Zugriff hat. Einige Leitplanken gelten weiterhin:

• Von Google gehostete Vorschauen und Google Maps-Bilder bleiben blockiert

• Instagram und Xiaohongshu hängen weiterhin von Ihrem verbundenen Chrome-Anmeldestatus und den tatsächlich sichtbaren Bild-URLs ab, die die Seite preisgibt

• Sie sind weiterhin dafür verantwortlich, die Lizenzierung vor der Wiederverwendung zu prüfen

• save_candidates_json bleibt rein metadatenbasiert, während download_candidate_images Bilddateien sowie ein Download-Manifest schreibt

Funktionen

MCP-Tools (11)

Standard-Quellenset (v0.4.0 kuratiert)

Die Standard-Quellenliste für search_wallpaper_sites wurde in v0.4.0 von 13 auf die 6 Quellen reduziert, die bei >80% der Themen in realen Stresstests herunterladbare Kandidaten lieferten:

1. Unsplash — moderne redaktionelle Fotografie

2. Pexels — moderne redaktionelle Fotografie

3. Pixabay — moderne redaktionelle Fotografie

4. Wikimedia Commons — Sehenswürdigkeiten, Architektur, Public Domain

5. Wallhaven — Top kostenlose 4K/8K-Hintergrundbilder

6. Alpha Coders / Wallpaper Abyss — Top kostenlose 4K/8K-Hintergrundbilder

Adapter für die entfernten Quellen werden weiterhin mitgeliefert – übergeben Sie diese explizit, wenn Sie sie benötigen: sites: ["openverse.org", "loc.gov", "images.nasa.gov", "rawpixel.com", "publicdomainpictures.net", "wallpaperscraft.com", "hdqwalls.com"].

Kandidaten-Bewertung

Jeder Kandidat erhält einen leichten scoreHint basierend auf:

• Bildgröße

• Nähe des Seitenverhältnisses zu gängigen Poster-/Hintergrundbild-Verhältnissen

• Titel- oder Alt-Text-Schlüsselwörter wie poster, cinematic, wallpaper, 4k, 8k, travel, film und landscape

Installation

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

Chrome für MCP starten

npm run chrome:debug

Dieser Helfer bindet das Chrome-Remote-Debugging nur an 127.0.0.1. Er legt den CDP-Port nicht öffentlich offen.

Wenn Sie das Rohskript bevorzugen:

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

Validierungs-Workflow

Führen Sie den deterministischen MCP-Rauchtest aus, nachdem Chrome gestartet wurde:

npm run smoke

Für einen umfassenden Verhaltens-Sweep, der alle 11 Tools abdeckt (Schema-Zwang, Abfrageoptimierung, Lebenszyklus der manuellen Seite, Unterdrückung der Login-Wand, Filter für falsch-positive Ergebnisse, Sicherheitswächter):

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

Was npm run smoke validiert:

• der lokale MCP-Server startet über stdio aus der aktuellen dist/-Ausgabe

• tools/list legt das erwartete Tool-Set offen

• open_url_and_extract_images kann sichtbare Kandidaten aus einer lokalen Fixture-Seite extrahieren

• extract_manual_page_candidates und close_manual_page werden für manuell unterstützte Follow-up-Flows offengelegt

• save_candidates_json schreibt Kandidaten-Metadaten in ein temporäres Ausgabe-Root

• download_candidate_images lädt ein erlaubtes lokales Bild herunter und überspringt einen blockierten, von Google gehosteten Kandidaten mit einem klaren Grund

Der Rauchtest verwendet ein temporäres VISUAL_HUNT_OUTPUT_ROOT und bereinigt es bei Erfolg. Um die Artefakte zur Überprüfung zu behalten:

npm run smoke -- --keep-output

Für einen Durchlauf mit höherer Konfidenz, der auch Live-Google-Bilder und Hintergrundbild-Suchabläufe über Ihre verbundene Chrome-Sitzung abdeckt:

npm run smoke:live

Verwenden Sie npm run validate als stabilen Standard-Validierungsbefehl. Er führt jetzt zuerst npm run build und dann den deterministischen Rauchtest aus.

MCP lokal ausführen

npm run dev

Für den produktionsnahen Einsatz:

npm run build
node dist/index.js

Claude Desktop-Konfiguration

{
  "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"
      }
    }
  }
}

Beispiel-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.

Hinweise

• Protokolle werden nur in stderr geschrieben, damit MCP JSON-RPC auf stdout sauber bleibt.

• Chrome muss bereits mit aktiviertem Remote-Debugging laufen.

• Ausgabeordner werden standardmäßig unter dem aktuellen Arbeitsverzeichnis des MCP-Servers erstellt. Beispiel: /path/to/visual-hunt-mcp/<project>/images.

• Überschreiben Sie das Ausgabe-Root mit VISUAL_HUNT_OUTPUT_ROOT, wenn Sie Downloads woanders speichern möchten.

• save_candidates_json schreibt Metadaten nach <output-root>/<project>/candidates.json.

• download_candidate_images schreibt Bilddateien nach <output-root>/<project>/images und ein Manifest nach <output-root>/<project>/downloads.json.

• scripts/smoke-test.mjs ist der schnellste Weg, den MCP-Vertrag von Ende zu Ende gegen einen lokalen Serverprozess zu validieren.

• scripts/smoke-test.mjs validiert den lokalen Server durch die aktuelle dist/-Ausgabe und verwendet ein temporäres Ausgabe-Root für Artefakte.

• Der Server speichert keine Anmeldedaten.

• Der Server führt keine beliebigen Shell-Befehle aus.

Umgebungsvariablen

Manuelle Überprüfungen über den Rauchtest hinaus

Wenn Sie die Live-/manuell unterstützten Teile des Produkts einer Plausibilitätsprüfung unterziehen möchten, sind dies die wertvollsten Follow-ups nach npm run smoke:

• npm run smoke:live

• open_instagram_visual_search mit demselben Chrome-Profil, das Sie täglich verwenden möchten

• open_xiaohongshu_visual_search mit demselben Profil, falls eine Anmeldung erforderlich ist

• open_google_maps_visual_search, um zu bestätigen, dass der Hinweis zur manuellen Überprüfung und das Verhalten ohne Umgehung weiterhin korrekt aussehen

Genaue Mac-Befehle

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