ruby_llm-mcp 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b40509c28a60e1ae01ed83d47503d76f30d5f3bf9852ef4c30ca033d6ea149bc
-  data.tar.gz: f3393dc6423c6bcda143cb6b22e7042434ca1d7d385cc2adf97ba925efff6912
+  metadata.gz: e57a30998e3b5b2e2ebc5a2166c1fd0a9501cf73f8bfe1120fedf8956ba3aaf0
+  data.tar.gz: 44ff135d42ca29a24175e33f12dedd24297d86dffe3cb06a640491f300c9fa1b
 SHA512:
-  metadata.gz: 86e6dd3009df055ad4fa6d088b6b1d9fb87cc8c6244b1436e4ef96ef1cbd822c321c779bd518557544a6c457d19270bf1a57c874cb6d80543141ecac7c370754
-  data.tar.gz: 5a76f9b2aaf2d3db38d97c9d66341458e25f3cdd89fdaf1768095a1bba20257154e128c9b60245f1f09f3e6f09b967daacd70748008c4edf90c3e836546bd6d6
+  metadata.gz: fc2325d76bfbca79d8f99b304b05816a80e4414dc6ea359d92556abeb391019ff02cdd6380fe84f0d2767ad82632c434424b2fdee77c5ff2d1cc78dce879a2ac
+  data.tar.gz: ba9b9d1bff3f0ab545a22ae27075a5b6d63a40393c3da5daa437c25340019622b258e4f621cc08f3f8d90565bd720c234a55d502df568b5e5bc6abcce5b4662e

data/lib/generators/ruby_llm/mcp/{install_generator.rb → install/install_generator.rb}

@@ -2,12 +2,14 @@
 
 require "rails/generators/base"
 
-module RubyLlm
-  module Mcp
+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

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

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module RubyLLM
+  module MCP
+    module OAuth
+      module Generators
+        class InstallGenerator < Rails::Generators::Base
+          include Rails::Generators::Migration
+
+          source_root File.expand_path("templates", __dir__)
+
+          namespace "ruby_llm:mcp:oauth"
+
+          argument :user_model, type: :string, default: "User", banner: "UserModel",
+                                desc: "The name of the user model (default: User)"
+
+          class_option :namespace, type: :string, default: nil,
+                                   desc: "Namespace for generated files (e.g., Admin)"
+          class_option :controller_name, type: :string, default: "McpConnectionsController",
+                                         desc: "Name of the controller to generate"
+          class_option :skip_routes, type: :boolean, default: false,
+                                     desc: "Skip adding routes to config/routes.rb"
+          class_option :skip_views, type: :boolean, default: false,
+                                    desc: "Skip generating view files"
+
+          desc "Install RubyLLM MCP OAuth configuration for multi-user authentication\n" \
+               "Usage: rails g ruby_llm:mcp:oauth:install [UserModel] [options]"
+
+          def self.next_migration_number(dirname)
+            ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+          end
+
+          # Validation methods
+          def check_dependencies
+            check_user_model_exists
+            check_rails_version
+            check_encryption_configured
+          end
+
+          def create_migrations
+            create_migration_if_needed(
+              "create_mcp_oauth_credentials",
+              "migrations/create_mcp_oauth_credentials.rb.tt"
+            )
+            create_migration_if_needed(
+              "create_mcp_oauth_states",
+              "migrations/create_mcp_oauth_states.rb.tt"
+            )
+          end
+
+          def create_models
+            template "models/mcp_oauth_credential.rb.tt", "app/models/mcp_oauth_credential.rb"
+            template "models/mcp_oauth_state.rb.tt", "app/models/mcp_oauth_state.rb"
+          end
+
+          def create_token_storage_concern
+            template "concerns/mcp_token_storage.rb.tt", "app/models/concerns/mcp_token_storage.rb"
+          end
+
+          def create_mcp_client
+            template "lib/mcp_client.rb.tt", "app/lib/mcp_client.rb"
+          end
+
+          def create_controller
+            controller_path = if namespace_name
+                                "#{namespace_name.underscore}/mcp_connections_controller.rb"
+                              else
+                                "mcp_connections_controller.rb"
+                              end
+            template "controllers/mcp_connections_controller.rb.tt", "app/controllers/#{controller_path}"
+          end
+
+          def add_routes
+            return if options[:skip_routes]
+
+            routes_content = if namespace_name
+                               <<~ROUTES.strip
+                                 namespace :#{namespace_name.underscore} do
+                                   resources :mcp_connections, only: [ :index, :show, :create, :update, :destroy ] do
+                                     collection do
+                                       get :callback
+                                     end
+                                   end
+                                 end
+                               ROUTES
+                             else
+                               <<~ROUTES.strip
+                                 resources :mcp_connections, only: [ :index, :show, :create, :update, :destroy ] do
+                                   collection do
+                                     get :callback
+                                   end
+                                 end
+                               ROUTES
+                             end
+
+            route routes_content
+          end
+
+          def create_views
+            return if options[:skip_views]
+
+            view_path = namespace_name ? "#{namespace_name.underscore}/mcp_connections" : "mcp_connections"
+            copy_file "views/index.html.erb", "app/views/#{view_path}/index.html.erb"
+            copy_file "views/show.html.erb", "app/views/#{view_path}/show.html.erb"
+          end
+
+          def add_user_concern
+            template "concerns/user_mcp_oauth_concern.rb.tt", "app/models/concerns/user_mcp_oauth.rb"
+          end
+
+          def inject_concern_into_user_model
+            user_model_path = "app/models/#{user_model_name.underscore}.rb"
+            return unless File.exist?(user_model_path)
+
+            # Check if concern is already included
+            if File.read(user_model_path).include?("include UserMcpOauth")
+              say "  ⏭️  UserMcpOauth concern already included in #{user_model_name}", :yellow
+              return
+            end
+
+            inject_into_class user_model_path, user_model_name do
+              "  include UserMcpOauth\n"
+            end
+
+            say "  ✅ Added UserMcpOauth concern to #{user_model_name}", :green
+          rescue StandardError => e
+            say "  ⚠️  Could not automatically add concern to #{user_model_name}: #{e.message}", :yellow
+            say "  Please manually add: include UserMcpOauth", :yellow
+          end
+
+          def create_example_job
+            template "jobs/example_job.rb.tt", "app/jobs/ai_research_job.rb"
+          end
+
+          def create_cleanup_job
+            template "jobs/cleanup_expired_oauth_states_job.rb.tt", "app/jobs/cleanup_expired_oauth_states_job.rb"
+          end
+
+          def display_readme
+            return unless behavior == :invoke
+
+            display_header
+            display_created_files
+            display_next_steps
+            display_documentation_links
+            display_usage_example
+          end
+
+          private
+
+          # Migration helper method
+          def create_migration_if_needed(migration_name, template_path)
+            if migration_exists?(migration_name)
+              say "  ⏭️  Migration #{migration_name} already exists, skipping", :yellow
+            else
+              migration_template template_path, "db/migrate/#{migration_name}.rb"
+            end
+          end
+
+          def migration_exists?(migration_name)
+            Dir.glob("db/migrate/*_#{migration_name}.rb").any?
+          end
+
+          # Validation methods
+          def check_user_model_exists
+            user_model_path = "app/models/#{user_model_name.underscore}.rb"
+            return if File.exist?(user_model_path)
+
+            say "\n⚠️  Warning: #{user_model_name} model not found at #{user_model_path}", :yellow
+            say "The generator will continue, but you'll need to:", :yellow
+            say "  1. Create the #{user_model_name} model", :yellow
+            say "  2. Include the UserMcpOauth concern in your #{user_model_name} model", :yellow
+            say "\n"
+          end
+
+          def check_rails_version
+            return if defined?(Rails) && Rails::VERSION::MAJOR >= 7
+
+            say "\n⚠️  Warning: Rails 7.0+ recommended for this generator", :yellow
+            say "Current Rails version: #{Rails::VERSION::STRING}", :yellow
+            say "\n"
+          end
+
+          def check_encryption_configured
+            return unless defined?(ActiveRecord::Encryption)
+
+            if ActiveRecord::Encryption.config.primary_key.blank?
+              say "\n🔐 ActiveRecord::Encryption not configured. Generating encryption keys...", :yellow
+
+              begin
+                # Run rails db:encryption:init to generate keys
+                run "bin/rails db:encryption:init", verbose: false
+
+                say "✅ Encryption keys generated successfully!", :green
+                say "   Keys have been added to your credentials file.", :green
+                say "   ⚠️  Important: Restart your Rails server for changes to take effect.", :yellow
+                say "\n"
+              rescue StandardError => e
+                say "\n⚠️  Warning: Could not automatically generate encryption keys", :yellow
+                say "Error: #{e.message}", :yellow
+                say "Please run manually: rails db:encryption:init", :yellow
+                say "Then add the generated keys to your credentials or environment variables", :yellow
+                say "\n"
+              end
+            end
+          rescue StandardError => e
+            # Encryption config check failed, but we'll continue
+            say "\n⚠️  Could not check encryption configuration: #{e.message}", :yellow
+            say "You may need to run: rails db:encryption:init", :yellow
+            say "\n"
+          end
+
+          # Helper methods for template variables
+          def user_model_name
+            @user_model_name ||= user_model.camelize
+          end
+
+          def user_table_name
+            @user_table_name ||= user_model_name.underscore.pluralize
+          end
+
+          def user_variable_name
+            @user_variable_name ||= user_model_name.underscore
+          end
+
+          def controller_class_name
+            @controller_class_name ||= if namespace_name
+                                         "#{namespace_name}::#{options[:controller_name]}"
+                                       else
+                                         options[:controller_name]
+                                       end
+          end
+
+          def controller_file_path
+            @controller_file_path ||= if namespace_name
+                                        "#{namespace_name.underscore}/#{controller_name.underscore}"
+                                      else
+                                        controller_name.underscore
+                                      end
+          end
+
+          def controller_name
+            @controller_name ||= options[:controller_name].sub(/Controller$/, "")
+          end
+
+          def current_user_method
+            @current_user_method ||= "current_#{user_variable_name}"
+          end
+
+          def authenticate_method
+            @authenticate_method ||= "authenticate_#{user_variable_name}!"
+          end
+
+          def credential_model_name
+            @credential_model_name ||= "McpOauthCredential"
+          end
+
+          def credential_table_name
+            @credential_table_name ||= "mcp_oauth_credentials"
+          end
+
+          def state_model_name
+            @state_model_name ||= "McpOauthState"
+          end
+
+          def state_table_name
+            @state_table_name ||= "mcp_oauth_states"
+          end
+
+          def namespace_name
+            @namespace_name ||= options[:namespace]
+          end
+
+          def concern_module_name
+            @concern_module_name ||= "UserMcpOauth"
+          end
+
+          # Display methods
+          def display_header
+            say "\n"
+            say "=" * 70, :green
+            say "✅ RubyLLM MCP OAuth installed successfully!", :green
+            say "=" * 70, :green
+            say "\n"
+          end
+
+          def display_created_files
+            say "📦 Created files:", :blue
+            say "  • db/migrate/..._create_mcp_oauth_credentials.rb"
+            say "  • db/migrate/..._create_mcp_oauth_states.rb"
+            say "  • app/models/mcp_oauth_credential.rb"
+            say "  • app/models/mcp_oauth_state.rb"
+            say "  • app/models/concerns/mcp_token_storage.rb"
+            say "  • app/models/concerns/user_mcp_oauth.rb"
+
+            # Show if concern was injected
+            user_model_path = "app/models/#{user_model_name.underscore}.rb"
+            if File.exist?(user_model_path) && File.read(user_model_path).include?("include UserMcpOauth")
+              say "  • app/models/#{user_model_name.underscore}.rb (concern added)", :green
+            end
+
+            say "  • app/lib/mcp_client.rb"
+            say "  • app/controllers/#{controller_file_path}_controller.rb"
+            unless options[:skip_views]
+              say "  • app/views/#{"#{namespace_name.underscore}/" if namespace_name}mcp_connections/index.html.erb"
+              say "  • app/views/#{"#{namespace_name.underscore}/" if namespace_name}mcp_connections/show.html.erb"
+            end
+            say "  • app/jobs/ai_research_job.rb (example)"
+            say "  • app/jobs/cleanup_expired_oauth_states_job.rb"
+            say "\n"
+          end
+
+          def display_next_steps
+            say "📝 Next steps:", :yellow
+
+            routes_status = options[:skip_routes] ? "not added - add them manually" : "added automatically"
+            say "  1. Routes #{routes_status}"
+            say "  2. Run migrations: rails db:migrate"
+
+            # Only show concern instruction if user model doesn't exist
+            user_model_path = "app/models/#{user_model_name.underscore}.rb"
+            unless File.exist?(user_model_path)
+              say "  3. Include concern in #{user_model_name}: include UserMcpOauth"
+            end
+
+            connections_path = namespace_name ? "#{namespace_name.underscore}/mcp_connections" : "mcp_connections"
+            say "  #{File.exist?(user_model_path) ? '3' : '4'}. Visit /#{connections_path} \
+              and enter your MCP server URL to connect"
+            say "\n"
+          end
+
+          def display_documentation_links
+            say "📚 Documentation:", :cyan
+            say "  • OAuth Guide: docs/guides/rails-oauth.md"
+            say "  • Full OAuth Docs: docs/guides/oauth.md"
+            say "  • Online: https://www.rubyllm-mcp.com/guides/rails-oauth"
+            say "\n"
+          end
+
+          def display_usage_example
+            say "💡 Usage Examples:", :blue
+            say "   client = McpClient.for(#{user_variable_name}, server_url: 'https://mcp.example.com')"
+            say "   or: #{user_variable_name}.mcp_client(server_url: 'https://mcp.example.com')"
+            say "⭐ Star us: https://github.com/patvice/ruby_llm-mcp", :magenta
+            say "\n"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/mcp/oauth/templates/concerns/mcp_token_storage.rb.tt

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+# Per-<%= user_variable_name %> OAuth token storage for RubyLLM MCP
+# Implements the storage interface required by RubyLLM::MCP::Auth::OAuthProvider
+#
+# Include this in your <%= user_model_name %> model (or any model that needs MCP OAuth):
+#   include McpTokenStorage
+module McpTokenStorage
+  extend ActiveSupport::Concern
+
+  # Create token storage instance for a specific server URL
+  # @param server_url [String] MCP server URL
+  # @param name [String] Optional friendly name for the server
+  # @param scope [String] Optional OAuth scope for the connection
+  # @return [TokenStorageAdapter] storage adapter instance
+  def mcp_token_storage(server_url, name = nil, scope = nil)
+    TokenStorageAdapter.new(self.id, server_url, self.class.name.underscore, name, scope)
+  end
+
+  # Internal adapter class that implements the OAuth storage interface
+  class TokenStorageAdapter
+    def initialize(<%= user_variable_name %>_id, server_url, user_type = "<%= user_variable_name %>", name = nil, scope = nil)
+      @<%= user_variable_name %>_id = <%= user_variable_name %>_id
+      @server_url = server_url
+      @user_type = user_type
+      @name = name
+      @scope = scope
+    end
+
+    # Token storage
+    def get_token(_server_url)
+      credential = <%= credential_model_name %>.find_by(<%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id, server_url: @server_url)
+      credential&.token
+    end
+
+    def set_token(_server_url, token)
+      credential = <%= credential_model_name %>.find_or_initialize_by(
+        <%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id,
+        server_url: @server_url
+      )
+      credential.name = @name if @name.present?
+      credential.token = token
+      credential.last_refreshed_at = Time.current
+      credential.save!
+    end
+
+    # Client registration storage
+    def get_client_info(_server_url)
+      credential = <%= credential_model_name %>.find_by(<%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id, server_url: @server_url)
+      credential&.client_info
+    end
+
+    def set_client_info(_server_url, client_info)
+      credential = <%= credential_model_name %>.find_or_initialize_by(
+        <%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id,
+        server_url: @server_url
+      )
+      credential.name = @name if @name.present?
+      credential.client_info = client_info
+      credential.save!
+    end
+
+    # Server metadata caching (shared across users)
+    def get_server_metadata(server_url)
+      Rails.cache.fetch("mcp:server_metadata:#{server_url}", expires_in: 24.hours) do
+        nil
+      end
+    end
+
+    def set_server_metadata(server_url, metadata)
+      Rails.cache.write("mcp:server_metadata:#{server_url}", metadata, expires_in: 24.hours)
+    end
+
+    # PKCE state management (temporary - per <%= user_variable_name %>)
+    def get_pkce(_server_url)
+      state = <%= state_model_name %>.find_by(<%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id, server_url: @server_url)
+      return nil unless state
+
+      state.pkce
+    end
+
+    def set_pkce(_server_url, pkce)
+      state = <%= state_model_name %>.find_or_initialize_by(<%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id, server_url: @server_url)
+      state.pkce = pkce
+      state.state_param ||= SecureRandom.hex(32)
+      state.name = @name if @name.present?
+      state.scope = @scope if @scope.present?
+      state.expires_at = 10.minutes.from_now
+      state.save!
+    end
+
+    def delete_pkce(_server_url)
+      <%= state_model_name %>.where(<%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id, server_url: @server_url).delete_all
+    end
+
+    # State parameter management
+    def get_state(_server_url)
+      <%= state_model_name %>.find_by(<%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id, server_url: @server_url)&.state_param
+    end
+
+    def set_state(_server_url, state_param)
+      state = <%= state_model_name %>.find_or_initialize_by(<%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id, server_url: @server_url)
+      state.state_param = state_param
+      state.name = @name if @name.present?
+      state.scope = @scope if @scope.present?
+      state.expires_at = 10.minutes.from_now
+      state.save!
+    end
+
+    def delete_state(_server_url)
+      <%= state_model_name %>.where(<%= user_table_name.singularize %>_id: @<%= user_variable_name %>_id, server_url: @server_url).delete_all
+    end
+  end
+end

data/lib/generators/ruby_llm/mcp/oauth/templates/concerns/user_mcp_oauth_concern.rb.tt

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Add this to your User model:
+# include UserMcpOauth
+
+module UserMcpOauth
+  extend ActiveSupport::Concern
+
+  include McpTokenStorage
+
+  included do
+    has_many :mcp_oauth_credentials, dependent: :destroy
+    has_many :mcp_oauth_states, dependent: :destroy
+  end
+
+  # Check if user has connected to a specific MCP server
+  # @param server_url [String] MCP server URL (required)
+  # @return [Boolean] true if user has an OAuth credential for this server
+  def mcp_connected?(server_url)
+    return false unless server_url.present?
+
+    mcp_oauth_credentials.exists?(server_url: server_url)
+  end
+
+  # Get valid token for a server
+  # @param server_url [String] MCP server URL (required)
+  # @return [RubyLLM::MCP::Auth::Token, nil] token if valid, nil otherwise
+  def mcp_token_for(server_url)
+    return nil unless server_url.present?
+
+    credential = mcp_oauth_credentials.find_by(server_url: server_url)
+    return nil unless credential
+
+    token = credential.token
+    return nil if token.nil? || token.expired? || token.expires_soon?
+
+    token
+  end
+
+  # Get MCP client for this user
+  # @param server_url [String] MCP server URL (required)
+  # @return [RubyLLM::MCP::Client] configured client
+  # @raise [McpClient::NotAuthenticatedError] if not connected
+  def mcp_client(server_url:)
+    McpClient.for(self, server_url: server_url)
+  end
+
+  # Get MCP client with fallback to nil if not authenticated
+  # @param server_url [String] MCP server URL (required)
+  # @return [RubyLLM::MCP::Client, nil] client or nil
+  def mcp_client_safe(server_url:)
+    McpClient.for_with_fallback(self, server_url: server_url)
+  end
+
+  # Get all connected MCP servers for this user
+  # @return [Array<String>] array of server URLs
+  def connected_mcp_servers
+    mcp_oauth_credentials.pluck(:server_url)
+  end
+
+  # Disconnect from a specific MCP server
+  # @param server_url [String] MCP server URL
+  def revoke_mcp_connection(server_url)
+    credential = mcp_oauth_credentials.find_by(server_url: server_url)
+    credential&.destroy
+  end
+
+  # Get OAuth connection status for a server
+  # @param server_url [String] MCP server URL (required)
+  # @return [Hash] status information
+  def mcp_connection_status(server_url)
+    return { connected: false } unless server_url.present?
+
+    credential = mcp_oauth_credentials.find_by(server_url: server_url)
+
+    return { connected: false } unless credential
+
+    token = credential.token
+
+    {
+      connected: true,
+      valid: token && !token.expired?,
+      expires_at: token&.expires_at,
+      expires_soon: token&.expires_soon?,
+      has_refresh_token: token&.refresh_token.present?,
+      last_refreshed_at: credential.last_refreshed_at,
+      scope: token&.scope
+    }
+  end
+end