5ca8b6ebbb
## Motivation and Context
SEP-2106 (modelcontextprotocol/modelcontextprotocol#2106, merged for the 2026-07-28 spec release)
makes tool `inputSchema` and `outputSchema` conform to the full JSON Schema 2020-12 vocabulary:
an input schema keeps `type: "object"` at the root but may use any 2020-12 keyword below it;
an output schema may be ANY valid schema (object, array, primitive, or a root-level composition);
and `CallToolResult.structuredContent` widens from an object to any JSON value. The SEP also adds
resource bounds: `$ref` resolution is restricted (same-document only in the reference implementation) and
composition-heavy documents must be bounded to avoid excessive validation cost.
This follows the TypeScript SDK's reference implementation (typescript-sdk#2249; the Python SDK tracks
the same work in python-sdk#2792):
- `Tool::Schema` now validates against the JSON Schema 2020-12 metaschema rather than the draft-04 metaschema.
The draft-04 pin was a stopgap from when the SDK used the `json-schema` gem, which did not support 2020-12;
`json_schemer` does, so `$defs`/`$ref` and the rest of the 2020-12 vocabulary now resolve natively.
This matches the dialect the SDK already advertises in emitted schemas and the Python SDK's behavior,
whose `jsonschema.validate` selects the validator from the schema's `$schema`.
- `Tool::Schema` moves root-type defaulting into an overridable `apply_default_root_type!` hook.
`InputSchema` keeps the historical `type: "object"` default; `OutputSchema` now applies it only
when no root schema keyword (`type`, `$ref`, `oneOf`, `anyOf`, `allOf`, `not`, `if`, `const`, `enum`) is present.
The previous unconditional default merged `type: "object"` into root combinators such as `{ oneOf: [...] }`,
producing a wrong schema, so that case is a bug fix.
- `Tool::Schema` enforces the TypeScript SDK's schema bounds at construction time: only same-document
`$ref`/`$dynamicRef`s (starting with `#`, so schema handling can never trigger network or file access),
`MAX_SCHEMA_DEPTH = 64` nesting levels, and `MAX_SUBSCHEMA_COUNT = 10_000` subschema objects,
all raising `ArgumentError` on violation.
- `Server#call_tool` mirrors non-object `structuredContent` into `content` as serialized JSON text
when the tool provided no content blocks, so pre-SEP clients that only read `content` still receive the data.
Object results and explicit content are untouched.
Resolves #377.
## How Has This Been Tested?
- `test/mcp/tool/output_schema_test.rb`: root-level `oneOf`, `$ref`+`$defs`, primitive, and `enum` schemas serialize
without an injected `type` and validate results correctly; the `properties`-only shorthand still serializes
with `type: "object"` (wire-format regression); explicit `type: "array"` keeps working.
- `test/mcp/tool/input_schema_test.rb`: an input schema using `$defs`, `$ref`, `oneOf`, `if`/`then`, and `allOf`
keeps its object root and round-trips all keywords; a draft-04-only boolean `exclusiveMinimum` is rejected
under the 2020-12 dialect while the numeric form is accepted.
- `test/mcp/tool/schema_test.rb`: depth and subschema-count bound violations raise `ArgumentError`;
non-same-document `$ref`s (remote URI, sibling file) are rejected while `#/$defs/...` is accepted.
The previous unbounded-depth caching test is replaced, since the depth bound now rejects such documents by design.
- `test/mcp/server_test.rb`: `tools/call` with array `structuredContent` and no content gains
the serialized TextContent fallback; explicit content is not overwritten; object `structuredContent` gets no fallback.
`bundle exec rake` (tests, RuboCop, and conformance baseline, including the `json-schema-2020-12` server scenario) passes.
## Breaking Changes
Three narrow behavior changes, all intentional per the SEP:
- Runtime validation now uses the JSON Schema 2020-12 metaschema instead of draft-04.
Schemas that rely on draft-04-only syntax are rejected at construction time. The practical case is the boolean
`exclusiveMinimum`/`exclusiveMaximum` form (deprecated since draft-06), which must now be the numeric form;
the Python SDK rejects it the same way. Other draft-04 spellings (`definitions`, `id`, `dependencies`) still validate,
since 2020-12 tolerates unknown keywords.
- Schemas that exceed the new resource bounds (nesting deeper than 64, more than 10,000 subschema objects) or
use a non-same-document `$ref`/`$dynamicRef` now raise `ArgumentError` at construction time.
Previously such documents were accepted (external references were already never fetched, only ignored).
- An `OutputSchema` whose root declares a schema keyword other than `type` (e.g. `oneOf`) no longer has `type: "object"`
merged into it. The old output was an invalid hybrid schema, so no conforming consumer could have relied on it.
285 lines
10 KiB
Ruby
285 lines
10 KiB
Ruby
# frozen_string_literal: true
|
|
|
|
require "test_helper"
|
|
|
|
module MCP
|
|
class Tool
|
|
class OutputSchemaTest < ActiveSupport::TestCase
|
|
test "to_h returns a hash representation of the output schema" do
|
|
output_schema = OutputSchema.new(properties: { result: { type: "string" } }, required: ["result"])
|
|
assert_equal(
|
|
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
type: "object",
|
|
properties: { result: { type: "string" } },
|
|
required: ["result"],
|
|
},
|
|
output_schema.to_h,
|
|
)
|
|
end
|
|
|
|
test "to_h preserves user-supplied $schema dialect" do
|
|
output_schema = OutputSchema.new(
|
|
"$schema": "https://json-schema.org/draft/2019-09/schema",
|
|
properties: { result: { type: "string" } },
|
|
)
|
|
assert_equal "https://json-schema.org/draft/2019-09/schema", output_schema.to_h[:"$schema"]
|
|
end
|
|
|
|
test "validate_result works when user supplies a 2020-12 $schema" do
|
|
output_schema = OutputSchema.new(
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
properties: { result: { type: "string" } },
|
|
required: ["result"],
|
|
)
|
|
assert_nothing_raised do
|
|
output_schema.validate_result({ result: "success" })
|
|
end
|
|
assert_raises(OutputSchema::ValidationError) do
|
|
output_schema.validate_result({ result: 123 })
|
|
end
|
|
end
|
|
|
|
test "validate_result validates result against the schema" do
|
|
output_schema = OutputSchema.new(properties: { result: { type: "string" } }, required: ["result"])
|
|
assert_nothing_raised do
|
|
output_schema.validate_result({ result: "success" })
|
|
end
|
|
end
|
|
|
|
test "validate_result validates result with additional properties against the schema when additionalProperties set to nil (default)" do
|
|
output_schema = OutputSchema.new(properties: { result: { type: "string" } }, required: ["result"])
|
|
assert_nothing_raised do
|
|
output_schema.validate_result({ result: "success", extra: 123 })
|
|
end
|
|
end
|
|
|
|
test "validate_result validates result with additional properties against the schema when additionalProperties set to true" do
|
|
output_schema = OutputSchema.new(properties: { result: { type: "string" } }, required: ["result"], additionalProperties: true)
|
|
assert_nothing_raised do
|
|
output_schema.validate_result({ result: "success", extra: 123 })
|
|
end
|
|
end
|
|
|
|
test "validate_result raises error with additional properties when additionalProperties set to false)" do
|
|
output_schema = OutputSchema.new(properties: { result: { type: "string" } }, required: ["result"], additionalProperties: false)
|
|
assert_raises(OutputSchema::ValidationError) do
|
|
output_schema.validate_result({ result: "success", extra: 123 })
|
|
end
|
|
end
|
|
|
|
test "validate_result raises error for invalid result" do
|
|
output_schema = OutputSchema.new(properties: { result: { type: "string" } }, required: ["result"])
|
|
assert_raises(OutputSchema::ValidationError) do
|
|
output_schema.validate_result({ result: 123 })
|
|
end
|
|
end
|
|
|
|
test "validate_result raises error for missing required field" do
|
|
output_schema = OutputSchema.new(properties: { result: { type: "string" } }, required: ["result"])
|
|
assert_raises(OutputSchema::ValidationError) do
|
|
output_schema.validate_result({})
|
|
end
|
|
end
|
|
|
|
test "valid schema initialization" do
|
|
schema = OutputSchema.new(properties: { foo: { type: "string" } }, required: ["foo"])
|
|
assert_equal(
|
|
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
type: "object",
|
|
properties: { foo: { type: "string" } },
|
|
required: ["foo"],
|
|
},
|
|
schema.to_h,
|
|
)
|
|
end
|
|
|
|
test "invalid schema raises argument error" do
|
|
assert_raises(ArgumentError) do
|
|
OutputSchema.new(properties: { foo: { type: "invalid_type" } }, required: ["foo"])
|
|
end
|
|
end
|
|
|
|
test "schema without required arguments is valid" do
|
|
assert_nothing_raised do
|
|
OutputSchema.new(properties: { foo: { type: "string" } })
|
|
end
|
|
end
|
|
|
|
test "unexpected errors bubble up from validate_result" do
|
|
schema = OutputSchema.new(properties: { foo: { type: "string" } }, required: ["foo"])
|
|
|
|
JSONSchemer::Schema.any_instance.stubs(:validate).raises("unexpected error")
|
|
|
|
assert_raises(RuntimeError) do
|
|
schema.validate_result(foo: "bar")
|
|
end
|
|
end
|
|
|
|
test "accepts schemas with $ref references" do
|
|
schema = OutputSchema.new(
|
|
properties: {
|
|
foo: { type: "string" },
|
|
},
|
|
definitions: {
|
|
bar: { type: "string" },
|
|
},
|
|
required: ["foo"],
|
|
)
|
|
assert_includes schema.to_h.keys, :definitions
|
|
end
|
|
|
|
test "accepts schemas with $ref string key and includes $ref in to_h" do
|
|
schema = OutputSchema.new({
|
|
"properties" => {
|
|
"foo" => { "$ref" => "#/definitions/bar" },
|
|
},
|
|
"definitions" => {
|
|
"bar" => { "type" => "string" },
|
|
},
|
|
})
|
|
assert_equal "#/definitions/bar", schema.to_h[:properties][:foo][:$ref]
|
|
end
|
|
|
|
test "accepts schemas with $ref symbol key and includes $ref in to_h" do
|
|
schema = OutputSchema.new({
|
|
properties: {
|
|
foo: { :$ref => "#/definitions/bar" },
|
|
},
|
|
definitions: {
|
|
bar: { type: "string" },
|
|
},
|
|
})
|
|
assert_equal "#/definitions/bar", schema.to_h[:properties][:foo][:$ref]
|
|
end
|
|
|
|
test "== compares two output schemas with the same properties and required fields" do
|
|
schema1 = OutputSchema.new(properties: { foo: { type: "string" } }, required: ["foo"])
|
|
schema2 = OutputSchema.new(properties: { foo: { type: "string" } }, required: ["foo"])
|
|
assert_equal schema1, schema2
|
|
|
|
schema3 = OutputSchema.new(properties: { bar: { type: "string" } }, required: ["bar"])
|
|
refute_equal schema1, schema3
|
|
|
|
schema4 = OutputSchema.new(properties: { foo: { type: "string" } }, required: ["bar"])
|
|
refute_equal schema1, schema4
|
|
|
|
schema5 = OutputSchema.new(properties: { bar: { type: "string" } }, required: ["foo"])
|
|
refute_equal schema1, schema5
|
|
end
|
|
|
|
test "empty schema is valid" do
|
|
schema = OutputSchema.new
|
|
assert_equal(
|
|
{ "$schema": "https://json-schema.org/draft/2020-12/schema", type: "object" },
|
|
schema.to_h,
|
|
)
|
|
end
|
|
|
|
test "validates complex nested schemas" do
|
|
schema = OutputSchema.new(
|
|
properties: {
|
|
data: {
|
|
type: "object",
|
|
properties: {
|
|
items: { type: "array", items: { type: "string" } },
|
|
count: { type: "integer", minimum: 0 },
|
|
},
|
|
required: ["items"],
|
|
},
|
|
},
|
|
required: ["data"],
|
|
)
|
|
|
|
valid_result = {
|
|
data: {
|
|
items: ["item1", "item2"],
|
|
count: 2,
|
|
},
|
|
}
|
|
|
|
assert_nothing_raised do
|
|
schema.validate_result(valid_result)
|
|
end
|
|
|
|
invalid_result = {
|
|
data: {
|
|
items: [123, 456], # Should be strings
|
|
count: 2,
|
|
},
|
|
}
|
|
|
|
assert_raises(OutputSchema::ValidationError) do
|
|
schema.validate_result(invalid_result)
|
|
end
|
|
end
|
|
|
|
test "does not inject a root type into a root-level oneOf schema" do
|
|
# Per SEP-2106, an output schema may be any JSON Schema 2020-12 document.
|
|
# Merging `type: "object"` into a root combinator would produce a wrong schema.
|
|
schema = OutputSchema.new(oneOf: [{ type: "string" }, { type: "integer" }])
|
|
|
|
refute schema.to_h.key?(:type)
|
|
assert_equal [{ type: "string" }, { type: "integer" }], schema.to_h[:oneOf]
|
|
assert_nothing_raised { schema.validate_result("text") }
|
|
assert_nothing_raised { schema.validate_result(42) }
|
|
assert_raises(OutputSchema::ValidationError) { schema.validate_result(1.5) }
|
|
end
|
|
|
|
test "does not inject a root type into a root-level $ref schema" do
|
|
schema = OutputSchema.new(
|
|
"$ref": "#/$defs/result",
|
|
"$defs": { result: { 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")
|
|
|
|
assert_nothing_raised { schema.validate_result("text") }
|
|
assert_raises(OutputSchema::ValidationError) { schema.validate_result(42) }
|
|
end
|
|
|
|
test "does not inject a root type into a root-level enum schema" do
|
|
schema = OutputSchema.new(enum: ["red", "green", "blue"])
|
|
|
|
refute schema.to_h.key?(:type)
|
|
assert_nothing_raised { schema.validate_result("red") }
|
|
assert_raises(OutputSchema::ValidationError) { schema.validate_result("yellow") }
|
|
end
|
|
|
|
test "defaults a properties-only schema to a root object" do
|
|
# Wire-format regression: the common shorthand keeps serializing with the injected `type: "object"`.
|
|
schema = OutputSchema.new(properties: { result: { type: "string" } })
|
|
|
|
assert_equal "object", schema.to_h[:type]
|
|
end
|
|
|
|
test "allow to declare array schemas" do
|
|
schema = OutputSchema.new({
|
|
type: "array",
|
|
items: {
|
|
properties: { foo: { type: "string" } },
|
|
required: ["foo"],
|
|
},
|
|
})
|
|
assert_equal(
|
|
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
type: "array",
|
|
items: {
|
|
properties: { foo: { type: "string" } },
|
|
required: ["foo"],
|
|
},
|
|
},
|
|
schema.to_h,
|
|
)
|
|
end
|
|
end
|
|
end
|
|
end
|