model-context-protocol-rb 0.4.0 → 0.5.1

data/README.md

@@ -1,28 +1,26 @@
 # 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
 
 - [Feature Support (Server)](#feature-support-server)
-- [Usage](#usage)
-  - [Building an MCP Server](#building-an-mcp-server)
-    - [Server Configuration Options](#server-configuration-options)
-    - [Pagination Configuration Options](#pagination-configuration-options)
-    - [Transport Configuration Options](#transport-configuration-options)
-      - [STDIO Transport](#stdio-transport)
-      - [Streamable HTTP Transport](#streamable-http-transport)
-    - [Registry Configuration Options](#registry-configuration-options)
-  - [Integration with Rails](#integration-with-rails)
-  - [Server features](#server-features)
-    - [Prompts](#prompts)
-    - [Resources](#resources)
-    - [Resource Templates](#resource-templates)
-    - [Tools](#tools)
-    - [Completions](#completions)
+- [Quick Start with Rails](#quick-start-with-rails)
 - [Installation](#installation)
+- [Building an MCP Server](#building-an-mcp-server)
+  - [Server Configuration Options](#server-configuration-options)
+  - [Pagination Configuration Options](#pagination-configuration-options)
+  - [Transport Configuration Options](#transport-configuration-options)
+  - [Redis Configuration](#redis-configuration)
+  - [Registry Configuration Options](#registry-configuration-options)
+- [Prompts](#prompts)
+- [Resources](#resources)
+- [Resource Templates](#resource-templates)
+- [Tools](#tools)
+- [Completions](#completions)
 - [Development](#development)
-  - [Releases](#releases)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -44,19 +42,148 @@ 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) |
+
+## Quick Start with Rails
+
+The `model-context-protocol-rb` works out of the box with any valid Rack request. Currently, this project has no plans for building a deeper Rails integration, but it is fairly simple to build it out yourself. To support modern application deployments across multiple servers, the streamable HTTP transport requires Redis as an external dependency.
+
+Here's an example of how you can easily integrate with Rails.
+
+First, configure Redis in an initializer:
+
+```ruby
+# config/initializers/model_context_protocol.rb
+require "model_context_protocol"
+
+ModelContextProtocol::Server.configure_redis do |config|
+  config.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
+  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
+  get "/mcp", to: "model_context_protocol#handle", as: :mcp_get
+  post "/mcp", to: "model_context_protocol#handle", as: :mcp_post
+  delete "/mcp", to: "model_context_protocol#handle", as: :mcp_delete
+end
+```
+
+Then, implement a controller endpoint to handle the requests.
+
+```ruby
+class ModelContextProtocolController < ActionController::API
+  include ActionController::Live
+
+  before_action :authenticate_user
+
+  def handle
+    server = ModelContextProtocol::Server.new do |config|
+      config.name = "MyMCPServer"
+      config.title = "My MCP Server"
+      config.version = "1.0.0"
+      config.logging_enabled = true
+      config.registry = build_registry
+      config.context = {
+        user_id: current_user.id,
+        request_id: request.id
+      }
+      config.transport = {
+        type: :streamable_http,
+        env: request.env
+      }
+      config.instructions = <<~INSTRUCTIONS
+        This server provides prompts, tools, and resources for interacting with my app.
+
+        Key capabilities:
+        - Does this one thing
+        - Does this other thing
+        - Oh, yeah, and it does that one thing, too
+
+        Use this server when you need to do stuff.
+      INSTRUCTIONS
+    end
+
+    result = server.start
+    handle_mcp_response(result)
+  end
+
+  private
+
+  def build_registry
+    ModelContextProtocol::Server::Registry.new do
+      tools do
+        # Implement user authorization logic to dynamically build registry
+        register TestTool if current_user.authorized_for?(TestTool)
+      end
+    end
+  end
+
+  def handle_mcp_response(result)
+    if result[:headers]&.dig("Content-Type") == "text/event-stream"
+      setup_streaming_headers
+      stream_response(result[:stream_proc])
+    else
+      render_json_response(result)
+    end
+  end
+
+  def setup_streaming_headers
+    response.headers.merge!(
+      "Content-Type" => "text/event-stream",
+      "Cache-Control" => "no-cache",
+      "Connection" => "keep-alive"
+    )
+  end
+
+  def stream_response(stream_proc)
+    stream_proc&.call(response.stream)
+  ensure
+    response.stream.close rescue nil
+  end
+
+  def render_json_response(result)
+    render json: result[:json],
+      status: result[:status] || 200,
+      headers: result[:headers] || {}
+  end
+end
+```
 
-## Usage
+Read more about the [server configuration options](building-an-mcp-server) to better understand how you can customize your MCP server.
 
-Include `model_context_protocol` in your project.
+From here, you can get started building [prompts](#prompts), [resources](#resources), [resource templates](#resource-templates), and [tools](#tools).
+
+## Installation
+
+Add this line to your application's Gemfile:
 
 ```ruby
-require 'model_context_protocol'
+gem 'model-context-protocol-rb'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+Or install it yourself as:
+
+```bash
+gem install model-context-protocol-rb
 ```
 
-### Building an MCP Server
+## Building an MCP Server
 
 Build a simple MCP server by registering your prompts, resources, resource templates, and tools. Then, configure and run the server. Messages from the MCP client will be routed to the appropriate custom handler. This SDK provides several classes that should be used to build your handlers.
 
@@ -116,7 +243,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)
   # }
 
@@ -144,7 +271,7 @@ end
 server.start
 ```
 
-#### Server Configuration Options
+### Server Configuration Options
 
 The following table details all available configuration options for the MCP server:
 
@@ -160,7 +287,7 @@ The following table details all available configuration options for the MCP serv
 | `transport` | Hash | No | `{ type: :stdio }` | Transport configuration |
 | `registry` | Registry | Yes | - | Registry containing prompts, resources, and tools |
 
-#### Pagination Configuration Options
+### Pagination Configuration Options
 
 When `pagination` is set to a Hash, the following options are available:
 
@@ -172,26 +299,55 @@ When `pagination` is set to a Hash, the following options are available:
 
 **Note:** Set `config.pagination = false` to completely disable pagination support.
 
-#### Transport Configuration Options
+### Transport Configuration Options
 
 The transport configuration supports two types: `:stdio` (default) and `:streamable_http`.
 
-##### STDIO Transport
+#### STDIO Transport
+
 ```ruby
 config.transport = { type: :stdio }  # This is the default, can be omitted
 ```
 
-##### Streamable HTTP Transport
-When using `:streamable_http`, the following options are available:
+#### Streamable HTTP Transport
+
+```ruby
+config.transport = { type: :streamable_http, env: request.env }
+```
+
+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) |
 
-#### Registry Configuration Options
+### Redis Configuration
+
+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 |
+
+### Registry Configuration Options
 
 The registry is configured using `ModelContextProtocol::Server::Registry.new` and supports the following block types:
 
@@ -222,83 +378,9 @@ config.registry = ModelContextProtocol::Server::Registry.new do
 end
 ```
 
-#### Integration with Rails
-
-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:
-
-```ruby
-constraints format: :json do
-  get "/mcp", to: "model_context_protocol#handle", as: :mcp_get
-  post "/mcp", to: "model_context_protocol#handle", as: :mcp_post
-  delete "/mcp", to: "model_context_protocol#handle", as: :mcp_delete
-end
-```
-
-Then, implement a controller endpoint to handle the requests.
-
-```ruby
-require 'model_context_protocol'
-
-class ModelContextProtocolController < ApplicationController
-  before_action :authenticate_user
-
-  def handle
-    server = ModelContextProtocol::Server.new do |config|
-      config.name = "MyMCPServer"
-      config.title = "My MCP Server"
-      config.version = "1.0.0"
-      config.logging_enabled = true
-      config.context = {
-        user_id: current_user.id,
-        request_id: request.id
-      }
-      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
-      }
-      config.instructions = <<~INSTRUCTIONS
-        This server provides prompts, tools, and resources for interacting with my app.
-
-        Key capabilities:
-        - Does this one thing
-        - Does this other thing
-        - Oh, yeah, and it does that one thing, too
-
-        Use this server when you need to do stuff.
-      INSTRUCTIONS
-    end
-
-    result = server.start
-
-    # For SSE responses
-    if result[:stream]
-      response.headers.merge!(result[:headers] || {})
-      response.content_type = result[:headers]["Content-Type"] || "text/event-stream"
-      # Handle streaming with result[:stream_proc]
-    else
-      # For regular JSON responses
-      render json: result[:json], status: result[:status], headers: result[:headers]
-    end
-  end
-
-  private
-
-  def build_registry
-    ModelContextProtocol::Server::Registry.new do
-      tools do
-        # Implement user authorization logic to dynamically build registry
-        register TestTool if current_user.authorized_for?(TestTool)
-      end
-    end
-  end
-end
-```
-
-### Prompts
+## Prompts
 
 The `ModelContextProtocol::Server::Prompt` base class allows subclasses to define a prompt that the MCP client can use.
 
@@ -306,7 +388,7 @@ Define the prompt properties and then implement the `call` method to build your
 
 You can also log from within your prompt by calling a valid logger level method on the `logger` and passing a string message.
 
-#### Prompt Definition
+### Prompt Definition
 
 Use the `define` block to set [prompt properties](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/prompts/) and configure arguments.
 
@@ -317,7 +399,7 @@ Use the `define` block to set [prompt properties](https://spec.modelcontextproto
 | `description` | Short description of what the prompt does |
 | `argument` | Define an argument block with name, description, required flag, and completion |
 
-#### Argument Definition
+### Argument Definition
 
 Define any arguments using `argument` blocks nested within the `define` block. You can mark an argument as required, and you can optionally provide a completion class. See [Completions](#completions) for more information.
 
@@ -328,18 +410,20 @@ Define any arguments using `argument` blocks nested within the `define` block. Y
 | `required` | Whether the argument is required (boolean) |
 | `completion` | Available hints for completions (array or completion class) |
 
-#### Prompt Methods
+### 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:`) |
 
-#### Message History DSL
+### Message History DSL
 
 Build a message history using the an intuitive DSL, creating an ordered history of user and assistant messages with flexible content blocks that can include text, image, audio, embedded resources, and resource links.
 
@@ -348,7 +432,7 @@ Build a message history using the an intuitive DSL, creating an ordered history
 | `user_message` | Within `message_history` | Create a message with user role |
 | `assistant_message` | Within `message_history` | Create a message with assistant role |
 
-#### Content Blocks
+### Content Blocks
 
 Use content blocks to properly format the content included in messages.
 
@@ -360,7 +444,7 @@ Use content blocks to properly format the content included in messages.
 | `embedded_resource_content` | Within message blocks | Create embedded resource content block (requires `resource:`) |
 | `resource_link` | Within message blocks | Create resource link content block (requires `name:` and `uri:`) |
 
-#### Available Instance Variables
+### Available Instance Variables
 
 The `arguments` passed from an MCP client are available, as well as the `context` values passed in at server initialization.
 
@@ -370,7 +454,7 @@ The `arguments` passed from an MCP client are available, as well as the `context
 | `context` | Within `call` | Hash containing server configuration context values |
 | `logger` | Within `call` | Logger instance for logging (e.g., `logger.info("message")`) |
 
-#### Examples
+### Examples
 
 This is an example prompt that returns a properly formatted response:
 
@@ -449,13 +533,15 @@ class TestPrompt < ModelContextProtocol::Server::Prompt
 end
 ```
 
-### Resources
+---
+
+## Resources
 
 The `ModelContextProtocol::Server::Resource` base class allows subclasses to define a resource that the MCP client can use.
 
 Define the resource properties and optionally annotations, then implement the `call` method to build your resource. Use the `respond_with` instance method to ensure your resource responds with appropriately formatted response data.
 
-#### Resource Definition
+### Resource Definition
 
 Use the `define` block to set [resource properties](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/resources/) and configure annotations.
 
@@ -468,7 +554,7 @@ Use the `define` block to set [resource properties](https://spec.modelcontextpro
 | `uri` | URI identifier for the resource |
 | `annotations` | Block for defining resource annotations |
 
-#### Annotation Definition
+### Annotation Definition
 
 Define any [resource annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations) using an `annotations` block nested within the `define` block.
 
@@ -478,17 +564,19 @@ Define any [resource annotations](https://modelcontextprotocol.io/specification/
 | `priority` | Priority level (numeric value, e.g., `0.9`) |
 | `last_modified` | Last modified timestamp (ISO 8601 string) |
 
-#### Resource Methods
+### 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
+### Available Instance Variables
 
 Resources are stateless and only have access to their configured properties.
 
@@ -497,7 +585,7 @@ Resources are stateless and only have access to their configured properties.
 | `mime_type` | Within `call` | The configured MIME type for this resource |
 | `uri` | Within `call` | The configured URI identifier for this resource |
 
-#### Examples
+### Examples
 
 This is an example resource that returns a text response:
 
@@ -559,13 +647,15 @@ class TestBinaryResource < ModelContextProtocol::Server::Resource
 end
 ```
 
-### Resource Templates
+---
+
+## Resource Templates
 
 The `ModelContextProtocol::Server::ResourceTemplate` base class allows subclasses to define a resource template that the MCP client can use.
 
 Define the resource template properties and URI template with optional parameter completions. Resource templates are used to define parameterized resources that clients can instantiate.
 
-#### Resource Template Definition
+### Resource Template Definition
 
 Use the `define` block to set [resource template properties](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#resource-templates).
 
@@ -576,7 +666,7 @@ Use the `define` block to set [resource template properties](https://modelcontex
 | `mime_type` | MIME type of resources created from this template |
 | `uri_template` | URI template with parameters (e.g., `"file:///{name}"`) |
 
-#### URI Template Configuration
+### URI Template Configuration
 
 Define the URI template and configure parameter completions within the `uri_template` block.
 
@@ -584,7 +674,7 @@ Define the URI template and configure parameter completions within the `uri_temp
 |--------|---------|-------------|
 | `completion` | Within `uri_template` block | Define completion for a URI parameter (e.g., `completion :name, ["value1", "value2"]`) |
 
-#### Resource Template Methods
+### Resource Template Methods
 
 Resource templates only use the `define` method to configure their properties - they don't have a `call` method.
 
@@ -592,7 +682,7 @@ Resource templates only use the `define` method to configure their properties -
 |--------|---------|-------------|
 | `define` | Class definition | Block for defining resource template metadata and URI template |
 
-#### Examples
+### Examples
 
 This is an example resource template that provides a completion for a parameter of the URI template:
 
@@ -628,13 +718,15 @@ class TestResourceTemplate < ModelContextProtocol::Server::ResourceTemplate
 end
 ```
 
-### Tools
+---
+
+## Tools
 
 The `ModelContextProtocol::Server::Tool` base class allows subclasses to define a tool that the MCP client can use.
 
 Define the tool properties and schemas, then implement the `call` method to build your tool response. Arguments from the MCP client and server context are available, along with logging capabilities.
 
-#### Tool Definition
+### Tool Definition
 
 Use the `define` block to set [tool properties](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/tools/) and configure schemas.
 
@@ -646,17 +738,19 @@ Use the `define` block to set [tool properties](https://spec.modelcontextprotoco
 | `input_schema` | JSON schema block for validating tool inputs |
 | `output_schema` | JSON schema block for validating structured content outputs |
 
-#### Tool Methods
+### 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
+### Content Blocks
 
 Use content blocks to properly format the content included in tool responses.
 
@@ -668,7 +762,7 @@ Use content blocks to properly format the content included in tool responses.
 | `embedded_resource_content` | Within `call` | Create embedded resource content block (requires `resource:`) |
 | `resource_link` | Within `call` | Create resource link content block (requires `name:` and `uri:`) |
 
-#### Response Types
+### Response Types
 
 Tools can return different types of responses using `respond_with`.
 
@@ -679,7 +773,7 @@ Tools can return different types of responses using `respond_with`.
 | `content:` | `respond_with content: [content_blocks]` | Return array of mixed content blocks |
 | `error:` | `respond_with error: "message"` | Return tool error response |
 
-#### Available Instance Variables
+### Available Instance Variables
 
 Arguments from MCP clients and server context are available, along with logging capabilities.
 
@@ -689,7 +783,7 @@ Arguments from MCP clients and server context are available, along with logging
 | `context` | Within `call` | Hash containing server configuration context values |
 | `logger` | Within `call` | Logger instance for logging (e.g., `logger.info("message")`) |
 
-#### Examples
+### Examples
 
 This is an example of a tool that returns structured content validated by an output schema:
 
@@ -973,13 +1067,96 @@ class TestToolWithToolErrorResponse < ModelContextProtocol::Server::Tool
 end
 ```
 
-### Completions
+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.
 
 Implement the `call` method to build your completion logic using the provided argument name and value. Completions are simpler than other server features - they don't use a `define` block and only provide filtered suggestion lists.
 
-#### Completion Methods
+### Completion Methods
 
 Completions only implement the `call` method to provide completion logic.
 
@@ -988,7 +1165,7 @@ Completions only implement the `call` method to provide completion logic.
 | `call` | Instance method | Main method to implement completion logic and build response |
 | `respond_with` | Within `call` | Return properly formatted completion response (e.g., `respond_with values:`) |
 
-#### Available Instance Variables
+### Available Instance Variables
 
 Completions receive the argument name and current value being completed.
 
@@ -997,7 +1174,7 @@ Completions receive the argument name and current value being completed.
 | `argument_name` | Within `call` | String name of the argument being completed |
 | `argument_value` | Within `call` | Current partial value being typed by the user |
 
-#### Examples
+### Examples
 
 This is an example completion that returns an array of values in the response:
 
@@ -1014,38 +1191,40 @@ class TestCompletion < ModelContextProtocol::Server::Completion
 end
 ```
 
-## Installation
+---
 
-Add this line to your application's Gemfile:
+## Development
 
-```ruby
-gem 'model-context-protocol-rb'
-```
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests.
 
-And then execute:
+### Generate Development Servers
+
+Generate executables that you can use for testing:
 
 ```bash
-bundle
+# generates bin/dev for STDIO transport
+bundle exec rake mcp:generate_stdio_server
+
+# generates bin/dev-http for streamable HTTP transport
+bundle exec rake mcp:generate_streamable_http_server
 ```
 
-Or install it yourself as:
+If you need to test with HTTPS (e.g., for clients that require SSL), generate self-signed certificates:
 
 ```bash
-gem install model-context-protocol-rb
+# 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"
 ```
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests.
-
-Generate executables that you can use for testing:
+The HTTP server supports both HTTP and HTTPS:
 
 ```bash
-# generates bin/dev for STDIO transport
-bundle exec rake mcp:generate_stdio_server
+# Run HTTP server (default)
+bin/dev-http
 
-# generates bin/dev-http for streamable HTTP transport
-bundle exec rake mcp:generate_streamable_http_server
+# 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.