mcp 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 149cbf6f8809235111648ffae6163abb1994cb5c2a4bd2240eb696f17197e421
-  data.tar.gz: 7c526f405b013d868032122484079ce715ef8db9629d78dc5c8635fccaf2fc6f
+  metadata.gz: 29a39b8c5bb27a2fcdc8d084dce2cd79dfada5981a18d156bc1de78604035b2e
+  data.tar.gz: d969675cb0bb08b9ee3971a9bd90891767c7b28d68fe60579cf4857a06ff3680
 SHA512:
-  metadata.gz: b7dcdebe8faa024fe784a894ae6383d2bcd812f41a3a492c75429034ed8f062a8da49963a94a159ce2af25928cccfbb92cb629be98ead1d751d54389e3dfc9a3
-  data.tar.gz: 9c6f1fb122e3d636da0a7585fe38bd3ea567ba98c2899d91ef87136b69e8d0c93007c3f031915b44c835d16bbcd1465875decc459e5a34aada517541b91d369f
+  metadata.gz: 3ff992068b54cc35acd43bc9e93edb3959f270a19eedf52540748344f2a94488829cbfec65dedb2772d67dd883f7536523af25d6419ded2cc71944359ff2d016
+  data.tar.gz: 0f716e3f54ca10619f95787c65dfe01fecc2356474ddf2909dfb2918f544f3fc8aa2a1a798836b2c556a9178ad842472fd79820ad83e96e855e4ca1ded4f5d8b

data/README.md

@@ -108,13 +108,22 @@ 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_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:
@@ -122,8 +131,58 @@ 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
+
 ### 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).
@@ -228,6 +287,14 @@ 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
@@ -242,11 +309,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 +324,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 +447,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 +1084,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 +1162,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.
@@ -88,11 +92,17 @@ module MCP
 
     # Calls a tool via the transport layer and returns the full response from the server.
     #
+    # @param name [String] The name of the tool to call.
     # @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
+    # @example Call by name
+    #   response = client.call_tool(name: "my_tool", arguments: { foo: "bar" })
+    #   content = response.dig("result", "content")
+    #
+    # @example Call with a tool object
     #   tool = client.tools.first
     #   response = client.call_tool(tool: tool, arguments: { foo: "bar" })
     #   structured_content = response.dig("result", "structuredContent")
@@ -100,12 +110,20 @@ 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(name: nil, tool: nil, arguments: nil, progress_token: nil)
+      tool_name = name || tool&.name
+      raise ArgumentError, "Either `name:` or `tool:` must be provided." unless tool_name
+
+      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,22 @@
+# frozen_string_literal: true
+
+module MCP
+  class Progress
+    def initialize(notification_target:, progress_token:)
+      @notification_target = notification_target
+      @progress_token = progress_token
+    end
+
+    def report(progress, total: nil, message: nil)
+      return unless @progress_token
+      return unless @notification_target
+
+      @notification_target.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
@@ -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...")