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¶
- 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 makedoctor.shstop complaining. - 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.envfile is involved, confirm it's gitignored before touching it. - Always run
doctor.shbefore declaring the setup done. A manifest that responds over HTTP doesn't mean the setup is safe —portage doctor(seeportage-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 raisingNotImplementedError).
Sequence¶
- Detect the stack —
detect_stack.sh(run from the app's root). Reports framework (Rails vs. plain Rack), whichportage-ucp*gems are already bundled, and whether anAdaptersubclass already exists. Read-only. - Pick or write an Adapter. If
detect_stack.shfound 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 withportage generate adapter Foo(see portage-cli) rather than hand-rolling the boilerplate. - Install —
install.sh [adapter-gem-name]. Addsportage-ucp(+ the adapter gem, if named) to the Gemfile, then either runsrails generate portage:ucp:install(Rails apps) or copies the same initializer template toconfig/initializers/portage_ucp.rbdirectly (plain Rack). Idempotent — safe to re-run. - 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. MountRack::ManifestEndpointandRack::WebhookEndpointper the routes the generator added (or portage-ucp's README, "Usage", if routing by hand). - 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. - 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/ucpand checks it nestsversion/business/services/capabilitiesunder a top-levelucpobject, with at least one advertised capability. - 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 kitrake conformancegates the bundled adapters on — see portage-ucp'slib/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."