reference-search-mcp

Личный инструмент: художники ищут референсные изображения для рисования. ИИ-агентам для кодирования сначала прочитать AGENTS.md.

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:

• Схема параметров принудительно проверяется провайдером модели — это гарантированно валидный JSON, без проблем с markdown-ограждениями, примесью прозы и «плывущими» именами ключей;

• несколько намерений выражается за раз (выбрать + отклонить + предложить ключевые слова следующего раунда);

• при передаче невалидного ID (например, a99) исполнитель возвращает ошибку — и модель сама исправится в следующем раунде;

• изоморфно внешнему уровню MCP: снаружи вызывающий ИИ «использует» нас через инструменты, а внутри мы используем модель через инструменты.

LLM-слой основан на pi (@earendil-works/pi-ai, MIT): унифицированный API для многих провайдеров (Anthropic / OpenAI / DeepSeek / Gemini / 通义 / Kimi / MiniMax…), автоматический разбор аутентификации, встроенный каталог моделей, повторы и инструменты починки JSON. Без тяжёлых агентских фреймворков — LLM на стороне сервера это лишь три ограниченные функции (разбор ключевых слов / интерпретация фидбека / фильтрация сетки), а настоящий цикл итераций ведёт вызывающий ИИ.

Быстрый старт

Требования: Node ≥ 22.19.

npm install --ignore-scripts
npm run build

1. Настройка 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-совместимый endpoint (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-...

Vision-модель DeepSeek (deepseek-v4-flash-vision-exp, во встроенном каталоге pi нет, подключается через свой endpoint):

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

3. Подключение к 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 — дать чисто текстовой модели глаза: поиск, сборка сетки и нумерация — механическая часть; визуальный отсев (смотреть на сетку и выбирать номера) — «отданное на аутсорс зрение». Мультимодальность вызывающей стороны определяет, будет ли сервер «смотреть» за неё:

collect из коробки принимает любые валидные ID — мультимодальная вызывающая сторона может проигнорировать selectedIds и выбирать сама. При каждом вызове также можно переопределить глобальную конфигурацию через filter: false.

Контракт инструментов

Правила ID: буква раунда + номер клетки. a3 = 3‑й клетка 1‑го раунда, b12 = 12‑й клетка 2‑го раунда. Все ссылки и collect опираются на это.

Конфигурация

Архитектура

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 передают лицензию как есть (Wikimedia/DeepSeek — эта лицензия присуща). Для коммерческих материалов источников направления проверяйте лицензию самостоятельно.

• Возле ссылок: некоторые сайты (например, Etsy) не разрешают скачивать сторонние контентные; при collect будет отчёт об ошибке по каждому ID; при 403 — посмотрите URL вбраузер напрямую.

• Антискрапинг: адаптеры несут UA, интервалы между запросами и ретраи; сбой одного источника не опасен для всего процесса.

• Пониженный режим: без LLM‑ключей требуется яявно передать keywords, при этом автоматическое отсев не выполняется (возвращаются все кандидаты).