search

Instructions

Implementation Reference

• server.py:10-49 (handler)

  The `search` function is the MCP tool handler decorated with @mcp.tool(). It accepts keyword, category, max_price, min_rating, and limit parameters, calls search_products(), and returns JSON results.

  @mcp.tool()
  def search(
      keyword: str,
      category: str | None = None,
      max_price: float | None = None,
      min_rating: float | None = None,
      limit: int = 10,
  ) -> str:
      """Search products by keyword with optional filters.
  
      Args:
          keyword: Search term matched against name, description, brand, category, and tags.
          category: Filter by exact category name (e.g. "Laptops", "Headphones").
          max_price: Upper price limit in USD.
          min_rating: Minimum rating (0–5).
          limit: Maximum number of results to return (default 10, max 50).
      """
      limit = min(max(1, limit), 50)
      results = search_products(
          keyword=keyword,
          category=category,
          max_price=max_price,
          min_rating=min_rating,
          limit=limit,
      )
  
      return json.dumps(
          {
              "keyword": keyword,
              "filters": {
                  "category": category,
                  "max_price": max_price,
                  "min_rating": min_rating,
              },
              "total_results": len(results),
              "products": results,
          },
          ensure_ascii=False,
          indent=2,
      )

• server.py:10-17 (schema)

  The type annotations on the `search` function parameters (keyword: str, category: str | None, max_price: float | None, min_rating: float | None, limit: int) define the input schema for the tool.

  @mcp.tool()
  def search(
      keyword: str,
      category: str | None = None,
      max_price: float | None = None,
      min_rating: float | None = None,
      limit: int = 10,
  ) -> str:

• server.py:7-7 (registration)

  The FastMCP instance is created as `mcp = FastMCP("product-search")` and the `@mcp.tool()` decorator on line 10 registers the `search` function as a tool.

  mcp = FastMCP("product-search")

• products.py:171-207 (helper)

  The `search_products` helper function performs the actual keyword matching and filtering logic against the product catalog, then returns results sorted by rating and price.

  def search_products(
      keyword: str,
      category: str | None = None,
      max_price: float | None = None,
      min_rating: float | None = None,
      limit: int = 10,
  ) -> list[dict[str, Any]]:
      """Search the product catalog by keyword and optional filters."""
      kw = keyword.lower().strip()
      results: list[Product] = []
  
      for product in CATALOG:
          # keyword match against name, description, brand, category, tags
          searchable = " ".join([
              product.name.lower(),
              product.description.lower(),
              product.brand.lower(),
              product.category.lower(),
              " ".join(product.tags),
          ])
          if kw not in searchable:
              continue
  
          if category and product.category.lower() != category.lower():
              continue
  
          if max_price is not None and product.price > max_price:
              continue
  
          if min_rating is not None and product.rating < min_rating:
              continue
  
          results.append(product)
  
      # sort by rating descending, then price ascending
      results.sort(key=lambda p: (-p.rating, p.price))
      return [p.to_dict() for p in results[:limit]]