Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/_server/tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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.

Expand Down
7 changes: 4 additions & 3 deletions lib/mcp/tool/output_schema.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
29 changes: 29 additions & 0 deletions test/mcp/server_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
39 changes: 39 additions & 0 deletions test/mcp/tool/output_schema_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand Down
Loading