portage-ucp 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a7cd8175dc8b1acd3a884205a5df5f030e897bf1090cdf6675fd582f7c4f0ee
-  data.tar.gz: 8acedc01a0e9dff428670248e9257647b26fb7ee54ea1e0625f67bf169c81285
+  metadata.gz: 6bfa07946dff1ff76a95ade848a4721727da69c8ecacd4d37c4a59bf449179e4
+  data.tar.gz: c23b673f2cedb83ffc2326804b96975b5d57c7737cd625bbf8465b89d02e4e70
 SHA512:
-  metadata.gz: 6422591fbb901e8e901b4ca6b6bba5b3cd8c6e776d1dd3980536c8245598787fbe2b25d4dd193bf5a05ed87cf6c4e2ff0d7f0b93222ae2716631f23fa028b7f6
-  data.tar.gz: 3d5928f821375dc3a71b7f9cae13864430d90b0167aebb8ca35f5ed008fe3e5617e0df0a95ada2f2db2fc962d8309eea7d852453374a81ce046f1609b9a366b7
+  metadata.gz: 3e53a572a3cddd068c4c653314c2348cbd3e75d014d563dc1bf6312eae84af8606364c747c1d58bd0f7accd82bb1a40199098fba4f40c03633ad8d42f4a1f443
+  data.tar.gz: aeda7078b20110826e45b900bcb634f8321f5b0df4edb7bb34374cabdd8da05158605757f790b917febb8f60c1b70f6fdb9e1e1d524de51b559bd63e45d6452e

data/CHANGELOG.md

@@ -6,6 +6,11 @@ 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.

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.
@@ -45,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,
@@ -54,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".
@@ -77,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,
@@ -134,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
@@ -146,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

@@ -25,9 +25,10 @@ module Portage
                        "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, use get_order, " \
-                       "cancel_order, request_return and refund_order. Catalog reads are open; every " \
-                       "tool that changes state needs an authenticated session, and a server run " \
+                       "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
 
@@ -191,9 +192,27 @@ module Portage
                          "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 get_checkout for anything not yet paid. #{OPEN_NOTE} " \
+                         "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. #{ID}" },
+            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" => {

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.16.0".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.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-21 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