ucpregistry

Official SDK for the UCP Registry API. Discover UCP-enabled merchants, search products across stores, and manage registry entities.

Install

npm install ucpregistry

Quick Start

import { UCPRegistry } from 'ucpregistry';

const registry = new UCPRegistry();

// Discover merchants
const merchants = await registry.discover({ category: 'Health & Beauty' });

// Get a specific merchant
const merchant = await registry.getMerchant('allbirds.com');
console.log(merchant.capabilities.checkout); // true
console.log(merchant.transports); // ['mcp', 'embedded']

// Search products across all merchants
const products = await registry.searchProducts({
  query: 'running shoes',
  sort: 'price_asc',
  limit: 5,
});

Authentication

Free tier endpoints (discover, search) work without authentication. For push API and entity management, pass your API token:

const registry = new UCPRegistry({
  apiKey: 'ucpr_...',
});

Get your token at ucpregistry.com/tokens.

API

discover(options?)

Find UCP-enabled merchants.

const merchants = await registry.discover({
  search: 'skincare',        // keyword search
  platform: 'shopify',       // shopify, woocommerce, bigcommerce, etc.
  category: 'Health & Beauty', // Google Product Taxonomy category
  has_checkout: true,         // only merchants with checkout
  sort: 'ucp_score',         // ucp_score | response_time | domain
  limit: 20,                 // max results
});

getMerchant(domain)

Get full details for a merchant.

const m = await registry.getMerchant('imageskincare.com');
// m.capabilities, m.transports, m.sample_products, m.benchmark, etc.

searchProducts(options?)

Search products across all merchants.

const products = await registry.searchProducts({
  query: 'serum',
  category: 'Health & Beauty',
  min_price: 20,
  max_price: 100,
  sort: 'price_asc',
});

push(type, slug, options) (requires token)

Push a manifest version.

const version = await registry.push('merchants', 'mystore.com', {
  manifest: { version: '1.0', capabilities: ['checkout'] },
  commit_message: 'Initial push',
});
// version.version → '1.0.0'

versions(type, slug) (requires token)

List version history.

diff(type, slug, v1, v2) (requires token)

Diff two versions.

MCP Server

UCP Registry is also available as an MCP server. Add it to your agent:

{
  "mcpServers": {
    "ucpregistry": {
      "url": "https://ucpregistry.com/mcp"
    }
  }
}

Tools: discover-merchants, get-merchant, search-products.

Types

All types are exported:

import type { Merchant, ProductResult, MerchantCapabilities } from 'ucpregistry';

License

MIT