reference-search-mcp
reference-search-mcp
Eigenes Werkzeug: Illustratoren suchen Referenzbilder zum Zeichnen. KI-Code-Agenten lesen zuerst AGENTS.md.
Ein MCP-Server für die Referenzbildsuche für KI-Agenten: nimmt natürlichsprachige Anfragen entgegen → zerlegt sie in Schlüsselwörter → durchsucht mehrere Bildquellen parallel → dedupliziert Thumbnails → setzt sie zu einem nummerierten Rasterbild zusammen → das multimodale Modell filtert über Tool-Aufrufe (statt aus nacktem JSON-Output) → clientgesteuerte Iteration (Runden a, b, c … mit Deduplizierung über die Runden) → lädt das Vollbild anhand der ID herunter und gibt den Dateipfad zurück.
调用方 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.jsonWarum über „Tool-Aufrufe“ liefern statt als strukturiertes JSON?
Die Auswahl des Modells beim Filtern des Rasterbilds wird über Funktionsaufrufe wie select_images / reject_images / refine_search ausgedrückt:
Das Parameterschema wird vom Modellanbieter erzwungen validiert – es ist von Natur aus gültiges JSON, ohne Probleme mit Markdown-Fences, eingesprengte Prosa oder driftende Schlüsselnamen;
Mehrere Absichten werden in einem einzigen Aufruf ausgedrückt (auswählen + verwerfen + Schlüsselwörter für die nächste Runde vorschlagen);
Bei ungültigen IDs (z. B.
a99) meldet der Ausführende einen Fehler, und das Modell korrigiert sich in der nächsten Runde selbst;Analog zur äußeren MCP-Ebene: Außen nutzt die aufrufende KI uns über Tools, innen nutzen wir das Modell über Tools.
Die LLM-Ebene basiert auf pi (@earendil-works/pi-ai, MIT): vereinheitlichte Multi-Provider-API (Anthropic / OpenAI / DeepSeek / Gemini / Tongyi / Kimi / MiniMax …), automatische Anmelde-Erkennung, eingebauter Modellkatalog, Retry- und JSON-Reparatur-Werkzeuge. Es wird kein schwergewichtiges Agent-Framework eingeführt – die serverseitige LLM besteht nur aus drei abgegrenzten Funktionen (Schlagwort-Parsing / Feedback-Interpretation / Raster-Auswahl); die eigentliche Iterationsschleife steuert die aufrufende KI.
Related MCP server: mcp-universal-crawler
Schnellstart
Voraussetzung: Node ≥ 22.19.
npm install --ignore-scripts
npm run build1. LLM konfigurieren (pi-Auth, eines von beiden)
# 方式 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 /loginModellwahl (optional):
export PI_TEXT_MODEL=deepseek/deepseek-chat
export PI_VISION_MODEL=anthropic/claude-sonnet-4-5
export PI_THINKING=off # off|minimal|low|medium|highBenutzerdefinierte OpenAI-kompatible Endpunkte (Qwen-VL / GLM-4V / Ollama usw.):
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-Vision-Modell (deepseek-v4-flash-vision-exp, nicht im pi-eigenen Modellkatalog, daher eigener Endpunkt):
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_KEYAuch ohne LLM-Zugangsdaten nutzbar (Degradationsmodus): bei start/iterate keywords explizit angegeben – die automatische Analyse und Filterung entfallen, alle Kandidaten werden zurückgegeben.
2. Bildquellen konfigurieren
export PROVIDERS=ddg,bing,wikimedia # 默认;并行查询
export OPENVERSE_TOKEN=... # 启用 openverse(CC 图库)
export SERPER_API_KEY=... # 启用 serper(Google 图搜)
export SAFE_SEARCH=true3. MCP-Client anbinden
Claude Code:
{
"mcpServers": {
"reference-search": {
"command": "node",
"args": ["D:/path/to/reference-search-mcp/dist/index.js"],
"env": { "DEEPSEEK_API_KEY": "...", "ANTHROPIC_API_KEY": "..." }
}
}
}Eigener stdio-Client: node dist/index.js, Standard-MCP-Protokoll, die Tools geben JSON-Textblöcke zurück.
Zwei Modi: Dieses MCP = „ausgelagerte visuelle Fähigkeit“
Der Kern dieses MCP ist es, reinen Textmodellen ein Paar Augen zu geben: Suche, Raster und Nummerierung sind der mechanische Teil; die visuelle Auswahl (das Raster ansehen und Nummern wählen) ist die „ausgelagerte visuelle Fähigkeit“. Ob die aufrufende KI multimodal ist, entscheidet, ob der Server für sie schauen muss:
Modus | geeigneter Aufrufer | Server-Verhalten | Interaktion |
| reine Textmodelle | Textschlüsselwortanalyse + visuelle Filterung | liefert |
| multimodale Modelle | nur der mechanische Teil, ruft kein Vision-Modell (spart einen Vision-API-Aufruf) | Pfelefad + alle Kandidatennummern zurück; der Aufrufer sieht sich das Raster selbst an und wählt die IDs selbst |
| beliebig | Wenn ein Vision-Modell eingerichtet ist, wird gefiltert; wenn nicht Fallback | wie server / client |
collect akzeptiert ohnehin jede gültige ID – eine multimodale Aufrufer kann selectedIds ignorieren und selbst wählen. Auch pro Aufruf kann filter: false die globale Konfiguration übersteuern.
Tool-Kontrakt
Tool | Parameter | Rückgabe zugsammenfassung |
|
|
|
|
| nächste Runde |
|
|
|
|
| pro Runde ausgewählt/verworfen, aktuelle Schlüsselwörter, bereits gesammelt |
ID‑Regeln: Runden-Jede Buchstabe + Zellnummer. a3 = Runde 1, Zelle 3; b12 = Runde 2, Zelle 12. Alle Referenzen und Collect richten sich danach.
Konfigurationsübersicht
Variable | Standard | Bedeutung |
|
| Aktivierte Bildquellen, kommasepariert |
| — | Optionale Anmeldedaten von Bildquellen |
| 6 / 8 | 48 Zellen pro Runde; |
| 120 | Sitzungen und temporäre Raster automatisch aufräumen |
| System-Temp / | Verzeichnisse für Daten und Sammelergebnisse |
| 15000 | Abruf-Timeout |
| 3 | Maximale Runden der Tool-Schleife |
|
|
|
| automatische Wahl | LLM-Modellauswahl |
Architektur
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 stateTests und Skripte
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 # 诊断:视觉模型对最近一轮拼图的原始响应Wichtige Hinweise
Lizenz:
metadata/manifestgeben die Lizenz transparent durch (Wikimedia/Openverse bringt eine eigene mit); bei kommerziellen Materialien bitte selbst die Befugnis der Quelle prüfen.Hotlink-Schutz: Manche Sites (z. B. Etsy) verweigern Downloads durch Dritte;
collectmeldet pro ID einen Fehler; bei 403 die URL im Browser öffnen.Scrape-Schutz: Die Adapter sind mit UA, Request-Interval und Retry-Backoff angerichtet; ein Ausfall einer einzelnen Quelle verhindert nicht das Gesamtergebnis.
Degradationsmodus: Ohne LLM-Zugangsdaten nur mit abgesetzten
keywords; keine automatische Auswahl (die ganze Kandidatenliste wird zurückgegeben).
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