Merge pull request patvice#89 from patvice/mcp-offical-sdk-support

Support offical MCP Gem as a Backend

Author: patvice

.github/workflows/cicd.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: ['3.1.3', '3.2', '3.3', '3.4']
+        ruby: ['3.1', '3.2', '3.3', '3.4']
 
     steps:
       - uses: actions/checkout@v4
@@ -39,4 +39,5 @@ jobs:
       - name: Run specs
         run: bundle exec rake
         env:
+          CI: "true"
           GITHUB_ACTIONS: "true"

.gitignore

@@ -18,3 +18,4 @@
 Gemfile.lock
 
 node_modules/
+.vcr_debug.log

Gemfile

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

README.md

@@ -15,12 +15,13 @@ Currently full support for MCP protocol version up to `2025-06-18`.
 
 ## RubyLLM::MCP Features
 
-- 🔌 **Multiple Transport Types**: Streamable HTTP, and STDIO and legacy SSE transports
+- 🎛️ **Dual SDK Support** _(v0.8+)_: Choose between native full-featured implementation or official MCP SDK
+- 🔌 **Multiple Transport Types**: Streamable HTTP, STDIO, and SSE 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
-- 🎛️ **Client Features**: Support for sampling, roots, and elicitation
-- 🎨 **Enhanced Chat Interface**: Extended RubyLLM chat methods for seamless MCP integration
+- 🎨 **Client Features**: Support for sampling, roots, progress tracking, human-in-the-loop, and elicitation
+- 🔧 **Enhanced Chat Interface**: Extended RubyLLM chat methods for seamless MCP integration
 - 🔄 **Multiple Client Management**: Create and manage multiple MCP clients simultaneously for different servers and purposes
 - 📚 **Simple API**: Easy-to-use interface that integrates seamlessly with RubyLLM
 
@@ -48,6 +49,46 @@ Or install it yourself as:
 gem install ruby_llm-mcp
 ```
 
+## Choosing an Adapter
+
+Starting with version 0.8.0, RubyLLM MCP supports multiple SDK adapters:
+
+### RubyLLM Adapter (Default)
+
+The native implementation with full MCP protocol support:
+
+```ruby
+client = RubyLLM::MCP.client(
+  name: "server",
+  adapter: :ruby_llm,  # Default, can be omitted
+  transport_type: :stdio,
+  config: { command: "mcp-server" }
+)
+```
+
+**Features**: All MCP features including SSE transport, sampling, roots, progress tracking, etc.
+
+### MCP SDK Adapter
+
+The official Anthropic-maintained SDK:
+
+```ruby
+# Add to Gemfile
+gem 'mcp', '~> 0.4'
+
+# Use in code
+client = RubyLLM::MCP.client(
+  name: "server",
+  adapter: :mcp_sdk,
+  transport_type: :stdio,
+  config: { command: "mcp-server" }
+)
+```
+
+**Features**: Core MCP features (tools, resources, prompts). No SSE, sampling, or advanced features.
+
+See the [Adapters Guide](https://rubyllm-mcp.com/guides/adapters.html) for detailed comparison.
+
 ## Usage
 
 ### Basic Setup

docs/configuration.md

@@ -75,6 +75,38 @@ RubyLLM::MCP.configure do |config|
 end
 ```
 
+## Adapter Selection
+
+{: .label .label-green }
+0.8+
+
+RubyLLM MCP supports multiple SDK adapters. Choose between the native full-featured implementation or the official MCP SDK.
+
+### Default Adapter
+
+Set the default adapter for all clients:
+
+```ruby
+RubyLLM::MCP.configure do |config|
+  # Options: :ruby_llm (default), :mcp_sdk
+  config.default_adapter = :ruby_llm
+end
+```
+
+### Adapter Options
+
+**`:ruby_llm`** (default)
+- Full MCP protocol implementation
+- All transport types (stdio, SSE, HTTP)
+- Advanced features (sampling, roots, progress tracking, etc.)
+
+**`:mcp_sdk`**
+- Official Anthropic-maintained SDK
+- Core features only (tools, resources, prompts)
+- Limited transport support (stdio, HTTP - no SSE)
+
+See the [Adapters Guide]({% link guides/adapters.md %}) for detailed feature comparison and usage examples.
+
 ## Client Configuration
 
 ### Basic Client Options
@@ -85,6 +117,7 @@ All MCP clients support these common options:
 client = RubyLLM::MCP.client(
   name: "unique-client-name",          # Required: unique identifier
   transport_type: :stdio,              # Required: :stdio, :sse, or :streamable
+  adapter: :ruby_llm,                  # Optional: :ruby_llm (default) or :mcp_sdk
   start: true,                         # Optional: auto-start connection (default: true)
   request_timeout: 8000,               # Optional: timeout in milliseconds (default: 8000)
   config: {                            # Required: transport-specific configuration
@@ -142,9 +175,13 @@ config: {
 
 Best for web-based MCP servers using Server-Sent Events:
 
+{: .warning }
+> SSE transport is only supported with `adapter: :ruby_llm`. The `:mcp_sdk` adapter does not support SSE.
+
 ```ruby
 client = RubyLLM::MCP.client(
   name: "web-server",
+  adapter: :ruby_llm,  # Required for SSE
   transport_type: :sse,
   config: {
     url: "https://api.example.com/mcp/sse",  # Required: SSE endpoint
@@ -371,19 +408,19 @@ The RubyLLM MCP client supports multiple protocol versions. You can access these
 
 ```ruby
 # Latest supported protocol version
-puts RubyLLM::MCP::Protocol.latest_version
+puts RubyLLM::MCP::Native::Protocol.latest_version
 # => "2025-06-18"
 
 # Default version used for negotiation
-puts RubyLLM::MCP::Protocol.default_negotiated_version
+puts RubyLLM::MCP::Native::Protocol.default_negotiated_version
 # => "2025-03-26"
 
 # All supported versions
-puts RubyLLM::MCP::Protocol.supported_versions
+puts RubyLLM::MCP::Native::Protocol.supported_versions
 # => ["2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"]
 
 # Check if a version is supported
-RubyLLM::MCP::Protocol.supported_version?("2025-06-18")
+RubyLLM::MCP::Native::Protocol.supported_version?("2025-06-18")
 # => true
 ```