ruby_llm-mcp 0.4.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f2215062be0096c9eb63dc7b01909a2566731e9ca787572653eb51f8f6292eb
-  data.tar.gz: 987658d5ffcf571d25a252d6ce8f53e4f141a222347ec8dad48a8fbca0344869
+  metadata.gz: 871fadee0f0166df56c6e8ef4ce2a6598c7875af9ca05631687cab1966ccb4e9
+  data.tar.gz: 6cbefa984fd7b541005be0f3f05c3970ab511c90afec9d135212dca33127d992
 SHA512:
-  metadata.gz: 46f94ef9c8a9522a4c66998354755818607874269306bfc91e9fccfde76b783a9e5003306e636c164dc2c01258fa586a054e083abf73f0fe562a887d956238da
-  data.tar.gz: b1cb8a80607903af6bd87c19f745b35285b07e51902af40f2617645bf15ff463e3285cc44759cd33968cad6f5a91059744cd5ce23fa2d8cf4b14a738960eab39
+  metadata.gz: 43b1fcb2d2fd8d6d1ebf7b8a43266443e72be5551ae9866a565bd38f7a90b98832294aadadb562d58a82dae24ff72251fe9eda91aab06a75df061413885c0560
+  data.tar.gz: 9a72ae094803de509b3ec447a43899a001ebd857d7f1085cb31f36a923d189324f7766ed37249866f0fc38e82fb962c11b00737f6821a7e6d723c6a30aa537aa

data/README.md

@@ -1,6 +1,6 @@
 # RubyLLM::MCP
 
-Aiming to make using MCP with RubyLLM as easy as possible.
+Aiming to make using MCPs with RubyLLM as easy as possible.
 
 This project is a Ruby client for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), designed to work seamlessly with [RubyLLM](https://github.com/crmne/ruby_llm). This gem enables Ruby applications to connect to MCP servers and use their tools, resources and prompts as part of LLM conversations.
 
@@ -8,11 +8,13 @@ This project is a Ruby client for the [Model Context Protocol (MCP)](https://mod
 
 ## Features
 
-- 🔌 **Multiple Transport Types**: Support for SSE (Server-Sent Events), Streamable HTTP, and stdio transports
+- 🔌 **Multiple Transport Types**: Streamable HTTP, and STDIO and legacy SSE transports
 - 🛠️ **Tool Integration**: Automatically converts MCP tools into RubyLLM-compatible tools
 - 📄 **Resource Management**: Access and include MCP resources (files, data) and resource templates in conversations
 - 🎯 **Prompt Integration**: Use predefined MCP prompts with arguments for consistent interactions
+- 🎛️ **Client Features**: Support for sampling and roots
 - 🎨 **Enhanced Chat Interface**: Extended RubyLLM chat methods for seamless MCP integration
+- 🔄 **Multiple Client Management**: Create and manage multiple MCP clients simultaneously for different servers and purposes
 - 📚 **Simple API**: Easy-to-use interface that integrates seamlessly with RubyLLM
 
 ## Installation
@@ -121,13 +123,11 @@ puts result # 3
 # If the human in the loop returns false, the tool call will be cancelled
 result = tool.execute(a: 2, b: 2)
 puts result # Tool execution error: Tool call was cancelled by the client
-```
 
 tool = client.tool("add")
 result = tool.execute(a: 1, b: 2)
 puts result
-
-````
+```
 
 ### Support Complex Parameters
 
@@ -135,7 +135,7 @@ If you want to support complex parameters, like an array of objects it currently
 
 ```ruby
 RubyLLM::MCP.support_complex_parameters!
-````
+```
 
 ### Streaming Responses with Tool Calls
 
@@ -228,23 +228,6 @@ content = log_template.to_content(arguments: {
 puts content
 ```
 
-#### Resource Argument Completion
-
-For resource templates, you can get suggested values for arguments:
-
-```ruby
-template = client.resource_template("user_profile")
-
-# Search for possible values for a specific argument
-suggestions = template.complete("username", "john")
-puts "Suggested usernames:"
-suggestions.values.each do |value|
-  puts "- #{value}"
-end
-puts "Total matches: #{suggestions.total}"
-puts "Has more: #{suggestions.has_more}"
-```
-
 ### Working with Prompts
 
 MCP servers can provide predefined prompts that can be used in conversations:
@@ -307,7 +290,7 @@ response = chat.ask("Please review the recent commits using the checklist and su
 puts response
 ```
 
-## Argument Completion
+### Argument Completion
 
 Some MCP servers support argument completion for prompts and resource templates:
 
@@ -324,7 +307,13 @@ puts "Total matches: #{suggestions.total}"
 puts "Has more results: #{suggestions.has_more}"
 ```
 
-## Additional Chat Methods
+### Pagination
+
+MCP servers can support pagination for their lists. The client will automatically paginate the lists to include all items from the list you wanted to pull.
+
+Pagination is supported for tools, resources, prompts, and resource templates.
+
+### Additional Chat Methods
 
 The gem extends RubyLLM's chat interface with convenient methods for MCP integration:
 
@@ -347,6 +336,86 @@ chat.with_prompt(prompt, arguments: { name: "Alice" })
 response = chat.ask_prompt(prompt, arguments: { name: "Alice" })
 ```
 
+## Rails Integration
+
+RubyLLM MCP provides seamless Rails integration through a Railtie and generator system.
+
+### Setup
+
+Generate the configuration files:
+
+```bash
+rails generate ruby_llm:mcp:install
+```
+
+This creates:
+
+- `config/initializers/ruby_llm_mcp.rb` - Main configuration
+- `config/mcps.yml` - MCP servers configuration
+
+### MCP Server Configuration
+
+Configure your MCP servers in `config/mcps.yml`:
+
+```yaml
+mcp_servers:
+  filesystem:
+    transport_type: stdio
+    command: npx
+    args:
+      - "@modelcontextprotocol/server-filesystem"
+      - "<%= Rails.root %>"
+    env: {}
+    with_prefix: true
+
+  api_server:
+    transport_type: sse
+    url: "https://api.example.com/mcp/sse"
+    headers:
+      Authorization: "Bearer <%= ENV['API_TOKEN'] %>"
+```
+
+### Automatic Client Management
+
+With `launch_control: :automatic`, Rails will:
+
+- Start all configured MCP clients when the application initializes
+- Gracefully shut down clients when the application exits
+- Handle client lifecycle automatically
+
+However, it's very command to due to the performace of LLM calls that are made in the background.
+
+For this, we recommend using `launch_control: :manual` and use `establish_connection` method to manage the client lifecycle manually inside your background jobs. It will provide you active connections to the MCP servers, and take care of closing them when the job is done.
+
+```ruby
+RubyLLM::MCP.establish_connection do |clients|
+  chat = RubyLLM.chat(model: "gpt-4")
+  chat.with_tools(*clients.tools)
+
+  response = chat.ask("Hello, world!")
+  puts response
+end
+```
+
+You can also avoid this completely manually start and stop the clients if you so choose.
+
+If you want to use the clients outside of the block, you can use the `clients` method to get the clients.
+
+```ruby
+clients = RubyLLM::MCP.establish_connection
+chat = RubyLLM.chat(model: "gpt-4")
+chat.with_tools(*clients.tools)
+
+response = chat.ask("Hello, world!")
+puts response
+```
+
+However, you will be responsible for closing the connection when you are done with it.
+
+```ruby
+RubyLLM::MCP.close_connection
+```
+
 ## Client Lifecycle Management
 
 You can manage the MCP client connection lifecycle:
@@ -462,6 +531,81 @@ puts result
 # Result: { status: "success", data: "Processed data" }
 ```
 
+## Client Features
+
+The RubyLLM::MCP client provides support functionality that can be exposed to MCP servers. These features must be explicitly configured before creating client objects to ensure you're opting into this functionality.
+
+### Roots
+
+Roots provide MCP servers with access to underlying file system information. The implementation starts with a lightweight approach due to the MCP specification's current limitations on root usage.
+
+When roots are configured, the client will:
+
+- Expose roots as a supported capability to MCP servers
+- Support dynamic addition and removal of roots during the client lifecycle
+- Fire `notifications/roots/list_changed` events when roots are modified
+
+#### Configuration
+
+```ruby
+RubyLLM::MCP.config do |config|
+  config.roots = ["to/a/path", Rails.root]
+end
+
+client = RubyLLM::MCP::Client.new(...)
+```
+
+#### Usage
+
+```ruby
+# Access current root paths
+client.roots.paths
+# => ["to/a/path", #<Pathname:/to/rails/root/path>]
+
+# Add a new root (fires list_changed notification)
+client.roots.add("new/path")
+client.roots.paths
+# => ["to/a/path", #<Pathname:/to/rails/root/path>, "new/path"]
+
+# Remove a root (fires list_changed notification)
+client.roots.remove("to/a/path")
+client.roots.paths
+# => [#<Pathname:/to/rails/root/path>, "new/path"]
+```
+
+### Sampling
+
+Sampling allows MCP servers to offload LLM requests to the MCP client rather than making them directly from the server. This enables MCP servers to optionally use LLM connections through the client.
+
+#### Configuration
+
+```ruby
+RubyLLM::MCP.configure do |config|
+  config.sampling.enabled = true
+  config.sampling.preferred_model = "gpt-4.1"
+
+  # Optional: Use a block for dynamic model selection
+  config.sampling.preferred_model do |model_preferences|
+    model_preferences.hints.first
+  end
+
+  # Optional: Add guards to filter sampling requests
+  config.sampling.guard do |sample|
+    sample.message.include("Hello")
+  end
+end
+```
+
+#### How It Works
+
+With the above configuration:
+
+- Clients will respond to all incoming sample requests using the specified model (`gpt-4.1`)
+- Sample messages will only be approved if they contain the word "Hello" (when using the guard)
+- The `preferred_model` can be a string or a proc that provides dynamic model selection based on MCP server characteristics
+
+The `preferred_model` proc receives model preferences from the MCP server, allowing you to make intelligent model selection decisions based on the server's requirements for success.
+
 ## Transport Types
 
 ### SSE (Server-Sent Events)
@@ -510,6 +654,150 @@ client = RubyLLM::MCP.client(
 )
 ```
 
+## Creating Custom Transports
+
+Part of the MCP specification outlines that custom transports can be used for some MCP servers. Out of the box, RubyLLM::MCP supports Streamable HTTP transports, STDIO and the legacy SSE transport.
+
+You can create custom transport implementations to support additional communication protocols or specialized connection methods.
+
+### Transport Registration
+
+Register your custom transport with the transport factory:
+
+```ruby
+# Define your custom transport class
+class MyCustomTransport
+  # Implementation details...
+end
+
+# Register it with the factory
+RubyLLM::MCP::Transport.register_transport(:my_custom, MyCustomTransport)
+
+# Now you can use it
+client = RubyLLM::MCP.client(
+  name: "custom-server",
+  transport_type: :my_custom,
+  config: {
+    # Your custom configuration
+  }
+)
+```
+
+### Required Interface
+
+All transport implementations must implement the following interface:
+
+```ruby
+class MyCustomTransport
+  # Initialize the transport
+  def initialize(coordinator:, **config)
+    @coordinator = coordinator # Uses for communication between the client and the MCP server
+    @config = config # Transport-specific configuration
+  end
+
+  # Send a request and optionally wait for response
+  # Returns a RubyLLM::MCP::Result object
+  # body: the request body
+  # add_id: true will add an id to the request
+  # wait_for_response: true will wait for a response from the MCP server
+  # Returns a RubyLLM::MCP::Result object
+  def request(body, add_id: true, wait_for_response: true)
+    # Implementation: send request and return result
+    data = some_method_to_send_request_and_get_result(body)
+    # Use Result object to make working with the protocol easier
+    result = RubyLLM::MCP::Result.new(data)
+
+    # Call the coordinator to process the result
+    @coordinator.process_result(result)
+    return if result.nil? # Some results are related to notifications and should not be returned to the client, but processed by the coordinator instead
+
+    # Return the result
+    result
+  end
+
+  # Check if transport is alive/connected
+  def alive?
+    # Implementation: return true if connected
+  end
+
+  # Start the transport connection
+  def start
+    # Implementation: establish connection
+  end
+
+  # Close the transport connection
+  def close
+    # Implementation: cleanup and close connection
+  end
+
+  # Set the MCP protocol version, used in some transports to identify the agreed upon protocol version
+  def set_protocol_version(version)
+    @protocol_version = version
+  end
+end
+```
+
+### The Result Object
+
+The `RubyLLM::MCP::Result` class wraps MCP responses and provides convenient methods:
+
+```ruby
+result = transport.request(body)
+
+# Core properties
+result.id          # Request ID
+result.method      # Request method
+result.result      # Result data (hash)
+result.params      # Request parameters
+result.error       # Error data (hash)
+result.session_id  # Session ID (if applicable)
+
+# Type checking
+result.success?      # Has result data
+result.error?        # Has error data
+result.notification? # Is a notification
+result.request?      # Is a request
+result.response?     # Is a response
+
+# Specialized methods
+result.tool_success?     # Successful tool execution
+result.execution_error?  # Tool execution failed
+result.matching_id?(id)  # Matches request ID
+result.next_cursor?      # Has pagination cursor
+
+# Error handling
+result.raise_error!  # Raise exception if error
+result.to_error      # Convert to Error object
+
+# Notifications
+result.notification  # Get notification object
+```
+
+### Error Handling
+
+Custom transports should handle errors appropriately. If request fails, you should raise a `RubyLLM::MCP::Errors::TransportError` exception. If the request times out, you should raise a `RubyLLM::MCP::Errors::TimeoutError` exception. This will ensure that a cancellation notification is sent to the MCP server correctly.
+
+```ruby
+def request(body, add_id: true, wait_for_response: true)
+  begin
+    # Send request
+    send_request(body)
+  rescue SomeConnectionError => e
+    # Convert to MCP transport error
+    raise RubyLLM::MCP::Errors::TransportError.new(
+      message: "Connection failed: #{e.message}",
+      error: e
+    )
+  rescue Timeout::Error => e
+    # Convert to MCP timeout error
+    raise RubyLLM::MCP::Errors::TimeoutError.new(
+      message: "Request timeout after #{@request_timeout}ms",
+      request_id: body["id"]
+    )
+  end
+end
+```
+
 ## RubyLLM::MCP and Client Configuration Options
 
 MCP comes with some common configuration options that can be set on the client.

data/lib/generators/ruby_llm/mcp/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RubyLlm
+  module Mcp
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Install RubyLLM MCP configuration files"
+
+        def create_initializer
+          template "initializer.rb", "config/initializers/ruby_llm_mcp.rb"
+        end
+
+        def create_config_file
+          template "mcps.yml", "config/mcps.yml"
+        end
+
+        def display_readme
+          readme "README.txt" if behavior == :invoke
+        end
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/mcp/templates/README.txt

@@ -0,0 +1,32 @@
+RubyLLM MCP has been successfully installed!
+
+The following files have been created:
+
+  config/initializers/ruby_llm_mcp.rb - Main configuration file
+  config/mcps.json                    - MCP servers configuration
+
+Next steps:
+
+1. Edit config/initializers/ruby_llm_mcp.rb to configure your MCP settings
+2. Edit config/mcps.json to define your MCP servers
+3. Install any MCP servers you want to use (e.g., npm install @modelcontextprotocol/server-filesystem) or use remote MCPs
+4. Update environment variables for any MCP servers that require authentication
+
+Example usage in your Rails application:
+
+  # With Ruby::MCP installed in a controller or service
+  clients = RubyLLM::MCP.clients
+
+  # Get all tools use the configured client
+  tools = RubyLLM::MCP.tools
+
+  # Or use the configured client
+  client = RubyLLM::MCP.clients["file-system"]
+
+  # Or use the configured client
+  tools = client.tools
+
+
+For more information, visit: https://github.com/patvice/ruby_llm-mcp
+
+===============================================================================

data/lib/generators/ruby_llm/mcp/templates/initializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Configure RubyLLM MCP
+RubyLLM::MCP.configure do |config|
+  # Request timeout in milliseconds
+  config.request_timeout = 8000
+
+  # Maximum connections in the pool
+  config.max_connections = Float::INFINITY
+
+  # Pool timeout in seconds
+  config.pool_timeout = 5
+
+  # Enable complex parameter support for various providers
+  config.support_complex_parameters!
+
+  # Path to MCPs configuration file
+  config.config_path = Rails.root.join("config", "mcps.yml")
+
+  # Launch MCPs (:automatic, :manual)
+  config.launch_control = :automatic
+
+  # Configure roots for file system access
+  # config.roots = [
+  #   Rails.root.to_s
+  # ]
+
+  # Configure sampling (optional)
+  config.sampling.enabled = false
+
+  # Set preferred model for sampling
+  # config.sampling.preferred_model do
+  #   # Return the preferred model name
+  #   "claude-3-5-sonnet-20240620"
+  # end
+
+  # Set a guard for sampling
+  # config.sampling.guard do
+  #   # Return true to enable sampling, false to disable
+  #   Rails.env.development?
+  # end
+end

data/lib/generators/ruby_llm/mcp/templates/mcps.yml

@@ -0,0 +1,9 @@
+mcp_servers:
+  filesystem:
+    transport_type: stdio
+    command: npx
+    args:
+      - "@modelcontextprotocol/server-filesystem"
+      - "<%%= Rails.root %>"
+    env: {}
+    with_prefix: true

data/lib/ruby_llm/chat.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-# This is an override of the RubyLLM::Chat class to convient methods for easy MCP support
+# This is an override of the RubyLLM::Chat class to add convenient methods to more
+# easily work with the MCP clients.
 module RubyLLM
   class Chat
     def with_resources(*resources, **args)

data/lib/ruby_llm/mcp/client.rb

@@ -7,10 +7,11 @@ module RubyLLM
     class Client
       extend Forwardable
 
-      attr_reader :name, :config, :transport_type, :request_timeout, :log_level, :on
+      attr_reader :name, :config, :transport_type, :request_timeout, :log_level, :on, :roots
 
       def initialize(name:, transport_type:, start: true, request_timeout: MCP.config.request_timeout, config: {})
         @name = name
+        @with_prefix = config.delete(:with_prefix) || false
         @config = config.merge(request_timeout: request_timeout)
         @transport_type = transport_type.to_sym
         @request_timeout = request_timeout
@@ -25,10 +26,13 @@ module RubyLLM
 
         @log_level = nil
 
+        setup_roots
+        setup_sampling
+
         @coordinator.start_transport if start
       end
 
-      def_delegators :@coordinator, :alive?, :capabilities, :ping
+      def_delegators :@coordinator, :alive?, :capabilities, :ping, :client_capabilities
 
       def start
         @coordinator.start_transport
@@ -47,7 +51,7 @@ module RubyLLM
 
         fetch(:tools, refresh) do
           tools = @coordinator.tool_list
-          build_map(tools, MCP::Tool)
+          build_map(tools, MCP::Tool, with_prefix: @with_prefix)
         end
 
         @tools.values
@@ -152,16 +156,19 @@ module RubyLLM
         !@log_level.nil?
       end
 
-      def on_logging(level: Logging::WARNING, logger: nil, &block)
+      def on_logging(level: Logging::WARNING, &block)
         @coordinator.set_logging(level: level)
 
-        @on[:logging] = if block_given?
-                          block
-                        else
-                          lambda do |notification|
-                            @coordinator.default_process_logging_message(notification, logger: logger)
-                          end
-                        end
+        @on[:logging] = block
+        self
+      end
+
+      def sampling_callback_enabled?
+        @on.key?(:sampling) && !@on[:sampling].nil?
+      end
+
+      def on_sampling(&block)
+        @on[:sampling] = block
         self
       end
 
@@ -181,12 +188,24 @@ module RubyLLM
         instance_variable_get("@#{cache_key}")
       end
 
-      def build_map(raw_data, klass)
+      def build_map(raw_data, klass, with_prefix: false)
         raw_data.each_with_object({}) do |item, acc|
-          instance = klass.new(@coordinator, item)
+          instance = if with_prefix
+                       klass.new(@coordinator, item, with_prefix: @with_prefix)
+                     else
+                       klass.new(@coordinator, item)
+                     end
           acc[instance.name] = instance
         end
       end
+
+      def setup_roots
+        @roots = Roots.new(paths: MCP.config.roots, coordinator: @coordinator)
+      end
+
+      def setup_sampling
+        @on[:sampling] = MCP.config.sampling.guard
+      end
     end
   end
 end