菜单
Expert-level implementation assistant for the Universal Commerce Protocol (UCP). Provides comprehensive tooling for adding UCP support to Next.js ecommerce codebases — from initial consultation through full implementation, testing, and validation.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/vercel-labs/agentic-commerce-skills --skill ucp命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | ucp |
| description | Expert-level implementation assistant for the Universal Commerce Protocol (UCP). Provides comprehensive tooling for adding UCP support to Next.js ecommerce codebases — from initial consultation through full implementation, testing, and validation. |
| arguments | {"Optional sub-command":"init | consult | plan | gaps | scaffold | validate | profile | test | docs"} |
| user_invocable | true |
ucp.config.jsonCheck in this order:
./ucp/ — User's local copy (use as-is)./.ucp-spec/ — Previously cloned spec (update it)When cloning is needed:
git clone --depth 1 https://github.com/Universal-Commerce-Protocol/ucp.git .ucp-spec
If HTTPS fails, try SSH:
git clone --depth 1 git@github.com:Universal-Commerce-Protocol/ucp.git .ucp-spec
When ./.ucp-spec/ exists:
cd .ucp-spec && git pull && cd ..
After cloning, ensure .ucp-spec/ is in .gitignore:
.gitignore if it exists.ucp-spec/ or .ucp-spec is already listed.ucp-spec/ on a new linedocs/specification/overview.md
docs/specification/checkout.md
docs/specification/checkout-rest.md
docs/specification/checkout-mcp.md
docs/specification/checkout-a2a.md
docs/specification/embedded-checkout.md
docs/specification/order.md
docs/specification/fulfillment.md
docs/specification/discount.md
docs/specification/buyer-consent.md
docs/specification/identity-linking.md
docs/specification/ap2-mandates.md
docs/specification/payment-handler-guide.md
docs/specification/tokenization-guide.md
spec/services/shopping/rest.openapi.json
spec/services/shopping/mcp.openrpc.json
spec/services/shopping/embedded.openrpc.json
spec/handlers/tokenization/openapi.json
spec/schemas/shopping/*
spec/discovery/profile_schema.json
./ucp.config.json at project root
{
"$schema": "./ucp.config.schema.json",
"ucp_version": "2026-01-11",
"roles": ["business"],
"runtime": "nodejs",
"capabilities": {
"core": ["dev.ucp.shopping.checkout"],
"extensions": []
},
"transports": ["rest"],
"transport_priority": ["rest", "mcp", "a2a", "embedded"],
"payment_handlers": [],
"features"
| Field | Type | Description |
|---|---|---|
ucp_version | string | UCP spec version (date-based) |
roles | string[] | One or more of: business, platform, payment_provider, host_embedded |
runtime | string | nodejs (default) or bun |
capabilities.core | string[] | Required capabilities to implement |
capabilities.extensions | string[] | Optional extensions to implement |
transports | string[] | Enabled transports: rest, mcp, a2a, embedded |
transport_priority | string[] | Order to implement transports |
payment_handlers | string[] | Payment handler IDs to support |
features.ap2_mandates | boolean | Enable AP2 mandate signing |
features.identity_linking | boolean | Enable OAuth identity linking |
features.multi_destination_fulfillment | boolean | Enable multi-destination shipping |
domain | string | Business domain for /.well-known/ucp |
existing_apis | object | Map of existing API endpoints to analyze |
policy_urls | object | URLs for privacy, terms, refunds, shipping policies |
scaffold_depth | string | types | scaffolding | full |
generated_files | string[] |
User runs /ucp with no sub-command
Display help listing all available sub-commands:
UCP Skill — Universal Commerce Protocol Implementation
Available commands:
/ucp init — Initialize UCP in this project (clone spec, create config)
/ucp consult — Full consultation: answer qualifying questions, build roadmap
/ucp plan — Generate detailed implementation plan
/ucp gaps — Analyze existing code against UCP requirements
/ucp scaffold — Generate full working UCP implementation
/ucp validate — Validate implementation against UCP schemas
/ucp profile — Generate /.well-known/ucp discovery profile
/ucp test — Generate unit tests for UCP handlers
/ucp docs — Generate internal documentation
Typical workflow:
/ucp init → /ucp consult → /ucp plan → /ucp scaffold → /ucp profile → /ucp test → /ucp validate
Configuration: ./ucp.config.json
Spec location: ./ucp/ or ./.ucp-spec/
User runs /ucp init
Bootstrap UCP in a project: clone spec, create config, ask essential questions.
./ucp/ exists
./.ucp-spec/ exists
git pull to update.ucp-spec/ to .gitignore./ucp.config.json existsQ1: What role(s) are you implementing?
If user selects multiple roles, WARN:
"Implementing multiple roles is unusual. This is typically for marketplace/aggregator scenarios. Are you sure?"
Q2: What runtime will you use?
NOTE: If user mentions Edge, respond:
"Edge runtime is not supported for UCP implementations. Please choose Node.js or Bun."
Q3: What is your business domain?
/.well-known/ucpshop.example.comQ4: Which transports do you need at launch?
Create ./ucp.config.json with:
ucp_version set to latest from specUCP initialized successfully!
Config: ./ucp.config.json
Spec: ./.ucp-spec/ (or ./ucp/)
Role: {role}
Domain: {domain}
Next steps:
/ucp consult — Complete full consultation (recommended)
/ucp plan — Skip to implementation planning
/ucp gaps — Analyze existing code first
User runs /ucp consult
Walk through all 12 qualifying questions, update config, produce implementation roadmap.
/ucp init first)Read ./ucp.config.json and use existing answers as defaults.
Ask each question. If already answered in config, show current value and ask to confirm or change.
Q1: Are we implementing the business side, the platform side, or both?
roles in configQ2: Which UCP version and which capabilities/extensions are in scope?
dev.ucp.shopping.checkout (required)dev.ucp.shopping.fulfillmentdev.ucp.shopping.discountdev.ucp.shopping.buyer_consentdev.ucp.shopping.ap2_mandatedev.ucp.shopping.orderdev.ucp.common.identity_linkingQ3: Which payment handlers do we need?
Q4: Do we need AP2 mandates and signing key infrastructure?
features.ap2_mandates: truefeatures.ap2_mandates: falseQ5: Do we need fulfillment options and multi-group/multi-destination support?
features.multi_destination_fulfillment: trueQ6: Do we need discounts, buyer consent capture, or identity linking?
dev.ucp.shopping.discount to extensionsdev.ucp.shopping.buyer_consent to extensionsdev.ucp.common.identity_linking, set features.identity_linking: trueQ7: What are the existing checkout and order APIs we should map to UCP?
existing_apis object/api/checkout, /api/cart, /api/ordersQ8: What are the required policy URLs?
policy_urls objectQ9: What authentication model is required for checkout endpoints?
answers.authentication_modelQ10: Who will receive order webhooks and what event cadence is required?
order.created, order.updated, order.fulfilled, order.canceledanswers.webhook_configQ11: Do we need to support MCP, A2A, or embedded checkout at launch?
transports arraytransport_priority orderQ12: What is the business domain that will host /.well-known/ucp?
domain fieldWrite all answers to ./ucp.config.json
Based on answers, produce a roadmap:
UCP Implementation Roadmap
==========================
Role: Business (merchant)
Version: 2026-01-11
Domain: shop.example.com
Capabilities to implement:
✓ dev.ucp.shopping.checkout (core)
✓ dev.ucp.shopping.fulfillment
✓ dev.ucp.shopping.discount
○ dev.ucp.shopping.order
Transports (in order):
1. REST
2. MCP
Payment handlers:
- Stripe tokenization
Key implementation tasks:
1. Create /.well-known/ucp discovery profile
2. Implement checkout session endpoints (create, get, update, complete)
3. Implement fulfillment options logic
4. Implement discount code application
5. Set up payment handler integration
6. Implement order webhooks
7. Add MCP transport layer
Estimated files to create/modify: ~15-20
Run /ucp plan for detailed file-by-file plan.
User runs /ucp plan
Generate detailed implementation plan with specific files and order of operations.
./ucp.config.jsonFor each capability/transport, list files to create/modify.
Example output:
UCP Implementation Plan
=======================
Phase 1: Core Types and Schemas
-------------------------------
CREATE lib/ucp/types/checkout.ts
- CheckoutSession interface
- LineItem, Totals, Payment types
- Status enum
CREATE lib/ucp/types/index.ts
- Re-export all types
CREATE lib/ucp/schemas/checkout.ts
- Zod schemas for validation
Phase 2: Discovery Profile
--------------------------
CREATE app/.well-known/ucp/route.ts
- GET handler returning profile JSON
- Read capabilities from config
CREATE lib/ucp/profile.ts
- Profile generation logic
Phase 3: Checkout Endpoints (REST)
----------------------------------
CREATE app/api/ucp/checkout/route.ts
- POST: Create checkout session
- Capability negotiation logic
CREATE app/api/ucp/checkout/[id]/route.ts
- GET: Retrieve checkout
- PATCH: Update checkout
- POST: Complete checkout (action=complete)
CREATE lib/ucp/handlers/checkout.ts
- Business logic for checkout operations
- State machine implementation
Phase 4: Fulfillment Extension
------------------------------
CREATE lib/ucp/handlers/fulfillment.ts
- Fulfillment options calculation
- Destination validation
MODIFY lib/ucp/handlers/checkout.ts
- Integrate fulfillment into checkout response
Phase 5: Discount Extension
---------------------------
CREATE lib/ucp/handlers/discount.ts
- Discount code validation
- Applied discount calculation
MODIFY lib/ucp/handlers/checkout.ts
- Integrate discounts into checkout
Phase 6: Payment Integration
----------------------------
CREATE lib/ucp/handlers/payment.ts
- Payment handler registry
- payment_data processing
CREATE lib/ucp/handlers/stripe.ts
- Stripe-specific tokenization
Phase 7: Order Webhooks
-----------------------
CREATE lib/ucp/handlers/order.ts
- Order event emission
- Webhook signing (JWS)
CREATE lib/ucp/webhooks/sender.ts
- Webhook delivery with retries
Phase 8: MCP Transport (if enabled)
-----------------------------------
CREATE lib/ucp/transports/mcp.ts
- MCP tool definitions
- JSON-RPC handlers
Dependencies to install:
------------------------
zod — Schema validation
jose — JWS signing (if AP2/webhooks enabled)
Run /ucp scaffold to generate these files.
Store the plan in answers.implementation_plan for scaffold reference.
User runs /ucp gaps
Deep analysis of existing codebase against UCP requirements. Uses AST parsing and data flow tracing.
Scan for:
app/api/**, pages/api/**)For each relevant file:
Analyze against UCP requirements:
| Requirement | Status | Finding |
|---|---|---|
| Discovery profile at /.well-known/ucp | MISSING | No route found |
| Checkout session creation | PARTIAL | Found /api/checkout but missing UCP fields |
| Status lifecycle | MISSING | No status state machine |
| Capability negotiation | MISSING | No UCP-Agent header handling |
| Payment handler support | PARTIAL | Stripe exists but not UCP-compliant |
| Response metadata (ucp object) | MISSING | Responses don't include ucp field |
UCP Gap Analysis Report
=======================
Existing codebase: Next.js 14 (App Router)
Target role: Business
Target capabilities: checkout, fulfillment, discount
CRITICAL GAPS (must fix)
------------------------
[GAP-001] Missing discovery profile
- Required: /.well-known/ucp endpoint
- Status: NOT FOUND
- Fix: Create app/.well-known/ucp/route.ts
[GAP-002] Missing UCP response envelope
- Required: All responses must include `ucp` object with version/capabilities
- Found: app/api/checkout/route.ts returns raw checkout data
- Fix: Wrap responses with UCP metadata
[GAP-003] Missing capability negotiation
- Required: Read UCP-Agent header, compute intersection
- Found: No header processing in checkout routes
- Fix: Add middleware or handler logic
PARTIAL IMPLEMENTATIONS
-----------------------
[PARTIAL-001] Checkout session exists but non-compliant
- File: app/api/checkout/route.ts
- Missing: id, status, currency, totals.grand_total, links, payment fields
- Has: line_items (needs schema adjustment)
[PARTIAL-002] Payment integration exists
- File: lib/stripe.ts
- Issue: Direct Stripe API, not UCP payment_data flow
- Fix: Wrap with UCP payment handler abstraction
COMPLIANT AREAS
---------------
[OK] Policy URLs configured in existing checkout
[OK] HTTPS enforced
[OK] Idempotency key support in POST handlers
RECOMMENDATIONS
---------------
1. Start with /ucp scaffold to generate compliant structure
2. Migrate existing checkout logic into new handlers
3. Run /ucp validate after migration
Total: 3 critical gaps, 2 partial, 3 compliant
User runs /ucp scaffold
Generate full working UCP implementation based on config and plan.
/ucp plan first, or scaffold will generate one)Ask user:
"What level of code generation do you want?"
- types: TypeScript interfaces and Zod schemas only
- scaffolding: Structure with TODO markers for business logic
- full: Complete working implementation (recommended)
Store choice in config.scaffold_depth
Identify required packages based on config:
zod — Always neededjose — If AP2 mandates or webhook signing enableduuid — For session ID generationAsk before installing:
"The following packages are required: zod, jose, uuid" "Install now? (npm install / bun add)"
If yes, run appropriate install command.
Generate files according to plan. For each file:
config.generated_files/**
* UCP Checkout Types
* Generated by /ucp scaffold
* Spec: {spec_version}
*/
export type CheckoutStatus =
| 'incomplete'
| 'requires_escalation'
| 'ready_for_complete'
| 'complete_in_progress'
| 'completed'
| 'canceled';
export type MessageSeverity =
| 'recoverable'
| 'requires_buyer_input'
| 'requires_buyer_review';
export interface UCPMetadata {
version: string;
capabilities: string[];
}
export interface LineItem {
id: string;
name: string;
quantity: number;
unit_price: number;
total_price: number;
currency: string;
// Extension fields added based on config
}
export interface Totals {
subtotal: number;
tax: number;
shipping: number;
discount: number;
grand_total: ;
: ;
}
{
: | | | ;
: [];
: ;
: ;
}
{
: ;
: ;
?: <, >;
}
{
: ;
: ;
: ;
?: ;
}
{
: ;
?: ;
: ;
: ;
?: ;
?: ;
}
{
: ;
: ;
: ;
: ;
: [];
: ;
: ;
: ;
: [];
: ;
: ;
: ;
?: ;
?: ;
?: ;
}
{
?: ;
?: ;
?: ;
}
/**
* UCP Checkout Zod Schemas
* Generated by /ucp scaffold
*/
import { z } from 'zod';
export const LineItemSchema = z.object({
id: z.string(),
name: z.string(),
quantity: z.number().int().positive(),
unit_price: z.number().int(), // minor units (cents)
total_price: z.number().int(),
currency: z.string().length(3),
});
export const TotalsSchema = z.object({
subtotal: z.number().int(),
tax: z.number().int(),
shipping: z.number().int(),
discount: z.number().int(),
grand_total: z.number().int(),
currency: z.string().length(3),
});
export = z.({
: z.().(),
: z.().(),
: z.({
: z.().().(),
: z.().(),
}).(),
});
= z.({
: z.().(),
: z.({
: z.().().(),
: z.().(),
}).(),
});
= z.({
: z.(),
: z.(z.()),
});
= z.< >;
= z.< >;
= z.< >;
/**
* UCP Discovery Profile Endpoint
* GET /.well-known/ucp
* Generated by /ucp scaffold
*/
import { NextResponse } from 'next/server';
import { generateProfile } from '@/lib/ucp/profile';
export const runtime = 'nodejs'; // Edge runtime is not supported
export async function GET() {
const profile = generateProfile();
return NextResponse.json(profile, {
headers: {
'Cache-Control': 'public, max-age=3600',
'Content-Type': 'application/json',
},
});
}
/**
* UCP Discovery Profile Generator
* Generated by /ucp scaffold
*/
import config from '@/../ucp.config.json';
export interface UCPProfile {
ucp: {
version: string;
services: Record<string, ServiceDefinition>;
capabilities: CapabilityDefinition[];
};
payment?: {
handlers: PaymentHandlerDefinition[];
};
signing_keys?: JsonWebKey[];
}
interface ServiceDefinition {
version: string;
spec: string;
rest?: { schema: string; endpoint: string };
mcp?: { schema: string; endpoint: string };
a2a?: { endpoint: string };
embedded?: { schema: string };
}
interface CapabilityDefinition {
name: string;
version: string;
spec: string;
schema: ;
?: ;
?: <, >;
}
{
: ;
: ;
: ;
: ;
}
(): {
baseUrl = ;
: = {
: {
: config.,
: {
: {
: config.,
: ,
...(config..() && {
: {
: ,
: ,
},
}),
...(config..() && {
: {
: ,
: ,
},
}),
...(config..() && {
: {
: ,
},
}),
...(config..() && {
: {
: ,
},
}),
},
},
: (config),
},
};
(config.. > ) {
profile. = {
: config..(buildHandlerDefinition),
};
}
profile;
}
(): [] {
: [] = [];
capabilities.({
: ,
: config.,
: ,
: ,
});
( ext config..) {
capabilities.((ext, config));
}
capabilities;
}
(): {
: <, { : ; : ; ?: }> = {
: {
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
},
: {
: ,
: ,
: {
: config.?.?.,
},
},
: {
: ,
: ,
},
};
def = extMap[extension];
{
: extension,
: config.,
: def?. || ,
: def?. || ,
...(def?. && { : def. }),
...(def?. && { : def. }),
};
}
(): {
: <, <, >> = {
: {
: ,
: ,
: ,
},
};
def = handlerMap[handlerId] || {
: ,
: ,
: ,
};
{ : handlerId, ...def };
}
/**
* UCP Checkout Session Endpoint
* POST /api/ucp/checkout - Create checkout session
* Generated by /ucp scaffold
*/
import { NextRequest, NextResponse } from 'next/server';
import { createCheckout } from '@/lib/ucp/handlers/checkout';
import { CreateCheckoutRequestSchema } from '@/lib/ucp/schemas/checkout';
import { negotiateCapabilities, parseUCPAgent } from '@/lib/ucp/negotiation';
import { wrapResponse, errorResponse } from '@/lib/ucp/response';
export const runtime = 'nodejs'; // Edge runtime is not supported
export async function POST(request: NextRequest) {
try {
// Parse UCP-Agent header for capability negotiation
const ucpAgent = parseUCPAgent(request.headers.get('UCP-Agent'));
// Negotiate capabilities
const negotiation = await negotiateCapabilities(ucpAgent?.profile);
// Parse and validate request body
const body = await request.json();
parsed = .(body);
(!parsed.) {
(, , parsed..);
}
idempotencyKey = request..();
checkout = (parsed., {
: negotiation.,
idempotencyKey,
});
(checkout, negotiation, );
} (error) {
.(, error);
(, , );
}
}
/**
* UCP Checkout Handler
* Core business logic for checkout operations
* Generated by /ucp scaffold
*/
import { randomUUID } from 'crypto';
import type {
CheckoutSession,
CheckoutStatus,
CreateCheckoutRequest,
UpdateCheckoutRequest,
} from '@/lib/ucp/types/checkout';
import config from '@/../ucp.config.json';
// In-memory store for demo - replace with your database
const checkoutStore = new Map<string, CheckoutSession>();
interface CreateCheckoutOptions {
capabilities: string[];
idempotencyKey?: string | null;
}
export async function createCheckout(
request: CreateCheckoutRequest,
options: CreateCheckoutOptions
): Promise<CheckoutSession> {
const id = randomUUID();
const now = new Date().toISOString();
const expiresAt = new Date(Date.() + * * ).();
subtotal = request..( sum + item., );
tax = (subtotal);
shipping = ;
discount = ;
: = {
: {
: config.,
: options.,
},
id,
: ,
: request.,
: request..( ({
...item,
: item. || ,
})),
: {
subtotal,
tax,
shipping,
discount,
: subtotal + tax + shipping - discount,
: request.,
},
: {
: ,
: (options.),
: subtotal + tax + shipping - discount,
: request.,
},
: {
: ,
: ,
: config..,
: config..,
...(config.. && { : config.. }),
...(config.. && { : config.. }),
},
: [],
: expiresAt,
: now,
: now,
};
(request.) {
checkout. = request.;
}
checkout. = (checkout);
checkout. = (checkout);
checkoutStore.(id, checkout);
checkout;
}
(): < | > {
checkoutStore.(id) || ;
}
(): < | > {
checkout = checkoutStore.(id);
(!checkout) ;
([, ].(checkout.)) {
();
}
(request.) {
checkout. = request.;
(checkout);
}
(request.) {
checkout. = { ...checkout., ...request. };
}
checkout. = ().();
checkout.. = capabilities;
checkout. = (checkout);
checkout. = (checkout);
checkoutStore.(id, checkout);
checkout;
}
(): < | > {
checkout = checkoutStore.(id);
(!checkout) ;
(checkout. !== ) {
();
}
checkout. = ;
checkout. = ().();
checkoutStore.(id, checkout);
{
(checkout, paymentData);
checkout. = ;
checkout.. = ;
checkout. = ().();
checkoutStore.(id, checkout);
(capabilities.()) {
(checkout);
}
checkout;
} (error) {
checkout. = ;
checkout.. = ;
checkout..({
: ,
: ,
: error ? error. : ,
});
checkout. = ().();
checkoutStore.(id, checkout);
checkout;
}
}
(): {
: [] = [];
(!checkout.?.) {
missingFields.();
}
(checkout. && !checkout..) {
missingFields.();
}
(missingFields. > ) {
;
}
(checkout..( m. === )) {
;
}
;
}
(): [] {
: [] = [];
(!checkout.?.) {
messages.({
: ,
: ,
: ,
: ,
});
}
messages;
}
(): {
subtotal = checkout..( sum + item., );
checkout.. = subtotal;
checkout.. = (subtotal);
checkout.. =
subtotal + checkout.. + checkout.. - checkout..;
checkout.. = checkout..;
}
(): {
.(subtotal * );
}
(): [][] {
config..( ({
id,
: ,
}));
}
(): <> {
handlerId = paymentData. ;
(!config..(handlerId)) {
();
}
}
(): <> {
}
/**
* UCP Capability Negotiation
* Generated by /ucp scaffold
*/
import config from '@/../ucp.config.json';
interface UCPAgentInfo {
profile: string;
}
interface NegotiationResult {
capabilities: string[];
version: string;
}
/**
* Parse UCP-Agent header (RFC 8941 dictionary syntax)
* Example: profile="https://platform.example.com/.well-known/ucp"
*/
export function parseUCPAgent(header: string | null): UCPAgentInfo | null {
if (!header) return null;
const profileMatch = header.match(/profile="([^"]+)"/);
if (!profileMatch) return null;
return { profile: profileMatch[1] };
}
/**
* Negotiate capabilities between business and platform
*/
export async function negotiateCapabilities(
platformProfileUrl?: string
): Promise<NegotiationResult> {
// Business capabilities
const businessCapabilities = ([
...config..,
...config..,
]);
(!platformProfileUrl) {
{
: .(businessCapabilities),
: config.,
};
}
{
response = (platformProfileUrl, {
: { : },
});
(!response.) {
.();
{
: .(businessCapabilities),
: config.,
};
}
platformProfile = response.();
profileUrl = (platformProfileUrl);
platformCapabilities = (
platformProfile.?.?.( c.) || []
);
intersection = [...businessCapabilities].(
platformCapabilities.(c)
);
platformVersion = platformProfile.?.;
(platformVersion && platformVersion > config.) {
();
}
{
: intersection,
: config.,
};
} (error) {
.(, error);
{
: .(businessCapabilities),
: config.,
};
}
}
/**
* UCP Response Helpers
* Generated by /ucp scaffold
*/
import { NextResponse } from 'next/server';
import type { NegotiationResult } from './negotiation';
/**
* Wrap a response with UCP metadata
*/
export function wrapResponse<T extends { ucp?: unknown }>(
data: T,
negotiation: NegotiationResult,
status: number = 200
): NextResponse {
// Ensure ucp metadata is present
const response = {
...data,
ucp: {
version: negotiation.version,
capabilities: negotiation.capabilities,
},
};
return NextResponse.json(response, { status });
}
/**
* Create an error response
*/
export function errorResponse(
status: number,
code: string,
message: string,
details?: Record<string, unknown>
): NextResponse {
return .(
{
: {
code,
message,
...(details && { details }),
},
},
{ status }
);
}
When MCP transport is enabled in config, generate these additional files.
npm install mcp-handler @modelcontextprotocol/sdk@1.25.2 zod
IMPORTANT: Use @modelcontextprotocol/sdk@1.25.2 or later — earlier versions have security vulnerabilities.
/**
* UCP MCP Transport Endpoint
* Model Context Protocol server for UCP checkout operations
* Generated by /ucp scaffold
*
* Supports:
* - Streamable HTTP transport (direct client connection)
* - SSE transport (via mcp-remote bridge)
*
* @see https://github.com/vercel/mcp-handler
*/
import { createMcpHandler } from 'mcp-handler';
import { z } from 'zod';
import {
createCheckout,
getCheckout,
updateCheckout,
completeCheckout,
} from '@/lib/ucp/handlers/checkout';
import { negotiateCapabilities } from '@/lib/ucp/negotiation';
import { generateProfile } from '@/lib/ucp/profile';
import config from '@/../ucp.config.json';
export const runtime = 'nodejs'; // Edge runtime is not supported
const handler = createMcpHandler(
(server) => {
// =========================================================================
// UCP Discovery
// =========================================================================
server.registerTool(
'ucp_get_profile',
{
title: 'Get UCP Profile',
description: 'Retrieve the UCP discovery profile for this business. Returns supported capabilities, transports, and payment handlers.',
inputSchema: {},
},
async () => {
const profile = ();
{
: [
{
: ,
: .(profile, , ),
},
],
};
}
);
server.(
,
{
: ,
: ,
: {
: z.(
z.({
: z.().().(),
: z.().(),
: z.().().().(),
: z.().().(),
: z.().().(),
: z.().().(),
})
).().(),
: z.().().(),
: z.({
: z.().().().(),
: z.().().(),
: z.().().(),
}).().(),
: z.().().().(),
},
},
({ line_items, currency, buyer, platform_profile_url }) => {
{
negotiation = (platform_profile_url);
checkout = (
{ line_items, currency, buyer },
{ : negotiation. }
);
{
: [
{
: ,
: .(checkout, , ),
},
],
};
} (error) {
{
: [
{
: ,
: .({
: {
: ,
: error ? error. : ,
},
}),
},
],
: ,
};
}
}
);
server.(
,
{
: ,
: ,
: {
: z.().(),
},
},
({ checkout_id }) => {
checkout = (checkout_id);
(!checkout) {
{
: [
{
: ,
: .({
: {
: ,
: ,
},
}),
},
],
: ,
};
}
{
: [
{
: ,
: .(checkout, , ),
},
],
};
}
);
server.(
,
{
: ,
: ,
: {
: z.().(),
: z.(
z.({
: z.(),
: z.(),
: z.().().(),
: z.().(),
: z.().(),
: z.().(),
})
).().(),
: z.({
: z.().().(),
: z.().(),
: z.().(),
}).().(),
: z.({
: z.().().(),
: z.({
: z.(),
: z.().(),
: z.(),
: z.().(),
: z.(),
: z.().(),
}).().(),
}).().(),
: z.(z.()).().(),
: z.().().().(),
},
},
({ checkout_id, line_items, buyer, fulfillment, discount_codes, platform_profile_url }) => {
{
negotiation = (platform_profile_url);
checkout = (
checkout_id,
{ line_items, buyer },
negotiation.
);
(!checkout) {
{
: [
{
: ,
: .({
: {
: ,
: ,
},
}),
},
],
: ,
};
}
{
: [
{
: ,
: .(checkout, , ),
},
],
};
} (error) {
{
: [
{
: ,
: .({
: {
: ,
: error ? error. : ,
},
}),
},
],
: ,
};
}
}
);
server.(
,
{
: ,
: ,
: {
: z.().(),
: z.({
: z.().(),
: z.().().(),
: z.(z.()).().(),
}).(),
: z.().().().(),
},
},
({ checkout_id, payment_data, platform_profile_url }) => {
{
negotiation = (platform_profile_url);
checkout = (
checkout_id,
payment_data,
negotiation.
);
(!checkout) {
{
: [
{
: ,
: .({
: {
: ,
: ,
},
}),
},
],
: ,
};
}
{
: [
{
: ,
: .(checkout, , ),
},
],
};
} (error) {
{
: [
{
: ,
: .({
: {
: ,
: error ? error. : ,
},
}),
},
],
: ,
};
}
}
);
(config...()) {
server.(
,
{
: ,
: ,
: {
: z.().(),
: z.({
: z.(),
: z.().(),
: z.(),
: z.().(),
: z.(),
: z.().().(),
}).(),
},
},
({ checkout_id, destination }) => {
{
: [
{
: ,
: .({
checkout_id,
destination,
: [
{
: ,
: ,
: ,
: ,
: ,
},
{
: ,
: ,
: ,
: ,
: ,
},
],
}, , ),
},
],
};
}
);
}
(config...()) {
server.(
,
{
: ,
: ,
: {
: z.().(),
: z.().(),
},
},
({ checkout_id, code }) => {
{
: [
{
: ,
: .({
: ,
code,
: {
: ,
: ,
: ,
},
}, , ),
},
],
};
}
);
}
server.(
,
{
: ,
: ,
: {
: z.().(),
},
},
({ checkout_id }) => {
checkout = (checkout_id);
(!checkout) {
{
: [
{
: ,
: .({
: {
: ,
: ,
},
}),
},
],
: ,
};
}
{
: [
{
: ,
: .({
checkout_id,
: checkout..,
: checkout..,
: checkout..,
}, , ),
},
],
};
}
);
},
{
: ,
: config.,
},
{
: ,
: ,
: process.. === ,
}
);
{ handler , handler };
/**
* UCP MCP Tool Definitions
* Reusable tool schemas for MCP transport
* Generated by /ucp scaffold
*/
import { z } from 'zod';
// Common schemas
export const LineItemSchema = z.object({
id: z.string().optional(),
name: z.string(),
quantity: z.number().int().positive(),
unit_price: z.number().int(),
total_price: z.number().int(),
currency: z.string().length(3),
});
export const BuyerSchema = z.object({
email: z.string().email().optional(),
phone: z.string().optional(),
name: z.string().optional(),
});
export const AddressSchema = z.object({
address_line1: z.string(),
address_line2: z.string().(),
: z.(),
: z.().(),
: z.(),
: z.().(),
});
= z.({
: z.(),
: z.().(),
: z.(z.()).(),
});
= {
: {
: ,
: {},
},
: {
: ,
: {
: ,
: ,
: ,
: ,
},
},
: {
: ,
: {
: ,
},
},
: {
: ,
: {
: ,
: ,
: ,
: ,
: ,
},
},
: {
: ,
: {
: ,
: ,
},
},
: {
: ,
: {
: ,
: ,
},
},
: {
: ,
: {
: ,
: ,
},
},
: {
: ,
: {
: ,
},
},
} ;
{
"framework": "nextjs",
"regions": ["iad1"],
"functions": {
"app/api/mcp/[transport]/route.ts": {
"maxDuration": 60
},
"app/api/ucp/**/*.ts": {
"maxDuration": 30
}
},
"headers": [
{
"source": "/.well-known/ucp",
"headers": [
{
"key": "Cache-Control",
"value": "public, max-age=3600"
},
{
"key": "Content-Type"
Set these in Vercel Dashboard → Settings → Environment Variables:
| Variable | Required | Description |
|---|---|---|
UCP_DOMAIN | Yes | Production domain (e.g., shop.example.com) |
UCP_SIGNING_KEY | If AP2 | JWS signing key (PEM or JWK) |
STRIPE_SECRET_KEY | If Stripe | Stripe API secret key |
/** @type {import('next').NextConfig} */
const nextConfig = {
// Required for mcp-handler streaming
experimental: {
serverActions: {
bodySizeLimit: '2mb',
},
},
// Ensure proper headers for MCP
async headers() {
return [
{
source: '/api/mcp/:path*',
headers: [
{ key: 'Access-Control-Allow-Origin', value: '*' },
{ key: 'Access-Control-Allow-Methods', value: 'GET, POST, OPTIONS' },
{ key: 'Access-Control-Allow-Headers', value: 'Content-Type, Authorization' },
],
},
];
},
// Required for MCP streaming responses
async rewrites() {
return [];
},
};
module.exports = nextConfig;
Option 1: Direct HTTP (if client supports streamable HTTP) Add to MCP client config:
{
"mcpServers": {
"ucp-shopping": {
"url": "https://your-domain.vercel.app/api/mcp"
}
}
}
Option 2: Via mcp-remote bridge (for stdio-only clients)
{
"mcpServers": {
"ucp-shopping": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://your-domain.vercel.app/api/mcp"]
}
}
}
#!/usr/bin/env node
/**
* MCP Server Test Script
* Usage: node scripts/test-mcp.mjs [deployment-url]
*/
const deploymentUrl = process.argv[2] || 'http://localhost:3000';
async function testMcpServer() {
console.log(`Testing MCP server at ${deploymentUrl}/api/mcp\n`);
// Test 1: Get Profile
console.log('1. Testing ucp_get_profile...');
const profileResponse = await fetch(`${deploymentUrl}/api/mcp`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: {
name: 'ucp_get_profile',
arguments: {},
},
}),
});
const profileResult = await profileResponse.json();
console.log(' Profile:', profileResult.result ? 'OK' : );
.();
createResponse = (, {
: ,
: { : },
: .({
: ,
: ,
: ,
: {
: ,
: {
: [
{
: ,
: ,
: ,
: ,
: ,
},
],
: ,
},
},
}),
});
createResult = createResponse.();
.(, createResult. ? : );
(createResult.?.?.[]?.) {
checkout = .(createResult..[].);
.();
.();
.();
getResponse = (, {
: ,
: { : },
: .({
: ,
: ,
: ,
: {
: ,
: { : checkout. },
},
}),
});
getResult = getResponse.();
.(, getResult. ? : );
}
.();
}
().(.);
When running /ucp scaffold with Vercel deployment, verify:
vercel.json created with function timeoutsnext.config.js updated for MCP streamingapp/api/mcp/[transport]/route.tsscripts/test-mcp.mjs.env.example updated with required variablesAfter deploying to Vercel:
Check discovery profile:
curl https://your-domain.vercel.app/.well-known/ucp | jq .
Test MCP endpoint:
node scripts/test-mcp.mjs https://your-domain.vercel.app
Configure MCP client: Add the server to Claude Desktop, Cursor, or your preferred MCP client.
Verify in client: Ask the AI to "list available UCP tools" — it should show the checkout tools.
After generation, update ucp.config.json:
generated_files arrayscaffold_depth to reflect what was generatedUCP Scaffold Complete
=====================
Generated files:
CREATE lib/ucp/types/checkout.ts
CREATE lib/ucp/types/index.ts
CREATE lib/ucp/schemas/checkout.ts
CREATE lib/ucp/profile.ts
CREATE lib/ucp/negotiation.ts
CREATE lib/ucp/response.ts
CREATE lib/ucp/handlers/checkout.ts
CREATE app/.well-known/ucp/route.ts
CREATE app/api/ucp/checkout/route.ts
CREATE app/api/ucp/checkout/[id]/route.ts
MCP Transport (if enabled):
CREATE app/api/mcp/[transport]/route.ts
CREATE lib/ucp/transports/mcp-tools.ts
Vercel Deployment:
CREATE vercel.json
CREATE scripts/test-mcp.mjs
MODIFY next.config.js
Dependencies installed:
zod, jose, uuid
mcp-handler, @modelcontextprotocol/sdk (if MCP enabled)
Next steps:
1. Review generated code and customize business logic
2. Set environment variables in Vercel dashboard
3. Deploy: vercel --prod
4. Run /ucp profile to verify discovery profile
5. Run /ucp test to generate unit tests
6. Run /ucp validate to check compliance
7. Configure MCP client with deployment URL
User runs /ucp validate
Validate the implementation against UCP JSON schemas.
/ucp scaffold first)Read JSON schemas from spec:
spec/schemas/shopping/checkout.jsonspec/schemas/shopping/fulfillment.jsonspec/schemas/shopping/discount.jsonspec/discovery/profile_schema.json/.well-known/ucp route (or read file directly)profile_schema.jsonFor each implemented endpoint:
Verify:
ucp objectUCP Validation Report
=====================
Discovery Profile: PASS
✓ Schema valid
✓ Required fields present
✓ Service definitions valid
✓ Capability specs accessible
Checkout Endpoints:
POST /api/ucp/checkout
✓ Response schema valid
✓ UCP metadata present
✓ Status enum valid
GET /api/ucp/checkout/[id]
✓ Response schema valid
✓ Idempotent
PATCH /api/ucp/checkout/[id]
✓ Response schema valid
✓ Partial update works
POST /api/ucp/checkout/[id] (complete)
✓ Response schema valid
✓ State transition correct
Protocol Requirements:
✓ Amounts in minor units
✓ Dates in RFC 3339
✓ HTTPS links
✓ Reverse-DNS capability names
Overall: PASS (24/24 checks)
User runs /ucp profile
Generate and display the /.well-known/ucp discovery profile JSON.
Use the generateProfile() function from lib/ucp/profile.ts (or generate inline if not scaffolded yet).
Output the formatted JSON:
{
"ucp": {
"version": "2026-01-11",
"services": {
"dev.ucp.shopping": {
"version": "2026-01-11",
"spec": "https://ucp.dev/spec/services/shopping",
"rest": {
"schema": "https://ucp.dev/spec/services/shopping/rest.openapi.json",
"endpoint": "https://shop.example.com/api/ucp"
}
}
},
"capabilities": [
{
"name": "dev.ucp.shopping.checkout",
"version": "2026-01-11",
"spec": "https://ucp.dev/spec/capabilities/checkout",
"schema":
Ask: "Write this to public/.well-known/ucp for static serving, or keep as dynamic route?"
If static:
public/.well-known/ucp (no extension, JSON content)User runs /ucp test
Generate unit tests for UCP handlers.
Look for:
jest.config.js / jest.config.ts → Jestvitest.config.js / vitest.config.ts → Vitestpackage.json test script hintsFor each handler, generate corresponding test file.
/**
* UCP Checkout Handler Tests
* Generated by /ucp test
*/
import { describe, it, expect, beforeEach } from 'vitest'; // or jest
import {
createCheckout,
getCheckout,
updateCheckout,
completeCheckout,
} from '../checkout';
describe('UCP Checkout Handler', () => {
const validRequest = {
line_items: [
{
id: 'item_1',
name: 'Test Product',
quantity: 1,
unit_price: 1000,
total_price: 1000,
currency: 'USD',
},
],
currency: 'USD',
};
describe('createCheckout', () => {
it('creates a checkout with valid request', async () => {
const checkout = await createCheckout(validRequest, {
capabilities: ['dev.ucp.shopping.checkout'],
});
expect(checkout.id).toBeDefined();
expect(checkout.status).toBe('incomplete');
expect(checkout.currency).();
(checkout.).();
(checkout..).();
(checkout..).();
});
(, () => {
checkout = (validRequest, {
: [],
});
(checkout..).();
(checkout..).(checkout..);
});
(, () => {
checkout = (validRequest, {
: [],
});
(checkout.).();
expiresAt = (checkout.);
(expiresAt.()).(.());
});
(, () => {
checkout = (validRequest, {
: [],
});
(checkout..).(checkout.);
(checkout..).();
(checkout..).();
});
});
(, {
(, () => {
created = (validRequest, {
: [],
});
retrieved = (created.);
(retrieved).(created);
});
(, () => {
retrieved = ();
(retrieved).();
});
});
(, {
(, () => {
created = (validRequest, {
: [],
});
updated = (
created.,
{
: [
{ ...validRequest.[], : , : },
],
},
[]
);
(updated?..).();
});
(, () => {
created = (validRequest, {
: [],
});
updated = (
created.,
{ : { : } },
[]
);
(updated?.?.).();
});
(, () => {
created = (validRequest, {
: [],
});
updated = (
created.,
{ : { : } },
[]
);
(updated?.).();
});
});
(, {
(, () => {
checkout = (validRequest, {
: [],
});
(checkout.).();
updated = (
checkout.,
{ : { : } },
[]
);
(updated?.).();
});
});
});
Generated test files:
CREATE lib/ucp/handlers/__tests__/checkout.test.ts
CREATE lib/ucp/handlers/__tests__/fulfillment.test.ts
CREATE lib/ucp/__tests__/negotiation.test.ts
CREATE lib/ucp/__tests__/profile.test.ts
CREATE app/api/ucp/__tests__/checkout.route.test.ts
Run tests with: npm test (or bun test)
User runs /ucp docs
Generate internal documentation for the UCP integration.
Create docs/ucp-integration.md:
# UCP Integration Documentation
## Overview
This codebase implements the Universal Commerce Protocol (UCP) version {version}.
**Role:** {role}
**Domain:** {domain}
**Transports:** {transports}
## Capabilities
### Core
- `dev.ucp.shopping.checkout` - Checkout session management
### Extensions
{list extensions with descriptions}
## API Endpoints
### Discovery
- `GET /.well-known/ucp` - UCP discovery profile
### Checkout (REST)
- `POST /api/ucp/checkout` - Create checkout session
- `GET /api/ucp/checkout/:id` - Get checkout session
- `PATCH /api/ucp/checkout/:id` - Update checkout session
- `POST /api/ucp/checkout/:id` (action=complete) - Complete checkout
## Checkout Status Lifecycle
incomplete → requires_escalation → ready_for_complete → complete_in_progress → completed ↘ canceled
## Payment Handlers
{list configured handlers with integration notes}
## Capability Negotiation
The platform sends their profile URL via `UCP-Agent` header:
UCP-Agent: profile="https://platform.example.com/.well-known/ucp"
The business fetches the platform profile, computes the capability intersection,
and includes the negotiated capabilities in every response.
## Configuration
Configuration is stored in `ucp.config.json` at the project root.
## Files
{list generated files with descriptions}
## Testing
Run unit tests:
```bash
npm test
Validate implementation against UCP schemas:
# Using the skill
/ucp validate
#### Step 3: Output
Generated documentation: CREATE docs/ucp-integration.md
Documentation includes:
---
## Error Handling
### Interactive Error Resolution
When encountering ambiguous situations, always ask the user:
1. **Missing config:** "Config file not found. Run /ucp init first, or create manually?"
2. **Spec fetch failed:** "Could not clone UCP spec. Check network/auth. Retry, use local path, or abort?"
3. **Conflicting files:** "File {path} already exists. Overwrite, merge, skip, or abort?"
4. **Unknown role:** "Role '{role}' not recognized. Did you mean: business, platform, payment_provider, or host_embedded?"
5. **Validation failure:** "Schema validation failed for {file}. Show details, attempt fix, or skip?"
### Error Codes
| Code | Meaning | Resolution |
|------|---------|------------|
| `CONFIG_NOT_FOUND` | ucp.config.json missing | Run /ucp init |
| `SPEC_NOT_FOUND` | Spec repo not available | Check network, clone manually |
| `INVALID_ROLE` | Unknown role in config | Fix config |
| `SCHEMA_INVALID` | Response doesn't match schema | Review generated code |
| `EDGE_RUNTIME_DETECTED` | Edge runtime used | Change to nodejs/bun |
---
## Next.js Conventions
### File Structure
project/ ├── app/ │ ├── .well-known/ │ │ └── ucp/ │ │ └── route.ts # Discovery profile │ └── api/ │ └── ucp/ │ ├── checkout/ │ │ ├── route.ts # POST create │ │ └── [id]/ │ │ └── route.ts # GET, PATCH, POST complete │ ├── mcp/ │ │ └── route.ts # MCP transport (if enabled) │ └── a2a/ │ └── route.ts # A2A transport (if enabled) ├── lib/ │ └── ucp/ │ ├── types/ │ │ ├── checkout.ts │ │ └── index.ts │ ├── schemas/ │ │ └── checkout.ts │ ├── handlers/ │ │ ├── checkout.ts │ │ ├── fulfillment.ts │ │ ├── discount.ts │ │ └── payment.ts │ ├── transports/ │ │ └── mcp.ts │ ├── profile.ts │ ├── negotiation.ts │ └── response.ts ├── docs/ │ └── ucp-integration.md ├── ucp.config.json └── .ucp-spec/ # Cloned spec (gitignored)
### Runtime Declaration
Every route file must include:
```typescript
export const runtime = 'nodejs'; // Edge runtime is not supported
Or for Bun:
export const runtime = 'nodejs'; // Bun-compatible Node.js runtime
route.ts) not API Routes (pages/api)NextRequest and NextResponse from next/serverrequest.json() for body parsingrequest.headers.get() for header access| Files created by scaffold (for tracking) |
answers | object | Raw answers to qualifying questions |