ruby_llm-mcp 0.8.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e57a30998e3b5b2e2ebc5a2166c1fd0a9501cf73f8bfe1120fedf8956ba3aaf0
-  data.tar.gz: 44ff135d42ca29a24175e33f12dedd24297d86dffe3cb06a640491f300c9fa1b
+  metadata.gz: a516cd88de84929d95dbaaea467780ba499dc8362001a02d00ac0c8672107506
+  data.tar.gz: b852e278be156403a32454a00fa4ad450491d219d6243d9629098680576056d2
 SHA512:
-  metadata.gz: fc2325d76bfbca79d8f99b304b05816a80e4414dc6ea359d92556abeb391019ff02cdd6380fe84f0d2767ad82632c434424b2fdee77c5ff2d1cc78dce879a2ac
-  data.tar.gz: ba9b9d1bff3f0ab545a22ae27075a5b6d63a40393c3da5daa437c25340019622b258e4f621cc08f3f8d90565bd720c234a55d502df568b5e5bc6abcce5b4662e
+  metadata.gz: a63c3650a2db47782d7db7eae32feec794302e63f2fe9967a584d1253fb42de75dfe004c87ba8758e9c09d06be856dc0d645183d0fc5b80e18a0cb294c5cda68
+  data.tar.gz: a89b6bffe3d03b95a9b2734c39f8b6152c7a07f945a9fe70f6eb3f3cb5423939a4fa7e16de2db94e5b01acdc82fde6b0d0d7eadcf4ce94ebd91a6654fa65565f

data/README.md

@@ -1,235 +1,217 @@
-<img src="/docs/assets/images/rubyllm-mcp-logo-text.svg" alt="RubyLLM" height="120" width="250">
+<div align="center">
 
-**Aiming to make using MCPs with RubyLLM and Ruby as easy as possible.**
+<img src="docs/assets/images/rubyllm-mcp-logo-text.svg#gh-light-mode-only" alt="RubyLLM::MCP" height="120" width="250">
+<img src="docs/assets/images/rubyllm-mcp-logo-text-white.svg#gh-dark-mode-only" alt="RubyLLM::MCP" height="120" width="250">
 
-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.
+<strong>MCP for Ruby and RubyLLM, as easy as possible.</strong>
 
-For a more detailed guide, see the [RubyLLM::MCP docs](https://rubyllm-mcp.com/).
+[![Gem Version](https://badge.fury.io/rb/ruby_llm-mcp.svg)](https://badge.fury.io/rb/ruby_llm-mcp)
+[![Gem Downloads](https://img.shields.io/gem/dt/ruby_llm-mcp)](https://rubygems.org/gems/ruby_llm-mcp)
 
-Currently full support for MCP protocol version up to `2025-06-18`.
-
-<div class="badge-container">
-  <a href="https://badge.fury.io/rb/ruby_llm-mcp"><img src="https://badge.fury.io/rb/ruby_llm-mcp.svg" alt="Gem Version" /></a>
-  <a href="https://rubygems.org/gems/ruby_llm-mcp"><img alt="Gem Downloads" src="https://img.shields.io/gem/dt/ruby_llm-mcp"></a>
 </div>
 
-## RubyLLM::MCP Features
-
-- 🔌 **Multiple Transport Types**: Streamable HTTP, and STDIO and legacy 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
-- 🔄 **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
+RubyLLM::MCP is a Ruby client for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), built to work cleanly with [RubyLLM](https://github.com/crmne/ruby_llm). Aiming to be completely spec compliant.
 
-## Installation
+Use MCP tools, resources, and prompts from your RubyLLM chats over `stdio`, streamable HTTP, or SSE.
 
-```bash
-bundle add ruby_llm-mcp
-```
+**Protocol support:** Fully supports MCP spec `2025-06-18` (stable), with draft spec `2026-01-26` available.
 
-or add this line to your application's Gemfile:
+## RubyLLM::MCP Out of the Box
 
-```ruby
-gem 'ruby_llm-mcp'
-```
+Our goal is to be able to plug MCP into Ruby/RubyLLM apps as easily as possible.
 
-And then execute:
+RubyLLM::MCP gives you that:
 
-```bash
-bundle install
-```
+- Ruby-first API for using MCP tools, resources, and prompts directly in RubyLLM chat workflows
+- Stable protocol track by default (`2025-06-18`), with opt-in draft track (`2026-01-26`)
+- Built-in notification and response handlers for real-time and interactive workflows
+- MCP OAuth 2.1 authentication support (PKCE, dynamic registration, discovery, and automatic token refresh)
+- OAuth setup paths for Rails apps (per-user connections) and browser-based CLI flows
+- Straightforward integration for any Ruby app, background job, or Rails project using RubyLLM
 
-Or install it yourself as:
-
-```bash
-gem install ruby_llm-mcp
-```
-
-## Usage
-
-### Basic Setup
-
-First, configure your RubyLLM client and create an MCP connection:
+## Show me the code
 
 ```ruby
-require 'ruby_llm/mcp'
+# Basic setup
+require "ruby_llm/mcp"
 
-# Configure RubyLLM
 RubyLLM.configure do |config|
-  config.openai_api_key = "your-api-key"
+  config.openai_api_key = ENV.fetch("OPENAI_API_KEY")
 end
 
-# Connect to an MCP server via SSE
 client = RubyLLM::MCP.client(
-  name: "my-mcp-server",
-  transport_type: :sse,
-  config: {
-    url: "http://localhost:9292/mcp/sse"
-  }
-)
-
-# Or connect via stdio
-client = RubyLLM::MCP.client(
-  name: "my-mcp-server",
+  name: "filesystem",
   transport_type: :stdio,
   config: {
-    command: "node",
-    args: ["path/to/mcp-server.js"],
-    env: { "NODE_ENV" => "production" }
+    command: "bunx",
+    args: ["@modelcontextprotocol/server-filesystem", Dir.pwd]
   }
 )
 
-# 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" }
+chat = RubyLLM.chat(model: "gpt-4.1-mini")
+chat.with_tools(*client.tools)
+
+puts chat.ask("Find Ruby files modified today and summarize what changed.")
+```
+
+```ruby
+# Resources
+resource = client.resource("release_notes")
+chat = RubyLLM.chat(model: "gpt-4.1-mini")
+chat.with_resource(resource)
+
+puts chat.ask("Summarize release notes for the team in 5 bullet points.")
+```
+
+```ruby
+# Prompts
+prompt = client.prompt("code_review")
+chat = RubyLLM.chat(model: "gpt-4.1-mini")
+
+response = chat.ask_prompt(
+  prompt,
+  arguments: {
+    language: "ruby",
+    focus: "security"
   }
 )
-```
 
-### Using MCP Tools with RubyLLM
+puts response
+```
 
 ```ruby
-# Get available tools from the MCP server
-tools = client.tools
-puts "Available tools:"
-tools.each do |tool|
-  puts "- #{tool.name}: #{tool.description}"
+# Handlers (response + notifications)
+client.on_progress do |progress|
+  puts "Progress: #{progress.progress}% - #{progress.message}"
 end
 
-# Create a chat session with MCP tools
-chat = RubyLLM.chat(model: "gpt-4")
+client.on_logging do |logging|
+  puts "[#{logging.level}] #{logging.message}"
+end
+
+chat = RubyLLM.chat(model: "gpt-4.1-mini")
 chat.with_tools(*client.tools)
 
-# Ask a question that will use the MCP tools
-response = chat.ask("Can you help me search for recent files in my project?")
-puts response
+chat.ask("Run a repository scan and summarize risks.") do |chunk|
+  print chunk.content
+end
 ```
 
-### Manual Tool Execution
-
-You can also execute MCP tools directly:
-
 ```ruby
-# Tools Execution
-tool = client.tool("search_files")
-
-# Execute a specific tool
-result = tool.execute(
-  name: "search_files",
-  parameters: {
-    query: "*.rb",
-    directory: "/path/to/search"
+# OAuth setup (Rails and CLI)
+# Rails: per-user OAuth client (after running rails generate ruby_llm:mcp:oauth:install User)
+client = current_user.mcp_client
+chat = RubyLLM.chat(model: "gpt-4.1-mini")
+chat.with_tools(*client.tools)
+puts chat.ask("What changed in my connected repos this week?")
+
+# CLI: browser-based OAuth flow
+cli_client = RubyLLM::MCP.client(
+  name: "oauth-server",
+  transport_type: :streamable,
+  start: false,
+  config: {
+    url: ENV.fetch("MCP_SERVER_URL"),
+    oauth: { scope: "mcp:read mcp:write" }
   }
 )
 
-puts result
+cli_client.oauth(type: :browser).authenticate
+cli_client.start
+puts RubyLLM.chat(model: "gpt-4.1-mini").with_tools(*cli_client.tools).ask("List my open tasks.")
+cli_client.stop
 ```
 
-### Working with Resources
+## Features
+
+- **Tools:** Convert MCP tools into RubyLLM-compatible tools
+- **Resources:** Work with resources and resource templates in chat context
+- **Prompts:** Execute server prompts with typed arguments
+- **Transports:** `:stdio`, `:streamable`, and `:sse`
+- **Client capabilities:** Sampling, roots, progress tracking, and elicitation
+- **Handlers:** Built-in notification and response handlers for real-time and interactive workflows
+- **MCP Authentication:** OAuth 2.1 support with PKCE, dynamic registration, discovery, and automatic token refresh
+- **OAuth setup paths:** Rails per-user OAuth setup and browser-based OAuth for CLI tools
+- **Extensions:** Global/per-client extension negotiation, including MCP Apps
+- **Multi-client support:** Manage multiple MCP servers in one workflow
+- **Protocol control:** Stable default with explicit draft opt-in
+- **Adapters:** Native `:ruby_llm` adapter (full feature set) and optional `:mcp_sdk`
 
-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.
+## Installation
 
-#### Normal Resources
+Add to your Gemfile:
 
 ```ruby
-# Get available resources from the MCP server
-resources = client.resources
-puts "Available resources:"
-resources.each do |resource|
-  puts "- #{resource.name}: #{resource.description}"
-end
+gem "ruby_llm-mcp"
+```
 
-# Access a specific resource by name
-file_resource = client.resource("project_readme")
-content = file_resource.content
-puts "Resource content: #{content}"
+Then run:
 
-# Include a resource in a chat conversation for reference with an LLM
-chat = RubyLLM.chat(model: "gpt-4")
-chat.with_resource(file_resource)
+```bash
+bundle install
+```
 
-# Or add a resource directly to the conversation
-file_resource.include(chat)
+If you want the official SDK adapter, also add:
 
-response = chat.ask("Can you summarize this README file?")
-puts response
+```ruby
+gem "mcp", "~> 0.7"
 ```
 
-#### Resource Templates
+## Rails
 
-Resource templates are parameterized resources that can be dynamically configured:
+```bash
+rails generate ruby_llm:mcp:install
+```
 
-```ruby
-# Get available resource templates
-templates = client.resource_templates
-log_template = client.resource_template("application_logs")
-
-# Use a template with parameters
-chat = RubyLLM.chat(model: "gpt-4")
-chat.with_resource_template(log_template, arguments: {
-  date: "2024-01-15",
-  level: "error"
-})
-
-response = chat.ask("What errors occurred on this date?")
-puts response
+For OAuth-based user connections:
 
-# You can also get templated content directly
-content = log_template.to_content(arguments: {
-  date: "2024-01-15",
-  level: "error"
-})
-puts content
+```bash
+rails generate ruby_llm:mcp:oauth:install User
 ```
 
-### Working with Prompts
-
-MCP servers can provide predefined prompts that can be used in conversations:
+OAuth quick example:
 
 ```ruby
-# Get available prompts from the MCP server
-prompts = client.prompts
-puts "Available prompts:"
-prompts.each do |prompt|
-  puts "- #{prompt.name}: #{prompt.description}"
-  prompt.arguments.each do |arg|
-    puts "  - #{arg.name}: #{arg.description} (required: #{arg.required})"
-  end
-end
+client = RubyLLM::MCP.client(
+  name: "oauth-server",
+  transport_type: :streamable,
+  start: false,
+  config: {
+    url: ENV.fetch("MCP_SERVER_URL"),
+    oauth: { scope: "mcp:read mcp:write" }
+  }
+)
 
-# Use a prompt in a conversation
-greeting_prompt = client.prompt("daily_greeting")
-chat = RubyLLM.chat(model: "gpt-4")
+client.oauth(type: :browser).authenticate
+client.start
 
-# Method 1: Ask prompt directly
-response = chat.ask_prompt(greeting_prompt, arguments: { name: "Alice", time: "morning" })
-puts response
+chat = RubyLLM.chat(model: "gpt-4.1-mini")
+chat.with_tools(*client.tools)
+puts chat.ask("What should I prioritize today?")
 
-# 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")
+client.stop
 ```
 
-## Development
+Then use explicit connection blocks in jobs/controllers/services:
 
-After checking out the repo, run `bundle` to install dependencies. Then, run `bundle exec rake` to run the tests. Tests currently use `bun` to run test MCP servers You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+RubyLLM::MCP.establish_connection do |clients|
+  chat = RubyLLM.chat(model: "gpt-4.1-mini")
+  chat.with_tools(*clients.tools)
+  chat.ask("Analyze this pull request and list risks.")
+end
+```
 
-There are also examples you you can run to verify the gem is working as expected.
+## Documentation
 
-```bash
-bundle exec ruby examples/tools/local_mcp.rb
-```
+- [rubyllm-mcp.com](https://rubyllm-mcp.com/)
+- [Getting Started](https://rubyllm-mcp.com/getting-started/getting-started.html)
+- [Rails Integration](https://rubyllm-mcp.com/guides/rails-integration.html)
+- [Adapters and transports](https://rubyllm-mcp.com/guides/adapters.html)
 
 ## Contributing
 
-We welcome contributions! Bug reports and pull requests are welcome on GitHub at https://github.com/patvice/ruby_llm-mcp.
+Issues and pull requests are welcome at [patvice/ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp).
 
 ## License
 

data/lib/generators/ruby_llm/mcp/install/templates/initializer.rb

@@ -2,6 +2,11 @@
 
 # Configure RubyLLM MCP
 RubyLLM::MCP.configure do |config|
+  # Default SDK adapter to use (:ruby_llm or :mcp_sdk)
+  # - :ruby_llm: Full-featured, supports all MCP features + extensions
+  # - :mcp_sdk: Official SDK, limited features but maintained by Anthropic
+  config.default_adapter = :ruby_llm
+
   # Request timeout in milliseconds
   config.request_timeout = 8000
 
@@ -17,23 +22,35 @@ RubyLLM::MCP.configure do |config|
   # Launch MCPs (:automatic, :manual)
   config.launch_control = :automatic
 
-  # Configure roots for file system access
+  # Configure roots for file system access (RubyLLM adapter only)
   # config.roots = [
   #   Rails.root.to_s
   # ]
 
-  # Configure sampling (optional)
+  # Configure sampling (RubyLLM adapter only)
   config.sampling.enabled = false
 
   # Set preferred model for sampling
   # config.sampling.preferred_model do
-  #   # Return the preferred model name
   #   "claude-sonnet-4"
   # end
 
   # Set a guard for sampling
   # config.sampling.guard do
-  #   # Return true to enable sampling, false to disable
   #   Rails.env.development?
   # end
+
+  # Event handlers (RubyLLM adapter only)
+  # config.on_progress do |progress_token, progress, total|
+  #   # Handle progress updates
+  # end
+
+  # config.on_human_in_the_loop do |tool_name, arguments|
+  #   # Return true to allow, false to deny
+  #   true
+  # end
+
+  # config.on_logging do |level, logger_name, data|
+  #   # Handle logging from MCP servers
+  # end
 end

data/lib/generators/ruby_llm/mcp/install/templates/mcps.yml

@@ -1,5 +1,9 @@
 mcp_servers:
   filesystem:
+    # SDK adapter to use (optional, defaults to config.default_adapter)
+    # Options: ruby_llm, mcp_sdk
+    # adapter: ruby_llm
+
     transport_type: stdio
     command: npx
     args:
@@ -7,3 +11,19 @@ mcp_servers:
       - "<%%= Rails.root %>"
     env: {}
     with_prefix: true
+
+  # Example with MCP SDK (official)
+  # weather:
+  #   adapter: mcp_sdk
+  #   transport_type: http
+  #   url: "https://api.example.com/mcp"
+  #   headers:
+  #     Authorization: "Bearer <%%= ENV['WEATHER_API_KEY'] %>"
+
+  # Example with SSE (RubyLLM adapter only)
+  # notifications:
+  #   adapter: ruby_llm
+  #   transport_type: sse
+  #   url: "https://api.example.com/mcp/sse"
+  #   headers:
+  #     Authorization: "Bearer <%%= ENV['API_KEY'] %>"