Metadata-Version: 2.4
Name: ucpregistry
Version: 0.1.0
Summary: Official Python SDK for the UCP Registry API — discover UCP merchants, search products, and manage registry entities.
Project-URL: Homepage, https://ucpregistry.com
Project-URL: Documentation, https://ucpregistry.com/developers
Project-URL: Repository, https://github.com/ucpregistry/python-sdk
Project-URL: MCP, https://ucpregistry.com/mcp
Author-email: UCP Registry <hello@ucpregistry.com>
License-Expression: MIT
Keywords: agent,ai,commerce,mcp,merchant,registry,shopping,ucp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Description-Content-Type: text/markdown

# ucpregistry

Official Python SDK for the [UCP Registry](https://ucpregistry.com) API. Discover UCP-enabled merchants, search products across stores, and manage registry entities.

## Install

```bash
pip install ucpregistry
```

## Quick Start

```python
from ucpregistry import UCPRegistry

registry = UCPRegistry()

# Discover merchants
merchants = registry.discover(platform="shopify")
for m in merchants:
    print(m.domain, m.ucp_score, m.capabilities.checkout)

# Get a specific merchant
merchant = registry.get_merchant("allbirds.com")
print(merchant.transports)  # ['mcp', 'embedded']

# Search products across all merchants
products = registry.search_products(query="running shoes", sort="price_asc")
for p in products:
    print(f"{p.title} - ${p.price} at {p.merchant}")
```

## Authentication

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

```python
registry = UCPRegistry(api_key="ucpr_...")
```

Get your token at [ucpregistry.com/tokens](https://ucpregistry.com/tokens).

## API

### `discover(**kwargs)`

Find UCP-enabled merchants.

```python
merchants = registry.discover(
    search="skincare",
    platform="shopify",
    category="Health & Beauty",
    sort="ucp_score",
    limit=20,
)
```

### `get_merchant(domain)`

Get full details for a merchant.

```python
m = registry.get_merchant("imageskincare.com")
print(m.capabilities.checkout)
print(m.sample_products)
```

### `search_products(**kwargs)`

Search products across all merchants.

```python
products = registry.search_products(
    query="serum",
    min_price=20,
    max_price=100,
    sort="price_asc",
)
```

### `push(entity_type, slug, manifest, commit_message=None)`

Push a manifest version (requires token).

```python
version = registry.push(
    "merchants", "mystore.com",
    manifest={"version": "1.0", "capabilities": ["checkout"]},
    commit_message="Initial push",
)
print(version.version)  # '1.0.0'
```

### `versions(entity_type, slug)`

List version history.

### `diff(entity_type, slug, v1, v2)`

Diff two versions.

## Context Manager

```python
with UCPRegistry(api_key="ucpr_...") as registry:
    merchants = registry.discover()
```

## MCP Server

UCP Registry is also available as an MCP server:

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

## License

MIT
