mcp 0.1.0 → 0.3.0

data/README.md

@@ -1,6 +1,6 @@
-# Model Context Protocol
+# MCP Ruby SDK [![Gem Version](https://img.shields.io/gem/v/mcp)](https://rubygems.org/gems/mcp) [![MIT licensed](https://img.shields.io/badge/license-MIT-green)](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/LICENSE.txt) [![CI](https://github.com/modelcontextprotocol/ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/modelcontextprotocol/ruby-sdk/actions/workflows/ci.yml)
 
-A Ruby gem for implementing Model Context Protocol servers
+The official Ruby SDK for Model Context Protocol servers and clients.
 
 ## Installation
 
@@ -12,29 +12,35 @@ gem 'mcp'
 
 And then execute:
 
-```bash
+```console
 $ bundle install
 ```
 
 Or install it yourself as:
 
-```bash
+```console
 $ gem install mcp
 ```
 
-## MCP Server
+You may need to add additional dependencies depending on which features you wish to access.
+
+## Building an MCP Server
 
 The `MCP::Server` class is the core component that handles JSON-RPC requests and responses.
 It implements the Model Context Protocol specification, handling model context requests and responses.
 
 ### Key Features
+
 - Implements JSON-RPC 2.0 message handling
 - Supports protocol initialization and capability negotiation
 - Manages tool registration and invocation
 - 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
 - `ping` - Simple health check
 - `tools/list` - Lists all registered tools and their schemas
@@ -45,31 +51,118 @@ 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
 
+### Custom Methods
+
+The server allows you to define custom JSON-RPC methods beyond the standard MCP protocol methods using the `define_custom_method` method:
+
+```ruby
+server = MCP::Server.new(name: "my_server")
+
+# Define a custom method that returns a result
+server.define_custom_method(method_name: "add") do |params|
+  params[:a] + params[:b]
+end
+
+# Define a custom notification method (returns nil)
+server.define_custom_method(method_name: "notify") do |params|
+  # Process notification
+  nil
+end
+```
+
+**Key Features:**
+
+- Accepts any method name as a string
+- Block receives the request parameters as a hash
+- Can handle both regular methods (with responses) and notifications
+- Prevents overriding existing MCP protocol methods
+- Supports instrumentation callbacks for monitoring
+
+**Usage Example:**
+
+```ruby
+# Client request
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "add",
+  "params": { "a": 5, "b": 3 }
+}
+
+# Server response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": 8
+}
+```
+
+**Error Handling:**
+
+- Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method
+- Supports the same exception reporting and instrumentation as standard methods
+
+### 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
+
+- **stdio**: Notifications are sent as JSON-RPC 2.0 messages to stdout
+- **Streamable HTTP**: Notifications are sent as JSON-RPC 2.0 messages over HTTP with streaming (chunked transfer or SSE)
+
+#### 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 StreamableHTTP implementation with streaming responses
 
 ### Usage
 
 #### Rails Controller
 
 When added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming
-[StreamableHTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport
+[Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport
 requests.
 
 You can use the `Server#handle_json` method to handle requests.
 
 ```ruby
 class ApplicationController < ActionController::Base
-
   def index
     server = MCP::Server.new(
       name: "my_server",
+      title: "Example Server Display Name", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
       version: "1.0.0",
+      instructions: "Use the tools of this server as a last resort",
       tools: [SomeTool, AnotherTool],
       prompts: [MyPrompt],
       server_context: { user_id: current_user.id },
@@ -84,9 +177,8 @@ end
 If you want to build a local command-line application, you can use the stdio transport:
 
 ```ruby
-#!/usr/bin/env ruby
 require "mcp"
-require "mcp/transports/stdio"
+require "mcp/server/transports/stdio_transport"
 
 # Create a simple tool
 class ExampleTool < MCP::Tool
@@ -115,20 +207,20 @@ server = MCP::Server.new(
 )
 
 # Create and start the transport
-transport = MCP::Transports::StdioTransport.new(server)
+transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open
 ```
 
 You can run this script and then type in requests to the server at the command line.
 
-```
-$ ./stdio_server.rb
-{"jsonrpc":"2.0","id":"1","result":"pong"}
-{"jsonrpc":"2.0","id":"2","result":["ExampleTool"]}
-{"jsonrpc":"2.0","id":"3","result":["ExampleTool"]}
+```console
+$ ruby examples/stdio_server.rb
+{"jsonrpc":"2.0","id":"1","method":"ping"}
+{"jsonrpc":"2.0","id":"2","method":"tools/list"}
+{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"example_tool","arguments":{"message":"Hello"}}}
 ```
 
-## Configuration
+### Configuration
 
 The gem can be configured using the `MCP.configure` block:
 
@@ -179,11 +271,13 @@ server = MCP::Server.new(
 The `server_context` is a user-defined hash that is passed into the server instance and made available to tools, prompts, and exception/instrumentation callbacks. It can be used to provide contextual information such as authentication state, user IDs, or request-specific data.
 
 **Type:**
+
 ```ruby
 server_context: { [String, Symbol] => Any }
 ```
 
 **Example:**
+
 ```ruby
 server = MCP::Server.new(
   name: "my_server",
@@ -203,6 +297,7 @@ The exception reporter receives:
 - `server_context`: The context hash provided to the server
 
 **Signature:**
+
 ```ruby
 exception_reporter = ->(exception, server_context) { ... }
 ```
@@ -219,12 +314,14 @@ The instrumentation callback receives a hash with the following possible keys:
 - `duration`: (Float) Duration of the call in seconds
 
 **Type:**
+
 ```ruby
 instrumentation_callback = ->(data) { ... }
 # where data is a Hash with keys as described above
 ```
 
 **Example:**
+
 ```ruby
 config.instrumentation_callback = ->(data) {
   puts "Instrumentation: #{data.inspect}"
@@ -233,19 +330,22 @@ config.instrumentation_callback = ->(data) {
 
 ### Server Protocol Version
 
-The server's protocol version can be overridden using the `protocol_version` class method:
+The server's protocol version can be overridden using the `protocol_version` keyword argument:
 
 ```ruby
-MCP::Server.protocol_version = "2024-11-05"
+configuration = MCP::Configuration.new(protocol_version: "2024-11-05")
+MCP::Server.new(name: "test_server", configuration: configuration)
 ```
 
 This will make all new server instances use the specified protocol version instead of the default version. The protocol version can be reset to the default by setting it to `nil`:
 
 ```ruby
-MCP::Server.protocol_version = nil
+MCP::Configuration.new(protocol_version: nil)
 ```
 
-Be sure to check the [MCP spec](https://spec.modelcontextprotocol.io/specification/2024-11-05/) for the protocol version to understand the supported features for the version being set.
+If an invalid `protocol_version` value is set, an `ArgumentError` is raised.
+
+Be sure to check the [MCP spec](https://modelcontextprotocol.io/specification/versioning) for the protocol version to understand the supported features for the version being set.
 
 ### Exception Reporting
 
@@ -267,16 +367,17 @@ When an exception occurs:
 
 If no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.
 
-## Tools
+### Tools
 
-MCP spec includes [Tools](https://modelcontextprotocol.io/docs/concepts/tools) which provide functionality to LLM apps.
+MCP spec includes [Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) which provide functionality to LLM apps.
 
-This gem provides a `MCP::Tool` class that can be used to create tools in two ways:
+This gem provides a `MCP::Tool` class that can be used to create tools in three ways:
 
 1. As a class definition:
 
 ```ruby
 class MyTool < MCP::Tool
+  title "My Tool" # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description "This tool performs specific functionality..."
   input_schema(
     properties: {
@@ -284,12 +385,20 @@ class MyTool < MCP::Tool
     },
     required: ["message"]
   )
+  output_schema(
+    properties: {
+      result: { type: "string" },
+      success: { type: "boolean" },
+      timestamp: { type: "string", format: "date-time" }
+    },
+    required: ["result", "success", "timestamp"]
+  )
   annotations(
-    title: "My Tool",
     read_only_hint: true,
     destructive_hint: false,
     idempotent_hint: true,
-    open_world_hint: false
+    open_world_hint: false,
+    title: "My Tool"
   )
 
   def self.call(message:, server_context:)
@@ -304,6 +413,23 @@ tool = MyTool
 
 ```ruby
 tool = MCP::Tool.define(
+  name: "my_tool",
+  title: "My Tool", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
+  description: "This tool performs specific functionality...",
+  annotations: {
+    read_only_hint: true,
+    title: "My Tool"
+  }
+) do |args, server_context|
+  MCP::Tool::Response.new([{ type: "text", text: "OK" }])
+end
+```
+
+3. By using the `ModelContextProtocol::Server#define_tool` method with a block:
+
+```ruby
+server = ModelContextProtocol::Server.new
+server.define_tool(
   name: "my_tool",
   description: "This tool performs specific functionality...",
   annotations: {
@@ -322,28 +448,128 @@ e.g. around authentication state.
 
 Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
 
+- `destructive_hint`: Indicates if the tool performs destructive operations. Defaults to true
+- `idempotent_hint`: Indicates if the tool's operations are idempotent. Defaults to false
+- `open_world_hint`: Indicates if the tool operates in an open world context. Defaults to true
+- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state). Defaults to false
 - `title`: A human-readable title for the tool
-- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state)
-- `destructive_hint`: Indicates if the tool performs destructive operations
-- `idempotent_hint`: Indicates if the tool's operations are idempotent
-- `open_world_hint`: Indicates if the tool operates in an open world context
 
 Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
 
-## Prompts
+> [!NOTE]
+> This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.
+
+### Tool Output Schemas
+
+Tools can optionally define an `output_schema` to specify the expected structure of their results. This works similarly to how `input_schema` is defined and can be used in three ways:
+
+1. **Class definition with output_schema:**
+
+```ruby
+class WeatherTool < MCP::Tool
+  tool_name "get_weather"
+  description "Get current weather for a location"
+
+  input_schema(
+    properties: {
+      location: { type: "string" },
+      units: { type: "string", enum: ["celsius", "fahrenheit"] }
+    },
+    required: ["location"]
+  )
+
+  output_schema(
+    properties: {
+      temperature: { type: "number" },
+      condition: { type: "string" },
+      humidity: { type: "integer" }
+    },
+    required: ["temperature", "condition", "humidity"]
+  )
+
+  def self.call(location:, units: "celsius", server_context:)
+    # Call weather API and structure the response
+    api_response = WeatherAPI.fetch(location, units)
+    weather_data = {
+      temperature: api_response.temp,
+      condition: api_response.description,
+      humidity: api_response.humidity_percent
+    }
+
+    output_schema.validate_result(weather_data)
+
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: weather_data.to_json
+    }])
+  end
+end
+```
+
+2. **Using Tool.define with output_schema:**
+
+```ruby
+tool = MCP::Tool.define(
+  name: "calculate_stats",
+  description: "Calculate statistics for a dataset",
+  input_schema: {
+    properties: {
+      numbers: { type: "array", items: { type: "number" } }
+    },
+    required: ["numbers"]
+  },
+  output_schema: {
+    properties: {
+      mean: { type: "number" },
+      median: { type: "number" },
+      count: { type: "integer" }
+    },
+    required: ["mean", "median", "count"]
+  }
+) do |args, server_context|
+  # Calculate statistics and validate against schema
+  MCP::Tool::Response.new([{ type: "text", text: "Statistics calculated" }])
+end
+```
+
+3. **Using OutputSchema objects:**
+
+```ruby
+class DataTool < MCP::Tool
+  output_schema MCP::Tool::OutputSchema.new(
+    properties: {
+      success: { type: "boolean" },
+      data: { type: "object" }
+    },
+    required: ["success"]
+  )
+end
+```
+
+MCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema) specifies that:
+
+- **Server Validation**: Servers MUST provide structured results that conform to the output schema
+- **Client Validation**: Clients SHOULD validate structured results against the output schema
+- **Better Integration**: Enables strict schema validation, type information, and improved developer experience
+- **Backward Compatibility**: Tools returning structured content SHOULD also include serialized JSON in a TextContent block
+
+The output schema follows standard JSON Schema format and helps ensure consistent data exchange between MCP servers and clients.
 
-MCP spec includes [Prompts](https://modelcontextprotocol.io/docs/concepts/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.
+### Prompts
 
-The `MCP::Prompt` class provides two ways to create prompts:
+MCP spec includes [Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.
+
+The `MCP::Prompt` class provides three ways to create prompts:
 
 1. As a class definition with metadata:
 
 ```ruby
 class MyPrompt < MCP::Prompt
   prompt_name "my_prompt"  # Optional - defaults to underscored class name
+  title "My Prompt" # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description "This prompt performs specific functionality..."
   arguments [
-    Prompt::Argument.new(
+    MCP::Prompt::Argument.new(
       name: "message",
       description: "Input message",
       required: true
@@ -352,16 +578,16 @@ class MyPrompt < MCP::Prompt
 
   class << self
     def template(args, server_context:)
-      Prompt::Result.new(
+      MCP::Prompt::Result.new(
         description: "Response description",
         messages: [
-          Prompt::Message.new(
+          MCP::Prompt::Message.new(
             role: "user",
-            content: Content::Text.new("User message")
+            content: MCP::Content::Text.new("User message")
           ),
-          Prompt::Message.new(
+          MCP::Prompt::Message.new(
             role: "assistant",
-            content: Content::Text.new(args["message"])
+            content: MCP::Content::Text.new(args["message"])
           )
         ]
       )
@@ -376,6 +602,38 @@ prompt = MyPrompt
 
 ```ruby
 prompt = MCP::Prompt.define(
+  name: "my_prompt",
+  title: "My Prompt", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
+  description: "This prompt performs specific functionality...",
+  arguments: [
+    MCP::Prompt::Argument.new(
+      name: "message",
+      description: "Input message",
+      required: true
+    )
+  ]
+) do |args, server_context:|
+  MCP::Prompt::Result.new(
+    description: "Response description",
+    messages: [
+      MCP::Prompt::Message.new(
+        role: "user",
+        content: MCP::Content::Text.new("User message")
+      ),
+      MCP::Prompt::Message.new(
+        role: "assistant",
+        content: MCP::Content::Text.new(args["message"])
+      )
+    ]
+  )
+end
+```
+
+3. Using the `ModelContextProtocol::Server#define_protocol` method:
+
+```ruby
+server = ModelContextProtocol::Server.new
+server.define_protocol(
   name: "my_prompt",
   description: "This prompt performs specific functionality...",
   arguments: [
@@ -407,10 +665,10 @@ e.g. around authentication state or user preferences.
 
 ### Key Components
 
-- `Prompt::Argument` - Defines input parameters for the prompt template
-- `Prompt::Message` - Represents a message in the conversation with a role and content
-- `Prompt::Result` - The output of a prompt template containing description and messages
-- `Content::Text` - Text content for messages
+- `MCP::Prompt::Argument` - Defines input parameters for the prompt template
+- `MCP::Prompt::Message` - Represents a message in the conversation with a role and content
+- `MCP::Prompt::Result` - The output of a prompt template containing description and messages
+- `MCP::Content::Text` - Text content for messages
 
 ### Usage
 
@@ -438,32 +696,37 @@ To register a handler pass a proc/lambda to as `instrumentation_callback` into t
 MCP.configure do |config|
   config.instrumentation_callback = ->(data) {
     puts "Got instrumentation data #{data.inspect}"
-  end
-}
+  }
+end
 ```
 
 The data contains the following keys:
-`method`: the metod called, e.g. `ping`, `tools/list`, `tools/call` etc
-`tool_name`: the name of the tool called
-`prompt_name`: the name of the prompt called
-`resource_uri`: the uri of the resource called
-`error`: if looking up tools/prompts etc failed, e.g. `tool_not_found`
-`duration`: the duration of the call in seconds
+
+- `method`: the method called, e.g. `ping`, `tools/list`, `tools/call` etc
+- `tool_name`: the name of the tool called
+- `prompt_name`: the name of the prompt called
+- `resource_uri`: the uri of the resource called
+- `error`: if looking up tools/prompts etc failed, e.g. `tool_not_found`
+- `duration`: the duration of the call in seconds
 
 `tool_name`, `prompt_name` and `resource_uri` are only populated if a matching handler is registered.
 This is to avoid potential issues with metric cardinality
 
-## Resources
+### Resources
+
+MCP spec includes [Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources).
 
-MCP spec includes [Resources](https://modelcontextprotocol.io/docs/concepts/resources)
+### Reading Resources
 
 The `MCP::Resource` class provides a way to register resources with the server.
 
 ```ruby
 resource = MCP::Resource.new(
-  uri: "example.com/my_resource",
-  mime_type: "text/plain",
-  text: "Lorem ipsum dolor sit amet"
+  uri: "https://example.com/my_resource",
+  name: "my-resource",
+  title: "My Resource", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
+  description: "Lorem ipsum dolor sit amet",
+  mime_type: "text/html",
 )
 
 server = MCP::Server.new(
@@ -479,13 +742,127 @@ server.resources_read_handler do |params|
   [{
     uri: params[:uri],
     mimeType: "text/plain",
-    text: "Hello, world!",
+    text: "Hello from example resource! URI: #{params[:uri]}"
   }]
 end
+```
+
+otherwise `resources/read` requests will be a no-op.
+
+### Resource Templates
+
+The `MCP::ResourceTemplate` class provides a way to register resource templates with the server.
+
+```ruby
+resource_template = MCP::ResourceTemplate.new(
+  uri_template: "https://example.com/my_resource_template",
+  name: "my-resource-template",
+  title: "My Resource Template", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
+  description: "Lorem ipsum dolor sit amet",
+  mime_type: "text/html",
+)
+
+server = MCP::Server.new(
+  name: "my_server",
+  resource_templates: [resource_template],
+)
+```
+
+## Building an MCP Client
+
+The `MCP::Client` class provides an interface for interacting with MCP servers.
+
+This class supports:
+
+- Tool listing via the `tools/list` method
+- Tool invocation via the `tools/call` method
+- Automatic JSON-RPC 2.0 message formatting
+- UUID request ID generation
+
+Clients are initialized with a transport layer instance that handles the low-level communication mechanics.
+Authorization is handled by the transport layer.
+
+## Transport Layer Interface
+
+If the transport layer you need is not included in the gem, you can build and pass your own instances so long as they conform to the following interface:
+
+```ruby
+class CustomTransport
+  # Sends a JSON-RPC request to the server and returns the raw response.
+  #
+  # @param request [Hash] A complete JSON-RPC request object.
+  #     https://www.jsonrpc.org/specification#request_object
+  # @return [Hash] A hash modeling a JSON-RPC response object.
+  #     https://www.jsonrpc.org/specification#response_object
+  def send_request(request:)
+    # Your transport-specific logic here
+    # - HTTP: POST to endpoint with JSON body
+    # - WebSocket: Send message over WebSocket
+    # - stdio: Write to stdout, read from stdin
+    # - etc.
+  end
+end
+```
+
+### HTTP Transport Layer
+
+Use the `MCP::Client::HTTP` transport to interact with MCP servers using simple HTTP requests.
 
+You'll need to add `faraday` as a dependency in order to use the HTTP transport layer:
+
+```ruby
+gem 'mcp'
+gem 'faraday', '>= 2.0'
+```
+
+Example usage:
+
+```ruby
+http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp")
+client = MCP::Client.new(transport: http_transport)
+
+# List available tools
+tools = client.tools
+tools.each do |tool|
+  puts <<~TOOL_INFORMATION
+    Tool: #{tool.name}
+    Description: #{tool.description}
+    Input Schema: #{tool.input_schema}
+  TOOL_INFORMATION
+end
+
+# Call a specific tool
+response = client.call_tool(
+  tool: tools.first,
+  arguments: { message: "Hello, world!" }
+)
+```
+
+#### HTTP Authorization
+
+By default, the HTTP transport layer provides no authentication to the server, but you can provide custom headers if you need authentication. For example, to use Bearer token authentication:
+
+```ruby
+http_transport = MCP::Client::HTTP.new(
+  url: "https://api.example.com/mcp",
+  headers: {
+    "Authorization" => "Bearer my_token"
+  }
+)
+
+client = MCP::Client.new(transport: http_transport)
+client.tools # will make the call using Bearer auth
 ```
 
-otherwise 'resources/read' requests will be a no-op.
+You can add any custom headers needed for your authentication scheme, or for any other purpose. The client will include these headers on every request.
+
+### Tool Objects
+
+The client provides a wrapper class for tools returned by the server:
+
+- `MCP::Client::Tool` - Represents a single tool with its metadata
+
+This class provides easy access to tool properties like name, description, input schema, and output schema.
 
 ## Releases
 
@@ -494,7 +871,8 @@ This gem is published to [RubyGems.org](https://rubygems.org/gems/mcp)
 Releases are triggered by PRs to the `main` branch updating the version number in `lib/mcp/version.rb`.
 
 1. **Update the version number** in `lib/mcp/version.rb`, following [semver](https://semver.org/)
-2. **Create A PR and get approval from a maintainer**
-3. **Merge your PR to the main branch** - This will automatically trigger the release workflow via GitHub Actions
+1. **Update CHANGELOG.md**, backfilling the changes since the last release if necessary, and adding a new section for the new version, clearing out the Unreleased section
+1. **Create a PR and get approval from a maintainer**
+1. **Merge your PR to the main branch** - This will automatically trigger the release workflow via GitHub Actions
 
 When changes are merged to the `main` branch, the GitHub Actions workflow (`.github/workflows/release.yml`) is triggered and the gem is published to RubyGems.