search_item_summary

Instructions

Implementation Reference

• ebay_mcp/client.py:323-360 (handler)

  Core implementation of search_item_summary. Builds query parameters (q, limit, offset, category_ids, sort), sends GET to eBay Browse API /buy/browse/v1/item_summary/search, and returns the response dict. Handles validation (non-empty query, limit 1-200, non-negative offset).

  def search_item_summary(
      self,
      query: str,
      *,
      limit: int = 20,
      offset: int = 0,
      category_ids: Optional[str] = None,
      sort: Optional[str] = None,
  ) -> Dict[str, Any]:
      """Browse item summary search (Buy Browse).
  
      GET buy/browse/v1/item_summary/search
  
      ``sort`` examples: ``newlyListed`` (listing date), ``endingSoonest``,
      ``price``, ``-price``, ``distance`` (requires pickup filters).
      """
      q = query.strip()
      if not q:
          raise EbayError("query must not be empty")
      if limit < 1 or limit > 200:
          raise EbayError("limit must be between 1 and 200")
      if offset < 0:
          raise EbayError("offset must be >= 0")
      params: Dict[str, Any] = {"q": q, "limit": limit, "offset": offset}
      if category_ids and category_ids.strip():
          params["category_ids"] = category_ids.strip()
      if sort and sort.strip():
          params["sort"] = sort.strip()
      url = f"{self.api_root}/buy/browse/v1/item_summary/search"
      data = self._request_json(
          "GET",
          url,
          params=params,
          retry_refresh=True,
      )
      if not isinstance(data, dict):
          raise EbayError(f"Unexpected search payload: {type(data)!r}")
      return data

• ebay_mcp/server.py:37-58 (registration)

  MCP tool registration using @mcp.tool() decorator. Defines the tool's schema (query, limit, offset, category_ids, sort params) and delegates to EbayClient.search_item_summary.

  @mcp.tool()
  def search_item_summary(
      query: str,
      limit: int = 20,
      offset: int = 0,
      category_ids: Optional[str] = None,
      sort: Optional[str] = None,
  ) -> Dict[str, Any]:
      """Search marketplace listings (Browse item_summary/search).
  
      Typical filters: limit 1–50 for quick previews. category_ids is optional
      (comma-separated eBay leaf category ids).
  
      Sort: omit for Best Match; use ``newlyListed`` for newest listings first.
      """
      return _client().search_item_summary(
          query,
          limit=limit,
          offset=offset,
          category_ids=category_ids,
          sort=sort,
      )

• ebay_mcp/server.py:37-44 (schema)

  Input schema definition for the MCP tool via function signature. Parameters: query (str, required), limit (int, default 20), offset (int, default 0), category_ids (Optional[str]), sort (Optional[str]). Return type is Dict[str, Any].

  @mcp.tool()
  def search_item_summary(
      query: str,
      limit: int = 20,
      offset: int = 0,
      category_ids: Optional[str] = None,
      sort: Optional[str] = None,
  ) -> Dict[str, Any]:

• ebay_mcp/client.py:284-290 (helper)

  Internal usage of search_item_summary within EbayClient.verify() as a probe call when using application tokens (no user token) to verify connectivity.

  if self.token_kind == "application":
      probe = self.search_item_summary(
          "electronics",
          limit=1,
          offset=0,
          sort=None,
      )

• ebay_mcp/check.py:56-61 (helper)

  Smoke-test usage of search_item_summary in check.py for end-to-end verification, called with query from env var and sort='newlyListed'.

  latest = client.search_item_summary(
      kw,
      limit=int(os.getenv("EBAY_CHECK_LIMIT", "10")),
      offset=0,
      sort="newlyListed",
  )