Add notification support

Co-authored-by: Kevin Fischer <[email protected]>

Author: Ginja

README.md

@@ -34,6 +34,7 @@ It implements the Model Context Protocol specification, handling model context r
 - Supports prompt registration and execution
 - Supports resource registration and retrieval
 - Supports stdio & Streamable HTTP (including SSE) transports
+- Supports notifications for list changes (tools, prompts, resources)
 
 ### Supported Methods
 - `initialize` - Initializes the protocol and returns server capabilities
@@ -46,13 +47,46 @@ It implements the Model Context Protocol specification, handling model context r
 - `resources/read` - Retrieves a specific resource by name
 - `resources/templates/list` - Lists all registered resource templates and their schemas
 
+### Notifications
+
+The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.
+
+#### Notification Methods
+
+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
+
+#### Notification Format
+
+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`
+
+#### Transport Support
+
+- **HTTP Transport**: Notifications are sent as Server-Sent Events (SSE) to all connected sessions
+- **Stdio Transport**: Notifications are sent as JSON-RPC 2.0 messages to stdout
+
+#### Usage Example
+
+```ruby
+server = MCP::Server.new(name: "my_server")
+transport = MCP::Transports::HTTP.new(server)
+server.transport = transport
+
+# When tools change, notify clients
+server.define_tool(name: "new_tool") { |**args| { result: "ok" } }
+server.notify_tools_list_changed()
+```
+
 ### Unsupported Features ( to be implemented in future versions )
 
-- Notifications
 - Log Level
 - Resource subscriptions
 - Completions
-- Complete Streamable HTTP implementation with streaming responses
 
 ### Usage
 

lib/mcp/methods.rb

@@ -21,6 +21,11 @@ module Methods
 
     SAMPLING_CREATE_MESSAGE = "sampling/createMessage"
 
+    # Notification methods
+    NOTIFICATIONS_TOOLS_LIST_CHANGED = "notifications/tools/list_changed"
+    NOTIFICATIONS_PROMPTS_LIST_CHANGED = "notifications/prompts/list_changed"
+    NOTIFICATIONS_RESOURCES_LIST_CHANGED = "notifications/resources/list_changed"
+
     class MissingRequiredCapabilityError < StandardError
       attr_reader :method
       attr_reader :capability

lib/mcp/server.rb

@@ -93,6 +93,30 @@ def define_prompt(name: nil, description: nil, arguments: [], &block)
       @prompts[prompt.name_value] = prompt
     end
 
+    def notify_tools_list_changed
+      return unless @transport
+
+      @transport.send_notification(Methods::NOTIFICATIONS_TOOLS_LIST_CHANGED)
+    rescue => e
+      report_exception(e, { notification: "tools_list_changed" })
+    end
+
+    def notify_prompts_list_changed
+      return unless @transport
+
+      @transport.send_notification(Methods::NOTIFICATIONS_PROMPTS_LIST_CHANGED)
+    rescue => e
+      report_exception(e, { notification: "prompts_list_changed" })
+    end
+
+    def notify_resources_list_changed
+      return unless @transport
+
+      @transport.send_notification(Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED)
+    rescue => e
+      report_exception(e, { notification: "resources_list_changed" })
+    end
+
     def resources_list_handler(&block)
       @handlers[Methods::RESOURCES_LIST] = block
     end

lib/mcp/transports/stdio.rb

@@ -36,6 +36,20 @@ def send_response(message)
         $stdout.puts(json_message)
         $stdout.flush
       end
+
+      def send_notification(method, params = nil)
+        notification = {
+          jsonrpc: "2.0",
+          method: method
+        }
+        notification[:params] = params if params
+        
+        send_response(notification)
+        true
+      rescue => e
+        MCP.configuration.exception_reporter.call(e, { error: "Failed to send notification" })
+        false
+      end
     end
   end
 end

test/mcp/server_notification_test.rb

@@ -0,0 +1,136 @@
+# typed: true
+# frozen_string_literal: true
+
+require "test_helper"
+
+module MCP
+  class ServerNotificationTest < ActiveSupport::TestCase
+    include InstrumentationTestHelper
+
+    class MockTransport < Transport
+      attr_reader :notifications
+
+      def initialize(server)
+        super
+        @notifications = []
+      end
+
+      def send_notification(method, params = nil)
+        @notifications << { method: method, params: params }
+        true
+      end
+
+      def send_response(response); end
+      def open; end
+      def close; end
+      def handle_request(request); end
+    end
+
+    setup do
+      configuration = MCP::Configuration.new
+      configuration.instrumentation_callback = instrumentation_helper.callback
+      
+      @server = Server.new(
+        name: "test_server",
+        version: "1.0.0",
+        configuration: configuration
+      )
+      
+      @mock_transport = MockTransport.new(@server)
+      @server.transport = @mock_transport
+    end
+
+    test "#notify_tools_list_changed sends notification through transport" do
+      @server.notify_tools_list_changed
+
+      assert_equal 1, @mock_transport.notifications.size
+      notification = @mock_transport.notifications.first
+      assert_equal Methods::NOTIFICATIONS_TOOLS_LIST_CHANGED, notification[:method]
+      assert_nil notification[:params]
+    end
+
+    test "#notify_prompts_list_changed sends notification through transport" do
+      @server.notify_prompts_list_changed
+
+      assert_equal 1, @mock_transport.notifications.size
+      notification = @mock_transport.notifications.first
+      assert_equal Methods::NOTIFICATIONS_PROMPTS_LIST_CHANGED, notification[:method]
+      assert_nil notification[:params]
+    end
+
+    test "#notify_resources_list_changed sends notification through transport" do
+      @server.notify_resources_list_changed
+
+      assert_equal 1, @mock_transport.notifications.size
+      notification = @mock_transport.notifications.first
+      assert_equal Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED, notification[:method]
+      assert_nil notification[:params]
+    end
+
+    test "notification methods work without transport" do
+      server_without_transport = Server.new(name: "test_server")
+      
+      # Should not raise any errors
+      assert_nothing_raised do
+        server_without_transport.notify_tools_list_changed
+        server_without_transport.notify_prompts_list_changed
+        server_without_transport.notify_resources_list_changed
+      end
+    end
+
+    test "notification methods handle transport errors gracefully" do
+      # Create a transport that raises errors
+      error_transport = Class.new(MockTransport) do
+        def send_notification(method, params = nil)
+          raise StandardError, "Transport error"
+        end
+      end.new(@server)
+      
+      @server.transport = error_transport
+      
+      # Mock the exception reporter
+      expected_contexts = [
+        { notification: "tools_list_changed" },
+        { notification: "prompts_list_changed" },
+        { notification: "resources_list_changed" }
+      ]
+      
+      call_count = 0
+      @server.configuration.exception_reporter.expects(:call).times(3).with do |exception, context|
+        assert_kind_of StandardError, exception
+        assert_equal "Transport error", exception.message
+        assert_includes expected_contexts, context
+        call_count += 1
+        true
+      end
+      
+      # Should not raise errors to the caller
+      assert_nothing_raised do
+        @server.notify_tools_list_changed
+        @server.notify_prompts_list_changed
+        @server.notify_resources_list_changed
+      end
+      
+      assert_equal 3, call_count
+    end
+
+    test "multiple notification methods can be called in sequence" do
+      @server.notify_tools_list_changed
+      @server.notify_prompts_list_changed
+      @server.notify_resources_list_changed
+
+      assert_equal 3, @mock_transport.notifications.size
+      
+      notifications = @mock_transport.notifications
+      assert_equal Methods::NOTIFICATIONS_TOOLS_LIST_CHANGED, notifications[0][:method]
+      assert_equal Methods::NOTIFICATIONS_PROMPTS_LIST_CHANGED, notifications[1][:method]
+      assert_equal Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED, notifications[2][:method]
+    end
+
+    test "notification method constants are defined correctly" do
+      assert_equal "notifications/tools/list_changed", Methods::NOTIFICATIONS_TOOLS_LIST_CHANGED
+      assert_equal "notifications/prompts/list_changed", Methods::NOTIFICATIONS_PROMPTS_LIST_CHANGED
+      assert_equal "notifications/resources/list_changed", Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED
+    end
+  end
+end