Skip to content

Skill: serve-via-ucp

The merchant-side counterpart to shop-via-ucp — sets up a merchant's own backend to serve UCP/MCP commerce to shopping agents.

Serving commerce via UCP/MCP

You are setting up a merchant's own backend to be a UCP/MCP commerce server — the seller side, not the shopper side (shop-via-ucp is the counterpart for acting as a buyer's agent). The scripts beside this file do the mechanical parts; you drive the sequence and make the judgment calls a script can't (which adapter gem fits, what the authenticator should actually check, whether the manifest looks right).

Guardrails — apply these every time, no exceptions

  1. Never write a permissive authenticator or rate limiter. The unconfigured defaults (UnconfiguredAuthenticator, NullRateLimiter) reject-by-default / never-limit on purpose (see portage-ucp's README, "Security hooks"). If you don't know what the real auth check should be, leave the TODO in place and say so — don't write ->(context) { true } just to make doctor.sh stop complaining.
  2. Never commit credentials. Every secret (webhook HMAC secret, PSP keys, platform admin tokens) is ENV.fetch("...") in the initializer, never a literal string — including in examples you write for the user. If a .env file is involved, confirm it's gitignored before touching it.
  3. Always run doctor.sh before declaring the setup done. A manifest that responds over HTTP doesn't mean the setup is safe — portage doctor (see portage-cli) catches the specific footguns nothing else does: unconfigured auth/rate-limiting still in place, missing signing keys, missing payment handlers, a capability half-implemented (some actions overridden, others still raising NotImplementedError).

Sequence

  1. Detect the stack — detect_stack.sh (run from the app's root). Reports framework (Rails vs. plain Rack), which portage-ucp* gems are already bundled, and whether an Adapter subclass already exists. Read-only.
  2. Pick or write an Adapter. If detect_stack.sh found none and no bundled platform gem fits (Shopify/Wix/WooCommerce/BigCommerce/Magento/Etsy/Instagram — see portage-ucp's README capability matrix for what each actually implements), scaffold one with portage generate adapter Foo (see portage-cli) rather than hand-rolling the boilerplate.
  3. Install — install.sh [adapter-gem-name]. Adds portage-ucp (+ the adapter gem, if named) to the Gemfile, then either runs rails generate portage:ucp:install (Rails apps) or copies the same initializer template to config/initializers/portage_ucp.rb directly (plain Rack). Idempotent — safe to re-run.
  4. Fill in the initializer. Every TODO in config/initializers/portage_ucp.rb (authenticator, rate_limiter, business, signing_keys, ...) needs a real value or a deliberate "leave unset" decision — this is the step guardrail 1 is about. Mount Rack::ManifestEndpoint and Rack::WebhookEndpoint per the routes the generator added (or portage-ucp's README, "Usage", if routing by hand).
  5. Run doctor.sh [require-file] [adapter-class-name] (default require path: config/environment, i.e. Rails boot). Fix every finding it reports — this is guardrail 3. Don't proceed to verify.sh with known findings unaddressed unless the user explicitly accepts the risk.
  6. Boot the app (however this app normally starts — this skill doesn't guess that part), then verify.sh [base-url] (default http://localhost:3000) — curls /.well-known/ucp and checks it nests version/business/services/ capabilities under a top-level ucp object, with at least one advertised capability.
  7. Run the conformance kit — conformance.sh [spec-path]. Fails loudly with a worked example if no spec includes "a portage adapter" yet (see portage-ucp-etsy's conformance spec in the Portage repo for a real one to copy the shape of); otherwise runs it. This is the same shared-examples kit rake conformance gates the bundled adapters on — see portage-ucp's lib/portage/ucp/rspec.rb.

What "done" looks like

doctor.sh reports no findings (or the user explicitly accepted the remaining ones), verify.sh confirms a well-formed live manifest, and conformance.sh passes against the merchant's own Adapter. Report which of these three actually ran and passed — don't claim the integration is safe on the strength of "the server responds."