Search Visuals (Messaging)

messagingmcp-messaging_search

Search messaging channel visuals (homepage and newsletter screenshots) by meaning.

Ranks whole-page captures against an embedding of the page's OCR text plus a VLM-written caption, so the query can match either what the page says or what it shows. Each hit's image_description is that caption (may be empty when captioning failed) and ocr_text is a whole-page OCR snippet — page-level text, not scoped to one promotion. Use this tool to find promotional visuals matching a topic or creative brief; pair with enrich_with_vm for full OCR.

Parameters

Name	Type	Required	Constraints	Description
`query`	`string`	yes	—	Natural-language query describing the promotional content to find.
`start_date`	`string \| null`	no	default: `null`	Inclusive start date (YYYY-MM-DD) on the shot date.
`end_date`	`string \| null`	no	default: `null`	Inclusive end date (YYYY-MM-DD) on the shot date.
`regions`	`string[] \| null`	no	default: `null`	Regions to filter by, e.g. ['UK', 'US']. None = all; matches any listed region. `list_retailers` reports the exact region values for each retailer; use those, since regions match exactly.
`retailers`	`string[] \| null`	no	default: `null`	Retailer slugs to filter by, e.g. ['zara', 'h-m']. None = all; matches any listed retailer. Call `list_retailers` and match the requested retailer against its `retailer_name`, then pass the row's `retailer` slug and a region it covers exactly as reported there. Slugs match exactly, so a display name or wrong case matches nothing.
`verticals`	`string[] \| null`	no	default: `null`	Verticals (industries) to filter by: subset of ['Apparel', 'Homeware', 'Beauty']. None = all; matches any listed vertical. Values match exactly (case-sensitive).
`channel_type`	`string[] \| null`	no	default: `null`	Filter to channel types: subset of ['homepage', 'newsletter']. None = all channels.
`k`	`integer`	no	default: `5` · 1–50	Number of results to return. Default 5, max 50.
`include_repeats`	`boolean`	no	default: `false`	When False (default), return chain-heads only — one result per unique shoot, excluding re-captures of unchanged pages. Set True to include all captures.

Returns

On success: {"total": int, "hits": list[MessagingHit]}.
total is the number of hits RETURNED (capped by k) — not a corpus-wide
match count; ranked retrieval has no meaningful total, so do not report
it as "N matching pages".
Each hit: image_id, retailer, retailer_name, channel_type, region,
date, image_url, image_description, ocr_text, channel_name,
channel_target, verticals, score.
On failure: {"error": str}.

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": "messagingmcp-messaging_search",
    "arguments": {
      "query": "Nike",
      "start_date": null,
      "end_date": null,
      "regions": null,
      "retailers": null,
      "verticals": null,
      "channel_type": null,
      "k": 5,
      "include_repeats": false
    }
  }
}'

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: "messagingmcp-messaging_search",
  arguments: {
    "query": "Nike",
    "start_date": null,
    "end_date": null,
    "regions": null,
    "retailers": null,
    "verticals": null,
    "channel_type": null,
    "k": 5,
    "include_repeats": false
  },
});

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(
            "messagingmcp-messaging_search",
            {"query": "Nike", "start_date": None, "end_date": None, "regions": None, "retailers": None, "verticals": None, "channel_type": None, "k": 5, "include_repeats": False},
        )

Input schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Natural-language query describing the promotional content to find.",
      "type": "string"
    },
    "start_date": {
      "anyOf": [
        {
          "format": "date",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive start date (YYYY-MM-DD) on the shot date."
    },
    "end_date": {
      "anyOf": [
        {
          "format": "date",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive end date (YYYY-MM-DD) on the shot date."
    },
    "regions": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Regions to filter by, e.g. ['UK', 'US']. None = all; matches any listed region. `list_retailers` reports the exact region values for each retailer; use those, since regions match exactly."
    },
    "retailers": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Retailer slugs to filter by, e.g. ['zara', 'h-m']. None = all; matches any listed retailer. Call `list_retailers` and match the requested retailer against its `retailer_name`, then pass the row's `retailer` slug and a region it covers exactly as reported there. Slugs match exactly, so a display name or wrong case matches nothing."
    },
    "verticals": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "Apparel",
              "Homeware",
              "Beauty"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Verticals (industries) to filter by: subset of ['Apparel', 'Homeware', 'Beauty']. None = all; matches any listed vertical. Values match exactly (case-sensitive)."
    },
    "channel_type": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "homepage",
              "newsletter"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter to channel types: subset of ['homepage', 'newsletter']. None = all channels."
    },
    "k": {
      "default": 5,
      "description": "Number of results to return. Default 5, max 50.",
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "include_repeats": {
      "default": false,
      "description": "When False (default), return chain-heads only — one result per unique shoot, excluding re-captures of unchanged pages. Set True to include all captures.",
      "type": "boolean"
    }
  },
  "required": [
    "query"
  ]
}

Parameters​

Returns​

Try it​

Code examples​

Input schema​

Parameters

Returns

Try it

Code examples

Input schema