spree_mcp 6.0.0.rc4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c756a35e627693b5ce74551d146f4d1e5cff4715d88332bfda3a609cb3c394d3
+  data.tar.gz: eb657c2993cef7ea93dd3c04583b08eb3a8251395c1f825f4432cb063a3d3013
+SHA512:
+  metadata.gz: a539ac84fd659c13e33512311a1d16676500ab831b20e32cb08763d5429709cd2685ae2474786431c45b6e9f559d358db31888ca5dce7cc0e33f12aae92b13ac
+  data.tar.gz: 1d2c0340424e86042bd677476bfb0a26308eab303b1952eba25c1bbfbb017694e910bc269da4ae20c2294179aa1b276e0dde5bd7711ea904bdf0b18e5fde7923

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present, Vendo Sp. z o.o., Vendo Connect Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,24 @@
+# Spree MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for the
+Spree back office. Any MCP client — Claude Code, Cursor, an in-house agent —
+can merchandise the catalog, answer reporting questions and manage store setup
+in plain language, under the same tenancy and permission rules as the Admin
+API.
+
+```bash
+spree add mcp   # or add gem 'spree_mcp' to the Gemfile
+```
+
+The endpoint is `POST /api/v3/admin/mcp`, authenticated with a Spree secret API
+key sent as `X-Spree-API-Key: sk_…` or `Authorization: Bearer sk_…`. The key's
+scopes decide which tools the model is offered, so an agent is never told about
+a capability its credential does not carry.
+
+This gem is a protocol adapter and nothing more. The tools, their schemas and
+the permissions gating them live in `spree_core` as `Spree.admin_agent_tools`, which
+means an extension registers a tool without depending on this gem, and the
+dashboard assistant offers the same tools over a different transport.
+
+See the [documentation](https://spreecommerce.org/docs/developer/mcp/overview)
+and `docs/plans/6.0-mcp-server.md`.

data/Rakefile

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rspec/core/rake_task'
+require 'spree/testing_support/common_rake'
+
+RSpec::Core::RakeTask.new
+
+task default: :spec
+
+desc "Generates a dummy app for testing"
+task :test_app do
+  ENV['LIB_NAME'] = 'spree_mcp'
+  Rake::Task['common:test_app'].invoke
+end

data/app/controllers/spree/api/v3/admin/mcp_controller.rb

@@ -0,0 +1,195 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The MCP endpoint: `POST /api/v3/admin/mcp`.
+        #
+        # An ordinary admin API controller rather than the gem's Rack
+        # transport, which takes one pre-built server for every request and so
+        # cannot carry a per-request principal. Here the key authenticates
+        # through the concern every other admin endpoint uses, selects the
+        # store the same way, and gets a server built for it alone.
+        #
+        # Stateless: one JSON-RPC message per request, one JSON response, no
+        # session and no server-to-client stream, so any Puma worker answers
+        # any request.
+        #
+        # See docs/plans/6.0-mcp-server.md.
+        class McpController < Spree::Api::V3::Admin::BaseController
+          # The scope gate is per tool, not per request: a call carries the
+          # tool it wants inside the JSON-RPC body, and every tool already
+          # declares the permission it needs. Checking one grant's scopes for
+          # the whole endpoint would mean either refusing a read it covers or
+          # waving through a write it does not.
+          skip_scope_check!
+
+          # Prepended so it answers before the inherited authentication does.
+          # The generic "Authentication required" is useless to an agent: this
+          # text is what both the model and the person actually read when a
+          # client is misconfigured.
+          prepend_before_action :require_oauth_token!
+
+          def create
+            render json: server.handle_json(request.body.read), content_type: 'application/json'
+          end
+
+          protected
+
+          # The only credential this endpoint takes. An agent acts for a
+          # person, so it carries that person's grant: the token names who
+          # approved it and what they allowed, both of which a standing key
+          # cannot express. A secret key authenticates the rest of the Admin
+          # API and the `spree api` CLI; it is deliberately not accepted
+          # here.
+          #
+          # The grant already bound the token to a real admin user and the
+          # audience check confirmed it was issued for this endpoint, which
+          # is the assurance `require_store_membership!` gives a JWT.
+          def authenticate_admin!
+            owner = oauth_resource_owner
+            # A `before_action` halts on a render, not on a falsy return, so
+            # refusing has to render. The grant's owner is an admin in every
+            # path that exists today; a customer-owned token would otherwise
+            # reach the action and die as a confusing 422 further in.
+            return refuse_unauthenticated if owner.nil?
+
+            @current_api_key = nil
+            @current_user = owner
+            true
+          end
+
+          private
+
+          # Split rather than matched: a regex with `\s+(.+)` backtracks on a
+          # header of many spaces, and this one is attacker-supplied on an
+          # unauthenticated request.
+          def bearer_value
+            scheme, value = request.headers['Authorization'].to_s.split(' ', 2)
+            return unless scheme&.casecmp?('Bearer')
+
+            value.to_s.strip.presence
+          end
+
+          def server
+            Spree::Mcp::Server.for(agent_context)
+          end
+
+          # The caller's authority is the admin user's own permissions,
+          # narrowed by what they consented to — resolved on every request
+          # rather than frozen when the token was issued, so narrowing a role
+          # takes effect immediately.
+          def agent_context
+            Spree::AgentTools::Context.new(
+              store: current_store,
+              user: oauth_resource_owner,
+              granted_scopes: current_oauth_token.scopes.to_a,
+              # What a dispatched tool call authenticates with: this request's
+              # own credential, repeated. The grant is what bounds the agent,
+              # so the inner request must be the same grant — not a wider one
+              # minted on its behalf.
+              request_headers: request.env.slice(*Spree::AgentTools::ApiDispatch::FORWARDED_HEADERS)
+            )
+          end
+
+          # RFC 6750: the challenge names where to discover the authorization
+          # server, which is how a consumer client starts its own sign-in.
+          #
+          # Both URLs are built from the origin this request arrived on, so
+          # they match what the client used and each other. A client compares
+          # them, and a different scheme or host is enough for it to decide
+          # the document describes another resource and stop.
+          #
+          # No `scope`: it is a SHOULD, and listing every grantable key makes
+          # a header several kilobytes long. A client reads the real list from
+          # the metadata document.
+          def oauth_challenge
+            format(
+              'Bearer realm="%<realm>s", resource_metadata="%<metadata>s"',
+              realm: Spree::Api::Oauth.resource_identifier(:admin, request.base_url),
+              metadata: "#{request.base_url}/api/v3/oauth/protected-resource/admin"
+            )
+          end
+
+          # A token issued for another resource must not work here, whatever
+          # its scopes say. Doorkeeper binds the audience at issue; this is
+          # the check that it matches.
+          # A token selects its own store, the way a secret key does.
+          #
+          # An MCP client sends a URL and a bearer token and nothing else — it
+          # has no way to set the store header the Admin API otherwise uses —
+          # so without this a token granted for any store but the default one
+          # would be measured against the default store's resource identifier
+          # and always fail its audience check.
+          def resolve_admin_store
+            bearer_access_token&.application&.store || super
+          end
+
+          # The token the bearer header names, before any check of whether it
+          # may be used here. Resolving the store needs it, and the audience
+          # check needs the store, so the lookup has to come first — and it is
+          # memoized because three callers want the same row.
+          def bearer_access_token
+            return @bearer_access_token if defined?(@bearer_access_token)
+
+            raw = bearer_value
+            @bearer_access_token = raw.present? ? Spree::OauthAccessToken.by_token(raw) : nil
+          end
+
+          # The token this request may actually act on: live, and issued for
+          # the Admin API. Named for the hook ScopedAuthorization reads, so a
+          # grant narrows authority through the same path every admin
+          # endpoint uses rather than only here.
+          #
+          # This endpoint shares the Admin API's audience rather than holding
+          # one of its own, because a tool call reaches data by dispatching
+          # into the Admin API carrying this very token. Two audiences on one
+          # credential could never both be satisfied.
+          def current_oauth_token
+            return @current_oauth_token if defined?(@current_oauth_token)
+
+            token = bearer_access_token
+            @current_oauth_token = token if token&.accessible? && admin_audience_matches?(token)
+          end
+
+          def oauth_resource_owner
+            owner = current_oauth_token.resource_owner
+            owner if owner.is_a?(Spree.admin_user_class)
+          end
+
+          # The error text is what both the model and the person read, so it
+          # says which header to set and where the key comes from rather than
+          # only that something was missing.
+          # Two ways in: a secret key a developer configured, or an OAuth
+          # token a merchant approved. A 401 carries the OAuth challenge, so
+          # a consumer client that arrives with nothing discovers how to sign
+          # in rather than simply failing.
+          # A 401 carrying the discovery header, which is how a client that
+          # arrived with nothing learns where to sign in rather than simply
+          # failing.
+          def require_oauth_token!
+            return if current_oauth_token.present?
+
+            refuse_unauthenticated
+          end
+
+          def refuse_unauthenticated
+            response.headers['WWW-Authenticate'] = oauth_challenge
+
+            render json: {
+              jsonrpc: '2.0',
+              id: nil,
+              error: {
+                code: -32_001,
+                message: 'Sign in to this store to continue. Your client will offer that when ' \
+                         'it reads the challenge on this response. A Spree API key is not ' \
+                         'accepted here — an agent acts for a person, so it carries that ' \
+                         "person's own permissions. Use the `spree api` CLI for scripted " \
+                         'access that cannot sign in.'
+              }
+            }, status: :unauthorized
+          end
+        end
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,12 @@
+Spree::Core::Engine.add_routes do
+  namespace :api, defaults: { format: 'json' } do
+    namespace :v3 do
+      namespace :admin do
+        # One JSON-RPC message per request. Drawn inside the admin namespace so
+        # the endpoint inherits the Admin API's authentication, rate limiting
+        # and security headers rather than reimplementing them.
+        post 'mcp', to: 'mcp#create'
+      end
+    end
+  end
+end

data/lib/spree/mcp/engine.rb

@@ -0,0 +1,9 @@
+module Spree
+  module Mcp
+    class Engine < ::Rails::Engine
+      isolate_namespace Spree
+      engine_name 'spree_mcp'
+
+    end
+  end
+end

data/lib/spree/mcp/exports.rb

@@ -0,0 +1,122 @@
+module Spree
+  module Mcp
+    # Finished exports, offered as MCP resources.
+    #
+    # A tool result has to fit the model's context; an export does not. A
+    # catalog of ten thousand products is megabytes of CSV, which is why
+    # `create_export` hands back an id rather than a file. Resources are the
+    # protocol's answer to that: the client sees what exists, and fetches a
+    # body only when it decides to.
+    #
+    # Reading one costs the same permission as reading the records it holds —
+    # a customers export needs what a customer needs — so the file cannot
+    # become a way around a scope the merchant withheld.
+    module Exports
+      URI_SCHEME = 'spree+export'.freeze
+
+      # Set by what a model can read, not by what storage can hold. A CSV is
+      # text, so this is roughly 50,000 tokens — a large but survivable share
+      # of a context window. Beyond it the client is told the size and given
+      # the dashboard link.
+      MAX_INLINE_BYTES = 200_000
+
+      # Exports whose rows carry a bearer instrument — a code that spends
+      # money for whoever reads it. The merchant downloads these from the
+      # dashboard; handing one to a model puts live codes in a third party's
+      # chat history, which cannot be undone.
+      #
+      # `Spree::GiftCard` is already kept out of the resource map and out of
+      # any serialized order for the same reason. An export must not be the
+      # way around that. The list lives with the tool that creates them, so
+      # refusing to make one and refusing to read one cannot disagree.
+
+      class << self
+        # @param context [Spree::AgentTools::Context]
+        # @return [Array<Hash>] MCP resource descriptors
+        def list(context)
+          response = dispatch(context, :get, '/api/v3/admin/exports', params: { limit: 50 })
+          return [] unless response.success?
+
+          Array(response.data).
+            select { |export| export['done'] && export['byte_size'].to_i.positive? }.
+            map { |export| descriptor(export) }
+        end
+
+        # @param context [Spree::AgentTools::Context]
+        # @param uri [String]
+        # @return [Array<Hash>, nil] contents, or nil when there is no such
+        #   export this caller may read
+        def read(context, uri)
+          id = uri.to_s.delete_prefix("#{URI_SCHEME}://")
+          return if id.blank?
+
+          # The endpoint answers 404 for an export of another store and for
+          # one this credential's scopes do not cover, so there is no second
+          # permission check here.
+          export = dispatch(context, :get, "/api/v3/admin/exports/#{id}")
+          return unless export.success?
+
+          record = export.data.to_h
+          return unless record['done']
+
+          return [withheld(uri)] if bearer_export?(record['type'])
+
+          size = record['byte_size'].to_i
+          return [too_large(uri, size)] if size > MAX_INLINE_BYTES
+
+          contents(context, uri, id)
+        end
+
+        private
+
+        def contents(context, uri, id)
+          file = dispatch(context, :get, "/api/v3/admin/exports/#{id}/download")
+          return [{ uri: uri, mimeType: 'text/plain', text: file.error_message }] unless file.success?
+
+          [{ uri: uri, mimeType: 'text/csv', text: file.content }]
+        end
+
+        def dispatch(context, method, path, params: {})
+          Spree::AgentTools::ApiDispatch.new(context).call(method: method, path: path, params: params)
+        end
+
+        def descriptor(export)
+          {
+            uri: "#{URI_SCHEME}://#{export['id']}",
+            name: export['filename'].to_s,
+            title: "#{export['type'].to_s.tr('_', ' ').humanize} export".strip,
+            description: "Generated #{Date.parse(export['created_at'].to_s).to_fs(:long)}",
+            mimeType: 'text/csv',
+            size: export['byte_size']
+          }
+        rescue Date::Error
+          { uri: "#{URI_SCHEME}://#{export['id']}", name: export['filename'].to_s,
+            mimeType: 'text/csv', size: export['byte_size'] }
+        end
+
+        def bearer_export?(type)
+          Spree::AgentTools::CreateExport::BEARER_EXPORTS.include?(type.to_s)
+        end
+
+        def withheld(uri)
+          {
+            uri: uri,
+            mimeType: 'text/plain',
+            text: 'This export contains codes that spend money for whoever reads them, so it is ' \
+                  'not readable here. Download it from the dashboard instead.'
+          }
+        end
+
+        def too_large(uri, byte_size)
+          {
+            uri: uri,
+            mimeType: 'text/plain',
+            text: "This export is #{ActiveSupport::NumberHelper.number_to_human_size(byte_size)}, " \
+                  'too large to read here. Download it from the dashboard, or narrow the export with ' \
+                  'filters and create a smaller one.'
+          }
+        end
+      end
+    end
+  end
+end

data/lib/spree/mcp/server.rb

@@ -0,0 +1,116 @@
+module Spree
+  module Mcp
+    # Builds an `MCP::Server` for one caller.
+    #
+    # Per request, not per process. A server carries the tools its caller may
+    # use and nothing else — a key minted to read orders is never told a
+    # refund tool exists — so the tool list cannot be shared between
+    # principals, and the gem's own Rack transport (one server for every
+    # request) is not what mounts this. An ordinary admin API controller does,
+    # and hands the JSON-RPC message to {MCP::Server#handle_json}.
+    module Server
+      # What the model is told about using this server at discovery, so it
+      # reaches for the discovery tools before guessing at names and filters.
+      INSTRUCTIONS = <<~TEXT.freeze
+        This server manages one Spree store's back office.
+
+        Start with describe_resource to learn which resources exist and which
+        fields each can be filtered and sorted by, then search_resources to find
+        records and get_resource to read one in full. For numbers — revenue,
+        orders, units — use describe_reporting and then query_report rather than
+        counting records yourself.
+
+        Which products a category, collection, catalog or price list holds is
+        curate_products — merchandising is mostly membership, and that one tool
+        covers every one of those parents.
+
+        Writes are named after what they do: a tool per operation, each running
+        the same workflow the dashboard runs, so validations and notifications
+        behave identically. Record arguments are prefixed ids as they appear in
+        search results. You are only offered the tools this credential permits,
+        so a tool you cannot see is one this store has not granted.
+
+        A file the merchant gives you goes the other way: upload_file stores it
+        and answers with an id, which you then pass to whatever uses it —
+        media_create to put an image on a product, create_import to start a
+        CSV import. Storing one changes nothing by itself.
+
+        Files are MCP resources, not tool results. A finished export is one:
+        after create_export, read its contents from resources rather than
+        reporting a download path — the path is for the merchant, the
+        resource is for you. So are the documents attached to records — a
+        buyer's purchase order, a shipping label — which come back as the
+        file itself for you to read.
+      TEXT
+
+      class << self
+        # @param context [Spree::AgentTools::Context] who is asking, and where
+        # @return [MCP::Server]
+        def for(context)
+          server = ::MCP::Server.new(
+            name: 'spree-admin',
+            title: "#{context.store.name} (Spree admin)",
+            version: Spree.version,
+            instructions: INSTRUCTIONS,
+            tools: tools_for(context),
+            server_context: { store_id: context.store.id }
+          )
+
+          register_resources(server, context)
+          server
+        end
+
+        # The files a client may fetch: finished exports, and the documents
+        # attached to records — a buyer's purchase order, a shipping label.
+        #
+        # A tool result has to fit the model's context; a file does not, so
+        # `create_export` hands back an id rather than a file. Resources are
+        # the protocol's answer: the client sees what exists and fetches a
+        # body only when it decides to.
+        #
+        # Handlers rather than a fixed list, because what exists depends on
+        # the store and on what this grant may read — both known only per
+        # request. The closure carries the caller, so a resource one
+        # credential can see is never offered to another.
+        #
+        # The protocol allows one handler of each kind, so the sources are
+        # composed here: each owns which of its records the caller may see,
+        # and each answers only for its own URI scheme.
+        #
+        # Exports are the only files a client fetches. A product's media, an
+        # order's purchase order and an import's own file are things an agent
+        # puts there, not things it reads back — and they are already visible
+        # on the records that carry them.
+        SOURCES = [Exports].freeze
+
+        def register_resources(server, context)
+          server.resources_list_handler { SOURCES.flat_map { |source| source.list(context) } }
+
+          server.resources_read_handler do |params|
+            uri = params[:uri] || params['uri']
+            contents = SOURCES.lazy.filter_map { |source| source.read(context, uri) }.first
+            # A file another store owns, or one this grant may not read, is
+            # indistinguishable from one that does not exist — the same answer
+            # the tools give, so a probe learns nothing either way.
+            raise ::MCP::Server::ResourceNotFoundError.new(uri, params) if contents.nil?
+
+            contents
+          end
+        end
+
+        # The tools this caller may use, as MCP definitions.
+        #
+        # Filtering happens here rather than at call time, so a tool the
+        # credential cannot use is never named to the model — and a call to
+        # something it was not offered is "unknown tool", not "forbidden",
+        # which says less about what else exists.
+        #
+        # @param context [Spree::AgentTools::Context]
+        # @return [Array<Class<MCP::Tool>>]
+        def tools_for(context)
+          Spree.admin_agent_tools.available_for(context).map { |tool| ToolAdapter.build(tool) }
+        end
+      end
+    end
+  end
+end

data/lib/spree/mcp/tool_adapter.rb

@@ -0,0 +1,144 @@
+module Spree
+  module Mcp
+    # Turns a {Spree::AgentTool} into an `MCP::Tool` the protocol can offer.
+    #
+    # The whole adapter: a name, a description, the tool's parameter schema as
+    # JSON Schema, and a handler that runs the tool and shapes what comes back.
+    # Nothing about a tool is written twice — a tool registered by an extension
+    # is offered over MCP with no MCP code anywhere near it.
+    module ToolAdapter
+      class << self
+        # @param tool [Spree::AgentTool] instantiated for the caller's context
+        # @return [Class<MCP::Tool>]
+        def build(tool)
+          # The block is instance_exec'd on the generated tool class, so it
+          # cannot call back into this module by name — `adapter` closes over
+          # it instead.
+          adapter = self
+
+          ::MCP::Tool.define(
+            name: tool.tool_name,
+            description: tool.description,
+            input_schema: input_schema(tool),
+            annotations: annotations(tool)
+          ) { |**arguments| adapter.respond(tool, arguments) }
+        end
+
+        # The tool's declared params as JSON Schema.
+        #
+        # @param tool [Spree::AgentTool]
+        # @return [Hash]
+        def input_schema(tool)
+          properties = tool.params.to_h do |name, options|
+            property = { type: json_type(options[:type]) }
+            property[:description] = options[:description] if options[:description].present?
+            # An array must say what it holds: a client validating arguments
+            # against the schema refuses the call otherwise.
+            property[:items] = { type: json_type(options[:items] || :string) } if property[:type] == 'array'
+
+            [name.to_s, property]
+          end
+
+          {
+            type: 'object',
+            properties: properties,
+            required: tool.params.select { |_name, options| options[:required] }.keys.map(&:to_s)
+          }
+        end
+
+        # Clients that gate confirmation on annotations rather than on a
+        # server's word need both hints set explicitly: the gem defaults
+        # `destructiveHint` to true, so a read tool that says nothing would be
+        # confirmed like a deletion.
+        #
+        # @return [Hash]
+        def annotations(tool)
+          { read_only_hint: !tool.mutating?, destructive_hint: tool.mutating?, idempotent_hint: !tool.mutating? }
+        end
+
+        # A tool answers with a plain hash. A hash carrying `:error` is the
+        # tool refusing — the model should read it and correct itself, so it
+        # comes back as a tool error rather than a protocol error, which the
+        # model never sees.
+        #
+        # A refusal carries more than its message: the resources that do
+        # exist, the fields that can be filtered, the import's own column
+        # names. Forwarding only `:error` threw all of that away, so a model
+        # told "Unknown filter(s): notreal_eq" had to guess again instead of
+        # reading the list the tool had already computed.
+        #
+        # Public because the definition block calls it through a closure.
+        #
+        # @param tool [Spree::AgentTool]
+        # @param arguments [Hash]
+        # @return [MCP::Tool::Response]
+        def respond(tool, arguments)
+          result = tool.call(**arguments.symbolize_keys.except(:server_context))
+
+          if result.is_a?(Hash) && result[:error].present?
+            ::MCP::Tool::Response.new([{ type: 'text', text: refusal_text(result) }], error: true)
+          else
+            ::MCP::Tool::Response.new([{ type: 'text', text: text_for(result) }], structured_content: result)
+          end
+        rescue ArgumentError => e
+          # A missing or unknown keyword means the model filled the schema in
+          # wrongly; naming the parameter lets it retry correctly.
+          ::MCP::Tool::Response.new([{ type: 'text', text: e.message }], error: true)
+        end
+
+        private
+
+        # A tool declares Ruby-ish types; JSON Schema wants its own names, and
+        # anything unrecognised is a string, which every client can render.
+        def json_type(type)
+          case type&.to_sym
+          when :boolean then 'boolean'
+          when :integer then 'integer'
+          when :number, :float, :decimal then 'number'
+          when :object, :hash then 'object'
+          when :array then 'array'
+          else 'string'
+          end
+        end
+
+        # A line the client can show beside its confirmation prompt, and the
+        # model can read without parsing the structured payload.
+        # What the model reads.
+        #
+        # A client may render the structured half, the text half, or both —
+        # the protocol does not say — so the text has to carry the answer
+        # rather than point at it. Claude reads the text, so a payload that
+        # travels only as structured content reaches the model as nothing:
+        # a search answered "Found 1 match." with the match itself stripped,
+        # and the model could not name what it had just found.
+        #
+        # A count is a description of an answer, never the answer. The only
+        # text that may stand in for a payload is one the tool wrote itself.
+        # The message, then whatever the refusal offered to correct it with.
+        #
+        # @param result [Hash]
+        # @return [String]
+        def refusal_text(result)
+          hints = result.except(:error).compact_blank
+          return result[:error].to_s if hints.empty?
+
+          "#{result[:error]}\n#{JSON.generate(hints)}"
+        end
+
+        def text_for(result)
+          return result.to_s unless result.is_a?(Hash)
+
+          summary = result[:summary].presence
+          return JSON.generate(result) if summary.nil?
+          # The summary alone says what was done but not what it did it to,
+          # so a write answered "Orders cancel R1002" and the model had to
+          # fetch the order again to report the new status. Every other key
+          # travels with it.
+          return summary if result.keys == [:summary]
+
+          "#{summary}\n#{JSON.generate(result)}"
+        end
+      end
+    end
+  end
+end

data/lib/spree_mcp.rb

@@ -0,0 +1,21 @@
+require 'spree_core'
+require 'spree_api'
+require 'mcp'
+
+require 'spree/mcp/exports'
+require 'spree/mcp/tool_adapter'
+require 'spree/mcp/server'
+require 'spree/mcp/engine'
+
+module Spree
+  # A Model Context Protocol server for the Spree back office.
+  #
+  # A thin protocol adapter over {Spree.admin_agent_tools}: the tools, their schemas
+  # and the permissions gating them all live in `spree_core`, so this gem adds
+  # a transport and nothing else. Optional — an installation that does not
+  # want an MCP endpoint simply does not load it.
+  #
+  # See docs/plans/6.0-mcp-server.md.
+  module Mcp
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: spree_mcp
+version: !ruby/object:Gem::Version
+  version: 6.0.0.rc4
+platform: ruby
+authors:
+- Vendo Connect Inc.
+- Vendo Sp. z o.o.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: spree_core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 6.0.0.rc4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 6.0.0.rc4
+- !ruby/object:Gem::Dependency
+  name: spree_api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 6.0.0.rc4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 6.0.0.rc4
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: Mounts an MCP endpoint on the Spree Admin API so any MCP client can merchandise
+  the catalog, query reports and manage store setup in plain language, under the same
+  tenancy and permission rules as the API
+email: hello@spreecommerce.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/controllers/spree/api/v3/admin/mcp_controller.rb
+- config/routes.rb
+- lib/spree/mcp/engine.rb
+- lib/spree/mcp/exports.rb
+- lib/spree/mcp/server.rb
+- lib/spree/mcp/tool_adapter.rb
+- lib/spree_mcp.rb
+homepage: https://spreecommerce.org
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/spree/spree/issues
+  changelog_uri: https://github.com/spree/spree/releases/tag/v6.0.0.rc4
+  documentation_uri: https://docs.spreecommerce.org/
+  source_code_uri: https://github.com/spree/spree/tree/v6.0.0.rc4
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Model Context Protocol server for the Spree Admin API
+test_files: []