mcp_on_ruby 0.3.0 → 1.0.0

data/lib/mcp_on_ruby/tool.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Base class for MCP tools - functions that AI can execute
+  class Tool
+    attr_reader :name, :description, :input_schema, :metadata, :tags
+
+    # Create a new tool
+    # @param name [String] The tool name
+    # @param description [String] The tool description
+    # @param input_schema [Hash] JSON Schema for input validation
+    # @param metadata [Hash] Additional metadata
+    # @param tags [Array<String>] Tags for categorization
+    def initialize(name:, description: '', input_schema: {}, metadata: {}, tags: [])
+      @name = name.to_s
+      @description = description
+      @input_schema = normalize_schema(input_schema)
+      @metadata = metadata
+      @tags = Array(tags)
+    end
+
+    # Execute the tool with given arguments
+    # @param arguments [Hash] The arguments to pass to the tool
+    # @param context [Hash] Request context (headers, user info, etc.)
+    # @return [Hash] The tool execution result
+    def call(arguments = {}, context = {})
+      # Validate arguments against schema
+      validate_arguments!(arguments)
+      
+      # Call the implementation
+      execute(arguments, context)
+    rescue => error
+      McpOnRuby.logger.error("Tool '#{name}' execution failed: #{error.message}")
+      McpOnRuby.logger.error(error.backtrace.join("\n"))
+      
+      {
+        error: {
+          code: -32603,
+          message: "Tool execution failed: #{error.message}",
+          data: { tool: name, error_type: error.class.name }
+        }
+      }
+    end
+
+    # Get the tool's schema for MCP protocol
+    # @return [Hash] The tool schema
+    def to_schema
+      {
+        name: name,
+        description: description,
+        inputSchema: input_schema
+      }.tap do |schema|
+        schema[:metadata] = metadata unless metadata.empty?
+        schema[:tags] = tags unless tags.empty?
+      end
+    end
+
+    # Check if tool 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 tool '#{name}': #{error.message}")
+      false
+    end
+
+    protected
+
+    # Override this method to implement tool functionality
+    # @param arguments [Hash] Validated arguments
+    # @param context [Hash] Request context
+    # @return [Hash] Tool result
+    def execute(arguments, context)
+      raise NotImplementedError, "Tool '#{name}' must implement #execute 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 arguments against the input schema
+    # @param arguments [Hash] Arguments to validate
+    # @raise [McpOnRuby::ValidationError] If validation fails
+    def validate_arguments!(arguments)
+      return if input_schema.empty?
+
+      errors = JSON::Validator.fully_validate(input_schema, arguments)
+      return if errors.empty?
+
+      raise McpOnRuby::ValidationError, "Tool '#{name}' validation failed: #{errors.join(', ')}"
+    end
+
+    # Normalize schema to ensure it's a proper JSON Schema
+    # @param schema [Hash] Input schema
+    # @return [Hash] Normalized schema
+    def normalize_schema(schema)
+      return {} if schema.nil? || schema.empty?
+
+      # Ensure we have a proper JSON Schema structure
+      normalized = schema.is_a?(Hash) ? schema.dup : {}
+      
+      # Set default type if not specified
+      normalized['type'] ||= 'object' if normalized.key?('properties') || normalized.key?('required')
+      
+      # Convert symbol keys to strings for JSON Schema compatibility
+      deep_stringify_keys(normalized)
+    end
+
+    # Convert all symbol keys to strings recursively
+    # @param obj [Object] Object to convert
+    # @return [Object] Object with string keys
+    def deep_stringify_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), hash|
+          hash[key.to_s] = deep_stringify_keys(value)
+        end
+      when Array
+        obj.map { |item| deep_stringify_keys(item) }
+      else
+        obj
+      end
+    end
+  end
+
+end

data/lib/mcp_on_ruby/transport.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  module Transport
+    # Rack middleware for handling MCP requests
+    class RackMiddleware
+      def initialize(app, server:, **options)
+        @app = app
+        @server = server
+        @path = options[:path] || @server.configuration.path
+        @logger = McpOnRuby.logger
+        @options = options
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        
+        # Only handle requests to our MCP path
+        return @app.call(env) unless request.path == @path
+        
+        # Only handle POST requests for JSON-RPC
+        return method_not_allowed_response unless request.post?
+        
+        # Security checks
+        security_result = check_security(request)
+        return security_result if security_result
+        
+        # Handle MCP request
+        handle_mcp_request(request)
+        
+      rescue => error
+        @logger.error("Transport error: #{error.message}")
+        @logger.error(error.backtrace.join("\n"))
+        internal_error_response
+      end
+
+      private
+
+      def handle_mcp_request(request)
+        # Build request context
+        context = build_request_context(request)
+        
+        # Read request body
+        request_body = request.body.read
+        
+        # Handle the request through server
+        response_json = @server.handle_request(request_body, context)
+        
+        if response_json
+          # JSON-RPC response
+          json_response(response_json)
+        else
+          # Notification (no response)
+          [204, cors_headers, []]
+        end
+      end
+
+      def build_request_context(request)
+        {
+          remote_ip: request.ip,
+          user_agent: request.user_agent,
+          headers: request.env.select { |k, _| k.start_with?('HTTP_') },
+          authenticated: authenticated?(request),
+          auth_token: extract_auth_token(request)
+        }
+      end
+
+      def check_security(request)
+        config = @server.configuration
+        
+        # DNS rebinding protection
+        if config.dns_rebinding_protection
+          origin = request.get_header('HTTP_ORIGIN')
+          host = request.get_header('HTTP_HOST')
+          
+          if origin && !origin_allowed?(origin, host)
+            return forbidden_response("Origin not allowed: #{origin}")
+          end
+        end
+        
+        # Authentication check
+        if config.authentication_required
+          unless authenticated?(request)
+            return unauthorized_response
+          end
+        end
+        
+        # Localhost only check
+        if config.localhost_only
+          unless localhost_request?(request)
+            return forbidden_response("Localhost only mode enabled")
+          end
+        end
+        
+        nil # No security issues
+      end
+
+      def origin_allowed?(origin, host)
+        config = @server.configuration
+        
+        # Check localhost patterns if localhost_only is enabled
+        return false if config.localhost_only && !config.localhost_allowed?(origin)
+        
+        # Check configured allowed origins
+        return config.origin_allowed?(origin) unless config.allowed_origins.empty?
+        
+        # Default: allow same origin
+        origin_host = URI.parse(origin).host rescue nil
+        origin_host == host
+      end
+
+      def authenticated?(request)
+        return true unless @server.configuration.authentication_required
+        
+        token = extract_auth_token(request)
+        token && token == @server.configuration.authentication_token
+      end
+
+      def extract_auth_token(request)
+        auth_header = request.get_header('HTTP_AUTHORIZATION')
+        return nil unless auth_header
+        
+        # Support Bearer token format
+        if auth_header.start_with?('Bearer ')
+          auth_header[7..-1]
+        else
+          auth_header
+        end
+      end
+
+      def localhost_request?(request)
+        ip = request.ip
+        %w[127.0.0.1 ::1 localhost].include?(ip) || ip.start_with?('127.')
+      end
+
+      def cors_headers
+        headers = {}
+        
+        if @server.configuration.cors_enabled
+          headers['Access-Control-Allow-Origin'] = '*'
+          headers['Access-Control-Allow-Methods'] = 'POST, OPTIONS'
+          headers['Access-Control-Allow-Headers'] = 'Content-Type, Authorization'
+          headers['Access-Control-Max-Age'] = '86400'
+        end
+        
+        headers['Content-Type'] = 'application/json'
+        headers
+      end
+
+      def json_response(json_body)
+        [200, cors_headers, [json_body]]
+      end
+
+      def method_not_allowed_response
+        [405, cors_headers.merge('Allow' => 'POST'), ['{"error": "Method not allowed"}']]
+      end
+
+      def unauthorized_response
+        error_body = {
+          jsonrpc: "2.0",
+          error: { code: -32600, message: "Unauthorized" },
+          id: nil
+        }
+        [401, cors_headers, [JSON.generate(error_body)]]
+      end
+
+      def forbidden_response(message = "Forbidden")
+        error_body = {
+          jsonrpc: "2.0",
+          error: { code: -32600, message: message },
+          id: nil
+        }
+        [403, cors_headers, [JSON.generate(error_body)]]
+      end
+
+      def internal_error_response
+        error_body = {
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal error" },
+          id: nil
+        }
+        [500, cors_headers, [JSON.generate(error_body)]]
+      end
+    end
+
+    # SSE (Server-Sent Events) transport for real-time updates
+    class SSETransport
+      def initialize(server, **options)
+        @server = server
+        @options = options
+        @logger = McpOnRuby.logger
+        @clients = {}
+        @mutex = Mutex.new
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        
+        # Only handle GET requests for SSE
+        return [405, {}, ['Method not allowed']] unless request.get?
+        
+        # Security checks (reuse from RackMiddleware)
+        # ... security implementation similar to RackMiddleware
+        
+        # Handle SSE connection
+        handle_sse_connection(env, request)
+      end
+
+      private
+
+      def handle_sse_connection(env, request)
+        # Hijack the connection for SSE
+        if env['rack.hijack?']
+          env['rack.hijack'].call
+          io = env['rack.hijack_io']
+          
+          # Send SSE headers
+          io.write("HTTP/1.1 200 OK\r\n")
+          io.write("Content-Type: text/event-stream\r\n")
+          io.write("Cache-Control: no-cache\r\n")
+          io.write("Connection: keep-alive\r\n")
+          io.write("\r\n")
+          
+          # Register client
+          client_id = SecureRandom.uuid
+          register_client(client_id, io, request)
+          
+          # Keep connection alive
+          keep_alive_loop(client_id, io)
+        else
+          [500, {}, ['SSE not supported - server must support connection hijacking']]
+        end
+      end
+
+      def register_client(client_id, io, request)
+        @mutex.synchronize do
+          @clients[client_id] = {
+            io: io,
+            context: build_request_context(request),
+            last_seen: Time.now
+          }
+        end
+        
+        @logger.info("SSE client connected: #{client_id}")
+        
+        # Send welcome message
+        send_event(client_id, 'connected', { clientId: client_id })
+      end
+
+      def keep_alive_loop(client_id, io)
+        loop do
+          begin
+            # Send periodic ping
+            send_event(client_id, 'ping', { timestamp: Time.now.iso8601 })
+            sleep(30)
+            
+            # Check if client is still connected
+            break unless client_connected?(client_id)
+          rescue => error
+            @logger.warn("SSE client #{client_id} disconnected: #{error.message}")
+            break
+          end
+        end
+      ensure
+        unregister_client(client_id)
+      end
+
+      def send_event(client_id, event_type, data)
+        client = nil
+        @mutex.synchronize { client = @clients[client_id] }
+        return unless client
+        
+        begin
+          io = client[:io]
+          io.write("event: #{event_type}\n")
+          io.write("data: #{JSON.generate(data)}\n")
+          io.write("\n")
+          io.flush
+          
+          # Update last seen
+          @mutex.synchronize { @clients[client_id][:last_seen] = Time.now }
+        rescue => error
+          @logger.warn("Failed to send SSE event to #{client_id}: #{error.message}")
+          unregister_client(client_id)
+        end
+      end
+
+      def client_connected?(client_id)
+        @mutex.synchronize { @clients.key?(client_id) }
+      end
+
+      def unregister_client(client_id)
+        @mutex.synchronize do
+          client = @clients.delete(client_id)
+          if client
+            begin
+              client[:io].close
+            rescue => error
+              @logger.debug("Error closing SSE client connection: #{error.message}")
+            end
+          end
+        end
+        
+        @logger.info("SSE client disconnected: #{client_id}")
+      end
+
+      def build_request_context(request)
+        {
+          remote_ip: request.ip,
+          user_agent: request.user_agent,
+          headers: request.env.select { |k, _| k.start_with?('HTTP_') }
+        }
+      end
+
+      # Broadcast resource update to all connected clients
+      def broadcast_resource_update(uri, event_type = 'resource_updated')
+        return if @clients.empty?
+        
+        data = {
+          uri: uri,
+          timestamp: Time.now.iso8601
+        }
+        
+        @clients.keys.each do |client_id|
+          send_event(client_id, event_type, data)
+        end
+      end
+    end
+  end
+end

data/lib/mcp_on_ruby/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  VERSION = "1.0.0"
+  PROTOCOL_VERSION = "2024-11-05"
+end

data/lib/mcp_on_ruby.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'json'
+require 'json-schema'
+require 'rack'
+require 'webrick'
+
+require_relative 'mcp_on_ruby/version'
+require_relative 'mcp_on_ruby/errors'
+require_relative 'mcp_on_ruby/configuration'
+require_relative 'mcp_on_ruby/server'
+require_relative 'mcp_on_ruby/tool'
+require_relative 'mcp_on_ruby/resource'
+require_relative 'mcp_on_ruby/transport'
+
+# Rails integration if available
+if defined?(Rails)
+  require_relative 'mcp_on_ruby/railtie'
+end
+
+# Production-ready Model Context Protocol implementation for Rails
+module McpOnRuby
+  class << self
+    attr_writer :logger
+    attr_accessor :configuration
+
+    # Configure the library
+    # @yield [Configuration] The configuration object
+    # @return [Configuration] The configuration object
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Get the logger
+    # @return [Logger] The logger
+    def logger
+      @logger ||= Logger.new($stdout).tap do |log|
+        log.progname = 'McpOnRuby'
+        log.level = configuration&.log_level || Logger::INFO
+      end
+    end
+
+    # Create a new MCP server
+    # @param options [Hash] Server configuration options
+    # @yield [Server] The server instance for configuration
+    # @return [Server] The configured server
+    def server(options = {}, &block)
+      Server.new(options, &block)
+    end
+
+    # Create a tool with DSL
+    # @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 tool
+    def tool(name, description = '', input_schema = {}, **options, &block)
+      raise ArgumentError, 'Tool implementation block is required' unless block_given?
+
+      Class.new(Tool) do
+        define_method :execute do |arguments, context|
+          case block.arity
+          when 0
+            instance_exec(&block)
+          when 1
+            instance_exec(arguments, &block)
+          else
+            instance_exec(arguments, context, &block)
+          end
+        end
+      end.new(
+        name: name,
+        description: description,
+        input_schema: input_schema,
+        metadata: options[:metadata] || {},
+        tags: options[:tags] || []
+      )
+    end
+
+    # Create a resource with DSL
+    # @param uri [String] Resource URI
+    # @param options [Hash] Resource options (name, description, etc.)
+    # @param block [Proc] Resource implementation
+    # @return [Resource] The created resource
+    def resource(uri, **options, &block)
+      raise ArgumentError, 'Resource implementation block is required' unless block_given?
+
+      Class.new(Resource) do
+        define_method :fetch_content do |params, context|
+          case block.arity
+          when 0
+            instance_exec(&block)
+          when 1
+            instance_exec(params, &block)
+          else
+            instance_exec(params, context, &block)
+          end
+        end
+      end.new(
+        uri: uri,
+        name: options[:name],
+        description: options[:description] || '',
+        mime_type: options[:mime_type] || 'application/json',
+        metadata: options[:metadata] || {},
+        tags: options[:tags] || []
+      )
+    end
+
+    # Broadcast resource update to connected SSE clients
+    # @param uri [String] Resource URI that was updated
+    # @param event_type [String] Type of event
+    def broadcast_resource_update(uri, event_type = 'resource_updated')
+      # This would be implemented when SSE is fully integrated
+      logger.info("Resource update broadcasted: #{uri} (#{event_type})")
+    end
+
+    # Mount MCP server in Rails application
+    # @param app [Rails::Application] The Rails application
+    # @param options [Hash] Mounting options
+    # @yield [Server] The server instance for configuration
+    # @return [Server] The mounted server
+    def mount_in_rails(app, **options, &block)
+      server = self.server(options, &block)
+      
+      # Mount the transport middleware
+      app.config.middleware.use(
+        Transport::RackMiddleware,
+        server: server,
+        **options
+      )
+      
+      server
+    end
+  end
+end
+
+# Alias for convenience
+MCP = McpOnRuby