From 0c8ed8d5b8af74cc62f08cbf3899e559a013066c Mon Sep 17 00:00:00 2001 From: Koichi ITO Date: Sun, 1 Nov 2026 22:14:23 +0900 Subject: [PATCH] Recognize a root $dynamicRef when defaulting an output schema to an object ## Motivation and Context An output schema whose root has none of the keywords in `ROOT_SCHEMA_KEYWORDS` is defaulted to `type: "object"`, which keeps the wire output of the common `properties`-only shape while SEP-2106 lets an output schema be any JSON Schema 2020-12 document. That list named `$ref` but not `$dynamicRef`, although `Tool::Schema` already treats both as the reference keywords it restricts to the same document. A schema whose root is a `$dynamicRef` to an array or a primitive was therefore advertised with an extra `type: "object"` and rejected its own valid results: with result validation on, `tools/call` answered -32603 where the same schema written with `$ref` passed. The list now takes both reference keywords from `Tool::Schema::REFERENCE_KEYWORDS`, so the two cannot drift apart again, and the tools page names `$dynamicRef` among the keywords that keep the default off and beside `$ref` in the same-document rule, which the code has always applied to both. Closes #647 ## How Has This Been Tested? test/mcp/tool/output_schema_test.rb and test/mcp/server_test.rb. Before the fix, the `$dynamicRef` root schema gained `type: "object"` in `to_h` and in the `tools/list` entry, `validate_result([1, 2])` raised "value at root is not an object", and `tools/call` answered -32603 "Internal error". ## Breaking Changes None. A schema whose root is a `$dynamicRef` is now advertised as written; every other root shape is unchanged. --- docs/_server/tools.md | 5 ++-- lib/mcp/tool/output_schema.rb | 7 +++--- test/mcp/server_test.rb | 29 +++++++++++++++++++++ test/mcp/tool/output_schema_test.rb | 39 +++++++++++++++++++++++++++++ 4 files changed, 75 insertions(+), 5 deletions(-) diff --git a/docs/_server/tools.md b/docs/_server/tools.md index e5902bef..021d52e4 100644 --- a/docs/_server/tools.md +++ b/docs/_server/tools.md @@ -265,7 +265,8 @@ end ``` Please note: in this case, you must provide `type: "array"`. The default type for output schemas is `object`, -applied only when the schema declares no root keyword (`type`, `$ref`, `oneOf`, `anyOf`, `allOf`, `not`, `if`, `const`, `enum`). +applied only when the schema declares none of these root keywords: +`type`, `$ref`, `$dynamicRef`, `oneOf`, `anyOf`, `allOf`, `not`, `if`, `const`, `enum`. Per SEP-2106, an output schema may be any valid JSON Schema 2020-12 document, including a primitive root (`{ type: "string" }`) or a root-level composition: @@ -283,7 +284,7 @@ end Input schemas keep `type: "object"` at the root but accept the full 2020-12 vocabulary below it (`$defs`/`$ref`, `oneOf`/`anyOf`/`allOf`/`not`, `if`/`then`/`else`). Two resource bounds apply to -all tool schemas: only same-document `$ref`s (starting with `#`) are accepted, and documents are +all tool schemas: only same-document `$ref` and `$dynamicRef` values (starting with `#`) are accepted, and documents are capped at `MCP::Tool::Schema::MAX_SCHEMA_DEPTH` nesting levels and `MCP::Tool::Schema::MAX_SUBSCHEMA_COUNT` subschema objects; violations raise `ArgumentError` at construction time. diff --git a/lib/mcp/tool/output_schema.rb b/lib/mcp/tool/output_schema.rb index 1d6e2a58..6d1c674d 100644 --- a/lib/mcp/tool/output_schema.rb +++ b/lib/mcp/tool/output_schema.rb @@ -7,9 +7,10 @@ class Tool class OutputSchema < Schema class ValidationError < StandardError; end - # Root-level keywords whose presence means the user already chose a root schema shape, - # so no `type: "object"` default should be merged in. - ROOT_SCHEMA_KEYWORDS = [:type, :"$ref", :oneOf, :anyOf, :allOf, :not, :if, :const, :enum].freeze + # Root-level keywords whose presence means the user already chose a root schema shape, so no `type: "object"` + # default should be merged in. Both reference keywords count, since a root `$dynamicRef` names the shape as + # a root `$ref` does; they come from `Schema` so that this list cannot drift from the same-document check. + ROOT_SCHEMA_KEYWORDS = [:type, *REFERENCE_KEYWORDS, :oneOf, :anyOf, :allOf, :not, :if, :const, :enum].freeze def validate_result(result) errors = fully_validate(result) diff --git a/test/mcp/server_test.rb b/test/mcp/server_test.rb index 4cfa6456..603635c1 100644 --- a/test/mcp/server_test.rb +++ b/test/mcp/server_test.rb @@ -3206,6 +3206,35 @@ def read_resource_request(uri) assert_equal({ result: "success" }, response[:result][:structuredContent]) end + test "tools/call validates structuredContent against an output schema whose root is a $dynamicRef" do + tool = Tool.define( + name: "dynamic_ref_tool", + output_schema: { + "$dynamicRef": "#vector", + "$defs": { vector: { "$dynamicAnchor": "vector", type: "array", items: { type: "number" } } }, + }, + ) do + Tool::Response.new([{ type: "text", text: "[1, 2]" }], structured_content: [1, 2]) + end + server = Server.new( + tools: [tool], + configuration: Configuration.new(validate_tool_call_results: true), + ) + + listed = server.handle({ jsonrpc: "2.0", id: 1, method: "tools/list" })[:result][:tools].first + refute listed[:outputSchema].key?(:type) + + response = server.handle({ + jsonrpc: "2.0", + id: 2, + method: "tools/call", + params: { name: "dynamic_ref_tool" }, + }) + + assert_nil response[:error] + assert_equal [1, 2], response[:result][:structuredContent] + end + test "tools/call returns JSON-RPC error for invalid structuredContent when output schema validation is enabled" do tool = Tool.define( name: "invalid_structured_content_tool", diff --git a/test/mcp/tool/output_schema_test.rb b/test/mcp/tool/output_schema_test.rb index a9522ccc..528e6de9 100644 --- a/test/mcp/tool/output_schema_test.rb +++ b/test/mcp/tool/output_schema_test.rb @@ -238,6 +238,45 @@ class OutputSchemaTest < ActiveSupport::TestCase assert_raises(OutputSchema::ValidationError) { schema.validate_result(42) } end + test "does not inject a root type into a root-level $dynamicRef schema" do + # `Schema` restricts `$ref` and `$dynamicRef` alike, and the root default has to know both: with the object default merged in, + # this schema advertised `type: "object"` and rejected the array it describes. + schema = OutputSchema.new( + "$dynamicRef": "#vector", + "$defs": { vector: { "$dynamicAnchor": "vector", type: "array", items: { type: "number" } } }, + ) + + refute schema.to_h.key?(:type) + assert_equal "#vector", schema.to_h[:"$dynamicRef"] + assert_nothing_raised { schema.validate_result([1, 2]) } + assert_raises(OutputSchema::ValidationError) { schema.validate_result(["bad"]) } + assert_raises(OutputSchema::ValidationError) { schema.validate_result({}) } + assert_empty MCP::Tool::Schema::REFERENCE_KEYWORDS - OutputSchema::ROOT_SCHEMA_KEYWORDS + end + + test "keeps an explicit type beside a root-level $dynamicRef" do + schema = OutputSchema.new( + type: "array", + "$dynamicRef": "#vector", + "$defs": { vector: { "$dynamicAnchor": "vector", items: { type: "number" } } }, + ) + + assert_equal "array", schema.to_h[:type] + assert_nothing_raised { schema.validate_result([1, 2]) } + assert_raises(OutputSchema::ValidationError) { schema.validate_result("text") } + end + + test "does not inject a root type into a root-level $dynamicRef schema given with String keys" do + schema = OutputSchema.new( + "$dynamicRef" => "#scalar", + "$defs" => { "scalar" => { "$dynamicAnchor" => "scalar", "type" => "string" } }, + ) + + refute schema.to_h.key?(:type) + assert_nothing_raised { schema.validate_result("text") } + assert_raises(OutputSchema::ValidationError) { schema.validate_result(42) } + end + test "allows primitive root schemas" do schema = OutputSchema.new(type: "string")