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.

UCP Skill — Universal Commerce Protocol Implementation Core Principles 1. Edge runtime is NOT USED — Only Node.js (default) or Bun (opt in) runtimes 2. Interactive error handling — When ambiguous, ask the user how to proceed 3. Config driven — All decisions persist in ucp.config.json 4. Spec grounded — All implementations reference the canonical UCP specification 5. Next.js conventions — Follow App Router patterns for code organization 6. Deep analysis — Use AST parsing and data flow tracing for gap detection Spec Repository Handling Location Priority Check in this order: 1. ./ucp/ — User's local copy (use as is) 2. ./.ucp spec/ — Previously cloned spec (update it) 3. Neither exists — Clone fresh Clone Procedure When cloning is needed: If HTTPS fails, try SSH: Update Procedure When ./.ucp spec/ exists: Gitignore Management After cloning, ensure .ucp spec/ is in .gitignore : Read .gitignore if it exists Check if .ucp spec/ or .ucp spec is already listed If not, append .ucp spec/ on a new line Spec File Locations (read on demand) Configuration File Location ./ucp.config.json at project root Schema Field Descriptions 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[] Files created by scaffold (for tracking) answers object Raw answers to qualifying questions Sub command: (no argument) Trigger User runs /ucp with no sub command Behavior Display help listing all available sub commands: Sub command: init Trigger User runs /ucp init Purpose Bootstrap UCP in a project: clone spec, create config, ask essential questions. Procedure Step 1: Check/Clone Spec Repository 1. Check if ./ucp/ exists If yes: "Found local UCP spec at ./ucp/" 2. If not, check if ./.ucp spec/ exists If yes: Run git pull to update If no: Clone the repo (see Spec Repository Handling) 3. After cloning, add .ucp spec/ to .gitignore Step 2: Check for Existing Config 1. Check if ./ucp.config.json exists 2. If yes, ask: "Config file exists. Overwrite, merge, or abort?" Overwrite: Delete and create fresh Merge: Keep existing values as defaults Abort: Stop init Step 3: Ask Essential Questions (4 questions) Q1: What role(s) are you implementing? Business (merchant of record) Platform (consumer app or agent) Payment credential provider Host embedding checkout Multiple (specify) 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? Node.js (recommended, stable) Bun (opt in, experimental) 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? The domain that will host /.well known/ucp Example: shop.example.com Q4: Which transports do you need at launch? REST (recommended baseline) MCP (Model Context Protocol) A2A (Agent to Agent) Embedded (iframe checkout) Step 4: Create Config File Create ./ucp.config.json with: Answers from essential questions Sensible defaults for other fields ucp version set to latest from spec Step 5: Output Ready Message Sub command: consult Trigger User runs /ucp consult Purpose Walk through all 12 qualifying questions, update config, produce implementation roadmap. Prerequisites Config file must exist (run /ucp init first) Spec must be available Procedure Step 1: Load Existing Config Read ./ucp.config.json and use existing answers as defaults. Step 2: Walk Through 12 Qualifying Questions 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? Map to roles in config If both/multiple, warn about unusual scenario Q2: Which UCP version and which capabilities/extensions are in scope? Read available versions from spec Present capability options: Core: dev.ucp.shopping.checkout (required) Extensions: dev.ucp.shopping.fulfillment dev.ucp.shopping.discount dev.ucp.shopping.buyer consent dev.ucp.shopping.ap2 mandate dev.ucp.shopping.order dev.ucp.common.identity linking Q3: Which payment handlers do we need? Wallets (Apple Pay, Google Pay) PSP tokenization (Stripe, Adyen, etc.) Custom handler None yet (decide later) Q4: Do we need AP2 mandates and signing key infrastructure? Yes → set features.ap2 mandates: true No → set features.ap2 mandates: false If yes, explain: "You'll need to provide JWS signing keys (ES256 recommended)" Q5: Do we need fulfillment options and multi group/multi destination support? No fulfillment needed Single destination only Multi destination support → set features.multi destination fulfillment: true Q6: Do we need discounts, buyer consent capture, or identity linking? Discounts → add dev.ucp.shopping.discount to extensions Buyer consent → add dev.ucp.shopping.buyer consent to extensions Identity linking → add dev.ucp.common.identity linking , set features.identity linking: true Q7: What are the existing checkout and order APIs we should map to UCP? Ask for existing endpoint paths Store in existing apis object Examples: /api/checkout , /api/cart , /api/orders Q8: What are the required policy URLs? Privacy policy URL Terms of service URL Refund policy URL Shipping policy URL Store in policy urls object Q9: What authentication model is required for checkout endpoints? None (anonymous checkout) API key OAuth 2.0 Session based Store in answers.authentication model Q10: Who will receive order webhooks and what event cadence is required? Webhook URL for order events Event types needed: order.created , order.updated , order.fulfilled , order.canceled Store in answers.webhook config Q11: Do we need to support MCP, A2A, or embedded checkout at launch? Confirm/update transports array Set transport priority order Q12: What is the business domain that will host /.well known/ucp? Confirm/update domain field Step 3: Update Config Write all answers to ./ucp.config.json Step 4: Generate Implementation Roadmap Based on answers, produce a roadmap: Sub command: plan Trigger User runs /ucp plan Purpose Generate detailed implementation plan with specific files and order of operations. Prerequisites Config file must exist with completed consultation Spec must be available Procedure Step 1: Load Config and Spec Read ./ucp.config.json Read relevant spec files based on capabilities/transports Step 2: Analyze Existing Codebase Structure Detect Next.js version (App Router vs Pages Router) Find existing API routes Find existing lib/utils structure Find existing types/schemas Identify package manager (npm, yarn, pnpm, bun) Step 3: Generate File Plan For each capability/transport, list files to create/modify. Example output: Step 4: Save Plan to Config Store the plan in answers.implementation plan for scaffold reference. Sub command: gaps Trigger User runs /ucp gaps Purpose Deep analysis of existing codebase against UCP requirements. Uses AST parsing and data flow tracing. Prerequisites Config file should exist (for role/capability context) Spec must be available Procedure Step 1: Load Context Read config for declared capabilities Read relevant spec files Step 2: Discover Existing Code Scan for: API routes ( app/api/ , pages/api/ ) Checkout related files (search for "checkout", "cart", "order") Payment handling code Webhook implementations Step 3: Deep Analysis (AST based) For each relevant file: Parse AST Trace data flow for checkout objects Identify existing patterns 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 Step 4: Generate Gap Report Sub command: scaffold Trigger User runs /ucp scaffold Purpose Generate full working UCP implementation based on config and plan. Prerequisites Config file must exist Plan should exist (run /ucp plan first, or scaffold will generate one) Procedure Step 1: Confirm Scaffold Depth 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 Step 2: Check Dependencies Identify required packages based on config: zod — Always needed jose — If AP2 mandates or webhook signing enabled uuid — For session ID generation Ask before installing: "The following packages are required: zod, jose, uuid" "Install now? (npm install / bun add)" If yes, run appropriate install command. Step 3: Generate Code Generate files according to plan. For each file: 1. Create parent directories if needed 2. Write file content 3. Track in config.generated files Code Generation Templates lib/ucp/types/checkout.ts lib/ucp/schemas/checkout.ts app/.well known/ucp/route.ts lib/ucp/profile.ts app/api/ucp/checkout/route.ts lib/ucp/handlers/checkout.ts lib/ucp/negotiation.ts lib/ucp/response.ts MCP Transport Code Templates (using mcp handler) When MCP transport is enabled in config, generate these additional files. Dependencies for MCP Transport IMPORTANT: Use @modelcontextprotocol/sdk@1.25.2 or later — earlier versions have security vulnerabilities. app/api/mcp/[transport]/route.ts lib/ucp/transports/mcp tools.ts Vercel Deployment Deployment Configuration vercel.json Environment Variables 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 next.config.js (MCP optimized) MCP Client Configuration For Claude Desktop / Cursor / Windsurf Option 1: Direct HTTP (if client supports streamable HTTP) Add to MCP client config: