model-context-protocol-rb 0.5.0 → 0.6.0

data/README.md

@@ -7,24 +7,21 @@ Provides simple abstractions that allow you to serve prompts, resources, resourc
 ## 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)
+  - [Server Logging Configuration](#server-logging-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)
 
@@ -50,15 +47,143 @@ Provides simple abstractions that allow you to serve prompts, resources, resourc
 | ✅ | [Ping](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/ping) |
 | ✅ | [Progress](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress) |
 
-## Usage
+## Quick Start with Rails
 
-Include `model_context_protocol` in your project.
+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
-require 'model_context_protocol'
+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
 ```
 
-### Building an MCP Server
+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.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
+```
+
+Read more about the [server configuration options](building-an-mcp-server) to better understand how you can customize your MCP server.
+
+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
+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
 
 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.
 
@@ -85,9 +210,6 @@ server = ModelContextProtocol::Server.new do |config|
     Use this server when you need to interact with the local development environment.
   INSTRUCTIONS
 
-  # Enable or disable MCP server logging
-  config.logging_enabled = true
-
   # Configure pagination options for the following methods:
   # prompts/list, resources/list, resource_template/list, tools/list
   config.pagination = {
@@ -124,11 +246,11 @@ server = ModelContextProtocol::Server.new do |config|
 
   # Register prompts, resources, resource templates, and tools
   config.registry = ModelContextProtocol::Server::Registry.new do
-    prompts list_changed: true do
+    prompts do
       register TestPrompt
     end
 
-    resources list_changed: true, subscribe: true do
+    resources do
       register TestResource
     end
 
@@ -136,7 +258,7 @@ server = ModelContextProtocol::Server.new do |config|
       register TestResourceTemplate
     end
 
-    tools list_changed: true do
+    tools do
       register TestTool
     end
   end
@@ -146,7 +268,7 @@ end
 server.start
 ```
 
-#### Server Configuration Options
+### Server Configuration Options
 
 The following table details all available configuration options for the MCP server:
 
@@ -156,13 +278,12 @@ The following table details all available configuration options for the MCP serv
 | `version` | String | Yes | - | Version of the MCP server |
 | `title` | String | No | - | Human-readable display name for the MCP server |
 | `instructions` | String | No | - | Instructions for how the MCP server should be used by LLMs |
-| `logging_enabled` | Boolean | No | `true` | Enable or disable MCP server logging |
 | `pagination` | Hash/Boolean | No | See pagination table | Pagination configuration (or `false` to disable) |
 | `context` | Hash | No | `{}` | Contextual variables available to prompts, resources, and tools |
 | `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:
 
@@ -174,16 +295,32 @@ 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
+#### 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 |
+| `session_ttl` | Integer | No | `3600` | Session timeout in seconds (1 hour) |
+| `env` | Hash | No | - | Rack environment hash (for Rails integration) |
+
+### Redis Configuration
+
 The `:streamable_http` transport requires Redis to be configured globally before use:
 
 ```ruby
@@ -206,15 +343,31 @@ end
 | `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:
+### Server Logging Configuration
+
+Server logging can be configured globally to customize how your MCP server writes debug and operational logs. This logging is separate from client logging (which sends messages to MCP clients via the protocol) and is used for server-side debugging, monitoring, and troubleshooting:
+
+```ruby
+ModelContextProtocol::Server.configure_server_logging do |config|
+  config.logdev = $stderr           # or a file path like '/var/log/mcp-server.log'
+  config.level = Logger::INFO       # Logger::DEBUG, Logger::INFO, Logger::WARN, Logger::ERROR, Logger::FATAL
+  config.progname = "MyMCPServer"   # Program name for log entries
+  config.formatter = proc do |severity, datetime, progname, msg|
+    "#{datetime.strftime('%Y-%m-%d %H:%M:%S')} #{severity} [#{progname}] #{msg}\n"
+  end
+end
+```
 
 | Option | Type | Required | Default | Description |
 |--------|------|----------|---------|-------------|
-| `type` | Symbol | Yes | `:stdio` | Must be `:streamable_http` for HTTP transport |
-| `session_ttl` | Integer | No | `3600` | Session timeout in seconds (1 hour) |
-| `env` | Hash | No | - | Rack environment hash (for Rails integration) |
+| `logdev` | IO/String | No | `$stderr` | Log destination (IO object or file path) |
+| `level` | Integer | No | `Logger::INFO` | Minimum log level to output |
+| `progname` | String | No | `"MCP-Server"` | Program name for log entries |
+| `formatter` | Proc | No | Default timestamp format | Custom log formatter |
+
+**Note:** When using `:stdio` transport, server logging must not use `$stdout` as it conflicts with the MCP protocol communication. Use `$stderr` or a file instead.
 
-#### Registry Configuration Options
+### Registry Configuration Options
 
 The registry is configured using `ModelContextProtocol::Server::Registry.new` and supports the following block types:
 
@@ -227,15 +380,17 @@ The registry is configured using `ModelContextProtocol::Server::Registry.new` an
 
 Within each block, use `register ClassName` to register your handlers.
 
+**Note:** The `list_changed` and `subscribe` options are accepted for capability advertisement but the  list changed notification functionality is not yet implemented (see [Feature Support](#feature-support-server)).
+
 **Example:**
 ```ruby
 config.registry = ModelContextProtocol::Server::Registry.new do
-  prompts list_changed: true do
+  prompts do
     register MyPrompt
     register AnotherPrompt
   end
 
-  resources list_changed: true, subscribe: true do
+  resources do
     register MyResource
   end
 
@@ -245,104 +400,17 @@ 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, 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
-  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,
-        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
-
-    # 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.
 
-Define the prompt properties and then implement the `call` method to build your prompt. Any arguments passed to the tool from the MCP client will be available in the `arguments` hash with symbol keys (e.g., `arguments[:argument_name]`), and any context values provided in the server configuration will be available in the `context` hash. Use the `respond_with` instance method to ensure your prompt responds with appropriately formatted response data.
+Define the prompt properties and then implement the `call` method to build your prompt. Any arguments passed to the prompt from the MCP client will be available in the `arguments` hash with symbol keys (e.g., `arguments[:argument_name]`), and any context values provided in the server configuration will be available in the `context` hash. Use the `respond_with` instance method to ensure your prompt responds with appropriately formatted response data.
 
-You can also log from within your prompt by calling a valid logger level method on the `logger` and passing a string message.
+You can also send MCP log messages to clients from within your prompt by calling a valid logger level method on the `client_logger` and passing a string message. For server-side debugging and monitoring, use the `server_logger` to write logs that are not sent to clients.
 
-#### 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.
 
@@ -353,7 +421,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.
 
@@ -364,7 +432,7 @@ 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. 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.
 
@@ -377,7 +445,7 @@ Define your prompt properties and arguments, implement the `call` method using t
 | `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.
 
@@ -386,7 +454,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.
 
@@ -398,7 +466,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.
 
@@ -406,9 +474,10 @@ The `arguments` passed from an MCP client are available, as well as the `context
 |----------|---------|-------------|
 | `arguments` | Within `call` | Hash containing client-provided arguments (symbol keys) |
 | `context` | Within `call` | Hash containing server configuration context values |
-| `logger` | Within `call` | Logger instance for logging (e.g., `logger.info("message")`) |
+| `client_logger` | Within `call` | Client logger instance for sending MCP log messages (e.g., `client_logger.info("message")`) |
+| `server_logger` | Within `call` | Server logger instance for debugging and monitoring (e.g., `server_logger.debug("message")`) |
 
-#### Examples
+### Examples
 
 This is an example prompt that returns a properly formatted response:
 
@@ -459,8 +528,12 @@ class TestPrompt < ModelContextProtocol::Server::Prompt
 
   # The call method is invoked by the MCP Server to generate a response to resource/read requests
   def call
-    # You can use the logger
-    logger.info("Brainstorming excuses...")
+    # You can use the client_logger
+    client_logger.info("Brainstorming excuses...")
+
+    # Server logging for debugging and monitoring (not sent to client)
+    server_logger.debug("Prompt called with arguments: #{arguments}")
+    server_logger.info("Generating excuse brainstorming prompt")
 
     # Build an array of user and assistant messages
     messages = message_history do
@@ -487,13 +560,17 @@ 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
+You can also send MCP log messages to clients from within your resource by calling a valid logger level method on the `client_logger` and passing a string message. For server-side debugging and monitoring, use the `server_logger` to write logs that are not sent to clients.
+
+### Resource Definition
 
 Use the `define` block to set [resource properties](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/resources/) and configure annotations.
 
@@ -506,7 +583,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.
 
@@ -516,7 +593,7 @@ 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. 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.
 
@@ -528,16 +605,19 @@ Define your resource properties and annotations, implement the `call` method to
 | `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.
+Resources have access to their configured properties and server context.
 
 | Variable | Context | Description |
 |----------|---------|-------------|
 | `mime_type` | Within `call` | The configured MIME type for this resource |
 | `uri` | Within `call` | The configured URI identifier for this resource |
+| `client_logger` | Within `call` | Client logger instance for sending MCP log messages (e.g., `client_logger.info("message")`) |
+| `server_logger` | Within `call` | Server logger instance for debugging and monitoring (e.g., `server_logger.debug("message")`) |
+| `context` | Within `call` | Hash containing server configuration context values |
 
-#### Examples
+### Examples
 
 This is an example resource that returns a text response:
 
@@ -599,13 +679,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).
 
@@ -616,7 +698,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.
 
@@ -624,7 +706,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.
 
@@ -632,7 +714,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:
 
@@ -668,13 +750,17 @@ 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.
+Define the tool properties and schemas, then implement the `call` method to build your tool. Any arguments passed to the tool from the MCP client will be available in the `arguments` hash with symbol keys (e.g., `arguments[:argument_name]`), and any context values provided in the server configuration will be available in the `context` hash. Use the `respond_with` instance method to ensure your prompt responds with appropriately formatted response data.
 
-#### Tool Definition
+You can also send MCP log messages to clients from within your tool by calling a valid logger level method on the `client_logger` and passing a string message. For server-side debugging and monitoring, use the `server_logger` to write logs that are not sent to clients.
+
+### Tool Definition
 
 Use the `define` block to set [tool properties](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/tools/) and configure schemas.
 
@@ -686,7 +772,7 @@ 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. 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.
 
@@ -698,7 +784,7 @@ Define your tool properties and schemas, implement the `call` method using conte
 | `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.
 
@@ -710,7 +796,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`.
 
@@ -721,7 +807,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.
 
@@ -729,9 +815,10 @@ Arguments from MCP clients and server context are available, along with logging
 |----------|---------|-------------|
 | `arguments` | Within `call` | Hash containing client-provided arguments (symbol keys) |
 | `context` | Within `call` | Hash containing server configuration context values |
-| `logger` | Within `call` | Logger instance for logging (e.g., `logger.info("message")`) |
+| `client_logger` | Within `call` | Client logger instance for sending MCP log messages (e.g., `client_logger.info("message")`) |
+| `server_logger` | Within `call` | Server logger instance for debugging and monitoring (e.g., `server_logger.debug("message")`) |
 
-#### Examples
+### Examples
 
 This is an example of a tool that returns structured content validated by an output schema:
 
@@ -783,11 +870,11 @@ class TestToolWithStructuredContentResponse < ModelContextProtocol::Server::Tool
   def call
     # Use values provided by the server as context
     user_id = context[:user_id]
-    logger.info("Initiating request for user #{user_id}...")
+    client_logger.info("Initiating request for user #{user_id}...")
 
     # Use values provided by clients as tool arguments
     location = arguments[:location]
-    logger.info("Getting weather data for #{location}...")
+    client_logger.info("Getting weather data for #{location}...")
 
     # Returns a hash that validates against the output schema
     weather_data = get_weather_data(location)
@@ -831,7 +918,7 @@ class TestToolWithTextResponse < ModelContextProtocol::Server::Tool
   end
 
   def call
-    logger.info("Silly user doesn't know how to double a number")
+    client_logger.info("Silly user doesn't know how to double a number")
     number = arguments[:number].to_i
     calculation = number * 2
 
@@ -923,7 +1010,7 @@ class TestToolWithResourceResponse < ModelContextProtocol::Server::Tool
       return respond_with :error, text: "Resource `#{name}` not found"
     end
 
-    resource_data = resource_klass.call
+    resource_data = resource_klass.call(client_logger, context)
 
     respond_with content: embedded_resource_content(resource: resource_data)
   end
@@ -951,7 +1038,7 @@ class TestToolWithMixedContentResponse < ModelContextProtocol::Server::Tool
   end
 
   def call
-    logger.info("Getting comprehensive temperature history data")
+    client_logger.info("Getting comprehensive temperature history data")
 
     zip = arguments[:zip]
     temperature_history = retrieve_temperature_history(zip:)
@@ -1033,7 +1120,7 @@ class TestToolWithCancellableSleep < ModelContextProtocol::Server::Tool
   end
 
   def call
-    logger.info("Starting 3 second sleep operation")
+    client_logger.info("Starting 3 second sleep operation")
 
     result = cancellable do
       sleep 3
@@ -1074,7 +1161,7 @@ class TestToolWithProgressableAndCancellable < ModelContextProtocol::Server::Too
   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}")
+    client_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
@@ -1096,13 +1183,15 @@ class TestToolWithProgressableAndCancellable < ModelContextProtocol::Server::Too
 end
 ```
 
-### Completions
+---
+
+## 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.
 
@@ -1111,7 +1200,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.
 
@@ -1120,7 +1209,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:
 
@@ -1137,25 +1226,7 @@ class TestCompletion < ModelContextProtocol::Server::Completion
 end
 ```
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'model-context-protocol-rb'
-```
-
-And then execute:
-
-```bash
-bundle
-```
-
-Or install it yourself as:
-
-```bash
-gem install model-context-protocol-rb
-```
+---
 
 ## Development