update

Author: artyomb

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stack-service-base (0.0.97)
+    stack-service-base (0.0.98)
       async
       debug
       dotenv

lib/stack-service-base/examples/mcp_config.ru

@@ -32,6 +32,35 @@ Tool :fetch do
   end
 end
 
+Tool :schema_echo do
+  description 'Echo a value using a direct JSON schema'
+  input_schema type: "object",
+               properties: {
+                 value: { type: "string", description: "Value to echo" }
+               },
+               required: ["value"]
+  annotations readOnlyHint: true
+  call do |inputs|
+    { value: inputs[:value] }
+  end
+end
+
+Tool :full_response_echo do
+  description 'Echo a value using a complete MCP tool response'
+  input value: { type: "string", description: "Value to echo", required: true }
+  call do |inputs|
+    {
+      content: [
+        { type: "text", text: inputs[:value] }
+      ],
+      structuredContent: {
+        value: inputs[:value]
+      },
+      isError: false
+    }
+  end
+end
+
 Tool :service_status do
   description 'Check current status of a service'
   input service_name: { type: "string", description: "Service name to inspect", required: true }

lib/stack-service-base/mcp/mcp_helper.rb

@@ -4,6 +4,21 @@
 MCP_PROCESSOR = McpProcessor.new
 
 module McpHelper
+  VALID_TRANSPORTS = [:sse, :json].freeze
+
+  class << self
+    def transport
+      @transport ||= :sse
+    end
+
+    def transport=(value)
+      value = value.to_sym
+      raise ArgumentError, "Unknown MCP transport: #{value}" unless VALID_TRANSPORTS.include?(value)
+
+      @transport = value
+    end
+  end
+
   def self.included(base)
     base.class_eval do
 
@@ -18,28 +33,34 @@ def self.included(base)
       end
 
       post '/mcp' do
-        content_type 'text/event-stream'
-        headers['Cache-Control'] = 'no-cache'
-        headers['X-Accel-Buffering'] = 'no'
-        headers['mcp-session-id'] = SecureRandom.uuid
         request.body&.rewind
-        body = request.body.read.to_s
 
         response_body =
           begin
-            MCP_PROCESSOR.rpc_endpoint(body)
+            MCP_PROCESSOR.rpc_endpoint(request.body.read.to_s)
           rescue McpProcessor::ParseError => e
             status e.status
             e.body
           end
 
-        LOGGER.debug "request body: #{body}"
-        LOGGER.debug "response body: #{response_body}"
+        if response_body.nil?
+          status 202
+          headers 'Content-Length' => '0'
+          ''
+        elsif McpHelper.transport == :json
+          content_type :json
+          response_body
+        else
+          content_type 'text/event-stream'
+          headers['Cache-Control'] = 'no-cache'
+          headers['X-Accel-Buffering'] = 'no'
+          headers['mcp-session-id'] = SecureRandom.uuid
 
-        stream true do |s|
-          s.callback { LOGGER.debug "stream closed: #{s}" }
-          s << "event: message\ndata: #{response_body}\n\n"
-          s.close
+          stream true do |s|
+            s.callback { LOGGER.debug "stream closed: #{s}" }
+            s << "event: message\ndata: #{response_body}\n\n"
+            s.close
+          end
         end
       end
     end

lib/stack-service-base/mcp/mcp_processor.rb

@@ -1,3 +1,5 @@
+require 'json'
+
 class JsonRpcError < StandardError
   attr_reader :code
 
@@ -15,6 +17,11 @@ def rpc_error!(code, message)
 
 class McpProcessor
   PROTOCOL_VERSION = '2025-06-18'
+  DEFAULT_SERVER_INFO = {
+    name: 'mcp-server',
+    title: 'MCP Server',
+    version: '1.0.0'
+  }.freeze
 
   include RpcErrorHelpers
   ParseError = Class.new(StandardError) do
@@ -27,7 +34,9 @@ def initialize(body:, status:)
     end
   end
 
-  def initialize(logger: LOGGER)
+  def initialize(registry: nil, server_info: DEFAULT_SERVER_INFO, logger: (defined?(LOGGER) ? LOGGER : nil))
+    @registry = registry
+    @server_info = server_info
     @logger = logger
   end
 
@@ -37,14 +46,22 @@ def root_endpoint
 
   def rpc_endpoint(raw_body)
     req = JSON.parse(raw_body.to_s)
-    rpc_response(id: req["id"], method: req["method"], params: req["params"])
-  rescue JSON::ParserError
+    method = req["method"]
+    params = req["params"]
+
+    if req.key?("id")
+      rpc_response(id: req["id"], method: method, params: params)
+    else
+      notification_response(method: method, params: params)
+    end
+  rescue JSON::ParserError => e
+    @logger&.warn("MCP JSON parse failed: #{e.message}")
     body = error_response(id: nil, code: -32700, message: "Parse error")
     raise ParseError.new(body: body, status: 400)
   end
 
   def list_tools
-    { tools: ToolRegistry.list, nextCursor: 'no-more' }
+    { tools: registry.list, nextCursor: 'no-more' }
   end
 
   def root_response
@@ -56,32 +73,47 @@ def error_response(id:, code:, message:)
   end
 
   def rpc_response(id:, method:, params:)
-    json_rpc_response(id: id) { |body| handle(method: method, params: params, body: body) }
+    json_rpc_response(id: id) { handle(method: method, params: params) }
+  end
+
+  def notification_response(method:, params:)
+    handle_notification(method: method, params: params)
+    nil
+  rescue => e
+    @logger&.error("Unhandled MCP notification error: #{e.class}: #{e.message}")
+    nil
   end
 
-  def handle(method:, params:, body: )
+  def handle(method:, params:)
     case method
     when "tools/list"  then list_tools
     # when "resources/list"  then {}
     # when "prompts/list"  then {}
     when "tools/call"  then call_tool(params || {})
-    when "initialize"  then initialize_(body)
-    when "notifications/initialized" then LOGGER.debug params; {}
-    when "logging/setLevel" then LOGGER.debug params; {}
+    when "initialize"  then initialize_response
+    when "notifications/initialized" then @logger&.debug(params); {}
+    when "logging/setLevel" then @logger&.debug(params); {}
     else
       rpc_error!(-32601, "Unknown method #{method}")
     end
   end
 
-  # https://gist.github.com/ruvnet/7b6843c457822cbcf42fc4aa635eadbb
+  def handle_notification(method:, params:)
+    case method
+    when "notifications/initialized", "notifications/cancelled"
+      @logger&.debug("MCP notification accepted: #{method}")
+    else
+      @logger&.debug("MCP notification ignored: #{method}")
+    end
+  end
 
-  def initialize_(body)
+  def initialize_(_body = nil)
+    initialize_response
+  end
+
+  def initialize_response
     {
-      serverInfo: {
-        name: 'mcp-server',
-        title: 'MCP Server',
-        version: '1.0.0'
-      },
+      serverInfo: @server_info,
       protocolVersion: PROTOCOL_VERSION,
       capabilities: {
         logging: {},
@@ -98,7 +130,7 @@ def json_rpc_response(id:)
     body = { jsonrpc: "2.0", id: id }
 
     begin
-      result = yield(body)
+      result = yield
       body[:result] = result unless body[:error] || result.nil?
     rescue JsonRpcError => e
       body[:error] = { code: e.code, message: e.message }
@@ -114,11 +146,29 @@ def json_rpc_response(id:)
   def call_tool(params)
     name      = params["name"]
     arguments = params["arguments"] || {}
-    tool      = ToolRegistry.fetch(name) || rpc_error!(-32601, "Unknown tool #{name}")
+    tool      = registry.fetch(name) || rpc_error!(-32601, "Unknown tool #{name}")
     response = tool.call_tool(arguments)
+    return response if mcp_tool_response?(response)
+
+    wrap_tool_response(response)
+  end
+
+  def registry
+    @registry || ToolRegistry.default
+  end
+
+  def mcp_tool_response?(response)
+    return false unless response.is_a?(Hash)
+
+    [:content, :structuredContent, :isError, "content", "structuredContent", "isError"].any? do |key|
+      response.key?(key)
+    end
+  end
+
+  def wrap_tool_response(response)
     {
       content: [
-        { "type": "text", "text": response.is_a?(String) ? response : response.to_json }
+        { "type": "text", "text": response.is_a?(String) ? response : JSON.dump(response) }
       ],
       isError: false
     }