Skip to main content
Glama
deenesjakoruzh
naer-lily

reference-search-mcp

by naer-lily
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

reference-search-mcp

自分用のツール：絵師が絵の参考を探すためのものです。AI コーディングエージェントは先に AGENTS.md を読んでください。

AI から使われる参考図検索 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 の外側と同じ構造です。外側では呼び出し側の AI がツールを通じて私たちを使い、内側では私たちがツールを通じてモデルを使います。

LLM レイヤーは pi（@earendil-works/pi-ai、MIT）に基づいています。複数プロバイダーのAPI（Anthropic / OpenAI / DeepSeek / Gemini / 通义 / Kimi / MiniMax…）を統一し、認証の自動解決、組み込みのモデルカタログ、リトライと JSON の修理ツールを提供します。重装備のエージェントフレームワークは導入していません。サーバー側の LLM は、キーワード解析・フィードバック解釈・グリッド選出という3つの限定的な関数だけを担い、実際の反復ループは呼び出し側の AI が駆動します。

クイックスタート

要件：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 互換エンドポイント（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-...

DeepSeek ビジョンモデル（deepseek-v4-flash-vision-exec、pi の組み込みカタログに存在しないため、自作エンドポイントを利用）：

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 を1回節約）

グリッド画像のパスと全候補の番号を返し、呼び出し側は自ら見て、自分で ID を選ぶ

auto（デフォルト）

任意

視覚モデルの設定があれば選定、なければフォールバック

server / client と同様

collect はそもそも任意の有効な ID を受け取れます。マルチモーダルの呼び出し側は selectedIds を無視して自分で選ぶこともできます。また、各呼び出しでも filter: false で全体指定を上書きできます。

ツール契約

ツール

引数

戻り値のポイント

image_search_start

query、keywords、criteria、count、safe_searc、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"…；ラウンド間の pHash 重複スキップ（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＝第1ラウンドの3番目、b12＝第2ラウンドの12番目です。すべての参照と 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/Openverse が提供）をそのまま通します。商用素材はご自身で配元の認証を確認してください。

  • ホットリンク保護：一部のサイト（Etsy など）は第三者のダウンロードを拒否します。collect は ID ごとに失敗を報告します。403 の場合はブラウザで直接 URL を開いてください。

  • 巡回対策：アダプタは UA、リクエスト間隔、リトライ回避を備えています。単一のソースが失敗しても全体には影響しません。

  • フォールバックモード：LLM 資格情報がない場合、keywords を明示的に渡す必要があり、自動的なフィルタリングは行われません（全候補が返されます）。

This server cannot be installed

-
license - not tested
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • Curio — design style library

    A design-style library for AI agents: search real styles, fetch a ready-to-apply design spec.

  • mcp

    Generate images, GIFs, and PDFs from HTML, URLs, or templates — from your AI agent.

  • limner

    AI visual generation agent: multi-pipeline rendering, prompt crafting, and image composition.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/naer-lily/reference-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server