Skip to main content
Glama

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 на стороне сервера это лишь три ограниченные функции (разбор ключевых слов / интерпретация фидбека / фильтрация сетки), а настоящий цикл итераций ведёт вызывающий ИИ.

Related MCP server: mcp-universal-crawler

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

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

Режим

Вызывающая сторона

Поведение сервера

Взаимодействие

server (FILTER_MODE=server)

чисто текстовая модель

текстовый разбор ключевых слов + визуальная фильтрация

возвращает selectedIds + reasons («отчёт о просмотре картинок» визуальной модели)

client (FILTER_MODE=client или filter: false)

мультимодальная модель

только механическая часть, без вызова визуальной модели (экономия одного визуального API‑вызова)

возвращает путь к сетке + все номера кандидатов; вызывающая сторона сама смотрит сетку и сама выбирает ID

auto (по умолчанию)

любая

есть визуальная модель — отсеивает, нет — пониженный режим

как server / client

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

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

Инструмент

Входные параметры

Основные возвращаемые данные

image_search_start

query, keywords?, criteria?, count?, safe_search?, filter?

session_id, round:"a", grid_path, filtered, selected_ids, metadata (номер → title/домен/license/размеры/URL), keywords_used, warnings

image_search_iterate

session_id, feedback (может ссылаться на a3/b12), keywords?, filter? , многие другие

следующий раунд round:"b"…; p‑Hash дедуп между раундами (dedupe_skipped); LLM через refine_search уточняет ключеви

image_search_collect

session_id, ids:["b1","c12"]

files (локальные пути/URL/license/ширина и высота), manifest_path, failures (по каждому ID)

image_search_status

session_id

отбор/отколк по каждому раунду, текущие ключевые слова, уже собранное

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

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

Переменная

По умолчанию

Описание

PROVIDERS

ddg,bing,wikimedia

включённые источники изображений, через запятую

OPENVERSE_TOKEN / SERPER_API_KEY

—

опциональные ключи для источников

GRID_COLUMNS / GRID_ROWS

6 / 8

48 клеток за круг; GRID_CELL_SIZE по умолчанию 256px

SESSION_TTL_MINUTES

120

автоочистка сессий и временных сеток

DATA_DIR / OUT_DIR

системный temp / ./out

каталоги данных и собранного результата

HTTP_TIMEOUT_MS

15000

таймаут получения

LLM_MAX_TURNS

3

максимум кругов внутреннего цикла инструментов

FILTER_MODE

auto

auto | server | client (см. «Два режима»)

PI_TEXT_MODEL / PI_VISION_MODEL / PI_THINKING

выбираются автоматически

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

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

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

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

Available Tools

4 tools
image_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

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers