visual-hunt-mcp

visual-hunt-mcp는 macOS용 로컬 TypeScript MCP 서버로, 기존 Chrome 세션에 CDP로 연결하여 Codex/Claude가 포스터, 배경화면, 영감 보드를 위한 시각적으로 강력한 이미지 후보를 찾도록 돕습니다.

v0.4.0 · 11개 도구 · 엔드투엔드 감사 완료 · 15/15 행동 테스트 통과 · 실제 10개 주제 스트레스 테스트에서 108개 이미지 다운로드 · 평가 제품군 및 전체 테스트 하네스 포함.

이 서버는 다음을 위해 설계되었습니다:

• McpServer 및 registerTool을 사용하여 공식 @modelcontextprotocol/sdk 활용

• chromium.connectOverCDP(...)를 통해 로컬 Chrome 인스턴스에 연결

• 수동 지원 검토를 선택할 때 로컬에 로그인된 브라우저 프로필 재사용

• 페이월, 로그인 월, CAPTCHA 또는 플랫폼 제어 우회 방지

• 후보 메타데이터 반환 및 선택적으로 MCP 서버의 현재 작업 디렉토리 아래에 생성된 프로젝트 폴더로 이미지 파일 다운로드

CDP를 사용하는 이유

이 프로젝트는 새로운 자동화 브라우저를 실행하는 대신 Chrome DevTools Protocol을 사용하여 MCP 서버가 사용자가 제어하는 로컬 Chrome 프로필을 재사용할 수 있도록 합니다. 이를 통해 브라우저 세션에 이미 로그인된 상태를 유지하면서 MCP 서버는 Mac에서 로컬로 작동하므로 Instagram 및 샤오홍슈(Xiaohongshu) 워크플로우를 더 실용적으로 만들 수 있습니다.

Instagram / 샤오홍슈가 수동 지원 방식인 이유

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