Serialize all paginated payloads through MCP serializers

`paginated_response` had two serialization branches: MCP serializers, and an `as_json(only: ...)` fast path used by three flat-payload tools that also leaked string keys into `structuredContent`. The fast path is gone: `list_groups`, `list_user_custom_fields` and the dormant `list_users` get from-scratch serializers (no `wraps` — the explicit `#attributes` hash keeps the allowlist property, PII allowlist included), and `Serializers::Base#to_h` now enforces the symbols-as-top-level-keys invariant so individual serializers cannot diverge (multiloc values keep their string locale keys).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: adessy

back/engines/commercial/mcp_server/app/lib/mcp_server/base_tool/pagination.rb

@@ -11,7 +11,7 @@ module McpServer::BaseTool::Pagination
     per_page: { type: 'integer', description: "Results per page (default: #{DEFAULT_PER_PAGE}, max: #{MAX_PER_PAGE})" }
   }.freeze
 
-  def paginated_response(label, scope, page: nil, per_page: nil, serializer: nil, params: {}, **json_options)
+  def paginated_response(label, scope, serializer:, page: nil, per_page: nil, params: {})
     page ||= 1
     per_page = (per_page || DEFAULT_PER_PAGE).to_i.clamp(1, MAX_PER_PAGE)
 
@@ -24,12 +24,8 @@ def paginated_response(label, scope, page: nil, per_page: nil, serializer: nil,
       total_pages: records.total_pages
     }
 
-    data = serializer ? serializer.serialize(records, params:) : records.as_json(**json_options)
-
-    structured_content = {
-      data: data,
-      pagination: pagination
-    }
+    data = serializer.serialize(records, params:)
+    structured_content = { data:, pagination: }
 
     summary = <<~TEXT.squish
       Found #{pagination[:total_count]} #{label}

back/engines/commercial/mcp_server/app/lib/mcp_server/serializers/base.rb

@@ -91,7 +91,13 @@ def to_h
         .index_by { it[:id] }
     end
 
-    collection? ? records.map { attributes(it) } : attributes(records.sole)
+    # Enforce the invariant that serializers return hashes with symbols as
+    # top-level keys (multiloc values keep their string locale keys).
+    if collection?
+      records.map { attributes(it).symbolize_keys }
+    else
+      attributes(records.sole).symbolize_keys
+    end
   end
 
   def attributes(record)

back/engines/commercial/mcp_server/app/lib/mcp_server/serializers/group.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class McpServer::Serializers::Group < McpServer::Serializers::Base
+  def attributes(record)
+    record.slice(:id, :title_multiloc, :membership_type, :memberships_count)
+  end
+end

back/engines/commercial/mcp_server/app/lib/mcp_server/serializers/user.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class McpServer::Serializers::User < McpServer::Serializers::Base
+  def attributes(record)
+    record.slice(:id, :first_name, :last_name, :email, :roles)
+  end
+end

back/engines/commercial/mcp_server/app/lib/mcp_server/serializers/user_custom_field.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Registration (user profile) fields. Not to be confused with Serializers::CustomField,
+# which serializes form fields (options and matrix statements inlined).
+class McpServer::Serializers::UserCustomField < McpServer::Serializers::Base
+  def attributes(record)
+    record.slice(:id, :title_multiloc, :input_type, :code, :required)
+  end
+end

back/engines/commercial/mcp_server/app/lib/mcp_server/tools/list_groups.rb

@@ -23,7 +23,7 @@ def run
         'groups',
         scope.order_new,
         **params.slice(:page, :per_page),
-        only: %i[id title_multiloc membership_type memberships_count]
+        serializer: McpServer::Serializers::Group
       )
     end
   end

back/engines/commercial/mcp_server/app/lib/mcp_server/tools/list_user_custom_fields.rb

@@ -12,7 +12,7 @@ def run
         'user custom fields',
         CustomField.registration.enabled.not_hidden.order(:ordering),
         **params.slice(:page, :per_page),
-        only: %i[id title_multiloc input_type code required]
+        serializer: McpServer::Serializers::UserCustomField
       )
     end
   end

back/engines/commercial/mcp_server/app/lib/mcp_server/tools/list_users.rb

@@ -26,7 +26,7 @@ def run
         'users',
         scope,
         **params.slice(:page, :per_page),
-        only: %i[id first_name last_name email roles]
+        serializer: McpServer::Serializers::User
       )
     end
   end

back/engines/commercial/mcp_server/spec/lib/mcp_server/base_tool/pagination_spec.rb

@@ -6,59 +6,60 @@
   subject(:host) { Class.new { include McpServer::BaseTool::Pagination }.new }
 
   let_it_be(:areas) { create_list(:area, 3) }
+  let_it_be(:current_user) { create(:super_admin) }
 
   let(:scope) { Area.order(:ordering) }
 
   def paginate(**options)
-    host.paginated_response('areas', scope, page: nil, per_page: nil, **options)
+    host.paginated_response(
+      'areas', scope,
+      page: nil, per_page: nil,
+      serializer: McpServer::Serializers::Area, params: { current_user: },
+      **options
+    )
   end
 
   it 'returns the data and pagination envelope with defaults' do
     response = paginate
 
     expect(response).not_to be_error
-    expect(response.structured_content[:data].size).to eq(3)
-    expect(response.structured_content[:pagination]).to eq(
-      page: 1,
-      per_page: described_class::DEFAULT_PER_PAGE,
-      total_count: 3,
-      total_pages: 1
+    expect(response.structured_content).to match(
+      data: have_attributes(size: 3),
+      pagination: {
+        page: 1,
+        per_page: described_class::DEFAULT_PER_PAGE,
+        total_count: 3,
+        total_pages: 1
+      }
     )
   end
 
   it 'summarizes the result in the text block' do
-    response = paginate
-
-    expect(response.content.first[:text])
+    expect(paginate.content.first[:text])
       .to include('Found 3 areas (showing page 1, 20 per page)')
   end
 
   it 'serves subsequent pages' do
     response = paginate(page: 2, per_page: 2)
 
-    expect(response.structured_content[:data].size).to eq(1)
-    expect(response.structured_content[:pagination]).to eq(
-      page: 2, per_page: 2, total_count: 3, total_pages: 2
+    expect(response.structured_content).to match(
+      data: have_attributes(size: 1),
+      pagination: { page: 2, per_page: 2, total_count: 3, total_pages: 2 }
     )
   end
 
   it 'clamps per_page between 1 and MAX_PER_PAGE' do
-    expect(paginate(per_page: 999).structured_content.dig(:pagination, :per_page))
-      .to eq(described_class::MAX_PER_PAGE)
-    expect(paginate(per_page: 0).structured_content.dig(:pagination, :per_page))
-      .to eq(1)
-  end
-
-  it 'serializes with as_json options when no serializer is given' do
-    response = paginate(only: %i[id])
+    per_page = paginate(per_page: 999).structured_content.dig(:pagination, :per_page)
+    expect(per_page).to eq(described_class::MAX_PER_PAGE)
 
-    expect(response.structured_content[:data]).to match_array(areas.map { |a| { 'id' => a.id } })
+    per_page = paginate(per_page: 0).structured_content.dig(:pagination, :per_page)
+    expect(per_page).to eq(1)
   end
 
-  it 'serializes with the given MCP serializer' do
-    response = paginate(serializer: McpServer::Serializers::Area, params: { current_user: create(:super_admin) })
+  it 'serializes the records with the given serializer' do
+    response = paginate
 
-    expect(response.structured_content[:data].pluck(:id)).to eq(scope.pluck(:id))
-    expect(response.structured_content[:data].first).to include(:title_multiloc)
+    expect(response.structured_content[:data])
+      .to eq(McpServer::Serializers::Area.serialize(scope, params: { current_user: }))
   end
 end

back/engines/commercial/mcp_server/spec/lib/mcp_server/serializers/base_spec.rb

@@ -2,74 +2,135 @@
 
 require 'rails_helper'
 
+# Tested through anonymous serializers that declare exactly the feature under test,
+# so this spec depends on no domain serializer. Integration with the real web
+# serializers is covered by the tool specs.
 describe McpServer::Serializers::Base do
-  let_it_be(:current_user) { create(:super_admin) }
+  let_it_be(:record) { create(:custom_field_select, :with_options) }
 
-  describe 'wrapping a web API serializer' do
-    it 'flattens the JSONAPI output into a plain hash' do
-      project = create(:project)
+  describe '.serialize' do
+    let(:serializer) do
+      Class.new(described_class) do
+        def attributes(record) = { id: record.id }
+      end
+    end
 
-      serialized = McpServer::Serializers::Project.serialize(project, params: { current_user: })
+    it 'returns a hash for a single record and an array for a relation' do
+      expect(serializer.serialize(record)).to be_a(Hash)
+      expect(serializer.serialize(CustomField.all)).to be_an(Array)
+    end
 
-      expect(serialized).to be_a(Hash)
-      expect(serialized[:id]).to eq(project.id)
-      expect(serialized[:title_multiloc]).to eq(project.title_multiloc)
-      expect(serialized).not_to include(:data, :attributes, :relationships)
+    it 'returns an empty array for an empty relation' do
+      expect(serializer.serialize(CustomField.none)).to eq([])
     end
+  end
 
-    it 'merges the click-through URLs when the serializer opts in' do
-      project = create(:project)
+  describe 'with a wrapped upstream serializer' do
+    before do
+      stub_const('UpstreamOptionSerializer', Class.new do
+        include JSONAPI::Serializer
+        set_type :option
+        attribute :option_title, &:title_multiloc
+      end)
+
+      stub_const('UpstreamSerializer', Class.new do
+        include JSONAPI::Serializer
+        set_type :probe
+        attribute :probe_title, &:title_multiloc
+        attribute(:echo) { |_record, params| params[:probe] }
+        has_many :options, serializer: UpstreamOptionSerializer
+      end)
+    end
 
-      serialized = McpServer::Serializers::Project.serialize(project, params: { current_user: })
+    let(:serializer) { Class.new(described_class) { wraps UpstreamSerializer } }
 
-      expect(serialized[:admin_url]).to end_with("/admin/projects/#{project.id}")
-      expect(serialized[:public_url]).to end_with("/projects/#{project.slug}")
+    it 'flattens the JSONAPI output into a plain hash' do
+      serialized = serializer.serialize(record)
+
+      expect(serialized).to match(
+        id: record.id,
+        probe_title: record.title_multiloc,
+        echo: nil,
+        option_ids: match_array(record.option_ids)
+      )
+    end
+
+    it 'serializes every record of a collection, in order' do
+      other_record = create(:custom_field)
+
+      serialized = serializer.serialize([record, other_record])
+
+      expect(serialized).to match([
+        a_hash_including(id: record.id, probe_title: record.title_multiloc),
+        a_hash_including(id: other_record.id, probe_title: other_record.title_multiloc)
+      ])
+    end
+
+    it 'forwards params to the upstream serializer' do
+      serialized = serializer.serialize(record, params: { probe: 'x' })
+
+      expect(serialized[:echo]).to eq('x')
     end
-  end
 
-  describe 'inline relationships' do
-    it 'embeds the related resources instead of exposing ids' do
-      field = create(:custom_field_select, :with_options)
+    it 'embeds relationships declared as inline instead of exposing ids' do
+      serializer = Class.new(described_class) do
+        wraps UpstreamSerializer
+        inline :options
+      end
 
-      serialized = McpServer::Serializers::CustomField.serialize(field)
+      serialized = serializer.serialize(record)
 
-      expect(serialized[:options]).to be_an(Array)
-      expect(serialized[:options].pluck(:id)).to match_array(field.options.pluck(:id))
-      expect(serialized[:options].first).to include(:title_multiloc)
       expect(serialized).not_to include(:option_ids)
+      expect(serialized[:options]).to match_array(
+        record.options.map { |option| { id: option.id, option_title: option.title_multiloc } }
+      )
     end
   end
 
-  describe 'building from scratch (no wraps)' do
-    it 'uses the #attributes override' do
-      permission = create(:permission)
+  describe 'with a from-scratch serializer (no wraps)' do
+    let(:serializer) do
+      Class.new(described_class) do
+        def attributes(record) = { 'id' => record.id, 'kind' => 'probe' }
+      end
+    end
 
-      serialized = McpServer::Serializers::Permission.serialize(permission)
+    it 'uses the #attributes override and symbolizes its top-level keys' do
+      serialized = serializer.serialize(record)
 
-      expect(serialized.keys).to eq(
-        %i[action permitted_by group_ids demographic_questions verification_expiry access_denied_explanation_multiloc]
-      )
+      expect(serialized).to match(id: record.id, kind: 'probe')
+    end
+
+    it 'exposes `params` to the #attributes override' do
+      serializer = Class.new(described_class) do
+        def attributes(_record) = { echo: params[:probe] }
+      end
+
+      serialized = serializer.serialize(record, params: { probe: 'x' })
+
+      expect(serialized).to eq(echo: 'x')
     end
 
     it 'raises when neither wraps nor #attributes is provided' do
       serializer = Class.new(described_class)
 
-      expect { serializer.serialize(create(:area)) }
+      expect { serializer.serialize(record) }
         .to raise_error(NotImplementedError, /wraps/)
     end
   end
 
-  describe 'collection semantics' do
-    it 'returns an array for a relation and a hash for a single record' do
-      create_list(:area, 2)
-      params = { current_user: }
+  describe '#urls' do
+    it 'returns the admin and public URLs of the record' do
+      project = create(:project)
+      serializer = Class.new(described_class) do
+        def attributes(record) = urls(record)
+      end
 
-      expect(McpServer::Serializers::Area.serialize(Area.all, params:)).to be_an(Array)
-      expect(McpServer::Serializers::Area.serialize(Area.first, params:)).to be_a(Hash)
-    end
+      serialized = serializer.serialize(project)
 
-    it 'returns an empty array for an empty relation' do
-      expect(McpServer::Serializers::Area.serialize(Area.none)).to eq([])
+      expect(serialized).to match(
+        admin_url: end_with("/admin/projects/#{project.id}"),
+        public_url: end_with("/projects/#{project.slug}")
+      )
     end
   end
 end