reference-search-mcp
reference-search-mcp
自用工具:画师找绘画参考图。AI 编码代理请先读 AGENTS.md。
一个给 AI 用的参考图搜索 MCP 服务器:接收自然语言查询 → 解析为关键词 → 并行搜索多个图源 → 缩略图去重 → 拼成带编号的拼图 → 多模态模型通过工具调用筛选(而不是裸 JSON 输出)→ 客户端驱动迭代(a、b、c… 轮,跨轮去重)→ 按 ID 下载整图并返回文件路径。
调用方 AI (MCP 客户端)
│ image_search_start("找适合播客封面的太空插画素材")
▼
[reference-search-mcp] ┌──────────────────────┐
├─ LLM 层 (pi) NL → 关键词 (submit_keywords 工具) │ 搜索适配器(并行) │
├─ providers DDG / Bing / Wikimedia / Openverse / Serper │ ddg ─┐ │
├─ 去重 pHash(跨轮 seen 集合) │ bing ─┤ 结果合并 │
├─ 拼图 sharp 编号拼图 round-a.png(a1..aN) │ wikimedia ─┘ │
├─ 视觉筛选 pi vision 模型看拼图,调用 select_images / └──────────────────────┘
│ reject_images / refine_search 工具
▼
{ round:"a", gridPath, selectedIds:["a3","a17"], metadata:[...] }
│ image_search_iterate("不要 a3,多找像 b7 的") → round b(重复图自动剔除)
│ image_search_collect(session, ["b1","c12"]) → 本地文件路径 + manifest.json为什么结果用"工具调用"交付,而不是结构化 JSON?
筛选模型对拼图的选择,通过 select_images / reject_images / refine_search 等函数调用表达:
参数 schema 由模型服务商强制校验——天然是合法 JSON,没有 markdown 围栏、散文夹杂、键名漂移问题;
多意图一次表达(选 + 拒 + 建议下一轮关键词);
传了无效 ID(如
a99)时执行器回执错误,模型下一轮自行修正;与 MCP 外层同构:外层是调用方 AI 通过工具用我们,内层是我们通过工具用模型。
LLM 层基于 pi(@earendil-works/pi-ai,MIT):统一多提供商 API(Anthropic / OpenAI / DeepSeek / Gemini / 通义 / Kimi / MiniMax…)、自动认证解析、内置模型目录、重试与 JSON 修复工具。不引入重型 agent 框架——服务器端 LLM 只是三个有界函数(解析关键词 / 解读反馈 / 筛选拼图),真正的迭代循环由调用方 AI 驱动。
Related MCP server: mcp-universal-crawler
快速开始
要求:Node ≥ 22.19。
npm install --ignore-scripts
npm run build1. 配置 LLM(pi 认证,二选一)
# 方式 A:环境变量(任意 pi 支持的提供商)
export DEEPSEEK_API_KEY=sk-... # 文本解析(便宜)
export ANTHROPIC_API_KEY=sk-ant-... # 视觉筛选
# 或 OPENAI_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY ...
# 方式 B:pi 的登录体系(支持订阅制)
npx @earendil-works/pi-coding-agent /login # 或直接 pi /login模型选择(可选):
export PI_TEXT_MODEL=deepseek/deepseek-chat
export PI_VISION_MODEL=anthropic/claude-sonnet-4-5
export PI_THINKING=off # off|minimal|low|medium|high自定义 OpenAI 兼容端点(Qwen-VL / GLM-4V / Ollama 等):
export PI_CUSTOM_PROVIDER_API=openai-completions
export PI_CUSTOM_PROVIDER_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export PI_CUSTOM_PROVIDER_MODELS=qwen-vl-max,qwen-turbo
export PI_CUSTOM_PROVIDER_API_KEY=sk-...DeepSeek 视觉模型(deepseek-v4-flash-vision-exp,不在 pi 内置目录里,走自定义端点):
export DEEPSEEK_API_KEY=sk-...
export PI_TEXT_MODEL=deepseek/deepseek-v4-flash
export PI_VISION_MODEL=deepseek-vision/deepseek-v4-flash-vision-exp
export PI_CUSTOM_PROVIDER_ID=deepseek-vision
export PI_CUSTOM_PROVIDER_API=openai-completions
export PI_CUSTOM_PROVIDER_BASE_URL=https://api.deepseek.com
export PI_CUSTOM_PROVIDER_MODELS=deepseek-v4-flash-vision-exp
export PI_CUSTOM_PROVIDER_API_KEY_ENV=DEEPSEEK_API_KEY没有 LLM 凭据也能用(降级模式):start/iterate 时显式传 keywords,跳过自动解析与筛选,返回全部候选。
2. 配置图源
export PROVIDERS=ddg,bing,wikimedia # 默认;并行查询
export OPENVERSE_TOKEN=... # 启用 openverse(CC 图库)
export SERPER_API_KEY=... # 启用 serper(Google 图搜)
export SAFE_SEARCH=true3. 接入 MCP 客户端
Claude Code:
{
"mcpServers": {
"reference-search": {
"command": "node",
"args": ["D:/path/to/reference-search-mcp/dist/index.js"],
"env": { "DEEPSEEK_API_KEY": "...", "ANTHROPIC_API_KEY": "..." }
}
}
}自研 stdio 客户端:node dist/index.js,标准 MCP 协议,工具返回 JSON 文本块。
双模式:这个 MCP 是"视觉能力外包"
这个 MCP 的本质是给纯文本模型一双眼睛:搜索、拼图、编号是机器部分;视觉筛选(看拼图选编号)是"外包的视觉能力"。调用方是否多模态,决定服务器要不要替它看:
模式 | 适用调用方 | 服务器行为 | 交互 |
| 纯文本模型 | 文本解析关键词 + 视觉筛选 | 返回 |
| 多模态模型 | 只做机械部分,不调用视觉模型(节省视觉 API 开销) | 返回拼图路径 + 全部候选编号,调用方自己看拼图自己选 ID |
| 任意 | 配置了视觉模型就筛,没配就降级 | 同 server / client |
collect 本来就接受任意有效 ID——多模态调用方可以无视 selectedIds 自己挑。每次调用也可用 filter: false 覆盖全局配置。
工具契约
工具 | 入参 | 返回要点 |
|
|
|
|
| 下一轮 |
|
|
|
|
| 各轮选中/拒绝、当前关键词、已收集 |
ID 规则:轮次字母 + 格序号。a3 = 第 1 轮第 3 格,b12 = 第 2 轮第 12 格。所有引用与 collect 均以此为准。
配置参考
变量 | 默认值 | 说明 |
|
| 启用图源,逗号分隔 |
| — | 可选图源凭据 |
| 6 / 8 | 每轮 48 格; |
| 120 | 会话与临时拼图自动清理 |
| 系统 temp / | 数据与收集产物目录 |
| 15000 | 抓取超时 |
| 3 | 内层工具循环最大轮数 |
|
|
|
| 自动挑选 | LLM 模型选择 |
架构
src/
mcp/ # MCP server(stdio)与 4 个工具注册
llm/ # pi-ai 之上的工具调用循环:parseKeywords / interpretFeedback / filterGrid
providers/ # SearchProvider 接口 + ddg/bing/wikimedia/openverse/serper 适配器,并行容错
grid/ # sharp 拼图构建(编号徽章/占位格)、pHash 去重
session/ # 会话状态机(轮次 a/b/c、seen 哈希、TTL 清理)
collect/ # 整图下载(UA/Referer/重试/校验)、manifest 生成
service.ts # 编排:search → dedupe → grid → filter → round state测试与脚本
npm test # 34 个测试:单测 + 真实 MCP stdio 集成测试
npm run smoke -- --query "space nebula" --keywords "nebula,art" --collect "a1,a2" [--iterate "更多星球"]
npm run handshake -- --query "cat" --keywords "cat" # MCP stdio 握手冒烟(先 build)
npx tsx scripts/debug-pi.ts # 诊断:pi 层工具调用(DeepSeek 文本)
npx tsx scripts/debug-vision.ts # 诊断:视觉模型对最近一轮拼图的原始响应注意事项
版权:
metadata/manifest透传 license(Wikimedia/Openverse 自带),商用素材请自行核验来源授权。热链保护:部分站点(如 Etsy)拒绝第三方下载,collect 会逐 ID 报告失败;403 时可用浏览器直接打开 URL。
反爬:适配器带 UA、请求间隔与重试退避;单源失败不影响整体。
降级模式:无 LLM 凭据时需显式传
keywords,且不自动筛选(返回全部候选)。
Available Tools
4 toolsimage_search_collectDownload the full images for chosen cell idsA
Download the full-resolution images for a list of round-qualified ids (e.g. ['a3', 'b12']) to the output directory. Returns local file paths plus a manifest with source URLs and licenses.
Inputs: ids (required), session_id (required).
image_search_iterateIterate on an existing search sessionA
Give feedback referencing round-qualified ids (e.g. 'keep a3, more like b7, no photos') plus optional explicit keywords. Produces the next round (b, c, ...) with dedup against all previously shown images. The LLM interprets the feedback into keyword additions/removals via refine_search.
Inputs: feedback (required), session_id (required), count, filter, +3 more.
image_search_startStart an image search sessionA
Parse a natural-language query into keywords (unless keywords are given), search all configured image providers in parallel, dedupe, render a numbered composite grid (round 'a', cell ids a1..aN), and run a multimodal filter that returns the selected cell ids. Returns the grid file path, the selected ids, the metadata table, and the keywords actually used.
Inputs: query (required), count, filter, criteria, +2 more.
image_search_statusShow session stateB
Rounds so far, per-round selections/rejections, current keywords, and collected ids.
Inputs: session_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a unique and clearly defined role: start initializes a search, iterate refines it with feedback, collect downloads selected results, and status reports the current state. No two tools overlap in purpose.
All tools follow the exact same `image_search_<verb>` pattern, with verbs that accurately describe the action (start, iterate, collect, status). The naming is uniformly styled and predictable.
Four tools is perfectly scoped for an iterative image search workflow. Each tool covers a necessary step without redundancy, making the set concise and well-balanced.
The tools cover the full lifecycle: initiating a search, refining it through feedback, collecting final results, and monitoring progress. No obvious gaps exist for the intended use case, as the start tool integrates search and multimodal filtering.
Maintenance
Related MCP Connectors
Search bilingual image prompts, upload reference images, and generate and download images from your AI agent. OAuth sign-in; image generation uses paid subscription credits. Setup: https://framepond.com/en/agent?utm_source=agent_directory&utm_campaign=agent_launch
Search Google straight from your AI agent. Web results, images, videos, news, products, scholarly ar
Image search for AI agents: 1.85M openly licensed images with source, license and attribution.
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to search, download, and analyze Google images via SerpAPI.320ISC
- AlicenseNot gradedqualityDmaintenanceEnables AI to autonomously search, filter, and download images from the web using natural language commands, with intelligent scoring and local storage.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to perform structured shopping actions and retrieve targeted product images for visual comparison, matching, and aesthetic recommendations.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search the web for images and videos, download them into website projects with automatic optimization, and receive paste-ready HTML snippets, all self-hosted and without API keys.1MIT