feat: pass _meta through resources/read path (#211)

Author: crisnahine

lib/action_mcp/content/resource.rb

@@ -9,7 +9,8 @@ class Resource < Base
       # @return [String] The MIME type of the resource.
       # @return [String, nil] The text content of the resource (optional).
       # @return [String, nil] The base64-encoded blob of the resource (optional).
-      attr_reader :uri, :mime_type, :text, :blob, :annotations
+      # @return [Hash, nil] Optional extension metadata (serialized on the wire as `_meta`).
+      attr_reader :uri, :mime_type, :text, :blob, :annotations, :meta
 
       # Initializes a new Resource content.
       #
@@ -18,24 +19,38 @@ class Resource < Base
       # @param text [String, nil] The text content of the resource (optional).
       # @param blob [String, nil] The base64-encoded blob of the resource (optional).
       # @param annotations [Hash, nil] Optional annotations for the resource.
-      def initialize(uri, mime_type = "text/plain", text: nil, blob: nil, annotations: nil)
+      # @param meta [Hash, #to_hash, #to_h, nil] Optional extension metadata. Emitted on the wire as `_meta`.
+      def initialize(uri, mime_type = "text/plain", text: nil, blob: nil, annotations: nil, meta: nil)
         super("resource", annotations: annotations)
         @uri = uri
         @mime_type = mime_type
         @text = text
         @blob = blob
         @annotations = annotations
+        @meta =
+          if meta.nil?
+            nil
+          elsif meta.respond_to?(:to_hash)
+            meta.to_hash
+          elsif meta.respond_to?(:to_h)
+            meta.to_h
+          else
+            raise ArgumentError, "meta must respond to :to_hash or :to_h, got: #{meta.class}"
+          end
       end
 
       # Returns a hash representation of the resource content.
       # Per MCP spec, embedded resources have type "resource" with a nested resource object.
+      # `meta` is emitted as `_meta` on the inner resource hash (TextResourceContents /
+      # BlobResourceContents), not on the outer content envelope.
       #
       # @return [Hash] The hash representation of the resource content.
       def to_h
         inner = { uri: @uri, mimeType: @mime_type }
         inner[:text] = @text if @text
         inner[:blob] = @blob if @blob
         inner[:annotations] = @annotations if @annotations
+        inner[:_meta] = @meta if @meta && !@meta.empty?
 
         { type: @type, resource: inner }
       end

lib/action_mcp/resource.rb

@@ -4,7 +4,7 @@ module ActionMCP
   # Represents a resource with its metadata.
   # Used by resources/list to describe concrete resources.
   class Resource
-    attr_reader :uri, :name, :title, :description, :mime_type, :size, :annotations
+    attr_reader :uri, :name, :title, :description, :mime_type, :size, :annotations, :meta
 
     # @param uri [String] The URI of the resource
     # @param name [String] Display name of the resource
@@ -13,14 +13,25 @@ class Resource
     # @param mime_type [String, nil] MIME type of the resource content
     # @param size [Integer, nil] Size of the resource in bytes
     # @param annotations [Hash, nil] Optional annotations
-    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil)
+    # @param meta [Hash, #to_hash, #to_h, nil] Optional extension metadata. Emitted on the wire as `_meta`.
+    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
       @mime_type = mime_type
       @size = size
       @annotations = annotations
+      @meta =
+        if meta.nil?
+          nil
+        elsif meta.respond_to?(:to_hash)
+          meta.to_hash
+        elsif meta.respond_to?(:to_h)
+          meta.to_h
+        else
+          raise ArgumentError, "meta must respond to :to_hash or :to_h, got: #{meta.class}"
+        end
       freeze
     end
 
@@ -35,6 +46,7 @@ def to_h
       hash[:mimeType] = mime_type if mime_type
       hash[:size] = size if size
       hash[:annotations] = annotations if annotations
+      hash[:_meta] = meta if meta && !meta.empty?
       hash
     end
 
@@ -46,12 +58,12 @@ def ==(other)
       other.is_a?(Resource) && uri == other.uri && name == other.name &&
         title == other.title && description == other.description &&
         mime_type == other.mime_type && size == other.size &&
-        annotations == other.annotations
+        annotations == other.annotations && meta == other.meta
     end
     alias eql? ==
 
     def hash
-      [ uri, name, title, description, mime_type, size, annotations ].hash
+      [ uri, name, title, description, mime_type, size, annotations, meta ].hash
     end
   end
 end

lib/action_mcp/resource_template.rb

@@ -156,16 +156,18 @@ def lists_resources?
       # @param mime_type [String, nil] Falls back to template mime_type
       # @param size [Integer, nil] Size in bytes
       # @param annotations [Hash, nil] Optional annotations
+      # @param meta [Hash, #to_hash, #to_h, nil] Optional extension metadata passed through to the Resource (emitted as `_meta`)
       # @return [ActionMCP::Resource]
-      def build_resource(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil)
+      def build_resource(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil, meta: nil)
         ActionMCP::Resource.new(
           uri: uri,
           name: name,
           title: title,
           description: description || @description,
           mime_type: mime_type || @mime_type,
           size: size,
-          annotations: annotations
+          annotations: annotations,
+          meta: meta
         )
       end
 

lib/action_mcp/server/resources.rb

@@ -163,13 +163,14 @@ def collect_resources(request_id)
 
       # Normalize a content object to MCP ReadResourceResult content shape.
       #
-      # @return [Hash] with keys: uri, mimeType, and text or blob
+      # @return [Hash] with keys: uri, mimeType, text or blob, and optional _meta
       def normalize_read_content(content, _uri)
         case content
         when ActionMCP::Content::Resource
           inner = { uri: content.uri, mimeType: content.mime_type }
           inner[:text] = content.text if content.text
           inner[:blob] = content.blob if content.blob
+          inner[:_meta] = content.meta if content.meta && !content.meta.empty?
           inner
         else
           content.respond_to?(:to_h) ? content.to_h : content

test/action_mcp/content_test.rb

@@ -80,6 +80,12 @@ class ContentTest < ActiveSupport::TestCase
         resource_full = Resource.new(uri, mime_type, text: text_content, blob: blob_content)
         expected_full = { type: "resource", resource: { uri: uri, mimeType: mime_type, text: text_content, blob: blob_content } }
         assert_equal expected_full, resource_full.to_h
+
+        # meta is emitted on the inner resource hash as `_meta`, not the outer envelope
+        meta = { ui: { prefersBorder: true } }
+        resource_with_meta = Resource.new(uri, mime_type, text: text_content, meta: meta)
+        assert_equal meta, resource_with_meta.to_h[:resource][:_meta]
+        refute resource_with_meta.to_h.key?(:_meta)
       end
 
       test "Resource content supports annotations" do

test/action_mcp/resource_template_test.rb

@@ -31,6 +31,17 @@ def self.name = "Test\#{SecureRandom.hex(6)}Template"
       end
     end
 
+    test "build_resource forwards meta to Resource" do
+      template = create_temp_template(uri_template: "meta://item/{id}", name: "MetaTemplate")
+      resource = template.build_resource(
+        uri: "meta://item/1",
+        name: "item 1",
+        meta: { ui: { prefersBorder: false } }
+      )
+
+      assert_equal({ ui: { prefersBorder: false } }, resource.meta)
+    end
+
     test "allows unique URI templates" do
       # Create temporary classes with unique templates
       create_temp_template(uri_template: "service://resource/{id}", name: "Template1")

test/action_mcp/resource_test.rb

@@ -12,7 +12,8 @@ class ResourceTest < ActiveSupport::TestCase
         description: "A test file",
         mime_type: "text/plain",
         size: 42,
-        annotations: { audience: [ "user" ] }
+        annotations: { audience: [ "user" ] },
+        meta: { ui: { prefersBorder: true } }
       )
 
       assert_equal "file:///test.txt", resource.uri
@@ -22,6 +23,8 @@ class ResourceTest < ActiveSupport::TestCase
       assert_equal "text/plain", resource.mime_type
       assert_equal 42, resource.size
       assert_equal({ audience: [ "user" ] }, resource.annotations)
+      assert_equal({ ui: { prefersBorder: true } }, resource.meta)
+      assert_equal({ ui: { prefersBorder: true } }, resource.to_h[:_meta])
     end
 
     test "creates resource with only required fields" do
@@ -58,6 +61,7 @@ class ResourceTest < ActiveSupport::TestCase
       hash = resource.to_h
 
       assert_equal({ uri: "file:///test.txt", name: "test.txt" }, hash)
+      refute hash.key?(:_meta)
     end
 
     test "to_h converts mime_type to mimeType" do
@@ -110,5 +114,21 @@ class ResourceTest < ActiveSupport::TestCase
       assert_equal "test.txt", parsed["name"]
       assert_equal "text/plain", parsed["mimeType"]
     end
+
+    test "rejects meta that is neither Hash-like nor nil" do
+      assert_raises(ArgumentError) do
+        Resource.new(uri: "file:///a", name: "a", meta: "bad")
+      end
+    end
+
+    test "accepts Hash-like meta via to_hash" do
+      hashlike = Class.new do
+        def to_hash = { ui: { prefersBorder: true } }
+      end.new
+
+      resource = Resource.new(uri: "file:///a", name: "a", meta: hashlike)
+      assert_equal({ ui: { prefersBorder: true } }, resource.meta)
+      assert_equal({ ui: { prefersBorder: true } }, resource.to_h[:_meta])
+    end
   end
 end

test/action_mcp/server/resources_test.rb

@@ -59,6 +59,16 @@ def self.readable_uri?(_uri) = false
         assert_equal "Resource not found", response[:error][:message]
         assert_equal({ uri: uri }, response[:error][:data])
       end
+
+      test "send_resource_read passes _meta through on contents" do
+        transport = TestTransport.new
+        transport.send_resource_read(101, { "uri" => "meta-echo://item/42" })
+
+        response = transport.responses.last
+        assert_nil response[:error]
+        content = response[:result][:contents].first
+        assert_equal({ ui: { prefersBorder: true } }, content[:_meta])
+      end
     end
   end
 end

test/dummy/app/mcp/resource_templates/meta_echo_template.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class MetaEchoTemplate < ApplicationMCPResTemplate
+  description "Echo resource that includes _meta in its content"
+  uri_template "meta-echo://item/{id}"
+  mime_type "application/json"
+
+  parameter :id, description: "Item identifier", required: true
+
+  def resolve
+    ActionMCP::Content::Resource.new(
+      "meta-echo://item/#{id}",
+      "application/json",
+      text: "{}",
+      meta: { ui: { prefersBorder: true } }
+    )
+  end
+end