Search Images (Research)

researchmcp-research_image_search

Search EDITED Research articles for images by meaning.

Returns image-level hits — each carries a URL, caption, and a session-scoped image_id. Use after research_article_search (passing report_ids to restrict by article) when visual content is needed, or stand-alone for visually-themed queries like "denim runway looks".

Ranking is automatic: a blend of relevance, recency, and — when you supply the optional intent axes — taxonomy match. The score on each hit is this composite value, not a raw relevance number and not comparable across tools.

Parameters: query: Natural language search query. report_ids: Restrict to specific report ids. Omit to search the full corpus. start_date: Inclusive lower bound, YYYY-MM-DD. end_date: Inclusive upper bound, YYYY-MM-DD. k: Number of images to return. Default 5, bounded 1..10. article_types, topics, gender, season, year, moments: optional intent axes that bias ranking; year/moments also inform the time window when no explicit dates are given.

Try queries like

"denim runway looks", "store window displays", "sneaker product shots", "SS25 colour charts".

Parameters

Name	Type	Required	Constraints	Description
`query`	`string`	yes	—	Natural language search query for finding images within reports.
`report_ids`	`integer[] \| null`	no	default: `null`	Constrain the search to specific articles — pass `report_id` values returned by `research_article_search`. Omit to search the full corpus.
`start_date`	`string \| null`	no	default: `null`	Inclusive start date (YYYY-MM-DD).
`end_date`	`string \| null`	no	default: `null`	Inclusive end date (YYYY-MM-DD).
`k`	`integer`	no	default: `5` · 1–10	Number of images to return. Default 5, max 10.
`article_types`	`string[] \| null`	no	default: `null`	Editorial-format slugs the query is about, to bias ranking toward matching reports (e.g. 'forecasting', 'trend-analysis', 'street-style'). Optional; unknown values are ignored. Populate from research_analyze_query.intent.article_types or your own reasoning.
`topics`	`string[] \| null`	no	default: `null`	Subject-matter slugs to bias ranking toward (e.g. 'denim-fabric', 'footwear', 'color', 'sustainability'). Optional; unknown values are ignored.
`gender`	`string[] \| null`	no	default: `null`	Audience slugs to bias ranking toward: 'men', 'women', 'children', 'mid-mature'. Optional; unknown values are ignored.
`season`	`string[] \| null`	no	default: `null`	Retail-season slugs to bias ranking toward: 'spring-summer', 'fall-winter', 'pre-spring', 'pre-fall'. A ranking signal only — never converted to a date filter. Optional; unknown values are ignored.
`year`	`string[] \| null`	no	default: `null`	Four-digit year(s) the query targets (e.g. ['2025']). Biases ranking and, when no explicit start/end date is given, narrows the time window to those years. Optional; values outside 2000-2099 are ignored.
`moments`	`string[] \| null`	no	default: `null`	Named retail-moment slugs the query targets (e.g. 'black-friday', 'valentines-day', 'holiday-season'). Biases ranking and, when no explicit start/end date is given, contributes a recent time window. Optional; unknown values are ignored.

Returns

On success: {"total": int, "images": list[ImageHit]}. Each hit carries
report_id, title, date, score, url, caption, copyright
(image attribution string such as "Launchmetrics/Spotlight", or null),
format (png/jpeg/webp/jpg or null), and image_id.
On retrieval failure: {"error": str}.
image_id is an opaque id assigned when the image is indexed — fetch it back
with research_get_image within the same session. It is not durable across
re-ingestion (the hourly cron reassigns ids when a report is modified), so
don't persist it beyond the session.

Try it

Loading interactive widget…

Code examples

curl
TypeScript
Python

curl -s https://mcp.edited.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "x-api-key: $MCP_API_KEY" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "researchmcp-research_image_search",
    "arguments": {
      "query": "Nike",
      "report_ids": null,
      "start_date": null,
      "end_date": null,
      "k": 5,
      "article_types": null,
      "topics": null,
      "gender": null,
      "season": null,
      "year": null,
      "moments": null
    }
  }
}'

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "demo", version: "1.0.0" }, { capabilities: {} });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://mcp.edited.com/mcp"), {
    requestInit: { headers: { "x-api-key": process.env.MCP_API_KEY ?? "" } },
  }),
);

const result = await client.callTool({
  name: "researchmcp-research_image_search",
  arguments: {
    "query": "Nike",
    "report_ids": null,
    "start_date": null,
    "end_date": null,
    "k": 5,
    "article_types": null,
    "topics": null,
    "gender": null,
    "season": null,
    "year": null,
    "moments": null
  },
});

import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

headers = {"x-api-key": os.environ["MCP_API_KEY"]}
async with streamablehttp_client("https://mcp.edited.com/mcp", headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "researchmcp-research_image_search",
            {"query": "Nike", "report_ids": None, "start_date": None, "end_date": None, "k": 5, "article_types": None, "topics": None, "gender": None, "season": None, "year": None, "moments": None},
        )

Input schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Natural language search query for finding images within reports.",
      "type": "string"
    },
    "report_ids": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Constrain the search to specific articles — pass `report_id` values returned by `research_article_search`. Omit to search the full corpus."
    },
    "start_date": {
      "anyOf": [
        {
          "format": "date",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive start date (YYYY-MM-DD)."
    },
    "end_date": {
      "anyOf": [
        {
          "format": "date",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive end date (YYYY-MM-DD)."
    },
    "k": {
      "default": 5,
      "description": "Number of images to return. Default 5, max 10.",
      "maximum": 10,
      "minimum": 1,
      "type": "integer"
    },
    "article_types": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Editorial-format slugs the query is about, to bias ranking toward matching reports (e.g. 'forecasting', 'trend-analysis', 'street-style'). Optional; unknown values are ignored. Populate from research_analyze_query.intent.article_types or your own reasoning.",
      "items": {
        "enum": [
          "trend-analysis",
          "trends-by-season",
          "trends-by-city",
          "street-style",
          "retailer-messaging",
          "buyers-guide",
          "consumer-moments",
          "hindsighting",
          "consumer-strategy",
          "forecasting",
          "product-newness",
          "collections-by-city",
          "events-opportunities",
          "messaging-calendars",
          "assortment-pricing",
          "site-merchandising-promotion"
        ],
        "type": "string"
      }
    },
    "topics": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Subject-matter slugs to bias ranking toward (e.g. 'denim-fabric', 'footwear', 'color', 'sustainability'). Optional; unknown values are ignored.",
      "items": {
        "enum": [
          "footwear",
          "accessories",
          "pricing-discounting",
          "denim-fabric",
          "color",
          "bottoms",
          "active-sports",
          "subcultures",
          "print-licensing",
          "intimates-swimwear",
          "tops",
          "outerwear",
          "details-trims",
          "diversity-inclusion",
          "dresses",
          "sustainability",
          "generation-demographic",
          "knitwear",
          "tailoring"
        ],
        "type": "string"
      }
    },
    "gender": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Audience slugs to bias ranking toward: 'men', 'women', 'children', 'mid-mature'. Optional; unknown values are ignored.",
      "items": {
        "enum": [
          "men",
          "women",
          "children",
          "mid-mature"
        ],
        "type": "string"
      }
    },
    "season": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Retail-season slugs to bias ranking toward: 'spring-summer', 'fall-winter', 'pre-spring', 'pre-fall'. A ranking signal only — never converted to a date filter. Optional; unknown values are ignored.",
      "items": {
        "enum": [
          "spring-summer",
          "fall-winter",
          "pre-spring",
          "pre-fall"
        ],
        "type": "string"
      }
    },
    "year": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Four-digit year(s) the query targets (e.g. ['2025']). Biases ranking and, when no explicit start/end date is given, narrows the time window to those years. Optional; values outside 2000-2099 are ignored.",
      "items": {
        "pattern": "^20[0-9]{2}$",
        "type": "string"
      }
    },
    "moments": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Named retail-moment slugs the query targets (e.g. 'black-friday', 'valentines-day', 'holiday-season'). Biases ranking and, when no explicit start/end date is given, contributes a recent time window. Optional; unknown values are ignored.",
      "items": {
        "enum": [
          "black-friday",
          "lunar-new-year",
          "easter",
          "halloween",
          "international-womens-day",
          "mothers-day-uk",
          "mothers-day-us",
          "4th-july-us",
          "earth-month",
          "festival-season",
          "holiday-season",
          "ramadan",
          "valentines-day",
          "back-to-college",
          "back-to-school",
          "fathers-day",
          "occasion-season",
          "spring-break-us"
        ],
        "type": "string"
      }
    }
  },
  "required": [
    "query"
  ]
}

Parameters​

Returns​

Try it​

Code examples​

Input schema​

Parameters

Returns

Try it

Code examples

Input schema