@buywhere/paperclip

BuyWhere tools for Paperclip agents — search and compare products across Singapore, SEA, and US markets. Part of the BuyWhere product catalog API for AI agent commerce.

Installation

npm install @buywhere/paperclip

Quick Start

import { createToolHandlers } from "@buywhere/paperclip";

// Requires BUYWHERE_API_KEY env var
const tools = createToolHandlers();

const result = await tools.search_products.handler({
  q: "wireless headphones",
  limit: 5,
});
console.log(result);

Using with Paperclip Agents

Paperclip agents can use BuyWhere tools in two ways:

1. Direct Function Calls (for custom agent code)

import { BuyWhereClient, createToolHandlers } from "@buywhere/paperclip";

const client = new BuyWhereClient({ apiKey: "bw_live_xxxx" });
const tools = createToolHandlers(client);

// Search products
const results = await tools.search_products.handler({
  q: "mechanical keyboard",
  country_code: "SG",
  limit: 10,
 });

2. MCP Server Integration (for any Paperclip agent)

Add this to your Paperclip agent's configuration:

{
  "mcpServers": {
    "buywhere": {
      "command": "npx",
      "args": ["-y", "@buywhere/mcp-server"],
      "env": {
        "BUYWHERE_API_KEY": "bw_live_xxxx"
      }
    }
  }
}

The @buywhere/mcp-server package is already published and maintained separately.

Tools

| Tool | Description | |------|-------------| | search_products | Search catalog by keyword, price range, region | | get_product | Get full product details by ID | | compare_products | Compare 2-10 products side-by-side | | get_deals | Get discounted products sorted by discount | | list_categories | List top-level product categories |

API

BuyWhereClient

const client = new BuyWhereClient({ apiKey: string, baseUrl?: string, timeout?: number });

BuyWhereClient.fromEnv()

Creates a client using BUYWHERE_API_KEY and optional BUYWHERE_API_URL environment variables.

createToolHandlers(client?: BuyWhereClient): ToolHandlerMap

Returns an object with named ToolHandler entries, each having:

• name — tool name
• description — tool description
• inputSchema — JSON Schema for input validation
• handler(args) — async function that calls the BuyWhere API

Environment Variables

| Variable | Description | |----------|-------------| | BUYWHERE_API_KEY | Your BuyWhere API key (required) | | BUYWHERE_API_URL | Custom API base URL (optional, default: https://api.buywhere.ai) |

Get your API key at https://buywhere.ai.

Requirements

• Node.js >= 18

Links

• BuyWhere API Docs
• GitHub
• npm
• MCP Server

License

MIT