Portage¶

Ruby gems that expose a commerce backend to AI shopping agents over MCP (Model Context Protocol) and UCP (Universal Commerce Protocol) at once. Open-source, for any Ruby app on any e-commerce stack, agnostic, versatile and fully customizable for any business logic.

"Portage": a conduit for cargo overland between waterways a ship can't sail directly between.

Status

0.10.0. APIs may still shift before 1.0.

Start here: Quickstart.

Which doc do I want?¶

Shoppers & agent builders (automating purchases): CLI usage tutorial · Walkthrough · shop-via-ucp skill · Agent profile · Tool-gating troubleshooting

Merchants (serving your own UCP endpoint): Serving /.well-known/ucp · Walkthrough § serving the manifest · Security hooks · serve-via-ucp skill

Adapter authors & contributors: Architecture · Writing adapters · Capability coverage · Spec conformance · Development · Contributing

The gems¶

Thirteen gems, mirroring how Faraday/Devise split core-vs-adapter:

Gem	Version	Role
`portage-ucp`	0.10.0	Protocol-only core: `Adapter` contract, capability registry, manifest builder, MCP server wrapper.
`portage-ucp-client`	0.6.3	Client SDK — connect to somebody else's manifest, or drive your own `Adapter`, as the shopper's agent. Loopback/stdio/HTTP behind one interface.
`portage-ucp-webmcp`	0.1.1	WebMCP transport onto the same `Adapter` contract — inbound (`document.modelContext`) and outbound (drives a page's WebMCP tools via a browser driver).
`portage-ucp-decision`	0.1.1	System One decision layer — offer ranking, escalation policy, a confidence gate (Jev/Laya), typed `PolicyGuard` wrapper.
`portage-ucp-journal`	0.1.1	Buyer-side purchase journal + the injectable `Store` abstraction it's built on.
`portage-cli`	0.7.4	Ships the `portage` command — `buy`, `find`, `compare`, `history`, `payment`, `policy`, `doctor`, `generate`.
`portage-ucp-shopify`	0.5.1	Shopify — Admin + Storefront GraphQL APIs.
`portage-ucp-wix`	0.1.4	Wix — Stores Catalog and eCommerce REST APIs.
`portage-ucp-woocommerce`	0.2.1	WooCommerce — Admin REST API and Store API.
`portage-ucp-bigcommerce`	0.1.4	BigCommerce — v3 Catalog/Carts/Checkouts and v2 Orders APIs.
`portage-ucp-magento`	0.1.4	Magento/Adobe Commerce — REST v1 (admin-token catalog/order, guest-cart cart/checkout).
`portage-ucp-etsy`	0.1.4	Etsy — real catalog/order via Open API v3; checkout is redirect-link only (Etsy's public API has no cart/checkout endpoint).
`portage-ucp-instagram`	0.1.5	Instagram/Facebook Shops — real catalog via Meta's Graph API Commerce Catalog; checkout is redirect-link only. `get_order` is deprecated (Meta removes Order Management endpoints 2026-10-27; after that, catalog search/product + checkout handoff only).

A backend on some other stack writes its own thin Adapter subclass against portage-ucp directly. Every adapter gem ships the same exe/ executable, examples/portage_ucp.rb starting point, and PORTAGE_UCP_CONFIG config hook — see Library usage (Etsy and Instagram gain exe/ + examples/ once feat/etsy-exe and harden/instagram merge — see the feature matrix for current status). Etsy and Instagram/Facebook Shops have no real cart/checkout API to back, so those two only implement catalog/order for real — full per-capability breakdown in Capability coverage (and the feature matrix for a row-per-adapter view). Already on Shopify? Its native Universal Commerce Agent app covers checkout+order with no code — this gem is for the cart/catalog capabilities it doesn't advertise, a signed manifest, and every other backend (Serving /.well-known/ucp).

Requirements¶

Ruby >= 3.2, and the mcp gem ~> 0.24 (pulled in by portage-ucp). The Homebrew formula brings its own Ruby, so a brew install of the CLI needs neither. Each adapter gem needs its backend's own credentials, read from env by its executable — see that gem's own docs page, or Adapter requirements for the full table.

Contributing¶

Bug reports and pull requests welcome at tomtom87/Portage. Since this is pre-1.0 and still spec-tracking, open an issue to discuss any change bigger than a bugfix before sending a PR. Contributing has the full workflow.