Enrich Image Context (Messaging)

messagingmcp-enrich_with_vm

Fetch VM (visual + page-text) context for a list of image_ids.

Use after a promo tool or messaging_search to pull the caption (and optionally OCR) plus channel/provenance metadata for specific shots. full_text=True returns untruncated OCR (default is a 500-char snippet).

Each entry's provenance: channel_name names the captured channel/page, channel_target describes how it was shot, date is the capture date. image_description is the VLM caption (may be empty when captioning failed); ocr_text is whole-page OCR text, not scoped to one promotion.

Parameters

Name	Type	Required	Constraints	Description
image_ids	string[]	yes	—	image_id values to look up — typically harvested from a prior promo tool (list_promos / count_promos / search_promo_text) or messaging_search.
include	string[]	no	—	Which content fields to return per image: subset of ['description', 'ocr']. Omitted defaults to ['description'] — visual context is VM enrichment's unique value; OCR is opt-in.
full_text	boolean	no	default: false	When True, forces OCR inclusion and returns it untruncated (overrides the default 500-char snippet). Default False.

Returns

• On success: {"result": {"image_ids_found": [...], "image_ids_missing": [...],
• "vm_context": {image_id: {...}}}}. Missing ids are surfaced, never dropped.
• On failure: {"error": {code, message}}
• code is invalid_input, upstream_unavailable, or
• not_entitled (authorization refused).

Try it

Loading interactive widget…

Code examples

curl

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-enrich_with_vm",
    "arguments": {
      "full_text": false
    }
  }
}'

TypeScript

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-enrich_with_vm",
  arguments: {
    "full_text": false
  },
});

Python

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-enrich_with_vm",
            {"full_text": False},
        )

Input schema

{
  "type": "object",
  "properties": {
    "image_ids": {
      "description": "image_id values to look up — typically harvested from a prior promo tool (list_promos / count_promos / search_promo_text) or messaging_search.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "include": {
      "description": "Which content fields to return per image: subset of ['description', 'ocr']. Omitted defaults to ['description'] — visual context is VM enrichment's unique value; OCR is opt-in.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "full_text": {
      "default": false,
      "description": "When True, forces OCR inclusion and returns it untruncated (overrides the default 500-char snippet). Default False.",
      "type": "boolean"
    }
  },
  "required": [
    "image_ids"
  ]
}

Output schema

Describes both branches of the envelope — result on success, error on a refusal. Validate against this rather than pattern-matching the prose above; see Concepts → Response shape.

{
  "type": "object",
  "properties": {
    "result": {
      "properties": {
        "image_ids_found": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "image_ids_missing": {
          "description": "Requested ids with no VM document; a miss lands here, never an error.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "vm_context": {
          "description": "Object keyed by image_id. Each value carries image_id, retailer (the filterable slug), retailer_name, date, channel_name, channel_target, channel_type, region, image_url and verticals (human-readable vertical names, [] if none) — all present, null where the document is silent. image_description and ocr_text are present only when `include` asked for them; ocr_text is truncated unless full_text was requested.",
          "title": "Vm Context"
        }
      },
      "required": [
        "image_ids_found",
        "image_ids_missing",
        "vm_context"
      ],
      "type": "object"
    },
    "error": {
      "type": "object",
      "description": "Present instead of `result` when the call was rejected. Branch on `code`; never string-match `message`.",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_input",
            "not_entitled",
            "upstream_unavailable",
            "internal"
          ]
        },
        "message": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "description": "Offending parameter, when the failure is attributable to one."
        },
        "details": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "oneOf": [
    {
      "required": [
        "result"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "x-fastmcp-wrap-result": true
}