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

@@ -111,6 +111,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
 
@@ -119,6 +120,28 @@ 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`
+
+#### Notification Logging Message Flow
+
+The `notifications/message` notification is used for structured logging between client and server.
+
+1. **Client sends logging configuration**: The client first sends a `logging/setLevel` request to configure the desired log level.
+2. **Server processes and notifies**: Upon receiving the log level configuration, the server uses `notify_log_message` to send log messages at the configured level and higher priority levels.For example, if "error" is configured, the server can send "error", "critical", "alert", and "emergency" messages. Please refer to `lib/mcp/logging_message_notification.rb` for log priorities in details.
+
+##### Usage Example
+
+```ruby
+# Client sets logging level
+# Request: { "jsonrpc": "2.0", "method": "logging/setLevel", "params": { "level": "error" } }
+
+# Server sends notifications for log events
+server.notify_log_message(
+  level: "error",
+  data: { error: "Connection Failed" },
+  logger: "DatabaseLogger"
+)
+```
 
 #### Transport Support
 
@@ -139,7 +162,6 @@ server.notify_tools_list_changed
 
 ### Unsupported Features ( to be implemented in future versions )
 
-- Log Level
 - Resource subscriptions
 - Completions
 

examples/streamable_http_client.rb

@@ -123,6 +123,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

@@ -109,6 +109,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" }, log_level: "info")
         sse_logger.info("Response sent via SSE stream")
       else
         mcp_logger.info("Response: success (id: #{parsed_response["id"]})")

lib/mcp/logging_message_notification.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json_rpc_handler"
+
+module MCP
+  class LoggingMessageNotification
+    LOG_LEVELS = {
+      "emergency" => 7,
+      "alert" => 6,
+      "critical" => 5,
+      "error" => 4,
+      "warning" => 3,
+      "notice" => 2,
+      "info" => 1,
+      "debug" => 0,
+    }.freeze
+
+    attr_reader :level
+
+    class InvalidLevelError < StandardError
+      def initialize
+        super("Invalid log level provided. Valid levels are: #{LOG_LEVELS.keys.join(", ")}")
+        @code = JsonRpcHandler::ErrorCode::InvalidParams
+      end
+    end
+
+    class NotSpecifiedLevelError < StandardError
+      def initialize
+        super("Log level not specified. Please set a valid log level.")
+        @code = JsonRpcHandler::ErrorCode::InternalError
+      end
+    end
+
+    def initialize(level:)
+      @level = level
+    end
+
+    def valid_level?
+      LOG_LEVELS.keys.include?(level)
+    end
+
+    def should_notify?(log_level:)
+      LOG_LEVELS[log_level] >= LOG_LEVELS[level]
+    end
+  end
+end

lib/mcp/server.rb

@@ -3,6 +3,7 @@
 require "json_rpc_handler"
 require_relative "instrumentation"
 require_relative "methods"
+require_relative "logging_message_notification"
 
 module MCP
   class Server
@@ -31,7 +32,7 @@ def initialize(method_name)
 
     include Instrumentation
 
-    attr_accessor :name, :version, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport
+    attr_accessor :name, :version, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
 
     def initialize(
       name: "model_context_protocol",
@@ -63,6 +64,7 @@ def initialize(
       end
 
       @capabilities = capabilities || default_capabilities
+      @logging_message_notification = nil
 
       @handlers = {
         Methods::RESOURCES_LIST => method(:list_resources),
@@ -75,12 +77,12 @@ def initialize(
         Methods::INITIALIZE => method(:init),
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
+        Methods::LOGGING_SET_LEVEL => method(:logging_level=),
 
         # No op handlers for currently unsupported methods
         Methods::RESOURCES_SUBSCRIBE => ->(_) {},
         Methods::RESOURCES_UNSUBSCRIBE => ->(_) {},
         Methods::COMPLETION_COMPLETE => ->(_) {},
-        Methods::LOGGING_SET_LEVEL => ->(_) {},
       }
       @transport = transport
     end
@@ -139,6 +141,20 @@ def notify_resources_list_changed
       report_exception(e, { notification: "resources_list_changed" })
     end
 
+    def notify_log_message(data:, log_level:, logger: nil)
+      return unless @transport
+      raise LoggingMessageNotification::NotSpecifiedLevelError unless logging_message_notification&.level
+
+      return unless logging_message_notification.should_notify?(log_level:)
+
+      params = { data:, level: log_level }
+      params[:logger] = logger if logger
+
+      @transport.send_notification(Methods::NOTIFICATIONS_MESSAGE, params)
+    rescue => e
+      report_exception(e, { notification: "logging_message_notification" })
+    end
+
     def resources_list_handler(&block)
       @handlers[Methods::RESOURCES_LIST] = block
     end
@@ -212,6 +228,7 @@ def default_capabilities
         tools: { listChanged: true },
         prompts: { listChanged: true },
         resources: { listChanged: true },
+        logging: {},
       }
     end
 
@@ -231,6 +248,13 @@ def init(request)
       }.compact
     end
 
+    def logging_level=(params)
+      logging_message_notification = LoggingMessageNotification.new(level: params[:level])
+      raise LoggingMessageNotification::InvalidLevelError unless logging_message_notification.valid_level?
+
+      @logging_message_notification = logging_message_notification
+    end
+
     def list_tools(request)
       @tools.map { |_, tool| tool.to_h }
     end

test/mcp/logging_message_notification_test.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module MCP
+  class LoggingMessageNotificationTest < ActiveSupport::TestCase
+    test "valid_level? returns true for valid levels" do
+      LoggingMessageNotification::LOG_LEVELS.keys.each do |level|
+        logging_message_notification = LoggingMessageNotification.new(level: level)
+        assert logging_message_notification.valid_level?, "#{level} should be valid"
+      end
+    end
+
+    test "valid_level? returns false for invalid levels" do
+      invalid_levels = ["invalid", 1, "", nil, :fatal]
+      invalid_levels.each do |level|
+        logging_message_notification = LoggingMessageNotification.new(level: level)
+        refute logging_message_notification.valid_level?, "#{level} should be invalid"
+      end
+    end
+
+    test "InvalidLevelError has correct error code" do
+      error = LoggingMessageNotification::InvalidLevelError.new
+      assert_equal(-32602, error.instance_variable_get(:@code))
+    end
+
+    test "InvalidLevelError message format" do
+      error = LoggingMessageNotification::InvalidLevelError.new
+      expected_levels = LoggingMessageNotification::LOG_LEVELS.keys.join(", ")
+      expected_message = "Invalid log level provided. Valid levels are: #{expected_levels}"
+
+      assert_equal expected_message, error.message
+    end
+
+    test "NotSpecifiedLevelError has correct error code" do
+      error = LoggingMessageNotification::NotSpecifiedLevelError.new
+      assert_equal(-32603, error.instance_variable_get(:@code))
+    end
+
+    test "NotSpecifiedLevelError has correct message" do
+      error = LoggingMessageNotification::NotSpecifiedLevelError.new
+      expected_message = "Log level not specified. Please set a valid log level."
+
+      assert_equal expected_message, error.message
+    end
+
+    test "should_notify? returns true when notification level is higher priority than threshold level or equals to it" do
+      logging_message_notification = LoggingMessageNotification.new(level: "warning")
+      assert logging_message_notification.should_notify?(log_level: "warning")
+      assert logging_message_notification.should_notify?(log_level: "error")
+      assert logging_message_notification.should_notify?(log_level: "critical")
+      assert logging_message_notification.should_notify?(log_level: "alert")
+      assert logging_message_notification.should_notify?(log_level: "emergency")
+    end
+
+    test "should_notify? returns false when notification level is lower priority than threshold level" do
+      logging_message_notification = LoggingMessageNotification.new(level: "warning")
+      refute logging_message_notification.should_notify?(log_level: "notice")
+      refute logging_message_notification.should_notify?(log_level: "info")
+      refute logging_message_notification.should_notify?(log_level: "debug")
+    end
+  end
+end

test/mcp/server/transports/stdio_notification_integration_test.rb

@@ -79,8 +79,12 @@ def closed?
           # Test resources notification
           @server.notify_resources_list_changed
 
+          # Test log notification
+          @server.logging_message_notification = MCP::LoggingMessageNotification.new(level: "error")
+          @server.notify_log_message(data: { error: "Connection Failed" }, log_level: "error")
+
           # Check the notifications were sent
-          assert_equal 3, @mock_stdout.output.size
+          assert_equal 4, @mock_stdout.output.size
 
           # Parse and verify each notification
           notifications = @mock_stdout.output.map { |msg| JSON.parse(msg) }
@@ -96,6 +100,10 @@ def closed?
           assert_equal "2.0", notifications[2]["jsonrpc"]
           assert_equal Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED, notifications[2]["method"]
           assert_nil notifications[2]["params"]
+
+          assert_equal "2.0", notifications[3]["jsonrpc"]
+          assert_equal Methods::NOTIFICATIONS_MESSAGE, notifications[3]["method"]
+          assert_equal({ "level" => "error", "data" => { "error" => "Connection Failed" } }, notifications[3]["params"])
         end
 
         test "notifications include params when provided" do
@@ -120,6 +128,7 @@ def closed?
             @server.notify_tools_list_changed
             @server.notify_prompts_list_changed
             @server.notify_resources_list_changed
+            @server.notify_log_message(data: { error: "Connection Failed" }, log_level: "error")
           end
         end
 
@@ -240,6 +249,16 @@ def puts(message)
           assert_equal 2, @mock_stdout.output.size
           second_notification = JSON.parse(@mock_stdout.output.last)
           assert_equal Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED, second_notification["method"]
+
+          # Set log level and notify
+          @server.logging_message_notification = MCP::LoggingMessageNotification.new(level: "error")
+
+          # Manually trigger notification
+          @server.notify_log_message(data: { error: "Connection Failed" }, log_level: "error")
+          assert_equal 3, @mock_stdout.output.size
+          third_notification = JSON.parse(@mock_stdout.output.last)
+          assert_equal Methods::NOTIFICATIONS_MESSAGE, third_notification["method"]
+          assert_equal({ "data" => { "error" => "Connection Failed" }, "level" => "error" }, third_notification["params"])
         end
       end
     end

test/mcp/server/transports/streamable_http_notification_integration_test.rb

@@ -51,13 +51,20 @@ class StreamableHTTPNotificationIntegrationTest < ActiveSupport::TestCase
           # Test resources notification
           @server.notify_resources_list_changed
 
+          # Set log level to error for log notification
+          @server.logging_message_notification = MCP::LoggingMessageNotification.new(level: "error")
+
+          # Test log notification
+          @server.notify_log_message(data: { error: "Connection Failed" }, log_level: "error")
+
           # Check the notifications were received
           io.rewind
           output = io.read
 
           assert_includes output, "data: {\"jsonrpc\":\"2.0\",\"method\":\"#{Methods::NOTIFICATIONS_TOOLS_LIST_CHANGED}\"}"
           assert_includes output, "data: {\"jsonrpc\":\"2.0\",\"method\":\"#{Methods::NOTIFICATIONS_PROMPTS_LIST_CHANGED}\"}"
           assert_includes output, "data: {\"jsonrpc\":\"2.0\",\"method\":\"#{Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED}\"}"
+          assert_includes output, "data: {\"jsonrpc\":\"2.0\",\"method\":\"#{Methods::NOTIFICATIONS_MESSAGE}\",\"params\":{\"data\":{\"error\":\"Connection Failed\"},\"level\":\"error\"}}\n\n"
         end
 
         test "notifications are broadcast to all connected sessions" do
@@ -147,6 +154,7 @@ class StreamableHTTPNotificationIntegrationTest < ActiveSupport::TestCase
             @server.notify_tools_list_changed
             @server.notify_prompts_list_changed
             @server.notify_resources_list_changed
+            @server.notify_log_message(data: { error: "Connection Failed" }, log_level: "error")
           end
         end