mcp 0.9.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0f26c1a29af5a799a750d9ad00a224f39d24638a9ad267a540313f06da674ed
-  data.tar.gz: d340e2c1f6492f74a28c6dabc6a04575285269e13a2352e3f747195d4dac1527
+  metadata.gz: 96d41b59f0a4af6d4f8b975fddb1611e9db6ce9abad93d1a49e41b0499d90e37
+  data.tar.gz: f22c32ee6cf069153e93a8a078d0e4c298216519a8237d600c5314851a910407
 SHA512:
-  metadata.gz: 7f428407e35305f1cb5a087bd7abb708df12d17abe6cb66f335c8dc2d82d1020407942dd36ad3cb200377e7d60783d87a72bab765b202ae8426cb267f5d3f46a
-  data.tar.gz: 49d835de35b9c6c124d99ffe82561a5f7554901d43971afbb82adfb31fe13d0d6d1b6782d460d9b861b6924cc43705266cb09e5de3afd9249b7caa68634fff63
+  metadata.gz: 8fe956d15d21c75eff61fc3a4b71fa8dc0c6f67271324656b5a3e4a908dfe5adb714a6b3ca7f21ce8432598ef388dd9d4039d9086a7adcf391355a132f5d0c01
+  data.tar.gz: 823aa108a3eb98f086ef8b31798074ae0f3a670e8256978b8d5ac2aa8bad8b6b772038fd5bf8550725be0e3e931ef880bdc5eb89b695b7395e253dd5b2ebffcb

data/README.md

@@ -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,6 +105,163 @@ 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.
@@ -113,9 +273,17 @@ 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_progress` - Send a progress notification for long-running operations
 - `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
 
 Notifications follow the JSON-RPC 2.0 specification and use these method names:
@@ -169,25 +337,58 @@ The `server_context.report_progress` method accepts:
 - `total:` (optional) — total expected value, so clients can display a percentage
 - `message:` (optional) — human-readable status message
 
-#### Server-Side: Direct `notify_progress` Usage
+**Key Features:**
 
-You can also call `notify_progress` directly on the server instance:
+- 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.notify_progress(
-  progress_token: "token-123",
-  progress: 50,
-  total: 100,        # optional
-  message: "halfway" # optional
+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
 ```
 
-**Key Features:**
+The handler receives a `params` hash with:
 
-- Tools report progress via `server_context.report_progress`
-- `report_progress` is a no-op when no `progressToken` was provided by the client
-- `notify_progress` is a no-op when no transport is configured
-- Supports both numeric and string progress tokens
+- `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
 
@@ -293,14 +494,28 @@ Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`
 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)
 
 - 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
@@ -1054,6 +1269,7 @@ This class supports:
 - 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
 

data/lib/json_rpc_handler.rb

@@ -92,7 +92,7 @@ module JsonRpcHandler
     end
 
     begin
-      method = method_finder.call(method_name)
+      method = method_finder.call(method_name, id)
 
       if method.nil?
         return error_response(id: id, id_validation_pattern: id_validation_pattern, error: {

data/lib/mcp/client.rb

@@ -6,6 +6,27 @@ require_relative "client/tool"
 
 module MCP
   class Client
+    class ServerError < StandardError
+      attr_reader :code, :data
+
+      def initialize(message, code:, data: nil)
+        super(message)
+        @code = code
+        @data = data
+      end
+    end
+
+    class RequestHandlerError < StandardError
+      attr_reader :error_type, :original_error, :request
+
+      def initialize(message, request, error_type: :internal_error, original_error: nil)
+        super(message)
+        @request = request
+        @error_type = error_type
+        @original_error = original_error
+      end
+    end
+
     # Initializes a new MCP::Client instance.
     #
     # @param transport [Object] The transport object to use for communication with the server.
@@ -33,11 +54,7 @@ module MCP
     #     puts tool.name
     #   end
     def tools
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "tools/list",
-      })
+      response = request(method: "tools/list")
 
       response.dig("result", "tools")&.map do |tool|
         Tool.new(
@@ -53,11 +70,7 @@ module MCP
     #
     # @return [Array<Hash>] An array of available resources.
     def resources
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "resources/list",
-      })
+      response = request(method: "resources/list")
 
       response.dig("result", "resources") || []
     end
@@ -67,11 +80,7 @@ module MCP
     #
     # @return [Array<Hash>] An array of available resource templates.
     def resource_templates
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "resources/templates/list",
-      })
+      response = request(method: "resources/templates/list")
 
       response.dig("result", "resourceTemplates") || []
     end
@@ -81,11 +90,7 @@ module MCP
     #
     # @return [Array<Hash>] An array of available prompts.
     def prompts
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "prompts/list",
-      })
+      response = request(method: "prompts/list")
 
       response.dig("result", "prompts") || []
     end
@@ -119,12 +124,7 @@ module MCP
         params[:_meta] = { progressToken: progress_token }
       end
 
-      transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "tools/call",
-        params: params,
-      })
+      request(method: "tools/call", params: params)
     end
 
     # Reads a resource from the server by URI and returns the contents.
@@ -132,12 +132,7 @@ module MCP
     # @param uri [String] The URI of the resource to read.
     # @return [Array<Hash>] An array of resource contents (text or blob).
     def read_resource(uri:)
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "resources/read",
-        params: { uri: uri },
-      })
+      response = request(method: "resources/read", params: { uri: uri })
 
       response.dig("result", "contents") || []
     end
@@ -147,31 +142,50 @@ module MCP
     # @param name [String] The name of the prompt to get.
     # @return [Hash] A hash containing the prompt details.
     def get_prompt(name:)
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "prompts/get",
-        params: { name: name },
-      })
+      response = request(method: "prompts/get", params: { name: name })
 
       response.fetch("result", {})
     end
 
+    # Requests completion suggestions from the server for a prompt argument or resource template URI.
+    #
+    # @param ref [Hash] The reference, e.g. `{ type: "ref/prompt", name: "my_prompt" }`
+    #   or `{ type: "ref/resource", uri: "file:///{path}" }`.
+    # @param argument [Hash] The argument being completed, e.g. `{ name: "language", value: "py" }`.
+    # @param context [Hash, nil] Optional context with previously resolved arguments.
+    # @return [Hash] The completion result with `"values"`, `"hasMore"`, and optionally `"total"`.
+    def complete(ref:, argument:, context: nil)
+      params = { ref: ref, argument: argument }
+      params[:context] = context if context
+
+      response = request(method: "completion/complete", params: params)
+
+      response.dig("result", "completion") || { "values" => [], "hasMore" => false }
+    end
+
     private
 
-    def request_id
-      SecureRandom.uuid
-    end
+    def request(method:, params: nil)
+      request_body = {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: method,
+      }
+      request_body[:params] = params if params
 
-    class RequestHandlerError < StandardError
-      attr_reader :error_type, :original_error, :request
+      response = transport.send_request(request: request_body)
 
-      def initialize(message, request, error_type: :internal_error, original_error: nil)
-        super(message)
-        @request = request
-        @error_type = error_type
-        @original_error = original_error
+      # Guard with `is_a?(Hash)` because custom transports may return non-Hash values.
+      if response.is_a?(Hash) && response.key?("error")
+        error = response["error"]
+        raise ServerError.new(error["message"], code: error["code"], data: error["data"])
       end
+
+      response
+    end
+
+    def request_id
+      SecureRandom.uuid
     end
   end
 end

data/lib/mcp/progress.rb

@@ -2,19 +2,22 @@
 
 module MCP
   class Progress
-    def initialize(server:, progress_token:)
-      @server = server
+    def initialize(notification_target:, progress_token:, related_request_id: nil)
+      @notification_target = notification_target
       @progress_token = progress_token
+      @related_request_id = related_request_id
     end
 
     def report(progress, total: nil, message: nil)
       return unless @progress_token
+      return unless @notification_target
 
-      @server.notify_progress(
+      @notification_target.notify_progress(
         progress_token: @progress_token,
         progress: progress,
         total: total,
         message: message,
+        related_request_id: @related_request_id,
       )
     end
   end

data/lib/mcp/server/transports/stdio_transport.rb

@@ -10,17 +10,19 @@ module MCP
         STATUS_INTERRUPTED = Signal.list["INT"] + 128
 
         def initialize(server)
-          @server = server
+          super(server)
           @open = false
+          @session = nil
           $stdin.set_encoding("UTF-8")
           $stdout.set_encoding("UTF-8")
-          super
         end
 
         def open
           @open = true
+          @session = ServerSession.new(server: @server, transport: self)
           while @open && (line = $stdin.gets)
-            handle_json_request(line.strip)
+            response = @session.handle_json(line.strip)
+            send_response(response) if response
           end
         rescue Interrupt
           warn("\nExiting...")
@@ -51,6 +53,41 @@ module MCP
           MCP.configuration.exception_reporter.call(e, { error: "Failed to send notification" })
           false
         end
+
+        def send_request(method, params = nil)
+          request_id = generate_request_id
+          request = { jsonrpc: "2.0", id: request_id, method: method }
+          request[:params] = params if params
+
+          begin
+            send_response(request)
+          rescue => e
+            MCP.configuration.exception_reporter.call(e, { error: "Failed to send request" })
+            raise
+          end
+
+          while @open && (line = $stdin.gets)
+            begin
+              parsed = JSON.parse(line.strip, symbolize_names: true)
+            rescue JSON::ParserError => e
+              MCP.configuration.exception_reporter.call(e, { error: "Failed to parse response" })
+              raise
+            end
+
+            if parsed[:id] == request_id && !parsed.key?(:method)
+              if parsed[:error]
+                raise StandardError, "Client returned an error for #{method} request (code: #{parsed[:error][:code]}): #{parsed[:error][:message]}"
+              end
+
+              return parsed[:result]
+            else
+              response = @session ? @session.handle(parsed) : @server.handle(parsed)
+              send_response(response) if response
+            end
+          end
+
+          raise "Transport closed while waiting for response to #{method} request."
+        end
       end
     end
   end