Search Passages (Research)

researchmcp-research_chunk_search

Search EDITED Research articles for granular text passages.

Returns chunk-level passages — each hit is a paragraph-sized excerpt with a session-scoped chunk_id. Use after research_article_search to drill into specific reports: pass the returned report_id values via the report_ids parameter, plus a focused query for the passage you want.

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 (use values from research_article_search). Omit to search the full corpus. start_date: Inclusive lower bound, YYYY-MM-DD. Defaults to 550 days ago when both dates are omitted. end_date: Inclusive upper bound, YYYY-MM-DD. k: Number of chunks 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

"average discount depth in womenswear", "outerwear sell-through rate", "spring/summer colour palette", "promotional cadence in footwear".

Parameters

Name	Type	Required	Constraints	Description
`query`	`string`	yes	—	Natural language search query for finding chunks 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 chunks 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, "chunks": list[ChunkHit]}. Each hit carries
report_id, title, date, score, text, and chunk_id.
On retrieval failure: {"error": str}.
chunk_id is an opaque id assigned when the chunk is indexed — fetch it back
with research_get_chunk 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_chunk_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_chunk_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_chunk_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 chunks 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 chunks 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