compare_prices

Instructions

Implementation Reference

• src/index.ts:242-260 (registration)

  Registration of compare_prices tool in the ListToolsRequestSchema handler. Defines the tool name, description, and input schema (product_ids array of 2–5 strings).

  {
    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"],
    },
  },

• src/index.ts:383-432 (handler)

  Handler for compare_prices tool. Validates 2–5 product_ids, calls POST /v1/products/compare API, then formats the response showing product details, price range, best value recommendation, and key differentiators.

  // ── compare_prices ───────────────────────────────────────────────────────
  if (name === "compare_prices") {
    const productIds = args.product_ids as string[] | undefined;
    if (!productIds || productIds.length < 2) {
      throw new McpError(ErrorCode.InvalidParams, "product_ids must be an array of 2–5 product IDs");
    }
    if (productIds.length > 5) {
      throw new McpError(ErrorCode.InvalidParams, "compare_prices supports at most 5 products at once");
    }
  
    const data = (await apiFetch("/v1/products/compare", { ids: productIds.join(",") })) as Record<string, unknown>;
    const products = (data.products as Array<Record<string, unknown>>) ?? [];
    const comparison = data.comparison as Record<string, unknown> | undefined;
  
    const lines: string[] = [`**Product comparison (${products.length} items):**\n`];
  
    for (const p of products) {
      const price = p.price as Record<string, unknown> | undefined;
      lines.push(
        `**${p.title ?? p.name}** (ID: ${p.product_id ?? p.id})`,
        `  Price: ${price?.currency ?? "SGD"} ${price?.amount ?? "N/A"}`,
        `  Category: ${p.category ?? ""}`,
        `  Merchant: ${(p.merchant as Record<string, unknown>)?.name ?? ""}`,
        `  URL: ${p.source_url ?? ""}`,
        "",
      );
    }
  
    if (comparison) {
      const priceRange = comparison.price_range as Record<string, unknown> | undefined;
      if (priceRange) {
        lines.push(`**Price range:** ${priceRange.currency ?? "SGD"} ${priceRange.min} – ${priceRange.max}`);
      }
      const bestValue = comparison.best_value as Record<string, unknown> | undefined;
      if (bestValue) {
        lines.push(`**Best value:** ${bestValue.title ?? bestValue.product_id} — ${bestValue.rationale ?? ""}`);
      }
      const differentiators = comparison.differentiators as string[] | undefined;
      if (differentiators?.length) {
        lines.push(`\n**Key differences:**`);
        for (const d of differentiators) {
          lines.push(`  • ${d}`);
        }
      }
    }
  
    return {
      content: [{ type: "text", text: lines.join("\n") }],
    };
  }