ruby-mcp-client 0.5.3 → 0.6.1

data/lib/mcp_client/server_stdio/json_rpc_transport.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'mcp_client/json_rpc_common'
+
+module MCPClient
+  class ServerStdio
+    # JSON-RPC request/notification plumbing for stdio transport
+    module JsonRpcTransport
+      include JsonRpcCommon
+      # Ensure the server process is started and initialized (handshake)
+      # @return [void]
+      # @raise [MCPClient::Errors::ConnectionError] if initialization fails
+      def ensure_initialized
+        return if @initialized
+
+        connect
+        start_reader
+        perform_initialize
+
+        @initialized = true
+      end
+
+      # Handshake: send initialize request and initialized notification
+      # @return [void]
+      # @raise [MCPClient::Errors::ConnectionError] if initialization fails
+      def perform_initialize
+        # Initialize request
+        init_id = next_id
+        init_req = build_jsonrpc_request('initialize', initialization_params, init_id)
+        send_request(init_req)
+        res = wait_response(init_id)
+        if (err = res['error'])
+          raise MCPClient::Errors::ConnectionError, "Initialize failed: #{err['message']}"
+        end
+
+        # Send initialized notification
+        notif = build_jsonrpc_notification('notifications/initialized', {})
+        @stdin.puts(notif.to_json)
+      end
+
+      # Generate a new unique request ID
+      # @return [Integer] a unique request ID
+      def next_id
+        @mutex.synchronize do
+          id = @next_id
+          @next_id += 1
+          id
+        end
+      end
+
+      # Send a JSON-RPC request and return nothing
+      # @param req [Hash] the JSON-RPC request
+      # @return [void]
+      # @raise [MCPClient::Errors::TransportError] on write errors
+      def send_request(req)
+        @logger.debug("Sending JSONRPC request: #{req.to_json}")
+        @stdin.puts(req.to_json)
+      rescue StandardError => e
+        raise MCPClient::Errors::TransportError, "Failed to send JSONRPC request: #{e.message}"
+      end
+
+      # Wait for a response with the given request ID
+      # @param id [Integer] the request ID
+      # @return [Hash] the JSON-RPC response message
+      # @raise [MCPClient::Errors::TransportError] on timeout
+      def wait_response(id)
+        deadline = Time.now + @read_timeout
+        @mutex.synchronize do
+          until @pending.key?(id)
+            remaining = deadline - Time.now
+            break if remaining <= 0
+
+            @cond.wait(@mutex, remaining)
+          end
+          msg = @pending[id]
+          @pending[id] = nil
+          raise MCPClient::Errors::TransportError, "Timeout waiting for JSONRPC response id=#{id}" unless msg
+
+          msg
+        end
+      end
+
+      # Stream tool call fallback for stdio transport (yields single result)
+      # @param tool_name [String] the name of the tool to call
+      # @param parameters [Hash] the parameters to pass to the tool
+      # @return [Enumerator] a stream containing a single result
+      def call_tool_streaming(tool_name, parameters)
+        Enumerator.new do |yielder|
+          yielder << call_tool(tool_name, parameters)
+        end
+      end
+
+      # Generic JSON-RPC request: send method with params and wait for result
+      # @param method [String] JSON-RPC method
+      # @param params [Hash] parameters for the request
+      # @return [Object] result from JSON-RPC response
+      # @raise [MCPClient::Errors::ServerError] if server returns an error
+      # @raise [MCPClient::Errors::TransportError] on transport errors
+      # @raise [MCPClient::Errors::ToolCallError] on tool call errors
+      def rpc_request(method, params = {})
+        ensure_initialized
+        with_retry do
+          req_id = next_id
+          req = build_jsonrpc_request(method, params, req_id)
+          send_request(req)
+          res = wait_response(req_id)
+          process_jsonrpc_response(res)
+        end
+      end
+
+      # Send a JSON-RPC notification (no response expected)
+      # @param method [String] JSON-RPC method
+      # @param params [Hash] parameters for the notification
+      # @return [void]
+      def rpc_notify(method, params = {})
+        ensure_initialized
+        notif = build_jsonrpc_notification(method, params)
+        @stdin.puts(notif.to_json)
+      end
+    end
+  end
+end

data/lib/mcp_client/server_stdio.rb

@@ -8,18 +8,31 @@ require 'logger'
 module MCPClient
   # JSON-RPC implementation of MCP server over stdio.
   class ServerStdio < ServerBase
-    attr_reader :command
+    require 'mcp_client/server_stdio/json_rpc_transport'
+
+    include JsonRpcTransport
+
+    # @!attribute [r] command
+    #   @return [String, Array] the command used to launch the server
+    # @!attribute [r] env
+    #   @return [Hash] environment variables for the subprocess
+    attr_reader :command, :env
 
     # Timeout in seconds for responses
     READ_TIMEOUT = 15
 
+    # Initialize a new ServerStdio instance
     # @param command [String, Array] the stdio command to launch the MCP JSON-RPC server
+    #   For improved security, passing an Array is recommended to avoid shell injection issues
     # @param retries [Integer] number of retry attempts on transient errors
     # @param retry_backoff [Numeric] base delay in seconds for exponential backoff
     # @param read_timeout [Numeric] timeout in seconds for reading responses
+    # @param name [String, nil] optional name for this server
     # @param logger [Logger, nil] optional logger
-    def initialize(command:, retries: 0, retry_backoff: 1, read_timeout: READ_TIMEOUT, logger: nil)
-      super()
+    # @param env [Hash] optional environment variables for the subprocess
+    def initialize(command:, retries: 0, retry_backoff: 1, read_timeout: READ_TIMEOUT, name: nil, logger: nil, env: {})
+      super(name: name)
+      @command_array = command.is_a?(Array) ? command : nil
       @command = command.is_a?(Array) ? command.join(' ') : command
       @mutex = Mutex.new
       @cond = ConditionVariable.new
@@ -29,22 +42,36 @@ module MCPClient
       @logger = logger || Logger.new($stdout, level: Logger::WARN)
       @logger.progname = self.class.name
       @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
-      @max_retries = retries
+      @max_retries   = retries
       @retry_backoff = retry_backoff
-      @read_timeout = read_timeout
+      @read_timeout  = read_timeout
+      @env           = env || {}
     end
 
     # Connect to the MCP server by launching the command process via stdout/stdin
     # @return [Boolean] true if connection was successful
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
     def connect
-      @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@command)
+      if @command_array
+        if @env.any?
+          @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@env, *@command_array)
+        else
+          @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(*@command_array)
+        end
+      else
+        if @env.any?
+          @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@env, @command)
+        else
+          @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@command)
+        end
+      end
       true
     rescue StandardError => e
       raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server: #{e.message}"
     end
 
     # Spawn a reader thread to collect JSON-RPC responses
+    # @return [Thread] the reader thread
     def start_reader
       @reader_thread = Thread.new do
         @stdout.each_line do |line|
@@ -58,6 +85,7 @@ module MCPClient
     # Handle a line of output from the stdio server
     # Parses JSON-RPC messages and adds them to pending responses
     # @param line [String] line of output to parse
+    # @return [void]
     def handle_line(line)
       msg = JSON.parse(line)
       @logger.debug("Received line: #{line.chomp}")
@@ -93,7 +121,7 @@ module MCPClient
         raise MCPClient::Errors::ServerError, err['message']
       end
 
-      (res.dig('result', 'tools') || []).map { |td| MCPClient::Tool.from_json(td) }
+      (res.dig('result', 'tools') || []).map { |td| MCPClient::Tool.from_json(td, server: self) }
     rescue StandardError => e
       raise MCPClient::Errors::ToolCallError, "Error listing tools: #{e.message}"
     end
@@ -127,6 +155,7 @@ module MCPClient
 
     # Clean up the server connection
     # Closes all stdio handles and terminates any running processes and threads
+    # @return [void]
     def cleanup
       return unless @stdin
 
@@ -143,125 +172,5 @@ module MCPClient
     ensure
       @stdin = @stdout = @stderr = @wait_thread = @reader_thread = nil
     end
-
-    private
-
-    # Ensure the server process is started and initialized (handshake)
-    def ensure_initialized
-      return if @initialized
-
-      connect
-      start_reader
-      perform_initialize
-
-      @initialized = true
-    end
-
-    # Handshake: send initialize request and initialized notification
-    def perform_initialize
-      # Initialize request
-      init_id = next_id
-      init_req = {
-        'jsonrpc' => '2.0',
-        'id' => init_id,
-        'method' => 'initialize',
-        'params' => {
-          'protocolVersion' => '2024-11-05',
-          'capabilities' => {},
-          'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
-        }
-      }
-      send_request(init_req)
-      res = wait_response(init_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ConnectionError, "Initialize failed: #{err['message']}"
-      end
-
-      # Send initialized notification
-      notif = { 'jsonrpc' => '2.0', 'method' => 'notifications/initialized', 'params' => {} }
-      @stdin.puts(notif.to_json)
-    end
-
-    def next_id
-      @mutex.synchronize do
-        id = @next_id
-        @next_id += 1
-        id
-      end
-    end
-
-    def send_request(req)
-      @logger.debug("Sending JSONRPC request: #{req.to_json}")
-      @stdin.puts(req.to_json)
-    rescue StandardError => e
-      raise MCPClient::Errors::TransportError, "Failed to send JSONRPC request: #{e.message}"
-    end
-
-    def wait_response(id)
-      deadline = Time.now + @read_timeout
-      @mutex.synchronize do
-        until @pending.key?(id)
-          remaining = deadline - Time.now
-          break if remaining <= 0
-
-          @cond.wait(@mutex, remaining)
-        end
-        msg = @pending[id]
-        @pending[id] = nil
-        raise MCPClient::Errors::TransportError, "Timeout waiting for JSONRPC response id=#{id}" unless msg
-
-        msg
-      end
-    end
-
-    # Stream tool call fallback for stdio transport (yields single result)
-    # @param tool_name [String]
-    # @param parameters [Hash]
-    # @return [Enumerator]
-    def call_tool_streaming(tool_name, parameters)
-      Enumerator.new do |yielder|
-        yielder << call_tool(tool_name, parameters)
-      end
-    end
-
-    # Generic JSON-RPC request: send method with params and wait for result
-    # @param method [String] JSON-RPC method
-    # @param params [Hash] parameters for the request
-    # @return [Object] result from JSON-RPC response
-    def rpc_request(method, params = {})
-      ensure_initialized
-      attempts = 0
-      begin
-        req_id = next_id
-        req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => method, 'params' => params }
-        send_request(req)
-        res = wait_response(req_id)
-        if (err = res['error'])
-          raise MCPClient::Errors::ServerError, err['message']
-        end
-
-        res['result']
-      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, IOError, Errno::ETIMEDOUT,
-             Errno::ECONNRESET => e
-        attempts += 1
-        if attempts <= @max_retries
-          delay = @retry_backoff * (2**(attempts - 1))
-          @logger.debug("Retry attempt #{attempts} after error: #{e.message}, sleeping #{delay}s")
-          sleep(delay)
-          retry
-        end
-        raise
-      end
-    end
-
-    # Send a JSON-RPC notification (no response expected)
-    # @param method [String] JSON-RPC method
-    # @param params [Hash] parameters for the notification
-    # @return [void]
-    def rpc_notify(method, params = {})
-      ensure_initialized
-      notif = { 'jsonrpc' => '2.0', 'method' => method, 'params' => params }
-      @stdin.puts(notif.to_json)
-    end
   end
 end

data/lib/mcp_client/tool.rb

@@ -3,24 +3,40 @@
 module MCPClient
   # Representation of an MCP tool
   class Tool
-    attr_reader :name, :description, :schema
+    # @!attribute [r] name
+    #   @return [String] the name of the tool
+    # @!attribute [r] description
+    #   @return [String] the description of the tool
+    # @!attribute [r] schema
+    #   @return [Hash] the JSON schema for the tool
+    # @!attribute [r] server
+    #   @return [MCPClient::ServerBase, nil] the server this tool belongs to
+    attr_reader :name, :description, :schema, :server
 
-    def initialize(name:, description:, schema:)
+    # Initialize a new Tool
+    # @param name [String] the name of the tool
+    # @param description [String] the description of the tool
+    # @param schema [Hash] the JSON schema for the tool
+    # @param server [MCPClient::ServerBase, nil] the server this tool belongs to
+    def initialize(name:, description:, schema:, server: nil)
       @name = name
       @description = description
       @schema = schema
+      @server = server
     end
 
     # Create a Tool instance from JSON data
     # @param data [Hash] JSON data from MCP server
+    # @param server [MCPClient::ServerBase, nil] the server this tool belongs to
     # @return [MCPClient::Tool] tool instance
-    def self.from_json(data)
+    def self.from_json(data, server: nil)
       # Some servers (Playwright MCP CLI) use 'inputSchema' instead of 'schema'
       schema = data['inputSchema'] || data['schema']
       new(
         name: data['name'],
         description: data['description'],
-        schema: schema
+        schema: schema,
+        server: server
       )
     end
 
@@ -47,6 +63,8 @@ module MCPClient
       }
     end
 
+    # Convert tool to Google Vertex AI tool specification format
+    # @return [Hash] Google Vertex AI tool specification with cleaned schema
     def to_google_tool
       {
         name: @name,

data/lib/mcp_client/version.rb

@@ -2,5 +2,8 @@
 
 module MCPClient
   # Current version of the MCP client gem
-  VERSION = '0.5.3'
+  VERSION = '0.6.1'
+
+  # JSON-RPC handshake protocol version (date-based)
+  PROTOCOL_VERSION = '2024-11-05'
 end

data/lib/mcp_client.rb

@@ -19,38 +19,50 @@ module MCPClient
   # @param mcp_server_configs [Array<Hash>] configurations for MCP servers
   # @param server_definition_file [String, nil] optional path to a JSON file defining server configurations
   #   The JSON may be a single server object or an array of server objects.
+  # @param logger [Logger, nil] optional logger for client operations
   # @return [MCPClient::Client] new client instance
-  def self.create_client(mcp_server_configs: [], server_definition_file: nil)
+  def self.create_client(mcp_server_configs: [], server_definition_file: nil, logger: nil)
     require 'json'
     # Start with any explicit configs provided
     configs = Array(mcp_server_configs)
     # Load additional configs from a JSON file if specified
     if server_definition_file
       # Parse JSON definitions into clean config hashes
-      parser = MCPClient::ConfigParser.new(server_definition_file)
+      parser = MCPClient::ConfigParser.new(server_definition_file, logger: logger)
       parsed = parser.parse
       parsed.each_value do |cfg|
         case cfg[:type].to_s
         when 'stdio'
-          # Build command list with args
+          # Build command list with args and propagate environment
           cmd_list = [cfg[:command]] + Array(cfg[:args])
-          configs << MCPClient.stdio_config(command: cmd_list)
+          configs << MCPClient.stdio_config(
+            command: cmd_list,
+            name: cfg[:name],
+            logger: logger,
+            env: cfg[:env]
+          )
         when 'sse'
           # Use 'url' from parsed config as 'base_url' for SSE config
-          configs << MCPClient.sse_config(base_url: cfg[:url], headers: cfg[:headers] || {})
+          configs << MCPClient.sse_config(base_url: cfg[:url], headers: cfg[:headers] || {}, name: cfg[:name],
+                                          logger: logger)
         end
       end
     end
-    MCPClient::Client.new(mcp_server_configs: configs)
+    MCPClient::Client.new(mcp_server_configs: configs, logger: logger)
   end
 
   # Create a standard server configuration for stdio
   # @param command [String, Array<String>] command to execute
+  # @param name [String, nil] optional name for this server
+  # @param logger [Logger, nil] optional logger for server operations
   # @return [Hash] server configuration
-  def self.stdio_config(command:)
+  def self.stdio_config(command:, name: nil, logger: nil, env: {})
     {
       type: 'stdio',
-      command: command
+      command: command,
+      name: name,
+      logger: logger,
+      env: env || {}
     }
   end
 
@@ -61,8 +73,11 @@ module MCPClient
   # @param ping [Integer] time in seconds after which to send ping if no activity (default: 10)
   # @param retries [Integer] number of retry attempts (default: 0)
   # @param retry_backoff [Integer] backoff delay in seconds (default: 1)
+  # @param name [String, nil] optional name for this server
+  # @param logger [Logger, nil] optional logger for server operations
   # @return [Hash] server configuration
-  def self.sse_config(base_url:, headers: {}, read_timeout: 30, ping: 10, retries: 0, retry_backoff: 1)
+  def self.sse_config(base_url:, headers: {}, read_timeout: 30, ping: 10, retries: 0, retry_backoff: 1,
+                      name: nil, logger: nil)
     {
       type: 'sse',
       base_url: base_url,
@@ -70,7 +85,9 @@ module MCPClient
       read_timeout: read_timeout,
       ping: ping,
       retries: retries,
-      retry_backoff: retry_backoff
+      retry_backoff: retry_backoff,
+      name: name,
+      logger: logger
     }
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.1
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-13 00:00:00.000000000 Z
+date: 2025-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -108,10 +108,15 @@ files:
 - lib/mcp_client/client.rb
 - lib/mcp_client/config_parser.rb
 - lib/mcp_client/errors.rb
+- lib/mcp_client/json_rpc_common.rb
 - lib/mcp_client/server_base.rb
 - lib/mcp_client/server_factory.rb
 - lib/mcp_client/server_sse.rb
+- lib/mcp_client/server_sse/json_rpc_transport.rb
+- lib/mcp_client/server_sse/reconnect_monitor.rb
+- lib/mcp_client/server_sse/sse_parser.rb
 - lib/mcp_client/server_stdio.rb
+- lib/mcp_client/server_stdio/json_rpc_transport.rb
 - lib/mcp_client/tool.rb
 - lib/mcp_client/version.rb
 homepage: https://github.com/simonx1/ruby-mcp-client