get_product

Instructions

Implementation Reference

• src/index.ts:211-293 (registration)

  Tool 'get_product' is registered in the ListToolsRequestSchema handler with name, description, and inputSchema requiring product_id.

    {
      name: "get_product",
      description: "Fetch full details for a single product by its BuyWhere product ID.",
      inputSchema: {
        type: "object",
        properties: {
          product_id: {
            type: "string",
            description: "The BuyWhere product ID (returned by search_products as product_id)",
          },
        },
        required: ["product_id"],
      },
    },
    {
      name: "get_price",
      description:
        "Get current prices for a product across all available merchants. " +
        "Returns a ranked list of listings with price, shipping, merchant rating, and stock status. " +
        "Use this to find the cheapest place to buy a specific product.",
      inputSchema: {
        type: "object",
        properties: {
          product_id: {
            type: "string",
            description: "The BuyWhere product ID",
          },
        },
        required: ["product_id"],
      },
    },
    {
      name: "compare_prices",
      description:
        "Compare 2–5 products side-by-side. Returns structured differentiators, price range, " +
        "pros/cons, and a best-value recommendation — purpose-built for AI agent decision-making.",
      inputSchema: {
        type: "object",
        properties: {
          product_ids: {
            type: "array",
            items: { type: "string" },
            description: "Array of 2–5 BuyWhere product IDs to compare",
            minItems: 2,
            maxItems: 5,
          },
        },
        required: ["product_ids"],
      },
    },
    {
      name: "get_affiliate_link",
      description:
        "Get the click-tracked BuyWhere affiliate link for a product. " +
        "Share this link with users — it logs the referral and redirects to the merchant page. " +
        "Always use this instead of raw product URLs when sharing links.",
      inputSchema: {
        type: "object",
        properties: {
          product_id: {
            type: "string",
            description: "The BuyWhere product ID",
          },
        },
        required: ["product_id"],
      },
    },
    {
      name: "get_catalog",
      description:
        "List available product categories in the BuyWhere catalog. " +
        "Use this to discover what categories exist before searching or filtering.",
      inputSchema: {
        type: "object",
        properties: {
          parent_slug: {
            type: "string",
            description: "Parent category slug to list subcategories (optional — omit for top-level categories)",
          },
        },
      },
    },
  ],

• src/index.ts:339-351 (handler)

  Handler for 'get_product' tool call: validates product_id, calls apiFetch on /v1/products/{id}, and formats the result using formatProduct().

  // ── get_product ──────────────────────────────────────────────────────────
  if (name === "get_product") {
    const productId = args.product_id as string | undefined;
    if (!productId) {
      throw new McpError(ErrorCode.InvalidParams, "product_id is required");
    }
  
    const data = (await apiFetch(`/v1/products/${encodeURIComponent(productId)}`)) as Record<string, unknown>;
  
    return {
      content: [{ type: "text", text: formatProduct(data) }],
    };
  }

• src/index.ts:111-140 (helper)

  The formatProduct() helper is used by get_product to format the API response into a human-readable text block with title, ID, price, category, merchant, stock, URL, image, and description.

  function formatProduct(p: Record<string, unknown>): string {
    const price = p.price as Record<string, unknown> | undefined;
    const merchant = p.merchant as Record<string, unknown> | undefined;
    const avail = p.availability as Record<string, unknown> | undefined;
    const images = (p.images as Array<Record<string, unknown>> | undefined) ?? [];
  
    const lines: string[] = [
      `**${p.title ?? p.name}**`,
      `ID: ${p.product_id ?? p.id}`,
      `Price: ${price?.currency ?? "SGD"} ${price?.amount ?? "N/A"}`,
      `Category: ${p.category ?? ""}`,
      `Merchant: ${merchant?.name ?? merchant?.merchant_id ?? ""}` +
        (merchant?.platform ? ` (${merchant.platform})` : ""),
      `In stock: ${avail?.in_stock ? "Yes" : "No"}`,
      `URL: ${p.source_url ?? ""}`,
    ];
  
    if (images.length > 0) {
      lines.push(`Image: ${images[0].url}`);
    }
    if (p.description_short) {
      lines.push(`Description: ${p.description_short}`);
    }
    if (p.description_full) {
      const desc = p.description_full as string;
      lines.push(`Description: ${desc.length > 300 ? desc.slice(0, 300) + "…" : desc}`);
    }
  
    return lines.join("\n");
  }

• src/index.ts:213-224 (schema)

  Input schema for get_product: requires a single string parameter 'product_id' which is the BuyWhere product ID returned by search_products.

    description: "Fetch full details for a single product by its BuyWhere product ID.",
    inputSchema: {
      type: "object",
      properties: {
        product_id: {
          type: "string",
          description: "The BuyWhere product ID (returned by search_products as product_id)",
        },
      },
      required: ["product_id"],
    },
  },