ruby_llm-mcp 0.0.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 131f358210388bfb593787a010a20459a2fc319f2249ee24594402ee92f78e5d
-  data.tar.gz: dbe0431413c8986bc76987cf748227c8e74bc201cfed23635d487430924d7f0a
+  metadata.gz: f54f8d20c1ebbaddd31672de6715ca3adc92db0187a98b743711f0aff06f373c
+  data.tar.gz: a41e69179703af28db4f7ea5ad27bc1f47c0f6c9eb189cacfb0392cf9d2adebb
 SHA512:
-  metadata.gz: f4d4a86d99b955925457348b7a1ec1916b42ed8afda1549c311f1915fa7a0c106f51350819968679970366f9bdeaa393cf42f239b6709c40558065c2f8328484
-  data.tar.gz: a775771f2574f7a77627a1215bc60aaded76a287da65e13bd7504a0bb61a83f81494cddb5280e7cc960f989daef4149180a5e121d30d5da940488a0805183937
+  metadata.gz: 0a01c76e79c94eb3cf19a422182ae1427fc5e2ac39f32951c18d32ed7be68007c09155f95e23595c4ae864fb1b192fea963193d325abe9e9d5a4406736f61f82
+  data.tar.gz: 25e4f7611a0a0c7c3462c1114daeeed832fc4900a1abccda65253c5a0b459a6ebf7955f2d3ef3473045d6530f220a8ac69f285ec32acca0e921a12a0f4feeebf

data/README.md

@@ -2,16 +2,19 @@
 
 Aiming to make using MCP 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/patvice/ruby_llm). This gem enables Ruby applications to connect to MCP servers and use their tools as part of LLM conversations.
+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.
 
-**Note:** This project is still under development and the API is subject to change. Currently supports the connecting workflow, tool lists and tool execution.
+**Note:** This project is still under development and the API is subject to change.
 
 ## Features
 
-- 🔌 **Multiple Transport Types**: Support for SSE (Server-Sent Events) and stdio transports
+- 🔌 **Multiple Transport Types**: Support for SSE (Server-Sent Events), Streamable HTTP, and stdio 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
 - 🔄 **Real-time Communication**: Efficient bidirectional communication with MCP servers
-- 🎯 **Simple API**: Easy-to-use interface that integrates seamlessly with RubyLLM
+- 🎨 **Enhanced Chat Interface**: Extended RubyLLM chat methods for seamless MCP integration
+- 📚 **Simple API**: Easy-to-use interface that integrates seamlessly with RubyLLM
 
 ## Installation
 
@@ -50,7 +53,7 @@ end
 # Connect to an MCP server via SSE
 client = RubyLLM::MCP.client(
   name: "my-mcp-server",
-  transport_type: "sse",
+  transport_type: :sse,
   config: {
     url: "http://localhost:9292/mcp/sse"
   }
@@ -59,13 +62,23 @@ client = RubyLLM::MCP.client(
 # Or connect via stdio
 client = RubyLLM::MCP.client(
   name: "my-mcp-server",
-  transport_type: "stdio",
+  transport_type: :stdio,
   config: {
     command: "node",
     args: ["path/to/mcp-server.js"],
     env: { "NODE_ENV" => "production" }
   }
 )
+
+# Or connect via streamable HTTP
+client = RubyLLM::MCP.client(
+  name: "my-mcp-server",
+  transport_type: :streamable,
+  config: {
+    url: "http://localhost:8080/mcp",
+    headers: { "Authorization" => "Bearer your-token" }
+  }
+)
 ```
 
 ### Using MCP Tools with RubyLLM
@@ -129,6 +142,142 @@ result = client.execute_tool(
 puts result
 ```
 
+### Working with Resources
+
+MCP servers can provide access to resources - structured data that can be included in conversations. Resources come in two types: normal resources and resource templates.
+
+#### Normal Resources
+
+```ruby
+# Get available resources from the MCP server
+resources = client.resources
+puts "Available resources:"
+resources.each do |name, resource|
+  puts "- #{name}: #{resource.description}"
+end
+
+# Access a specific resource
+file_resource = resources["project_readme"]
+content = file_resource.content
+puts "Resource content: #{content}"
+
+# Include a resource in a chat conversation for reference with an LLM
+chat = RubyLLM.chat(model: "gpt-4")
+chat.with_resource(file_resource)
+
+# Or add a resource directly to the conversation
+file_resource.include(chat)
+
+response = chat.ask("Can you summarize this README file?")
+puts response
+```
+
+#### Resource Templates
+
+Resource templates are parameterized resources that can be dynamically configured:
+
+```ruby
+# Get available resource templates
+templates = client.resource_templates
+log_template = templates["application_logs"]
+
+# Use a template with parameters
+chat = RubyLLM.chat(model: "gpt-4")
+chat.with_resource(log_template, arguments: {
+  date: "2024-01-15",
+  level: "error"
+})
+
+response = chat.ask("What errors occurred on this date?")
+puts response
+
+# You can also get templated content directly
+content = log_template.content(arguments: {
+  date: "2024-01-15",
+  level: "error"
+})
+puts content
+```
+
+#### Resource Argument Completion
+
+For resource templates, you can get suggested values for arguments:
+
+```ruby
+template = client.resource_templates["user_profile"]
+
+# Search for possible values for a specific argument
+suggestions = template.arguments_search("username", "john")
+puts "Suggested usernames:"
+suggestions.arg_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:
+
+```ruby
+# Get available prompts from the MCP server
+prompts = client.prompts
+puts "Available prompts:"
+prompts.each do |name, prompt|
+  puts "- #{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"]
+chat = RubyLLM.chat(model: "gpt-4")
+
+# Method 1: Ask prompt directly
+response = chat.ask_prompt(greeting_prompt, arguments: { name: "Alice", time: "morning" })
+puts response
+
+# Method 2: Add prompt to chat and then ask
+chat.with_prompt(greeting_prompt, arguments: { name: "Alice", time: "morning" })
+response = chat.ask("Continue with the greeting")
+```
+
+### Combining Resources, Prompts, and Tools
+
+You can combine all MCP features for powerful conversations:
+
+```ruby
+client = RubyLLM::MCP.client(
+  name: "development-assistant",
+  transport_type: :sse,
+  config: { url: "http://localhost:9292/mcp/sse" }
+)
+
+chat = RubyLLM.chat(model: "gpt-4")
+
+# Add tools for capabilities
+chat.with_tools(*client.tools)
+
+# Add resources for context
+chat.with_resource(client.resources["project_structure"])
+chat.with_resource(
+  client.resource_templates["recent_commits"],
+  arguments: { days: 7 }
+)
+
+# Add prompts for guidance
+chat.with_prompt(
+  client.prompts["code_review_checklist"],
+  arguments: { focus: "security" }
+)
+
+# Now ask for analysis
+response = chat.ask("Please review the recent commits using the checklist and suggest improvements")
+puts response
+```
+
 ## Transport Types
 
 ### SSE (Server-Sent Events)
@@ -138,13 +287,28 @@ Best for web-based MCP servers or when you need HTTP-based communication:
 ```ruby
 client = RubyLLM::MCP.client(
   name: "web-mcp-server",
-  transport_type: "sse",
+  transport_type: :sse,
   config: {
     url: "https://your-mcp-server.com/mcp/sse"
   }
 )
 ```
 
+### Streamable HTTP
+
+Best for HTTP-based MCP servers that support streaming responses:
+
+```ruby
+client = RubyLLM::MCP.client(
+  name: "streaming-mcp-server",
+  transport_type: :streamable,
+  config: {
+    url: "https://your-mcp-server.com/mcp",
+    headers: { "Authorization" => "Bearer your-token" }
+  }
+)
+```
+
 ### Stdio
 
 Best for local MCP servers or command-line tools:
@@ -152,7 +316,7 @@ Best for local MCP servers or command-line tools:
 ```ruby
 client = RubyLLM::MCP.client(
   name: "local-mcp-server",
-  transport_type: "stdio",
+  transport_type: :stdio,
   config: {
     command: "python",
     args: ["-m", "my_mcp_server"],
@@ -164,10 +328,11 @@ client = RubyLLM::MCP.client(
 ## Configuration Options
 
 - `name`: A unique identifier for your MCP client
-- `transport_type`: Either `:sse` or `:stdio`
+- `transport_type`: Either `:sse`, `:streamable`, or `:stdio`
 - `request_timeout`: Timeout for requests in milliseconds (default: 8000)
 - `config`: Transport-specific configuration
   - For SSE: `{ url: "http://..." }`
+  - For Streamable: `{ url: "http://...", headers: {...} }`
   - For stdio: `{ command: "...", args: [...], env: {...} }`
 
 ## Development

data/lib/ruby_llm/chat.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# This is an override of the RubyLLM::Chat class to convient methods for easy MCP support
+module RubyLLM
+  class Chat
+    def with_resources(*resources, **args)
+      resources.each do |resource|
+        resource.include(self, **args)
+      end
+      self
+    end
+
+    def with_resource(resource, **args)
+      resource.include(self, **args)
+      self
+    end
+
+    def with_prompt(prompt, arguments: {})
+      prompt.include(self, arguments: arguments)
+      self
+    end
+
+    def ask_prompt(prompt, ...)
+      prompt.ask(self, ...)
+    end
+  end
+end

data/lib/ruby_llm/mcp/attachment.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    class Attachment < RubyLLM::Attachment
+      attr_reader :content, :mime_type
+
+      def initialize(content, mime_type) # rubocop:disable Lint/MissingSuper
+        @content = content
+        @mime_type = mime_type
+      end
+
+      def encoded
+        @content
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/capabilities.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    class Capabilities
+      attr_reader :capabilities
+
+      def initialize(capabilities)
+        @capabilities = capabilities
+      end
+
+      def resources_list_changed?
+        @capabilities.dig("resources", "listChanged") || false
+      end
+
+      def resource_subscribe?
+        @capabilities.dig("resources", "subscribe") || false
+      end
+
+      def tools_list_changed?
+        @capabilities.dig("tools", "listChanged") || false
+      end
+
+      def completion?
+        @capabilities["completion"].present?
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/client.rb

@@ -4,22 +4,30 @@ module RubyLLM
   module MCP
     class Client
       PROTOCOL_VERSION = "2025-03-26"
-      attr_reader :name, :config, :transport_type, :transport, :request_timeout, :reverse_proxy_url
+      PV_2024_11_05 = "2024-11-05"
+
+      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: {})
         @name = name
         @config = config
+        @protocol_version = PROTOCOL_VERSION
+        @headers = config[:headers] || {}
+
         @transport_type = transport_type.to_sym
 
-        # TODO: Add streamable HTTP
         case @transport_type
         when :sse
-          @transport = RubyLLM::MCP::Transport::SSE.new(@config[:url])
+          @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
@@ -28,8 +36,8 @@ module RubyLLM
         notification_request
       end
 
-      def request(body, wait_for_response: true)
-        @transport.request(body, wait_for_response: wait_for_response)
+      def request(body, **options)
+        @transport.request(body, **options)
       end
 
       def tools(refresh: false)
@@ -37,31 +45,62 @@ module RubyLLM
         @tools ||= fetch_and_create_tools
       end
 
-      def execute_tool(name:, parameters:)
-        response = execute_tool_request(name: name, parameters: parameters)
-        result = response["result"]
-        # TODO: handle tool error when "isError" is true in result
-        #
-        # TODO: Implement "type": "image" and "type": "resource"
-        result["content"].map { |content| content["text"] }.join("\n")
+      def resources(refresh: false)
+        @resources = nil if refresh
+        @resources ||= fetch_and_create_resources
+      end
+
+      def resource_templates(refresh: false)
+        @resource_templates = nil if refresh
+        @resource_templates ||= fetch_and_create_resources(set_as_template: true)
+      end
+
+      def prompts(refresh: false)
+        @prompts = nil if refresh
+        @prompts ||= fetch_and_create_prompts
+      end
+
+      def execute_tool(**args)
+        RubyLLM::MCP::Requests::ToolCall.new(self, **args).call
+      end
+
+      def resource_read_request(**args)
+        RubyLLM::MCP::Requests::ResourceRead.new(self, **args).call
+      end
+
+      def completion(**args)
+        RubyLLM::MCP::Requests::Completion.new(self, **args).call
+      end
+
+      def execute_prompt(**args)
+        RubyLLM::MCP::Requests::PromptCall.new(self, **args).call
       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 notification_request
-        @notification_response = RubyLLM::MCP::Requests::Notification.new(self).call
+        RubyLLM::MCP::Requests::Notification.new(self).call
       end
 
       def tool_list_request
-        @tool_request = RubyLLM::MCP::Requests::ToolList.new(self).call
+        RubyLLM::MCP::Requests::ToolList.new(self).call
       end
 
-      def execute_tool_request(name:, parameters:)
-        @execute_tool_response = RubyLLM::MCP::Requests::ToolCall.new(self, name: name, parameters: parameters).call
+      def resources_list_request
+        RubyLLM::MCP::Requests::ResourceList.new(self).call
+      end
+
+      def resource_template_list_request
+        RubyLLM::MCP::Requests::ResourceTemplateList.new(self).call
+      end
+
+      def prompt_list_request
+        RubyLLM::MCP::Requests::PromptList.new(self).call
       end
 
       def fetch_and_create_tools
@@ -72,6 +111,36 @@ module RubyLLM
           RubyLLM::MCP::Tool.new(self, tool)
         end
       end
+
+      def fetch_and_create_resources(set_as_template: false)
+        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)
+          resources[new_resource.name] = new_resource
+        end
+
+        resources
+      end
+
+      def fetch_and_create_prompts
+        prompts_response = prompt_list_request
+        prompts_response = prompts_response["result"]["prompts"]
+
+        prompts = {}
+        prompts_response.each do |prompt|
+          new_prompt = RubyLLM::MCP::Prompt.new(self,
+                                                name: prompt["name"],
+                                                description: prompt["description"],
+                                                arguments: prompt["arguments"])
+
+          prompts[new_prompt.name] = new_prompt
+        end
+
+        prompts
+      end
     end
   end
 end

data/lib/ruby_llm/mcp/completion.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    class Completion
+      attr_reader :values, :total, :has_more
+
+      def initialize(values:, total:, has_more:)
+        @values = values
+        @total = total
+        @has_more = has_more
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/content.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    class Content < RubyLLM::Content
+      attr_reader :text, :attachments, :content
+
+      def initialize(text: nil, attachments: nil) # rubocop:disable Lint/MissingSuper
+        @text = text
+        @attachments = attachments || []
+      end
+
+      # This is a workaround to allow the content object to be passed as the tool call
+      # to return audio or image attachments.
+      def to_s
+        attachments.empty? ? text : self
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/errors.rb

@@ -3,7 +3,7 @@
 module RubyLLM
   module MCP
     module Errors
-      class TimeoutError < StandardError
+      class BaseError < StandardError
         attr_reader :message
 
         def initialize(message:)
@@ -11,6 +11,16 @@ module RubyLLM
           super(message)
         end
       end
+
+      class InvalidProtocolVersionError < BaseError; end
+
+      class SessionExpiredError < BaseError; end
+
+      class TimeoutError < BaseError; end
+
+      class PromptArgumentError < BaseError; end
+
+      class CompletionNotAvailable < BaseError; end
     end
   end
 end

data/lib/ruby_llm/mcp/prompt.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    class Prompt
+      class Argument
+        attr_reader :name, :description, :required
+
+        def initialize(name:, description:, required:)
+          @name = name
+          @description = description
+          @required = required
+        end
+      end
+
+      attr_reader :name, :description, :arguments, :mcp_client
+
+      def initialize(mcp_client, name:, description:, arguments:)
+        @mcp_client = mcp_client
+        @name = name
+        @description = description
+
+        @arguments = arguments.map do |arg|
+          Argument.new(name: arg["name"], description: arg["description"], required: arg["required"])
+        end
+      end
+
+      def include(chat, arguments: {})
+        validate_arguments!(arguments)
+        messages = fetch_prompt_messages(arguments)
+
+        messages.each { |message| chat.add_message(message) }
+        chat
+      end
+
+      def ask(chat, arguments: {}, &)
+        include(chat, arguments: arguments)
+
+        chat.complete(&)
+      end
+
+      alias say ask
+
+      def arguments_search(argument, value)
+        if @mcp_client.capabilities.completion?
+          response = @mcp_client.completion(type: :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"
+        end
+      end
+
+      private
+
+      def fetch_prompt_messages(arguments)
+        response = @mcp_client.execute_prompt(
+          name: @name,
+          arguments: arguments
+        )
+
+        response["result"]["messages"].map do |message|
+          content = create_content_for_message(message["content"])
+
+          RubyLLM::Message.new(
+            role: message["role"],
+            content: content
+          )
+        end
+      end
+
+      def validate_arguments!(incoming_arguments)
+        @arguments.each do |arg|
+          if arg.required && incoming_arguments.key?(arg.name)
+            raise Errors::PromptArgumentError, "Argument #{arg.name} is required"
+          end
+        end
+      end
+
+      def create_content_for_message(content)
+        case content["type"]
+        when "text"
+          MCP::Content.new(text: content["text"])
+        when "image", "audio"
+          attachment = MCP::Attachment.new(content["content"], content["mime_type"])
+          MCP::Content.new(text: nil, attachments: [attachment])
+        when "resource"
+          resource = Resource.new(mcp_client, content["resource"])
+          resource.to_content
+        end
+      end
+    end
+  end
+end