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 实例

• 在你选择进行人工辅助审查时，复用你本地已登录的浏览器配置文件

• 避免绕过付费墙、登录墙、验证码或平台控制

• 返回候选素材元数据，并可选择将图像文件下载到 MCP 服务器当前工作目录下创建的项目文件夹中

为什么选择 CDP

本项目使用 Chrome DevTools Protocol 而不是启动一个新的自动化浏览器，这样 MCP 服务器就可以复用你所控制的本地 Chrome 配置文件。这使得 Instagram 和小红书的工作流更加实用，因为浏览器会话可以保持已登录状态，而 MCP 服务器仍然保留在你的 Mac 本地。

为什么 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 个来源精简为 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

为 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/ 输出验证本地服务器，并使用临时输出根目录存放工件。

• 服务器不存储凭据。

• 服务器不执行任意 shell 命令。

环境变量

冒烟测试之外的人工检查

当你想要对产品的实时/人工辅助部分进行健全性检查时，这些是 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