Add logging support

A server can send structured logging messages to the client.
https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging#logging

Logging was specified in the 2024-11-05 specification, but since it was not supported in ruby-sdk, I implemented it.
https://modelcontextprotocol.io/specification/2024-11-05/server/utilities/logging

I also made it possible to output a simple notification message in the examples.

Author: dak2

README.md

@@ -113,6 +113,7 @@ The server provides three notification methods:
 - `notify_tools_list_changed` - Send a notification when the tools list changes
 - `notify_prompts_list_changed` - Send a notification when the prompts list changes
 - `notify_resources_list_changed` - Send a notification when the resources list changes
+- `notify_log_message` - Send a structured logging notification message
 
 #### Notification Format
 
@@ -121,6 +122,82 @@ Notifications follow the JSON-RPC 2.0 specification and use these method names:
 - `notifications/tools/list_changed`
 - `notifications/prompts/list_changed`
 - `notifications/resources/list_changed`
+- `notifications/message`
+
+### Logging
+
+The MCP Ruby SDK supports structured logging through the `notify_log_message` method, following the [MCP Logging specification](https://modelcontextprotocol.io/specification/latest/server/utilities/logging).
+
+The `notifications/message` notification is used for structured logging between client and server.
+
+#### Log Levels
+
+The SDK supports 8 log levels with increasing severity:
+
+- `debug` - Detailed debugging information
+- `info` - General informational messages
+- `notice` - Normal but significant events
+- `warning` - Warning conditions
+- `error` - Error conditions
+- `critical` - Critical conditions
+- `alert` - Action must be taken immediately
+- `emergency` - System is unusable
+
+#### How Logging Works
+
+1. **Client Configuration**: The client sends a `logging/setLevel` request to configure the minimum log level
+2. **Server Filtering**: The server only sends log messages at the configured level or higher severity
+3. **Notification Delivery**: Log messages are sent as `notifications/message` to the client
+
+For example, if the client sets the level to `"error"` (severity 4), the server will send messages with levels: `error`, `critical`, `alert`, and `emergency`.
+
+For more details, see the [MCP Logging specification](https://modelcontextprotocol.io/specification/latest/server/utilities/logging).
+
+**Usage Example:**
+
+```ruby
+server = MCP::Server.new(name: "my_server")
+transport = MCP::Server::Transports::StdioTransport.new(server)
+server.transport = transport
+
+# The client first configures the logging level (on the client side):
+transport.send_request(
+  request: {
+    jsonrpc: "2.0",
+    method: "logging/setLevel",
+    params: { level: "info" },
+    id: session_id # Unique request ID within the session
+  }
+)
+
+# Send log messages at different severity levels
+server.notify_log_message(
+  data: { message: "Application started successfully" },
+  level: "info"
+)
+
+server.notify_log_message(
+  data: { message: "Configuration file not found, using defaults" },
+  level: "warning"
+)
+
+server.notify_log_message(
+  data: {
+    error: "Database connection failed",
+    details: { host: "localhost", port: 5432 }
+  },
+  level: "error",
+  logger: "DatabaseLogger" # Optional logger name
+)
+```
+
+**Key Features:**
+
+- Supports 8 log levels (debug, info, notice, warning, error, critical, alert, emergency) based on https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging#log-levels
+- Server has capability `logging` to send log messages
+- Messages are only sent if a transport is configured
+- Messages are filtered based on the client's configured log level
+- If the log level hasn't been set by the client, no messages will be sent
 
 #### Transport Support
 
@@ -153,7 +230,6 @@ transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, statele
 
 ### Unsupported Features (to be implemented in future versions)
 
-- Log Level
 - Resource subscriptions
 - Completions
 - Elicitation

examples/streamable_http_client.rb

@@ -122,6 +122,10 @@ def main
     exit(1)
   end
 
+  if init_response[:body].dig("result", "capabilities", "logging")
+    make_request(session_id, "logging/setLevel", { level: "info" })
+  end
+
   logger.info("Session initialized: #{session_id}")
   logger.info("Server info: #{init_response[:body]["result"]["serverInfo"]}")
 

examples/streamable_http_server.rb

@@ -107,6 +107,7 @@ def call(message:, delay: 0)
         mcp_logger.error("Response error: #{parsed_response["error"]["message"]}")
       elsif parsed_response["accepted"]
         # Response was sent via SSE
+        server.notify_log_message(data: { details: "Response accepted and sent via SSE" }, level: "info")
         sse_logger.info("Response sent via SSE stream")
       else
         mcp_logger.info("Response: success (id: #{parsed_response["id"]})")

lib/json_rpc_handler.rb

@@ -105,6 +105,8 @@ def process_request(request, id_validation_pattern:, &method_finder)
       result = method.call(params)
 
       success_response(id: id, result: result)
+    rescue MCP::Server::RequestHandlerError => e
+      handle_request_error(e, id, id_validation_pattern)
     rescue StandardError => e
       error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
         code: ErrorCode::INTERNAL_ERROR,
@@ -114,6 +116,24 @@ def process_request(request, id_validation_pattern:, &method_finder)
     end
   end
 
+  def handle_request_error(error, id, id_validation_pattern)
+    error_type = error.respond_to?(:error_type) ? error.error_type : nil
+
+    code, message = case error_type
+    when :invalid_request then [ErrorCode::INVALID_REQUEST, "Invalid Request"]
+    when :invalid_params then [ErrorCode::INVALID_PARAMS, "Invalid params"]
+    when :parse_error then [ErrorCode::PARSE_ERROR, "Parse error"]
+    when :internal_error then [ErrorCode::INTERNAL_ERROR, "Internal error"]
+    else [ErrorCode::INTERNAL_ERROR, "Internal error"]
+    end
+
+    error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
+      code: code,
+      message: message,
+      data: error.message,
+    })
+  end
+
   def valid_version?(version)
     version == Version::V2_0
   end

lib/mcp/logging_message_notification.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json_rpc_handler"
+
+module MCP
+  class LoggingMessageNotification
+    LOG_LEVEL_SEVERITY = {
+      "debug" => 0,
+      "info" => 1,
+      "notice" => 2,
+      "warning" => 3,
+      "error" => 4,
+      "critical" => 5,
+      "alert" => 6,
+      "emergency" => 7,
+    }.freeze
+
+    def initialize(level:)
+      @level = level
+    end
+
+    def valid_level?
+      LOG_LEVEL_SEVERITY.keys.include?(@level)
+    end
+
+    def should_notify?(log_level)
+      return false unless LOG_LEVEL_SEVERITY.key?(log_level)
+
+      LOG_LEVEL_SEVERITY[log_level] >= LOG_LEVEL_SEVERITY[@level]
+    end
+  end
+end

lib/mcp/server.rb

@@ -3,6 +3,7 @@
 require_relative "../json_rpc_handler"
 require_relative "instrumentation"
 require_relative "methods"
+require_relative "logging_message_notification"
 
 module MCP
   class ToolNotUnique < StandardError
@@ -40,7 +41,7 @@ def initialize(method_name)
 
     include Instrumentation
 
-    attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport
+    attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
 
     def initialize(
       description: nil,
@@ -78,6 +79,7 @@ def initialize(
       validate!
 
       @capabilities = capabilities || default_capabilities
+      @logging_message_notification = nil
 
       @handlers = {
         Methods::RESOURCES_LIST => method(:list_resources),
@@ -90,12 +92,12 @@ def initialize(
         Methods::INITIALIZE => method(:init),
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
+        Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
 
         # No op handlers for currently unsupported methods
         Methods::RESOURCES_SUBSCRIBE => ->(_) {},
         Methods::RESOURCES_UNSUBSCRIBE => ->(_) {},
         Methods::COMPLETION_COMPLETE => ->(_) {},
-        Methods::LOGGING_SET_LEVEL => ->(_) {},
         Methods::ELICITATION_CREATE => ->(_) {},
       }
       @transport = transport
@@ -162,6 +164,18 @@ def notify_resources_list_changed
       report_exception(e, { notification: "resources_list_changed" })
     end
 
+    def notify_log_message(data:, level:, logger: nil)
+      return unless @transport
+      return unless logging_message_notification&.should_notify?(level)
+
+      params = { "data" => data, "level" => level }
+      params["logger"] = logger if logger
+
+      @transport.send_notification(Methods::NOTIFICATIONS_MESSAGE, params)
+    rescue => e
+      report_exception(e, { notification: "log_message" })
+    end
+
     def resources_list_handler(&block)
       @handlers[Methods::RESOURCES_LIST] = block
     end
@@ -284,6 +298,7 @@ def default_capabilities
         tools: { listChanged: true },
         prompts: { listChanged: true },
         resources: { listChanged: true },
+        logging: {},
       }
     end
 
@@ -307,6 +322,19 @@ def init(request)
       }.compact
     end
 
+    def configure_logging_level(request)
+      if capabilities[:logging].nil?
+        raise RequestHandlerError.new("Server does not support logging", request, error_type: :internal_error)
+      end
+
+      logging_message_notification = LoggingMessageNotification.new(level: request[:level])
+      unless logging_message_notification.valid_level?
+        raise RequestHandlerError.new("Invalid log level #{request[:level]}", request, error_type: :invalid_params)
+      end
+
+      @logging_message_notification = logging_message_notification
+    end
+
     def list_tools(request)
       @tools.values.map(&:to_h)
     end

test/json_rpc_handler_test.rb

@@ -398,6 +398,96 @@
       }
     end
 
+    it "returns an error with the code set to -32600 when error_type of RequestHandlerError is :invalid_request" do
+      register("test_method") do
+        raise MCP::Server::RequestHandlerError.new(
+          "Invalid request data",
+          {},
+          error_type: :invalid_request,
+        )
+      end
+
+      handle jsonrpc: "2.0", id: 1, method: "test_method"
+
+      assert_rpc_error expected_error: {
+        code: -32600,
+        message: "Invalid Request",
+        data: "Invalid request data",
+      }
+    end
+
+    it "returns an error with the code set to -32602 when error_type of RequestHandlerError is :invalid_params" do
+      register("test_method") do
+        raise MCP::Server::RequestHandlerError.new(
+          "Parameter validation failed",
+          {},
+          error_type: :invalid_params,
+        )
+      end
+
+      handle jsonrpc: "2.0", id: 1, method: "test_method"
+
+      assert_rpc_error expected_error: {
+        code: -32602,
+        message: "Invalid params",
+        data: "Parameter validation failed",
+      }
+    end
+
+    it "returns an error with the code set to -32700 when error_type of RequestHandlerError is :parse_error" do
+      register("test_method") do
+        raise MCP::Server::RequestHandlerError.new(
+          "Failed to parse input",
+          {},
+          error_type: :parse_error,
+        )
+      end
+
+      handle jsonrpc: "2.0", id: 1, method: "test_method"
+
+      assert_rpc_error expected_error: {
+        code: -32700,
+        message: "Parse error",
+        data: "Failed to parse input",
+      }
+    end
+
+    it "returns an error with the code set to -32603 when error_type of RequestHandlerError is :internal_error" do
+      register("test_method") do
+        raise MCP::Server::RequestHandlerError.new(
+          "Internal processing error",
+          {},
+          error_type: :internal_error,
+        )
+      end
+
+      handle jsonrpc: "2.0", id: 1, method: "test_method"
+
+      assert_rpc_error expected_error: {
+        code: -32603,
+        message: "Internal error",
+        data: "Internal processing error",
+      }
+    end
+
+    it "returns an error with the code set to -32603 when error_type of RequestHandlerError is unknown" do
+      register("test_method") do
+        raise MCP::Server::RequestHandlerError.new(
+          "Unknown error occurred",
+          {},
+          error_type: :unknown,
+        )
+      end
+
+      handle jsonrpc: "2.0", id: 1, method: "test_method"
+
+      assert_rpc_error expected_error: {
+        code: -32603,
+        message: "Internal error",
+        data: "Unknown error occurred",
+      }
+    end
+
     # 6 Batch
     #
     # To send several Request objects at the same time, the Client MAY send an Array filled with Request objects.