The Problem

Commerce platforms operate in a fragmented landscape where AI agents, businesses, Payment Service Providers, and Credential Providers must each build custom integrations to communicate. There is no standardized common language for declaring capabilities, facilitating checkout, or exchanging shopping data—forcing every new integration to be engineered from scratch.

What This Does

The Universal Commerce Protocol (UCP) provides an open standard for interoperability across commerce entities. It defines composable Capabilities (Checkout, Identity Linking, Order) and Extensions (Discounts, Fulfillment) that businesses implement to enable autonomous platform discovery and secure transactions. The repository contains 216 files organized into docs/ (101 documentation files), source/ (79 source files), and scripts/ (3 utility files). Core logic resides in main.py (1,008 lines, 23 functions) and hooks.py (11 functions), with schema definitions stored as JSON files under source/schemas/. The protocol is transport-agnostic, supporting REST, MCP, and A2A transports.

How It Is Wired

Execution begins at entry points in main.py: method_fields (line 1026), auto_generate_schema_reference (line 873), extension_fields (line 985), extension_schema_fields (line 857), and schema_fields (line 790). These reach 13–14 downstream functions each. The internal call graph contains 48 resolved edges between self-contained modules; _render_table_from_schema is called from 7 places, and get_error_context from 6. Traced paths show method_fields flowing to _render_table_from_schema which accesses the filesystem via UCP_SCHEMA_PATH.open; schema_fields invoking _resolve_schema which runs a subprocess via subprocess.run; and header_fields reading files through full_path.open. hooks.py defines _process_refs, _rewrite_version_urls, _set_schema_version, and rewrite_nav, handling page-level transformations during the build pipeline. scripts/check_links.py (6 functions, 1 class) validates links across the site, and scripts/super_linter_local.py (2 functions) runs linting locally.

How To Use It

Setup:

git clone https://github.com/moses-y/ucp
cd ucp
npm install  # or pip install -e . for Python dependencies

Configuration: Environment variables are read via define_env in main.py. The pyproject.toml and package.json manage Python and npm dependencies respectively. No Dockerfile is present; builds are local via scripts/build_local.sh.

Running it: The primary entry point is main.py. To generate or validate the schema, invoke method_fields or auto_generate_schema_reference from the command line or import the function programmatically. The schema files under source/schemas/shopping/ and source/schemas/common/ define the data structures for carts, checkouts, payments, and more.

Real-World Use

An AI agent discovers a merchant's UCP profile by reading docs/index.md and the capability JSON files in source/schemas/. It identifies supported capabilities (e.g., Checkout, Identity Linking) and initiates a checkout session by calling the merchant's REST endpoint or MCP transport. The agent receives a standardized schema, validates the cart and payment instruments against source/schemas/shopping/payment.json, and completes the purchase via the declared flow—with or without human intervention. Extensions such as discounts or fulfillment are optional; the merchant declares support in its profile, and the agent adapts accordingly.

Code Health & Issues

Static analysis identified 5 medium-severity findings across 4 kinds:

  • Duplicated code blocks in hooks.py and main.py — 5 repeated 6-line blocks share identical logic; extract shared helpers to DRY the code.
  • Broad exception handling in scripts/check_links.py — except clauses swallow errors indiscriminately; catch specific exceptions and re-raise or log the rest.
  • Oversized file — main.py at 1,008 code lines is hard to hold in one head; a change ripples widely through 23 functions.
  • High branching density — hooks.py and scripts/check_links.py each have 91 branch points over ~310 lines; decompose decision-heavy logic, consider table or strategy dispatch.

Code health audit (5 findings):

  • [HIGH] Pin third-party GitHub Actions to commit SHAs — .github/workflows uses astral-sh/setup-uv@v7, tj-actions/changed-files@v46, super-linter/super-linter/slim@v8.5.0, streetsidesoftware/cspell-action@v7; a tag can be moved, so actions run with your token at whatever version the owner last pushed.
  • [HIGH] Pull requests push to gh-pages — .github/workflows/docs.yml uses git push origin gh-pages; automated commits land on the deploying branch with no test having run against the result.
  • [MEDIUM] No Dependabot or Renovate configured — 2 manifest files (package.json, pyproject.toml) have no update bot; advisories sit unpatched.
  • [MEDIUM] No dependency vulnerability scan in CI — no dependency-review-action on pull_request or osv-scanner on push/schedule.
  • [LOW] Workflow jobs declare no timeout-minutes — 4 jobs in .github/workflows have no timeout, risking overlap on a two-hourly schedule.

The Bottom Line

UCP is a well-structured open protocol for commerce interoperability with solid documentation (103 doc files), 33 test files, and a clear capability model. The codebase is functional but suffers from an oversized main.py, duplicated logic in hooks.py, and risky GitHub Actions pinning. It is suitable for teams building agentic commerce systems who need a standardized schema and don't mind pinning Action versions and setting up Dependabot. Teams needing a lightweight, immediately runnable integration should pin SHAs, add a dependency scan gate, and consider splitting main.py into cohesive units.