reference-search-mcp

Herramienta de uso personal: búsqueda de imágenes de referencia de dibujo para ilustradores. Los agentes de IA de codificación deben leer primero AGENTS.md.

Un servidor MCP de búsqueda de imágenes de referencia pensado para IA: recibe una consulta en lenguaje natural → la convierte en palabras clave → busca en paralelo en varias fuentes de imágenes → elimina las miniaturas duplicadas → compone un mosaico numerado → el modelo multimodal los selecciona mediante llamadas a herramientas (en lugar de JSON en bruto) → el cliente impulsa la iteración (rondas a, b, c…, con deduplicación entre rondas) → al final descarga la imagen completa por su ID y devuelve la ruta del archivo.

调用方 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

¿Por qué los resultados se entregan con «llamadas a herramientas» y no con un JSON estructurado?

La selección que hace el modelo de filtrado sobre el mosaico se expresa con llamadas a funciones como select_images / reject_images / refine_search:

• El esquema de parámetros lo valida el propio proveedor del modelo — por lo tanto es JSON válido de forma natural, sin cercos de markdown, ni prosa intercalada, ni claves irreverentes.

• Expresa varias intenciones de una vez (elegir + rechazar + sugerir la siguiente palabra clave).

• Si el ejecutor recibe un ID no válido (p. ej., a99), devuelve un error y el modelo lo corrige automáticamente en la siguiente ronda.

• Es idéntico a la capa externa de MCP: en la capa externa, el modelo solicitante nos utiliza mediante herramientas, y en la capa interna nosotros utilizamos al modelo mediante herramientas.

La capa LLM se apoya en pi (@earendil-works/pi-ai, MIT): unifica varios proveedores de API (Anthropic / OpenAI / DeepSeek / Gemini / 通义 / Kimi / MiniMax…), resolución automática de credenciales, catálogo de modelos integrado, reintentos y utilidades de reparación de JSON. No introduce un framework pesado de agentes — el LLM del servidor es tan solo tres funciones acotadas (parsear palabras clave / interpretar el idioma / filtrar la imagen), y el bucle de iteración real lo impulsa la IA que hace la llamada.

Inicio rápido

Requisito: Node ≥ 22.19.

npm install --ignore-scripts
npm run build

1. Configurar el LLM (credenciales de pi, elige una de las dos)

# 方式 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

Selección de modelo (opcional):

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

Punto de puntosco personalizado compatible con OpenAI (Qwen-VL / GLM-4V / Ollama, etc.):

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

Modelo de visión de DeepSeek (deepseek-v4-flash-vision-exp, no está en el catálogo integrado de pi, modelo con punto personalizado):

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

Puede usarse sin credenciales de LLM (modo degradado): cuando llames a start/iterate pasas keywords explícitamente, se omite el análisis y el filtrado automáticos y se devuelven todos los candidatos.

2. Configurar las fuentes de imágenes

export PROVIDERS=ddg,bing,wikimedia          # 默认；并行查询
export OPENVERSE_TOKEN=...                   # 启用 openverse（CC 图库）
export SERPER_API_KEY=...                    # 启用 serper（Google 图搜）
export SAFE_SEARCH=true

3. Conectar el cliente 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": "..." }
    }
  }
}

Cliente stdio propio: node dist/index.js, protocolo MCP estándar; las herramientas devuelven bloques de texto JSON.

Doble modo: este MCP es «capacidad visual externalizada»

La esencia de este MCP es darle ojos a un modelo de solo texto: la búsqueda, el mosaico y la numeración son la parte mecánica; el filtrado visual (mirar el mosaico y elegir los números) es la «capacidad visual externalizada». Que el llamante sea multimodal o no decide si el servidor tiene que mirar por él:

collect admite de por sí cualquier ID válido — un llamante multimodal puede ignorar selectedIds y elegir libre por sí mismo. Cada llamada también se puede usar filter: false para anular la configuración global.

Contrato de herramientas

Regla de IDs: letra de ronda + nº de casilla. a3 = ronda 1, casilla 3; b12 = ronda 2, casilla 12. Todas las referencias y colecciones se rigen por esto.

Referencia de configuración

Sección GXP:

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

Pruebas y scripts

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       # 诊断：视觉模型对最近一轮拼图的原始响应

Consideraciones

• Copyright: metadata/manifest transmiten la licencia (incluida por Wikimedia / Openverse); para material comercial, verificación de la autorización de la fuente.

• Protección anti enlaces directos: algunos sitios (como Etsy) rechazan las descargas de terceros; collect informará por ID; si da 403, puedes abrir la URL directamente en el navegador.

• Antirrobot: los adaptadores tienen User-Agent, intervalos de petición y retroceso por reintentos; el fallo de una fuente no derrumba el conjunto.

• Modo degradado: sin credenciales de LLM hay que se explicita keywords y no se filtra automáticamente (devuelve todos los candidatos).