mcp_on_ruby 0.3.0 → 1.0.0

data/lib/mcp_on_ruby/generators/tool_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module McpOnRuby
+  module Generators
+    # Generator for creating MCP tools
+    class ToolGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      desc "Generate an MCP tool class"
+
+      argument :name, type: :string, desc: "Name of the tool"
+      
+      class_option :description, type: :string, desc: "Description of the tool"
+      class_option :input_schema, type: :hash, default: {}, desc: "JSON Schema for input validation"
+
+      def create_tool_file
+        template 'tool.rb', File.join('app/tools', "#{file_name}_tool.rb")
+      end
+
+      def create_spec_file
+        return unless File.exist?(Rails.root.join('spec'))
+        
+        template 'tool_spec.rb', File.join('spec/tools', "#{file_name}_tool_spec.rb")
+      end
+
+      private
+
+      def tool_name
+        name.underscore
+      end
+
+      def tool_class_name
+        "#{name.camelize}Tool"
+      end
+
+      def tool_description
+        options[:description] || "#{name.humanize} tool"
+      end
+
+      def input_schema_code
+        if options[:input_schema].any?
+          "input_schema #{options[:input_schema].inspect}"
+        else
+          "# input_schema({\n    #   type: 'object',\n    #   properties: {\n    #     param: { type: 'string' }\n    #   },\n    #   required: ['param']\n    # })"
+        end
+      end
+    end
+  end
+end

data/lib/mcp_on_ruby/railtie.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+if defined?(Rails)
+  module McpOnRuby
+    # Rails integration via Railtie
+    class Railtie < Rails::Railtie
+      # Add MCP-specific directories to Rails autoload paths
+      initializer "mcp_on_ruby.setup_autoload_paths" do |app|
+        # Add app/tools and app/resources to autoload paths
+        %w[tools resources].each do |dir|
+          path = app.root.join("app", dir)
+          if path.exist? && !app.config.autoload_paths.include?(path.to_s)
+            app.config.autoload_paths = app.config.autoload_paths.dup if app.config.autoload_paths.frozen?
+            app.config.autoload_paths << path.to_s
+          end
+        end
+      end
+
+      # Set up Rails-friendly aliases
+      initializer "mcp_on_ruby.setup_aliases" do
+        # Create Rails-style base classes
+        Object.const_set('ApplicationTool', Class.new(McpOnRuby::Tool)) unless defined?(ApplicationTool)
+        Object.const_set('ApplicationResource', Class.new(McpOnRuby::Resource)) unless defined?(ApplicationResource)
+      end
+
+      # Configure MCP server if needed
+      initializer "mcp_on_ruby.configure" do |app|
+        # Set up default configuration
+        McpOnRuby.configure do |config|
+          config.log_level = Rails.logger.level
+        end
+
+        # Add MCP configuration to Rails application
+        app.config.mcp = ActiveSupport::OrderedOptions.new
+        app.config.mcp.enabled = false
+        app.config.mcp.path = '/mcp'
+        app.config.mcp.authentication_required = false
+        app.config.mcp.authentication_token = nil
+        app.config.mcp.rate_limit_per_minute = 60
+        app.config.mcp.auto_register_tools = true
+        app.config.mcp.auto_register_resources = true
+      end
+
+      # Setup MCP middleware
+      initializer "mcp_on_ruby.setup_middleware", after: :load_config_initializers do |app|
+        next unless app.config.mcp.enabled
+
+        # Eager load MCP classes in development
+        if Rails.env.development?
+          tools_path = app.root.join('app/tools')
+          resources_path = app.root.join('app/resources')
+          
+          if tools_path.exist?
+            Dir[tools_path.join('**/*.rb')].each { |file| require_dependency file }
+          end
+          
+          if resources_path.exist?
+            Dir[resources_path.join('**/*.rb')].each { |file| require_dependency file }
+          end
+        end
+
+        # Create MCP server instance
+        server = McpOnRuby.server do |s|
+          # Auto-register tools if enabled
+          if app.config.mcp.auto_register_tools && defined?(ApplicationTool)
+            ApplicationTool.descendants.each do |tool_class|
+              instance = tool_class.new
+              s.register_tool(instance)
+            end
+          end
+
+          # Auto-register resources if enabled
+          if app.config.mcp.auto_register_resources && defined?(ApplicationResource)
+            ApplicationResource.descendants.each do |resource_class|
+              instance = resource_class.new
+              s.register_resource(instance)
+            end
+          end
+        end
+
+        # Mount the server middleware (before the stack is frozen)
+        app.middleware.use(
+          McpOnRuby::Transport::RackMiddleware,
+          server: server,
+          path: app.config.mcp.path,
+          authentication_required: app.config.mcp.authentication_required,
+          authentication_token: app.config.mcp.authentication_token,
+          rate_limit_per_minute: app.config.mcp.rate_limit_per_minute
+        )
+
+        # Store server reference for manual access
+        app.config.mcp_server = server
+      end
+
+      # Add rake tasks (uncomment when tasks file is created)
+      # rake_tasks do
+      #   load File.expand_path('tasks/mcp.rake', __dir__)
+      # end
+
+      # Add generators
+      generators do
+        require_relative 'generators/install_generator'
+        require_relative 'generators/tool_generator'
+        require_relative 'generators/resource_generator'
+      end
+    end
+  end
+end

data/lib/mcp_on_ruby/resource.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Base class for MCP resources - data sources that AI can read
+  class Resource
+    attr_reader :uri, :name, :description, :mime_type, :metadata, :tags
+
+    # Create a new resource
+    # @param uri [String] The resource URI (supports templates with {param})
+    # @param name [String] Optional human-readable name
+    # @param description [String] Resource description
+    # @param mime_type [String] MIME type of the resource content
+    # @param metadata [Hash] Additional metadata
+    # @param tags [Array<String>] Tags for categorization
+    def initialize(uri:, name: nil, description: '', mime_type: 'application/json', metadata: {}, tags: [])
+      @uri = uri.to_s
+      @name = name
+      @description = description
+      @mime_type = mime_type
+      @metadata = metadata
+      @tags = Array(tags)
+    end
+
+    # Read the resource content with given parameters
+    # @param params [Hash] URI template parameters
+    # @param context [Hash] Request context (headers, user info, etc.)
+    # @return [Hash] The resource content wrapped in MCP format
+    def read(params = {}, context = {})
+      # Validate parameters if this is a template
+      validate_template_params!(params) if template?
+      
+      # Get the content
+      content = fetch_content(params, context)
+      
+      # Wrap in MCP resource format
+      {
+        contents: [
+          {
+            uri: resolve_uri(params),
+            mimeType: mime_type,
+            text: serialize_content(content)
+          }
+        ]
+      }
+    rescue => error
+      McpOnRuby.logger.error("Resource '#{uri}' read failed: #{error.message}")
+      McpOnRuby.logger.error(error.backtrace.join("\n"))
+      
+      {
+        error: {
+          code: -32603,
+          message: "Resource read failed: #{error.message}",
+          data: { uri: uri, error_type: error.class.name }
+        }
+      }
+    end
+
+    # Get the resource schema for MCP protocol
+    # @return [Hash] The resource schema
+    def to_schema
+      schema = {
+        uri: uri,
+        mimeType: mime_type
+      }
+      
+      schema[:name] = name if name
+      schema[:description] = description unless description.empty?
+      schema[:metadata] = metadata unless metadata.empty?
+      schema[:tags] = tags unless tags.empty?
+      
+      schema
+    end
+
+    # Check if this resource is a template (contains {param} placeholders)
+    # @return [Boolean] True if resource URI contains template parameters
+    def template?
+      uri.include?('{') && uri.include?('}')
+    end
+
+    # Extract parameter names from template URI
+    # @return [Array<String>] Parameter names
+    def template_params
+      return [] unless template?
+      
+      uri.scan(/\{([^}]+)\}/).flatten
+    end
+
+    # Check if resource is authorized for the given context
+    # @param context [Hash] Request context
+    # @return [Boolean] True if authorized
+    def authorized?(context = {})
+      return true unless respond_to?(:authorize, true)
+      
+      authorize(context)
+    rescue => error
+      McpOnRuby.logger.warn("Authorization check failed for resource '#{uri}': #{error.message}")
+      false
+    end
+
+    protected
+
+    # Override this method to implement resource content fetching
+    # @param params [Hash] URI template parameters
+    # @param context [Hash] Request context
+    # @return [Object] Resource content (will be serialized)
+    def fetch_content(params, context)
+      raise NotImplementedError, "Resource '#{uri}' must implement #fetch_content method"
+    end
+
+    # Override this method to implement authorization logic
+    # @param context [Hash] Request context
+    # @return [Boolean] True if authorized
+    def authorize(context)
+      true
+    end
+
+    private
+
+    # Validate template parameters
+    # @param params [Hash] Parameters to validate
+    # @raise [McpOnRuby::ValidationError] If required parameters are missing
+    def validate_template_params!(params)
+      required_params = template_params
+      missing_params = required_params - params.keys.map(&:to_s)
+      
+      unless missing_params.empty?
+        raise McpOnRuby::ValidationError, 
+              "Resource '#{uri}' missing required parameters: #{missing_params.join(', ')}"
+      end
+    end
+
+    # Resolve URI template with parameters
+    # @param params [Hash] Parameters to substitute
+    # @return [String] Resolved URI
+    def resolve_uri(params)
+      return uri unless template?
+      
+      resolved = uri.dup
+      params.each do |key, value|
+        resolved.gsub!("{#{key}}", value.to_s)
+      end
+      resolved
+    end
+
+    # Serialize content based on MIME type
+    # @param content [Object] Content to serialize
+    # @return [String] Serialized content
+    def serialize_content(content)
+      case mime_type
+      when 'application/json'
+        content.is_a?(String) ? content : JSON.pretty_generate(content)
+      when 'text/plain', 'text/html', 'text/css', 'text/javascript'
+        content.to_s
+      else
+        # For other types, assume it's already in the correct format
+        content.to_s
+      end
+    end
+  end
+
+end

data/lib/mcp_on_ruby/server.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Main MCP server class that handles JSON-RPC protocol and manages tools/resources
+  class Server
+    attr_reader :tools, :resources, :configuration, :logger
+
+    # Initialize a new MCP server
+    # @param options [Hash] Server configuration options
+    # @yield [Server] Server instance for configuration
+    def initialize(options = {}, &block)
+      @configuration = McpOnRuby.configuration || Configuration.new
+      @configuration.tap do |config|
+        options.each { |key, value| config.send("#{key}=", value) if config.respond_to?("#{key}=") }
+      end
+      
+      @logger = McpOnRuby.logger
+      @tools = {}
+      @resources = {}
+      @rate_limiter = RateLimiter.new(@configuration.rate_limit_per_minute)
+      
+      # Configure the server using the block
+      instance_eval(&block) if block_given?
+    end
+
+    # Register a tool
+    # @param tool [Tool] The tool to register
+    # @param name [String] Optional name override
+    # @return [Tool] The registered tool
+    def register_tool(tool, name = nil)
+      tool_name = name || tool.name
+      @tools[tool_name] = tool
+      @logger.debug("Registered tool: #{tool_name}")
+      tool
+    end
+
+    # Register a resource
+    # @param resource [Resource] The resource to register
+    # @param uri [String] Optional URI override
+    # @return [Resource] The registered resource
+    def register_resource(resource, uri = nil)
+      resource_uri = uri || resource.uri
+      @resources[resource_uri] = resource
+      @logger.debug("Registered resource: #{resource_uri}")
+      resource
+    end
+
+    # DSL method to define a tool
+    # @param name [String] Tool name
+    # @param description [String] Tool description
+    # @param input_schema [Hash] JSON Schema for validation
+    # @param options [Hash] Additional options (metadata, tags)
+    # @param block [Proc] Tool implementation
+    # @return [Tool] The created and registered tool
+    def tool(name, description = '', input_schema = {}, **options, &block)
+      tool_instance = McpOnRuby.tool(name, description, input_schema, **options, &block)
+      register_tool(tool_instance)
+    end
+
+    # DSL method to define a resource
+    # @param uri [String] Resource URI
+    # @param options [Hash] Resource options (name, description, etc.)
+    # @param block [Proc] Resource implementation
+    # @return [Resource] The created and registered resource
+    def resource(uri, **options, &block)
+      resource_instance = McpOnRuby.resource(uri, **options, &block)
+      register_resource(resource_instance)
+    end
+
+    # Handle a JSON-RPC request
+    # @param request_body [String] JSON request body
+    # @param context [Hash] Request context (headers, IP, etc.)
+    # @return [String, nil] JSON response or nil for notifications
+    def handle_request(request_body, context = {})
+      # Parse JSON request
+      request = JSON.parse(request_body)
+      
+      # Rate limiting check
+      unless @rate_limiter.allowed?(context[:remote_ip])
+        return error_response(nil, -32603, "Rate limit exceeded")
+      end
+      
+      # Handle the request
+      response = handle_json_rpc(request, context)
+      
+      # Return JSON response for requests with ID, nil for notifications
+      response ? JSON.generate(response) : nil
+      
+    rescue JSON::ParserError => e
+      @logger.warn("Invalid JSON request: #{e.message}")
+      JSON.generate(error_response(nil, -32700, "Parse error"))
+    rescue => e
+      @logger.error("Request handling failed: #{e.message}")
+      @logger.error(e.backtrace.join("\n"))
+      JSON.generate(error_response(nil, -32603, "Internal error"))
+    end
+
+    # Get server capabilities for MCP initialization
+    # @return [Hash] Server capabilities
+    def capabilities
+      {
+        tools: tools.any? ? {} : nil,
+        resources: resources.any? ? { subscribe: @configuration.enable_sse } : nil
+      }.compact
+    end
+
+    # Get server information
+    # @return [Hash] Server info
+    def server_info
+      {
+        name: "mcp_on_ruby",
+        version: McpOnRuby::VERSION
+      }
+    end
+
+    private
+
+    # Handle JSON-RPC protocol
+    # @param request [Hash] Parsed JSON-RPC request
+    # @param context [Hash] Request context
+    # @return [Hash, nil] Response hash or nil for notifications
+    def handle_json_rpc(request, context)
+      method = request['method']
+      params = request['params'] || {}
+      id = request['id']
+      
+      @logger.debug("Handling method: #{method}")
+      
+      case method
+      when 'initialize'
+        success_response(id, handle_initialize(params))
+      when 'tools/list'
+        success_response(id, handle_tools_list(context))
+      when 'tools/call'
+        success_response(id, handle_tool_call(params, context))
+      when 'resources/list'
+        success_response(id, handle_resources_list(context))
+      when 'resources/read'
+        success_response(id, handle_resource_read(params, context))
+      when 'ping'
+        success_response(id, { pong: true })
+      else
+        id ? error_response(id, -32601, "Method not found: #{method}") : nil
+      end
+    end
+
+    # Handle initialization request
+    # @param params [Hash] Initialization parameters
+    # @return [Hash] Initialization response
+    def handle_initialize(params)
+      client_info = params['clientInfo'] || {}
+      protocol_version = params['protocolVersion']
+      
+      @logger.info("Client connected: #{client_info['name']} #{client_info['version']}")
+      
+      {
+        serverInfo: server_info,
+        protocolVersion: McpOnRuby::PROTOCOL_VERSION,
+        capabilities: capabilities
+      }
+    end
+
+    # Handle tools list request
+    # @param context [Hash] Request context
+    # @return [Hash] Tools list response
+    def handle_tools_list(context)
+      authorized_tools = @tools.select { |_, tool| tool.authorized?(context) }
+      
+      {
+        tools: authorized_tools.values.map(&:to_schema)
+      }
+    end
+
+    # Handle tool call request
+    # @param params [Hash] Tool call parameters
+    # @param context [Hash] Request context
+    # @return [Hash] Tool call response
+    def handle_tool_call(params, context)
+      tool_name = params['name']
+      arguments = params['arguments'] || {}
+      
+      tool = @tools[tool_name]
+      unless tool
+        raise McpOnRuby::NotFoundError, "Tool not found: #{tool_name}"
+      end
+      
+      unless tool.authorized?(context)
+        raise McpOnRuby::AuthorizationError, "Not authorized to call tool: #{tool_name}"
+      end
+      
+      result = tool.call(arguments, context)
+      
+      # Handle error results from tool execution
+      if result.key?(:error)
+        raise McpOnRuby::ToolExecutionError, result[:error][:message]
+      end
+      
+      {
+        content: [
+          {
+            type: "text",
+            text: serialize_tool_result(result)
+          }
+        ]
+      }
+    end
+
+    # Handle resources list request
+    # @param context [Hash] Request context
+    # @return [Hash] Resources list response
+    def handle_resources_list(context)
+      authorized_resources = @resources.select { |_, resource| resource.authorized?(context) }
+      
+      {
+        resources: authorized_resources.values.map(&:to_schema)
+      }
+    end
+
+    # Handle resource read request
+    # @param params [Hash] Resource read parameters
+    # @param context [Hash] Request context
+    # @return [Hash] Resource read response
+    def handle_resource_read(params, context)
+      uri = params['uri']
+      
+      # Find exact match or template match
+      resource = find_resource(uri)
+      unless resource
+        raise McpOnRuby::NotFoundError, "Resource not found: #{uri}"
+      end
+      
+      unless resource.authorized?(context)
+        raise McpOnRuby::AuthorizationError, "Not authorized to read resource: #{uri}"
+      end
+      
+      # Extract parameters from URI if it's a template
+      template_params = extract_template_params(resource.uri, uri)
+      
+      result = resource.read(template_params, context)
+      
+      # Handle error results from resource reading
+      if result.key?(:error)
+        raise McpOnRuby::ResourceReadError, result[:error][:message]
+      end
+      
+      result
+    end
+
+    # Find a resource by URI (exact match or template match)
+    # @param uri [String] The URI to find
+    # @return [Resource, nil] The matching resource
+    def find_resource(uri)
+      # Try exact match first
+      return @resources[uri] if @resources.key?(uri)
+      
+      # Try template matching
+      @resources.each do |template_uri, resource|
+        next unless resource.template?
+        
+        if uri_matches_template?(template_uri, uri)
+          return resource
+        end
+      end
+      
+      nil
+    end
+
+    # Check if a URI matches a template
+    # @param template [String] Template URI with {param} placeholders
+    # @param uri [String] Actual URI to match
+    # @return [Boolean] True if URI matches template
+    def uri_matches_template?(template, uri)
+      # Convert template to regex
+      regex_pattern = template.gsub(/\{[^}]+\}/, '([^/]+)')
+      regex = /^#{regex_pattern}$/
+      
+      uri =~ regex
+    end
+
+    # Extract parameters from URI using template
+    # @param template [String] Template URI
+    # @param uri [String] Actual URI
+    # @return [Hash] Extracted parameters
+    def extract_template_params(template, uri)
+      return {} unless template.include?('{')
+      
+      # Get parameter names
+      param_names = template.scan(/\{([^}]+)\}/).flatten
+      
+      # Convert template to regex with capture groups
+      regex_pattern = template.gsub(/\{[^}]+\}/, '([^/]+)')
+      regex = /^#{regex_pattern}$/
+      
+      # Extract values
+      matches = uri.match(regex)
+      return {} unless matches
+      
+      # Build parameter hash
+      param_names.zip(matches.captures).to_h
+    end
+
+    # Serialize tool result for response
+    # @param result [Object] Tool execution result
+    # @return [String] Serialized result
+    def serialize_tool_result(result)
+      case result
+      when String
+        result
+      when Hash, Array
+        JSON.pretty_generate(result)
+      else
+        result.to_s
+      end
+    end
+
+    # Create success response
+    # @param id [String, Integer] Request ID
+    # @param result [Object] Response result
+    # @return [Hash] Success response
+    def success_response(id, result)
+      {
+        jsonrpc: "2.0",
+        id: id,
+        result: result
+      }
+    end
+
+    # Create error response
+    # @param id [String, Integer, nil] Request ID
+    # @param code [Integer] Error code
+    # @param message [String] Error message
+    # @param data [Object] Additional error data
+    # @return [Hash] Error response
+    def error_response(id, code, message, data = nil)
+      response = {
+        jsonrpc: "2.0",
+        id: id,
+        error: {
+          code: code,
+          message: message
+        }
+      }
+      response[:error][:data] = data if data
+      response
+    end
+
+    # Simple rate limiter
+    class RateLimiter
+      def initialize(requests_per_minute)
+        @requests_per_minute = requests_per_minute
+        @requests = {}
+        @mutex = Mutex.new
+      end
+
+      def allowed?(ip)
+        return true if @requests_per_minute <= 0
+        
+        @mutex.synchronize do
+          now = Time.now.to_i
+          minute = now / 60
+          
+          @requests[ip] ||= {}
+          @requests[ip][minute] ||= 0
+          
+          # Clean old entries
+          @requests[ip].delete_if { |m, _| m < minute }
+          
+          if @requests[ip][minute] >= @requests_per_minute
+            false
+          else
+            @requests[ip][minute] += 1
+            true
+          end
+        end
+      end
+    end
+  end
+end