modelcontextprotocol/ruby-sdk
Watch
1
0
Fork
You've already forked ruby-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add _meta field to resource, content, and result classes

Browse source 
## Motivation and Context

MCP 2025-11-25 spec defines a `_meta` general field on many types,
but the Ruby SDK only exposed it on `Tool` and `Prompt`.
To attach metadata (e.g. MCP Apps CSP hints on resource contents),
consumers had to subclass existing classes and override `to_h`.

Add a `meta:` keyword argument and `_meta` serialization to:

- `Resource::Contents`, `Resource::TextContents`, `Resource::BlobContents`
- `Resource`, `ResourceTemplate`
- `Content::Text`, `Content::Image`, `Content::Audio`, `Content::EmbeddedResource`
- `Tool::Response` (`CallToolResult`)
- `Prompt::Result` (`GetPromptResult`)

This aligns the Ruby SDK with the Python and TypeScript SDKs, which both expose `_meta` on these types.

Resolves #308.

## How Has This Been Tested?

Added unit tests for each updated class covering two patterns: `_meta` present
(asserts the value is reflected in `to_h[:_meta]`) and `_meta` omitted
(asserts no `:_meta` key in `to_h`, i.e., `.compact` behavior).
All existing tests continue to pass, and `rake rubocop` is clean.

## Breaking Changes

None. All new `meta:` parameters are optional keyword arguments defaulting to `nil`.
The `to_h` output stays backward-compatible because `nil` values are removed by the existing `.compact` call,
so existing callers require no changes.
This commit is contained in:
Koichi ITO 2026-04-11 14:24:00 +09:00
commit 0ad9a89d97
12 changed files with 269 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

28
lib/mcp/content.rb
View file

@ -3,56 +3,60 @@
module MCP
module Content
class Text
attr_reader :text, :annotations
attr_reader :text, :annotations, :meta
def initialize(text, annotations: nil)
def initialize(text, annotations: nil, meta: nil)
@text = text
@annotations = annotations
@meta = meta
end
def to_h
{ text: text, annotations: annotations, type: "text" }.compact
{ text: text, annotations: annotations, _meta: meta, type: "text" }.compact
end
end
class Image
attr_reader :data, :mime_type, :annotations
attr_reader :data, :mime_type, :annotations, :meta
def initialize(data, mime_type, annotations: nil)
def initialize(data, mime_type, annotations: nil, meta: nil)
@data = data
@mime_type = mime_type
@annotations = annotations
@meta = meta
end
def to_h
{ data: data, mimeType: mime_type, annotations: annotations, type: "image" }.compact
{ data: data, mimeType: mime_type, annotations: annotations, _meta: meta, type: "image" }.compact
end
end
class Audio
attr_reader :data, :mime_type, :annotations
attr_reader :data, :mime_type, :annotations, :meta
def initialize(data, mime_type, annotations: nil)
def initialize(data, mime_type, annotations: nil, meta: nil)
@data = data
@mime_type = mime_type
@annotations = annotations
@meta = meta
end
def to_h
{ data: data, mimeType: mime_type, annotations: annotations, type: "audio" }.compact
{ data: data, mimeType: mime_type, annotations: annotations, _meta: meta, type: "audio" }.compact
end
end
class EmbeddedResource
attr_reader :resource, :annotations
attr_reader :resource, :annotations, :meta
def initialize(resource, annotations: nil)
def initialize(resource, annotations: nil, meta: nil)
@resource = resource
@annotations = annotations
@meta = meta
end
def to_h
{ resource: resource.to_h, annotations: annotations, type: "resource" }.compact
{ resource: resource.to_h, annotations: annotations, _meta: meta, type: "resource" }.compact
end
end
end

7
lib/mcp/prompt/result.rb
View file

@ -3,15 +3,16 @@
module MCP
class Prompt
class Result
attr_reader :description, :messages
attr_reader :description, :messages, :meta
def initialize(description: nil, messages: [])
def initialize(description: nil, messages: [], meta: nil)
@description = description
@messages = messages
@meta = meta
end
def to_h
{ description: description, messages: messages.map(&:to_h) }.compact
{ description: description, messages: messages.map(&:to_h), _meta: meta }.compact
end
end
end

6
lib/mcp/resource.rb
View file

@ -5,15 +5,16 @@ require_relative "resource/embedded"
module MCP
class Resource
attr_reader :uri, :name, :title, :description, :icons, :mime_type
attr_reader :uri, :name, :title, :description, :icons, :mime_type, :meta
def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil)
def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
@uri = uri
@name = name
@title = title
@description = description
@icons = icons
@mime_type = mime_type
@meta = meta
end
def to_h
@ -24,6 +25,7 @@ module MCP
description: description,
icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
mimeType: mime_type,
_meta: meta,
}.compact
end
end

15
lib/mcp/resource/contents.rb
View file

@ -3,23 +3,24 @@
module MCP
class Resource
class Contents
attr_reader :uri, :mime_type
attr_reader :uri, :mime_type, :meta
def initialize(uri:, mime_type: nil)
def initialize(uri:, mime_type: nil, meta: nil)
@uri = uri
@mime_type = mime_type
@meta = meta
end
def to_h
{ uri: uri, mimeType: mime_type }.compact
{ uri: uri, mimeType: mime_type, _meta: meta }.compact
end
end
class TextContents < Contents
attr_reader :text
def initialize(text:, uri:, mime_type:)
super(uri: uri, mime_type: mime_type)
def initialize(text:, uri:, mime_type:, meta: nil)
super(uri: uri, mime_type: mime_type, meta: meta)
@text = text
end
@ -31,8 +32,8 @@ module MCP
class BlobContents < Contents
attr_reader :data
def initialize(data:, uri:, mime_type:)
super(uri: uri, mime_type: mime_type)
def initialize(data:, uri:, mime_type:, meta: nil)
super(uri: uri, mime_type: mime_type, meta: meta)
@data = data
end

6
lib/mcp/resource_template.rb
View file

@ -2,15 +2,16 @@
module MCP
class ResourceTemplate
attr_reader :uri_template, :name, :title, :description, :icons, :mime_type
attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :meta
def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil)
def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
@uri_template = uri_template
@name = name
@title = title
@description = description
@icons = icons
@mime_type = mime_type
@meta = meta
end
def to_h
@ -21,6 +22,7 @@ module MCP
description: description,
icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
mimeType: mime_type,
_meta: meta,
}.compact
end
end

7
lib/mcp/tool/response.rb
View file

@ -5,9 +5,9 @@ module MCP
class Response
NOT_GIVEN = Object.new.freeze
attr_reader :content, :structured_content
attr_reader :content, :structured_content, :meta
def initialize(content = nil, deprecated_error = NOT_GIVEN, error: false, structured_content: nil)
def initialize(content = nil, deprecated_error = NOT_GIVEN, error: false, structured_content: nil, meta: nil)
if deprecated_error != NOT_GIVEN
warn("Passing `error` with the 2nd argument of `Response.new` is deprecated. Use keyword argument like `Response.new(content, error: error)` instead.", uplevel: 1)
error = deprecated_error
@ -16,6 +16,7 @@ module MCP
@content = content || []
@error = error
@structured_content = structured_content
@meta = meta
end
def error?
@ -23,7 +24,7 @@ module MCP
end
def to_h
{ content: content, isError: error?, structuredContent: @structured_content }.compact
{ content: content, isError: error?, structuredContent: @structured_content, _meta: meta }.compact
end
end
end

72
test/mcp/content_test.rb
View file

@ -28,6 +28,19 @@ module MCP
refute result.key?(:annotations)
end
test "#to_h with meta" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
image = Image.new("base64data", "image/png", meta: meta)
assert_equal meta, image.to_h[:_meta]
end
test "#to_h without meta omits the key" do
image = Image.new("base64data", "image/png")
refute image.to_h.key?(:_meta)
end
end
class AudioTest < ActiveSupport::TestCase
@ -53,6 +66,19 @@ module MCP
refute result.key?(:annotations)
end
test "#to_h with meta" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
audio = Audio.new("base64data", "audio/wav", meta: meta)
assert_equal meta, audio.to_h[:_meta]
end
test "#to_h without meta omits the key" do
audio = Audio.new("base64data", "audio/wav")
refute audio.to_h.key?(:_meta)
end
end
class EmbeddedResourceTest < ActiveSupport::TestCase
@ -92,6 +118,52 @@ module MCP
refute result.key?(:annotations)
end
test "#to_h with meta" do
resource = Object.new
def resource.to_h
{ uri: "test://x" }
end
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
embedded = EmbeddedResource.new(resource, meta: meta)
assert_equal meta, embedded.to_h[:_meta]
end
test "#to_h without meta omits the key" do
resource = Object.new
def resource.to_h
{ uri: "test://x" }
end
embedded = EmbeddedResource.new(resource)
refute embedded.to_h.key?(:_meta)
end
end
class TextTest < ActiveSupport::TestCase
test "#to_h returns correct format per MCP spec" do
text = Text.new("hello")
result = text.to_h
assert_equal "text", result[:type]
assert_equal "hello", result[:text]
end
test "#to_h with meta" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
text = Text.new("hello", meta: meta)
assert_equal meta, text.to_h[:_meta]
end
test "#to_h without meta omits the key" do
text = Text.new("hello")
refute text.to_h.key?(:_meta)
end
end
end
end

41
test/mcp/prompt/result_test.rb Normal file
View file

@ -0,0 +1,41 @@
# frozen_string_literal: true
require "test_helper"
module MCP
class Prompt
class ResultTest < ActiveSupport::TestCase
test "#to_h returns description and messages" do
result = Prompt::Result.new(
description: "a prompt",
messages: [Prompt::Message.new(role: "user", content: Content::Text.new("hi"))],
)
hash = result.to_h
assert_equal "a prompt", hash[:description]
assert_equal 1, hash[:messages].size
end
test "#to_h includes _meta when present" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
result = Prompt::Result.new(
description: "a prompt",
messages: [Prompt::Message.new(role: "user", content: Content::Text.new("hi"))],
meta: meta,
)
assert_equal meta, result.to_h[:_meta]
end
test "#to_h omits _meta when nil" do
result = Prompt::Result.new(
description: "a prompt",
messages: [Prompt::Message.new(role: "user", content: Content::Text.new("hi"))],
)
refute result.to_h.key?(:_meta)
end
end
end
end

72
test/mcp/resource/contents_test.rb
View file

@ -70,6 +70,78 @@ module MCP
assert_equal({ uri: "test://binary", blob: "base64data" }, result)
refute result.key?(:mimeType)
end
test "Contents#to_h omits _meta when nil" do
contents = Resource::Contents.new(uri: "test://example", mime_type: "text/plain")
refute contents.to_h.key?(:_meta)
end
test "Contents#to_h includes _meta when present" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
contents = Resource::Contents.new(uri: "test://example", mime_type: "text/plain", meta: meta)
assert_equal meta, contents.to_h[:_meta]
end
test "TextContents#to_h includes _meta when present" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
text_contents = Resource::TextContents.new(
uri: "test://text",
mime_type: "text/plain",
text: "Hello",
meta: meta,
)
result = text_contents.to_h
assert_equal meta, result[:_meta]
assert_equal "Hello", result[:text]
end
test "TextContents#to_h omits _meta when nil" do
text_contents = Resource::TextContents.new(
uri: "test://text",
mime_type: "text/plain",
text: "Hello",
)
refute text_contents.to_h.key?(:_meta)
end
test "BlobContents#to_h includes _meta when present" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
blob_contents = Resource::BlobContents.new(
uri: "test://binary",
mime_type: "image/png",
data: "base64data",
meta: meta,
)
result = blob_contents.to_h
assert_equal meta, result[:_meta]
assert_equal "base64data", result[:blob]
end
test "BlobContents#to_h omits _meta when nil" do
blob_contents = Resource::BlobContents.new(
uri: "test://binary",
mime_type: "image/png",
data: "base64data",
)
refute blob_contents.to_h.key?(:_meta)
end
test "Contents#to_h preserves empty _meta hash" do
contents = Resource::Contents.new(uri: "test://example", mime_type: "text/plain", meta: {})
result = contents.to_h
assert result.key?(:_meta)
assert_equal({}, result[:_meta])
end
end
end
end

17
test/mcp/resource_template_test.rb
View file

@ -36,5 +36,22 @@ module MCP
assert_equal expected_icons, resource_template.to_h[:icons]
end
test "#to_h omits _meta when nil" do
resource_template = ResourceTemplate.new(uri_template: "file:///{path}", name: "template_without_meta")
refute resource_template.to_h.key?(:_meta)
end
test "#to_h includes _meta when present" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
resource_template = ResourceTemplate.new(
uri_template: "file:///{path}",
name: "template_with_meta",
meta: meta,
)
assert_equal meta, resource_template.to_h[:_meta]
end
end
end

13
test/mcp/resource_test.rb
View file

@ -36,5 +36,18 @@ module MCP
assert_equal expected_icons, resource.to_h[:icons]
end
test "#to_h omits _meta when nil" do
resource = Resource.new(uri: "file:///test.txt", name: "resource_without_meta")
refute resource.to_h.key?(:_meta)
end
test "#to_h includes _meta when present" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
resource = Resource.new(uri: "file:///test.txt", name: "resource_with_meta", meta: meta)
assert_equal meta, resource.to_h[:_meta]
end
end
end

14
test/mcp/tool/response_test.rb
View file

@ -122,6 +122,20 @@ module MCP
assert_equal structured_content, actual[:structuredContent]
refute actual[:isError]
end
test "#to_h includes _meta when present" do
meta = { "application/vnd.ant.mcp-app" => { "csp" => "default-src 'self'" } }
response = Response.new([{ type: "text", text: "ok" }], meta: meta)
actual = response.to_h
assert_equal meta, actual[:_meta]
end
test "#to_h omits _meta when nil" do
response = Response.new([{ type: "text", text: "ok" }])
refute response.to_h.key?(:_meta)
end
end
end
end