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.json

Warum ü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.

Schnellstart

Voraussetzung: Node ≥ 22.19.

npm install --ignore-scripts
npm run build

1. 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 /login

Modellwahl (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|high

Benutzerdefinierte 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_KEY

Auch 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=true

3. 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:

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

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

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 state

Tests 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/manifest geben 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; collect meldet 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).