reference-search-mcp
This server provides a multi-round, multi-provider image search and collection workflow with visual filtering, dedup, and full-resolution downloads.
Start a new image search session from a natural-language query (or explicit keywords), searching all configured providers in parallel, deduplicating, and rendering a numbered grid with cell ids like a1..aN.
Optionally apply an automated multimodal filter to select relevant cells; returns the grid file path, selected ids, metadata table, and actual keywords used.
Iterate on a session by giving natural-language feedback (e.g. "keep a3, more like b7, no photos") or explicit keyword replacement; produces subsequent rounds (b, c, ...) with dedup against all previously shown images.
Download full-resolution images for chosen round-qualified ids (e.g. a3, b12) to an output directory, returning local file paths plus a manifest with source URLs and licenses.
Check session status to see rounds so far, per-round selections/rejections, current keywords, and collected ids.
Allows searching the Openverse image library as one of the parallel image sources, returning metadata such as title, domain, license, and dimensions alongside the search results.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@reference-search-mcp find reference images of a cyberpunk city street for a painting"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
imgref
自用工具:画师找绘画参考图。AI 编码代理请先读 AGENTS.md; 给 AI 调用方的用法说明在 SKILL.md。
无状态的多图源参考图搜索:一个图源 + 一个查询串 → 一张编号拼图 + 一张候选表。
python3 scripts/imgref.py search wikimedia "M1911 pistol left side" --label side[wikimedia] 'M1911 pistol left side' | 候选 12 → 12 格 | 去重排除 0 | 2.2s
grid: /abs/path/.out/20260915-143556-wikimedia-m1911-pistol/grid.jpg
data: /abs/path/.out/20260915-143556-wikimedia-m1911-pistol/results.json
# size source id
1 2632x1868 commons.wikimedia.org wikimedia|https://upload.wikimedia.org/.../1911A1-JH02.jpg
2 3648x2736 commons.wikimedia.org wikimedia|https://upload.wikimedia.org/.../460Rowland_M1911.jpg
…调用方拿到的就是两个绝对路径:看 grid.jpg(图上有编号),从表里抄 ID 用。
为什么是这个形态
它原本是一个 MCP 服务器,存在的理由是"给纯文本模型外包一双眼睛"。那个理由消失了: 调用方的模型自己就有视觉、自己就是语言模型。于是 LLM 层、会话状态机、 关键词解析、视觉筛选全部删掉——不是搬家,是不需要了。
剩下的是真正有价值的机械管线:多图源异步搜索、编号拼图、aHash 去重、按 ID 取图。 这些都是一次性的无状态处理,一个脚本 + 一份说明就够了。
旧 MCP | 现在 | |
形态 | Node 常驻进程 + config 段 + 改一次要重启 | 一个 Python 脚本 + SKILL.md |
配置 |
| 零 key 零配置 |
谁做编排 | 服务端的会话状态机(轮次 a/b/c、TTL、分组) | 调用方 AI,自己并发自己挑 |
依赖 | Node + sharp + pi-ai | Python 3.10+ + httpx + Pillow |
Related MCP server: mcp-universal-crawler
命令
imgref search <provider> "<query>" [options] 搜索 → 编号拼图 + 候选表
imgref preview <id>... 按 ID 取图到缓存目录(可降采样)
imgref download <id>... --out DIR 按 ID 取全分辨率原图
imgref montage <results.json>... --out FILE 把多轮拼图合并成一张(helper)preview/download都是多选:位置参数给多个、--ids-file、或--pick 1,3,7 --from <manifest>。配合
--from取图时,落盘文件名以拼图编号开头(03-colt_m1911.png),与图上的数字一致; 没给--from就不知道编号,此时不加数字前缀。--exclude <旧 manifest>按 aHash 排除上一轮出现过的图(迭代重搜用)。imgref search --help看图源索引;imgref search <provider> --help看该图源的专属参数。
帮助文本刻意分成三段,回答"哪些参数所有图源共用、哪些是某个图源专属":
全局参数(所有命令共用):
--cache-dir / --no-cache / --timeout / --proxy / --concurrency / -v / -q
搜索参数(所有图源共用):
--out / --keep / --limit / --label / --cols / --rows / --cell / --max-edge / --exclude / --no-json
bing 专属参数(来自 Bing):
--safe {off,moderate,strict} 成人内容过滤级别(默认 moderate)图源
八个,全部零 key(serper 除外)。查询串的写法分两类:booru 标签和自然语言。
provider | 适合 | 查询串 | 原图尺寸 | 备注 |
| 插画 / 背景 / 角色参考 | booru 标签 | ✅ 声明 | 官方 API;默认 |
| 插画参考(站点只收 SFW) | booru 标签 | ✅ 声明 | Gelbooru 0.2 API |
| 中文图片站(照片 / 壁纸) | 中文自然语言 | ✅ 声明 | 非官方 napi |
| 公共领域照片、图纸、史料 | 自然语言 | ✅ 声明 | 官方 API,带版权 |
| CC 授权图库 | 自然语言 | ✅ 声明 | 匿名可用 |
| 通用网络图片 | 自然语言 | ❌ 不声明 | 抓取型,可能被反爬 |
| 通用网络图片 | 自然语言 | ✅ 声明 | 抓取型, |
| 谷歌图片 | 自然语言 | ✅ 声明 | 需 |
尺寸列写 2632x1868 是图源声明的原图尺寸;写 ~474x308 说明该图源没声明原图尺寸,
给的是缩略图实测尺寸(bing 就是这种)。
booru 类(yandere / safebooru)用的是站内标签词表,各家不通用——scenery 在
safebooru 有六万多张、在 yande.re 根本不存在。所以这两个图源会在搜索前逐个校验标签:
全不存在就报错并给出相近标签,部分不存在就说明后改用剩下的。不会让你对着静默的
「0 条」猜。
校验很便宜:单标签精确查 0.1KB / ~0.5s。而"拉全量标签表"这条路实测走不通—— yande.re 全量 9.8MB / 8.4s,safebooru 没有全量接口(1000 条/页,上百万标签)。
设计要点
ID 自包含:<provider>|<image_url>。拼图上的数字只是给眼睛的抓手,
不是 ID——数字离开那张图就没有意义,而 ID 可以单独复制、单独传递、单独解析。
preview / download 因此完全不需要 manifest。
无状态:没有会话、没有轮次、没有 TTL。跨轮去重靠调用方显式传 --exclude。
缓存不是状态:删掉缓存只影响快慢,不改变任何结果(跟热着的 TCP 连接同级)。
编排归调用方:一次调用只做一件事。要 3 个角度就发 3 条命令,
要合并就显式 montage。脚本里没有"批量"这个概念。
拼图按视觉模型的预算做:默认 4×3、每格 375px → 画布 1536×1310,
正好顶满 1536 长边。再大只会被降采样,白扔算力。编号画在每格底部的黑条上
(不盖主体、字号开到 0.78×条高),JPEG 用 subsampling=0 保证文字不糊。
图上只画 ASCII:Pillow 默认字体渲染不了中文,为了中文标签去背一个 CJK 字体 又会毁掉"零字体依赖"。所以分组/域名等文字只保留 ASCII,中文说明放在 stdout 表和 JSON 里。
图源 = Protocol,不是继承:一个图源就是一个普通类,
声明 name / label / args / requires + 实现 async def search(...) 即可,
连基类都不用继承(Protocol 在注册表那里做静态检查)。
可选能力(headers_for 决定 referer/UA、parse_options 解析私有参数)
用独立的小 Protocol 表达——框架完全不知道 referer 是什么东西。
分页是不透明游标:谁家按 page、谁家按 offset、谁家给 continuation token
(wikimedia 给的就是个 JSON 对象)、ddg 甚至直接把 next URL 塞进游标,
全被适配器吞掉;框架只做 cursor = page.next_cursor。
加一个图源
# imgref/providers/example.py —— 没有 class 继承,没有 super()
class Example:
name: str = "example"
label: str = "示例图源(无需 key)"
args: Sequence[Arg] = (Arg("--mode", choices=("fast", "full"), default="fast", help="……"),)
requires: Sequence[str] = ()
def parse_options(self, ns: Namespace) -> Options: ... # 可选
def headers_for(self, url: str) -> Mapping[str, str]: ... # 可选:referer/cookie/UA
async def search(self, ctx: Ctx, query: str, *, limit: int, cursor: Cursor | None, opts: Options) -> Page:
payload = await ctx.get_json("https://api.example.com/search", params={"q": query, "n": limit})
return Page([...], next_cursor=None)然后把实例加进 imgref/providers/__init__.py 的 _ALL 元组——那一行就是静态检查点,
mypy 会核对它是否满足 Provider 协议。帮助文本会自动出现(含"专属参数"分组)。
环境管理
scripts/imgref.py 是个自举入口:它只在标准库上运行,检测到 .venv 缺失或
requirements.txt 变了,就建环境 + pip install --only-binary=:all:,然后
POSIX 用 os.execv 替换当前进程(内存不叠加)、Windows 用子进程带原样退出码。
带 IMGREF_BOOTSTRAPPED=1 护栏防止无限自举,建环境时用 O_CREAT|O_EXCL 锁防止并发撞坏。
依赖全落在技能自己的 .venv 里,全局零污染;日常调用就是
python3 scripts/imgref.py ...,不需要任何前缀。
自举入口在下面这些环境实测过(全局环境都保持干净):
环境 | 首次运行 | 之后每次 |
Windows 11 + Python 3.10.17(最低版本) | 14.3s(建 venv + 装依赖) | 0.23s |
Windows 11 + Python 3.13.3 | 11.5s | 0.22s |
| 30.6s | 0.77s |
| 32.0s | — |
另外验证过:3 个进程同时首次自举只会建一次环境(锁生效);Python 3.8 会被护栏 挡住并给出可操作提示,而不是抛出语法错误。
装依赖用 --only-binary=:all:(不在小内存机器上触发本地编译);两个依赖在
glibc 和 musl 上都有现成 wheel。若将来引入只有源码包的依赖,这一条会拦下它。
开发
uv venv --python 3.10 --seed .venv # 按最低支持版本建环境,能挡住用高版本语法
uv pip install --python .venv/Scripts/python.exe -r requirements-dev.txt # POSIX 用 .venv/bin/python
.venv/Scripts/python.exe -m mypy # strict,48 个文件
.venv/Scripts/python.exe -m pytest # 273 个用例,全部离线
.venv/Scripts/python.exe scripts/smoke.py wikimedia "M1911 pistol" --download # 真机 smoke语言级别 Python 3.10+(mypy 也按 3.10 校验),mypy --strict,全部公开函数
带完整类型标注与 docstring。测试用 httpx.MockTransport 注入假网络、用确定性生成的
图片做夹具,不联网。
验证状态与已知问题
真实网络下端到端跑通过:
wikimedia:搜索 12 张 M1911 → 编号拼图 → 目视校对 →preview降采样 →download拿到 2220×1488 原图 → 三个不同角度的搜索用montage合并成 12 格。--exclude:用上一轮 manifest 重搜同一查询,12 张全部被 aHash 命中排除(退出码 2)。mypy --strict全绿;pytest273 passed(Python 3.10 与 3.13 各跑一遍)。
图源可用性取决于出网环境(地区、代理、对方的反爬策略),不是代码问题:
bing/ddg是抓取型接口,部分网络下会失效:bing会返回与查询无关的图,ddg的i.js直接 403。遇到就换--provider,或配HTTPS_PROXY。 注意这类失败不会报错——只会给你错的图。openverse在部分网络下会超时。wikimedia是官方 API,最稳;但它要求带说明的 User-Agent(本项目默认就是), 伪装浏览器会被 403。
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