support ruby version 3.1 again, only run mcp specs on 3.2 >. Improved docs and references to adapters being in +1.0

Author: patvice

.github/workflows/cicd.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: ['3.2', '3.3', '3.4']
+        ruby: ['3.1', '3.2', '3.3', '3.4']
 
     steps:
       - uses: actions/checkout@v4

.rubocop.yml

@@ -6,7 +6,7 @@ plugins:
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.2
+  TargetRubyVersion: 3.1
   Exclude:
     - 'vendor/**/*'
     - 'bin/**/*'

Gemfile

@@ -5,7 +5,9 @@ source "https://rubygems.org"
 gemspec
 
 group :development do
-  gem "mcp", "~> 0.4"
+  if RUBY_VERSION >= "3.2.0"
+    gem "mcp", "~> 0.4"
+  end
 
   # Development dependencies
   gem "activesupport"

docs/guides/adapters.md

@@ -1,18 +1,18 @@
 ---
 layout: default
-title: Adapters
+title: Adapters & Transports
 parent: Guides
-nav_order: 5
-description: "Understanding and using MCP adapters in RubyLLM"
+nav_order: 4
+description: "Understanding MCP adapters, transports, and building custom transport implementations"
 ---
 
-# Adapters
+# Adapters & Transports
 {: .no_toc }
 
 {: .label .label-green }
-0.8+
+1.0+
 
-Starting with version 0.8.0, RubyLLM MCP supports multiple SDK adapters, allowing you to choose between the native full-featured implementation or the official MCP SDK.
+RubyLLM MCP 1.0 provides a mature, stable adapter system with multiple SDK implementations and transport types, giving you complete control over how your application communicates with MCP servers.
 
 ## Table of contents
 {: .no_toc .text-delta }
@@ -24,43 +24,48 @@ Starting with version 0.8.0, RubyLLM MCP supports multiple SDK adapters, allowin
 
 ## Overview
 
-The adapter pattern in RubyLLM MCP allows you to choose which SDK implementation powers your MCP clients. This gives you flexibility to:
+RubyLLM MCP provides two key architectural components:
 
-- Use the native `:ruby_llm` adapter for full MCP feature support build inside the gem
-- Use the official `:mcp_sdk` adapter (still under development, but making great progress)
+**Adapters** - Choose which SDK implementation powers your MCP clients:
+- Use the native `:ruby_llm` adapter for full MCP feature support built inside the gem
+- Use the official `:mcp_sdk` adapter maintained by Anthropic (requires Ruby 3.2+)
 - Mix both adapters in the same application for different servers
 
+**Transports** - Handle the communication layer between your Ruby client and MCP servers:
+- Establish connections
+- Send requests and receive responses
+- Manage the connection lifecycle
+- Handle protocol-specific details
+
 ## Available Adapters
 
 ### RubyLLM Adapter (`:ruby_llm`)
 
 The default, full-featured adapter that implements the complete MCP protocol with extensions.
 
-**When to use:**
-- You need advanced features like sampling, roots, or progress tracking
-- You want SSE transport support
-- You need human-in-the-loop approvals
-- You're using elicitation for interactive workflows
+**Key Features:**
+- ✅ Complete MCP protocol implementation with advanced features (sampling, roots, progress tracking, elicitation)
+- ✅ All transport types supported (stdio, SSE, streamable HTTP)
+- ✅ **Custom transport support** - Register and use your own transport implementations
+- ✅ Ruby 2.7+ compatible
 
-**Advantages:**
-- Complete MCP protocol implementation
-- All transport types supported
-- Additional features beyond core spec
-- Optimized for RubyLLM integration
+**Best for:** Full-featured MCP integrations, custom transport requirements, and advanced protocol features.
 
 ### MCP SDK Adapter (`:mcp_sdk`)
 
 Wraps the official MCP SDK maintained by Anthropic.
 
-**When to use:**
-- You prefer the official Anthropic-maintained implementation
-- You only need core MCP features (tools, resources, prompts)
-- You want to ensure compatibility with the reference implementation
+{: .important }
+> **Ruby 3.2+ Required**
+> The official `mcp` gem requires Ruby 3.2 or higher. If you're using an older Ruby version, use the `:ruby_llm` adapter instead.
+
+**Key Features:**
+- ✅ Official Anthropic-maintained implementation
+- ✅ Core MCP features (tools, resources, prompts)
+- ✅ Basic transports (stdio, HTTP) with custom wrapper support
+- ⚠️ No custom transport registration - requires Ruby 3.2+
 
-**Advantages:**
-- Official Anthropic support
-- Reference implementation compatibility
-- Simpler, focused feature set
+**Best for:** Reference implementation compatibility and core MCP features only.
 
 ## Feature Comparison
 
@@ -98,6 +103,113 @@ Custom transports are implemented by the adapter and are not part of the officia
 | `:streamable_http` | ✅ | Custom |
 | `:sse` | ✅ | Custom |
 
+---
+
+## Built-in Transport Types
+
+### STDIO Transport
+
+Best for local MCP servers that communicate via standard input/output:
+
+```ruby
+client = RubyLLM::MCP.client(
+  name: "local-server",
+  transport_type: :stdio,
+  config: {
+    command: "python",
+    args: ["-m", "my_mcp_server"],
+    env: { "DEBUG" => "1" }
+  }
+)
+```
+
+**Use cases:**
+
+- Local development
+- Command-line MCP servers
+- Subprocess-based servers
+
+### SSE Transport (Server-Sent Events)
+
+Best for web-based MCP servers using HTTP with server-sent events:
+
+```ruby
+client = RubyLLM::MCP.client(
+  name: "web-server",
+  transport_type: :sse,
+  config: {
+    url: "https://api.example.com/mcp/sse",
+    version: :http2, # You can force HTTP/1.1 by setting this to :http1, default will try to setup HTTP/2 connection
+    headers: { "Authorization" => "Bearer token" }
+  }
+)
+```
+
+**Use cases:**
+
+- Web-based MCP services
+- Real-time communication needs
+- HTTP-based infrastructure
+
+### Streamable HTTP Transport
+
+Best for HTTP-based MCP servers that support streaming responses:
+
+```ruby
+client = RubyLLM::MCP.client(
+  name: "streaming-server",
+  transport_type: :streamable,
+  config: {
+    url: "https://api.example.com/mcp",
+    version: :http2, # You can force HTTP/1.1 by setting this to :http1, default will try to setup HTTP/2 connection
+    headers: { "Content-Type" => "application/json" }
+  }
+)
+```
+
+#### OAuth Authentication
+
+{: .new }
+OAuth authentication is available in MCP Protocol 2025-06-18 for Streamable HTTP transport.
+
+For servers requiring OAuth authentication:
+
+```ruby
+client = RubyLLM::MCP.client(
+  name: "oauth-server",
+  transport_type: :streamable,
+  config: {
+    url: "https://api.example.com/mcp",
+    oauth: {
+      issuer: "https://oauth.provider.com",
+      client_id: "your-client-id",
+      client_secret: "your-client-secret",
+      scope: "mcp:read mcp:write"  # Optional
+    }
+  }
+)
+```
+
+**OAuth Configuration:**
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `issuer` | OAuth provider's issuer URL | Yes |
+| `client_id` | OAuth client identifier | Yes |
+| `client_secret` | OAuth client secret | Yes |
+| `scope` | Requested OAuth scopes | No |
+
+The client automatically handles token acquisition, refresh, and authorization headers.
+
+**Use cases:**
+
+- REST API-based MCP servers
+- HTTP-first architectures
+- Cloud-based MCP services
+- Enterprise servers requiring OAuth
+
+---
+
 ## Configuration
 
 ### Global Default Adapter
@@ -163,11 +275,15 @@ mcp_servers:
 
 ### Installation
 
+{: .warning }
+> **Ruby 3.2+ Required**
+> The official `mcp` gem requires Ruby 3.2 or higher. Ensure your Ruby version is compatible before proceeding.
+
 The official MCP SDK is an optional dependency. Add it to your Gemfile when using the `:mcp_sdk` adapter:
 
 ```ruby
-gem 'ruby_llm-mcp', '~> 0.8'
-gem 'mcp', '~> 0.4'  # Required for mcp_sdk adapter
+gem 'ruby_llm-mcp', '~> 1.0'
+gem 'mcp', '~> 0.4'  # Required for mcp_sdk adapter (Ruby 3.2+)
 ```
 
 Then run:
@@ -298,6 +414,77 @@ RubyLLM::MCP.establish_connection do |clients|
 end
 ```
 
+---
+
+## Custom Transports
+
+{: .label .label-blue }
+RubyLLM Adapter Only
+
+The `:ruby_llm` adapter supports registering custom transport implementations, allowing you to extend the gem with your own communication protocols.
+
+### Transport Interface
+
+All transport implementations must implement the following interface:
+
+```ruby
+class CustomTransport
+  # Initialize the transport
+  def initialize(coordinator:, **config)
+    @coordinator = coordinator
+    @config = config
+  end
+
+  # Send a request and optionally wait for response
+  def request(body, add_id: true, wait_for_response: true)
+    # Implementation specific
+  end
+
+  # Check if transport is alive/connected
+  def alive?
+    # Implementation specific
+  end
+
+  # Start the transport connection
+  def start
+    # Implementation specific
+  end
+
+  # Close the transport connection
+  def close
+    # Implementation specific
+  end
+
+  # Set the MCP protocol version
+  def set_protocol_version(version)
+    @protocol_version = version
+  end
+end
+```
+
+### Registering Custom Transports
+
+Once you've created a custom transport, register it with the transport factory:
+
+```ruby
+# Register your custom transport
+RubyLLM::MCP::Native::Transport.register_transport(:websocket, WebSocketTransport)
+RubyLLM::MCP::Native::Transport.register_transport(:redis_pubsub, RedisPubSubTransport)
+
+# Now you can use it with any client using the ruby_llm adapter
+client = RubyLLM::MCP.client(
+  name: "websocket-server",
+  adapter: :ruby_llm,  # Custom transports only work with ruby_llm adapter
+  transport_type: :websocket,
+  config: {
+    url: "ws://localhost:8080/mcp",
+    headers: { "Authorization" => "Bearer token" }
+  }
+)
+```
+
+---
+
 ## Best Practices
 
 ### Choosing an Adapter
@@ -306,22 +493,16 @@ end
 2. **Use `:mcp_sdk`** when you specifically need the official implementation
 3. **Check feature requirements** before choosing an adapter
 4. **Consider transport needs** - SSE requires `:ruby_llm`
+5. **Check Ruby version** - `:mcp_sdk` requires Ruby 3.2+
 
-### Performance Considerations
+### Upgrading from 1.0
 
-- Both adapters have similar performance for core operations
-- `:ruby_llm` has additional overhead for advanced features when enabled
-- `:mcp_sdk` is lighter if you only need core functionality
-
-### Upgrading from 0.7
-
-If you're upgrading from version 0.7:
+If you're upgrading from version 1.0:
 
 1. The default adapter is `:ruby_llm` - no changes needed for existing code
 2. All existing features continue to work as before
 3. Optionally migrate specific clients to `:mcp_sdk` if desired
 
-See the [Upgrading from 0.7 to 0.8]({% link guides/upgrading-0.7-to-0.8.md %}) guide for detailed migration steps.
 
 ## Troubleshooting
 
@@ -347,11 +528,23 @@ If you see "LoadError: cannot load such file -- mcp":
 
 1. Add `gem 'mcp', '~> 0.4'` to your Gemfile
 2. Run `bundle install`
-3. This is only needed when using `adapter: :mcp_sdk`
+3. Ensure you're running Ruby 3.2 or higher
+4. This is only needed when using `adapter: :mcp_sdk`
+
+### Ruby Version Compatibility
+
+If you encounter issues with the `:mcp_sdk` adapter:
+
+1. Check your Ruby version: `ruby -v`
+2. The `mcp` gem requires Ruby 3.2 or higher
+3. Switch to `:ruby_llm` adapter if you're on an older Ruby version
+4. Consider upgrading Ruby if you need the official SDK
 
 ## Next Steps
 
 - **[Configuration]({% link configuration.md %})** - Detailed configuration options
+- **[Getting Started]({% link guides/getting-started.md %})** - Quick start guide
 - **[Tools]({% link server/tools.md %})** - Working with MCP tools
 - **[Resources]({% link server/resources.md %})** - Managing resources
-- **[Upgrading]({% link guides/upgrading-0.7-to-0.8.md %})** - Migration guide
+- **[Notifications]({% link server/notifications.md %})** - Handling real-time updates
+- **[Upgrading from 0.8 to 1.0]({% link guides/upgrading-0.8-to-1.0.md %})** - Migration guide