model-context-protocol-rb 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cb9fa1e4fc1430df1df1bd454f3f718cf3693afb7b412976751e7f44f56a10e
-  data.tar.gz: fc70eac6a64674c886cc246bb3fcc0efcf956f27d406d511cc833fe33a11fc77
+  metadata.gz: 5f97580e7f9c5723d25472b545c037bad650d82434865324c6d1dd450ac4031e
+  data.tar.gz: 1b73ad6036c7ded852210dc338190675e419c6f6354e027d2b7073a5e655c665
 SHA512:
-  metadata.gz: c2819592f7f0e3c3360e5265a0e15f73a92e6a4d439fc3fb86fcce99c41f8e08e03fd361bd1a8c31968c05334e55957a169c5f33f4586380347178edc89fb851
-  data.tar.gz: ba81388d3e7f1b7f903c6eb3f2094cbdc37d8a8e5ff9af605855d07708dab8fea5cf1c642a5e1e92e0121e5b2207fe1ac99ae563c21c0e0ead6d7157a53ecf4e
+  metadata.gz: 3075cfc900a60fd1cb83b973c23f6f517373f6132ab043ea64079653bbc0ecc5c5aeb8a077e2c685396f9921d80ad341f9fa271fd343fb9b9f29ce93b6abda4b
+  data.tar.gz: c72619fea381f8968d7dd33e60c306449973bbeda9f5a8ffd6b8d5baf95d26df8278a2106b82daeef61982a950b74b5f168a8afb680baa6e44f10d26626cac69

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.5.0] - 2025-09-22
+
+- Make streamable HTTP transport thread-safe by using Redis to manage state.
+- Implement Redis connection pooling with robust management and configuration.
+- Automatically upgrade connection to SSE to send notifications.
+- Add support for cancellations and progress notifications via `cancellable` and `progressable` blocks in prompts, resources, and tools.
+
 ## [0.4.0] - 2025-09-07
 
 - Implement pagination support.
@@ -67,7 +74,8 @@
 
 - Initial release
 
-[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.4...v0.4.0
 [0.3.4]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.2...v0.3.3

data/README.md

@@ -1,6 +1,8 @@
 # model-context-protocol-rb
 
-An implementation of the [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/specification/2025-06-18/) in Ruby. You are welcome to contribute.
+An implementation of the [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/specification/2025-06-18/) in Ruby.
+
+Provides simple abstractions that allow you to serve prompts, resources, resource templates, and tools via MCP locally (stdio) or in production (streamable HTTP backed by Redis) with minimal effort.
 
 ## Table of Contents
 
@@ -44,9 +46,9 @@ An implementation of the [Model Context Protocol (MCP)](https://spec.modelcontex
 | ❌ | [List Changed Notification (Resources)](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#list-changed-notification) |
 | ❌ | [Subscriptions (Resources)](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#subscriptions) |
 | ❌ | [List Changed Notification (Tools)](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#list-changed-notification) |
-| ❌ | [Cancellation](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/cancellation) |
+| ✅ | [Cancellation](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/cancellation) |
 | ✅ | [Ping](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/ping) |
-| ❌ | [Progress](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress) |
+| ✅ | [Progress](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress) |
 
 ## Usage
 
@@ -116,7 +118,7 @@ server = ModelContextProtocol::Server.new do |config|
   # Optional: configure streamable HTTP transport if required
   # config.transport = {
   #   type: :streamable_http,
-  #   redis_client: Redis.new(url: ENV['REDIS_URL']),
+  #   env: request.env,
   #   session_ttl: 3600 # Optional: session timeout in seconds (default: 3600)
   # }
 
@@ -182,12 +184,33 @@ config.transport = { type: :stdio }  # This is the default, can be omitted
 ```
 
 ##### Streamable HTTP Transport
-When using `:streamable_http`, the following options are available:
+The `:streamable_http` transport requires Redis to be configured globally before use:
+
+```ruby
+ModelContextProtocol::Server.configure_redis do |config|
+  config.redis_url = ENV.fetch('REDIS_URL')
+  config.pool_size = 20
+  config.pool_timeout = 5
+  config.enable_reaper = true
+  config.reaper_interval = 60
+  config.idle_timeout = 300
+end
+```
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `redis_url` | String | Yes | - | Redis connection URL |
+| `pool_size` | Integer | No | `20` | Connection pool size |
+| `pool_timeout` | Integer | No | `5` | Pool checkout timeout in seconds |
+| `enable_reaper` | Boolean | No | `true` | Enable connection reaping |
+| `reaper_interval` | Integer | No | `60` | Reaper check interval in seconds |
+| `idle_timeout` | Integer | No | `300` | Idle connection timeout in seconds |
+
+When using `:streamable_http` transport, the following options are available:
 
 | Option | Type | Required | Default | Description |
 |--------|------|----------|---------|-------------|
 | `type` | Symbol | Yes | `:stdio` | Must be `:streamable_http` for HTTP transport |
-| `redis_client` | Redis | Yes | - | Redis client instance for session management |
 | `session_ttl` | Integer | No | `3600` | Session timeout in seconds (1 hour) |
 | `env` | Hash | No | - | Rack environment hash (for Rails integration) |
 
@@ -226,7 +249,21 @@ end
 
 The streamable HTTP transport works with any valid Rack request. Here's an example of how you can integrate with Rails.
 
-First, set the routes:
+First, configure Redis in an initializer:
+
+```ruby
+# config/initializers/model_context_protocol.rb
+ModelContextProtocol::Server.configure_redis do |config|
+  config.redis_url = ENV.fetch('REDIS_URL')
+  config.pool_size = 20
+  config.pool_timeout = 5
+  config.enable_reaper = true
+  config.reaper_interval = 60
+  config.idle_timeout = 300
+end
+```
+
+Then, set the routes:
 
 ```ruby
 constraints format: :json do
@@ -257,8 +294,7 @@ class ModelContextProtocolController < ApplicationController
       config.registry = build_registry
       config.transport = {
         type: :streamable_http,
-        redis_client: Redis.new(url: ENV['REDIS_URL']), # Prefer initializing a client from a connection pool
-        env: request.env                                # Rack environment hash
+        env: request.env
       }
       config.instructions = <<~INSTRUCTIONS
         This server provides prompts, tools, and resources for interacting with my app.
@@ -330,12 +366,14 @@ Define any arguments using `argument` blocks nested within the `define` block. Y
 
 #### Prompt Methods
 
-Define your prompt properties and arguments, implement the `call` method using the `message_history` DSL to build prompt messages and `respond_with` to serialize them.
+Define your prompt properties and arguments, implement the `call` method using the `message_history` DSL to build prompt messages and `respond_with` to serialize them. You can wrap long running operations in a `cancellable` block to allow clients to cancel the request. Also, you can automatically send progress notifications to clients by wrapping long-running operations in a `progressable` block.
 
 | Method | Context | Description |
 |--------|---------|-------------|
 | `define` | Class definition | Block for defining prompt metadata and arguments |
 | `call` | Instance method | Main method to implement prompt logic and build response |
+| `cancellable` | Within `call` | Wrap long-running operations to allow client cancellation (e.g., `cancellable { slow_operation }`) |
+| `progressable` | Within `call` | Wrap long-running operations to send clients progress notifications (e.g., `progressable { slow_operation }`) |
 | `message_history` | Within `call` | DSL method to build an array of user and assistant messages |
 | `respond_with` | Within `call` | Return properly formatted response data (e.g., `respond_with messages:`) |
 
@@ -480,12 +518,14 @@ Define any [resource annotations](https://modelcontextprotocol.io/specification/
 
 #### Resource Methods
 
-Define your resource properties and annotations, implement the `call` method to build resource content and `respond_with` to serialize the response.
+Define your resource properties and annotations, implement the `call` method to build resource content and `respond_with` to serialize the response. You can wrap long running operations in a `cancellable` block to allow clients to cancel the request. Also, you can automatically send progress notifications to clients by wrapping long-running operations in a `progressable` block.
 
 | Method | Context | Description |
 |--------|---------|-------------|
 | `define` | Class definition | Block for defining resource metadata and annotations |
 | `call` | Instance method | Main method to implement resource logic and build response |
+| `cancellable` | Within `call` | Wrap long-running operations to allow client cancellation (e.g., `cancellable { slow_operation }`) |
+| `progressable` | Within `call` | Wrap long-running operations to send clients progress notifications (e.g., `progressable { slow_operation }`) |
 | `respond_with` | Within `call` | Return properly formatted response data (e.g., `respond_with text:` or `respond_with binary:`) |
 
 #### Available Instance Variables
@@ -648,12 +688,14 @@ Use the `define` block to set [tool properties](https://spec.modelcontextprotoco
 
 #### Tool Methods
 
-Define your tool properties and schemas, implement the `call` method using content helpers and `respond_with` to serialize responses.
+Define your tool properties and schemas, implement the `call` method using content helpers and `respond_with` to serialize responses. You can wrap long running operations in a `cancellable` block to allow clients to cancel the request. Also, you can automatically send progress notifications to clients by wrapping long-running operations in a `progressable` block.
 
 | Method | Context | Description |
 |--------|---------|-------------|
 | `define` | Class definition | Block for defining tool metadata and schemas |
 | `call` | Instance method | Main method to implement tool logic and build response |
+| `cancellable` | Within `call` | Wrap long-running operations to allow client cancellation (e.g., `cancellable { slow_operation }`) |
+| `progressable` | Within `call` | Wrap long-running operations to send clients progress notifications (e.g., `progressable { slow_operation }`) |
 | `respond_with` | Within `call` | Return properly formatted response data with various content types |
 
 #### Content Blocks
@@ -973,6 +1015,87 @@ class TestToolWithToolErrorResponse < ModelContextProtocol::Server::Tool
 end
 ```
 
+This is an example of a tool that allows a client to cancel a long-running operation:
+
+```ruby
+class TestToolWithCancellableSleep < ModelContextProtocol::Server::Tool
+  define do
+    name "cancellable_sleep"
+    title "Cancellable Sleep Tool"
+    description "Sleep for 3 seconds with cancellation support"
+    input_schema do
+      {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      }
+    end
+  end
+
+  def call
+    logger.info("Starting 3 second sleep operation")
+
+    result = cancellable do
+      sleep 3
+      "Sleep completed successfully"
+    end
+
+    respond_with content: text_content(text: result)
+  end
+end
+```
+
+This is an example of a tool that automatically sends progress notifications to the client and allows the client to cancel the operation:
+
+```ruby
+class TestToolWithProgressableAndCancellable < ModelContextProtocol::Server::Tool
+  define do
+    name "test_tool_with_progressable_and_cancellable"
+    description "A test tool that demonstrates combined progressable and cancellable functionality"
+
+    input_schema do
+      {
+        type: "object",
+        properties: {
+          max_duration: {
+            type: "number",
+            description: "Expected maximum duration in seconds"
+          },
+          work_steps: {
+            type: "number",
+            description: "Number of work steps to perform"
+          }
+        },
+        required: ["max_duration"]
+      }
+    end
+  end
+
+  def call
+    max_duration = arguments[:max_duration] || 10
+    work_steps = arguments[:work_steps] || 10
+    logger.info("Starting progressable call with max_duration=#{max_duration}, work_steps=#{work_steps}")
+
+    result = progressable(max_duration:, message: "Processing #{work_steps} items") do
+      cancellable do
+        processed_items = []
+
+        work_steps.times do |i|
+          sleep(max_duration / work_steps.to_f)
+          processed_items << "item_#{i + 1}"
+        end
+
+        processed_items
+      end
+    end
+
+    response = text_content(text: "Successfully processed #{result.length} items: #{result.join(", ")}")
+
+    respond_with content: response
+  end
+end
+```
+
 ### Completions
 
 The `ModelContextProtocol::Server::Completion` base class allows subclasses to define a completion that the MCP client can use to obtain hints or suggestions for arguments to prompts and resources.
@@ -1038,6 +1161,8 @@ gem install model-context-protocol-rb
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests.
 
+### Generate Development Servers
+
 Generate executables that you can use for testing:
 
 ```bash
@@ -1048,6 +1173,24 @@ bundle exec rake mcp:generate_stdio_server
 bundle exec rake mcp:generate_streamable_http_server
 ```
 
+If you need to test with HTTPS (e.g., for clients that require SSL), generate self-signed certificates:
+
+```bash
+# Create SSL directory and generate certificates
+mkdir -p tmp/ssl
+openssl req -x509 -newkey rsa:4096 -keyout tmp/ssl/server.key -out tmp/ssl/server.crt -days 365 -nodes -subj "/C=US/ST=Dev/L=Dev/O=Dev/CN=localhost"
+```
+
+The HTTP server supports both HTTP and HTTPS:
+
+```bash
+# Run HTTP server (default)
+bin/dev-http
+
+# Run HTTPS server (requires SSL certificates in tmp/ssl/)
+SSL=true bin/dev-http
+```
+
 You can also run `bin/console` for an interactive prompt that will allow you to experiment. Execute command `rp` to reload the project.
 
 To install this gem onto your local machine, run `bundle exec rake install`.

data/lib/model_context_protocol/server/cancellable.rb

@@ -0,0 +1,54 @@
+require "concurrent-ruby"
+
+module ModelContextProtocol
+  module Server::Cancellable
+    # Raised when a request has been cancelled by the client
+    class CancellationError < StandardError; end
+
+    # Execute a block with automatic cancellation support for blocking I/O operations.
+    # This method uses Concurrent::TimerTask to poll for cancellation every 100ms
+    # and can interrupt even blocking operations like HTTP requests or database queries.
+    #
+    # @param interval [Float] polling interval in seconds (default: 0.1)
+    # @yield block to execute with cancellation support
+    # @return [Object] the result of the block
+    # @raise [CancellationError] if the request is cancelled during execution
+    #
+    # @example
+    #   cancellable do
+    #     response = Net::HTTP.get(URI('https://slow-api.example.com'))
+    #     process_response(response)
+    #   end
+    def cancellable(interval: 0.1, &block)
+      context = Thread.current[:mcp_context]
+      executing_thread = Concurrent::AtomicReference.new(nil)
+
+      timer_task = Concurrent::TimerTask.new(execution_interval: interval) do
+        if context && context[:request_store] && context[:request_id]
+          if context[:request_store].cancelled?(context[:request_id])
+            thread = executing_thread.get
+            thread&.raise(CancellationError, "Request was cancelled") if thread&.alive?
+          end
+        end
+      end
+
+      begin
+        executing_thread.set(Thread.current)
+
+        if context && context[:request_store] && context[:request_id]
+          if context[:request_store].cancelled?(context[:request_id])
+            raise CancellationError, "Request #{context[:request_id]} was cancelled"
+          end
+        end
+
+        timer_task.execute
+
+        result = block.call
+        result
+      ensure
+        executing_thread.set(nil)
+        timer_task&.shutdown if timer_task&.running?
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/configuration.rb

@@ -200,15 +200,10 @@ module ModelContextProtocol
     end
 
     def validate_streamable_http_transport!
-      options = transport_options
-
-      unless options[:redis_client]
-        raise InvalidTransportError, "streamable_http transport requires redis_client option"
-      end
-
-      redis_client = options[:redis_client]
-      unless redis_client.respond_to?(:hset) && redis_client.respond_to?(:expire)
-        raise InvalidTransportError, "redis_client must be a Redis-compatible client"
+      unless ModelContextProtocol::Server::RedisConfig.configured?
+        raise InvalidTransportError,
+          "streamable_http transport requires Redis configuration. " \
+          "Call ModelContextProtocol::Server.configure_redis in an initializer."
       end
     end
 

data/lib/model_context_protocol/server/progressable.rb

@@ -0,0 +1,72 @@
+require "concurrent-ruby"
+
+module ModelContextProtocol
+  module Server::Progressable
+    # Execute a block with automatic time-based progress reporting.
+    # Uses Concurrent::TimerTask to send progress notifications at regular intervals.
+    #
+    # @param max_duration [Numeric] Expected duration in seconds
+    # @param message [String, nil] Optional custom progress message
+    # @yield block to execute with progress tracking
+    # @return [Object] the result of the block
+    #
+    # @example
+    #   progressable(max_duration: 30) do  # 30 seconds
+    #     perform_long_operation
+    #   end
+    def progressable(max_duration:, message: nil, &block)
+      context = Thread.current[:mcp_context]
+
+      return yield unless context && context[:progress_token] && context[:transport]
+
+      progress_token = context[:progress_token]
+      transport = context[:transport]
+      start_time = Time.now
+      update_interval = [1.0, max_duration * 0.05].max
+
+      timer_task = Concurrent::TimerTask.new(execution_interval: update_interval) do
+        elapsed_seconds = Time.now - start_time
+        progress_pct = [(elapsed_seconds / max_duration) * 100, 99].min
+
+        progress_message = if message
+          "#{message} (#{elapsed_seconds.round(1)}s / ~#{max_duration}s)"
+        else
+          "Processing... (#{elapsed_seconds.round(1)}s / ~#{max_duration}s)"
+        end
+
+        begin
+          transport.send_notification("notifications/progress", {
+            progressToken: progress_token,
+            progress: progress_pct.round(1),
+            total: 100,
+            message: progress_message
+          })
+        rescue
+          nil
+        end
+
+        timer_task.shutdown if elapsed_seconds >= max_duration
+      end
+
+      begin
+        timer_task.execute
+        result = yield
+
+        begin
+          transport.send_notification("notifications/progress", {
+            progressToken: progress_token,
+            progress: 100,
+            total: 100,
+            message: "Completed"
+          })
+        rescue
+          nil
+        end
+
+        result
+      ensure
+        timer_task&.shutdown if timer_task&.running?
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/prompt.rb

@@ -1,6 +1,8 @@
 module ModelContextProtocol
   class Server::Prompt
-    include Server::ContentHelpers
+    include ModelContextProtocol::Server::Cancellable
+    include ModelContextProtocol::Server::ContentHelpers
+    include ModelContextProtocol::Server::Progressable
 
     attr_reader :arguments, :context, :logger
 

data/lib/model_context_protocol/server/redis_client_proxy.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Server
+    class RedisClientProxy
+      def initialize(pool)
+        @pool = pool
+      end
+
+      def get(key)
+        with_connection { |redis| redis.get(key) }
+      end
+
+      def set(key, value, **options)
+        with_connection { |redis| redis.set(key, value, **options) }
+      end
+
+      def del(*keys)
+        with_connection { |redis| redis.del(*keys) }
+      end
+
+      def exists(*keys)
+        with_connection { |redis| redis.exists(*keys) }
+      end
+
+      def expire(key, seconds)
+        with_connection { |redis| redis.expire(key, seconds) }
+      end
+
+      def ttl(key)
+        with_connection { |redis| redis.ttl(key) }
+      end
+
+      def hget(key, field)
+        with_connection { |redis| redis.hget(key, field) }
+      end
+
+      def hset(key, *args)
+        with_connection { |redis| redis.hset(key, *args) }
+      end
+
+      def hgetall(key)
+        with_connection { |redis| redis.hgetall(key) }
+      end
+
+      def lpush(key, *values)
+        with_connection { |redis| redis.lpush(key, *values) }
+      end
+
+      def rpop(key)
+        with_connection { |redis| redis.rpop(key) }
+      end
+
+      def lrange(key, start, stop)
+        with_connection { |redis| redis.lrange(key, start, stop) }
+      end
+
+      def llen(key)
+        with_connection { |redis| redis.llen(key) }
+      end
+
+      def ltrim(key, start, stop)
+        with_connection { |redis| redis.ltrim(key, start, stop) }
+      end
+
+      def incr(key)
+        with_connection { |redis| redis.incr(key) }
+      end
+
+      def decr(key)
+        with_connection { |redis| redis.decr(key) }
+      end
+
+      def keys(pattern)
+        with_connection { |redis| redis.keys(pattern) }
+      end
+
+      def multi(&block)
+        with_connection do |redis|
+          redis.multi do |multi|
+            multi_wrapper = RedisMultiWrapper.new(multi)
+            block.call(multi_wrapper)
+          end
+        end
+      end
+
+      def pipelined(&block)
+        with_connection do |redis|
+          redis.pipelined do |pipeline|
+            pipeline_wrapper = RedisMultiWrapper.new(pipeline)
+            block.call(pipeline_wrapper)
+          end
+        end
+      end
+
+      def mget(*keys)
+        with_connection { |redis| redis.mget(*keys) }
+      end
+
+      def eval(script, keys: [], argv: [])
+        with_connection { |redis| redis.eval(script, keys: keys, argv: argv) }
+      end
+
+      def ping
+        with_connection { |redis| redis.ping }
+      end
+
+      def flushdb
+        with_connection { |redis| redis.flushdb }
+      end
+
+      private
+
+      def with_connection(&block)
+        @pool.with(&block)
+      end
+
+      # Wrapper for Redis multi/pipeline operations
+      class RedisMultiWrapper
+        def initialize(multi)
+          @multi = multi
+        end
+
+        def method_missing(method, *args, **kwargs, &block)
+          @multi.send(method, *args, **kwargs, &block)
+        end
+
+        def respond_to_missing?(method, include_private = false)
+          @multi.respond_to?(method, include_private)
+        end
+      end
+    end
+  end
+end