Skip to content

Commit 8f6a206

Browse files
authored
Merge pull request #649 from koic/recognize_a_root_dynamic_ref_when_defaulting_an_output_schema
Recognize a root $dynamicRef when defaulting an output schema to an object
2 parents 3b2c60b + 0c8ed8d commit 8f6a206

4 files changed

Lines changed: 75 additions & 5 deletions

File tree

‎docs/_server/tools.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -265,7 +265,8 @@ end
265265
```
266266

267267
Please note: in this case, you must provide `type: "array"`. The default type for output schemas is `object`,
268-
applied only when the schema declares no root keyword (`type`, `$ref`, `oneOf`, `anyOf`, `allOf`, `not`, `if`, `const`, `enum`).
268+
applied only when the schema declares none of these root keywords:
269+
`type`, `$ref`, `$dynamicRef`, `oneOf`, `anyOf`, `allOf`, `not`, `if`, `const`, `enum`.
269270

270271
Per SEP-2106, an output schema may be any valid JSON Schema 2020-12 document, including a primitive root
271272
(`{ type: "string" }`) or a root-level composition:
@@ -283,7 +284,7 @@ end
283284

284285
Input schemas keep `type: "object"` at the root but accept the full 2020-12 vocabulary below it
285286
(`$defs`/`$ref`, `oneOf`/`anyOf`/`allOf`/`not`, `if`/`then`/`else`). Two resource bounds apply to
286-
all tool schemas: only same-document `$ref`s (starting with `#`) are accepted, and documents are
287+
all tool schemas: only same-document `$ref` and `$dynamicRef` values (starting with `#`) are accepted, and documents are
287288
capped at `MCP::Tool::Schema::MAX_SCHEMA_DEPTH` nesting levels and `MCP::Tool::Schema::MAX_SUBSCHEMA_COUNT` subschema objects;
288289
violations raise `ArgumentError` at construction time.
289290

‎lib/mcp/tool/output_schema.rb‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ class Tool
77
class OutputSchema < Schema
88
class ValidationError < StandardError; end
99

10-
# Root-level keywords whose presence means the user already chose a root schema shape,
11-
# so no `type: "object"` default should be merged in.
12-
ROOT_SCHEMA_KEYWORDS = [:type, :"$ref", :oneOf, :anyOf, :allOf, :not, :if, :const, :enum].freeze
10+
# Root-level keywords whose presence means the user already chose a root schema shape, so no `type: "object"`
11+
# default should be merged in. Both reference keywords count, since a root `$dynamicRef` names the shape as
12+
# a root `$ref` does; they come from `Schema` so that this list cannot drift from the same-document check.
13+
ROOT_SCHEMA_KEYWORDS = [:type, *REFERENCE_KEYWORDS, :oneOf, :anyOf, :allOf, :not, :if, :const, :enum].freeze
1314

1415
def validate_result(result)
1516
errors = fully_validate(result)

‎test/mcp/server_test.rb‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3206,6 +3206,35 @@ def read_resource_request(uri)
32063206
assert_equal({ result: "success" }, response[:result][:structuredContent])
32073207
end
32083208

3209+
test "tools/call validates structuredContent against an output schema whose root is a $dynamicRef" do
3210+
tool = Tool.define(
3211+
name: "dynamic_ref_tool",
3212+
output_schema: {
3213+
"$dynamicRef": "#vector",
3214+
"$defs": { vector: { "$dynamicAnchor": "vector", type: "array", items: { type: "number" } } },
3215+
},
3216+
) do
3217+
Tool::Response.new([{ type: "text", text: "[1, 2]" }], structured_content: [1, 2])
3218+
end
3219+
server = Server.new(
3220+
tools: [tool],
3221+
configuration: Configuration.new(validate_tool_call_results: true),
3222+
)
3223+
3224+
listed = server.handle({ jsonrpc: "2.0", id: 1, method: "tools/list" })[:result][:tools].first
3225+
refute listed[:outputSchema].key?(:type)
3226+
3227+
response = server.handle({
3228+
jsonrpc: "2.0",
3229+
id: 2,
3230+
method: "tools/call",
3231+
params: { name: "dynamic_ref_tool" },
3232+
})
3233+
3234+
assert_nil response[:error]
3235+
assert_equal [1, 2], response[:result][:structuredContent]
3236+
end
3237+
32093238
test "tools/call returns JSON-RPC error for invalid structuredContent when output schema validation is enabled" do
32103239
tool = Tool.define(
32113240
name: "invalid_structured_content_tool",

‎test/mcp/tool/output_schema_test.rb‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,45 @@ class OutputSchemaTest < ActiveSupport::TestCase
238238
assert_raises(OutputSchema::ValidationError) { schema.validate_result(42) }
239239
end
240240

241+
test "does not inject a root type into a root-level $dynamicRef schema" do
242+
# `Schema` restricts `$ref` and `$dynamicRef` alike, and the root default has to know both: with the object default merged in,
243+
# this schema advertised `type: "object"` and rejected the array it describes.
244+
schema = OutputSchema.new(
245+
"$dynamicRef": "#vector",
246+
"$defs": { vector: { "$dynamicAnchor": "vector", type: "array", items: { type: "number" } } },
247+
)
248+
249+
refute schema.to_h.key?(:type)
250+
assert_equal "#vector", schema.to_h[:"$dynamicRef"]
251+
assert_nothing_raised { schema.validate_result([1, 2]) }
252+
assert_raises(OutputSchema::ValidationError) { schema.validate_result(["bad"]) }
253+
assert_raises(OutputSchema::ValidationError) { schema.validate_result({}) }
254+
assert_empty MCP::Tool::Schema::REFERENCE_KEYWORDS - OutputSchema::ROOT_SCHEMA_KEYWORDS
255+
end
256+
257+
test "keeps an explicit type beside a root-level $dynamicRef" do
258+
schema = OutputSchema.new(
259+
type: "array",
260+
"$dynamicRef": "#vector",
261+
"$defs": { vector: { "$dynamicAnchor": "vector", items: { type: "number" } } },
262+
)
263+
264+
assert_equal "array", schema.to_h[:type]
265+
assert_nothing_raised { schema.validate_result([1, 2]) }
266+
assert_raises(OutputSchema::ValidationError) { schema.validate_result("text") }
267+
end
268+
269+
test "does not inject a root type into a root-level $dynamicRef schema given with String keys" do
270+
schema = OutputSchema.new(
271+
"$dynamicRef" => "#scalar",
272+
"$defs" => { "scalar" => { "$dynamicAnchor" => "scalar", "type" => "string" } },
273+
)
274+
275+
refute schema.to_h.key?(:type)
276+
assert_nothing_raised { schema.validate_result("text") }
277+
assert_raises(OutputSchema::ValidationError) { schema.validate_result(42) }
278+
end
279+
241280
test "allows primitive root schemas" do
242281
schema = OutputSchema.new(type: "string")
243282

0 commit comments

Comments
 (0)