Merge pull request #26 from patvice/errors-and-utilities

v0.4.0 - Errors, MCP utilities and new StreamabeHTTP

Author: patvice

.rubocop.yml

@@ -56,17 +56,19 @@ Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
 
+
 RSpec/DescribedClass:
   Enabled: false
 
+RSpec/ExampleLength:
+  Max: 30
+
+
 RSpec/MultipleExpectations:
   Max: 5
 
 RSpec/MultipleMemoizedHelpers:
   Max: 15
 
-RSpec/ExampleLength:
-  Max: 10
-
 RSpec/NestedGroups:
   Max: 10

Gemfile

@@ -18,6 +18,10 @@ group :development do
   gem "rubocop-rspec", ">= 3.6"
   gem "simplecov"
   gem "vcr"
-end
+  gem "webmock", "~> 3.25"
 
-gem "webmock", "~> 3.25"
+  # For another MCP server test
+  gem "fast-mcp"
+  gem "puma"
+  gem "rack"
+end

README.md

@@ -103,13 +103,39 @@ response = chat.ask("Can you help me search for recent files in my project?")
 puts response
 ```
 
+### Human in the Loop
+
+You can use the `on_human_in_the_loop` callback to allow the human to intervene in the tool call. This is useful for tools that require human input or programic input to verify if the tool should be executed.
+
+For tool calls that have access to do important operations, there SHOULD always be a human in the loop with the ability to deny tool invocations.
+
+```ruby
+client.on_human_in_the_loop do |name, params|
+  name == "add" && params[:a] == 1 && params[:b] == 2
+end
+
+tool = client.tool("add")
+result = tool.execute(a: 1, b: 2)
+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
 
 If you want to support complex parameters, like an array of objects it currently requires a patch to RubyLLM itself. This is planned to be temporary until the RubyLLM is updated.
 
 ```ruby
 RubyLLM::MCP.support_complex_parameters!
-```
+````
 
 ### Streaming Responses with Tool Calls
 
@@ -341,6 +367,14 @@ client.restart!
 client.stop
 ```
 
+### Ping
+
+You can ping the MCP server to check if it is alive:
+
+```ruby
+client.ping # => true or false
+```
+
 ## 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:
@@ -363,6 +397,71 @@ prompt = client.prompt("daily_greeting", refresh: true)
 template = client.resource_template("user_logs", refresh: true)
 ```
 
+## Notifications
+
+MCPs can produce notifications that happen in an async nature outside normal calls to the MCP server.
+
+### Subscribing to a Resource Update
+
+By default, the client will look for any resource cha to resource updates and refresh the resource content when it changes.
+
+### Logging Notifications
+
+MCPs can produce logging notifications for long-running tool operations. Logging notifications allow tools to send real-time updates about their execution status.
+
+```ruby
+client.on_logging do |logging|
+  puts "Logging: #{logging.level} - #{logging.message}"
+end
+
+# Execute a tool that supports logging notifications
+tool = client.tool("long_running_operation")
+result = tool.execute(operation: "data_processing")
+
+# Logging: info - Processing data...
+# Logging: info - Processing data...
+# Logging: warning - Something went wrong but not major...
+```
+
+Different levels of logging are supported:
+
+```ruby
+client.on_logging(RubyLLM::MCP::Logging::WARNING) do |logging|
+  puts "Logging: #{logging.level} - #{logging.message}"
+end
+
+# Execute a tool that supports logging notifications
+tool = client.tool("long_running_operation")
+result = tool.execute(operation: "data_processing")
+
+# Logging: warning - Something went wrong but not major...
+```
+
+### Progress Notifications
+
+MCPs can produce progress notifications for long-running tool operations. Progress notifications allow tools to send real-time updates about their execution status.
+
+**Note:** that we only support progress notifications for tool calls today.
+
+```ruby
+# Set up progress tracking
+client.on_progress do |progress|
+  puts "Progress: #{progress.progress}% - #{progress.message}"
+end
+
+# Execute a tool that supports progress notifications
+tool = client.tool("long_running_operation")
+result = tool.execute(operation: "data_processing")
+
+# Progress 25% - Processing data...
+# Progress 50% - Processing data...
+# Progress 75% - Processing data...
+# Progress 100% - Processing data...
+puts result
+
+# Result: { status: "success", data: "Processed data" }
+```
+
 ## Transport Types
 
 ### SSE (Server-Sent Events)
@@ -411,7 +510,27 @@ client = RubyLLM::MCP.client(
 )
 ```
 
-## Configuration Options
+## RubyLLM::MCP and Client Configuration Options
+
+MCP comes with some common configuration options that can be set on the client.
+
+```ruby
+RubyLLM::MCP.configure do |config|
+  # Set the progress handler
+  config.support_complex_parameters!
+
+  # Set parameters on the built in logger
+  config.log_file = $stdout
+  config.log_level = Logger::ERROR
+
+  # Or add a custom logger
+  config.logger = Logger.new(STDOUT)
+end
+```
+
+### MCP Client Options
+
+MCP client options are set on the client itself.
 
 - `name`: A unique identifier for your MCP client
 - `transport_type`: Either `:sse`, `:streamable`, or `:stdio`

Rakefile

@@ -3,6 +3,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
+Dir.glob("lib/tasks/*.rake").each { |file| load file }
+
 RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"

examples/tools/local_mcp.rb

@@ -11,7 +11,10 @@
   config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
 end
 
-RubyLLM::MCP.support_complex_parameters!
+RubyLLM::MCP.configure do |config|
+  config.support_complex_parameters!
+  config.log_level = Logger::ERROR
+end
 
 # Test with filesystem MCP server using stdio transport
 client = RubyLLM::MCP.client(
@@ -31,17 +34,16 @@
 puts "Connected to filesystem MCP server"
 puts "Available tools:"
 tools = client.tools
-puts tools.map(&:name).join("\n")
+puts tools.map { |tool| "#{tool.display_name}: #{tool.description}" }.join("\n")
 puts "-" * 50
 
-tool = client.tool("firecrawl_crawl")
-chat = RubyLLM.chat(model: "gpt-4.1")
-chat.with_tool(tool)
-
-message = "Can you crawl the website http://www.fullscript.com and tell me what fullscript does?"
+message = "Can you list the files in the current directly and give me a summary of the contents of each file?"
 puts "Asking: #{message}"
 puts "-" * 50
 
+chat = RubyLLM.chat(model: "gpt-4.1")
+chat.with_tools(*tools)
+
 chat.ask(message) do |chunk|
   if chunk.tool_call?
     chunk.tool_calls.each do |key, tool_call|

examples/utilities/progress.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ruby_llm/mcp"
+require "debug"
+require "dotenv"
+
+Dotenv.load
+
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
+end
+
+RubyLLM::MCP.configure do |config|
+  config.support_complex_parameters!
+  config.log_level = Logger::ERROR
+end
+
+# Test with streamable HTTP transport
+client = RubyLLM::MCP.client(
+  name: "streamable_mcp",
+  transport_type: :streamable,
+  config: {
+    url: "http://localhost:3005/mcp"
+  }
+)
+
+puts "Connected to streamable MCP server"
+client.on_progress do |progress|
+  puts "Progress: #{progress.progress}%"
+end
+
+result = client.tool("progress").execute(operation: "processing", steps: 3)
+puts "Result: #{result}"

lib/ruby_llm/mcp.rb

@@ -8,7 +8,10 @@
 loader.inflector.inflect("mcp" => "MCP")
 loader.inflector.inflect("sse" => "SSE")
 loader.inflector.inflect("openai" => "OpenAI")
+loader.inflector.inflect("streamable_http" => "StreamableHTTP")
+
 loader.setup
+loader.eager_load
 
 module RubyLLM
   module MCP
@@ -23,5 +26,20 @@ def support_complex_parameters!
       require_relative "mcp/providers/anthropic/complex_parameter_support"
       require_relative "mcp/providers/gemini/complex_parameter_support"
     end
+
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    alias configuration config
+    module_function :configuration
+
+    def logger
+      config.logger
+    end
   end
 end

lib/ruby_llm/mcp/capabilities.rb

@@ -9,21 +9,41 @@ def initialize(capabilities = {})
         @capabilities = capabilities
       end
 
-      def resources_list_changed?
+      def resources_list?
+        !@capabilities["resources"].nil?
+      end
+
+      def resources_list_changes?
         @capabilities.dig("resources", "listChanged") || false
       end
 
       def resource_subscribe?
         @capabilities.dig("resources", "subscribe") || false
       end
 
-      def tools_list_changed?
+      def tools_list?
+        !@capabilities["tools"].nil?
+      end
+
+      def tools_list_changes?
         @capabilities.dig("tools", "listChanged") || false
       end
 
+      def prompt_list?
+        !@capabilities["prompts"].nil?
+      end
+
+      def prompt_list_changes?
+        @capabilities.dig("prompts", "listChanged") || false
+      end
+
       def completion?
         !@capabilities["completions"].nil?
       end
+
+      def logging?
+        !@capabilities["logging"].nil?
+      end
     end
   end
 end