Search Articles (Research)

researchmcp-research_article_search

Search EDITED Research articles by meaning.

Returns one article-level summary per relevant report. Use this first to identify which reports cover a topic. Then drill in with research_chunk_search (passing the returned report_id values) for granular passages, or research_image_search for visual content.

Before presenting results, resolve the report_id values you cite with research_report_links (one batched call) so the user gets clickable EDITED Research URLs alongside your answer — this follow-up is expected, not optional. The linked pages require login, so when the user wants the content itself, also call research_read_report.

Ranking is automatic: results are ordered by a blend of relevance, recency, and — when you supply the optional intent axes (article_types, topics, gender, season, year, moments) — how well each report's tags match them. No intent is required; supplying it biases the order toward matching reports. Populate the axes from research_analyze_query or your own reasoning; unknown slugs are ignored. 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. 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. Defaults to now when omitted. k: Number of articles 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. See each parameter's description.

Try queries like

"Black Friday discounting strategy", "Gen Z denim trends", "luxury handbag pricing", "athleisure market growth".

Parameters

Name	Type	Required	Constraints	Description
`query`	`string`	yes	—	Natural language search query for finding research articles.
`start_date`	`string \| null`	no	default: `null`	Inclusive start date (YYYY-MM-DD). Articles on or after this date.
`end_date`	`string \| null`	no	default: `null`	Inclusive end date (YYYY-MM-DD). Articles on or before this date.
`k`	`integer`	no	default: `5` · 1–10	Number of articles 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, "articles": list[ArticleHit]}. Each hit carries
report_id, title, date, score, and a summary field drawn from the
report's full text. Follow up with research_report_links to turn the
report_ids you cite into public links; to read the full article text,
call research_read_report.
On retrieval 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": "researchmcp-research_article_search",
    "arguments": {
      "query": "Nike",
      "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_article_search",
  arguments: {
    "query": "Nike",
    "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_article_search",
            {"query": "Nike", "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 research articles.",
      "type": "string"
    },
    "start_date": {
      "anyOf": [
        {
          "format": "date",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive start date (YYYY-MM-DD). Articles on or after this date."
    },
    "end_date": {
      "anyOf": [
        {
          "format": "date",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive end date (YYYY-MM-DD). Articles on or before this date."
    },
    "k": {
      "default": 5,
      "description": "Number of articles 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