model-context-protocol-rb 0.5.1 → 0.7.0

data/README.md

@@ -4,26 +4,6 @@ An implementation of the [Model Context Protocol (MCP)](https://spec.modelcontex
 
 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)
-- [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)
-- [Contributing](#contributing)
-- [License](#license)
-
 ## Feature Support (Server)
 
 | Status | Feature |
@@ -38,131 +18,14 @@ Provides simple abstractions that allow you to serve prompts, resources, resourc
 | ✅ | [Environment Variables](https://modelcontextprotocol.io/legacy/tools/debugging#environment-variables) |
 | ✅ | [STDIO Transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) |
 | ✅ | [Streamable HTTP Transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) |
-| ❌ | [List Changed Notification (Prompts)](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts#list-changed-notification) |
-| ❌ | [List Changed Notification (Resources)](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#list-changed-notification) |
+| ✅ | [List Changed Notification (Prompts)](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts#list-changed-notification) ¹ |
+| ✅ | [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) |
+| ✅ | [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) |
 | ✅ | [Ping](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/ping) |
 | ✅ | [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
-```
-
-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:
@@ -183,609 +46,249 @@ Or install it yourself as:
 gem install model-context-protocol-rb
 ```
 
+For detailed installation instructions, see the [Installation wiki page](https://github.com/dickdavis/model-context-protocol-rb/wiki/Installation).
+
 ## 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.
+Build a simple MCP server by registering your prompts, resources, resource templates, and tools. Messages from the MCP client will be routed to the appropriate custom handler.
 
-```ruby
-server = ModelContextProtocol::Server.new do |config|
-  # Name of the MCP server (intended for programmatic use)
-  config.name = "MCPDevelopmentServer"
+### STDIO Transport (Default)
 
-  # Version of the MCP server
-  config.version = "1.0.0"
+For command-line MCP servers that communicate via standard input/output:
 
-  # Optional: human-readable display name for the MCP server
-  config.title = "My Awesome Server"
-
-  # Optional: instuctions for how the MCP server should be used by LLMs
+```ruby
+server = ModelContextProtocol::Server.with_stdio_transport do |config|
+  config.name = "MyMCPServer"
+  config.title = "My Server"
+  config.version = "1.0.0"
   config.instructions = <<~INSTRUCTIONS
-    This server provides file system access and development tools.
+    This server provides prompts, tools, and resources for interacting with my app.
 
     Key capabilities:
-    - Read and write files in the project directory
-    - Execute shell commands for development tasks
-    - Analyze code structure and dependencies
+    - Does something
+    - Does something else
+    - Oh, and it does this other thing, too
 
-    Use this server when you need to interact with the local development environment.
+    Use this server when you need to do things.
   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 = {
-    default_page_size: 50,   # Default items per page
-    max_page_size: 500,      # Maximum allowed page size
-    cursor_ttl: 1800         # Cursor expiry in seconds (30 minutes)
-  }
-
-  # Disable pagination support (enabled by default)
-  # config.pagination = false
-
-  # Optional: require specific environment variables to be set
-  config.require_environment_variable("API_KEY")
-
-  # Optional: set environment variables programmatically
-  config.set_environment_variable("DEBUG_MODE", "true")
-
-  # Optional: provide prompts, resources, and tools with contextual variables
-  config.context = {
-    user_id: "123456",
-    request_id: SecureRandom.uuid
-  }
-
-  # Optional: explicitly specify STDIO as the transport
-  # This is not necessary as STDIO is the default transport
-  # config.transport = { type: :stdio }
- 
-  # Optional: configure streamable HTTP transport if required
-  # config.transport = {
-  #   type: :streamable_http,
-  #   env: request.env,
-  #   session_ttl: 3600 # Optional: session timeout in seconds (default: 3600)
-  # }
-
-  # Register prompts, resources, resource templates, and tools
-  config.registry = ModelContextProtocol::Server::Registry.new do
-    prompts list_changed: true do
-      register TestPrompt
+  config.registry do
+    prompts do
+      register MyPrompt
     end
 
-    resources list_changed: true, subscribe: true do
-      register TestResource
+    resources do
+      register MyResource
     end
 
-    resource_templates do
-      register TestResourceTemplate
-    end
-
-    tools list_changed: true do
-      register TestTool
+    tools do
+      register MyTool
     end
   end
 end
 
-# Start the MCP server
 server.start
 ```
 
-### Server Configuration Options
-
-The following table details all available configuration options for the MCP server:
+### Streamable HTTP Transport
 
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `name` | String | Yes | - | Name of the MCP server for programmatic use |
-| `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 |
+For HTTP-based MCP servers (e.g., Rails applications), you'll need to setup your MCP server in an initializer with Redis configuration. Redis enables coordination across multiple server processes in production deployments (e.g., Puma workers), where no single process can hold all state in memory.
 
-### Pagination Configuration Options
+```ruby
+# config/initializers/model_context_protocol.rb
+require "model_context_protocol"
 
-When `pagination` is set to a Hash, the following options are available:
+# Assuming your handlers will be organized in the app/mcp folder.
+Dir[Rails.root.join("app/mcp/**/*.rb")].sort.each { |f| require f }
 
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `default_page_size` | Integer | No | `50` | Default number of items per page |
-| `max_page_size` | Integer | No | `500` | Maximum allowed page size |
-| `cursor_ttl` | Integer | No | `1800` | Cursor expiry time in seconds (30 minutes) |
+ModelContextProtocol::Server.with_streamable_http_transport do |config|
+  config.name = "MyServer"
+  config.title = "My Server"
+  config.version = "1.0.0"
+  config.instructions = <<~INSTRUCTIONS
+    This server provides prompts, tools, and resources for interacting with my app.
 
-**Note:** Set `config.pagination = false` to completely disable pagination support.
+    Key capabilities:
+    - Does something
+    - Does something else
+    - Oh, and it does this other thing, too
 
-### Transport Configuration Options
+    Use this server when you need to do things.
+  INSTRUCTIONS
 
-The transport configuration supports two types: `:stdio` (default) and `:streamable_http`.
+  config.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
+  config.redis_pool_size = 20
+  config.redis_pool_timeout = 5
+  config.redis_enable_reaper = true
+  config.redis_reaper_interval = 60
+  config.redis_idle_timeout = 300
+  config.redis_ssl_params = {verify_mode: OpenSSL::SSL::VERIFY_NONE}
+
+  config.registry do
+    prompts do
+      register MyPrompt
+    end
 
-#### STDIO Transport
+    resources do
+      register MyResource
+    end
 
-```ruby
-config.transport = { type: :stdio }  # This is the default, can be omitted
+    tools do
+      register MyTool
+    end
+  end
+end
 ```
 
-#### Streamable HTTP Transport
+If your app uses Puma (>= 7.0) as the web server, use the provided plugin to start the MCP server.
 
 ```ruby
-config.transport = { type: :streamable_http, env: request.env }
+# config/puma.rb
+plugin :mcp
 ```
 
-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:
+For Puma 6.x or other web servers, you'll need to manually implement logic for starting and shutting the MCP server appropriately. This example shows how to do so for Puma 6.x; you can adapt it for your server of choice:
 
 ```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
-```
+# config/puma.rb
 
-| 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 |
+workers ENV.fetch("WEB_CONCURRENCY", 0).to_i
 
-### Registry Configuration Options
+mcp_start = ->(*) { ModelContextProtocol::Server.start unless ModelContextProtocol::Server.running? }
+mcp_shutdown = ->(*) { ModelContextProtocol::Server.shutdown }
 
-The registry is configured using `ModelContextProtocol::Server::Registry.new` and supports the following block types:
+# Clustered mode: workers fork, so start threads after fork
+on_worker_boot(&mcp_start)
+on_worker_shutdown(&mcp_shutdown)
 
-| Block Type | Options | Description |
-|------------|---------|-------------|
-| `prompts` | `list_changed: Boolean` | Register prompt handlers with optional list change notifications |
-| `resources` | `list_changed: Boolean`, `subscribe: Boolean` | Register resource handlers with optional list change notifications and subscriptions |
-| `resource_templates` | - | Register resource template handlers |
-| `tools` | `list_changed: Boolean` | Register tool handlers with optional list change notifications |
+# Single mode: start directly (no forking)
+if ENV.fetch("WEB_CONCURRENCY", 0).to_i.zero?
+  mcp_start.call
+  at_exit(&mcp_shutdown)
+end
+```
 
-Within each block, use `register ClassName` to register your handlers.
+Then, implement a controller action to handle the requests to the MCP server.
 
-**Example:**
 ```ruby
-config.registry = ModelContextProtocol::Server::Registry.new do
-  prompts list_changed: true do
-    register MyPrompt
-    register AnotherPrompt
-  end
+class ModelContextProtocolController < ActionController::API
+  include ActionController::Live
 
-  resources list_changed: true, subscribe: true do
-    register MyResource
-  end
+  def handle
+    result = ModelContextProtocol::Server.serve(
+      env: request.env,
+      session_context: { user_id: current_user.id }
+    )
+
+    response.headers.merge!(result[:headers]) if result[:headers]
 
-  tools do
-    register MyTool
+    if result[:stream]
+      result[:stream_proc]&.call(response.stream)
+    else
+      render json: result[:json], status: result[:status] || 200
+    end
+  ensure
+    response.stream.close rescue nil
   end
 end
 ```
 
----
-
-## 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.
-
-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
-
-Use the `define` block to set [prompt properties](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/prompts/) and configure arguments.
-
-| Property | Description |
-|----------|-------------|
-| `name` | The programmatic name of the prompt |
-| `title` | Human-readable display name |
-| `description` | Short description of what the prompt does |
-| `argument` | Define an argument block with name, description, required flag, and completion |
+Lastly, add the necessary routes:
 
-### 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.
-
-| Property | Description |
-|----------|-------------|
-| `name` | The name of the argument |
-| `description` | A short description of the argument |
-| `required` | Whether the argument is required (boolean) |
-| `completion` | Available hints for completions (array or completion class) |
-
-### 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.
-
-| 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
-
-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.
-
-| Method | Context | Description |
-|--------|---------|-------------|
-| `user_message` | Within `message_history` | Create a message with user role |
-| `assistant_message` | Within `message_history` | Create a message with assistant role |
-
-### Content Blocks
-
-Use content blocks to properly format the content included in messages.
+```ruby
+get "/", to: "model_context_protocol#handle", as: :mcp_get
+post "/", to: "model_context_protocol#handle", as: :mcp_post
+delete "/", to: "model_context_protocol#handle", as: :mcp_delete
+```
 
-| Method | Context | Description |
-|--------|---------|-------------|
-| `text_content` | Within message blocks | Create text content block |
-| `image_content` | Within message blocks | Create image content block (requires `data:` and `mime_type:`) |
-| `audio_content` | Within message blocks | Create audio content block (requires `data:` and `mime_type:`) |
-| `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:`) |
+For a complete Rails integration example, see the [Quick Start with Rails](https://github.com/dickdavis/model-context-protocol-rb/wiki/Quick-Start-with-Rails) guide.
 
-### Available Instance Variables
+For complete configuration details including all server options, Redis configuration, and logging options, see the [Building an MCP Server](https://github.com/dickdavis/model-context-protocol-rb/wiki/Building-an-MCP-Server) wiki page.
 
-The `arguments` passed from an MCP client are available, as well as the `context` values passed in at server initialization.
+## Claude Code Plugin
 
-| Variable | Context | Description |
-|----------|---------|-------------|
-| `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")`) |
+The [mcp-rb](https://github.com/dickdavis/model-context-protocol-rb-plugin) Claude Code plugin teaches Claude how to build MCP handlers and configure servers using this gem's DSL. It provides skills for creating tools, prompts, resources, and server configurations.
 
-### Examples
+## Prompts
 
-This is an example prompt that returns a properly formatted response:
+Define prompts that MCP clients can use to generate contextual message sequences.
 
 ```ruby
 class TestPrompt < ModelContextProtocol::Server::Prompt
   define do
-    # The name of the prompt for programmatic use
     name "brainstorm_excuses"
-    # The human-readable prompt name for display in UI
-    title "Brainstorm Excuses"
-    # A short description of what the tool does
-    description "A prompt for brainstorming excuses to get out of something"
-
-    # Define arguments to be used with your prompt
-    argument do
-      # The name of the argument
-      name "tone"
-      # A short description of the argument
-      description "The general tone to be used in the generated excuses"
-      # If the argument is required
-      required false
-      # Available hints for completions
-      completion ["whiny", "angry", "callous", "desperate", "nervous", "sneaky"]
-    end
-
-    argument do
-      name "undesirable_activity"
-      description "The thing to get out of"
-      required true
-    end
+    description "A prompt for brainstorming excuses"
+    argument { name "tone"; required false }
   end
 
-  # You can optionally define a custom completion for an argument and pass it to completions.
-  # ToneCompletion = ModelContextProtocol::Server::Completion.define do
-  #   hints = ["whiny", "angry", "callous", "desperate", "nervous", "sneaky"]
-  #   values = hints.grep(/#{argument_value}/)
-  #   respond_with values:
-  # end
-  #   ...
-  # define do
-  #   argument do
-  #     name "tone"
-  #     description "The general tone to be used in the generated excuses"
-  #     required false
-  #     completion ToneCompletion
-  #   end
-  # end
-
-  # 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...")
-
-    # Build an array of user and assistant messages
     messages = message_history do
-      # Create a message with the user role
-      user_message do
-        # Use any type of content block in a message (text, image, audio, embedded_resource, or resource_link)
-        text_content(text: "My wife wants me to: #{arguments[:undesirable_activity]}... Can you believe it?")
-      end
-
-      # You can also create messages with the assistant role
-      assistant_message do
-        text_content(text: "Oh, that's just downright awful. How can I help?")
-      end
-
-      user_message do
-        # Reference any inputs from the client by accessing the appropriate key in the arguments hash
-        text_content(text: "Can you generate some excuses for me?" + (arguments[:tone] ? " Make them as #{arguments[:tone]} as possible." : ""))
-      end
+      user_message { text_content(text: "Generate excuses with #{arguments[:tone]} tone") }
     end
-
-    # Respond with the messages
     respond_with messages:
   end
 end
 ```
 
----
-
-## 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
-
-Use the `define` block to set [resource properties](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/resources/) and configure annotations.
-
-| Property | Description |
-|----------|-------------|
-| `name` | The name of the resource |
-| `title` | Human-readable display name |
-| `description` | Short description of what the resource contains |
-| `mime_type` | MIME type of the resource content |
-| `uri` | URI identifier for the resource |
-| `annotations` | Block for defining resource annotations |
-
-### 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.
-
-| Property | Description |
-|----------|-------------|
-| `audience` | Target audience for the resource (array of symbols like `[:user, :assistant]`) |
-| `priority` | Priority level (numeric value, e.g., `0.9`) |
-| `last_modified` | Last modified timestamp (ISO 8601 string) |
-
-### 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.
-
-| 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
-
-Resources are stateless and only have access to their configured properties.
+Key features:
+- Define arguments with validation and completion hints
+- Build message histories with user and assistant messages
+- Support for text, image, audio, and embedded resource content
 
-| Variable | Context | Description |
-|----------|---------|-------------|
-| `mime_type` | Within `call` | The configured MIME type for this resource |
-| `uri` | Within `call` | The configured URI identifier for this resource |
+For complete documentation and examples, see the [Prompts](https://github.com/dickdavis/model-context-protocol-rb/wiki/Prompts) wiki page.
 
-### Examples
+## Resources
 
-This is an example resource that returns a text response:
+Expose data and content to MCP clients through defined resources.
 
 ```ruby
 class TestResource < ModelContextProtocol::Server::Resource
   define do
-    name "top-secret-plans.txt"
-    title "Top Secret Plans"
-    description "Top secret plans to do top secret things"
-    mime_type "text/plain"
-    uri "file:///top-secret-plans.txt"
+    name "config.json"
+    description "Application configuration"
+    mime_type "application/json"
+    uri "file:///config.json"
   end
 
   def call
-    respond_with text: "I'm finna eat all my wife's leftovers."
+    respond_with text: { setting: "value" }.to_json
   end
 end
 ```
 
-This is an example resource with annotations:
-
-```ruby
-class TestAnnotatedResource < ModelContextProtocol::Server::Resource
-  define do
-    name "annotated-document.md"
-    description "A document with annotations showing priority and audience"
-    mime_type "text/markdown"
-    uri "file:///docs/annotated-document.md"
-    annotations do
-      audience [:user, :assistant]
-      priority 0.9
-      last_modified "2025-01-12T15:00:58Z"
-    end
-  end
-
-  def call
-    respond_with text: "# Annotated Document\n\nThis document has annotations."
-  end
-end
-```
+Key features:
+- Define metadata including MIME type and URI
+- Return text or binary content
+- Add annotations for audience and priority
 
-This is an example resource that returns binary data:
-
-```ruby
-class TestBinaryResource < ModelContextProtocol::Server::Resource
-  define do
-    name "project-logo.png"
-    description "The logo for the project"
-    mime_type "image/png"
-    uri "file:///project-logo.png"
-  end
-
-  def call
-    # In a real implementation, we would retrieve the binary resource
-    # This is a small valid base64 encoded string (represents "test")
-    data = "dGVzdA=="
-    respond_with binary: data
-  end
-end
-```
-
----
+For complete documentation and examples, see the [Resources](https://github.com/dickdavis/model-context-protocol-rb/wiki/Resources) wiki page.
 
 ## 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
-
-Use the `define` block to set [resource template properties](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#resource-templates).
-
-| Property | Description |
-|----------|-------------|
-| `name` | The name of the resource template |
-| `description` | Short description of what the template provides |
-| `mime_type` | MIME type of resources created from this template |
-| `uri_template` | URI template with parameters (e.g., `"file:///{name}"`) |
-
-### URI Template Configuration
-
-Define the URI template and configure parameter completions within the `uri_template` block.
-
-| Method | Context | Description |
-|--------|---------|-------------|
-| `completion` | Within `uri_template` block | Define completion for a URI parameter (e.g., `completion :name, ["value1", "value2"]`) |
-
-### Resource Template Methods
-
-Resource templates only use the `define` method to configure their properties - they don't have a `call` method.
-
-| Method | Context | Description |
-|--------|---------|-------------|
-| `define` | Class definition | Block for defining resource template metadata and URI template |
-
-### Examples
-
-This is an example resource template that provides a completion for a parameter of the URI template:
+Define parameterized resources with URI templates that clients can instantiate.
 
 ```ruby
 class TestResourceTemplate < ModelContextProtocol::Server::ResourceTemplate
   define do
-    name "project-document-resource-template"
-    description "A resource template for retrieving project documents"
+    name "document-template"
+    description "Template for retrieving documents"
     mime_type "text/plain"
     uri_template "file:///{name}" do
-      completion :name, ["top-secret-plans.txt"]
+      completion :name, ["readme.txt", "config.json"]
     end
   end
-
-  # You can optionally define a custom completion for an argument and pass it to completions.
-  # Completion = ModelContextProtocol::Server::Completion.define do
-  #   hints = {
-  #     "name" => ["top-secret-plans.txt"]
-  #   }
-  #   values = hints[argument_name].grep(/#{argument_value}/)
-
-  #   respond_with values:
-  # end
-
-  # define do
-  #   name "project-document-resource-template"
-  #   description "A resource template for retrieving project documents"
-  #   mime_type "text/plain"
-  #   uri_template "file:///{name}" do
-  #     completion :name, Completion
-  #   end
-  # end
 end
 ```
 
----
-
-## 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
-
-Use the `define` block to set [tool properties](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/tools/) and configure schemas.
-
-| Property | Description |
-|----------|-------------|
-| `name` | The programmatic name of the tool |
-| `title` | Human-readable display name |
-| `description` | Short description of what the tool does |
-| `input_schema` | JSON schema block for validating tool inputs |
-| `output_schema` | JSON schema block for validating structured content outputs |
-
-### 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.
-
-| 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
+Key features:
+- Define URI templates with parameters
+- Provide completion hints for template parameters
 
-Use content blocks to properly format the content included in tool responses.
+For complete documentation and examples, see the [Resource Templates](https://github.com/dickdavis/model-context-protocol-rb/wiki/Resource-Templates) wiki page.
 
-| Method | Context | Description |
-|--------|---------|-------------|
-| `text_content` | Within `call` | Create text content block |
-| `image_content` | Within `call` | Create image content block (requires `data:` and `mime_type:`) |
-| `audio_content` | Within `call` | Create audio content block (requires `data:` and `mime_type:`) |
-| `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
-
-Tools can return different types of responses using `respond_with`.
-
-| Response Type | Usage | Description |
-|---------------|-------|-------------|
-| `structured_content:` | `respond_with structured_content: data` | Return structured data validated against output schema |
-| `content:` | `respond_with content: content_block` | Return single content block |
-| `content:` | `respond_with content: [content_blocks]` | Return array of mixed content blocks |
-| `error:` | `respond_with error: "message"` | Return tool error response |
-
-### Available Instance Variables
-
-Arguments from MCP clients and server context are available, along with logging capabilities.
-
-| Variable | Context | Description |
-|----------|---------|-------------|
-| `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")`) |
-
-### Examples
+## Tools
 
-This is an example of a tool that returns structured content validated by an output schema:
+Create callable functions that MCP clients can invoke with validated inputs.
 
 ```ruby
 class TestToolWithStructuredContentResponse < ModelContextProtocol::Server::Tool
@@ -830,16 +333,23 @@ class TestToolWithStructuredContentResponse < ModelContextProtocol::Server::Tool
         required: ["temperature", "conditions", "humidity"]
       }
     end
+    # Optional security requirements for the tool
+    security_schemes do
+      [
+        {type: "noauth"},
+        {type: "oauth2", scopes: ["search.read"]}
+      ]
+    end
   end
 
   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)
@@ -861,337 +371,55 @@ class TestToolWithStructuredContentResponse < ModelContextProtocol::Server::Tool
 end
 ```
 
-This is an example tool that returns a text response:
-
-```ruby
-class TestToolWithTextResponse < ModelContextProtocol::Server::Tool
-  define do
-    name "double"
-    title "Number Doubler"
-    description "Doubles the provided number"
-    input_schema do
-      {
-        type: "object",
-        properties: {
-          number: {
-            type: "string"
-          }
-        },
-        required: ["number"]
-      }
-    end
-  end
-
-  def call
-    logger.info("Silly user doesn't know how to double a number")
-    number = arguments[:number].to_i
-    calculation = number * 2
-
-    user_id = context[:user_id]
-    salutation = user_id ? "User #{user_id}, " : ""
-    text_content = text_content(text: salutation << "#{number} doubled is #{calculation}")
-
-    respond_with content: text_content
-  end
-end
-```
-
-This is an example of a tool that returns an image:
-
-```ruby
-class TestToolWithImageResponse < ModelContextProtocol::Server::Tool
-  define do
-    name "custom-chart-generator"
-    description "Generates a chart in various formats"
-    input_schema do
-      {
-        type: "object",
-        properties: {
-          chart_type: {
-            type: "string",
-            description: "Type of chart (pie, bar, line)"
-          },
-          format: {
-            type: "string",
-            description: "Image format (jpg, svg, etc)"
-          }
-        },
-        required: ["chart_type", "format"]
-      }
-    end
-  end
-
-  def call
-    # Map format to mime type
-    mime_type = case arguments[:format].downcase
-    when "svg"
-      "image/svg+xml"
-    when "jpg", "jpeg"
-      "image/jpeg"
-    else
-      "image/png"
-    end
-
-    # In a real implementation, we would generate an actual chart
-    # This is a small valid base64 encoded string (represents "test")
-    data = "dGVzdA=="
-    image_content = image_content(data:, mime_type:)
-    respond_with content: image_content
-  end
-end
-```
-
-This is an example of a tool that returns an embedded resource response:
-
-```ruby
-class TestToolWithResourceResponse < ModelContextProtocol::Server::Tool
-  define do
-    name "resource-finder"
-    description "Finds a resource given a name"
-    input_schema do
-      {
-        type: "object",
-        properties: {
-          name: {
-            type: "string",
-            description: "The name of the resource"
-          }
-        },
-        required: ["name"]
-      }
-    end
-  end
-
-  RESOURCE_MAPPINGS = {
-    test_annotated_resource: TestAnnotatedResource,
-    test_binary_resource: TestBinaryResource,
-    test_resource: TestResource
-  }.freeze
-
-  def call
-    name = arguments[:name]
-    resource_klass = RESOURCE_MAPPINGS[name.downcase.to_sym]
-    unless resource_klass
-      return respond_with :error, text: "Resource `#{name}` not found"
-    end
-
-    resource_data = resource_klass.call
-
-    respond_with content: embedded_resource_content(resource: resource_data)
-  end
-end
-```
-
-This is an example of a tool that returns mixed content:
+Key features:
+- Define input and output JSON schemas
+- Declare tool security schemes (e.g., noauth, oauth2 scopes)
+- Return text, image, audio, or embedded resource content
+- Support for structured content responses
+- Cancellable and progressable operations
 
-```ruby
-class TestToolWithMixedContentResponse < ModelContextProtocol::Server::Tool
-  define do
-    name "get_temperature_history"
-    description "Gets comprehensive temperature history for a zip code"
-    input_schema do
-      {
-        type: "object",
-        properties: {
-          zip: {
-            type: "string"
-          }
-        },
-        required: ["zip"]
-      }
-    end
-  end
-
-  def call
-    logger.info("Getting comprehensive temperature history data")
+For complete documentation and 7 detailed examples, see the [Tools](https://github.com/dickdavis/model-context-protocol-rb/wiki/Tools) wiki page.
 
-    zip = arguments[:zip]
-    temperature_history = retrieve_temperature_history(zip:)
-    temperature_history_block = text_content(text: temperature_history.join(", "))
-
-    temperature_chart = generate_weather_history_chart(temperature_history)
-    temperature_chart_block = image_content(
-      data: temperature_chart[:base64_chart_data],
-      mime_type: temperature_chart[:mime_type]
-    )
-
-    respond_with content: [temperature_history_block, temperature_chart_block]
-  end
-
-  private
-
-  def retrieve_temperature_history(zip:)
-    # Simulates a call to an API or DB to retrieve weather history
-    [85.2, 87.4, 89.0, 95.3, 96.0]
-  end
-
-  def generate_weather_history_chart(history)
-    # SImulate a call to generate a chart given the weather history
-    {
-      base64_chart_data: "dGVzdA==",
-      mime_type: "image/png"
-    }
-  end
-end
-```
+## Completions
 
-This is an example of a tool that returns a tool error response:
+Provide argument completion hints for prompts and resource templates.
 
 ```ruby
-class TestToolWithToolErrorResponse < ModelContextProtocol::Server::Tool
-  define do
-    name "api-caller"
-    description "Makes calls to external APIs"
-    input_schema do
-      {
-        type: "object",
-        properties: {
-          api_endpoint: {
-            type: "string",
-            description: "API endpoint URL"
-          },
-          method: {
-            type: "string",
-            description: "HTTP method (GET, POST, etc)"
-          }
-        },
-        required: ["api_endpoint", "method"]
-      }
-    end
-  end
-
+class TestCompletion < ModelContextProtocol::Server::Completion
   def call
-    # Simulate an API call failure
-    respond_with error: "Failed to call API at #{arguments[:api_endpoint]}: Connection timed out"
+    hints = { "tone" => ["whiny", "angry", "nervous"] }
+    values = hints[argument_name].grep(/#{argument_value}/)
+    respond_with values:
   end
 end
 ```
 
-This is an example of a tool that allows a client to cancel a long-running operation:
+For complete documentation, see the [Completions](https://github.com/dickdavis/model-context-protocol-rb/wiki/Completions) wiki page.
 
-```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
-```
+## Testing with RSpec
 
-This is an example of a tool that automatically sends progress notifications to the client and allows the client to cancel the operation:
+This gem provides custom RSpec matchers and helpers for testing your MCP handlers.
 
 ```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"
+require "model_context_protocol/rspec"
+ModelContextProtocol::RSpec.configure!
 
-    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
+RSpec.describe WeatherTool, type: :mcp do
+  it "returns weather data" do
+    response = call_mcp_tool(WeatherTool, { location: "New York" })
+    expect(response).to be_valid_mcp_tool_response
+    expect(response).to have_text_content(/temperature/)
   end
 end
 ```
 
----
-
-## Completions
+Key features:
+- Helper methods: `call_mcp_tool`, `call_mcp_prompt`, `call_mcp_resource`
+- Class definition matchers: `be_valid_mcp_class(:tool)`
+- Response matchers for text, image, audio, and structured content
+- Prompt and resource-specific matchers
 
-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
-
-Completions only implement the `call` method to provide completion logic.
-
-| Method | Context | Description |
-|--------|---------|-------------|
-| `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
-
-Completions receive the argument name and current value being completed.
-
-| Variable | Context | Description |
-|----------|---------|-------------|
-| `argument_name` | Within `call` | String name of the argument being completed |
-| `argument_value` | Within `call` | Current partial value being typed by the user |
-
-### Examples
-
-This is an example completion that returns an array of values in the response:
-
-```ruby
-class TestCompletion < ModelContextProtocol::Server::Completion
-  def call
-    hints = {
-      "message" => ["hello", "world", "foo", "bar"]
-    }
-    values = hints[argument_name].grep(/#{argument_value}/)
-
-    respond_with values:
-  end
-end
-```
-
----
+For complete matcher documentation and examples, see the [Testing with RSpec](https://github.com/dickdavis/model-context-protocol-rb/wiki/Testing-with-RSpec) wiki page.
 
 ## Development
 
@@ -1207,6 +435,9 @@ bundle exec rake mcp:generate_stdio_server
 
 # generates bin/dev-http for streamable HTTP transport
 bundle exec rake mcp:generate_streamable_http_server
+
+# generates bin/dev-http-puma for streamable HTTP transport with Puma web server
+bundle exec rake mcp:generate_puma_server
 ```
 
 If you need to test with HTTPS (e.g., for clients that require SSL), generate self-signed certificates: