Conform Tool Schemas to JSON Schema 2020-12 per SEP-2106
## 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.
This commit is contained in:
Koichi ITO
parent
217542f812
commit
5ca8b6ebbb
3 changed files with 303 additions and 25 deletions
|
|
@ -636,7 +636,7 @@ module MCP
|
|||
tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session, related_request_id: related_request_id, cancellation: cancellation
|
||||
)
|
||||
validate_tool_call_result!(tool, result)
|
||||
result
|
||||
serialize_structured_content_fallback(result)
|
||||
rescue RequestHandlerError, CancelledError
|
||||
# CancelledError is intentionally not wrapped so `handle_request` can turn it into
|
||||
# `JsonRpcHandler::NO_RESPONSE` per the MCP cancellation spec.
|
||||
|
|
@ -801,6 +801,18 @@ module MCP
|
|||
tool.output_schema.validate_result(result[:structuredContent])
|
||||
end
|
||||
|
||||
# Per SEP-2106, `structuredContent` may be any JSON value, not only an object.
|
||||
# Clients on older protocol versions may only read `content`,
|
||||
# so when a tool returns non-object structured content without providing
|
||||
# any content blocks, mirror the value into `content` as serialized JSON text.
|
||||
def serialize_structured_content_fallback(result)
|
||||
structured = result[:structuredContent]
|
||||
return result if structured.nil? || structured.is_a?(Hash)
|
||||
return result unless result[:content].nil? || result[:content].empty?
|
||||
|
||||
result.merge(content: [{ type: "text", text: JSON.generate(structured) }])
|
||||
end
|
||||
|
||||
# Whether a tool/prompt handler opts in to receiving an `MCP::ServerContext`.
|
||||
# Recognizes `:keyrest` (`**kwargs`) because tools are invoked without a positional argument
|
||||
# (`tool.call(**args, server_context:)`), soa `**kwargs`-only signature safely captures `server_context:`.
|
||||
|
|
|
|||
|
|
@ -7,12 +7,29 @@ module MCP
|
|||
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
|
||||
|
||||
def validate_result(result)
|
||||
errors = fully_validate(result)
|
||||
if errors.any?
|
||||
raise ValidationError, "Invalid result: #{errors.join(", ")}"
|
||||
end
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
# Per SEP-2106, an output schema may be ANY valid JSON Schema 2020-12 document: object, array, primitive,
|
||||
# or a root-level composition.
|
||||
# Default the root to an object only when no root schema keyword is present, which preserves the wire output
|
||||
# of the common `properties`-only shape while leaving e.g. `{ type: "array" }` or `{ oneOf: [...] }` untouched
|
||||
# (the old unconditional default merged `type: "object"` into root combinators, producing a wrong schema).
|
||||
def apply_default_root_type!
|
||||
return if ROOT_SCHEMA_KEYWORDS.any? { |keyword| @schema.key?(keyword) }
|
||||
|
||||
super
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
|
|
|
|||
|
|
@ -36,16 +36,29 @@ module MCP
|
|||
end
|
||||
VALIDATION_CACHE = ValidationCache.new
|
||||
|
||||
# JSON Schema 2020-12 is the default dialect for MCP schema definitions
|
||||
# per MCP 2025-11-25 (SEP-1613). Note: emission only — runtime validation
|
||||
# is still performed against the JSON Schema draft-04 metaschema.
|
||||
# JSON Schema 2020-12 is the default dialect for MCP schema definitions per MCP 2025-11-25 (SEP-1613),
|
||||
# and SEP-2106 requires tool schemas to conform to the full 2020-12 vocabulary. Both emission and
|
||||
# runtime validation use this dialect. Because MCP mandates 2020-12, the SDK validates against it
|
||||
# regardless of any `$schema` a document embeds; for compliant schemas this is the same dialect
|
||||
# the Python SDK's `jsonschema.validate` resolves to.
|
||||
JSON_SCHEMA_2020_12_URI = "https://json-schema.org/draft/2020-12/schema"
|
||||
|
||||
DRAFT4_META_SCHEMA_URI = "http://json-schema.org/draft-04/schema#"
|
||||
# Resource bounds for schema compilation, mirroring the TypeScript SDK's schema bounds (SEP-2106):
|
||||
# schemas may use the full JSON Schema 2020-12 vocabulary including composition keywords and `$ref`,
|
||||
# so adversarial documents must be rejected before they can cause excessive validation cost.
|
||||
# Only same-document references (starting with `#`) are accepted, so schema handling can never trigger network
|
||||
# or file access.
|
||||
MAX_SCHEMA_DEPTH = 64
|
||||
MAX_SUBSCHEMA_COUNT = 10_000
|
||||
|
||||
# Reference keywords whose targets the SDK refuses to dereference. Both `$ref` and `$dynamicRef` may carry
|
||||
# an absolute URI under JSON Schema 2020-12, so a non-same-document value is an external reference.
|
||||
REFERENCE_KEYWORDS = [:"$ref", :"$dynamicRef"].freeze
|
||||
|
||||
def initialize(schema = {})
|
||||
@schema = JSON.parse(JSON.dump(schema), symbolize_names: true)
|
||||
@schema[:type] ||= "object"
|
||||
apply_default_root_type!
|
||||
validate_schema_bounds!
|
||||
validate_schema!
|
||||
end
|
||||
|
||||
|
|
@ -61,6 +74,48 @@ module MCP
|
|||
|
||||
private
|
||||
|
||||
# Root-type defaulting hook. The base class preserves the historical behavior of defaulting the root
|
||||
# to an object schema; `OutputSchema` overrides this because SEP-2106 allows any root schema there.
|
||||
def apply_default_root_type!
|
||||
@schema[:type] ||= "object"
|
||||
end
|
||||
|
||||
# Enforces `MAX_SCHEMA_DEPTH` / `MAX_SUBSCHEMA_COUNT` and the same-document reference rule over
|
||||
# the whole schema document.
|
||||
def validate_schema_bounds!
|
||||
subschema_count = 0
|
||||
stack = [[@schema, 1]]
|
||||
|
||||
until stack.empty?
|
||||
node, depth = stack.pop
|
||||
if depth > MAX_SCHEMA_DEPTH
|
||||
raise ArgumentError,
|
||||
"Invalid JSON Schema: nesting exceeds the maximum depth of #{MAX_SCHEMA_DEPTH}."
|
||||
end
|
||||
|
||||
case node
|
||||
when Hash
|
||||
subschema_count += 1
|
||||
if subschema_count > MAX_SUBSCHEMA_COUNT
|
||||
raise ArgumentError,
|
||||
"Invalid JSON Schema: document exceeds the maximum of #{MAX_SUBSCHEMA_COUNT} subschema objects."
|
||||
end
|
||||
|
||||
REFERENCE_KEYWORDS.each do |keyword|
|
||||
ref = node[keyword]
|
||||
next unless ref.is_a?(String) && !ref.start_with?("#")
|
||||
|
||||
raise ArgumentError,
|
||||
"Invalid JSON Schema: only same-document #{keyword} (starting with '#') is supported, got #{ref.inspect}."
|
||||
end
|
||||
|
||||
node.each_value { |child| stack << [child, depth + 1] }
|
||||
when Array
|
||||
node.each { |child| stack << [child, depth + 1] }
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
def stringify(obj)
|
||||
case obj
|
||||
when Hash
|
||||
|
|
@ -78,13 +133,16 @@ module MCP
|
|||
# Memoized per Schema instance because schema content is fixed at construction,
|
||||
# so the compiled schemer is reusable across many `fully_validate` calls.
|
||||
#
|
||||
# Validated against the JSON Schema 2020-12 metaschema per SEP-2106, so `$defs`/`$ref` and
|
||||
# the rest of the 2020-12 vocabulary resolve natively.
|
||||
#
|
||||
# `format: false` preserves the legacy behavior of the previous `json-schema` based implementation,
|
||||
# which did not enforce `format` keywords. `RegexpError` from a malformed `pattern` is re-raised as
|
||||
# `ArgumentError` so callers see the same exception class they used to.
|
||||
def schemer
|
||||
@schemer ||= JSONSchemer.schema(
|
||||
stringify(schema_for_validation),
|
||||
meta_schema: DRAFT4_META_SCHEMA_URI,
|
||||
meta_schema: JSON_SCHEMA_2020_12_URI,
|
||||
format: false,
|
||||
)
|
||||
rescue RegexpError => e
|
||||
|
|
@ -112,8 +170,8 @@ module MCP
|
|||
VALIDATION_CACHE.store(key)
|
||||
end
|
||||
|
||||
# `json_schemer` is pinned to the draft-04 metaschema, so strip top-level `$schema` before validation:
|
||||
# this preserves the legacy behavior of ignoring the advertised dialect URI when the SDK validates schemas.
|
||||
# Strip the top-level `$schema` before validation so the SDK always validates against
|
||||
# the 2020-12 metaschema (SEP-2106) regardless of any dialect URI a caller embedded in the document.
|
||||
def schema_for_validation
|
||||
return @schema unless @schema.key?(:"$schema")
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue