solidus_mcp 0.2.0.rc1 → 0.2.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9309d2faa1dc3fb43625241d6d56734bdf7ad99605a910714cb1241e6da551b7
-  data.tar.gz: a2e9c1d6ac448bb64d97134652c353cb85becdd602c39e2370b6fc70bcd2624e
+  metadata.gz: f5922154aa4d65341aecb0312e8a1a72d20ef1e81a5e423f000eaa6f6239e4fd
+  data.tar.gz: 2ff83f035e9b9268c9df907b4f40004b1b3528af8c30ff033b8b3fe4493847b2
 SHA512:
-  metadata.gz: b6d6e4a456c1415d09edd064c6bb35c884d867d75fddb82aa58fb077d972b9d68d538bdddaef97e8b16f8d293d461e30f1fde75ec85519ba5f19d59d4b538329
-  data.tar.gz: 8f56da97fc37e7df7ac216bf9397a13df4219644759e37df50bccfab42b5c63110bd8173eb82f2f2adac964e8f7ccaec8c930206706040de8febe65af2c68214
+  metadata.gz: fd23eee0805800c0de1d3a939c1ea99358aef8ad711b3437f4c002c17a67b5da3388dd0fa37dfc7fa0bb48ceb0cf10b588e7b8e3e8f92db836f13ada990141ba
+  data.tar.gz: a8aba2d7d878b8993289046e915eba690d8dd70a7fd1fc9fe241337174bfd12b741fbcc305658b809cceab09002179533b8fc43f43fbb4f2bbc8765cd1eae4a5

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+- Add optional product and order serializer hooks for built-in read tools, with
+  a plain Ruby interface and an Alba adapter example. Preserve record authorization,
+  pagination, and tool-owned order line items; resolve class names across Rails reloads.
+- Add `Policy#can?` so serializers can omit inaccessible optional related fields
+  while retaining strict authorization for required records.
+
 ## 0.2.0.rc1 (2026-11-08)
 
 First public release candidate. The earlier registry implementation was unpublished.

data/CONTRIBUTING.md

@@ -25,7 +25,54 @@ The direct migration command is `bin/rails solidus_mcp:migrate` after host
 migrations. Keep migrations immutable and safe alongside the previous release.
 Do not run down migrations automatically during deployment rollback.
 
-For release, run admin and core-only suites, both loading checks, style checks,
-and gem packaging locally. Review the package and changelog. Preserve immutable
-build inputs and verify the real host integration before production promotion.
-Publishing, pushing, tagging and deployment remain deliberate separate actions.
+## Releasing
+
+Pushing a version tag triggers `.github/workflows/release.yml`. The workflow
+requires the tag to match `SolidusMcp::VERSION` exactly (for example,
+`v0.2.0.rc2`) and its commit to be on `main`. It runs the full Rails/admin CI
+matrix before building and publishing the gem to RubyGems. Ordinary branch pushes
+and pull requests do not publish. The built gem is retained as a workflow artifact.
+Publishing does not update or deploy any host application.
+
+### One-time setup
+
+1. In this repository's GitHub **Settings > Environments**, create `rubygems`.
+   Restrict its deployment tags to `v*`; optionally require a release reviewer.
+   Allow version tags to be created only by release maintainers using a GitHub
+   tag ruleset. Tagged code executes in the publishing workflow, so access to
+   create release tags is release authority.
+2. On RubyGems.org, open the `solidus_mcp` gem's **Settings > Trusted Publishers**
+   and add a GitHub Actions publisher with these exact values:
+   - Repository owner: `michaelmichael`
+   - Repository name: `solidus_mcp`
+   - Workflow filename: `release.yml`
+   - Environment: `rubygems`
+
+The workflow uses OIDC to obtain short-lived publishing credentials. Do not add
+a `RUBYGEMS_API_KEY` or other long-lived publishing secret to GitHub. The
+`id-token: write` permission is limited to the publishing job, after tests pass.
+
+### Each release
+
+1. Bump `lib/solidus_mcp/version.rb` and move the applicable `CHANGELOG.md`
+   entries into a section for that version.
+2. Run `bin/ci` (or `docker compose run --rm test`) and review the package and
+   changelog. Merge the version change into `main` and wait for CI to pass.
+3. From a clean checkout of the merged `main` commit, create and push the tag:
+
+   ```bash
+   git switch main
+   git pull --ff-only
+   test -z "$(git status --porcelain)"
+   version=$(ruby -r ./lib/solidus_mcp/version -e 'print SolidusMcp::VERSION')
+   git tag -a "v${version}" -m "Release ${version}"
+   git push origin "v${version}"
+   ```
+
+4. Watch the **Release gem** workflow, approve the `rubygems` deployment if
+   required, and verify the new version on RubyGems.org before updating hosts.
+
+Do not move a published tag or try to replace a published gem. Fixes need a new
+version. A failed run can be re-run if publishing never succeeded; if the gem is
+already on RubyGems, do not re-run the publish job (RubyGems rejects duplicates).
+Verify the real host integration before production promotion.

data/README.md

@@ -230,6 +230,97 @@ The built-in price update tools use Solidus's standard pricing options. Stores w
 
 Product and price updates take effect immediately. There are currently no built-in order or inventory mutation tools. Add your own, as desired.
 
+## Custom serializers
+
+You can change the product and order fields returned by the built-in tools without replacing those tools. Configure a serializer class in your initializer:
+
+```ruby
+config.product_serializer = 'Mcp::ProductSerializer'
+# config.order_serializer = 'Mcp::OrderSerializer'
+```
+
+Both settings are optional. Leave one unset to keep that record's default representation. Use class-name strings so Rails can reload your serializers in development.
+
+Each class implements `.call(record, context:)` and returns a JSON-compatible Ruby hash. For example, in `app/serializers/mcp/product_serializer.rb`:
+
+```ruby
+module Mcp
+  class ProductSerializer
+    def self.call(product, context:)
+      {
+        id: product.id,
+        name: product.name,
+        display_name: "#{product.name} (#{product.slug})"
+      }
+    end
+  end
+end
+```
+
+The returned hash replaces the default fields; it isn't merged with them. You choose which fields to include. The same interface works for orders.
+
+| Setting | Used by |
+| --- | --- |
+| `product_serializer` | `search_products` and `get_product` |
+| `order_serializer` | `search_orders` and `get_order` |
+
+Pagination stays under the tool's control. `get_order` still adds its authorized, bounded line items and truncation indicator, so order serializers cannot return `line_items` or `line_items_truncated`. Variants, prices, inventory, order status, and write responses keep their existing representations.
+
+### Using Alba or another library
+
+The hook accepts plain Ruby classes or adapters for your preferred serialization library. Add that library to your app's Gemfile; it is not a runtime dependency of Solidus MCP.
+
+For Alba, define `app/serializers/mcp/product_resource.rb`:
+
+```ruby
+module Mcp
+  class ProductResource
+    include Alba::Resource
+
+    attributes :id, :name, :slug
+  end
+end
+```
+
+Then use this adapter in `app/serializers/mcp/product_serializer.rb`:
+
+```ruby
+module Mcp
+  class ProductSerializer
+    def self.call(product, context:)
+      ProductResource.new(product, params: {policy: context}).to_h
+    end
+  end
+end
+```
+
+Return a hash, not an encoded JSON string. For another library, adapt its output to the same interface.
+
+### Authorization and field access
+
+The gem checks that the connected user can read the product or order before calling your serializer. If you include information from related records, your serializer must check access to those records as well. For example, a store may allow someone to read an order's totals while restricting access to its shipping address.
+
+For optional information, use `context.can?` to check access and omit the fields when the record is missing or access is denied:
+
+```ruby
+def self.call(order, context:)
+  result = {number: order.number}
+  address = order.ship_address
+  result[:shipping_city] = address.city if context.can?(:read, address)
+  result
+end
+```
+
+The order still comes back if the shipping address is inaccessible; it simply has no `shipping_city` field. Clients should not assume an omitted field means no related record exists. The check uses the store's existing Solidus abilities and returns `false` for a missing record.
+
+This does not create a separate MCP permission for addresses. An account with broad Solidus access will pass these record checks. Your store controls which fields its serializers expose.
+
+If a related record is essential to the response, use `context.authorize_record!(:read, record)` instead. It raises an access-denied error and fails the call when the record is missing or access is denied. Access to the primary product or order is always required.
+
+For related collections, use `context.scope(Model)` to return only records the connected user can read. These helpers do not automatically restrict the queries or associations you access elsewhere in the serializer.
+
+These hooks do not add field-level permissions. Serializer changes apply to existing connections with access to the affected tools. To expose sensitive information under a separate grant, use a custom tool with its own permission key. Serializers are trusted application code, just like custom tools.
+
 ## Custom tools
 
 To create your own custom MCP tools, add a named subclass of `SolidusMcp::Tool` under `app/tools`. For example, `app/tools/count_products.rb`:

data/app/services/solidus_mcp/serializers.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module SolidusMcp
-  # Fixed public representations. Related records are checked separately.
+  # Record authorization stays outside host serialization. Custom serializers are
+  # trusted application code and must authorize any related records they expose.
   class Serializers
     def initialize(policy)
       @policy = policy
@@ -9,7 +10,9 @@ module SolidusMcp
 
     def product(record)
       @policy.authorize_record!(:read, record)
-      record.attributes.slice("id", "name", "slug", "description", "meta_title", "meta_description", "meta_keywords")
+      serialize(:product, record) do
+        record.attributes.slice("id", "name", "slug", "description", "meta_title", "meta_description", "meta_keywords")
+      end
     end
 
     def variant(record)
@@ -36,8 +39,10 @@ module SolidusMcp
 
     def order(record)
       @policy.authorize_record!(:read, record)
-      status(record).merge(currency: record.currency, total: record.total.to_s("F"),
-        item_total: record.item_total.to_s("F"), completed_at: record.completed_at&.iso8601)
+      serialize(:order, record) do
+        status(record).merge(currency: record.currency, total: record.total.to_s("F"),
+          item_total: record.item_total.to_s("F"), completed_at: record.completed_at&.iso8601)
+      end
     end
 
     def status(record)
@@ -45,5 +50,24 @@ module SolidusMcp
       {id: record.id, number: record.number, state: record.state,
        payment_state: record.payment_state, shipment_state: record.shipment_state}
     end
+
+    private
+
+    def serialize(kind, record)
+      serializer = SolidusMcp.configuration.serializer_class(kind)
+      return yield unless serializer
+
+      result = serializer.call(record, context: @policy)
+      valid = result.is_a?(Hash) && result.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) }
+      unless valid
+        raise ToolError, "#{serializer.name} must return a Hash with string or symbol keys, not encoded JSON"
+      end
+      keys = result.keys.map(&:to_s)
+      raise ToolError, "#{serializer.name} returned duplicate field names" unless keys.uniq == keys
+      if kind == :order && (keys & %w[line_items line_items_truncated]).any?
+        raise ToolError, "Order serializers cannot replace line_items or line_items_truncated"
+      end
+      result.dup
+    end
   end
 end

data/lib/solidus_mcp/configuration.rb

@@ -5,7 +5,8 @@ require "uri"
 module SolidusMcp
   class Configuration
     attr_accessor :custom_tools, :endpoint_url, :issuer_url, :allowed_origins,
-      :server_name, :instructions, :resource_owner_authenticator, :default_shipping_category_id, :superadmin_emails
+      :server_name, :instructions, :resource_owner_authenticator, :default_shipping_category_id, :superadmin_emails,
+      :product_serializer, :order_serializer
 
     def initialize
       @superadmin_emails = ENV.fetch("SOLIDUS_MCP_SUPERADMIN_EMAILS", "").split(",").map { |email| email.strip.downcase }.uniq
@@ -23,6 +24,23 @@ module SolidusMcp
       endpoint_url.present? && issuer_url.present?
     end
 
+    def serializer_class(kind)
+      name = public_send(:"#{kind}_serializer")
+      return if name.nil?
+      unless name.is_a?(String) && name.present?
+        raise ArgumentError, "#{kind}_serializer must be a class-name string or nil"
+      end
+      serializer = name.constantize
+      unless serializer.is_a?(Class) && serializer.respond_to?(:call)
+        raise ArgumentError, "#{name} must implement .call(record, context:)"
+      end
+      serializer
+    end
+
+    def validate_serializers!
+      %i[product order].each { |kind| serializer_class(kind) }
+    end
+
     def validate!
       [endpoint_url, issuer_url].each do |value|
         uri = URI.parse(value.to_s)

data/lib/solidus_mcp/engine.rb

@@ -5,6 +5,7 @@ module SolidusMcp
     engine_name "solidus_mcp"
 
     config.to_prepare do
+      SolidusMcp.configuration.validate_serializers!
       SolidusMcp.rebuild_registry!
     end
 

data/lib/solidus_mcp/policy.rb

@@ -31,10 +31,14 @@ module SolidusMcp
     end
 
     def authorize_record!(action, record)
-      raise AccessDenied, "Record is unavailable" unless ability.can?(action, record)
+      raise AccessDenied, "Record is unavailable" unless can?(action, record)
       record
     end
 
+    def can?(action, record)
+      !record.nil? && ability.can?(action, record)
+    end
+
     def scope(model, action = :read)
       model.accessible_by(ability, action)
     end

data/lib/solidus_mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidusMcp
-  VERSION = "0.2.0.rc1"
+  VERSION = "0.2.0.rc2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solidus_mcp
 version: !ruby/object:Gem::Version
-  version: 0.2.0.rc1
+  version: 0.2.0.rc2
 platform: ruby
 authors:
 - Michael Caviness
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-08 00:00:00.000000000 Z
+date: 2026-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: solidus_core