ruby_llm-mcp 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49b1593de3f38afce9d3002a696c7034c2bea82711742ea4bd96a5f155f113e3
-  data.tar.gz: 6fb3c4b87bc82684bb9ef093b70b13eea91e759f5ee44a08b4be543cc45d30d3
+  metadata.gz: c414a0306ebefcb35dcb599406a0092e554e1389aebfa812597e7072e304cf88
+  data.tar.gz: 25b384446ad37b3422bf64e1f9b15413bd8cd64636dbf50ad8ae861e4dc4589d
 SHA512:
-  metadata.gz: 6950867fde16315dba705049ec2d23cc89f3977808d323af20b5bf343b2453228145190e183bfd6350b95df856ae96bf4f60a83145eb0137dad0003454c889d3
-  data.tar.gz: 1ed01c5ec46651c1b420971a429299e60b59707255403f1a167c8832cfde9ee5ba1a5ed00ba1edea8f2bf710006f1d605896781c329f02f5ca056642fe246100
+  metadata.gz: abbca445c4ecb2ee7a3f2af4457f47aff5337ac981426746184cb0cb63e699b606116d5db983d8d4183557896675743a14bada2af4dd3d54d85066183fe34653
+  data.tar.gz: d8007f3ee983eb3a8e2e76ad2b0daa8ead92bc6347e3352d8d569fab770056026a29237a76182c137459663b54cb4b364df93fb7e968a2d783d1c96fe98f4774

data/README.md

@@ -12,13 +12,16 @@ This project is a Ruby client for the [Model Context Protocol (MCP)](https://mod
 - 🛠️ **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
-- 🔄 **Real-time Communication**: Efficient bidirectional communication with MCP servers
 - 🎨 **Enhanced Chat Interface**: Extended RubyLLM chat methods for seamless MCP integration
 - 📚 **Simple API**: Easy-to-use interface that integrates seamlessly with RubyLLM
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```bash
+bundle add ruby_llm-mcp
+```
+
+or add this line to your application's Gemfile:
 
 ```ruby
 gem 'ruby_llm-mcp'
@@ -152,12 +155,12 @@ MCP servers can provide access to resources - structured data that can be includ
 # Get available resources from the MCP server
 resources = client.resources
 puts "Available resources:"
-resources.each do |name, resource|
-  puts "- #{name}: #{resource.description}"
+resources.each do |resource|
+  puts "- #{resource.name}: #{resource.description}"
 end
 
-# Access a specific resource
-file_resource = resources["project_readme"]
+# Access a specific resource by name
+file_resource = client.resource("project_readme")
 content = file_resource.content
 puts "Resource content: #{content}"
 
@@ -179,11 +182,11 @@ Resource templates are parameterized resources that can be dynamically configure
 ```ruby
 # Get available resource templates
 templates = client.resource_templates
-log_template = templates["application_logs"]
+log_template = client.resource_template("application_logs")
 
 # Use a template with parameters
 chat = RubyLLM.chat(model: "gpt-4")
-chat.with_resource(log_template, arguments: {
+chat.with_resource_template(log_template, arguments: {
   date: "2024-01-15",
   level: "error"
 })
@@ -192,7 +195,7 @@ response = chat.ask("What errors occurred on this date?")
 puts response
 
 # You can also get templated content directly
-content = log_template.content(arguments: {
+content = log_template.to_content(arguments: {
   date: "2024-01-15",
   level: "error"
 })
@@ -204,12 +207,12 @@ puts content
 For resource templates, you can get suggested values for arguments:
 
 ```ruby
-template = client.resource_templates["user_profile"]
+template = client.resource_template("user_profile")
 
 # Search for possible values for a specific argument
-suggestions = template.arguments_search("username", "john")
+suggestions = template.complete("username", "john")
 puts "Suggested usernames:"
-suggestions.arg_values.each do |value|
+suggestions.values.each do |value|
   puts "- #{value}"
 end
 puts "Total matches: #{suggestions.total}"
@@ -224,15 +227,15 @@ MCP servers can provide predefined prompts that can be used in conversations:
 # Get available prompts from the MCP server
 prompts = client.prompts
 puts "Available prompts:"
-prompts.each do |name, prompt|
-  puts "- #{name}: #{prompt.description}"
+prompts.each do |prompt|
+  puts "- #{prompt.name}: #{prompt.description}"
   prompt.arguments.each do |arg|
     puts "  - #{arg.name}: #{arg.description} (required: #{arg.required})"
   end
 end
 
 # Use a prompt in a conversation
-greeting_prompt = prompts["daily_greeting"]
+greeting_prompt = client.prompt("daily_greeting")
 chat = RubyLLM.chat(model: "gpt-4")
 
 # Method 1: Ask prompt directly
@@ -261,15 +264,15 @@ chat = RubyLLM.chat(model: "gpt-4")
 chat.with_tools(*client.tools)
 
 # Add resources for context
-chat.with_resource(client.resources["project_structure"])
+chat.with_resource(client.resource("project_structure"))
 chat.with_resource(
-  client.resource_templates["recent_commits"],
+  client.resource_template("recent_commits"),
   arguments: { days: 7 }
 )
 
 # Add prompts for guidance
 chat.with_prompt(
-  client.prompts["code_review_checklist"],
+  client.prompt("code_review_checklist"),
   arguments: { focus: "security" }
 )
 
@@ -278,6 +281,88 @@ response = chat.ask("Please review the recent commits using the checklist and su
 puts response
 ```
 
+## Argument Completion
+
+Some MCP servers support argument completion for prompts and resource templates:
+
+```ruby
+# For prompts
+prompt = client.prompt("user_search")
+suggestions = prompt.complete("username", "jo")
+puts "Suggestions: #{suggestions.values}" # ["john", "joanna", "joseph"]
+
+# For resource templates
+template = client.resource_template("user_logs")
+suggestions = template.complete("user_id", "123")
+puts "Total matches: #{suggestions.total}"
+puts "Has more results: #{suggestions.has_more}"
+```
+
+## Additional Chat Methods
+
+The gem extends RubyLLM's chat interface with convenient methods for MCP integration:
+
+```ruby
+chat = RubyLLM.chat(model: "gpt-4")
+
+# Add a single resource
+chat.with_resource(resource)
+
+# Add multiple resources
+chat.with_resources(resource1, resource2, resource3)
+
+# Add a resource template with arguments
+chat.with_resource_template(resource_template, arguments: { key: "value" })
+
+# Add a prompt with arguments
+chat.with_prompt(prompt, arguments: { name: "Alice" })
+
+# Ask using a prompt directly
+response = chat.ask_prompt(prompt, arguments: { name: "Alice" })
+```
+
+## Client Lifecycle Management
+
+You can manage the MCP client connection lifecycle:
+
+```ruby
+client = RubyLLM::MCP.client(name: "my-server", transport_type: :stdio, start: false, config: {...})
+
+# Manually start the connection
+client.start
+
+# Check if connection is alive
+puts client.alive?
+
+# Restart the connection
+client.restart!
+
+# Stop the connection
+client.stop
+```
+
+## Refreshing Cached Data
+
+The client caches tools, resources, prompts, and resource templates list calls are cached to reduce round trips back to the MCP server. You can refresh this cache:
+
+```ruby
+# Refresh all cached tools
+tools = client.tools(refresh: true)
+
+# Refresh a specific tool
+tool = client.tool("search_files", refresh: true)
+
+# Same pattern works for resources, prompts, and resource templates
+resources = client.resources(refresh: true)
+prompts = client.prompts(refresh: true)
+templates = client.resource_templates(refresh: true)
+
+# Or refresh specific items
+resource = client.resource("project_readme", refresh: true)
+prompt = client.prompt("daily_greeting", refresh: true)
+template = client.resource_template("user_logs", refresh: true)
+```
+
 ## Transport Types
 
 ### SSE (Server-Sent Events)
@@ -289,7 +374,8 @@ client = RubyLLM::MCP.client(
   name: "web-mcp-server",
   transport_type: :sse,
   config: {
-    url: "https://your-mcp-server.com/mcp/sse"
+    url: "https://your-mcp-server.com/mcp/sse",
+    headers: { "Authorization" => "Bearer your-token" }
   }
 )
 ```
@@ -329,9 +415,10 @@ client = RubyLLM::MCP.client(
 
 - `name`: A unique identifier for your MCP client
 - `transport_type`: Either `:sse`, `:streamable`, or `:stdio`
+- `start`: Whether to automatically start the connection (default: true)
 - `request_timeout`: Timeout for requests in milliseconds (default: 8000)
 - `config`: Transport-specific configuration
-  - For SSE: `{ url: "http://..." }`
+  - For SSE: `{ url: "http://...", headers: {...} }`
   - For Streamable: `{ url: "http://...", headers: {...} }`
   - For stdio: `{ command: "...", args: [...], env: {...} }`
 
@@ -339,13 +426,16 @@ client = RubyLLM::MCP.client(
 
 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.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. Run `bundle exec rake` to test specs and run linters. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Examples
 
 Check out the `examples/` directory for more detailed usage examples:
 
-- `examples/test_local_mcp.rb` - Complete example with SSE transport
+- `examples/tools/local_mcp.rb` - Complete example with stdio transport
+- `examples/tools/sse_mcp_with_gpt.rb` - Example using SSE transport with GPT
+- `examples/resources/list_resources.rb` - Example of listing and using resources
+- `examples/prompts/streamable_prompt_call.rb` - Example of using prompts with streamable transport
 
 ## Contributing
 

data/lib/ruby_llm/chat.rb

@@ -10,8 +10,14 @@ module RubyLLM
       self
     end
 
-    def with_resource(resource, **args)
-      resource.include(self, **args)
+    def with_resource(resource)
+      resource.include(self)
+      self
+    end
+
+    def with_resource_template(resource_template, arguments: {})
+      resource = resource_template.fetch_resource(arguments: arguments)
+      resource.include(self)
       self
     end
 

data/lib/ruby_llm/mcp/capabilities.rb

@@ -3,9 +3,9 @@
 module RubyLLM
   module MCP
     class Capabilities
-      attr_reader :capabilities
+      attr_accessor :capabilities
 
-      def initialize(capabilities)
+      def initialize(capabilities = {})
         @capabilities = capabilities
       end
 
@@ -22,7 +22,7 @@ module RubyLLM
       end
 
       def completion?
-        @capabilities["completion"].present?
+        !@capabilities["completions"].nil?
       end
     end
   end

data/lib/ruby_llm/mcp/client.rb

@@ -9,55 +9,113 @@ module RubyLLM
       attr_reader :name, :config, :transport_type, :transport, :request_timeout, :reverse_proxy_url, :protocol_version,
                   :capabilities
 
-      def initialize(name:, transport_type:, request_timeout: 8000, reverse_proxy_url: nil, config: {})
+      def initialize(name:, transport_type:, start: true, request_timeout: 8000, reverse_proxy_url: nil, config: {}) # rubocop:disable Metrics/ParameterLists
         @name = name
         @config = config
         @protocol_version = PROTOCOL_VERSION
         @headers = config[:headers] || {}
 
         @transport_type = transport_type.to_sym
+        @transport = nil
 
+        @capabilities = nil
+
+        @request_timeout = request_timeout
+        @reverse_proxy_url = reverse_proxy_url
+
+        if start
+          self.start
+        end
+      end
+
+      def request(body, **options)
+        @transport.request(body, **options)
+      end
+
+      def start
         case @transport_type
         when :sse
-          @transport = RubyLLM::MCP::Transport::SSE.new(@config[:url], headers: @headers)
+          @transport = RubyLLM::MCP::Transport::SSE.new(@config[:url], request_timeout: @request_timeout,
+                                                                       headers: @headers)
         when :stdio
-          @transport = RubyLLM::MCP::Transport::Stdio.new(@config[:command], args: @config[:args], env: @config[:env])
+          @transport = RubyLLM::MCP::Transport::Stdio.new(@config[:command], request_timeout: @request_timeout,
+                                                                             args: @config[:args], env: @config[:env])
         when :streamable
-          @transport = RubyLLM::MCP::Transport::Streamable.new(@config[:url], headers: @headers)
+          @transport = RubyLLM::MCP::Transport::Streamable.new(@config[:url], request_timeout: @request_timeout,
+                                                                              headers: @headers)
         else
           raise "Invalid transport type: #{transport_type}"
         end
-        @capabilities = nil
 
-        @request_timeout = request_timeout
-        @reverse_proxy_url = reverse_proxy_url
-
-        initialize_request
+        @initialize_response = initialize_request
+        @capabilities = RubyLLM::MCP::Capabilities.new(@initialize_response["result"]["capabilities"])
         notification_request
       end
 
-      def request(body, **options)
-        @transport.request(body, **options)
+      def stop
+        @transport&.close
+        @transport = nil
+      end
+
+      def restart!
+        stop
+        start
+      end
+
+      def alive?
+        !!@transport&.alive?
       end
 
       def tools(refresh: false)
         @tools = nil if refresh
         @tools ||= fetch_and_create_tools
+        @tools.values
+      end
+
+      def tool(name, refresh: false)
+        @tools = nil if refresh
+        @tools ||= fetch_and_create_tools
+
+        @tools[name]
       end
 
       def resources(refresh: false)
         @resources = nil if refresh
         @resources ||= fetch_and_create_resources
+        @resources.values
+      end
+
+      def resource(name, refresh: false)
+        @resources = nil if refresh
+        @resources ||= fetch_and_create_resources
+
+        @resources[name]
       end
 
       def resource_templates(refresh: false)
         @resource_templates = nil if refresh
-        @resource_templates ||= fetch_and_create_resources(set_as_template: true)
+        @resource_templates ||= fetch_and_create_resource_templates
+        @resource_templates.values
+      end
+
+      def resource_template(name, refresh: false)
+        @resource_templates = nil if refresh
+        @resource_templates ||= fetch_and_create_resource_templates
+
+        @resource_templates[name]
       end
 
       def prompts(refresh: false)
         @prompts = nil if refresh
         @prompts ||= fetch_and_create_prompts
+        @prompts.values
+      end
+
+      def prompt(name, refresh: false)
+        @prompts = nil if refresh
+        @prompts ||= fetch_and_create_prompts
+
+        @prompts[name]
       end
 
       def execute_tool(**args)
@@ -68,8 +126,12 @@ module RubyLLM
         RubyLLM::MCP::Requests::ResourceRead.new(self, **args).call
       end
 
-      def completion(**args)
-        RubyLLM::MCP::Requests::Completion.new(self, **args).call
+      def completion_resource(**args)
+        RubyLLM::MCP::Requests::CompletionResource.new(self, **args).call
+      end
+
+      def completion_prompt(**args)
+        RubyLLM::MCP::Requests::CompletionPrompt.new(self, **args).call
       end
 
       def execute_prompt(**args)
@@ -79,8 +141,7 @@ module RubyLLM
       private
 
       def initialize_request
-        @initialize_response = RubyLLM::MCP::Requests::Initialization.new(self).call
-        @capabilities = RubyLLM::MCP::Capabilities.new(@initialize_response["result"]["capabilities"])
+        RubyLLM::MCP::Requests::Initialization.new(self).call
       end
 
       def notification_request
@@ -107,24 +168,41 @@ module RubyLLM
         tools_response = tool_list_request
         tools_response = tools_response["result"]["tools"]
 
-        @tools = tools_response.map do |tool|
-          RubyLLM::MCP::Tool.new(self, tool)
+        tools = {}
+        tools_response.each do |tool|
+          new_tool = RubyLLM::MCP::Tool.new(self, tool)
+          tools[new_tool.name] = new_tool
         end
+
+        tools
       end
 
-      def fetch_and_create_resources(set_as_template: false)
+      def fetch_and_create_resources
         resources_response = resources_list_request
         resources_response = resources_response["result"]["resources"]
 
         resources = {}
         resources_response.each do |resource|
-          new_resource = RubyLLM::MCP::Resource.new(self, resource, template: set_as_template)
+          new_resource = RubyLLM::MCP::Resource.new(self, resource)
           resources[new_resource.name] = new_resource
         end
 
         resources
       end
 
+      def fetch_and_create_resource_templates
+        resource_templates_response = resource_template_list_request
+        resource_templates_response = resource_templates_response["result"]["resourceTemplates"]
+
+        resource_templates = {}
+        resource_templates_response.each do |resource_template|
+          new_resource_template = RubyLLM::MCP::ResourceTemplate.new(self, resource_template)
+          resource_templates[new_resource_template.name] = new_resource_template
+        end
+
+        resource_templates
+      end
+
       def fetch_and_create_prompts
         prompts_response = prompt_list_request
         prompts_response = prompts_response["result"]["prompts"]

data/lib/ruby_llm/mcp/parameter.rb

@@ -3,7 +3,17 @@
 module RubyLLM
   module MCP
     class Parameter < RubyLLM::Parameter
-      attr_accessor :items, :properties
+      attr_accessor :items, :properties, :enum, :union_type
+
+      def initialize(name, type: "string", desc: nil, required: true, union_type: nil)
+        super(name, type: type.to_sym, desc: desc, required: required)
+        @properties = {}
+        @union_type = union_type
+      end
+
+      def item_type
+        @items["type"].to_sym
+      end
     end
   end
 end

data/lib/ruby_llm/mcp/prompt.rb

@@ -19,10 +19,11 @@ module RubyLLM
         @mcp_client = mcp_client
         @name = name
         @description = description
+        @arguments = parse_arguments(arguments)
+      end
 
-        @arguments = arguments.map do |arg|
-          Argument.new(name: arg["name"], description: arg["description"], required: arg["required"])
-        end
+      def fetch(arguments = {})
+        fetch_prompt_messages(arguments)
       end
 
       def include(chat, arguments: {})
@@ -41,14 +42,14 @@ module RubyLLM
 
       alias say ask
 
-      def arguments_search(argument, value)
+      def complete(argument, value)
         if @mcp_client.capabilities.completion?
-          response = @mcp_client.completion(type: :prompt, name: @name, argument: argument, value: value)
+          response = @mcp_client.completion_prompt(name: @name, argument: argument, value: value)
           response = response.dig("result", "completion")
 
           Completion.new(values: response["values"], total: response["total"], has_more: response["hasMore"])
         else
-          raise Errors::CompletionNotAvailable, "Completion is not available for this MCP server"
+          raise Errors::CompletionNotAvailable.new(message: "Completion is not available for this MCP server")
         end
       end
 
@@ -90,6 +91,16 @@ module RubyLLM
           resource.to_content
         end
       end
+
+      def parse_arguments(arguments)
+        if arguments.nil?
+          []
+        else
+          arguments.map do |arg|
+            Argument.new(name: arg["name"], description: arg["description"], required: arg["required"])
+          end
+        end
+      end
     end
   end
 end

data/lib/ruby_llm/mcp/providers/anthropic/complex_parameter_support.rb

@@ -20,21 +20,32 @@ module RubyLLM
           def build_properties(param)
             case param.type
             when :array
-              {
-                type: param.type,
-                items: { type: param.item_type }
-              }
+              if param.item_type == :object
+                {
+                  type: param.type,
+                  items: { type: param.item_type, properties: clean_parameters(param.properties) }
+                }
+              else
+                {
+                  type: param.type,
+                  items: { type: param.item_type, enum: param.enum }.compact
+                }
+              end
             when :object
               {
                 type: param.type,
                 properties: clean_parameters(param.properties),
                 required: required_parameters(param.properties)
               }
+            when :union
+              {
+                param.union_type => param.properties.map { |property| build_properties(property) }
+              }
             else
               {
                 type: param.type,
                 description: param.description
-              }
+              }.compact
             end
           end
         end
@@ -43,4 +54,12 @@ module RubyLLM
   end
 end
 
-RubyLLM::Providers::Anthropic.extend(RubyLLM::MCP::Providers::Anthropic::ComplexParameterSupport)
+module RubyLLM::Providers::Anthropic::Tools
+  def self.clean_parameters(parameters)
+    RubyLLM::MCP::Providers::Anthropic::ComplexParameterSupport.clean_parameters(parameters)
+  end
+
+  def self.required_parameters(parameters)
+    RubyLLM::MCP::Providers::Anthropic::ComplexParameterSupport.required_parameters(parameters)
+  end
+end

data/lib/ruby_llm/mcp/providers/gemini/complex_parameter_support.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Providers
+      module Gemini
+        module ComplexParameterSupport
+          module_function
+
+          # Format tool parameters for Gemini API
+          def format_parameters(parameters)
+            {
+              type: "OBJECT",
+              properties: parameters.transform_values { |param| build_properties(param) },
+              required: parameters.select { |_, p| p.required }.keys.map(&:to_s)
+            }
+          end
+
+          def build_properties(param)
+            properties = case param.type
+                         when :array
+                           if param.item_type == :object
+                             {
+                               type: param_type_for_gemini(param.type),
+                               items: {
+                                 type: param_type_for_gemini(param.item_type),
+                                 properties: param.properties.transform_values { |value| build_properties(value) }
+                               }
+                             }
+                           else
+                             {
+                               type: param_type_for_gemini(param.type),
+                               items: { type: param_type_for_gemini(param.item_type), enum: param.enum }.compact
+                             }
+                           end
+                         when :object
+                           {
+                             type: param_type_for_gemini(param.type),
+                             properties: param.properties.transform_values { |value| build_properties(value) },
+                             required: param.properties.select { |_, p| p.required }.keys
+                           }
+                         when :union
+                           {
+                             param.union_type => param.properties.map { |properties| build_properties(properties) }
+                           }
+                         else
+                           {
+                             type: param_type_for_gemini(param.type),
+                             description: param.description
+                           }
+                         end
+
+            properties.compact
+          end
+        end
+      end
+    end
+  end
+end
+
+RubyLLM::Providers::Gemini.extend(RubyLLM::MCP::Providers::Gemini::ComplexParameterSupport)