v5.5.6 Fix MCP SSE event names to spec-mandated "message"

Author: AdrianCurtin

CHANGELOG.md

@@ -1,5 +1,23 @@
 ## parse-stack-next Changelog
 
+### 5.5.6
+
+#### MCP clients now receive the SSE response instead of hanging
+
+- **FIXED**: The Streamable HTTP SSE transport framed its events with custom
+  event names — `event: progress` for `notifications/progress` and
+  `event: response` for the final JSON-RPC response. MCP defines a single SSE
+  event type for JSON-RPC traffic, and clients match only the default
+  `message` type, so every frame the SDK emitted was silently discarded: tool
+  progress never surfaced, and, critically, the terminating response never
+  arrived, leaving the client blocked until its own timeout on any streaming
+  `tools/call`. All frames on both the request-scoped POST stream and the
+  server-to-client GET notification stream now carry `event: message`, and
+  clients discriminate from the JSON-RPC envelope (`method` present for a
+  notification, `id` plus `result`/`error` for a response) as the protocol
+  intends. Deployments that worked around this with a middleware rewriting
+  the event name can drop it.
+
 ### 5.5.5
 
 #### Agent `call_method` runs under the caller's scope, not the master key

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack-next (5.5.5)
+    parse-stack-next (5.5.6)
       activemodel (>= 6.1, < 9)
       activesupport (>= 6.1, < 9)
       connection_pool (>= 2.2, < 4)

lib/parse/agent/mcp_rack_app.rb

@@ -1183,10 +1183,21 @@ def principal_fingerprint(agent, env)
       # Wire format for each SSE event (note: trailing blank line is required
       # by the SSE spec):
       #
-      #   event: progress\n
+      #   event: message\n
       #   data: <json>\n
       #   \n
       #
+      # EVERY frame — progress notifications, list-changed notifications,
+      # and the final JSON-RPC response alike — carries the event name
+      # `message`. MCP Streamable HTTP defines exactly one SSE event type
+      # for JSON-RPC traffic; clients discriminate by inspecting the
+      # envelope (`method` present => notification, `id` + `result`/`error`
+      # => response), NOT by the SSE event name. Earlier releases emitted
+      # `event: progress` and `event: response`, which real MCP clients
+      # silently discard — they match only the default `message` type — so
+      # the final response never arrived and the call appeared to hang.
+      # Do not reintroduce custom event names.
+      #
       # @api private
       class SSEBody
         # Sentinel pushed to the queue when the worker is done.
@@ -1546,6 +1557,9 @@ def start_worker
         # The `total` field is omitted (rather than nil) so the wire
         # shape matches the spec's optional-field convention.
         #
+        # Emitted as `event: message` — see the SSEBody class docs. The
+        # payload's `method` is what marks it as progress.
+        #
         # @param elapsed [Float] seconds elapsed since the stream started.
         # @return [String] SSE event string (includes trailing blank line).
         def build_progress_event(elapsed)
@@ -1557,15 +1571,14 @@ def build_progress_event(elapsed)
               "progress"      => elapsed,
             },
           })
-          "event: progress\ndata: #{data}\n\n"
+          "event: message\ndata: #{data}\n\n"
         end
 
         # Format a `notifications/tools/list_changed` or
         # `notifications/prompts/list_changed` SSE event. Both
         # notifications have no `params` — the wire shape is just the
-        # JSON-RPC envelope with `method` set. SSE event name is
-        # "message" since this is not a progress notification (the
-        # progress event name is reserved for progress notifications).
+        # JSON-RPC envelope with `method` set. Emitted as `event: message`,
+        # like every other frame on this stream.
         #
         # @param method [String] full MCP method string.
         # @return [String] SSE event string (includes trailing blank line).
@@ -1599,7 +1612,7 @@ def build_tool_progress_event(progress, total, message)
             "method"  => "notifications/progress",
             "params"  => params,
           })
-          "event: progress\ndata: #{data}\n\n"
+          "event: message\ndata: #{data}\n\n"
         end
 
         # Build the callback the dispatcher block passes into
@@ -1631,12 +1644,17 @@ def build_progress_callback
           end
         end
 
-        # Format the final `response` SSE event.
+        # Format the final JSON-RPC response SSE event.
+        #
+        # Emitted as `event: message` (NOT `event: response`) — an MCP
+        # client matching only the default `message` type would otherwise
+        # discard the response and block until its own timeout. The
+        # envelope's `id` + `result`/`error` is what marks it final.
         #
         # @param body [Hash] JSON-RPC response envelope.
         # @return [String] SSE event string (includes trailing blank line).
         def build_response_event(body)
-          "event: response\ndata: #{JSON.generate(body)}\n\n"
+          "event: message\ndata: #{JSON.generate(body)}\n\n"
         end
 
         # Build an internal-error JSON-RPC envelope (id may be nil at this layer).
@@ -1755,9 +1773,9 @@ def start_heartbeat
           end
         end
 
-        # SSE wire form for a server→client notification. Event name "message"
-        # (not "progress"/"response", which are reserved for the request-scoped
-        # SSE path).
+        # SSE wire form for a server→client notification. Event name
+        # "message" — the single event type MCP Streamable HTTP defines for
+        # JSON-RPC traffic, matching the request-scoped SSE path.
         def format_event(notification)
           "event: message\ndata: #{JSON.generate(notification)}\n\n"
         end

lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.5.5"
+    VERSION = "5.5.6"
   end
 end

test/lib/parse/agent/mcp_sse_e2e_test.rb

@@ -39,15 +39,34 @@
 # Shared SSE parse helper
 # ---------------------------------------------------------------------------
 module SSETestHelpers
-  # Parse raw SSE text (may span many chunks) into [{event:, data:}] hashes.
+  # Parse raw SSE text (may span many chunks) into [{event:, data:, kind:}].
+  #
+  # `event:` is always the wire-mandated "message"; `kind:` is the
+  # payload-derived classification (see #sse_kind) that tests assert on,
+  # mirroring how a real MCP client discriminates frames.
   def parse_sse(raw)
     events = []
     raw.scan(/event:\s*(\S+)\r?\ndata:\s*(.+?)(?=\r?\n\r?\n|\z)/m) do |event, data|
-      events << { event: event.strip, data: data.strip }
+      clean = data.strip
+      events << { event: event.strip, data: clean, kind: sse_kind(clean) }
     end
     events
   end
 
+  # Classify an SSE frame the way an MCP client does — from the envelope.
+  def sse_kind(data)
+    payload = begin
+      JSON.parse(data)
+    rescue StandardError
+      nil
+    end
+    return :unknown unless payload.is_a?(Hash)
+    return :progress if payload["method"] == "notifications/progress"
+    return :notification if payload.key?("method")
+    return :response if payload.key?("id") && (payload.key?("result") || payload.key?("error"))
+    :unknown
+  end
+
   # Collect all streamed chunks from a Net::HTTP response into a single String.
   def collect_sse_body(response)
     buf = +""
@@ -261,7 +280,7 @@ def test_at_least_two_progress_events_arrive_for_slow_tool
     @@dispatch_delay = 0.6
 
     events, _headers, _raw = sse_post(tools_call_body)
-    progress_events = events.select { |e| e[:event] == "progress" }
+    progress_events = events.select { |e| e[:kind] == :progress }
 
     assert progress_events.size >= 2,
            "Expected >=2 progress events for 0.6s tool; got #{progress_events.size}"
@@ -273,7 +292,7 @@ def test_progress_events_have_jsonrpc_notification_shape
     @@dispatch_delay = 0.6
 
     events, _headers, _raw = sse_post(tools_call_body)
-    progress_events = events.select { |e| e[:event] == "progress" }
+    progress_events = events.select { |e| e[:kind] == :progress }
 
     assert progress_events.size >= 1, "Need at least one progress event to check shape"
 
@@ -300,7 +319,7 @@ def test_progress_token_from_client_params_echoed_in_events
     @@dispatch_delay = 0.6
 
     events, _headers, _raw = sse_post(tools_call_body(progress_token: token))
-    progress_events = events.select { |e| e[:event] == "progress" }
+    progress_events = events.select { |e| e[:kind] == :progress }
 
     assert progress_events.size >= 1, "Need progress events to verify token"
 
@@ -322,7 +341,7 @@ def test_exactly_one_response_event_in_stream
     @@dispatch_delay = 0.3
 
     events, _headers, _raw = sse_post(tools_call_body(id: 42))
-    response_events = events.select { |e| e[:event] == "response" }
+    response_events = events.select { |e| e[:kind] == :response }
 
     assert_equal 1, response_events.size,
                  "Expected exactly one response event, got #{response_events.size}"
@@ -332,7 +351,7 @@ def test_response_event_contains_valid_jsonrpc_envelope
     @@dispatch_delay = 0.15
 
     events, _headers, _raw = sse_post(tools_call_body(id: 99))
-    response_event = events.find { |e| e[:event] == "response" }
+    response_event = events.find { |e| e[:kind] == :response }
     refute_nil response_event, "No response event found in SSE stream"
 
     data = JSON.parse(response_event[:data])
@@ -353,7 +372,7 @@ def test_response_event_matches_plain_json_result
     @@dispatch_delay  = 0
 
     events, _headers, _raw = sse_post(tools_call_body(id: 7))
-    response_event = events.find { |e| e[:event] == "response" }
+    response_event = events.find { |e| e[:kind] == :response }
     refute_nil response_event
 
     data = JSON.parse(response_event[:data])
@@ -520,8 +539,8 @@ def test_multiple_concurrent_sse_connections
       Thread.new do
         events, _h, _r = sse_post(tools_call_body(id: 100 + i))
         results[i] = {
-          progress: events.count { |e| e[:event] == "progress" },
-          response: events.count { |e| e[:event] == "response" },
+          progress: events.count { |e| e[:kind] == :progress },
+          response: events.count { |e| e[:kind] == :response },
         }
       end
     end
@@ -545,8 +564,10 @@ def test_response_event_is_last_in_stream
 
     refute events.empty?, "Should have received at least one event"
     last_event = events.last
-    assert_equal "response", last_event[:event],
-                 "Final event must be 'response', got '#{last_event[:event]}'"
+    assert_equal :response, last_event[:kind],
+                 "Final frame must carry the JSON-RPC response envelope, got #{last_event[:kind].inspect}"
+    assert_equal "message", last_event[:event],
+                 "Final frame must use the wire event name 'message', got '#{last_event[:event]}'"
   end
 
   # ---------------------------------------------------------------------------
@@ -558,8 +579,8 @@ def test_progress_events_precede_response_event
 
     events, _headers, _raw = sse_post(tools_call_body)
 
-    progress_indices = events.each_index.select { |i| events[i][:event] == "progress" }
-    response_index   = events.each_index.find   { |i| events[i][:event] == "response" }
+    progress_indices = events.each_index.select { |i| events[i][:kind] == :progress }
+    response_index   = events.each_index.find   { |i| events[i][:kind] == :response }
 
     refute_nil response_index, "No response event found"
     assert progress_indices.size >= 1, "Expected at least one progress event before response"
@@ -580,7 +601,7 @@ def test_auto_generated_progress_token_is_non_empty_string
     # Do NOT supply a progressToken in the request
     events, _headers, _raw = sse_post(tools_call_body)
 
-    progress_events = events.select { |e| e[:event] == "progress" }
+    progress_events = events.select { |e| e[:kind] == :progress }
     assert progress_events.size >= 1, "Need at least one progress event"
 
     token = JSON.parse(progress_events.first[:data]).dig("params", "progressToken")