From 7b00aec73f1e950fc5f92393f4ca06ed5f0f2a00 Mon Sep 17 00:00:00 2001 From: Koichi ITO Date: Mon, 2 Nov 2026 23:39:09 +0900 Subject: [PATCH] Refuse a `_meta` that is not an object as invalid params ## Motivation and Context `_meta` is an object on every request (`MetaObject` in the schema). After #650, a String, Array, or number there no longer raises from `dig`, and the modern lifecycle answers -32602 because the envelope keys are missing; the legacy lifecycle, though, went on to run the handler. That left two gaps. The value still reached `server_context[:_meta]`, where the `server_context.dig(:_meta, ...)` the server context page shows raises `TypeError` on a String or an Array, so a handler written as documented still turned the request into -32603. And the TypeScript and Python servers refuse such a request as invalid params on both lifecycles, through schema validation of `params` and their inbound checks, so the Ruby server answered differently from both. The request is now refused with -32602 "Invalid params: _meta must be an object" before the envelope is read and before any handler runs, on both lifecycles. A notification handed to a handler is dropped the same way, without a response, as the TypeScript server drops a notification with invalid params; `notifications/cancelled` is served before the check and reads no `_meta`. A `null` `_meta` reads as absent, as it does for the Python server's request model. The server context page states the rule, since it tells handlers to read `_meta` from `server_context`. ## How Has This Been Tested? test/mcp/server_test.rb and test/mcp/server/transports/streamable_http_transport_test.rb. Before the fix, legacy `tools/call` with `_meta: "not-an-object"` ran the tool, and a tool reading `server_context.dig(:_meta, :key)` answered -32603 "Internal error" with "Internal error calling tool meta_reader" as the data. ## Breaking Changes A legacy-lifecycle request whose `_meta` is not an object now answers -32602. Released versions served such a request for methods that never read `_meta`, such as `tools/list`, and answered -32603 for `tools/call` and `prompts/get`. --- docs/_server/server-context.md | 3 ++ lib/mcp/server.rb | 21 +++++++++ .../streamable_http_transport_test.rb | 31 +++++++++++++ test/mcp/server_test.rb | 46 +++++++++++++++---- 4 files changed, 91 insertions(+), 10 deletions(-) diff --git a/docs/_server/server-context.md b/docs/_server/server-context.md index 1c90aad1..5c88c070 100644 --- a/docs/_server/server-context.md +++ b/docs/_server/server-context.md @@ -68,6 +68,9 @@ class MyTool < MCP::Tool end ``` +A `_meta` that is not an object is refused with `-32602` before any handler runs, on both lifecycles, +and a `null` `_meta` reads as absent, so `server_context[:_meta]`, when present, is always a `Hash`. + **Client Request Example:** A `tools/call` request carrying `_meta`, as read by the tool above: diff --git a/lib/mcp/server.rb b/lib/mcp/server.rb index cf76a621..7ae234b7 100644 --- a/lib/mcp/server.rb +++ b/lib/mcp/server.rb @@ -799,6 +799,7 @@ def handle_request(request, method, session: nil, related_request_id: nil, auth_ server_context: { request: request }, exception_already_reported: ->(e) { reported_exception.equal?(e) }, ) do + refuse_non_object_meta!(params) envelope = lift_request_envelope(params, method: method, session: session) # The envelope's `logLevel` member replaces `logging/setLevel` in the modern lifecycle: @@ -931,6 +932,26 @@ def modern_request?(request, session) RequestEnvelope.modern?(request.is_a?(Hash) ? request[:params] : nil) end + # `_meta` is an object on every request (`MetaObject`); a String, Array, or number there carries no envelope, + # no progress token, and no trace context, and the TypeScript and Python servers refuse it as invalid params on + # both lifecycles. Refused before the envelope is read and before any handler can meet it in `server_context`. + # `null` reads as absent, as it does for the Python server. + def refuse_non_object_meta!(params) + return unless params.is_a?(Hash) + + # Read as `RequestEnvelope` reads it, so the two cannot disagree on a Hash holding both key spellings. + meta = params[:_meta] + meta = params["_meta"] if meta.nil? + return if meta.nil? || meta.is_a?(Hash) + + raise RequestHandlerError.new( + "Invalid params: _meta must be an object", + params, + error_type: :invalid_params, + error_code: JsonRpcHandler::ErrorCode::INVALID_PARAMS, + ) + end + # Lifts the SEP-2575 per-request `_meta` envelope for modern requests. Only a request whose `_meta` carries # the full required triple is classified as modern; a partial triple keeps flowing through the legacy path untouched. # Notifications carry no envelope (their `_meta` is a `NotificationMetaObject`), and `server/discover` is diff --git a/test/mcp/server/transports/streamable_http_transport_test.rb b/test/mcp/server/transports/streamable_http_transport_test.rb index d08c4d8d..8a81a1b8 100644 --- a/test/mcp/server/transports/streamable_http_transport_test.rb +++ b/test/mcp/server/transports/streamable_http_transport_test.rb @@ -6516,6 +6516,37 @@ def string end end + test "legacy POST refuses a _meta that is not an object with -32602 before the tool runs" do + calls = 0 + @server.define_tool(name: "meta_reader") do |server_context:| + calls += 1 + server_context.dig(:_meta, :key) + Tool::Response.new([]) + end + session_id = initialize_test_session + + ["not-an-object", [], 42].each do |meta| + response = @transport.handle_request(create_rack_request( + "POST", + "/", + { "CONTENT_TYPE" => "application/json", "HTTP_MCP_SESSION_ID" => session_id }, + { jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "meta_reader", arguments: {}, _meta: meta } }.to_json, + )) + body = if response[1]["content-type"].to_s.start_with?("text/event-stream") + io = StringIO.new + response[2].call(io) + JSON.parse(io.string[/^data: (.+)$/, 1]) + else + JSON.parse(response[2][0]) + end + + assert_equal 200, response[0] + assert_equal(-32602, body.dig("error", "code"), meta.inspect) + assert_equal "Invalid params: _meta must be an object", body.dig("error", "message") + end + assert_equal 0, calls + end + test "modern POST rejects an envelope missing clientCapabilities with 400 and -32602" do body = { jsonrpc: "2.0", diff --git a/test/mcp/server_test.rb b/test/mcp/server_test.rb index 30ec26da..73827b93 100644 --- a/test/mcp/server_test.rb +++ b/test/mcp/server_test.rb @@ -4350,18 +4350,44 @@ def server_context end end - test "#handle tools/call and prompts/get ignore a _meta that is not an object" do - @server.define_tool(name: "echo_tool") { Tool::Response.new([]) } + test "#handle refuses a _meta that is not an object with -32602 before any handler runs" do + calls = 0 + server = Server.new(name: "meta_server", server_context: { user: "u" }) + # Reads `_meta` as the server context page shows (`dig`), which raises TypeError on a String or an Array. + server.define_tool(name: "meta_reader") do |server_context:| + calls += 1 + server_context.dig(:_meta, :key) + Tool::Response.new([]) + end + + ["not-an-object", [], 42].each do |meta| + [ + [server, { jsonrpc: "2.0", method: "tools/call", id: 1, params: { name: "meta_reader", _meta: meta } }], + [server, { jsonrpc: "2.0", method: "tools/call", id: 1, params: { name: "meta_reader", "_meta" => meta } }], + [server, { jsonrpc: "2.0", method: "tools/list", id: 1, params: { _meta: meta } }], + [@server, { jsonrpc: "2.0", method: "prompts/get", id: 1, params: { name: "test_prompt", arguments: { test_argument: "x" }, _meta: meta } }], + ].each do |target, request| + response = target.handle(request) + assert_equal(-32602, response[:error][:code], request.inspect) + assert_equal "Invalid params: _meta must be an object", response[:error][:message] + end + end + assert_equal 0, calls - ["not-an-object", []].each do |meta| - tool = @server.handle({ jsonrpc: "2.0", method: "tools/call", id: 1, params: { name: "echo_tool", _meta: meta } }) - prompt = @server.handle({ - jsonrpc: "2.0", method: "prompts/get", id: 1, params: { name: "test_prompt", arguments: { test_argument: "x" }, _meta: meta }, - }) + # `null` reads as absent and an object reaches the handler, where the documented `dig` works on both. + assert_nil server.handle({ jsonrpc: "2.0", method: "tools/call", id: 1, params: { name: "meta_reader", _meta: nil } })[:error] + assert_nil server.handle({ jsonrpc: "2.0", method: "tools/call", id: 1, params: { name: "meta_reader", _meta: { key: "v" } } })[:error] + assert_equal 2, calls + end - assert_nil tool[:error] - assert_nil prompt[:error] - end + test "#handle drops a notification whose _meta is not an object without running its handler" do + calls = 0 + @server.define_custom_method(method_name: "custom/notify") { |_params| calls += 1 } + + assert_nil @server.handle({ jsonrpc: "2.0", method: "custom/notify", params: { _meta: "not-an-object" } }) + assert_equal 0, calls + assert_nil @server.handle({ jsonrpc: "2.0", method: "custom/notify", params: { _meta: { key: "v" } } }) + assert_equal 1, calls end test "#handle tools/call mirrors non-object structuredContent when content is omitted or nil" do