ucp-toolkit

UCP Toolkit Plugin

Development toolkit for the Universal Commerce Protocol (UCP). A Claude Code plugin that provides schema design guidance, validation tools, spec generation commands, and AI-powered agents for building and maintaining UCP-compliant commerce APIs.

Website: ucpstore.dev | Documentation: docs.ucpstore.dev

Contact & Business Inquiries

Email: ben@ibracob.dev

For questions, support, partnerships, or business inquiries, reach out to us directly.

---

Table of Contents

• What is UCP?
• Installation
• Quick Start
• Commands
• Agents
• Skills
• Hooks
• UCP Schema Reference
• Project Integration
• Directory Structure
• Requirements
• License

---

What is UCP?

The Universal Commerce Protocol is a standardized specification for e-commerce APIs, built on JSON Schema Draft 2020-12 with custom annotations. UCP defines a unified way for commerce platforms to describe capabilities like carts, checkout, orders, payments, products, customers, and fulfillment.

UCP source schemas are used to generate:

• OpenAPI 3.1.0 specs for REST APIs
• OpenRPC 1.3.2 specs for JSON-RPC APIs
• Bundled JSON Schemas with all references resolved
• TypeScript type definitions for type-safe development

This plugin gives you the tools to design, validate, generate, and document UCP schemas directly from Claude Code.

---

Installation

claude plugin install github:ibraschwan/ucp-plugin

Or using the slash command inside Claude Code:

/plugin install github:ibraschwan/ucp-plugin

---

Quick Start

# Validate all schemas
/validate

# Generate all specs (OpenAPI, OpenRPC, bundled schemas)
/generate all

# Create TypeScript types
/types generate

# Check for broken $ref references
/check-refs

# Ask the schema designer agent to create a new capability
"Help me create a wishlist capability for UCP"

# Ask the spec validator to debug issues
"My schema changes are failing validation, can you help?"

---

Commands

/validate [target]

Validate UCP schemas, references, and spec compliance.

Parameter	Default	Options
target	all	all, schemas, refs, annotations

Validation checks performed:

• Schema syntax — Valid JSON, compliant with JSON Schema Draft 2020-12
• Required fields — $schema and $id present in every schema file
• Naming conventions — Definition names use PascalCase
• Reference resolution — All $ref paths point to existing files, no circular references
• UCP annotations — ucp_request on request schemas, ucp_response on response schemas
• Method naming — Methods follow domain.capability.action pattern

/validate              # Full validation suite
/validate schemas      # JSON Schema syntax only
/validate refs         # Reference resolution only
/validate annotations  # UCP annotation compliance only

/generate [type]

Generate OpenAPI, OpenRPC, bundled JSON Schema specs, or TypeScript types from source schemas.

Parameter	Default	Options
type	all	all, openapi, openrpc, json-schema, types

Generation outputs:

Type	Format	Output Directory
openapi	OpenAPI 3.1.0	generated/openapi/
openrpc	OpenRPC 1.3.2	generated/openrpc/
json-schema	Bundled schemas	generated/json-schema/
types	TypeScript definitions	types/

/generate              # Generate all formats
/generate openapi      # OpenAPI 3.1.0 only
/generate openrpc      # OpenRPC 1.3.2 only
/generate types        # TypeScript types only

The generation pipeline reads source schemas from source/schemas/shopping/, resolves all $ref references, and writes the output to the corresponding directory.

/types [action] [name]

Generate and explore TypeScript types from UCP schemas.

Parameter	Default	Options
action	generate	generate, list, show
name	—	Type name (for show action)

/types                 # Generate all TypeScript types
/types list            # List available types
/types show money      # Show the money type definition

Available type categories:

• Core — money.json, address.json, pagination.json, error.json
• Product — product-variant.json, product-option.json, inventory.json
• Order — line-item.json, discount.json, shipping-rate.json
• Customer — customer.json, payment-method.json

/docs [action] [topic]

Access and generate UCP documentation.