raix 0.8.6 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f28d49373248dcc8209a5c4c3678c632953aab2282f3f71a887ee1e2b3e7d249
-  data.tar.gz: bacd7d9ef9b7aff8ab6b998d1ddb2efe3fd3dfa5855d8d5851161a271b056963
+  metadata.gz: '0868c4163ea58511e3c0dfc66b2b22a5cb2dbb16a7575746b36cd70af4777137'
+  data.tar.gz: 4e396262603a787dc58817e9fbb536264f25cdb9462bcbe035d675e59cb179ad
 SHA512:
-  metadata.gz: a7a75b0c7c8f9ecfcbae002e6b5dfea7cee17be8d3d8825dacf2276f200f9bb542e0ccc4f7bb402b03b57d0240d84431bba3d749657a51ef4a90e937fd096633
-  data.tar.gz: b367bdd61f7c7fb269232387c0d31af1cb2315d9bed8abc16758931851dab4b849139cb23e1c2c4236f8e8ced55368726db8c2a308efa3b6db503290d07165c2
+  metadata.gz: 8ae8a80e0e45dfba22290aefe27c39fd914f9046228dac33af1bc631e55a9eff73e38500c12c9eec6ba7bff67a5a16d51438ccf80cbcf423b070125dcd5710c4
+  data.tar.gz: ffb45352168291e28041b787fa8c2bf61c032d5bd5c59fb5a5653a602d6b1bb5ef282475ce7d828722113df797369127a1a4cdeec5da1c53ad887f1665b0385a

data/.rubocop.yml

@@ -36,6 +36,9 @@ Metrics/PerceivedComplexity:
 Metrics/ParameterLists:
   Enabled: false
 
+Metrics/ClassLength:
+  Enabled: false
+
 Style/FrozenStringLiteralComment:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [0.9.1] - 2025-05-30
+### Added
+- **MCP Type Coercion** - Automatic type conversion for MCP tool arguments based on JSON schema
+  - Supports integer, number, boolean, array, and object types
+  - Handles nested objects and arrays of objects with proper coercion
+  - Gracefully handles invalid JSON and type mismatches
+- **MCP Image Support** - MCP tools can now return image content as structured JSON
+
+### Fixed
+- Fixed handling of nil values in MCP argument coercion
+
+## [0.9.0] - 2025-05-30
+### Added
+- **MCP (Model Context Protocol) Support**
+  - New `stdio_mcp` method for stdio-based MCP servers
+  - Refactored existing MCP code into `SseClient` and `StdioClient`
+  - Split top-level `mcp` method into `sse_mcp` and `stdio_mcp`
+  - Added authentication support for MCP servers
+- **Class-Level Configuration**
+  - Moved configuration to separate `Configuration` class
+  - Added fallback mechanism for configuration options
+  - Cleaner metaprogramming implementation
+
+### Fixed
+- Fixed method signature of functions added via MCP
+
 ## [0.8.6] - 2025-05-19
 - add `required` and `optional` flags for parameters in `function` declarations
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    raix (0.8.6)
+    raix (0.9.1)
       activesupport (>= 6.0)
       faraday-retry (~> 2.0)
       open_router (~> 0.2)

data/README.md

@@ -703,6 +703,21 @@ You can add an initializer to your application's `config/initializers` directory
 
 You will also need to configure the OpenRouter API access token as per the instructions here: https://github.com/OlympiaAI/open_router?tab=readme-ov-file#quickstart
 
+### Global vs class level configuration
+
+You can either configure Raix globally or at the class level. The global configuration is set in the initializer as shown above. You can however also override all configuration options of the `Configuration` class on the class level with the
+same syntax:
+
+```ruby
+class MyClass
+  include Raix::ChatCompletion
+
+  configure do |config|
+    config.openrouter_client = OpenRouter::Client.new # with my special options
+  end
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/mcp/sse_client.rb

@@ -0,0 +1,297 @@
+require_relative "tool"
+require "json"
+require "securerandom"
+require "faraday"
+require "uri"
+
+module Raix
+  module MCP
+    # Client for communicating with MCP servers via Server-Sent Events (SSE).
+    class SseClient
+      PROTOCOL_VERSION = "2024-11-05".freeze
+      CONNECTION_TIMEOUT = 10
+      OPEN_TIMEOUT = 30
+
+      # Creates a new client and establishes SSE connection to discover the JSON-RPC endpoint.
+      #
+      # @param url [String] the SSE endpoint URL
+      def initialize(url, headers: {})
+        @url = url
+        @endpoint_url = nil
+        @sse_thread = nil
+        @event_queue = Thread::Queue.new
+        @buffer = ""
+        @closed = false
+        @headers = headers
+
+        # Start the SSE connection and discover endpoint
+        establish_sse_connection
+      end
+
+      # Returns available tools from the server.
+      def tools
+        @tools ||= begin
+          request_id = SecureRandom.uuid
+          send_json_rpc(request_id, "tools/list", {})
+
+          # Wait for response through SSE
+          response = wait_for_response(request_id)
+          response[:tools].map do |tool_json|
+            Tool.from_json(tool_json)
+          end
+        end
+      end
+
+      # Executes a tool with given arguments.
+      # Returns text content directly, or JSON-encoded data for other content types.
+      def call_tool(name, **arguments)
+        request_id = SecureRandom.uuid
+        send_json_rpc(request_id, "tools/call", name:, arguments:)
+
+        # Wait for response through SSE
+        response = wait_for_response(request_id)
+        content = response[:content]
+        return "" if content.nil? || content.empty?
+
+        # Handle different content formats
+        first_item = content.first
+        case first_item
+        when Hash
+          case first_item[:type]
+          when "text"
+            first_item[:text]
+          when "image"
+            # Return a structured response for images
+            {
+              type: "image",
+              data: first_item[:data],
+              mime_type: first_item[:mimeType] || "image/png"
+            }.to_json
+          else
+            # For any other type, return the item as JSON
+            first_item.to_json
+          end
+        else
+          first_item.to_s
+        end
+      end
+
+      # Closes the connection to the server.
+      def close
+        @closed = true
+        @sse_thread&.kill
+        @connection&.close
+      end
+
+      def unique_key
+        @url.parameterize.underscore.gsub("https_", "")
+      end
+
+      private
+
+      # Establishes and maintains the SSE connection
+      def establish_sse_connection
+        @sse_thread = Thread.new do
+          headers = {
+            "Accept" => "text/event-stream",
+            "Cache-Control" => "no-cache",
+            "Connection" => "keep-alive",
+            "MCP-Version" => PROTOCOL_VERSION
+          }.merge(@headers)
+
+          @connection = Faraday.new(url: @url) do |faraday|
+            faraday.options.timeout = CONNECTION_TIMEOUT
+            faraday.options.open_timeout = OPEN_TIMEOUT
+          end
+
+          @connection.get do |req|
+            req.headers = headers
+            req.options.on_data = proc do |chunk, _size|
+              next if @closed
+
+              @buffer << chunk
+              process_sse_buffer
+            end
+          end
+        rescue StandardError => e
+          # puts "[MCP DEBUG] SSE connection error: #{e.message}"
+          @event_queue << { error: e }
+        end
+
+        # Wait for endpoint discovery
+        loop do
+          event = @event_queue.pop
+          if event[:error]
+            raise ProtocolError, "SSE connection failed: #{event[:error].message}"
+          elsif event[:endpoint_url]
+            @endpoint_url = event[:endpoint_url]
+            break
+          end
+        end
+
+        # Initialize the MCP session
+        initialize_mcp_session
+      end
+
+      # Process SSE buffer for complete events
+      def process_sse_buffer
+        while (idx = @buffer.index("\n\n"))
+          event_text = @buffer.slice!(0..idx + 1)
+          event_type, event_data = parse_sse_fields(event_text)
+
+          case event_type
+          when "endpoint"
+            endpoint_url = build_absolute_url(@url, event_data)
+            @event_queue << { endpoint_url: }
+          when "message"
+            handle_message_event(event_data)
+          end
+        end
+      end
+
+      # Handle SSE message events
+      def handle_message_event(event_data)
+        parsed = JSON.parse(event_data, symbolize_names: true)
+
+        # Handle different message types
+        case parsed
+        when ->(p) { p[:method] == "initialize" && p.dig(:params, :endpoint_url) }
+          # Legacy endpoint discovery
+          endpoint_url = parsed.dig(:params, :endpoint_url)
+          @event_queue << { endpoint_url: }
+        when ->(p) { p[:id] && p[:result] }
+          @event_queue << { id: parsed[:id], result: parsed[:result] }
+        when ->(p) { p[:result] }
+          @event_queue << { result: parsed[:result] }
+        end
+      rescue JSON::ParserError => e
+        puts "[MCP DEBUG] Error parsing message: #{e.message}"
+        puts "[MCP DEBUG] Message data: #{event_data}"
+      end
+
+      # Initialize the MCP session
+      def initialize_mcp_session
+        request_id = SecureRandom.uuid
+        send_json_rpc(request_id, "initialize", {
+                        protocolVersion: PROTOCOL_VERSION,
+                        capabilities: {
+                          roots: { listChanged: true },
+                          sampling: {}
+                        },
+                        clientInfo: {
+                          name: "Raix",
+                          version: Raix::VERSION
+                        }
+                      })
+
+        # Wait for initialization response
+        response = wait_for_response(request_id)
+
+        # Send acknowledgment if needed
+        return unless response.dig(:capabilities, :tools, :listChanged)
+
+        send_notification("notifications/initialized", {})
+      end
+
+      # Send a JSON-RPC request
+      def send_json_rpc(id, method, params)
+        body = {
+          jsonrpc: JSONRPC_VERSION,
+          id:,
+          method:,
+          params:
+        }
+
+        # Use a new connection for the POST request
+        conn = Faraday.new(url: @endpoint_url) do |faraday|
+          faraday.options.timeout = CONNECTION_TIMEOUT
+        end
+
+        conn.post do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = body.to_json
+        end
+      rescue StandardError => e
+        raise ProtocolError, "Failed to send request: #{e.message}"
+      end
+
+      # Send a notification (no response expected)
+      def send_notification(method, params)
+        body = {
+          jsonrpc: JSONRPC_VERSION,
+          method:,
+          params:
+        }
+
+        conn = Faraday.new(url: @endpoint_url) do |faraday|
+          faraday.options.timeout = CONNECTION_TIMEOUT
+        end
+
+        conn.post do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = body.to_json
+        end
+      rescue StandardError => e
+        puts "[MCP DEBUG] Error sending notification: #{e.message}"
+      end
+
+      # Wait for a response with a specific ID
+      def wait_for_response(request_id)
+        timeout = Time.now + CONNECTION_TIMEOUT
+
+        loop do
+          if Time.now > timeout
+            raise ProtocolError, "Timeout waiting for response"
+          end
+
+          # Use non-blocking pop with timeout
+          begin
+            event = @event_queue.pop(true) # non_block = true
+          rescue ThreadError
+            # Queue is empty, wait a bit
+            sleep 0.1
+            next
+          end
+
+          if event[:error]
+            raise ProtocolError, "SSE error: #{event[:error].message}"
+          elsif event[:id] == request_id && event[:result]
+            return event[:result]
+          elsif event[:result] && !event[:id]
+            return event[:result]
+          else
+            @event_queue << event
+            sleep 0.01
+          end
+        end
+      end
+
+      # Parses SSE event fields from raw text.
+      def parse_sse_fields(event_text)
+        event_type = "message"
+        data_lines = []
+
+        event_text.each_line do |line|
+          case line
+          when /^event:\s*(.+)$/
+            event_type = Regexp.last_match(1).strip
+          when /^data:\s*(.*)$/
+            data_lines << Regexp.last_match(1)
+          end
+        end
+
+        [event_type, data_lines.join("\n").strip]
+      end
+
+      # Builds an absolute URL for candidate relative to base.
+      def build_absolute_url(base, candidate)
+        uri = URI.parse(candidate)
+        return candidate if uri.absolute?
+
+        URI.join(base, candidate).to_s
+      rescue URI::InvalidURIError
+        candidate
+      end
+    end
+  end
+end

data/lib/mcp/stdio_client.rb

@@ -0,0 +1,78 @@
+require_relative "tool"
+require "json"
+require "securerandom"
+
+module Raix
+  module MCP
+    # Client for communicating with MCP servers via stdio using JSON-RPC.
+    class StdioClient
+      # Creates a new client with a bidirectional pipe to the MCP server.
+      def initialize(*args, env)
+        @args = args
+        @io = IO.popen(env, args, "w+")
+      end
+
+      # Returns available tools from the server.
+      def tools
+        result = call("tools/list")
+
+        result["tools"].map do |tool_json|
+          Tool.from_json(tool_json)
+        end
+      end
+
+      # Executes a tool with given arguments.
+      # Returns text content directly, or JSON-encoded data for other content types.
+      def call_tool(name, **arguments)
+        result = call("tools/call", name:, arguments:)
+        content = result["content"]
+        return "" if content.nil? || content.empty?
+
+        # Handle different content formats
+        first_item = content.first
+        case first_item
+        when Hash
+          case first_item["type"]
+          when "text"
+            first_item["text"]
+          when "image"
+            # Return a structured response for images
+            {
+              type: "image",
+              data: first_item["data"],
+              mime_type: first_item["mimeType"] || "image/png"
+            }.to_json
+          else
+            # For any other type, return the item as JSON
+            first_item.to_json
+          end
+        else
+          first_item.to_s
+        end
+      end
+
+      # Closes the connection to the server.
+      def close
+        @io.close
+      end
+
+      def unique_key
+        @args.join(" ").parameterize.underscore
+      end
+
+      private
+
+      # Sends JSON-RPC request and returns the result.
+      def call(method, **params)
+        @io.puts({ id: SecureRandom.uuid, method:, params:, jsonrpc: JSONRPC_VERSION }.to_json)
+        @io.flush # Ensure data is immediately sent
+        message = JSON.parse(@io.gets)
+        if (error = message["error"])
+          raise ProtocolError, error["message"]
+        end
+
+        message["result"]
+      end
+    end
+  end
+end

data/lib/mcp/tool.rb

@@ -0,0 +1,67 @@
+module Raix
+  module MCP
+    # Represents an MCP (Model Context Protocol) tool with metadata and schema
+    #
+    # @example
+    #   tool = Tool.new(
+    #     name: "weather",
+    #     description: "Get weather info",
+    #     input_schema: { "type" => "object", "properties" => { "city" => { "type" => "string" } } }
+    #   )
+    class Tool
+      attr_reader :name, :description, :input_schema
+
+      # Initialize a new Tool
+      #
+      # @param name [String] the tool name
+      # @param description [String] human-readable description of what the tool does
+      # @param input_schema [Hash] JSON schema defining the tool's input parameters
+      def initialize(name:, description:, input_schema: {})
+        @name = name
+        @description = description
+        @input_schema = input_schema
+      end
+
+      # Initialize from raw MCP JSON response
+      #
+      # @param json [Hash] parsed JSON data from MCP response
+      # @return [Tool] new Tool instance
+      def self.from_json(json)
+        new(
+          name: json[:name] || json["name"],
+          description: json[:description] || json["description"],
+          input_schema: json[:inputSchema] || json["inputSchema"] || {}
+        )
+      end
+
+      # Get the input schema type
+      #
+      # @return [String, nil] the schema type (e.g., "object")
+      def input_type
+        input_schema["type"]
+      end
+
+      # Get the properties hash
+      #
+      # @return [Hash] schema properties definition
+      def properties
+        input_schema["properties"] || {}
+      end
+
+      # Get required properties array
+      #
+      # @return [Array<String>] list of required property names
+      def required_properties
+        input_schema["required"] || []
+      end
+
+      # Check if a property is required
+      #
+      # @param property_name [String] name of the property to check
+      # @return [Boolean] true if the property is required
+      def required?(property_name)
+        required_properties.include?(property_name)
+      end
+    end
+  end
+end

data/lib/raix/chat_completion.rb

@@ -38,6 +38,23 @@ module Raix
                   :prediction, :repetition_penalty, :response_format, :stream, :temperature, :max_completion_tokens,
                   :max_tokens, :seed, :stop, :top_a, :top_k, :top_logprobs, :top_p, :tools, :available_tools, :tool_choice, :provider
 
+    class_methods do
+      # Returns the current configuration of this class. Falls back to global configuration for unset values.
+      def configuration
+        @configuration ||= Configuration.new(fallback: Raix.configuration)
+      end
+
+      # Let's you configure the class-level configuration using a block.
+      def configure
+        yield(configuration)
+      end
+    end
+
+    # Instance level access to the class-level configuration.
+    def configuration
+      self.class.configuration
+    end
+
     # This method performs chat completion based on the provided transcript and parameters.
     #
     # @param params [Hash] The parameters for chat completion.
@@ -54,8 +71,8 @@ module Raix
       params[:frequency_penalty] ||= frequency_penalty.presence
       params[:logit_bias] ||= logit_bias.presence
       params[:logprobs] ||= logprobs.presence
-      params[:max_completion_tokens] ||= max_completion_tokens.presence || Raix.configuration.max_completion_tokens
-      params[:max_tokens] ||= max_tokens.presence || Raix.configuration.max_tokens
+      params[:max_completion_tokens] ||= max_completion_tokens.presence || configuration.max_completion_tokens
+      params[:max_tokens] ||= max_tokens.presence || configuration.max_tokens
       params[:min_p] ||= min_p.presence
       params[:prediction] = { type: "content", content: params[:prediction] || prediction } if params[:prediction] || prediction.present?
       params[:presence_penalty] ||= presence_penalty.presence
@@ -64,7 +81,7 @@ module Raix
       params[:response_format] ||= response_format.presence
       params[:seed] ||= seed.presence
       params[:stop] ||= stop.presence
-      params[:temperature] ||= temperature.presence || Raix.configuration.temperature
+      params[:temperature] ||= temperature.presence || configuration.temperature
       params[:tool_choice] ||= tool_choice.presence
       params[:tools] = if available_tools == false
                          nil
@@ -95,7 +112,7 @@ module Raix
       self.loop = loop
 
       # set the model to the default if not provided
-      self.model ||= Raix.configuration.model
+      self.model ||= configuration.model
 
       adapter = MessageAdapters::Base.new(self)
 
@@ -227,7 +244,7 @@ module Raix
 
       params.delete(:temperature) if model.start_with?("o")
 
-      Raix.configuration.openai_client.chat(parameters: params.compact.merge(model:, messages:))
+      configuration.openai_client.chat(parameters: params.compact.merge(model:, messages:))
     end
 
     def openrouter_request(params:, model:, messages:)
@@ -237,7 +254,7 @@ module Raix
       retry_count = 0
 
       begin
-        Raix.configuration.openrouter_client.complete(messages, model:, extras: params.compact, stream:)
+        configuration.openrouter_client.complete(messages, model:, extras: params.compact, stream:)
       rescue OpenRouter::ServerError => e
         if e.message.include?("retry")
           puts "Retrying OpenRouter request... (#{retry_count} attempts) #{e.message}"

data/lib/raix/configuration.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Raix
+  # The Configuration class holds the configuration options for the Raix gem.
+  class Configuration
+    def self.attr_accessor_with_fallback(method_name)
+      define_method(method_name) do
+        value = instance_variable_get("@#{method_name}")
+        return value if value
+        return unless fallback
+
+        fallback.public_send(method_name)
+      end
+      define_method("#{method_name}=") do |value|
+        instance_variable_set("@#{method_name}", value)
+      end
+    end
+
+    # The temperature option determines the randomness of the generated text.
+    # Higher values result in more random output.
+    attr_accessor_with_fallback :temperature
+
+    # The max_tokens option determines the maximum number of tokens to generate.
+    attr_accessor_with_fallback :max_tokens
+
+    # The max_completion_tokens option determines the maximum number of tokens to generate.
+    attr_accessor_with_fallback :max_completion_tokens
+
+    # The model option determines the model to use for text generation. This option
+    # is normally set in each class that includes the ChatCompletion module.
+    attr_accessor_with_fallback :model
+
+    # The openrouter_client option determines the default client to use for communication.
+    attr_accessor_with_fallback :openrouter_client
+
+    # The openai_client option determines the OpenAI client to use for communication.
+    attr_accessor_with_fallback :openai_client
+
+    DEFAULT_MAX_TOKENS = 1000
+    DEFAULT_MAX_COMPLETION_TOKENS = 16_384
+    DEFAULT_MODEL = "meta-llama/llama-3-8b-instruct:free"
+    DEFAULT_TEMPERATURE = 0.0
+
+    # Initializes a new instance of the Configuration class with default values.
+    def initialize(fallback: nil)
+      self.temperature = DEFAULT_TEMPERATURE
+      self.max_completion_tokens = DEFAULT_MAX_COMPLETION_TOKENS
+      self.max_tokens = DEFAULT_MAX_TOKENS
+      self.model = DEFAULT_MODEL
+      self.fallback = fallback
+    end
+
+    private
+
+    attr_accessor :fallback
+
+    def get_with_fallback(method)
+      value = instance_variable_get("@#{method}")
+      return value if value
+      return unless fallback
+
+      fallback.public_send(method)
+    end
+  end
+end

data/lib/raix/mcp.rb

@@ -14,9 +14,10 @@
 require "active_support/concern"
 require "active_support/inflector"
 require "securerandom"
-require "faraday"
 require "uri"
-require "json"
+
+require_relative "../mcp/sse_client"
+require_relative "../mcp/stdio_client"
 
 module Raix
   # Model Context Protocol integration for Raix
@@ -28,15 +29,38 @@ module Raix
   module MCP
     extend ActiveSupport::Concern
 
+    # Error raised when there's a protocol-level error in MCP communication
+    class ProtocolError < StandardError; end
+
     JSONRPC_VERSION = "2.0".freeze
-    PROTOCOL_VERSION = "2024-11-05".freeze # Current supported protocol version
-    CONNECTION_TIMEOUT = 10
-    OPEN_TIMEOUT = 30
 
     class_methods do
-      # Declare an MCP server by URL.
+      # Declare an MCP server by URL, using the SSE transport.
       #
-      #   mcp "https://server.example.com/sse"
+      #   sse_mcp "https://server.example.com/sse",
+      #           headers: { "Authorization" => "Bearer <token>" },
+      #           only: [:get_issue]
+      #
+      def sse_mcp(url, headers: {}, only: nil, except: nil)
+        mcp(only:, except:, client: MCP::SseClient.new(url, headers:))
+      end
+
+      # Declare an MCP server by command line arguments, and environment variables  ,
+      # using the stdio transport.
+      #
+      #   stdio_mcp "docker", "run", "-i", "--rm",
+      #             "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
+      #             "ghcr.io/github/github-mcp-server",
+      #             env: { GITHUB_PERSONAL_ACCESS_TOKEN: "${input:github_token}" },
+      #             only: [:github_search]
+      #
+      def stdio_mcp(*args, env: {}, only: nil, except: nil)
+        mcp(only:, except:, client: MCP::StdioClient.new(*args, env))
+      end
+
+      # Declare an MCP server, using the given client.
+      #
+      #   mcp client: MCP::SseClient.new("https://server.example.com/sse")
       #
       # This will automatically:
       #   • query `tools/list` on the server
@@ -46,72 +70,65 @@ module Raix
       #     call to the server and appends the proper messages to the
       #     transcript.
       # NOTE TO SELF: NEVER MOCK SERVER RESPONSES! THIS MUST WORK WITH REAL SERVERS!
-      def mcp(url, only: nil, except: nil)
+      def mcp(client:, only: nil, except: nil)
         @mcp_servers ||= {}
 
-        return if @mcp_servers.key?(url) # avoid duplicate definitions
+        return if @mcp_servers.key?(client.unique_key) # avoid duplicate definitions
 
-        # Connect and initialize the SSE endpoint
-
-        result = Thread::Queue.new
-        Thread.new do
-          establish_sse_connection(url, result:)
-        end
-        tools = result.pop
+        # Fetch tools
+        tools = client.tools
 
         if tools.empty?
-          puts "[MCP DEBUG] No tools found from MCP server at #{url}"
+          # puts "[MCP DEBUG] No tools found from MCP server at #{url}"
+          client.close
           return nil
         end
 
-        # 3. Register each tool so ChatCompletion#tools picks them up
         # Apply filters
         filtered_tools = if only.present?
                            only_symbols = Array(only).map(&:to_sym)
-                           tools.select { |tool| only_symbols.include?(tool["name"].to_sym) }
+                           tools.select { |tool| only_symbols.include?(tool.name.to_sym) }
                          elsif except.present?
                            except_symbols = Array(except).map(&:to_sym)
-                           tools.reject { |tool| except_symbols.include?(tool["name"].to_sym) }
+                           tools.reject { |tool| except_symbols.include?(tool.name.to_sym) }
                          else
                            tools
                          end
 
         # Ensure FunctionDispatch is included in the class
-        # Explicit include in the class context
         include FunctionDispatch unless included_modules.include?(FunctionDispatch)
-        puts "[MCP DEBUG] FunctionDispatch included in #{name}"
+        # puts "[MCP DEBUG] FunctionDispatch included in #{name}"
 
         filtered_tools.each do |tool|
-          remote_name = tool[:name]
+          remote_name = tool.name
           # TODO: Revisit later whether this much context is needed in the function name
-          local_name = "#{url.parameterize.underscore}_#{remote_name}".gsub("https_", "").to_sym
+          local_name = "#{client.unique_key}_#{remote_name}".to_sym
 
-          description  = tool["description"]
-          input_schema = tool["inputSchema"] || {}
+          description = tool.description
+          input_schema = tool.input_schema || {}
 
           # --- register with FunctionDispatch (adds to .functions)
           function(local_name, description, **{}) # placeholder parameters replaced next
           latest_definition = functions.last
-          latest_definition[:parameters] = input_schema.deep_symbolize_keys if input_schema.present?
+          latest_definition[:parameters] = input_schema.deep_symbolize_keys || {}
+
+          # Required by OpenAI
+          latest_definition[:parameters][:properties] ||= {}
+
+          # Store the schema for type coercion
+          tool_schemas = @tool_schemas ||= {}
+          tool_schemas[local_name] = input_schema
 
           # --- define an instance method that proxies to the server
-          define_method(local_name) do |**arguments|
+          define_method(local_name) do |arguments, _cache|
             arguments ||= {}
 
-            call_id = SecureRandom.uuid
-            result = Thread::Queue.new
-            Thread.new do
-              self.class.establish_sse_connection(url, name: remote_name, arguments:, result:)
-            end
-
-            content_item = result.pop
+            # Coerce argument types based on the input schema
+            stored_schema = self.class.instance_variable_get(:@tool_schemas)&.dig(local_name)
+            coerced_arguments = coerce_arguments(arguments, stored_schema)
 
-            # Decide what to add to the transcript
-            content_text = if content_item.is_a?(Hash) && content_item["type"] == "text"
-                             content_item["text"]
-                           else
-                             content_item.to_json
-                           end
+            content_text = client.call_tool(remote_name, **coerced_arguments)
+            call_id = SecureRandom.uuid
 
             # Mirror FunctionDispatch transcript behaviour
             transcript << [
@@ -144,193 +161,95 @@ module Raix
           end
         end
 
-        # Store the URL and tools for future use
-        @mcp_servers[url] = { tools: }
+        # Store the URL, tools, and client for future use
+        @mcp_servers[client.unique_key] = { tools: filtered_tools, client: }
       end
+    end
 
-      # Establishes an SSE connection to +url+ and returns the JSON‑RPC POST endpoint
-      # advertised by the server.  The MCP specification allows two different event
-      # formats during initialization:
-      #
-      # 1. A generic JSON‑RPC *initialize* event (the behaviour previously
-      #    implemented):
-      #
-      #        event: message    (implicit when no explicit event type is given)
-      #        data: {"jsonrpc":"2.0","method":"initialize","params":{"endpoint_url":"https://…/rpc"}}
-      #
-      # 2. A dedicated *endpoint* event, as implemented by the reference
-      #    TypeScript SDK and the public GitMCP server used in our test-suite:
-      #
-      #        event: endpoint\n
-      #        data: /rpc\n
-      #
-      # This method now supports **both** formats.
-      #
-      # It uses Net::HTTP directly rather than Faraday streaming because the latter
-      # does not consistently surface partial body reads across adapters.  The
-      # implementation reads the response body incrementally, splitting on the
-      # SSE record delimiter (double newline) and processing each event until an
-      # endpoint is discovered (or a timeout / connection error occurs).
-      def establish_sse_connection(url, name: nil, arguments: {}, result: nil)
-        puts "[MCP DEBUG] Establishing MCP connection with URL: #{url}"
-
-        headers = {
-          "Accept" => "text/event-stream",
-          "Cache-Control" => "no-cache",
-          "Connection" => "keep-alive",
-          "MCP-Version" => PROTOCOL_VERSION
-        }
-
-        endpoint_url = nil
-        buffer = ""
-
-        connection = Faraday.new(url:) do |faraday|
-          faraday.options.timeout = CONNECTION_TIMEOUT
-          faraday.options.open_timeout = OPEN_TIMEOUT
-        end
+    private
 
-        connection.get do |req|
-          req.headers = headers
-          req.options.on_data = proc do |chunk, _size|
-            buffer << chunk
-
-            # Process complete SSE events (separated by a blank line)
-            while (idx = buffer.index("\n\n"))
-              event_text = buffer.slice!(0..idx + 1) # include delimiter
-              event_type, event_data = parse_sse_fields(event_text)
-
-              case event_type
-              when "endpoint"
-                # event data is expected to be a plain string with the endpoint
-                puts "[MCP DEBUG] Found endpoint event: #{event_data}"
-                endpoint_url = build_absolute_url(url, event_data)
-                initialize_mcp_connection(connection, endpoint_url)
-              when "message"
-                puts "[MCP DEBUG] Received message: #{event_data}"
-                dispatch_event(event_data, connection, endpoint_url, name, arguments, result)
-              else
-                puts "[MCP DEBUG] Unexpected event type: #{event_type} with data: #{event_data}"
-              end
-            end
-          end
-        end
-      end
+    # Coerce argument types based on the JSON schema
+    def coerce_arguments(arguments, schema)
+      return arguments unless schema.is_a?(Hash) && schema["properties"].is_a?(Hash)
 
-      # Parses an SSE *event block* (text up to the blank line delimiter) and
-      # returns `[event_type, data]` where *event_type* defaults to "message" when
-      # no explicit `event:` field is present.  The *data* combines all `data:`
-      # lines separated by newlines, as per the SSE specification.
-      def parse_sse_fields(event_text)
-        event_type = "message"
-        data_lines = []
-
-        event_text.each_line do |line|
-          case line
-          when /^event:\s*(.+)$/
-            event_type = Regexp.last_match(1).strip
-          when /^data:\s*(.*)$/
-            data_lines << Regexp.last_match(1)
-          end
-        end
+      coerced = {}
+      schema["properties"].each do |key, prop_schema|
+        value = if arguments.key?(key)
+                  arguments[key]
+                elsif arguments.key?(key.to_sym)
+                  arguments[key.to_sym]
+                end
+        next if value.nil?
 
-        [event_type, data_lines.join("\n").strip]
+        coerced[key] = coerce_value(value, prop_schema)
       end
 
-      # Builds an absolute URL for +candidate+ relative to +base+.
-      # If +candidate+ is already absolute, it is returned unchanged.
-      def build_absolute_url(base, candidate)
-        uri = URI.parse(candidate)
-        return candidate if uri.absolute?
-
-        URI.join(base, candidate).to_s
-      rescue URI::InvalidURIError
-        candidate # fall back to original string
+      # Include any additional arguments not in the schema
+      arguments.each do |key, value|
+        key_str = key.to_s
+        coerced[key_str] = value unless coerced.key?(key_str)
       end
 
-      def initialize_mcp_connection(connection, endpoint_url)
-        puts "[MCP DEBUG] Initializing MCP connection with URL: #{endpoint_url}"
-        connection.post(endpoint_url) do |req|
-          req.headers["Content-Type"] = "application/json"
-          req.body = {
-            jsonrpc: JSONRPC_VERSION,
-            id: SecureRandom.uuid,
-            method: "initialize",
-            params: {
-              protocolVersion: PROTOCOL_VERSION,
-              capabilities: {
-                roots: {
-                  listChanged: true
-                },
-                sampling: {}
-              },
-              clientInfo: {
-                name: "Raix",
-                version: Raix::VERSION
-              }
-            }
-          }.to_json
-        end
-      end
+      coerced.with_indifferent_access
+    end
 
-      def dispatch_event(event_data, connection, endpoint_url, name, arguments, result)
-        event_data = JSON.parse(event_data, symbolize_names: true)
-        case event_data
-        in { result: { capabilities: { tools: { listChanged: true } } } }
-          puts "[MCP DEBUG] Received listChanged event"
-          acknowledge_event(connection, endpoint_url)
-          fetch_mcp_tools(connection, endpoint_url)
-        in { result: { tools: } }
-          puts "[MCP DEBUG] Received tools event: #{tools}"
-          if name.present?
-            puts "[MCP DEBUG] Calling function: #{name} with params: #{arguments.inspect}"
-            remote_dispatch(connection, endpoint_url, name, arguments)
-          else
-            result << tools # will unblock the pop on the main thread
-            connection.close
-          end
-        in { result: { content: } }
-          puts "[MCP DEBUG] Received content event: #{content}"
-          result << content # will unblock the pop on the main thread
-          connection.close
+    # Coerce a single value based on its schema
+    def coerce_value(value, schema)
+      return value unless schema.is_a?(Hash)
+
+      case schema["type"]
+      when "number", "integer"
+        if value.is_a?(String) && value.match?(/\A-?\d+(\.\d+)?\z/)
+          schema["type"] == "integer" ? value.to_i : value.to_f
         else
-          puts "[MCP DEBUG] Received unexpected event: #{event_data}"
+          value
         end
-      end
-
-      def remote_dispatch(connection, endpoint_url, name, arguments)
-        connection.post(endpoint_url) do |req|
-          req.headers["Content-Type"] = "application/json"
-          req.body = {
-            jsonrpc: JSONRPC_VERSION,
-            id: SecureRandom.uuid,
-            method: "tools/call",
-            params: { name:, arguments: }
-          }.to_json
+      when "boolean"
+        case value
+        when "true", true then true
+        when "false", false then false
+        else value
+        end
+      when "array"
+        array_value = begin
+          value.is_a?(String) ? JSON.parse(value) : value
+        rescue JSON::ParserError
+          value
         end
-      end
 
-      def acknowledge_event(connection, endpoint_url)
-        puts "[MCP DEBUG] Acknowledging event"
-        connection.post(endpoint_url) do |req|
-          req.headers["Content-Type"] = "application/json"
-          req.body = {
-            jsonrpc: JSONRPC_VERSION,
-            method: "notifications/initialized"
-          }.to_json
+        # If there's an items schema, coerce each element
+        if array_value.is_a?(Array) && schema["items"]
+          array_value.map { |item| coerce_value(item, schema["items"]) }
+        else
+          array_value
         end
-      end
+      when "object"
+        object_value = begin
+          value.is_a?(String) ? JSON.parse(value) : value
+        rescue JSON::ParserError
+          value
+        end
+
+        # If there are properties defined, coerce them recursively
+        if object_value.is_a?(Hash) && schema["properties"]
+          coerced_object = {}
+          schema["properties"].each do |prop_key, prop_schema|
+            prop_value = object_value[prop_key] || object_value[prop_key.to_sym]
+            coerced_object[prop_key] = coerce_value(prop_value, prop_schema) unless prop_value.nil?
+          end
 
-      def fetch_mcp_tools(connection, endpoint_url)
-        puts "[MCP DEBUG] Fetching tools"
-        connection.post(endpoint_url) do |req|
-          req.headers["Content-Type"] = "application/json"
-          req.body = {
-            jsonrpc: JSONRPC_VERSION,
-            id: SecureRandom.uuid,
-            method: "tools/list",
-            params: {}
-          }.to_json
+          # Include any additional properties not in the schema
+          object_value.each do |obj_key, obj_value|
+            obj_key_str = obj_key.to_s
+            coerced_object[obj_key_str] = obj_value unless coerced_object.key?(obj_key_str)
+          end
+
+          coerced_object
+        else
+          object_value
         end
+      else
+        value
       end
     end
   end

data/lib/raix/predicate.rb

@@ -26,12 +26,9 @@ module Raix
   #   question = Question.new
   #   question.ask("Is Ruby a programming language?")
   module Predicate
+    extend ActiveSupport::Concern
     include ChatCompletion
 
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-
     def ask(question, openai: false)
       raise "Please define a yes and/or no block" if self.class.yes_block.nil? && self.class.no_block.nil?
 

data/lib/raix/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Raix
-  VERSION = "0.8.6"
+  VERSION = "0.9.1"
 end

data/lib/raix.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "raix/version"
+require_relative "raix/configuration"
 require_relative "raix/chat_completion"
 require_relative "raix/function_dispatch"
 require_relative "raix/prompt_declarations"
@@ -10,42 +11,6 @@ require_relative "raix/mcp"
 
 # The Raix module provides configuration options for the Raix gem.
 module Raix
-  # The Configuration class holds the configuration options for the Raix gem.
-  class Configuration
-    # The temperature option determines the randomness of the generated text.
-    # Higher values result in more random output.
-    attr_accessor :temperature
-
-    # The max_tokens option determines the maximum number of tokens to generate.
-    attr_accessor :max_tokens
-
-    # The max_completion_tokens option determines the maximum number of tokens to generate.
-    attr_accessor :max_completion_tokens
-
-    # The model option determines the model to use for text generation. This option
-    # is normally set in each class that includes the ChatCompletion module.
-    attr_accessor :model
-
-    # The openrouter_client option determines the default client to use for communicatio.
-    attr_accessor :openrouter_client
-
-    # The openai_client option determines the OpenAI client to use for communication.
-    attr_accessor :openai_client
-
-    DEFAULT_MAX_TOKENS = 1000
-    DEFAULT_MAX_COMPLETION_TOKENS = 16_384
-    DEFAULT_MODEL = "meta-llama/llama-3-8b-instruct:free"
-    DEFAULT_TEMPERATURE = 0.0
-
-    # Initializes a new instance of the Configuration class with default values.
-    def initialize
-      self.temperature = DEFAULT_TEMPERATURE
-      self.max_completion_tokens = DEFAULT_MAX_COMPLETION_TOKENS
-      self.max_tokens = DEFAULT_MAX_TOKENS
-      self.model = DEFAULT_MODEL
-    end
-  end
-
   class << self
     attr_writer :configuration
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.9.1
 platform: ruby
 authors:
 - Obie Fernandez
@@ -83,8 +83,12 @@ files:
 - README.llm
 - README.md
 - Rakefile
+- lib/mcp/sse_client.rb
+- lib/mcp/stdio_client.rb
+- lib/mcp/tool.rb
 - lib/raix.rb
 - lib/raix/chat_completion.rb
+- lib/raix/configuration.rb
 - lib/raix/function_dispatch.rb
 - lib/raix/mcp.rb
 - lib/raix/message_adapters/base.rb