mcp 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 149cbf6f8809235111648ffae6163abb1994cb5c2a4bd2240eb696f17197e421
-  data.tar.gz: 7c526f405b013d868032122484079ce715ef8db9629d78dc5c8635fccaf2fc6f
+  metadata.gz: d5cd1f7d23be518ff8bff1b1710ff8e8c4ba86ba3d55417e991f921057c0841d
+  data.tar.gz: 8e6bba0111698a39ff5aeaa0b4a34e51822018ac943b13b828f9bd2965062ddb
 SHA512:
-  metadata.gz: b7dcdebe8faa024fe784a894ae6383d2bcd812f41a3a492c75429034ed8f062a8da49963a94a159ce2af25928cccfbb92cb629be98ead1d751d54389e3dfc9a3
-  data.tar.gz: 9c6f1fb122e3d636da0a7585fe38bd3ea567ba98c2899d91ef87136b69e8d0c93007c3f031915b44c835d16bbcd1465875decc459e5a34aada517541b91d369f
+  metadata.gz: 1f9689d2ecb0a2b4e5ba6888e515d577a12d1f41cd48be8459c2d90ad3b7e4cbe7f557c23aac134a8426bf7bfaba2c3579ab496817ade2ff0fd24056286e52cd
+  data.tar.gz: 03601ddc6bf751a75ec6bbadc67458ab9d49367feac7b834d90072028e41a2d1046ed3da6551832482884f435c8779620071f1aa5df66753cf9afade090eb220

data/README.md

@@ -108,11 +108,12 @@ The server supports sending notifications to clients when lists of tools, prompt
 
 #### 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_progress` - Send a progress notification for long-running operations
 - `notify_log_message` - Send a structured logging notification message
 
 #### Notification Format
@@ -122,8 +123,72 @@ 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
+
+#### Server-Side: Direct `notify_progress` Usage
+
+You can also call `notify_progress` directly on the server instance:
+
+```ruby
+server.notify_progress(
+  progress_token: "token-123",
+  progress: 50,
+  total: 100,        # optional
+  message: "halfway" # optional
+)
+```
+
+**Key Features:**
+
+- 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
+
 ### 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).
@@ -242,11 +307,12 @@ When added to a Rails controller on a route that handles POST requests, your ser
 [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",
@@ -256,7 +322,11 @@ class ApplicationController < ActionController::Base
       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
 ```
@@ -375,6 +445,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
@@ -968,6 +1082,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.
@@ -1000,8 +1160,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:

data/lib/mcp/client/stdio.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "securerandom"
+require "timeout"
+require_relative "../../json_rpc_handler"
+require_relative "../configuration"
+require_relative "../methods"
+require_relative "../version"
+
+module MCP
+  class Client
+    class Stdio
+      # Seconds to wait for the server process to exit before sending SIGTERM.
+      # Matches the Python and TypeScript SDKs' shutdown timeout:
+      # https://github.com/modelcontextprotocol/python-sdk/blob/v1.26.0/src/mcp/client/stdio/__init__.py#L48
+      # https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.27.1/src/client/stdio.ts#L221
+      CLOSE_TIMEOUT = 2
+      STDERR_READ_SIZE = 4096
+
+      attr_reader :command, :args, :env
+
+      def initialize(command:, args: [], env: nil, read_timeout: nil)
+        @command = command
+        @args = args
+        @env = env
+        @read_timeout = read_timeout
+        @stdin = nil
+        @stdout = nil
+        @stderr = nil
+        @wait_thread = nil
+        @stderr_thread = nil
+        @started = false
+        @initialized = false
+      end
+
+      def send_request(request:)
+        start unless @started
+        initialize_session unless @initialized
+
+        write_message(request)
+        read_response(request)
+      end
+
+      def start
+        raise "MCP::Client::Stdio already started" if @started
+
+        spawn_env = @env || {}
+        @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(spawn_env, @command, *@args)
+        @stdout.set_encoding("UTF-8")
+        @stdin.set_encoding("UTF-8")
+
+        # Drain stderr in the background to prevent the pipe buffer from filling up,
+        # which would cause the server process to block and deadlock.
+        @stderr_thread = Thread.new do
+          loop do
+            @stderr.readpartial(STDERR_READ_SIZE)
+          end
+        rescue IOError
+          nil
+        end
+
+        @started = true
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ENOEXEC => e
+        raise RequestHandlerError.new(
+          "Failed to spawn server process: #{e.message}",
+          {},
+          error_type: :internal_error,
+          original_error: e,
+        )
+      end
+
+      def close
+        return unless @started
+
+        @stdin.close
+        @stdout.close
+        @stderr.close
+
+        begin
+          Timeout.timeout(CLOSE_TIMEOUT) { @wait_thread.value }
+        rescue Timeout::Error
+          begin
+            Process.kill("TERM", @wait_thread.pid)
+            Timeout.timeout(CLOSE_TIMEOUT) { @wait_thread.value }
+          rescue Timeout::Error
+            begin
+              Process.kill("KILL", @wait_thread.pid)
+            rescue Errno::ESRCH
+              nil
+            end
+          rescue Errno::ESRCH
+            nil
+          end
+        end
+
+        @stderr_thread.join(CLOSE_TIMEOUT)
+        @started = false
+        @initialized = false
+      end
+
+      private
+
+      # The client MUST send a protocol version it supports. This SHOULD be the latest version.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#version-negotiation
+      #
+      # Always sends `LATEST_STABLE_PROTOCOL_VERSION`, matching the Python and TypeScript SDKs:
+      # https://github.com/modelcontextprotocol/python-sdk/blob/v1.26.0/src/mcp/client/session.py#L175
+      # https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.27.1/src/client/index.ts#L495
+      def initialize_session
+        init_request = {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          id: SecureRandom.uuid,
+          method: MCP::Methods::INITIALIZE,
+          params: {
+            protocolVersion: MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "mcp-ruby-client", version: MCP::VERSION },
+          },
+        }
+
+        write_message(init_request)
+        response = read_response(init_request)
+
+        if response.key?("error")
+          error = response["error"]
+          raise RequestHandlerError.new(
+            "Server initialization failed: #{error["message"]}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        unless response.key?("result")
+          raise RequestHandlerError.new(
+            "Server initialization failed: missing result in response",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        notification = {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
+        }
+        write_message(notification)
+
+        @initialized = true
+      end
+
+      def write_message(message)
+        ensure_running!
+        json = JSON.generate(message)
+        @stdin.puts(json)
+        @stdin.flush
+      rescue IOError, Errno::EPIPE => e
+        raise RequestHandlerError.new(
+          "Failed to write to server process",
+          {},
+          error_type: :internal_error,
+          original_error: e,
+        )
+      end
+
+      def read_response(request)
+        request_id = request[:id] || request["id"]
+        method = request[:method] || request["method"]
+        params = request[:params] || request["params"]
+
+        loop do
+          ensure_running!
+          wait_for_readable!(method, params) if @read_timeout
+          line = @stdout.gets
+          raise_connection_error!(method, params) if line.nil?
+
+          parsed = JSON.parse(line.strip)
+
+          next unless parsed.key?("id")
+
+          return parsed if parsed["id"] == request_id
+        end
+      rescue JSON::ParserError => e
+        raise RequestHandlerError.new(
+          "Failed to parse server response",
+          { method: method, params: params },
+          error_type: :internal_error,
+          original_error: e,
+        )
+      end
+
+      def ensure_running!
+        return if @wait_thread.alive?
+
+        raise RequestHandlerError.new(
+          "Server process has exited",
+          {},
+          error_type: :internal_error,
+        )
+      end
+
+      def wait_for_readable!(method, params)
+        ready = @stdout.wait_readable(@read_timeout)
+        return if ready
+
+        raise RequestHandlerError.new(
+          "Timed out waiting for server response",
+          { method: method, params: params },
+          error_type: :internal_error,
+        )
+      end
+
+      def raise_connection_error!(method, params)
+        raise RequestHandlerError.new(
+          "Server process closed stdout unexpectedly",
+          { method: method, params: params },
+          error_type: :internal_error,
+        )
+      end
+    end
+  end
+end

data/lib/mcp/client.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "client/stdio"
+require_relative "client/http"
+require_relative "client/tool"
+
 module MCP
   class Client
     # Initializes a new MCP::Client instance.
@@ -90,6 +94,7 @@ module MCP
     #
     # @param tool [MCP::Client::Tool] The tool to be called.
     # @param arguments [Object, nil] The arguments to pass to the tool.
+    # @param progress_token [String, Integer, nil] A token to request progress notifications from the server during tool execution.
     # @return [Hash] The full JSON-RPC response from the transport.
     #
     # @example
@@ -100,12 +105,17 @@ module MCP
     # @note
     #   The exact requirements for `arguments` are determined by the transport layer in use.
     #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
-    def call_tool(tool:, arguments: nil)
+    def call_tool(tool:, arguments: nil, progress_token: nil)
+      params = { name: tool.name, arguments: arguments }
+      if progress_token
+        params[:_meta] = { progressToken: progress_token }
+      end
+
       transport.send_request(request: {
         jsonrpc: JsonRpcHandler::Version::V2_0,
         id: request_id,
         method: "tools/call",
-        params: { name: tool.name, arguments: arguments },
+        params: params,
       })
     end
 

data/lib/mcp/progress.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MCP
+  class Progress
+    def initialize(server:, progress_token:)
+      @server = server
+      @progress_token = progress_token
+    end
+
+    def report(progress, total: nil, message: nil)
+      return unless @progress_token
+
+      @server.notify_progress(
+        progress_token: @progress_token,
+        progress: progress,
+        total: total,
+        message: message,
+      )
+    end
+  end
+end

data/lib/mcp/prompt.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "prompt/argument"
+require_relative "prompt/message"
+require_relative "prompt/result"
+
 module MCP
   class Prompt
     class << self

data/lib/mcp/resource.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "resource/contents"
+require_relative "resource/embedded"
+
 module MCP
   class Resource
     attr_reader :uri, :name, :title, :description, :icons, :mime_type

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "../../transport"
 require "json"
+require_relative "../../transport"
 
 module MCP
   class Server

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "../../transport"
 require "json"
 require "securerandom"
+require_relative "../../transport"
 
 module MCP
   class Server
@@ -154,13 +154,7 @@ module MCP
             return success_response
           end
 
-          session_id = request.env["HTTP_MCP_SESSION_ID"]
-
-          return [
-            400,
-            { "Content-Type" => "application/json" },
-            [{ error: "Missing session ID" }.to_json],
-          ] unless session_id
+          return missing_session_id_response unless (session_id = request.env["HTTP_MCP_SESSION_ID"])
 
           cleanup_session(session_id)
           success_response
@@ -193,6 +187,8 @@ module MCP
           return not_acceptable_response(required_types) unless accept_header
 
           accepted_types = parse_accept_header(accept_header)
+          return if accepted_types.include?("*/*")
+
           missing_types = required_types - accepted_types
           return not_acceptable_response(required_types) unless missing_types.empty?
 
@@ -257,31 +253,23 @@ module MCP
 
         def handle_regular_request(body_string, session_id)
           unless @stateless
-            # If session ID is provided, but not in the sessions hash, return an error
-            if session_id && !@sessions.key?(session_id)
-              return [400, { "Content-Type" => "application/json" }, [{ error: "Invalid session ID" }.to_json]]
+            if session_id && !session_exists?(session_id)
+              return session_not_found_response
             end
           end
 
-          response = @server.handle_json(body_string) || ""
+          response = @server.handle_json(body_string)
 
           # Stream can be nil since stateless mode doesn't retain streams
           stream = get_session_stream(session_id) if session_id
 
           if stream
             send_response_to_stream(stream, response, session_id)
-          elsif response.nil? && notification_request?(body_string)
-            [202, { "Content-Type" => "application/json" }, [response]]
           else
             [200, { "Content-Type" => "application/json" }, [response]]
           end
         end
 
-        def notification_request?(body_string)
-          body = parse_request_body(body_string)
-          body.is_a?(Hash) && body["method"].start_with?("notifications/")
-        end
-
         def get_session_stream(session_id)
           @mutex.synchronize { @sessions[session_id]&.fetch(:stream, nil) }
         end

data/lib/mcp/server/transports.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    module Transports
+      autoload :StdioTransport, "mcp/server/transports/stdio_transport"
+      autoload :StreamableHTTPTransport, "mcp/server/transports/streamable_http_transport"
+    end
+  end
+end