compare_competitors

Instructions

Implementation Reference

• src/yaparai/tools/enterprise.py:68-90 (handler)

  The main tool handler function. Validates that 2–4 competitor IDs are provided, then delegates to the HTTP client.

  async def compare_competitors(
      competitor_ids: list[str],
      org_id: str | None = None,
  ) -> dict:
      """
      Compare 2–4 competitors on key metrics.
  
      Returns latest metric snapshots for each competitor including
      PageSpeed score, total followers, posts in last 30 days, and
      product count. Use this as the basis for SWOT analysis or
      positioning decisions.
  
      Args:
          competitor_ids: 2–4 competitor UUIDs
          org_id: Optional — override the org bound to the API key
  
      Returns:
          {"metrics": [...]} — one entry per competitor with KPI snapshot.
      """
      if not 2 <= len(competitor_ids) <= 4:
          raise ValueError("competitor_ids must have 2 to 4 items")
      client = YaparAIClient()
      return await client.enterprise_compare_competitors(competitor_ids, org_id=org_id)

• src/yaparai/server.py:179-179 (registration)

  Registers the compare_competitors function as an MCP tool on the FastMCP server.

  mcp.tool(compare_competitors)

• src/yaparai/tools/enterprise.py:68-90 (schema)

  Type signature and docstring define the input schema (list of 2-4 competitor UUIDs, optional org_id) and output shape (dict with metrics).

  async def compare_competitors(
      competitor_ids: list[str],
      org_id: str | None = None,
  ) -> dict:
      """
      Compare 2–4 competitors on key metrics.
  
      Returns latest metric snapshots for each competitor including
      PageSpeed score, total followers, posts in last 30 days, and
      product count. Use this as the basis for SWOT analysis or
      positioning decisions.
  
      Args:
          competitor_ids: 2–4 competitor UUIDs
          org_id: Optional — override the org bound to the API key
  
      Returns:
          {"metrics": [...]} — one entry per competitor with KPI snapshot.
      """
      if not 2 <= len(competitor_ids) <= 4:
          raise ValueError("competitor_ids must have 2 to 4 items")
      client = YaparAIClient()
      return await client.enterprise_compare_competitors(competitor_ids, org_id=org_id)

• src/yaparai/client.py:341-350 (helper)

  HTTP client method that sends a POST request to /v1/public/enterprise/competitors/compare with the competitor_ids payload.

  async def enterprise_compare_competitors(
      self, competitor_ids: list[str], org_id: str | None = None
  ) -> dict:
      headers = {"X-Organization-Id": org_id} if org_id else {}
      return await self._request(
          "POST",
          "/v1/public/enterprise/competitors/compare",
          json={"competitor_ids": competitor_ids},
          headers=headers,
      )

• src/yaparai/server.py:94-101 (registration)

  Import of the compare_competitors function into the server module from the enterprise tools module.

  from yaparai.tools.enterprise import (
      list_competitors,
      get_competitor,
      compare_competitors,
      list_org_products,
      create_org_product,
      update_product_stock,
  )