raix 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90b0072e3af33e82ccfb040554e9645920e34b4477457ba79335582c9325a7bd
-  data.tar.gz: beeb6e0b98b473597d2191b5005fc89cb57fe69633cfe1e8927a6c1c0f61048f
+  metadata.gz: '08737974243ed41d4db2406405a4d081e31972cf173cfc3b2859cb97eabf0848'
+  data.tar.gz: 0d78927f5a35fad586f300bff4d86ce773d7bb7cd9f6787320e1cff6297f1aed
 SHA512:
-  metadata.gz: cbc28460d07263899c0e45be8ccfd3fa522b3162ad2a53d640c1ff0cccb6c7d96f7ab4bef2afa809d47733a98a4a502602b78a6c53918e676955da9d88220f69
-  data.tar.gz: d5e4f7dedaeb3ab2de64168f17a9de920a18894d5acfff22c0e00b870bdf96c77478130a61d47f82f7cc01a566b1cbc95f41fb43241cb3ece24c743b80993fed
+  metadata.gz: c0eec6ef99a37cd8ba69dfec62c8be70c9a8f6ed0be78b24ed184bde364c78f5189ccac71e3196f56af4c85390844b044c30be1b69172fe4e0f3c584903ea7c0
+  data.tar.gz: 90f084213b11dd737b55ed89fd21e75cf23b4c0ef5ab0daca8652f974b9fdb0f40a68ee07ea2abcd0b6af715ae3edc684643034b7e7e3455f7d05fae9ee1e473

data/.rubocop.yml

@@ -35,3 +35,9 @@ Metrics/PerceivedComplexity:
 
 Metrics/ParameterLists:
   Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false

data/.ruby-version

@@ -1 +1 @@
-3.2.2
+3.4.2

data/CHANGELOG.md

@@ -1,4 +1,20 @@
+## [0.8.0] - 2024-05-08
+### Added
+* **MCP integration (Experimental)** — new `Raix::MCP` concern and `mcp` DSL for declaring remote MCP servers.
+  * Automatically fetches `tools/list`, registers remote tools as OpenAI‑compatible function schemas, and defines proxy methods that forward `tools/call`.
+  * `ChatCompletion#tools` now returns remote MCP tools alongside local `function` declarations.
+
+### Changed
+* `lib/raix.rb` now requires `raix/mcp` so the concern is auto‑loaded.
+
+### Fixed
+* Internal transcript handling spec expectations updated.
+
+### Specs
+* Added `spec/raix/mcp_spec.rb` with comprehensive stubs for tools discovery & call flow.
+
 ## [0.7.3] - 2025-04-23
+- commit function call and result to transcript in one operation for thread safety
 
 ## [0.7.2] - 2025-04-19
 - adds support for `messages` parameter in `chat_completion` to override the transcript

data/Gemfile

@@ -5,11 +5,6 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in raix-rails.gemspec
 gemspec
 
-gem "activesupport", ">= 6.0"
-gem "faraday-retry"
-gem "open_router", "~> 0.3"
-gem "ruby-openai", "~> 7.0"
-
 group :development do
   gem "dotenv", ">= 2"
   gem "guard"

data/Gemfile.lock

@@ -1,10 +1,11 @@
 PATH
   remote: .
   specs:
-    raix (0.7.3)
+    raix (0.8.0)
       activesupport (>= 6.0)
+      faraday-retry (~> 2.0)
       open_router (~> 0.2)
-      ruby-openai (~> 7.0)
+      ruby-openai (~> 7)
 
 GEM
   remote: https://rubygems.org/
@@ -43,10 +44,10 @@ GEM
       multipart-post (~> 2)
     faraday-net_http (3.1.0)
       net-http
-    faraday-retry (2.2.1)
+    faraday-retry (2.3.1)
       faraday (~> 2.0)
-    ffi (1.17.0-arm64-darwin)
-    ffi (1.17.0-x86_64-linux-gnu)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
     formatador (1.1.0)
     guard (2.18.1)
       formatador (>= 0.2.4)
@@ -84,9 +85,9 @@ GEM
     net-http (0.4.1)
       uri
     netrc (0.11.0)
-    nokogiri (1.16.6-arm64-darwin)
+    nokogiri (1.18.8-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.16.6-x86_64-linux)
+    nokogiri (1.18.8-x86_64-linux-gnu)
       racc (~> 1.4)
     notiffany (0.1.3)
       nenv (~> 0.1)
@@ -216,18 +217,14 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  activesupport (>= 6.0)
   dotenv (>= 2)
-  faraday-retry
   guard
   guard-rspec
-  open_router (~> 0.3)
   pry (>= 0.14)
   raix!
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.21)
-  ruby-openai (~> 7.0)
   solargraph-rails (~> 0.2.0.pre)
   sorbet
   tapioca

data/README.md

@@ -452,6 +452,50 @@ question.ask("Any question")
 # => RuntimeError: Please define a yes and/or no block
 ```
 
+## Model Context Protocol (Experimental)
+
+The `Raix::MCP` module provides integration with the Model Context Protocol, allowing you to connect your Raix-powered application to remote MCP servers. This feature is currently **experimental**.
+
+### Usage
+
+Include the `Raix::MCP` module in your class and declare MCP servers using the `mcp` DSL:
+
+```ruby
+class McpConsumer
+  include Raix::ChatCompletion
+  include Raix::FunctionDispatch
+  include Raix::MCP
+
+  mcp "https://your-mcp-server.example.com/sse"
+end
+```
+
+### Features
+
+- Automatically fetches available tools from the remote MCP server using `tools/list`
+- Registers remote tools as OpenAI-compatible function schemas
+- Defines proxy methods that forward requests to the remote server via `tools/call`
+- Seamlessly integrates with the existing `FunctionDispatch` workflow
+- Handles transcript recording to maintain consistent conversation history
+
+### Filtering Tools
+
+You can filter which remote tools to include:
+
+```ruby
+class FilteredMcpConsumer
+  include Raix::ChatCompletion
+  include Raix::FunctionDispatch
+  include Raix::MCP
+
+  # Only include specific tools
+  mcp "https://server.example.com/sse", only: [:tool_one, :tool_two]
+
+  # Or exclude specific tools
+  mcp "https://server.example.com/sse", except: [:tool_to_exclude]
+end
+```
+
 ## Response Format (Experimental)
 
 The `ResponseFormat` class provides a way to declare a JSON schema for the response format of an AI chat completion. It's particularly useful when you need structured responses from AI models, ensuring the output conforms to your application's requirements.

data/lib/raix/mcp.rb

@@ -0,0 +1,337 @@
+# Simple integration layer that lets Raix classes declare an MCP server
+# with a single DSL call:
+#
+#   mcp "https://my-server.example.com/sse"
+#
+# The concern fetches the remote server's tool list (via JSON‑RPC 2.0
+# `tools/list`) and exposes each remote tool as if it were an inline
+# `function` declared with Raix::FunctionDispatch.  When the tool is
+# invoked by the model, the generated instance method forwards the
+# request to the remote server using `tools/call`, captures the result,
+# and appends the appropriate messages to the transcript so that the
+# conversation history stays consistent.
+
+require "active_support/concern"
+require "active_support/inflector"
+require "securerandom"
+require "faraday"
+require "uri"
+require "json"
+
+module Raix
+  # Model Context Protocol integration for Raix
+  #
+  # Allows declaring MCP servers with a simple DSL that automatically:
+  # - Queries tools from the remote server
+  # - Exposes each tool as a function callable by LLMs
+  # - Handles transcript recording and response processing
+  module MCP
+    extend ActiveSupport::Concern
+
+    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.
+      #
+      #   mcp "https://server.example.com/sse"
+      #
+      # This will automatically:
+      #   • query `tools/list` on the server
+      #   • register each remote tool with FunctionDispatch so that the
+      #     OpenAI / OpenRouter request body includes its JSON‑Schema
+      #   • define an instance method for each tool that forwards the
+      #     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)
+        @mcp_servers ||= {}
+
+        return if @mcp_servers.key?(url) # 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
+
+        if tools.empty?
+          puts "[MCP DEBUG] No tools found from MCP server at #{url}"
+          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) }
+                         elsif except.present?
+                           except_symbols = Array(except).map(&: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}"
+
+        filtered_tools.each do |tool|
+          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
+
+          description  = tool["description"]
+          input_schema = tool["inputSchema"] || {}
+
+          # --- 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?
+
+          # --- define an instance method that proxies to the server
+          define_method(local_name) do |**arguments|
+            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
+
+            # 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
+
+            # Mirror FunctionDispatch transcript behaviour
+            transcript << [
+              {
+                role: "assistant",
+                content: nil,
+                tool_calls: [
+                  {
+                    id: call_id,
+                    type: "function",
+                    function: {
+                      name: remote_name,
+                      arguments: arguments.to_json
+                    }
+                  }
+                ]
+              },
+              {
+                role: "tool",
+                tool_call_id: call_id,
+                name: remote_name,
+                content: content_text
+              }
+            ]
+
+            # Continue the chat loop if requested (same semantics as FunctionDispatch)
+            chat_completion(**chat_completion_args) if loop
+
+            content_text
+          end
+        end
+
+        # Store the URL and tools for future use
+        @mcp_servers[url] = { tools: }
+      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
+
+        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
+
+      # 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
+
+        [event_type, data_lines.join("\n").strip]
+      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
+      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
+
+      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
+        else
+          puts "[MCP DEBUG] Received unexpected event: #{event_data}"
+        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
+        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
+        end
+      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
+        end
+      end
+    end
+  end
+end

data/lib/raix/version.rb

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

data/lib/raix.rb

@@ -6,6 +6,7 @@ require_relative "raix/function_dispatch"
 require_relative "raix/prompt_declarations"
 require_relative "raix/predicate"
 require_relative "raix/response_format"
+require_relative "raix/mcp"
 
 # The Raix module provides configuration options for the Raix gem.
 module Raix

data/raix.gemspec

@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "activesupport", ">= 6.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
   spec.add_dependency "open_router", "~> 0.2"
-  spec.add_dependency "ruby-openai", "~> 7.0"
+  spec.add_dependency "ruby-openai", "~> 7"
 end

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - Obie Fernandez
-autorequire:
 bindir: exe
 cert_chain: []
 date: 2025-04-23 00:00:00.000000000 Z
@@ -24,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: open_router
   requirement: !ruby/object:Gem::Requirement
@@ -44,15 +57,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
-description:
+        version: '7'
 email:
 - obiefernandez@gmail.com
 executables: []
@@ -74,6 +86,7 @@ files:
 - lib/raix.rb
 - lib/raix/chat_completion.rb
 - lib/raix/function_dispatch.rb
+- lib/raix/mcp.rb
 - lib/raix/message_adapters/base.rb
 - lib/raix/predicate.rb
 - lib/raix/prompt_declarations.rb
@@ -88,7 +101,6 @@ metadata:
   homepage_uri: https://github.com/OlympiaAI/raix
   source_code_uri: https://github.com/OlympiaAI/raix
   changelog_uri: https://github.com/OlympiaAI/raix/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -103,8 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Ruby AI eXtensions
 test_files: []