ruby_llm_swarm-mcp 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5ee1e3f459d8555cc547963bd6470dfa16e14c0c57e788064e604084dc6909b
+  data.tar.gz: 7b423a5ec9acd5a9554c3a6903bfde6536e30e9c5d5ab9c01aa484cab7bd0fa7
+SHA512:
+  metadata.gz: c144bc4598c9aaff5155f84e188a5b8adb8543caaea84c3d55b244eca0f98f3ed90de465233b2f0887e1231c65e32375b0ea6832fc8ee734693f602e610beada
+  data.tar.gz: 5b7d3e98e3126921e49e34a9b9569dbabf21fa5125e6e5342bcaab25b367da38fb13abd751bc9c267f591501fbbdd0d712e07e1d6d393682d3a6cbdc409c725a

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Patrick Vice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,277 @@
+<img src="/docs/assets/images/rubyllm-mcp-logo-text.svg" alt="RubyLLM" height="120" width="250">
+
+**Aiming to make using MCPs with RubyLLM and Ruby as easy as possible.**
+
+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.
+
+For a more detailed guide, see the [RubyLLM::MCP docs](https://rubyllm-mcp.com/).
+
+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
+
+- 🎛️ **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, 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
+
+## Installation
+
+```bash
+bundle add ruby_llm-mcp
+```
+
+or add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby_llm-mcp'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+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
+
+First, configure your RubyLLM client and create an MCP connection:
+
+```ruby
+require 'ruby_llm/mcp'
+
+# Configure RubyLLM
+RubyLLM.configure do |config|
+  config.openai_api_key = "your-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",
+  transport_type: :stdio,
+  config: {
+    command: "node",
+    args: ["path/to/mcp-server.js"],
+    env: { "NODE_ENV" => "production" }
+  }
+)
+
+# 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" }
+  }
+)
+```
+
+### Using MCP Tools with RubyLLM
+
+```ruby
+# Get available tools from the MCP server
+tools = client.tools
+puts "Available tools:"
+tools.each do |tool|
+  puts "- #{tool.name}: #{tool.description}"
+end
+
+# Create a chat session with MCP tools
+chat = RubyLLM.chat(model: "gpt-4")
+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
+```
+
+### 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"
+  }
+)
+
+puts result
+```
+
+### Working with Resources
+
+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.
+
+#### Normal Resources
+
+```ruby
+# Get available resources from the MCP server
+resources = client.resources
+puts "Available resources:"
+resources.each do |resource|
+  puts "- #{resource.name}: #{resource.description}"
+end
+
+# Access a specific resource by name
+file_resource = client.resource("project_readme")
+content = file_resource.content
+puts "Resource content: #{content}"
+
+# Include a resource in a chat conversation for reference with an LLM
+chat = RubyLLM.chat(model: "gpt-4")
+chat.with_resource(file_resource)
+
+# Or add a resource directly to the conversation
+file_resource.include(chat)
+
+response = chat.ask("Can you summarize this README file?")
+puts response
+```
+
+#### Resource Templates
+
+Resource templates are parameterized resources that can be dynamically configured:
+
+```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
+
+# You can also get templated content directly
+content = log_template.to_content(arguments: {
+  date: "2024-01-15",
+  level: "error"
+})
+puts content
+```
+
+### Working with Prompts
+
+MCP servers can provide predefined prompts that can be used in conversations:
+
+```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
+
+# Use a prompt in a conversation
+greeting_prompt = client.prompt("daily_greeting")
+chat = RubyLLM.chat(model: "gpt-4")
+
+# Method 1: Ask prompt directly
+response = chat.ask_prompt(greeting_prompt, arguments: { name: "Alice", time: "morning" })
+puts response
+
+# 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")
+```
+
+## Development
+
+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.
+
+There are also examples you you can run to verify the gem is working as expected.
+
+```bash
+bundle exec ruby examples/tools/local_mcp.rb
+```
+
+## Contributing
+
+We welcome contributions! Bug reports and pull requests are welcome on GitHub at https://github.com/patvice/ruby_llm-mcp.
+
+## License
+
+Released under the MIT License.

data/lib/generators/ruby_llm/mcp/install/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RubyLLM
+  module MCP
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        namespace "ruby_llm:mcp:install"
+
+        desc "Install RubyLLM MCP configuration files"
+
+        def create_initializer
+          template "initializer.rb", "config/initializers/ruby_llm_mcp.rb"
+        end
+
+        def create_config_file
+          template "mcps.yml", "config/mcps.yml"
+        end
+
+        def display_readme
+          return unless behavior == :invoke
+
+          say "✅ RubyLLM MCP installed!", :green
+          say ""
+          say "Next steps:", :blue
+          say "  1. Configure config/initializers/ruby_llm_mcp.rb (main settings)"
+          say "  2. Define servers in config/mcps.yml"
+          say "  3. Install MCP servers (e.g., npm install @modelcontextprotocol/server-filesystem)"
+          say "  4. Set environment variables for authentication"
+          say ""
+          say "📚 Full docs: https://www.rubyllm-mcp.com/", :cyan
+          say ""
+          say "⭐ Help us improve!", :magenta
+          say "  Report issues or show your support with a GitHub star: https://github.com/patvice/ruby_llm-mcp"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# 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
+
+  # Maximum connections in the pool
+  config.max_connections = Float::INFINITY
+
+  # Pool timeout in seconds
+  config.pool_timeout = 5
+
+  # Path to MCPs configuration file
+  config.config_path = Rails.root.join("config", "mcps.yml")
+
+  # Launch MCPs (:automatic, :manual)
+  config.launch_control = :automatic
+
+  # Configure roots for file system access (RubyLLM adapter only)
+  # config.roots = [
+  #   Rails.root.to_s
+  # ]
+
+  # Configure sampling (RubyLLM adapter only)
+  config.sampling.enabled = false
+
+  # Set preferred model for sampling
+  # config.sampling.preferred_model do
+  #   "claude-sonnet-4"
+  # end
+
+  # Set a guard for sampling
+  # config.sampling.guard do
+  #   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

@@ -0,0 +1,29 @@
+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:
+      - "@modelcontextprotocol/server-filesystem"
+      - "<%%= 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'] %>"