Match Images to Text (Research)

researchmcp-research_match_images_to_text

Find images that match arbitrary text by meaning.

Use when you have an answer (or any text) and want to surface images that visually support it. Differs from research_image_search in two ways:

The input is text (typically longer than a query — e.g. an already-generated answer).
No date filters. Use report_ids to constrain scope.

Match-only: the response is the raw search hits. The caller is responsible for any perceptual-hash dedup or LLM relevance filtering if desired.

Ranking blends relevance with recency, plus the optional intent axes when supplied (no date window is applied here — only report_ids constrains scope). The score on each hit is this composite value.

Try queries like

"Oversized tailoring dominated the autumn runways.", "Retailers are leaning into minimalist, recyclable packaging this season.".

Parameters

Name	Type	Required	Constraints	Description
`text`	`string`	yes	—	Free-form text — an answer, paragraph, or anything — to find images that match its meaning. Typically longer than a search query.
`report_ids`	`integer[] \| null`	no	default: `null`	Constrain the search to images from specific reports. Pass the `report_id` values from a previous search. Omit to search the full corpus.
`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]} where each hit
carries report_id, title, date, score, url, caption,
copyright (image attribution string or null), format, and
image_id. total is the number of images returned (<= k).
On retrieval failure or invalid k: {"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_match_images_to_text",
    "arguments": {
      "text": "example",
      "report_ids": 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_match_images_to_text",
  arguments: {
    "text": "example",
    "report_ids": 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_match_images_to_text",
            {"text": "example", "report_ids": None, "k": 5, "article_types": None, "topics": None, "gender": None, "season": None, "year": None, "moments": None},
        )

Input schema

{
  "type": "object",
  "properties": {
    "text": {
      "description": "Free-form text — an answer, paragraph, or anything — to find images that match its meaning. Typically longer than a search query.",
      "type": "string"
    },
    "report_ids": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Constrain the search to images from specific reports. Pass the `report_id` values from a previous search. Omit to search the full corpus."
    },
    "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": [
    "text"
  ]
}

Parameters​

Returns​

Try it​

Code examples​

Input schema​

Parameters

Returns

Try it

Code examples

Input schema