Skip to content

Commit 99cbefc

Browse files
koickoic
committed
Allow $ref in Tool::Schema for protocol version 2025-11-25
`Tool::Schema` rejected `$ref` with an `ArgumentError`. Earlier MCP spec versions (2024-11-05 through 2025-06-18) did not define a JSON Schema dialect or reference the `$ref` keyword. `inputSchema` was described only as "JSON Schema defining expected parameters" with no further constraints: - https://modelcontextprotocol.io/specification/2024-11-05/server/tools - https://modelcontextprotocol.io/specification/2025-06-18/server/tools The MCP spec 2025-11-25 introduced a "JSON Schema Usage" section that adopts JSON Schema 2020-12 as the default dialect. Since `$ref` is a core keyword in 2020-12, it is now allowed for protocol version 2025-11-25 and later. - https://modelcontextprotocol.io/specification/2025-11-25/basic#json-schema-usage - https://modelcontextprotocol.io/specification/2025-11-25/server/tools - https://json-schema.org/draft/2020-12/release-notes For backward compatibility with older protocol versions (2025-06-18 and earlier), `Server#validate!` continues to raise `ArgumentError` when a tool input schema contains `$ref`. This preserves the existing behavior for servers targeting those spec versions.
1 parent 5b04089 commit 99cbefc

File tree

6 files changed

+133
-34
lines changed

6 files changed

+133
-34
lines changed

‎lib/mcp/server.rb‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,14 @@ def validate!
219219
message = "Error occurred in server_info. `description` is not supported in protocol version 2025-06-18 or earlier"
220220
raise ArgumentError, message
221221
end
222+
223+
tools_with_ref = @tools.each_with_object([]) do |(tool_name, tool), names|
224+
names << tool_name if schema_contains_ref?(tool.input_schema_value.to_h)
225+
end
226+
unless tools_with_ref.empty?
227+
message = "Error occurred in #{tools_with_ref.join(", ")}. `$ref` in input schemas is supported by protocol version 2025-11-25 or higher"
228+
raise ArgumentError, message
229+
end
222230
end
223231

224232
if @configuration.protocol_version <= "2025-03-26"
@@ -259,6 +267,17 @@ def validate_tool_name!
259267
raise ToolNotUnique, duplicated_tool_names unless duplicated_tool_names.empty?
260268
end
261269

270+
def schema_contains_ref?(schema)
271+
case schema
272+
when Hash
273+
schema.any? { |key, value| key.to_s == "$ref" || schema_contains_ref?(value) }
274+
when Array
275+
schema.any? { |element| schema_contains_ref?(element) }
276+
else
277+
false
278+
end
279+
end
280+
262281
def handle_request(request, method)
263282
handler = @handlers[method]
264283
unless handler

‎lib/mcp/tool/schema.rb‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,6 @@ def deep_transform_keys(schema, &block)
3131
case schema
3232
when Hash
3333
schema.each_with_object({}) do |(key, value), result|
34-
if key.casecmp?("$ref")
35-
raise ArgumentError, "Invalid JSON Schema: $ref is not allowed in tool schemas"
36-
end
37-
3834
result[yield(key)] = deep_transform_keys(value, &block)
3935
end
4036
when Array

‎test/mcp/server_test.rb‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1184,6 +1184,44 @@ class Example < Tool
11841184
assert_equal("Error occurred in Test resource. `title` is not supported in protocol version 2025-03-26 or earlier", exception.message)
11851185
end
11861186

1187+
test "allows `$ref` in tool input schema with protocol version 2025-11-25" do
1188+
tool = Tool.define(
1189+
name: "ref_tool",
1190+
description: "Tool with $ref",
1191+
input_schema: {
1192+
type: "object",
1193+
"$defs": { address: { type: "object", properties: { city: { type: "string" } } } },
1194+
properties: { address: { "$ref": "#/$defs/address" } },
1195+
},
1196+
)
1197+
configuration = Configuration.new(protocol_version: "2025-11-25")
1198+
1199+
assert_nothing_raised do
1200+
Server.new(name: "test_server", tools: [tool], configuration: configuration)
1201+
end
1202+
end
1203+
1204+
test "raises error if `$ref` in tool input schema is used with protocol version 2025-06-18" do
1205+
tool = Tool.define(
1206+
name: "ref_tool",
1207+
description: "Tool with $ref",
1208+
input_schema: {
1209+
type: "object",
1210+
"$defs": { address: { type: "object", properties: { city: { type: "string" } } } },
1211+
properties: { address: { "$ref": "#/$defs/address" } },
1212+
},
1213+
)
1214+
configuration = Configuration.new(protocol_version: "2025-06-18")
1215+
1216+
exception = assert_raises(ArgumentError) do
1217+
Server.new(name: "test_server", tools: [tool], configuration: configuration)
1218+
end
1219+
assert_equal(
1220+
"Error occurred in ref_tool. `$ref` in input schemas is supported by protocol version 2025-11-25 or higher",
1221+
exception.message,
1222+
)
1223+
end
1224+
11871225
test "raises error if `title` of resource template is used with protocol version 2025-03-26" do
11881226
configuration = Configuration.new(protocol_version: "2025-03-26")
11891227

‎test/mcp/tool/input_schema_test.rb‎

Lines changed: 35 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -92,16 +92,41 @@ class InputSchemaTest < ActiveSupport::TestCase
9292
end
9393
end
9494

95-
test "rejects schemas with $ref references" do
96-
assert_raises(ArgumentError) do
97-
InputSchema.new(properties: { foo: { "$ref" => "#/definitions/bar" } }, required: ["foo"])
98-
end
99-
end
100-
101-
test "rejects schemas with symbol $ref references" do
102-
assert_raises(ArgumentError) do
103-
InputSchema.new(properties: { foo: { :$ref => "#/definitions/bar" } }, required: ["foo"])
104-
end
95+
test "accepts schemas with $ref references" do
96+
schema = InputSchema.new(
97+
properties: {
98+
foo: { type: "string" },
99+
},
100+
definitions: {
101+
bar: { type: "string" },
102+
},
103+
required: ["foo"],
104+
)
105+
assert_includes schema.to_h.keys, :definitions
106+
end
107+
108+
test "accepts schemas with $ref string key and includes $ref in to_h" do
109+
schema = InputSchema.new({
110+
"properties" => {
111+
"foo" => { "$ref" => "#/definitions/bar" },
112+
},
113+
"definitions" => {
114+
"bar" => { "type" => "string" },
115+
},
116+
})
117+
assert_equal "#/definitions/bar", schema.to_h[:properties][:foo][:$ref]
118+
end
119+
120+
test "accepts schemas with $ref symbol key and includes $ref in to_h" do
121+
schema = InputSchema.new({
122+
properties: {
123+
foo: { :$ref => "#/definitions/bar" },
124+
},
125+
definitions: {
126+
bar: { type: "string" },
127+
},
128+
})
129+
assert_equal "#/definitions/bar", schema.to_h[:properties][:foo][:$ref]
105130
end
106131

107132
test "== compares two input schemas with the same properties, required fields" do

‎test/mcp/tool/output_schema_test.rb‎

Lines changed: 33 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -82,16 +82,41 @@ class OutputSchemaTest < ActiveSupport::TestCase
8282
end
8383
end
8484

85-
test "rejects schemas with $ref references" do
86-
assert_raises(ArgumentError) do
87-
OutputSchema.new(properties: { foo: { "$ref" => "#/definitions/bar" } }, required: ["foo"])
88-
end
85+
test "accepts schemas with $ref references" do
86+
schema = OutputSchema.new(
87+
properties: {
88+
foo: { type: "string" },
89+
},
90+
definitions: {
91+
bar: { type: "string" },
92+
},
93+
required: ["foo"],
94+
)
95+
assert_includes schema.to_h.keys, :definitions
8996
end
9097

91-
test "rejects schemas with symbol $ref references" do
92-
assert_raises(ArgumentError) do
93-
OutputSchema.new(properties: { foo: { :$ref => "#/definitions/bar" } }, required: ["foo"])
94-
end
98+
test "accepts schemas with $ref string key and includes $ref in to_h" do
99+
schema = OutputSchema.new({
100+
"properties" => {
101+
"foo" => { "$ref" => "#/definitions/bar" },
102+
},
103+
"definitions" => {
104+
"bar" => { "type" => "string" },
105+
},
106+
})
107+
assert_equal "#/definitions/bar", schema.to_h[:properties][:foo][:$ref]
108+
end
109+
110+
test "accepts schemas with $ref symbol key and includes $ref in to_h" do
111+
schema = OutputSchema.new({
112+
properties: {
113+
foo: { :$ref => "#/definitions/bar" },
114+
},
115+
definitions: {
116+
bar: { type: "string" },
117+
},
118+
})
119+
assert_equal "#/definitions/bar", schema.to_h[:properties][:foo][:$ref]
95120
end
96121

97122
test "== compares two output schemas with the same properties and required fields" do

‎test/mcp/tool_test.rb‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -320,7 +320,7 @@ def call(message, server_context: nil)
320320
assert_equal [{ type: "text", content: "OK" }], response.content
321321
end
322322

323-
test "input_schema rejects any $ref in schema" do
323+
test "input_schema accepts $ref in schema" do
324324
schema_with_ref = {
325325
properties: {
326326
foo: { "$ref" => "#/definitions/bar" },
@@ -330,12 +330,10 @@ def call(message, server_context: nil)
330330
bar: { type: "string" },
331331
},
332332
}
333-
error = assert_raises(ArgumentError) do
334-
Class.new(MCP::Tool) do
335-
input_schema schema_with_ref
336-
end
333+
tool_class = Class.new(MCP::Tool) do
334+
input_schema schema_with_ref
337335
end
338-
assert_match(/Invalid JSON Schema/, error.message)
336+
assert_equal "#/definitions/bar", tool_class.input_schema.to_h[:properties][:foo][:$ref]
339337
end
340338

341339
test "#to_h includes outputSchema when present" do
@@ -409,7 +407,7 @@ class OutputSchemaObjectTool < Tool
409407
assert_includes error.message, "string did not match the following type: number"
410408
end
411409

412-
test "output_schema rejects any $ref in schema" do
410+
test "output_schema accepts $ref in schema" do
413411
schema_with_ref = {
414412
properties: {
415413
foo: { "$ref" => "#/definitions/bar" },
@@ -419,12 +417,10 @@ class OutputSchemaObjectTool < Tool
419417
bar: { type: "string" },
420418
},
421419
}
422-
error = assert_raises(ArgumentError) do
423-
Class.new(MCP::Tool) do
424-
output_schema schema_with_ref
425-
end
420+
tool_class = Class.new(MCP::Tool) do
421+
output_schema schema_with_ref
426422
end
427-
assert_match(/Invalid JSON Schema/, error.message)
423+
assert_equal "#/definitions/bar", tool_class.output_schema.to_h[:properties][:foo][:$ref]
428424
end
429425

430426
test ".define allows definition of tools with output_schema" do

0 commit comments

Comments
 (0)