ruby_llm-mcp 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49b1593de3f38afce9d3002a696c7034c2bea82711742ea4bd96a5f155f113e3
-  data.tar.gz: 6fb3c4b87bc82684bb9ef093b70b13eea91e759f5ee44a08b4be543cc45d30d3
+  metadata.gz: 53435b09aee8d32aaede3da3463b8fb782a6d00f6abcabc3b9925f1301cd60c9
+  data.tar.gz: 366cf4d89bef7f79904cd897a7db006ee21a8766c8ff1675e51225576e8c87f4
 SHA512:
-  metadata.gz: 6950867fde16315dba705049ec2d23cc89f3977808d323af20b5bf343b2453228145190e183bfd6350b95df856ae96bf4f60a83145eb0137dad0003454c889d3
-  data.tar.gz: 1ed01c5ec46651c1b420971a429299e60b59707255403f1a167c8832cfde9ee5ba1a5ed00ba1edea8f2bf710006f1d605896781c329f02f5ca056642fe246100
+  metadata.gz: 94754a9b6d8799252bebfb19ccc3dedfc6767fdbe07468960ed3eb56978954d734425f79b366fb92610f4c059970a0607c249b3c6c35bca943fbab7e5a721e77
+  data.tar.gz: d0e757cdc7d064ffc4334b0b1c2a1ebc1feff3dc684d35d28f0b51ce5761a3c80ad427654767fae97da8c8ddacbc182d3d896ef4dedc45ce4d6d8e6297b81fe3

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

@@ -1,145 +1,103 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module RubyLLM
   module MCP
     class Client
-      PROTOCOL_VERSION = "2025-03-26"
-      PV_2024_11_05 = "2024-11-05"
+      extend Forwardable
 
-      attr_reader :name, :config, :transport_type, :transport, :request_timeout, :reverse_proxy_url, :protocol_version,
-                  :capabilities
+      attr_reader :name, :config, :transport_type, :request_timeout
 
-      def initialize(name:, transport_type:, request_timeout: 8000, reverse_proxy_url: nil, config: {})
+      def initialize(name:, transport_type:, start: true, request_timeout: 8000, config: {})
         @name = name
-        @config = config
-        @protocol_version = PROTOCOL_VERSION
-        @headers = config[:headers] || {}
-
+        @config = config.merge(request_timeout: request_timeout)
         @transport_type = transport_type.to_sym
-
-        case @transport_type
-        when :sse
-          @transport = RubyLLM::MCP::Transport::SSE.new(@config[:url], headers: @headers)
-        when :stdio
-          @transport = RubyLLM::MCP::Transport::Stdio.new(@config[:command], args: @config[:args], env: @config[:env])
-        when :streamable
-          @transport = RubyLLM::MCP::Transport::Streamable.new(@config[:url], headers: @headers)
-        else
-          raise "Invalid transport type: #{transport_type}"
-        end
-        @capabilities = nil
-
         @request_timeout = request_timeout
-        @reverse_proxy_url = reverse_proxy_url
 
-        initialize_request
-        notification_request
-      end
+        @coordinator = Coordinator.new(self, transport_type: @transport_type, config: @config)
 
-      def request(body, **options)
-        @transport.request(body, **options)
+        start_transport if start
       end
 
-      def tools(refresh: false)
-        @tools = nil if refresh
-        @tools ||= fetch_and_create_tools
-      end
+      def_delegators :@coordinator, :start_transport, :stop_transport, :restart_transport, :alive?, :capabilities
 
-      def resources(refresh: false)
-        @resources = nil if refresh
-        @resources ||= fetch_and_create_resources
-      end
+      alias start start_transport
+      alias stop stop_transport
+      alias restart! restart_transport
 
-      def resource_templates(refresh: false)
-        @resource_templates = nil if refresh
-        @resource_templates ||= fetch_and_create_resources(set_as_template: true)
-      end
+      def tools(refresh: false)
+        fetch(:tools, refresh) do
+          tools_data = @coordinator.tool_list.dig("result", "tools")
+          build_map(tools_data, MCP::Tool)
+        end
 
-      def prompts(refresh: false)
-        @prompts = nil if refresh
-        @prompts ||= fetch_and_create_prompts
+        @tools.values
       end
 
-      def execute_tool(**args)
-        RubyLLM::MCP::Requests::ToolCall.new(self, **args).call
-      end
+      def tool(name, refresh: false)
+        tools(refresh: refresh)
 
-      def resource_read_request(**args)
-        RubyLLM::MCP::Requests::ResourceRead.new(self, **args).call
+        @tools[name]
       end
 
-      def completion(**args)
-        RubyLLM::MCP::Requests::Completion.new(self, **args).call
-      end
+      def resources(refresh: false)
+        fetch(:resources, refresh) do
+          resources_data = @coordinator.resource_list.dig("result", "resources")
+          build_map(resources_data, MCP::Resource)
+        end
 
-      def execute_prompt(**args)
-        RubyLLM::MCP::Requests::PromptCall.new(self, **args).call
+        @resources.values
       end
 
-      private
-
-      def initialize_request
-        @initialize_response = RubyLLM::MCP::Requests::Initialization.new(self).call
-        @capabilities = RubyLLM::MCP::Capabilities.new(@initialize_response["result"]["capabilities"])
-      end
+      def resource(name, refresh: false)
+        resources(refresh: refresh)
 
-      def notification_request
-        RubyLLM::MCP::Requests::Notification.new(self).call
+        @resources[name]
       end
 
-      def tool_list_request
-        RubyLLM::MCP::Requests::ToolList.new(self).call
-      end
+      def resource_templates(refresh: false)
+        fetch(:resource_templates, refresh) do
+          templates_data = @coordinator.resource_template_list.dig("result", "resourceTemplates")
+          build_map(templates_data, MCP::ResourceTemplate)
+        end
 
-      def resources_list_request
-        RubyLLM::MCP::Requests::ResourceList.new(self).call
+        @resource_templates.values
       end
 
-      def resource_template_list_request
-        RubyLLM::MCP::Requests::ResourceTemplateList.new(self).call
-      end
+      def resource_template(name, refresh: false)
+        resource_templates(refresh: refresh)
 
-      def prompt_list_request
-        RubyLLM::MCP::Requests::PromptList.new(self).call
+        @resource_templates[name]
       end
 
-      def fetch_and_create_tools
-        tools_response = tool_list_request
-        tools_response = tools_response["result"]["tools"]
-
-        @tools = tools_response.map do |tool|
-          RubyLLM::MCP::Tool.new(self, tool)
+      def prompts(refresh: false)
+        fetch(:prompts, refresh) do
+          prompts_data = @coordinator.prompt_list.dig("result", "prompts")
+          build_map(prompts_data, MCP::Prompt)
         end
-      end
 
-      def fetch_and_create_resources(set_as_template: false)
-        resources_response = resources_list_request
-        resources_response = resources_response["result"]["resources"]
+        @prompts.values
+      end
 
-        resources = {}
-        resources_response.each do |resource|
-          new_resource = RubyLLM::MCP::Resource.new(self, resource, template: set_as_template)
-          resources[new_resource.name] = new_resource
-        end
+      def prompt(name, refresh: false)
+        prompts(refresh: refresh)
 
-        resources
+        @prompts[name]
       end
 
-      def fetch_and_create_prompts
-        prompts_response = prompt_list_request
-        prompts_response = prompts_response["result"]["prompts"]
+      private
 
-        prompts = {}
-        prompts_response.each do |prompt|
-          new_prompt = RubyLLM::MCP::Prompt.new(self,
-                                                name: prompt["name"],
-                                                description: prompt["description"],
-                                                arguments: prompt["arguments"])
+      def fetch(cache_key, refresh)
+        instance_variable_set("@#{cache_key}", nil) if refresh
+        instance_variable_get("@#{cache_key}") || instance_variable_set("@#{cache_key}", yield)
+      end
 
-          prompts[new_prompt.name] = new_prompt
+      def build_map(raw_data, klass)
+        raw_data.each_with_object({}) do |item, acc|
+          instance = klass.new(@coordinator, item)
+          acc[instance.name] = instance
         end
-
-        prompts
       end
     end
   end

data/lib/ruby_llm/mcp/coordinator.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    class Coordinator
+      PROTOCOL_VERSION = "2025-03-26"
+      PV_2024_11_05 = "2024-11-05"
+
+      attr_reader :client, :transport_type, :config, :request_timeout, :headers, :transport, :initialize_response,
+                  :capabilities, :protocol_version
+
+      def initialize(client, transport_type:, config: {})
+        @client = client
+        @transport_type = transport_type
+        @config = config
+
+        @protocol_version = PROTOCOL_VERSION
+        @headers = config[:headers] || {}
+
+        @transport = nil
+        @capabilities = nil
+      end
+
+      def request(body, **options)
+        @transport.request(body, **options)
+      end
+
+      def start_transport
+        case @transport_type
+        when :sse
+          @transport = RubyLLM::MCP::Transport::SSE.new(@config[:url],
+                                                        request_timeout: @config[:request_timeout],
+                                                        headers: @headers)
+        when :stdio
+          @transport = RubyLLM::MCP::Transport::Stdio.new(@config[:command],
+                                                          request_timeout: @config[:request_timeout],
+                                                          args: @config[:args],
+                                                          env: @config[:env])
+        when :streamable
+          @transport = RubyLLM::MCP::Transport::Streamable.new(@config[:url],
+                                                               request_timeout: @config[:request_timeout],
+                                                               headers: @headers)
+        else
+          message = "Invalid transport type: :#{transport_type}. Supported types are :sse, :stdio, :streamable"
+          raise Errors::InvalidTransportType.new(message: message)
+        end
+
+        @initialize_response = initialize_request
+        @capabilities = RubyLLM::MCP::Capabilities.new(@initialize_response["result"]["capabilities"])
+        initialize_notification
+      end
+
+      def stop_transport
+        @transport&.close
+        @transport = nil
+      end
+
+      def restart_transport
+        stop_transport
+        start_transport
+      end
+
+      def alive?
+        !!@transport&.alive?
+      end
+
+      def execute_tool(**args)
+        RubyLLM::MCP::Requests::ToolCall.new(self, **args).call
+      end
+
+      def resource_read(**args)
+        RubyLLM::MCP::Requests::ResourceRead.new(self, **args).call
+      end
+
+      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)
+        RubyLLM::MCP::Requests::PromptCall.new(self, **args).call
+      end
+
+      def initialize_request
+        RubyLLM::MCP::Requests::Initialization.new(self).call
+      end
+
+      def initialize_notification
+        RubyLLM::MCP::Requests::InitializeNotification.new(self).call
+      end
+
+      def tool_list
+        RubyLLM::MCP::Requests::ToolList.new(self).call
+      end
+
+      def resource_list
+        RubyLLM::MCP::Requests::ResourceList.new(self).call
+      end
+
+      def resource_template_list
+        RubyLLM::MCP::Requests::ResourceTemplateList.new(self).call
+      end
+
+      def prompt_list
+        RubyLLM::MCP::Requests::PromptList.new(self).call
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/errors.rb

@@ -12,15 +12,17 @@ module RubyLLM
         end
       end
 
+      class CompletionNotAvailable < BaseError; end
+
+      class PromptArgumentError < BaseError; end
+
       class InvalidProtocolVersionError < BaseError; end
 
       class SessionExpiredError < BaseError; end
 
       class TimeoutError < BaseError; end
 
-      class PromptArgumentError < BaseError; end
-
-      class CompletionNotAvailable < BaseError; end
+      class InvalidTransportType < BaseError; end
     end
   end
 end

data/lib/ruby_llm/mcp/parameter.rb

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