v0.5.0

Rails Integration, Module Interface improvements and Transport Layer Refactoring

This release adds comprehensive Rails support to the RubyLLM MCP library and refactors the transport layer for better extensibility.

✨ What's New

Client Feature Support

This is the first piece of MCP client functionality that can be exposed to MCP servers. For both Root and Sampling support, the RubyLLM::MCP client must be configured before clients objects are created. This ensuring that people are opting into this functionality before we would expose anything to a remote server.

Roots

Roots give access to underlaying file system information. Due to the nature of the MCP spec being limited on what roots are used for and what could be done with them, our implementation of roots will start off very lite.

When a root is added into the MCP configuration we will expose the the MCP server that roots is a capability we support. We then will support adding and remove roots (with a list_change notification being fired to the server) from the client dynamic lifecycle the lifecycle of a client.

RubyLLM::MCP.config do |config|
  config.roots = ["to/a/path", Rails.root]
end

client = RubyLLM::MCP::Client.new(...)

client.roots.paths #  ["to/a/path", #<Pathname:/to/rails/root/path>]

client.roots.add("new/path") # notifications/roots/list_changed is fired
client.roots.paths # ["to/a/path",  #<Pathname:/to/rails/root/path>, "new/path"]

client.roots.remove("to/a/path") # notifications/roots/list_changed is fired
client.roots.paths # [#<Pathname:/to/rails/root/path>, "new/path"]

Sampling

Sampling allows for an MCP server to offload requests to an LLM to be made from the MCP client either than from the server. As this allows MCP server to optionally use an LLM connection, we are ensuring that client explicitly opt into this functionality before we would expose access.

We included a sub config object called sampling to allow for sampling specific configuration.

RubyLLM::MCP.configure do |config|
  config.sampling.enabled = true
  config.sampling.preferred_model = "gpt-4.1"
  
  # or
  config.sampling.preferred_model do |model_preferences|
    model_preferences.hints.first
  end

  config.sampling.guard do |sample|
    sample.message.include("Hello")
  end
end

Clients will then response to all incoming sample requests with gpt-4.1 and only approve a sample message if it contains the word "Hello".

Rails Integration

• Rails Railtie: Automatic MCP client lifecycle management

  • Starts all configured MCP clients when Rails initializes (configurable)
  • Gracefully shuts down clients when Rails application exits
  • Automatic generator registration

• Rails Generator: Easy setup with rails generate ruby_llm:mcp:install

  • Creates config/initializers/ruby_llm_mcp.rb with comprehensive configuration
  • Generates config/mcps.yml with sample MCP server configuration
  • Includes setup instructions and usage examples

MCP module interface

• Added some support methods to MCP to make it easy to work with multiple MCPs.
• Added a global tools method to more easily work with tools across multiple MCPs.

Transport Layer Improvements

• New Transport Factory Pattern: Centralized transport type registration and management
• Better Process Management: Improved handling of transport instances across process boundaries
• Enhanced Configuration: Support for YAML configuration files with ERB templating

Configuration Enhancements

• YAML Support: Use .yml files instead of JSON for more readable configuration
• Rails-Specific Options:
  • launch_control: :automatic or :manual MCP client management
  • config_path: Rails-aware configuration file paths
• Template Support: ERB processing in configuration files (e.g., <%= Rails.root %>)

Pagination Support

• MCPs can optionally add pagination for any list requests. We now will automatically paginate lists to get the fully setup from a given MCP.

Contributions

• Changing Zeitwerk setup by @patvice in #32
• Client Features: Support for Roots and Sampling by @patvice in #30
• List Pagination Support by @patvice in #33
• Improvements to CI and Github actions by @patvice in #35
• Enable external client management by @MadBomber in #38
• Fix nil handling in item_type method and add parameter specs by @MadBomber in #37
• Better MCP module interface rails support by @patvice in #39

New Contributors

• @MadBomber made their first contribution in #38

Full Changelog: v0.4.1...v0.5.0

v0.4.1

What's Changed

• Hot fix to remove eager_load by @patvice in #31

Zeitwerk was causing a loading error when the gem was being required, however this was only present when the gem was being required not in spec mode where files are getting required slightly differently.

Full Changelog: v0.4.0...v0.4.1

V0.4.0

Enhanced Error Handling, Utilities, and StreamableHTTP Transport Improvements

This release brings significant improvements to error handling, introduces new utility features, and includes a complete rewrite of the streamable HTTP transport with migration from Faraday to HTTPX, and prep for client side responses.

✨ New Features

Notification Support

• MCP Notification communication with MCP servers. All defined notifications in the MPC spec are are now supported
• Resource Subscriptions support marking resources dirty and refetching content when MPC pass a resource updated notification
• Support list change notifications tools, resources and prompts list will be refetched when MCP send a notification that they have changed
• Message Notification logging events can down be feed from the server to the client to give debug or general information
• Progress Notification progress notification and progress hooks are now available to update on progress on tool execution timing

Enhanced Error Handling & Utilities

• Improved logging capabilities with configurable log levels support server fed logs
• Progress tracking utilities for long-running operations, allowing for MCPs to update progress
• Human-in-the-loop support with callback mechanisms for tool execution approval, allowing for some user feedback or programmatic controller over what tools & parameters can be called
• • Comprehensive error management system with detailed error types and context, using all standard error types defined in the MPC spec
• Ping is now supported bidirectionally, allowing for pinging server and clinic responding to pings.

Streamable HTTP Transport Rewrite

• Complete rewrite of the StreamableHTTP transport class
• Enhanced SSE (Server-Sent Events) support with:
  • Automatic reconnection with exponential backoff
  • Better error handling and recovery
  • Improved connection lifecycle management
  • Thread-safe operations with proper cleanup
• Bidirectional streaming capabilities for real-time communication, starting with ping support as the first bidirectional action
• Session management with proper termination handling, including deletion on close

🔧 Breaking Changes

HTTP Client Migration: Faraday → HTTPX

• Migrated from Faraday to HTTPX for all HTTP transport operations
• Reason: While Faraday is used by RubyLLM, it has critical issues with reading text/event-stream responses, which are essential for MCP's Streamable and Server-Sent Events (SSE) transports. Faraday (while works great in RubyLLM) has some issues with reason text/event_streams from post method requests.
• HTTPX provides better streaming support and more reliable handling of SSE connections and modern http handing behaviours

Error Handling

• Improved error handing returns cleaning up what errors can be send from all transports and standardized behaviours. New errors (in a more structured format) will now fire on transport errors.

Reduced Client surface area

• Reduced public surface area for cleaner API design. Cliented used to include methods that were ment for internal use only as public methods to allow downstream classes to access transport.
• New Coordinator class an internal class that will manage transport and server interactions
• Centralized request/response handling across all transport types

🛠️ Improvements

Transport Layer Enhancements

• Improved SSE connection stability with better error handling
• Enhanced timeout management across all transport types
• Better connection pooling and resource cleanup
• Thread-safe operations with proper synchronization

🧪 Testing

• 95+ new test cases covering error scenarios, edge cases, and transport reliability
• Cross-transport testing ensuring consistency across SSE, stdio, and streamable transports
• Provider compatibility testing with major LLM providers
• Stress testing for connection management and recovery

More testing

• Comprehensive test coverage for all transport types (SSE, stdio, streamable)
• Cross-provider testing for with_prompt with Anthropic Claude, OpenAI GPT-4, Gemini, and DeepSeek for prompts
• Additional SSE test server Added test server for fast-mcp being the currently most popular MCP server in ruby

🔄 Migration Guide

For users upgrading from v0.3.x:

1. No breaking API changes for standard usage
2. Error handling may surface different exception types (more specific)
3. Logging output format has been enhanced
4. Transport configuration remains the same

What's Changed

• include description in all complex types by @josh-m-sharpe in #24
• v0.4.0 - Errors, MCP utilities and new StreamabeHTTP by @patvice in #26
• Changed how sse server is spun up in specs in improve consistency by @patvice in #27

New Contributors

• @josh-m-sharpe made their first contribution in #24

Full Changelog: v0.3.1...v0.4.0

v0.3.1

What's Changed

• fix(sse): Add request_timeout support to SSE transport initializer by @scald in #22
• Fixed enum setting bug and added default value by @patvice in #23
• Coordinator refactor by @patvice in #19

New Contributors

• @scald made their first contribution in #22

Full Changelog: v0.3.0...v0.3.1

Version 0.3.0

RubyLLM::MCP V0.3.0

This includes a large spec refactor, with some solved bugs found from the specs as well as an update to the readme.

Feature Adds

• with_resource_template now a top level method on RubyLLM chat object. Allowing for better resource template use, that will attach the returning resource as part of the messages going to the LLM.
• Support for union types in function complex parameters
• Better client management methods available (start, stop and alive?) to be able to check on longer running clients

Better Specs

• Specs are not completely redone to perform more end to end pieces of functionality. Specs today focus on Streamable and STDIO. FastRuby test setup to be added shortly to test SSE directly
• Specs now test against the official typescript MCP SDK. There is a server in specs/fixtures/typescript-mcp. Future plans the ruby official MCP SDK once it becomes version 1.0.
• Specs also test the MCP interfaces end to end using VCR and going directly
• Github action now going to use a test matrix against all supported version of Ruby (from 3.1.3 - 3.4.x)

Improvements

• Better resource template support, now managed in it's own class outside of resource.
• Competition API calls broken out on there own to better support there usecases

Bugs

• Timeout config was not being respected with has been corrected
• Anthropic complex parameter support was not working correctly and has not been corrected
• Stdio Env was not formatted corrected when passed into Open3

What's Changed

• Bump to v0.3 - Complete Spec Refactor! by @patvice in #18

Full Changelog: v0.2.1...v0.3.0