ruby-mcp-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0fd821eaf2b01a8628e7d54f2b39826b3d980d9e0d183ac0d81d5fb2ae135a36
+  data.tar.gz: 0d2afee24c1ebbb49f597056b9257546256e3152a4d789b7bc2789b3afc40a4f
+SHA512:
+  metadata.gz: b21d59cb475b4202442658dd81b3ee394f317b767fb0a1bacba3c575dc96ac4004a0849a4fc59b2d7481c75ae55181cca21f11a5ebbe2d15179eeb2a30aba242
+  data.tar.gz: 6a06a38dd0066331efcd1ec3a1eb5d6178dd12091a7f217199a314c891aef4b0100d3d7da9d12e3f69ac01da42d3eee60135f68ac43bf79cebf14f9fd43308e4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Szymon Kurcab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,218 @@
+# ruby-mcp-client
+
+This gem provides a Ruby client for the Model Context Protocol (MCP),
+enabling integration with external tools and services via a standardized protocol.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby-mcp-client'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install ruby-mcp-client
+```
+
+## Overview
+
+MCP enables AI assistants and other services to discover and invoke external tools
+via different transport mechanisms:
+
+- **Standard I/O**: Local processes implementing the MCP protocol
+- **Server-Sent Events (SSE)**: Remote MCP servers over HTTP
+
+The core client resides in `MCPClient::Client` and provides helper methods for integrating
+with popular AI services with built-in conversions:
+
+- `to_openai_tools()` - Formats tools for OpenAI API
+- `to_anthropic_tools()` - Formats tools for Anthropic Claude API
+
+## Usage
+
+### Basic Client Usage
+
+```ruby
+require 'mcp_client'
+
+client = MCPClient.create_client(
+  mcp_server_configs: [
+    # Local stdio server
+    MCPClient.stdio_config(command: 'npx -y @modelcontextprotocol/server-filesystem /home/user'),
+    # Remote HTTP SSE server
+    MCPClient.sse_config(
+      base_url: 'https://api.example.com/sse',
+      headers: { 'Authorization' => 'Bearer YOUR_TOKEN' },
+      read_timeout: 30 # Optional timeout in seconds (default: 30)
+    )
+  ]
+)
+
+# List available tools
+tools = client.list_tools
+
+# Call a specific tool by name
+result = client.call_tool('example_tool', { param1: 'value1', param2: 42 })
+
+# Format tools for specific AI services
+openai_tools = client.to_openai_tools
+anthropic_tools = client.to_anthropic_tools
+
+# Clean up connections
+client.cleanup
+```
+
+### Integration Examples
+
+The repository includes examples for integrating with popular AI APIs:
+
+#### OpenAI Integration
+
+Ruby-MCP-Client works with both official and community OpenAI gems:
+
+```ruby
+# Using the openai/openai-ruby gem (official)
+require 'mcp_client'
+require 'openai'
+
+# Create MCP client
+mcp_client = MCPClient.create_client(
+  mcp_server_configs: [
+    MCPClient.stdio_config(
+      command: %W[npx -y @modelcontextprotocol/server-filesystem #{Dir.pwd}]
+    )
+  ]
+)
+
+# Convert tools to OpenAI format
+tools = mcp_client.to_openai_tools
+
+# Use with OpenAI client
+client = OpenAI::Client.new(api_key: ENV['OPENAI_API_KEY'])
+response = client.chat.completions.create(
+  model: 'gpt-4',
+  messages: [
+    { role: 'user', content: 'List files in current directory' }
+  ],
+  tools: tools
+)
+
+# Process tool calls and results
+# See examples directory for complete implementation
+```
+
+```ruby
+# Using the alexrudall/ruby-openai gem (community)
+require 'mcp_client'
+require 'openai'
+
+# Create MCP client
+mcp_client = MCPClient.create_client(
+  mcp_server_configs: [
+    MCPClient.stdio_config(command: 'npx @playwright/mcp@latest')
+  ]
+)
+
+# Convert tools to OpenAI format
+tools = mcp_client.to_openai_tools
+
+# Use with Ruby-OpenAI client
+client = OpenAI::Client.new(access_token: ENV['OPENAI_API_KEY'])
+# See examples directory for complete implementation
+```
+
+#### Anthropic Integration
+
+```ruby
+require 'mcp_client'
+require 'anthropic'
+
+# Create MCP client
+mcp_client = MCPClient.create_client(
+  mcp_server_configs: [
+    MCPClient.stdio_config(
+      command: %W[npx -y @modelcontextprotocol/server-filesystem #{Dir.pwd}]
+    )
+  ]
+)
+
+# Convert tools to Anthropic format
+claude_tools = mcp_client.to_anthropic_tools
+
+# Use with Anthropic client
+client = Anthropic::Client.new(access_token: ENV['ANTHROPIC_API_KEY'])
+# See examples directory for complete implementation
+```
+
+Complete examples can be found in the `examples/` directory:
+- `ruby_openai_mcp.rb` - Integration with alexrudall/ruby-openai gem
+- `openai_ruby_mcp.rb` - Integration with official openai/openai-ruby gem
+- `ruby_anthropic_mcp.rb` - Integration with alexrudall/ruby-anthropic gem
+
+## MCP Server Compatibility
+
+This client works with any MCP-compatible server, including:
+
+- [@modelcontextprotocol/server-filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) - File system access
+- [@playwright/mcp](https://www.npmjs.com/package/@playwright/mcp) - Browser automation
+- Custom servers implementing the MCP protocol
+
+### Server-Sent Events (SSE) Implementation
+
+The SSE client implementation provides these key features:
+
+- **Robust connection handling**: Properly manages HTTP/HTTPS connections with configurable timeouts
+- **Thread safety**: All operations are thread-safe using monitors and synchronized access
+- **Reliable error handling**: Comprehensive error handling for network issues, timeouts, and malformed responses
+- **JSON-RPC over SSE**: Full implementation of JSON-RPC 2.0 over SSE transport
+
+## Requirements
+
+- Ruby >= 2.7.0
+- No runtime dependencies
+
+## Implementing an MCP Server
+
+To implement a compatible MCP server you must:
+
+- Listen on your chosen transport (JSON-RPC stdio, or HTTP SSE)
+- Respond to `list_tools` requests with a JSON list of tools
+- Respond to `call_tool` requests by executing the specified tool
+- Return results (or errors) in JSON format
+
+## Tool Schema
+
+Each tool is defined by a name, description, and a JSON Schema for its parameters:
+
+```json
+{
+  "name": "example_tool",
+  "description": "Does something useful",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "param1": { "type": "string" },
+      "param2": { "type": "number" }
+    },
+    "required": ["param1"]
+  }
+}
+```
+
+## License
+
+This gem is available as open source under the [MIT License](LICENSE).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/simonx1/ruby-mcp-client.

data/lib/mcp_client/client.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # MCP Client for integrating with the Model Context Protocol
+  # This is the main entry point for using MCP tools
+  class Client
+    attr_reader :servers, :tool_cache
+
+    def initialize(mcp_server_configs: [])
+      @servers = mcp_server_configs.map { |config| MCPClient::ServerFactory.create(config) }
+      @tool_cache = {}
+    end
+
+    # Lists all available tools from all connected MCP servers
+    # @param cache [Boolean] whether to use cached tools or fetch fresh
+    # @return [Array<MCPClient::Tool>] list of available tools
+    def list_tools(cache: true)
+      return @tool_cache.values if cache && !@tool_cache.empty?
+
+      tools = []
+      servers.each do |server|
+        server.list_tools.each do |tool|
+          @tool_cache[tool.name] = tool
+          tools << tool
+        end
+      end
+
+      tools
+    end
+
+    # Calls a specific tool by name with the given parameters
+    # @param tool_name [String] the name of the tool to call
+    # @param parameters [Hash] the parameters to pass to the tool
+    # @return [Object] the result of the tool invocation
+    def call_tool(tool_name, parameters)
+      tools = list_tools
+      tool = tools.find { |t| t.name == tool_name }
+
+      raise MCPClient::Errors::ToolNotFound, "Tool '#{tool_name}' not found" unless tool
+
+      # Find the server that owns this tool
+      server = find_server_for_tool(tool)
+      raise MCPClient::Errors::ServerNotFound, "No server found for tool '#{tool_name}'" unless server
+
+      server.call_tool(tool_name, parameters)
+    end
+
+    # Convert MCP tools to OpenAI function specifications
+    # @return [Array<Hash>] OpenAI function specifications
+    def to_openai_tools
+      list_tools.map(&:to_openai_tool)
+    end
+
+    # Convert MCP tools to Anthropic Claude tool specifications
+    # @return [Array<Hash>] Anthropic Claude tool specifications
+    def to_anthropic_tools
+      list_tools.map(&:to_anthropic_tool)
+    end
+
+    # Clean up all server connections
+    def cleanup
+      servers.each(&:cleanup)
+    end
+
+    private
+
+    def find_server_for_tool(tool)
+      servers.find do |server|
+        server.list_tools.any? { |t| t.name == tool.name }
+      end
+    end
+  end
+end

data/lib/mcp_client/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Collection of error classes used by the MCP client
+  module Errors
+    # Base error class for all MCP-related errors
+    class MCPError < StandardError; end
+
+    # Raised when a tool is not found
+    class ToolNotFound < MCPError; end
+
+    # Raised when a server is not found
+    class ServerNotFound < MCPError; end
+
+    # Raised when there's an error calling a tool
+    class ToolCallError < MCPError; end
+
+    # Raised when there's a connection error with an MCP server
+    class ConnectionError < MCPError; end
+
+    # Raised when the MCP server returns an error response
+    class ServerError < MCPError; end
+
+    # Raised when there's an error in the MCP server transport
+    class TransportError < MCPError; end
+  end
+end

data/lib/mcp_client/server_base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Base class for MCP servers - serves as the interface for different server implementations
+  class ServerBase
+    # Initialize a connection to the MCP server
+    # @return [Boolean] true if connection successful
+    def connect
+      raise NotImplementedError, 'Subclasses must implement connect'
+    end
+
+    # List all tools available from the MCP server
+    # @return [Array<MCPClient::Tool>] list of available tools
+    def list_tools
+      raise NotImplementedError, 'Subclasses must implement list_tools'
+    end
+
+    # Call a tool with the given parameters
+    # @param tool_name [String] the name of the tool to call
+    # @param parameters [Hash] the parameters to pass to the tool
+    # @return [Object] the result of the tool invocation
+    def call_tool(tool_name, parameters)
+      raise NotImplementedError, 'Subclasses must implement call_tool'
+    end
+
+    # Clean up the server connection
+    def cleanup
+      raise NotImplementedError, 'Subclasses must implement cleanup'
+    end
+  end
+end

data/lib/mcp_client/server_factory.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Factory for creating MCP server instances based on configuration
+  class ServerFactory
+    # Create a server instance based on configuration
+    # @param config [Hash] server configuration
+    # @return [MCPClient::ServerBase] server instance
+    def self.create(config)
+      case config[:type]
+      when 'stdio'
+        MCPClient::ServerStdio.new(command: config[:command])
+      when 'sse'
+        MCPClient::ServerSSE.new(
+          base_url: config[:base_url],
+          headers: config[:headers] || {},
+          read_timeout: config[:read_timeout] || 30
+        )
+      else
+        raise ArgumentError, "Unknown server type: #{config[:type]}"
+      end
+    end
+  end
+end

data/lib/mcp_client/server_sse.rb

@@ -0,0 +1,413 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'net/http'
+require 'json'
+require 'openssl'
+require 'monitor'
+
+module MCPClient
+  # Implementation of MCP server that communicates via Server-Sent Events (SSE)
+  # Useful for communicating with remote MCP servers over HTTP
+  class ServerSSE < ServerBase
+    attr_reader :base_url, :tools, :session_id, :http_client
+
+    # @param base_url [String] The base URL of the MCP server
+    # @param headers [Hash] Additional headers to include in requests
+    # @param read_timeout [Integer] Read timeout in seconds (default: 30)
+    def initialize(base_url:, headers: {}, read_timeout: 30)
+      super()
+      @base_url = base_url.end_with?('/') ? base_url : "#{base_url}/"
+      @headers = headers.merge({
+                                 'Accept' => 'text/event-stream',
+                                 'Cache-Control' => 'no-cache',
+                                 'Connection' => 'keep-alive'
+                               })
+      @http_client = nil
+      @tools = nil
+      @read_timeout = read_timeout
+      @session_id = nil
+      @tools_data = nil
+      @request_id = 0
+      @sse_results = {}
+      @mutex = Monitor.new
+      @buffer = ''
+      @sse_connected = false
+      @connection_established = false
+      @connection_cv = @mutex.new_cond
+    end
+
+    # List all tools available from the MCP server
+    # @return [Array<MCPClient::Tool>] list of available tools
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+    # @raise [MCPClient::Errors::ToolCallError] for other errors during tool listing
+    def list_tools
+      @mutex.synchronize do
+        return @tools if @tools
+      end
+
+      connect
+
+      begin
+        tools_data = request_tools_list
+        @mutex.synchronize do
+          @tools = tools_data.map do |tool_data|
+            MCPClient::Tool.from_json(tool_data)
+          end
+        end
+
+        @mutex.synchronize { @tools }
+      rescue MCPClient::Errors::TransportError
+        # Re-raise TransportError directly
+        raise
+      rescue JSON::ParserError => e
+        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+      rescue StandardError => e
+        raise MCPClient::Errors::ToolCallError, "Error listing tools: #{e.message}"
+      end
+    end
+
+    # Call a tool with the given parameters
+    # @param tool_name [String] the name of the tool to call
+    # @param parameters [Hash] the parameters to pass to the tool
+    # @return [Object] the result of the tool invocation
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+    # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
+    def call_tool(tool_name, parameters)
+      connect
+
+      begin
+        request_id = @mutex.synchronize { @request_id += 1 }
+
+        json_rpc_request = {
+          jsonrpc: '2.0',
+          id: request_id,
+          method: 'tools/call',
+          params: {
+            name: tool_name,
+            arguments: parameters
+          }
+        }
+
+        send_jsonrpc_request(json_rpc_request)
+      rescue MCPClient::Errors::TransportError
+        # Re-raise TransportError directly
+        raise
+      rescue JSON::ParserError => e
+        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+      rescue StandardError => e
+        raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
+      end
+    end
+
+    # Connect to the MCP server over HTTP/HTTPS with SSE
+    # @return [Boolean] true if connection was successful
+    # @raise [MCPClient::Errors::ConnectionError] if connection fails
+    def connect
+      @mutex.synchronize do
+        return true if @connection_established
+
+        uri = URI.parse(@base_url)
+        @http_client = Net::HTTP.new(uri.host, uri.port)
+
+        if uri.scheme == 'https'
+          @http_client.use_ssl = true
+          @http_client.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        end
+
+        @http_client.open_timeout = 10
+        @http_client.read_timeout = @read_timeout
+        @http_client.keep_alive_timeout = 60
+
+        @http_client.start
+        start_sse_thread
+
+        timeout = 10
+        success = @connection_cv.wait(timeout) { @connection_established }
+
+        unless success
+          cleanup
+          raise MCPClient::Errors::ConnectionError, 'Timed out waiting for SSE connection to be established'
+        end
+
+        @connection_established
+      end
+    rescue StandardError => e
+      cleanup
+      raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server at #{@base_url}: #{e.message}"
+    end
+
+    # Clean up the server connection
+    # Properly closes HTTP connections and clears cached tools
+    def cleanup
+      @mutex.synchronize do
+        begin
+          @sse_thread&.kill
+        rescue StandardError
+          nil
+        end
+        @sse_thread = nil
+
+        if @http_client
+          @http_client.finish if @http_client.started?
+          @http_client = nil
+        end
+
+        @tools = nil
+        @session_id = nil
+        @connection_established = false
+        @sse_connected = false
+      end
+    end
+
+    private
+
+    # Start the SSE thread to listen for events
+    def start_sse_thread
+      return if @sse_thread&.alive?
+
+      @sse_thread = Thread.new do
+        sse_http = nil
+        begin
+          uri = URI.parse(@base_url)
+          sse_http = Net::HTTP.new(uri.host, uri.port)
+
+          if uri.scheme == 'https'
+            sse_http.use_ssl = true
+            sse_http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          end
+
+          sse_http.open_timeout = 10
+          sse_http.read_timeout = @read_timeout
+          sse_http.keep_alive_timeout = 60
+
+          sse_http.start do |http|
+            request = Net::HTTP::Get.new(uri)
+            @headers.each { |k, v| request[k] = v }
+
+            http.request(request) do |response|
+              unless response.is_a?(Net::HTTPSuccess) && response['content-type']&.start_with?('text/event-stream')
+                @mutex.synchronize do
+                  @connection_established = false
+                  @connection_cv.broadcast
+                end
+                raise MCPClient::Errors::ServerError, 'Server response not OK or not text/event-stream'
+              end
+
+              @mutex.synchronize do
+                @sse_connected = true
+              end
+
+              response.read_body do |chunk|
+                process_sse_chunk(chunk.dup)
+              end
+            end
+          end
+        rescue StandardError
+          nil
+        ensure
+          sse_http&.finish if sse_http&.started?
+          @mutex.synchronize do
+            @sse_connected = false
+          end
+        end
+      end
+    end
+
+    # Process an SSE chunk from the server
+    # @param chunk [String] the chunk to process
+    def process_sse_chunk(chunk)
+      local_buffer = nil
+
+      @mutex.synchronize do
+        @buffer += chunk
+
+        while (event_end = @buffer.index("\n\n"))
+          event_data = @buffer.slice!(0, event_end + 2)
+          local_buffer = event_data
+        end
+      end
+
+      parse_and_handle_sse_event(local_buffer) if local_buffer
+    end
+
+    # Parse and handle an SSE event
+    # @param event_data [String] the event data to parse
+    def parse_and_handle_sse_event(event_data)
+      event = parse_sse_event(event_data)
+      return if event.nil?
+
+      case event[:event]
+      when 'endpoint'
+        if event[:data].include?('sessionId=')
+          session_id = event[:data].split('sessionId=').last
+
+          @mutex.synchronize do
+            @session_id = session_id
+            @connection_established = true
+            @connection_cv.broadcast
+          end
+        end
+      when 'message'
+        begin
+          data = JSON.parse(event[:data])
+
+          @mutex.synchronize do
+            @tools_data = data['result']['tools'] if data['result'] && data['result']['tools']
+
+            if data['id']
+              if data['error']
+                @sse_results[data['id']] = {
+                  'isError' => true,
+                  'content' => [{ 'type' => 'text', 'text' => data['error'].to_json }]
+                }
+              elsif data['result']
+                @sse_results[data['id']] = data['result']
+              end
+            end
+          end
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+
+    # Parse an SSE event
+    # @param event_data [String] the event data to parse
+    # @return [Hash, nil] the parsed event, or nil if the event is invalid
+    def parse_sse_event(event_data)
+      event = { event: 'message', data: '', id: nil }
+      data_lines = []
+
+      event_data.each_line do |line|
+        line = line.chomp
+        next if line.empty?
+
+        if line.start_with?('event:')
+          event[:event] = line[6..].strip
+        elsif line.start_with?('data:')
+          data_lines << line[5..].strip
+        elsif line.start_with?('id:')
+          event[:id] = line[3..].strip
+        end
+      end
+
+      event[:data] = data_lines.join("\n")
+      event[:data].empty? ? nil : event
+    end
+
+    # Request the tools list using JSON-RPC
+    # @return [Array<Hash>] the tools data
+    def request_tools_list
+      @mutex.synchronize do
+        return @tools_data if @tools_data
+      end
+
+      request_id = @mutex.synchronize { @request_id += 1 }
+
+      json_rpc_request = {
+        jsonrpc: '2.0',
+        id: request_id,
+        method: 'tools/list',
+        params: {}
+      }
+
+      result = send_jsonrpc_request(json_rpc_request)
+
+      if result && result['tools']
+        @mutex.synchronize do
+          @tools_data = result['tools']
+        end
+        return @mutex.synchronize { @tools_data.dup }
+      elsif result
+        @mutex.synchronize do
+          @tools_data = result
+        end
+        return @mutex.synchronize { @tools_data.dup }
+      end
+
+      raise MCPClient::Errors::ToolCallError, 'Failed to get tools list from JSON-RPC request'
+    end
+
+    # Send a JSON-RPC request to the server and wait for result
+    # @param request [Hash] the JSON-RPC request
+    # @return [Hash] the result of the request
+    def send_jsonrpc_request(request)
+      uri = URI.parse(@base_url)
+      rpc_http = Net::HTTP.new(uri.host, uri.port)
+
+      if uri.scheme == 'https'
+        rpc_http.use_ssl = true
+        rpc_http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      end
+
+      rpc_http.open_timeout = 10
+      rpc_http.read_timeout = @read_timeout
+      rpc_http.keep_alive_timeout = 60
+
+      begin
+        rpc_http.start do |http|
+          session_id = @mutex.synchronize { @session_id }
+
+          url = if session_id
+                  "#{@base_url.sub(%r{/sse/?$}, '')}/messages?sessionId=#{session_id}"
+                else
+                  "#{@base_url.sub(%r{/sse/?$}, '')}/messages"
+                end
+
+          uri = URI.parse(url)
+          http_request = Net::HTTP::Post.new(uri)
+          http_request.content_type = 'application/json'
+          http_request.body = request.to_json
+
+          headers = @mutex.synchronize { @headers.dup }
+          headers.except('Accept', 'Cache-Control')
+                 .each { |k, v| http_request[k] = v }
+
+          response = http.request(http_request)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise MCPClient::Errors::ServerError, "Server returned error: #{response.code} #{response.message}"
+          end
+
+          if response.code == '202'
+            request_id = request[:id]
+
+            start_time = Time.now
+            timeout = 10
+            result = nil
+
+            loop do
+              @mutex.synchronize do
+                if @sse_results[request_id]
+                  result = @sse_results[request_id]
+                  @sse_results.delete(request_id)
+                end
+              end
+
+              break if result || (Time.now - start_time > timeout)
+
+              sleep 0.1
+            end
+
+            return result if result
+
+            raise MCPClient::Errors::ToolCallError, "Timeout waiting for SSE result for request #{request_id}"
+
+          else
+            begin
+              data = JSON.parse(response.body)
+              return data['result']
+            rescue JSON::ParserError => e
+              raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+            end
+          end
+        end
+      ensure
+        rpc_http.finish if rpc_http.started?
+      end
+    end
+  end
+end

data/lib/mcp_client/server_stdio.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'json'
+require_relative 'version'
+
+module MCPClient
+  # JSON-RPC implementation of MCP server over stdio.
+  class ServerStdio < ServerBase
+    attr_reader :command
+
+    # Timeout in seconds for responses
+    READ_TIMEOUT = 15
+
+    # @param command [String, Array] the stdio command to launch the MCP JSON-RPC server
+    def initialize(command:)
+      super()
+      @command = command.is_a?(Array) ? command.join(' ') : command
+      @mutex = Mutex.new
+      @cond = ConditionVariable.new
+      @next_id = 1
+      @pending = {}
+      @initialized = false
+    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)
+      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
+    def start_reader
+      @reader_thread = Thread.new do
+        @stdout.each_line do |line|
+          handle_line(line)
+        end
+      rescue StandardError
+        # Reader thread aborted unexpectedly
+      end
+    end
+
+    # 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
+    def handle_line(line)
+      msg = JSON.parse(line)
+      id = msg['id']
+      return unless id
+
+      @mutex.synchronize do
+        @pending[id] = msg
+        @cond.broadcast
+      end
+    rescue JSON::ParserError
+      # Skip non-JSONRPC lines in the output stream
+    end
+
+    # List all tools available from the MCP server
+    # @return [Array<MCPClient::Tool>] list of available tools
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ToolCallError] for other errors during tool listing
+    def list_tools
+      ensure_initialized
+      req_id = next_id
+      # JSON-RPC method for listing tools
+      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'tools/list', 'params' => {} }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      (res.dig('result', 'tools') || []).map { |td| MCPClient::Tool.from_json(td) }
+    rescue StandardError => e
+      raise MCPClient::Errors::ToolCallError, "Error listing tools: #{e.message}"
+    end
+
+    # Call a tool with the given parameters
+    # @param tool_name [String] the name of the tool to call
+    # @param parameters [Hash] the parameters to pass to the tool
+    # @return [Object] the result of the tool invocation
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
+    def call_tool(tool_name, parameters)
+      ensure_initialized
+      req_id = next_id
+      # JSON-RPC method for calling a tool
+      req = {
+        'jsonrpc' => '2.0',
+        'id' => req_id,
+        'method' => 'tools/call',
+        'params' => { 'name' => tool_name, 'arguments' => parameters }
+      }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      res['result']
+    rescue StandardError => e
+      raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
+    end
+
+    # Clean up the server connection
+    # Closes all stdio handles and terminates any running processes and threads
+    def cleanup
+      return unless @stdin
+
+      @stdin.close unless @stdin.closed?
+      @stdout.close unless @stdout.closed?
+      @stderr.close unless @stderr.closed?
+      if @wait_thread&.alive?
+        Process.kill('TERM', @wait_thread.pid)
+        @wait_thread.join(1)
+      end
+      @reader_thread&.kill
+    rescue StandardError
+      # Clean up resources during unexpected termination
+    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)
+      @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
+  end
+end

data/lib/mcp_client/tool.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of an MCP tool
+  class Tool
+    attr_reader :name, :description, :schema
+
+    def initialize(name:, description:, schema:)
+      @name = name
+      @description = description
+      @schema = schema
+    end
+
+    # Create a Tool instance from JSON data
+    # @param data [Hash] JSON data from MCP server
+    # @return [MCPClient::Tool] tool instance
+    def self.from_json(data)
+      # Some servers (Playwright MCP CLI) use 'inputSchema' instead of 'schema'
+      schema = data['inputSchema'] || data['schema']
+      new(
+        name: data['name'],
+        description: data['description'],
+        schema: schema
+      )
+    end
+
+    # Convert tool to OpenAI function specification format
+    # @return [Hash] OpenAI function specification
+    def to_openai_tool
+      {
+        type: 'function',
+        function: {
+          name: @name,
+          description: @description,
+          parameters: @schema
+        }
+      }
+    end
+
+    # Convert tool to Anthropic Claude tool specification format
+    # @return [Hash] Anthropic Claude tool specification
+    def to_anthropic_tool
+      {
+        name: @name,
+        description: @description,
+        input_schema: @schema
+      }
+    end
+  end
+end

data/lib/mcp_client/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Current version of the MCP client gem
+  VERSION = '0.1.0'
+end

data/lib/mcp_client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Load all MCPClient components
+require_relative 'mcp_client/errors'
+require_relative 'mcp_client/tool'
+require_relative 'mcp_client/server_base'
+require_relative 'mcp_client/server_stdio'
+require_relative 'mcp_client/server_sse'
+require_relative 'mcp_client/server_factory'
+require_relative 'mcp_client/client'
+require_relative 'mcp_client/version'
+
+# Model Context Protocol (MCP) Client module
+# Provides a standardized way for agents to communicate with external tools and services
+# through a protocol-based approach
+module MCPClient
+  # Create a new MCPClient client
+  # @param mcp_server_configs [Array<Hash>] configurations for MCP servers
+  # @return [MCPClient::Client] new client instance
+  def self.create_client(mcp_server_configs: [])
+    MCPClient::Client.new(mcp_server_configs: mcp_server_configs)
+  end
+
+  # Create a standard server configuration for stdio
+  # @param command [String, Array<String>] command to execute
+  # @return [Hash] server configuration
+  def self.stdio_config(command:)
+    {
+      type: 'stdio',
+      command: command
+    }
+  end
+
+  # Create a standard server configuration for SSE
+  # @param base_url [String] base URL for the server
+  # @param headers [Hash] HTTP headers to include in requests
+  # @param read_timeout [Integer] read timeout in seconds (default: 30)
+  # @return [Hash] server configuration
+  def self.sse_config(base_url:, headers: {}, read_timeout: 30)
+    {
+      type: 'sse',
+      base_url: base_url,
+      headers: headers,
+      read_timeout: read_timeout
+    }
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: ruby-mcp-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Szymon Kurcab
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.62'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.62'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.34
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.34
+description: Ruby client library for integrating with Model Context Protocol (MCP)
+  servers to access and invoke tools from AI assistants
+email:
+- szymon.kurcab@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mcp_client.rb
+- lib/mcp_client/client.rb
+- lib/mcp_client/errors.rb
+- lib/mcp_client/server_base.rb
+- lib/mcp_client/server_factory.rb
+- lib/mcp_client/server_sse.rb
+- lib/mcp_client/server_stdio.rb
+- lib/mcp_client/tool.rb
+- lib/mcp_client/version.rb
+homepage: https://github.com/simonx1/ruby-mcp-client
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: A Ruby client for the Model Context Protocol (MCP)
+test_files: []