mcp 0.4.0 → 0.11.0

data/README.md

@@ -1,4 +1,4 @@
-# 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)
+# MCP Ruby SDK [![Gem Version](https://img.shields.io/gem/v/mcp)](https://rubygems.org/gems/mcp) [![Apache 2.0 licensed](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/LICENSE) [![CI](https://github.com/modelcontextprotocol/ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/modelcontextprotocol/ruby-sdk/actions/workflows/ci.yml)
 
 The official Ruby SDK for Model Context Protocol servers and clients.
 
@@ -38,6 +38,7 @@ It implements the Model Context Protocol specification, handling model context r
 - Supports resource registration and retrieval
 - Supports stdio & Streamable HTTP (including SSE) transports
 - Supports notifications for list changes (tools, prompts, resources)
+- Supports sampling (server-to-client LLM completion requests)
 
 ### Supported Methods
 
@@ -50,6 +51,8 @@ It implements the Model Context Protocol specification, handling model context r
 - `resources/list` - Lists all registered resources and their schemas
 - `resources/read` - Retrieves a specific resource by name
 - `resources/templates/list` - Lists all registered resource templates and their schemas
+- `completion/complete` - Returns autocompletion suggestions for prompt arguments and resource URIs
+- `sampling/createMessage` - Requests LLM completion from the client (server-to-client)
 
 ### Custom Methods
 
@@ -102,17 +105,184 @@ end
 - Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method
 - Supports the same exception reporting and instrumentation as standard methods
 
+### Sampling
+
+The Model Context Protocol allows servers to request LLM completions from clients through the `sampling/createMessage` method.
+This enables servers to leverage the client's LLM capabilities without needing direct access to AI models.
+
+**Key Concepts:**
+
+- **Server-to-Client Request**: Unlike typical MCP methods (client→server), sampling is initiated by the server
+- **Client Capability**: Clients must declare `sampling` capability during initialization
+- **Tool Support**: When using tools in sampling requests, clients must declare `sampling.tools` capability
+- **Human-in-the-Loop**: Clients can implement user approval before forwarding requests to LLMs
+
+**Usage Example (Stdio transport):**
+
+`Server#create_sampling_message` is for single-client transports (e.g., `StdioTransport`).
+For multi-client transports (e.g., `StreamableHTTPTransport`), use `server_context.create_sampling_message` inside tools instead,
+which routes the request to the correct client session.
+
+```ruby
+server = MCP::Server.new(name: "my_server")
+transport = MCP::Server::Transports::StdioTransport.new(server)
+server.transport = transport
+```
+
+Client must declare sampling capability during initialization.
+This happens automatically when the client connects.
+
+```ruby
+result = server.create_sampling_message(
+  messages: [
+    { role: "user", content: { type: "text", text: "What is the capital of France?" } }
+  ],
+  max_tokens: 100,
+  system_prompt: "You are a helpful assistant.",
+  temperature: 0.7
+)
+```
+
+Result contains the LLM response:
+
+```ruby
+{
+  role: "assistant",
+  content: { type: "text", text: "The capital of France is Paris." },
+  model: "claude-3-sonnet-20240307",
+  stopReason: "endTurn"
+}
+```
+
+**Parameters:**
+
+Required:
+
+- `messages:` (Array) - Array of message objects with `role` and `content`
+- `max_tokens:` (Integer) - Maximum tokens in the response
+
+Optional:
+
+- `system_prompt:` (String) - System prompt for the LLM
+- `model_preferences:` (Hash) - Model selection preferences (e.g., `{ intelligencePriority: 0.8 }`)
+- `include_context:` (String) - Context inclusion: `"none"`, `"thisServer"`, or `"allServers"` (soft-deprecated)
+- `temperature:` (Float) - Sampling temperature
+- `stop_sequences:` (Array) - Sequences that stop generation
+- `metadata:` (Hash) - Additional metadata
+- `tools:` (Array) - Tools available to the LLM (requires `sampling.tools` capability)
+- `tool_choice:` (Hash) - Tool selection mode (e.g., `{ mode: "auto" }`)
+
+**Using Sampling in Tools (works with both Stdio and HTTP transports):**
+
+Tools that accept a `server_context:` parameter can call `create_sampling_message` on it.
+The request is automatically routed to the correct client session.
+Set `server.server_context = server` so that `server_context.create_sampling_message` delegates to the server:
+
+```ruby
+class SummarizeTool < MCP::Tool
+  description "Summarize text using LLM"
+  input_schema(
+    properties: {
+      text: { type: "string" }
+    },
+    required: ["text"]
+  )
+
+  def self.call(text:, server_context:)
+    result = server_context.create_sampling_message(
+      messages: [
+        { role: "user", content: { type: "text", text: "Please summarize: #{text}" } }
+      ],
+      max_tokens: 500
+    )
+
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: result[:content][:text]
+    }])
+  end
+end
+
+server = MCP::Server.new(name: "my_server", tools: [SummarizeTool])
+server.server_context = server
+```
+
+**Tool Use in Sampling:**
+
+When tools are provided in a sampling request, the LLM can call them during generation.
+The server must handle tool calls and continue the conversation with tool results:
+
+```ruby
+result = server.create_sampling_message(
+  messages: [
+    { role: "user", content: { type: "text", text: "What's the weather in Paris?" } }
+  ],
+  max_tokens: 1000,
+  tools: [
+    {
+      name: "get_weather",
+      description: "Get weather for a city",
+      inputSchema: {
+        type: "object",
+        properties: { city: { type: "string" } },
+        required: ["city"]
+      }
+    }
+  ],
+  tool_choice: { mode: "auto" }
+)
+
+if result[:stopReason] == "toolUse"
+  tool_results = result[:content].map do |tool_use|
+    weather_data = get_weather(tool_use[:input][:city])
+
+    {
+      type: "tool_result",
+      toolUseId: tool_use[:id],
+      content: [{ type: "text", text: weather_data.to_json }]
+    }
+  end
+
+  final_result = server.create_sampling_message(
+    messages: [
+      { role: "user", content: { type: "text", text: "What's the weather in Paris?" } },
+      { role: "assistant", content: result[:content] },
+      { role: "user", content: tool_results }
+    ],
+    max_tokens: 1000,
+    tools: [...]
+  )
+end
+```
+
+**Error Handling:**
+
+- Raises `RuntimeError` if transport is not set
+- Raises `RuntimeError` if client does not support `sampling` capability
+- Raises `RuntimeError` if `tools` are used but client lacks `sampling.tools` capability
+- Raises `StandardError` if client returns an error response
+
 ### 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:
+The server provides the following 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
+- `notify_log_message` - Send a structured logging notification message
+
+#### Session Scoping
+
+When using Streamable HTTP transport with multiple clients, each client connection gets its own session. Notifications are scoped as follows:
+
+- **`report_progress`** and **`notify_log_message`** called via `server_context` inside a tool handler are automatically sent only to the requesting client.
+No extra configuration is needed.
+- **`notify_tools_list_changed`**, **`notify_prompts_list_changed`**, and **`notify_resources_list_changed`** are always broadcast to all connected clients,
+as they represent server-wide state changes. These should be called on the `server` instance directly.
 
 #### Notification Format
 
@@ -121,6 +291,179 @@ 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`
+- `notifications/progress`
+- `notifications/message`
+
+### Progress
+
+The MCP Ruby SDK supports progress tracking for long-running tool operations,
+following the [MCP Progress specification](https://modelcontextprotocol.io/specification/latest/server/utilities/progress).
+
+#### How Progress Works
+
+1. **Client Request**: The client sends a `progressToken` in the `_meta` field when calling a tool
+2. **Server Notification**: The server sends `notifications/progress` messages back to the client during tool execution
+3. **Tool Integration**: Tools call `server_context.report_progress` to report incremental progress
+
+#### Server-Side: Tool with Progress
+
+Tools that accept a `server_context:` parameter can call `report_progress` on it.
+The server automatically wraps the context in an `MCP::ServerContext` instance that provides this method:
+
+```ruby
+class LongRunningTool < MCP::Tool
+  description "A tool that reports progress during execution"
+  input_schema(
+    properties: {
+      count: { type: "integer" },
+    },
+    required: ["count"]
+  )
+
+  def self.call(count:, server_context:)
+    count.times do |i|
+      # Do work here.
+      server_context.report_progress(i + 1, total: count, message: "Processing item #{i + 1}")
+    end
+
+    MCP::Tool::Response.new([{ type: "text", text: "Done" }])
+  end
+end
+```
+
+The `server_context.report_progress` method accepts:
+
+- `progress` (required) — current progress value (numeric)
+- `total:` (optional) — total expected value, so clients can display a percentage
+- `message:` (optional) — human-readable status message
+
+**Key Features:**
+
+- Tools report progress via `server_context.report_progress`
+- `report_progress` is a no-op when no `progressToken` was provided by the client
+- Supports both numeric and string progress tokens
+
+### Completions
+
+MCP spec includes [Completions](https://modelcontextprotocol.io/specification/latest/server/utilities/completion),
+which enable servers to provide autocompletion suggestions for prompt arguments and resource URIs.
+
+To enable completions, declare the `completions` capability and register a handler:
+
+```ruby
+server = MCP::Server.new(
+  name: "my_server",
+  prompts: [CodeReviewPrompt],
+  resource_templates: [FileTemplate],
+  capabilities: { completions: {} },
+)
+
+server.completion_handler do |params|
+  ref = params[:ref]
+  argument = params[:argument]
+  value = argument[:value]
+
+  case ref[:type]
+  when "ref/prompt"
+    values = case argument[:name]
+    when "language"
+      ["python", "pytorch", "pyside"].select { |v| v.start_with?(value) }
+    else
+      []
+    end
+    { completion: { values: values, hasMore: false } }
+  when "ref/resource"
+    { completion: { values: [], hasMore: false } }
+  end
+end
+```
+
+The handler receives a `params` hash with:
+
+- `ref` - The reference (`{ type: "ref/prompt", name: "..." }` or `{ type: "ref/resource", uri: "..." }`)
+- `argument` - The argument being completed (`{ name: "...", value: "..." }`)
+- `context` (optional) - Previously resolved arguments (`{ arguments: { ... } }`)
+
+The handler must return a hash with a `completion` key containing `values` (array of strings), and optionally `total` and `hasMore`.
+The SDK automatically enforces the 100-item limit per the MCP specification.
+
+The server validates that the referenced prompt, resource, or resource template is registered before calling the handler.
+Requests for unknown references return an error.
+
+### Logging
+
+The MCP Ruby SDK supports structured logging through the `notify_log_message` method, following the [MCP Logging specification](https://modelcontextprotocol.io/specification/latest/server/utilities/logging).
+
+The `notifications/message` notification is used for structured logging between client and server.
+
+#### Log Levels
+
+The SDK supports 8 log levels with increasing severity:
+
+- `debug` - Detailed debugging information
+- `info` - General informational messages
+- `notice` - Normal but significant events
+- `warning` - Warning conditions
+- `error` - Error conditions
+- `critical` - Critical conditions
+- `alert` - Action must be taken immediately
+- `emergency` - System is unusable
+
+#### How Logging Works
+
+1. **Client Configuration**: The client sends a `logging/setLevel` request to configure the minimum log level
+2. **Server Filtering**: The server only sends log messages at the configured level or higher severity
+3. **Notification Delivery**: Log messages are sent as `notifications/message` to the client
+
+For example, if the client sets the level to `"error"` (severity 4), the server will send messages with levels: `error`, `critical`, `alert`, and `emergency`.
+
+For more details, see the [MCP Logging specification](https://modelcontextprotocol.io/specification/latest/server/utilities/logging).
+
+**Usage Example:**
+
+```ruby
+server = MCP::Server.new(name: "my_server")
+transport = MCP::Server::Transports::StdioTransport.new(server)
+server.transport = transport
+
+# The client first configures the logging level (on the client side):
+transport.send_request(
+  request: {
+    jsonrpc: "2.0",
+    method: "logging/setLevel",
+    params: { level: "info" },
+    id: session_id # Unique request ID within the session
+  }
+)
+
+# Send log messages at different severity levels
+server.notify_log_message(
+  data: { message: "Application started successfully" },
+  level: "info"
+)
+
+server.notify_log_message(
+  data: { message: "Configuration file not found, using defaults" },
+  level: "warning"
+)
+
+server.notify_log_message(
+  data: {
+    error: "Database connection failed",
+    details: { host: "localhost", port: 5432 }
+  },
+  level: "error",
+  logger: "DatabaseLogger" # Optional logger name
+)
+```
+
+**Key Features:**
+
+- Supports 8 log levels (debug, info, notice, warning, error, critical, alert, emergency) based on https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging#log-levels
+- Server has capability `logging` to send log messages
+- Messages are only sent if a transport is configured
+- Messages are filtered based on the client's configured log level
+- If the log level hasn't been set by the client, no messages will be sent
 
 #### Transport Support
 
@@ -131,7 +474,10 @@ Notifications follow the JSON-RPC 2.0 specification and use these method names:
 
 ```ruby
 server = MCP::Server.new(name: "my_server")
+
+# Default Streamable HTTP - session oriented
 transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+
 server.transport = transport
 
 # When tools change, notify clients
@@ -139,35 +485,63 @@ server.define_tool(name: "new_tool") { |**args| { result: "ok" } }
 server.notify_tools_list_changed
 ```
 
-### Unsupported Features ( to be implemented in future versions )
+You can use Stateless Streamable HTTP, where notifications are not supported and all calls are request/response interactions.
+This mode allows for easy multi-node deployment.
+Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new` (`stateless` defaults to `false`):
+
+```ruby
+# Stateless Streamable HTTP - session-less
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
+```
+
+By default, sessions do not expire. To mitigate session hijacking risks, you can set a `session_idle_timeout` (in seconds).
+When configured, sessions that receive no HTTP requests for this duration are automatically expired and cleaned up:
+
+```ruby
+# Session timeout of 30 minutes
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 1800)
+```
+
+### Unsupported Features (to be implemented in future versions)
 
-- Log Level
 - Resource subscriptions
-- Completions
+- Elicitation
 
 ### Usage
 
+> [!IMPORTANT]
+> `MCP::Server::Transports::StreamableHTTPTransport` stores session and SSE stream state in memory,
+> so it must run in a single process. Use a single-process server (e.g., Puma with `workers 0`).
+> Multi-process configurations (Unicorn, or Puma with `workers > 0`) fork separate processes that
+> do not share memory, which breaks session management and SSE connections.
+> Stateless mode (`stateless: true`) does not use sessions and works with any server configuration.
+
 #### Rails Controller
 
 When added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming
-[Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport
+[Streamable HTTP](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http) transport
 requests.
 
-You can use the `Server#handle_json` method to handle requests.
+You can use `StreamableHTTPTransport#handle_request` to handle requests with proper HTTP
+status codes (e.g., 202 Accepted for notifications).
 
 ```ruby
-class ApplicationController < ActionController::Base
-  def index
+class McpController < ActionController::Base
+  def create
     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.
+      title: "Example Server Display Name",
       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 },
     )
-    render(json: server.handle_json(request.body.read))
+    transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+    server.transport = transport
+    status, headers, body = transport.handle_request(request)
+
+    render(json: body.first, status: status, headers: headers)
   end
 end
 ```
@@ -286,6 +660,50 @@ server = MCP::Server.new(
 
 This hash is then passed as the `server_context` argument to tool and prompt calls, and is included in exception and instrumentation callbacks.
 
+#### Request-specific `_meta` Parameter
+
+The MCP protocol supports a special [`_meta` parameter](https://modelcontextprotocol.io/specification/2025-06-18/basic#general-fields) in requests that allows clients to pass request-specific metadata. The server automatically extracts this parameter and makes it available to tools and prompts as a nested field within the `server_context`.
+
+**Access Pattern:**
+
+When a client includes `_meta` in the request params, it becomes available as `server_context[:_meta]`:
+
+```ruby
+class MyTool < MCP::Tool
+  def self.call(message:, server_context:)
+    # Access provider-specific metadata
+    session_id = server_context.dig(:_meta, :session_id)
+    request_id = server_context.dig(:_meta, :request_id)
+
+    # Access server's original context
+    user_id = server_context.dig(:user_id)
+
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: "Processing for user #{user_id} in session #{session_id}"
+    }])
+  end
+end
+```
+
+**Client Request Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "my_tool",
+    "arguments": { "message": "Hello" },
+    "_meta": {
+      "session_id": "abc123",
+      "request_id": "req_456"
+    }
+  }
+}
+```
+
 #### Configuration Block Data
 
 ##### Exception Reporter
@@ -307,10 +725,16 @@ The instrumentation callback receives a hash with the following possible keys:
 
 - `method`: (String) The protocol method called (e.g., "ping", "tools/list")
 - `tool_name`: (String, optional) The name of the tool called
+- `tool_arguments`: (Hash, optional) The arguments passed to the tool
 - `prompt_name`: (String, optional) The name of the prompt called
 - `resource_uri`: (String, optional) The URI of the resource called
 - `error`: (String, optional) Error code if a lookup failed
 - `duration`: (Float) Duration of the call in seconds
+- `client`: (Hash, optional) Client information with `name` and `version` keys, from the initialize request
+
+> [!NOTE]
+> `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.
 
 **Type:**
 
@@ -322,9 +746,11 @@ instrumentation_callback = ->(data) { ... }
 **Example:**
 
 ```ruby
-config.instrumentation_callback = ->(data) {
-  puts "Instrumentation: #{data.inspect}"
-}
+MCP.configure do |config|
+  config.instrumentation_callback = ->(data) {
+    puts "Instrumentation: #{data.inspect}"
+  }
+end
 ```
 
 ### Server Protocol Version
@@ -336,6 +762,9 @@ configuration = MCP::Configuration.new(protocol_version: "2024-11-05")
 MCP::Server.new(name: "test_server", configuration: configuration)
 ```
 
+If no protocol version is specified, the latest stable version will be applied by default.
+The latest stable version includes new features from the [draft version](https://modelcontextprotocol.io/specification/draft).
+
 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
@@ -368,7 +797,7 @@ If no exception reporter is configured, a default no-op reporter is used that si
 
 ### Tools
 
-MCP spec includes [Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) which provide functionality to LLM apps.
+MCP spec includes [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) which provide functionality to LLM apps.
 
 This gem provides a `MCP::Tool` class that can be used to create tools in three ways:
 
@@ -376,7 +805,7 @@ This gem provides a `MCP::Tool` class that can be used to create tools in three
 
 ```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.
+  title "My Tool"
   description "This tool performs specific functionality..."
   input_schema(
     properties: {
@@ -413,13 +842,13 @@ 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.
+  title: "My Tool",
   description: "This tool performs specific functionality...",
   annotations: {
     read_only_hint: true,
     title: "My Tool"
   }
-) do |args, server_context|
+) do |args, server_context:|
   MCP::Tool::Response.new([{ type: "text", text: "OK" }])
 end
 ```
@@ -435,7 +864,7 @@ server.define_tool(
     title: "My Tool",
     read_only_hint: true
   }
-) do |args, server_context|
+) do |args, server_context:|
   Tool::Response.new([{ type: "text", text: "OK" }])
 end
 ```
@@ -525,7 +954,7 @@ tool = MCP::Tool.define(
     },
     required: ["mean", "median", "count"]
   }
-) do |args, server_context|
+) do |args, server_context:|
   # Calculate statistics and validate against schema
   MCP::Tool::Response.new([{ type: "text", text: "Statistics calculated" }])
 end
@@ -551,7 +980,7 @@ Output schema may also describe an array of objects:
 class WeatherTool < MCP::Tool
   output_schema(
     type: "array",
-    item: {
+    items: {
       properties: {
         temperature: { type: "number" },
         condition: { type: "string" },
@@ -566,7 +995,7 @@ end
 Please note: in this case, you must provide `type: "array"`. The default type
 for output schemas is `object`.
 
-MCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema) specifies that:
+MCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/latest/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
@@ -582,10 +1011,10 @@ Tools can return structured data alongside text content using the `structured_co
 The structured content will be included in the JSON-RPC response as the `structuredContent` field.
 
 ```ruby
-class APITool < MCP::Tool
+class WeatherTool < MCP::Tool
   description "Get current weather and return structured data"
 
-  def self.call(endpoint:, server_context:)
+  def self.call(location:, units: "celsius", server_context:)
     # Call weather API and structure the response
     api_response = WeatherAPI.fetch(location, units)
     weather_data = {
@@ -607,9 +1036,35 @@ class APITool < MCP::Tool
 end
 ```
 
+### Tool Responses with Errors
+
+Tools can return error information alongside text content using the `error` parameter.
+
+The error will be included in the JSON-RPC response as the `isError` field.
+
+```ruby
+class WeatherTool < MCP::Tool
+  description "Get current weather and return structured data"
+
+  def self.call(server_context:)
+    # Do something here
+    content = {}
+
+    MCP::Tool::Response.new(
+      [{
+        type: "text",
+        text: content.to_json
+      }],
+      structured_content: content,
+      error: true
+    )
+  end
+end
+```
+
 ### 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.
+MCP spec includes [Prompts](https://modelcontextprotocol.io/specification/latest/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:
 
@@ -618,7 +1073,7 @@ The `MCP::Prompt` class provides three ways to create prompts:
 ```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.
+  title "My Prompt"
   description "This prompt performs specific functionality..."
   arguments [
     MCP::Prompt::Argument.new(
@@ -657,7 +1112,7 @@ 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.
+  title: "My Prompt",
   description: "This prompt performs specific functionality...",
   arguments: [
     MCP::Prompt::Argument.new(
@@ -745,34 +1200,9 @@ The server will handle prompt listing and execution through the MCP protocol met
 - `prompts/list` - Lists all registered prompts and their schemas
 - `prompts/get` - Retrieves and executes a specific prompt with arguments
 
-### Instrumentation
-
-The server allows registering a callback to receive information about instrumentation.
-To register a handler pass a proc/lambda to as `instrumentation_callback` into the server constructor.
-
-```ruby
-MCP.configure do |config|
-  config.instrumentation_callback = ->(data) {
-    puts "Got instrumentation data #{data.inspect}"
-  }
-end
-```
-
-The data contains the following keys:
-
-- `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
 
-MCP spec includes [Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources).
+MCP spec includes [Resources](https://modelcontextprotocol.io/specification/latest/server/resources).
 
 ### Reading Resources
 
@@ -782,7 +1212,7 @@ The `MCP::Resource` class provides a way to register resources with the server.
 resource = MCP::Resource.new(
   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.
+  title: "My Resource",
   description: "Lorem ipsum dolor sit amet",
   mime_type: "text/html",
 )
@@ -815,7 +1245,7 @@ The `MCP::ResourceTemplate` class provides a way to register resource templates
 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.
+  title: "My Resource Template",
   description: "Lorem ipsum dolor sit amet",
   mime_type: "text/html",
 )
@@ -835,7 +1265,11 @@ This class supports:
 - Tool listing via the `tools/list` method (`MCP::Client#tools`)
 - Tool invocation via the `tools/call` method (`MCP::Client#call_tools`)
 - Resource listing via the `resources/list` method (`MCP::Client#resources`)
+- Resource template listing via the `resources/templates/list` method (`MCP::Client#resource_templates`)
 - Resource reading via the `resources/read` method (`MCP::Client#read_resources`)
+- Prompt listing via the `prompts/list` method (`MCP::Client#prompts`)
+- Prompt retrieval via the `prompts/get` method (`MCP::Client#get_prompt`)
+- Completion requests via the `completion/complete` method (`MCP::Client#complete`)
 - Automatic JSON-RPC 2.0 message formatting
 - UUID request ID generation
 
@@ -864,6 +1298,52 @@ class CustomTransport
 end
 ```
 
+### Stdio Transport Layer
+
+Use the `MCP::Client::Stdio` transport to interact with MCP servers running as subprocesses over standard input/output.
+
+`MCP::Client::Stdio.new` accepts the following keyword arguments:
+
+| Parameter | Required | Description |
+|---|---|---|
+| `command:` | Yes | The command to spawn the server process (e.g., `"ruby"`, `"bundle"`, `"npx"`). |
+| `args:` | No | An array of arguments passed to the command. Defaults to `[]`. |
+| `env:` | No | A hash of environment variables to set for the server process. Defaults to `nil`. |
+| `read_timeout:` | No | Timeout in seconds for waiting for a server response. Defaults to `nil` (no timeout). |
+
+Example usage:
+
+```ruby
+stdio_transport = MCP::Client::Stdio.new(
+  command: "bundle",
+  args: ["exec", "ruby", "path/to/server.rb"],
+  env: { "API_KEY" => "my_secret_key" },
+  read_timeout: 30
+)
+client = MCP::Client.new(transport: stdio_transport)
+
+# List available tools.
+tools = client.tools
+tools.each do |tool|
+  puts "Tool: #{tool.name} - #{tool.description}"
+end
+
+# Call a specific tool.
+response = client.call_tool(
+  tool: tools.first,
+  arguments: { message: "Hello, world!" }
+)
+
+# Close the transport when done.
+stdio_transport.close
+```
+
+The stdio transport automatically handles:
+
+- Spawning the server process with `Open3.popen3`
+- MCP protocol initialization handshake (`initialize` request + `notifications/initialized`)
+- JSON-RPC 2.0 message framing over newline-delimited JSON
+
 ### HTTP Transport Layer
 
 Use the `MCP::Client::HTTP` transport to interact with MCP servers using simple HTTP requests.
@@ -896,8 +1376,17 @@ response = client.call_tool(
   tool: tools.first,
   arguments: { message: "Hello, world!" }
 )
+
+# Call a tool with progress tracking.
+response = client.call_tool(
+  tool: tools.first,
+  arguments: { count: 10 },
+  progress_token: "my-progress-token"
+)
 ```
 
+The server will send `notifications/progress` back to the client during execution.
+
 #### 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:
@@ -924,15 +1413,13 @@ The client provides a wrapper class for tools returned by the server:
 
 This class provides easy access to tool properties like name, description, input schema, and output schema.
 
-## Releases
+## Conformance Testing
 
-This gem is published to [RubyGems.org](https://rubygems.org/gems/mcp)
+The `conformance/` directory contains a test server and runner that validate the SDK against the MCP specification using [`@modelcontextprotocol/conformance`](https://github.com/modelcontextprotocol/conformance).
 
-Releases are triggered by PRs to the `main` branch updating the version number in `lib/mcp/version.rb`.
+See [conformance/README.md](conformance/README.md) for usage instructions.
 
-1. **Update the version number** in `lib/mcp/version.rb`, following [semver](https://semver.org/)
-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
+## Documentation
 
-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.
+- [SDK API documentation](https://rubydoc.info/gems/mcp)
+- [Model Context Protocol documentation](https://modelcontextprotocol.io)