portage-ucp 0.15.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f99f8f55e4bbfeb276c93c8f1c7e63d36b3f30661702303d1295103e2ea4993c
-  data.tar.gz: 1c21857f2b52165c30994ba40bab0d8522520bfe8d7bb50b7459898630b71647
+  metadata.gz: 6bfa07946dff1ff76a95ade848a4721727da69c8ecacd4d37c4a59bf449179e4
+  data.tar.gz: c23b673f2cedb83ffc2326804b96975b5d57c7737cd625bbf8465b89d02e4e70
 SHA512:
-  metadata.gz: c406f740bebf4a83c4eb9184d62e6abc693478ba97b0ab51cd4549bcc8996addd658b84f437f488ffffafa03782be6b2ea464b05057545091380b86b02066f7a
-  data.tar.gz: 6acd7187aad41ebae15d667ebc150e6896e1f0f72b2f86211d173bd77a25a26d1cc0119d7a9375329c688d13423a655244c43b04537a30aa9a3c851c12c4efca
+  metadata.gz: 3e53a572a3cddd068c4c653314c2348cbd3e75d014d563dc1bf6312eae84af8606364c747c1d58bd0f7accd82bb1a40199098fba4f40c03633ad8d42f4a1f443
+  data.tar.gz: aeda7078b20110826e45b900bcb634f8321f5b0df4edb7bb34374cabdd8da05158605757f790b917febb8f60c1b70f6fdb9e1e1d524de51b559bd63e45d6452e

data/CHANGELOG.md

@@ -6,6 +6,14 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-10-22
+
+- **Changed: requires `mcp` `~> 1.8`** (was `~> 0.24`), which serves MCP 2026-07-28 through `server/discover` and keeps `initialize` for 2025-11-25 and earlier. Minor bump because the `mcp` requirement moved from 0.x to 1.x; no API change and no changes under `lib/`.
+- **Added: `app.portage-ucp.order_history` extension capability with a `list_orders` MCP tool.** `Adapter#list_orders(limit:, query: nil)` returns a new `OrderList` value object (`{"orders" => [...]}` on the wire, since MCP `structuredContent` must be an object): placed orders newest first, optionally filtered by free text. Not part of the UCP spec, which reads orders only by id. `ReferenceAdapter` implements it (matching order id and line item titles). `list_orders` is read-only but `Mcp::Server` runs the authenticator and rate limiter for it (`Mcp::Server::AUTH_REQUIRED_READS`), because an open list would expose every customer's orders; an unconfigured server rejects it like a mutating tool. `ToolMetadata` documents it, points `get_order` at it, and the server instructions mention it. WebMCP's default capability filter (`dev.ucp.shopping.*` only) leaves it out of page-registered tools.
+
+## [0.16.0] - 2026-10-21
+
+- **Changed: MCP tool descriptions rewritten against the TDQS rubric** (tdqs.dev, the score Glama shows). Each tool's description now names its siblings for when and when not to use it, states the auth and rate-limit behavior of state-changing tools, and says what it returns, since tools have no output schema. Parameter descriptions say where IDs come from. `Mcp::Server.build` now sends server `instructions` (`ToolMetadata::INSTRUCTIONS`, overridable with `instructions:`) that walk the catalog → cart → checkout → order flow. `tools/list` text only; tool names, schemas and annotations are unchanged.
 - **Added: `dev.ucp.shopping.permalink` capability** (UCP 2026-08-25). An adapter that overrides `Adapter#permalink_endpoint` (default `nil`) to return its https browser endpoint is advertised with `config.endpoint`. `Capability` takes an optional `config:` callable for the manifest entry's `config`. No MCP tool: the permalink is a browser redirect the host serves (design-log §61).
 - **Added: policy disclosure warnings on `Cart` and `Checkout`** (UCP 2026-08-25). Each entry of `policies:` now also yields a `messages[]` warning with `code` equal to the policy `type`, `presentation: "disclosure"`, `content` from the description and `url`/`path` when the policy has them. Derived in `to_wire_h`, so every adapter gets it and nothing is stored. Orders are unchanged (design-log §62).
 - **Added: optional `messages:` on `Cart` and `Checkout`.** An array of wire-shaped message hashes (default `[]`) an adapter can set itself. `to_wire_h` emits them before the derived policy warnings and drops a derived warning when the adapter already warned with the same `code`. `messages` is omitted from the wire when the combined list is empty (design-log §63).

data/lib/portage/ucp/adapter.rb

@@ -116,6 +116,17 @@ module Portage
       # @return [Portage::Ucp::ReorderResult, nil] nil if the order isn't found.
       def reorder(order_id:, idempotency_key:) = not_implemented
 
+      # --- Order History (app.portage-ucp.order_history — Portage extension,
+      # not part of the UCP spec: dev.ucp.shopping.order has no list/search
+      # action as of the 2026-08-25 spec) ---
+      # Newest first, at most `limit`. `query` is free text an adapter matches
+      # however its platform searches (order number, product title, ...);
+      # nil lists everything. An adapter may return lighter Orders than
+      # #get_order (e.g. no fulfillment detail) — callers re-read one with
+      # #get_order for the full record.
+      # @return [Portage::Ucp::OrderList]
+      def list_orders(limit:, query: nil) = not_implemented
+
       # --- Discount (dev.ucp.shopping.discount) ---
       # Extends Cart/Checkout with the `discount_codes:` param above rather
       # than adding actions of its own — Capability::DISCOUNT advertises off

data/lib/portage/ucp/authenticator.rb

@@ -5,10 +5,11 @@ module Portage
     #   Portage::Ucp::AuthenticationError. There is deliberately no default that
     #   allows anonymous mutation — an unconfigured server rejects every
     #   mutating capability call (see UnconfiguredAuthenticator below).
-    #   Mcp::Server.build calls it only for mutating tools: those whose
-    #   adapter method takes `idempotency_key:`. Every other tool (catalog
-    #   search, product, cart, checkout and order lookups) never reaches it,
-    #   and Server.build has no option to change that.
+    #   Mcp::Server.build calls it for mutating tools (those whose adapter
+    #   method takes `idempotency_key:`) and for the reads listed in
+    #   Mcp::Server::AUTH_REQUIRED_READS (list_orders). Every other tool
+    #   (catalog search, product, cart, checkout and order lookups) never
+    #   reaches it, and Server.build has no option to change that.
     class Authenticator
       def call(_server_context)
         raise NotImplementedError, "#{self.class} must implement #call"

data/lib/portage/ucp/capabilities/identity_linking.rb

@@ -8,7 +8,7 @@ module Portage
       )
 
       ALL = [CATALOG, CART, CHECKOUT, ORDER, IDENTITY_LINKING, DISCOUNT, FULFILLMENT, PERMALINK,
-             REORDER, PAYMENT_ENROLLMENT, PAYMENT_METHOD, SAVED_ADDRESS, SHOPPER_DATA].freeze
+             REORDER, ORDER_HISTORY, PAYMENT_ENROLLMENT, PAYMENT_METHOD, SAVED_ADDRESS, SHOPPER_DATA].freeze
     end
   end
 end

data/lib/portage/ucp/capabilities/order_history.rb

@@ -0,0 +1,17 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # Portage-only extension, not part of the UCP spec: dev.ucp.shopping.order
+      # only reads an order by id, with no way to find one without it. Same
+      # Portage-owned namespacing as Capabilities::REORDER. Mcp::Server gates
+      # list_orders behind the authenticator even though it reads (see
+      # Mcp::Server::AUTH_REQUIRED_READS) — an open list would hand any
+      # caller every customer's orders.
+      ORDER_HISTORY = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.order_history",
+        version: "1",
+        actions: { "list_orders" => :list_orders }
+      )
+    end
+  end
+end

data/lib/portage/ucp/mcp/server.rb

@@ -13,6 +13,12 @@ module Portage
         # doesn't need one keyword argument per collaborator.
         Context = Struct.new(:dispatcher, :authenticator, :rate_limiter, :logger, keyword_init: true)
 
+        # Read-only actions that still go through authorize/rate_limit, which
+        # otherwise run only for actions taking an idempotency_key. Listing
+        # orders reads, but an open list would hand any caller every
+        # customer's orders.
+        AUTH_REQUIRED_READS = %w[list_orders].freeze
+
         # @param journal [#record_checkout, nil] forwarded straight to
         #   `Dispatcher.new` (see its own doc comment) — `nil` by default and
         #   never `require`d from core (§2), same as `Dispatcher` itself.
@@ -23,7 +29,8 @@ module Portage
         def self.build(adapter:, registry: Portage::Ucp.configuration.registry,
                        authenticator: Portage::Ucp.configuration.authenticator,
                        rate_limiter: Portage::Ucp.configuration.rate_limiter,
-                       logger: Portage::Ucp.configuration.logger, journal: nil, **server_opts)
+                       logger: Portage::Ucp.configuration.logger, journal: nil,
+                       instructions: ToolMetadata::INSTRUCTIONS, **server_opts)
           context = Context.new(
             dispatcher: Portage::Ucp::Dispatcher.new(adapter: adapter, registry: registry, logger: logger,
                                                      journal: journal),
@@ -36,7 +43,7 @@ module Portage
             end
           end
 
-          ::MCP::Server.new(name: "portage-ucp", tools: tools, **server_opts)
+          ::MCP::Server.new(name: "portage-ucp", tools: tools, instructions: instructions, **server_opts)
         end
 
         def self.build_tool(adapter:, capability:, action_name:, method_name:, context:)
@@ -44,7 +51,7 @@ module Portage
           required = keyword_params.select { |type, _| type == :keyreq }.map { |_, name| name.to_s }
           metadata = ToolMetadata::TOOLS[action_name]
           properties = keyword_params.to_h { |_, name| [name.to_s, property_schema(name.to_s, metadata)] }
-          mutating = keyword_params.any? { |_, name| name == :idempotency_key }
+          guarded = guarded?(keyword_params, action_name)
 
           ::MCP::Tool.define(
             name: action_name,
@@ -53,10 +60,16 @@ module Portage
             annotations: metadata && metadata[:annotations]
           ) do |**kwargs|
             Portage::Ucp::Mcp::Server.call_tool(context: context, capability: capability, action_name: action_name,
-                                                mutating: mutating, kwargs: kwargs)
+                                                guarded: guarded, kwargs: kwargs)
           end
         end
 
+        # Whether authorize/rate_limit run for this tool: every mutating action
+        # (it takes an idempotency_key) plus AUTH_REQUIRED_READS.
+        def self.guarded?(keyword_params, action_name)
+          keyword_params.any? { |_, name| name == :idempotency_key } || AUTH_REQUIRED_READS.include?(action_name)
+        end
+
         # @return [String] the documented description from ToolMetadata, or
         #   (for an undocumented/extension action) the old namespaced
         #   fallback, e.g. "dev.ucp.shopping.catalog#get_product".
@@ -76,15 +89,15 @@ module Portage
           schema
         end
 
-        def self.call_tool(context:, capability:, action_name:, mutating:, kwargs:)
+        def self.call_tool(context:, capability:, action_name:, guarded:, kwargs:)
           server_context = kwargs.delete(:server_context)
           correlation_id = correlation_id_for(server_context)
           agent_profile = agent_profile_for(server_context)
           log_tool_event(context.logger, "tool_call_received", correlation_id, agent_profile,
                          capability: capability.name, action: action_name)
 
-          rejection = authorize(context.authenticator, server_context, mutating: mutating) ||
-                      rate_limit(context.rate_limiter, server_context, capability.name, mutating: mutating)
+          rejection = authorize(context.authenticator, server_context, guarded: guarded) ||
+                      rate_limit(context.rate_limiter, server_context, capability.name, guarded: guarded)
           return rejection if rejection
 
           log_tool_event(context.logger, "tool_called", correlation_id, agent_profile,
@@ -133,8 +146,8 @@ module Portage
           meta && (meta["ucp-agent.profile"] || meta[:"ucp-agent.profile"])
         end
 
-        def self.authorize(authenticator, server_context, mutating:)
-          return unless mutating
+        def self.authorize(authenticator, server_context, guarded:)
+          return unless guarded
 
           authenticator.call(server_context)
           nil
@@ -145,8 +158,8 @@ module Portage
         # @param key [Object] whatever the consumer's RateLimiter derives an
         #   identity from — the gem hands over the raw MCP server_context
         #   rather than inventing its own per-session/per-key extraction (§9).
-        def self.rate_limit(rate_limiter, key, capability_name, mutating:)
-          return unless mutating
+        def self.rate_limit(rate_limiter, key, capability_name, guarded:)
+          return unless guarded
 
           rate_limiter.check!(key, capability_name)
           nil

data/lib/portage/ucp/mcp/tool_metadata.rb

@@ -6,9 +6,9 @@ module Portage
       # ::MCP::Tool. Kept separate from Capability (name/version/actions/
       # schema — the UCP wire contract) since this is MCP-presentation only:
       # what a calling agent reads before it decides whether and how to call
-      # a tool, not part of the UCP spec itself. Content mirrors the @param/
-      # @return docs already on Adapter's methods (adapter.rb) rather than
-      # inventing anything new.
+      # a tool, not part of the UCP spec itself. Written against the TDQS
+      # rubric (tdqs.dev): purpose, when/when-not with named siblings,
+      # behavior annotations can't carry, and return shape (no output schema).
       module ToolMetadata
         ID = "A stable identifier returned by an earlier call (e.g. get_cart, create_checkout) " \
              "— not something the caller makes up.".freeze
@@ -16,6 +16,21 @@ module Portage
                           "key returns the original result instead of repeating the effect.".freeze
         REPLACE_NOTE = "Replaces the existing contents rather than adding to them — resend the " \
                        "full desired list with an item adjusted, added, or omitted.".freeze
+        AUTH_NOTE = "Requires an authenticated session and may be rate-limited; a rejected call " \
+                    "returns an error result and changes nothing.".freeze
+        OPEN_NOTE = "Needs no authentication and is never rate-limited.".freeze
+
+        INSTRUCTIONS = "Shopping tools for one store, following the UCP lifecycle: catalog → cart → " \
+                       "checkout → order. Find products with search_catalog, read them with " \
+                       "get_product or lookup_catalog. Either build a cart (create_cart/update_cart) " \
+                       "or go straight to create_checkout; a checkout never charges until " \
+                       "complete_checkout, which must only follow the shopper's explicit approval of " \
+                       "the exact total shown by get_checkout. After purchase, find orders with " \
+                       "list_orders when you have no order ID, then use get_order, cancel_order, " \
+                       "request_return and refund_order. Catalog reads are open; list_orders and every " \
+                       "tool that changes state need an authenticated session, and a server run " \
+                       "without one is read-only. Payment is a single-use token, never a card number. " \
+                       "Prices and stock come live from the store and can change between calls.".freeze
 
         # JSON Schema `type` for parameter names whose shape is unambiguous
         # from the name alone and constant across every action it appears
@@ -30,155 +45,212 @@ module Portage
 
         TOOLS = {
           "search_catalog" => {
-            description: "Search the store's product catalog by free-text query, returning up to " \
-                         "`limit` matches with price and availability. Use this to discover products " \
-                         "when you don't yet have an ID; once you do, use get_product for one or " \
-                         "lookup_catalog for several — neither re-runs a search.",
-            params: { "query" => "Free-text search query.", "limit" => "Maximum number of results to return." },
+            description: "Search the store's product catalog by free-text query and return up to " \
+                         "`limit` matching products, each with ID, title, price range, variants and " \
+                         "availability. Use it to discover products when you have no product ID yet; " \
+                         "once you have IDs, use get_product (one) or lookup_catalog (several) " \
+                         "instead of searching again. #{OPEN_NOTE} An empty product list means no " \
+                         "match, not an error; results reflect the live store and can change between calls.",
+            params: {
+              "query" => "Free-text search, e.g. a product name, brand or category (\"burton snowboard\").",
+              "limit" => "Maximum number of products to return; 5–20 suits most searches."
+            },
             annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
           },
           "get_product" => {
-            description: "Fetch full details — price, availability, and whatever else the store's " \
-                         "catalog carries — for one product by ID. Returns not-found rather than " \
-                         "raising if the ID doesn't exist. Use search_catalog first if you don't " \
-                         "already have the ID; use lookup_catalog instead for several known IDs, to " \
-                         "avoid one call per product.",
+            description: "Fetch the full record for one product by ID: title, description, price " \
+                         "range, every variant with its own price and availability, URL and store " \
+                         "policies. Use it when you need variant-level detail for a single product " \
+                         "before adding it to a cart; use lookup_catalog for several IDs at once, and " \
+                         "search_catalog if you don't have an ID. #{OPEN_NOTE} An unknown ID returns " \
+                         "an empty result rather than an error.",
             params: { "product_id" => "Product ID, as returned by search_catalog or lookup_catalog." },
             annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
           },
           "lookup_catalog" => {
-            description: "Batch-fetch several products by ID in one call, same result shape as " \
-                         "search_catalog. Use when you already have a set of product IDs — e.g. " \
-                         "hydrating a cart or order — instead of calling get_product once per ID.",
+            description: "Fetch several products by ID in one call, returning the same product list " \
+                         "shape as search_catalog. Use it when you already hold a set of IDs — e.g. to " \
+                         "refresh prices for a cart or order — instead of calling get_product once per " \
+                         "ID; use search_catalog when you have a query rather than IDs. #{OPEN_NOTE} " \
+                         "IDs the store doesn't recognise are omitted from the result, not reported as errors.",
             params: { "product_ids" => "Product IDs to fetch, as returned by search_catalog, a cart, or an order." },
             annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
           },
           "create_cart" => {
-            description: "Start a new cart from a list of line items — the cart's complete starting " \
-                         "contents, not an item appended to an existing one. Use update_cart to change " \
-                         "a cart that already exists. Optional discount_codes applies coupons if the " \
-                         "store supports them.",
+            description: "Create a new cart holding the given line items and return it with its ID, " \
+                         "line items, currency and totals. Use it to collect items before checkout; " \
+                         "to change a cart that already exists use update_cart, and to buy straight " \
+                         "away without a cart use create_checkout. Nothing is reserved or charged. " \
+                         "#{AUTH_NOTE}",
             params: {
-              "line_items" => "Items to add, each {product_id:, quantity:}.",
+              "line_items" => "The cart's starting contents, each {product_id:, quantity:} with a " \
+                              "product or variant ID from the catalog tools.",
               "idempotency_key" => IDEMPOTENCY_KEY,
-              "discount_codes" => "Discount/coupon codes to apply, if the store supports them."
+              "discount_codes" => "Optional coupon codes to apply, if the store supports them."
             },
             annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
           },
           "get_cart" => {
-            description: "Fetch a cart's current contents and totals by ID.",
-            params: { "cart_id" => ID },
+            description: "Fetch an existing cart by ID and return its line items, currency, applied " \
+                         "discounts and current totals, recalculated against live store prices. Use " \
+                         "it to show the shopper what is in the cart; it is for carts only — use " \
+                         "get_checkout once a checkout exists and get_order after purchase. #{OPEN_NOTE}",
+            params: { "cart_id" => "Cart ID returned by create_cart. #{ID}" },
             annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
           },
           "update_cart" => {
-            description: "Replace a cart's contents. #{REPLACE_NOTE} Use this for every change to an " \
-                         "existing cart: adding an item, removing one, or changing a quantity.",
+            description: "Replace an existing cart's line items and discount codes, then return the " \
+                         "updated cart with new totals. #{REPLACE_NOTE} Use it for every change to a " \
+                         "cart — add, remove or change a quantity; use create_cart only for a new " \
+                         "cart and update_checkout once the shopper has moved to checkout. " \
+                         "Nothing is charged. #{AUTH_NOTE}",
             params: {
-              "cart_id" => ID,
-              "line_items" => "The cart's complete desired contents, each {product_id:, quantity:}. #{REPLACE_NOTE}",
+              "cart_id" => "Cart ID returned by create_cart. #{ID}",
+              "line_items" => "The cart's complete desired contents, each {product_id:, quantity:}.",
               "idempotency_key" => IDEMPOTENCY_KEY,
-              "discount_codes" => "Discount/coupon codes to apply, if the store supports them."
+              "discount_codes" => "Optional coupon codes, replacing those applied; leave out to keep the current ones."
             },
             annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
           },
           "cancel_cart" => {
-            description: "Cancel and discard a cart. Irreversible — use this to abandon a cart the " \
-                         "shopper no longer wants.",
-            params: { "cart_id" => ID, "idempotency_key" => IDEMPOTENCY_KEY },
+            description: "Abandon a cart and return it in its final state; don't reuse the cart ID " \
+                         "afterwards (some stores delete it, others such as Shopify let it expire). " \
+                         "Use it when the shopper gives up on the cart; to just " \
+                         "remove items use update_cart instead, and to abandon a checkout use " \
+                         "cancel_checkout. No money is involved. #{AUTH_NOTE}",
+            params: { "cart_id" => "Cart ID returned by create_cart. #{ID}", "idempotency_key" => IDEMPOTENCY_KEY },
             annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
           },
           "create_checkout" => {
-            description: "Start a checkout directly from line items, skipping a separate cart. " \
-                         "Optional discount_codes applies coupons; optional fulfillment carries the " \
-                         "shopper's desired shipping or pickup selection, if the store supports it. " \
-                         "Does not charge anything — call complete_checkout once the shopper approves " \
-                         "the total from get_checkout.",
+            description: "Open a checkout for the given line items and return it with its ID, status, " \
+                         "currency, itemised totals (including tax and shipping once known) and links. " \
+                         "Use it when the shopper is ready to buy; use create_cart instead if they " \
+                         "are still collecting items. Does not charge — complete_checkout does that, " \
+                         "only after the shopper approves the total. #{AUTH_NOTE}",
             params: {
-              "line_items" => "Items to buy, each {product_id:, quantity:}.",
+              "line_items" => "Items to buy, each {product_id:, quantity:} with a product or variant ID " \
+                              "from the catalog tools or a cart.",
               "idempotency_key" => IDEMPOTENCY_KEY,
-              "discount_codes" => "Discount/coupon codes to apply, if the store supports them.",
-              "fulfillment" => "Desired shipping/pickup method selection, if the store supports it."
+              "discount_codes" => "Optional coupon codes to apply, if the store supports them.",
+              "fulfillment" => "Optional shipping or pickup selection; leave it out to get the " \
+                               "store's available options back on the checkout."
             },
             annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
           },
           "get_checkout" => {
-            description: "Fetch a checkout's current contents, totals, and status by ID.",
-            params: { "checkout_id" => ID },
+            description: "Fetch an existing checkout by ID and return its status, line items, " \
+                         "currency and itemised totals. Use it to show the shopper the exact final " \
+                         "total to approve before complete_checkout, or to check whether a completed " \
+                         "checkout produced an order; use get_cart for carts and get_order for placed " \
+                         "orders. #{OPEN_NOTE}",
+            params: { "checkout_id" => "Checkout ID returned by create_checkout. #{ID}" },
             annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
           },
           "update_checkout" => {
-            description: "Replace a checkout's contents before payment. #{REPLACE_NOTE} Also accepts " \
-                         "updated discount_codes or fulfillment selection. Does not charge anything.",
+            description: "Replace an open checkout's line items, discount codes or fulfillment " \
+                         "selection and return it with recalculated totals. #{REPLACE_NOTE} Use it " \
+                         "before payment only; a completed checkout can't change — adjust the order " \
+                         "with cancel_order or request_return instead. Does not charge, and any total " \
+                         "the shopper approved earlier must be re-approved. #{AUTH_NOTE}",
             params: {
-              "checkout_id" => ID,
-              "line_items" => "The checkout's complete desired contents, each {product_id:, quantity:}. " \
-                              "#{REPLACE_NOTE}",
+              "checkout_id" => "Checkout ID returned by create_checkout. #{ID}",
+              "line_items" => "The checkout's complete desired contents, each {product_id:, quantity:}.",
               "idempotency_key" => IDEMPOTENCY_KEY,
-              "discount_codes" => "Discount/coupon codes to apply, if the store supports them.",
-              "fulfillment" => "Desired shipping/pickup method selection, if the store supports it."
+              "discount_codes" => "Optional coupon codes, replacing those applied; leave out to keep the current ones.",
+              "fulfillment" => "Optional shipping or pickup selection, from the options listed on the checkout."
             },
             annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
           },
           "complete_checkout" => {
-            description: "Charge the checkout and place the order — the one tool here that moves " \
-                         "money. Takes a single-use payment_token from a payment handler, never a raw " \
-                         "card number. Re-checks stock at this point, since catalog calls don't " \
-                         "guarantee live inventory, and fails rather than charging if a line item is " \
-                         "no longer available. Only call this after the shopper has explicitly " \
-                         "approved the exact total from get_checkout.",
+            description: "Charge the shopper and place the order for an open checkout — the only tool " \
+                         "here that spends money. Call it once, only after the shopper has explicitly " \
+                         "approved the exact total from get_checkout; never to preview a price. Before " \
+                         "charging it rejects anything resembling a raw card number, enforces the " \
+                         "operator's spending caps and allowlist, may require a human confirmation, " \
+                         "and re-checks stock, failing without a charge if anything is off. Returns " \
+                         "the checkout with status completed and the new order. #{AUTH_NOTE}",
             params: {
-              "checkout_id" => ID,
+              "checkout_id" => "Checkout ID returned by create_checkout. #{ID}",
               "payment_token" => "Single-use payment token from a payment handler — never a raw card number.",
-              "idempotency_key" => IDEMPOTENCY_KEY,
+              "idempotency_key" => "#{IDEMPOTENCY_KEY} Reuse it on retry so a timeout never charges twice.",
               "mandate" => "Optional AP2 payment mandate authorizing this charge, alongside or instead " \
-                           "of payment_token."
+                           "of payment_token; its signature is verified before use."
             },
             annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
           },
           "cancel_checkout" => {
-            description: "Cancel a checkout before payment. Irreversible — use this to abandon a " \
-                         "checkout the shopper no longer wants. Safe with respect to money, since " \
-                         "complete_checkout hasn't run yet.",
-            params: { "checkout_id" => ID, "idempotency_key" => IDEMPOTENCY_KEY },
+            description: "Abandon an open checkout before payment and return it with status canceled; " \
+                         "it cannot be completed afterwards. Use it when the shopper declines the " \
+                         "total; nothing has been charged yet, so no refund is needed. For a checkout " \
+                         "that already completed, use cancel_order instead. #{AUTH_NOTE}",
+            params: { "checkout_id" => "Checkout ID returned by create_checkout. #{ID}",
+                      "idempotency_key" => IDEMPOTENCY_KEY },
             annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
           },
           "get_order" => {
-            description: "Fetch a placed order's status, line items, and totals by ID. Returns " \
-                         "not-found rather than raising if the ID doesn't exist.",
-            params: { "order_id" => ID },
+            description: "Fetch a placed order by ID and return its line items with per-item " \
+                         "fulfillment status, shipping details, totals, permalink and any " \
+                         "cancellations, returns or refunds applied so far. Use it to answer " \
+                         "\"where is my order\" or to pick line item IDs for request_return or " \
+                         "refund_order; use list_orders to find an order without its ID, and " \
+                         "get_checkout for anything not yet paid. #{OPEN_NOTE} " \
+                         "An unknown ID returns an empty result rather than an error.",
+            params: { "order_id" => "Order ID from a completed checkout or list_orders. #{ID}" },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "list_orders" => {
+            description: "List the store's placed orders, newest first, optionally filtered by a " \
+                         "free-text query, and return up to `limit` orders, each with ID, line items, " \
+                         "totals, currency, permalink and any cancellation, refund or return " \
+                         "recorded. Use it to find an order when you don't hold its ID, e.g. " \
+                         "\"what did I order last week\"; once you have the ID, use get_order for " \
+                         "the full record with fulfillment and tracking, which list results may " \
+                         "leave out. Read-only, but it exposes customers' orders, so it requires an " \
+                         "authenticated session and may be rate-limited; a rejected call returns an " \
+                         "error result. An empty list means no match, not an error.",
+            params: {
+              "query" => "Optional free-text filter, e.g. an order number, product title or customer " \
+                         "email; how it matches depends on the store. Leave out to list all orders.",
+              "limit" => "Maximum number of orders to return; 5–10 suits most lookups."
+            },
             annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
           },
           "cancel_order" => {
-            description: "Cancel an already-placed order. Irreversible. Optional reason is a " \
-                         "free-text note for the merchant, not a fixed enum.",
+            description: "Cancel an entire placed order and return it with the cancellation recorded. " \
+                         "Use it before the order ships; for part of an order, or once it has shipped, " \
+                         "use request_return. Whether a refund follows automatically depends on the " \
+                         "store — check the returned order's adjustments. Cannot be undone. #{AUTH_NOTE}",
             params: {
-              "order_id" => ID, "idempotency_key" => IDEMPOTENCY_KEY,
-              "reason" => "Optional free-text reason for the cancellation."
+              "order_id" => "Order ID from a completed checkout. #{ID}", "idempotency_key" => IDEMPOTENCY_KEY,
+              "reason" => "Optional free-text note for the merchant, e.g. \"ordered by mistake\"."
             },
             annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
           },
           "request_return" => {
-            description: "Request a return for one or more order line items. This files the request; " \
-                         "it doesn't refund money itself — the order shows the items as pending until " \
-                         "the merchant processes it. Use refund_order only once a refund has actually " \
-                         "been approved.",
+            description: "File a return request for some or all line items of a placed order and " \
+                         "return the order with the request recorded as pending. It only asks — no " \
+                         "money moves until the merchant approves and a refund is issued with " \
+                         "refund_order. Use it for delivered items; use cancel_order for an order " \
+                         "that hasn't shipped. #{AUTH_NOTE}",
             params: {
-              "order_id" => ID,
-              "line_items" => "Items to return, each {id:, quantity:}.",
+              "order_id" => "Order ID from a completed checkout. #{ID}",
+              "line_items" => "Items to return, each {id:, quantity:} using the order line item IDs from get_order.",
               "idempotency_key" => IDEMPOTENCY_KEY,
-              "reason" => "Optional free-text reason for the return."
+              "reason" => "Optional free-text reason for the merchant, e.g. \"wrong size\"."
             },
             annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
           },
           "refund_order" => {
-            description: "Refund one or more order line items, moving money back to the shopper. " \
-                         "Irreversible. Use request_return first if the merchant requires a return " \
-                         "before refunding.",
+            description: "Refund some or all line items of a placed order back to the original " \
+                         "payment method and return the order with the refund recorded. Money moves " \
+                         "and it cannot be reversed. Use it once a refund is agreed; if the store " \
+                         "needs the goods back first, call request_return before this. To call off " \
+                         "a whole unshipped order, use cancel_order. #{AUTH_NOTE}",
             params: {
-              "order_id" => ID,
-              "line_items" => "Items to refund, each {id:, quantity:}.",
+              "order_id" => "Order ID from a completed checkout. #{ID}",
+              "line_items" => "Items to refund, each {id:, quantity:} using the order line item IDs from get_order.",
               "idempotency_key" => IDEMPOTENCY_KEY,
-              "reason" => "Optional free-text reason for the refund."
+              "reason" => "Optional free-text reason for the merchant."
             },
             annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
           }

data/lib/portage/ucp/reference_adapter.rb

@@ -133,6 +133,18 @@ module Portage
 
       def get_order(order_id:) = @orders[order_id]
 
+      # Matches the query against the order id and line item titles.
+      def list_orders(limit:, query: nil)
+        orders = @orders.values.reverse
+        if query
+          needle = query.downcase
+          orders = orders.select do |order|
+            order.id.downcase.include?(needle) || order.line_items.any? { |li| li.item.title.downcase.include?(needle) }
+          end
+        end
+        Portage::Ucp::OrderList.new(orders: orders.first(limit))
+      end
+
       def cancel_order(order_id:, idempotency_key:, reason: nil)
         dedup(idempotency_key) do
           add_adjustment(order_id, type: "cancellation", status: "completed", description: reason)

data/lib/portage/ucp/value_objects.rb

@@ -580,6 +580,13 @@ module Portage
       end
     end
 
+    # Portage extension (see Adapter#list_orders / Capabilities::ORDER_HISTORY)
+    # — wraps the list in an object because MCP's structuredContent must be a
+    # JSON object, not a bare array.
+    OrderList = Data.define(:orders) do
+      def to_wire_h = { "orders" => orders.map(&:to_wire_h) }
+    end
+
     # Portage extension (see Adapter#reorder / Capabilities::REORDER) — no
     # schemas/ counterpart to cite, since it isn't part of the UCP spec.
     # `reason` is a short adapter-chosen string (e.g. "out_of_stock",

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.15.1".freeze
+    VERSION = "0.17.0".freeze
   end
 end

data/lib/portage/ucp.rb

@@ -55,6 +55,7 @@ require_relative "ucp/capabilities/cart"
 require_relative "ucp/capabilities/checkout"
 require_relative "ucp/capabilities/order"
 require_relative "ucp/capabilities/reorder"
+require_relative "ucp/capabilities/order_history"
 require_relative "ucp/capabilities/discount"
 require_relative "ucp/capabilities/fulfillment"
 require_relative "ucp/capabilities/permalink"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.17.0
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.24'
+        version: '1.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.24'
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -191,6 +191,7 @@ files:
 - lib/portage/ucp/capabilities/fulfillment.rb
 - lib/portage/ucp/capabilities/identity_linking.rb
 - lib/portage/ucp/capabilities/order.rb
+- lib/portage/ucp/capabilities/order_history.rb
 - lib/portage/ucp/capabilities/payment_enrollment.rb
 - lib/portage/ucp/capabilities/payment_method.rb
 - lib/portage/ucp/capabilities/permalink.rb