@opencommerceprotocol/registry

Public agent registry server for the Open Commerce Protocol. A searchable directory of agent-enabled websites — the "agents.directory" — where AI agents can discover sites that expose OCP tools or agent APIs.

Installation

npm install @opencommerceprotocol/registry

Quick Start

Run the registry server

OCP_REGISTRY_PORT=3200 OCP_REGISTRY_DB=./registry.db npx tsx src/index.ts

Embed in your application

import { createApp } from '@opencommerceprotocol/registry';
import { serve } from '@hono/node-server';

const { app, storage } = createApp('./registry.db');

serve({ fetch: app.fetch, port: 3200 });
console.log('OCP Registry running at http://localhost:3200');

createApp(dbPath?)

Returns { app: Hono, storage: RegistryStorage }.

| Parameter | Default | Description | |-----------|---------|-------------| | dbPath | ':memory:' | SQLite database file path |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | OCP_REGISTRY_PORT | 3200 | HTTP server port | | OCP_REGISTRY_DB | ./ocp-registry.db | SQLite database path |

API Endpoints

POST /v1/register — Register a site

curl -X POST http://localhost:3200/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mystore.com",
    "name": "My Store",
    "description": "Premium pet supplies — agent-enabled",
    "vertical": "commerce",
    "manifest_url": "https://mystore.com/.well-known/ocp.json",
    "tools": ["search_products", "get_product", "add_to_cart"],
    "ships_to": ["US", "CA", "GB"],
    "payment_methods": ["card", "paypal"],
    "categories": ["Dog Food", "Cat Food", "Pet Toys"],
    "price_tier": "mid"
  }'

GET /v1/search — Search registered sites

# Full-text search
curl "http://localhost:3200/v1/search?q=organic+pet+food"

# With filters
curl "http://localhost:3200/v1/search?q=restaurants&vertical=food&ships_to=US"
curl "http://localhost:3200/v1/search?vertical=commerce&payment_method=paypal&price_tier=budget"
curl "http://localhost:3200/v1/search?category=electronics&q=headphones&limit=20&offset=0"

| Query Parameter | Description | |-----------------|-------------| | q | Full-text search query | | vertical | Filter by vertical (see list below) | | ships_to | ISO country code filter | | payment_method | Payment method filter | | category | Product category filter | | price_tier | budget, mid, premium, luxury | | limit | Max results (default: 20) | | offset | Pagination offset |

GET /v1/route — Intent-based routing

Finds the most relevant site for a natural language intent:

curl "http://localhost:3200/v1/route?intent=buy+wireless+headphones+under+%24100"

Response:

{
  "url": "https://electronicshub.com",
  "name": "Electronics Hub",
  "manifest_url": "https://electronicshub.com/.well-known/ocp.json",
  "match_reason": "Best match for electronics in budget range"
}

GET /v1/site/:id — Get site details

curl http://localhost:3200/v1/site/abc123

DELETE /v1/site/:id — Unregister a site

curl -X DELETE http://localhost:3200/v1/site/abc123

GET /v1/stats — Registry statistics

curl http://localhost:3200/v1/stats

Response:

{
  "total_sites": 1234,
  "by_vertical": { "commerce": 890, "food": 234, "travel": 110 },
  "recently_registered": 42,
  "by_payment_method": { "card": 900, "paypal": 600 }
}

GET /health — Health check

curl http://localhost:3200/health
# { "status": "ok", "service": "ocp-registry" }

RegistryStorage

Access the registry database directly:

import { RegistryStorage } from '@opencommerceprotocol/registry';

const storage = new RegistryStorage('./registry.db');

// Register a site
const entry = await storage.register({
  url: 'https://mystore.com',
  name: 'My Store',
  vertical: 'commerce',
  manifest_url: 'https://mystore.com/.well-known/ocp.json',
});

// Search
const results = await storage.search({ q: 'pet food', vertical: 'commerce' });

// Get one
const site = await storage.getById(entry.id);

// Delete
await storage.delete(entry.id);

// Stats
const stats = await storage.getStats();

Verticals

The registry supports 10 verticals:

| Vertical | Description | |----------|-------------| | commerce | E-commerce stores | | food | Restaurants, food delivery, groceries | | travel | Hotels, flights, vacation packages | | knowledge | Documentation, wikis, knowledge bases | | saas | Software services | | enterprise | B2B tools and services | | finance | Financial products and services | | health | Health and wellness | | real_estate | Property listings | | media | News, content, streaming |

Self-Registration via CLI

# Register your store with the public OCP registry
npx @opencommerceprotocol/cli agent-discover https://agents.directory/register \
  --manifest .well-known/ocp.json

Public Registry

The public OCP registry is available at https://agents.directory. AI agents can query it to find agent-enabled sites by topic, vertical, or capability.

# Find pet stores that ship to the US
curl "https://agents.directory/v1/search?q=pet+food&ships_to=US&vertical=commerce"