robot_lab 0.0.1

data/lib/robot_lab/mcp/server.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module MCP
+    # Configuration for an MCP server connection
+    #
+    # @example WebSocket transport
+    #   Server.new(
+    #     name: "neon",
+    #     transport: { type: "ws", url: "ws://localhost:8080" }
+    #   )
+    #
+    # @example StdIO transport
+    #   Server.new(
+    #     name: "filesystem",
+    #     transport: {
+    #       type: "stdio",
+    #       command: "mcp-server-filesystem",
+    #       args: ["--root", "/data"]
+    #     }
+    #   )
+    #
+    class Server
+      # Valid transport types for MCP connections
+      VALID_TRANSPORT_TYPES = %w[stdio sse ws websocket streamable-http http].freeze
+
+      # @!attribute [r] name
+      #   @return [String] the server name
+      # @!attribute [r] transport
+      #   @return [Hash] the transport configuration
+      attr_reader :name, :transport
+
+      # Creates a new Server configuration.
+      #
+      # @param name [String] the server name
+      # @param transport [Hash] the transport configuration
+      # @raise [ArgumentError] if transport type is invalid or required fields are missing
+      def initialize(name:, transport:)
+        @name = name.to_s
+        @transport = normalize_transport(transport)
+        validate!
+      end
+
+      # Returns the transport type.
+      #
+      # @return [String] the transport type (stdio, sse, ws, etc.)
+      def transport_type
+        @transport[:type]
+      end
+
+      # Converts the server configuration to a hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          name: name,
+          transport: transport
+        }
+      end
+
+      private
+
+      def normalize_transport(transport)
+        transport = transport.transform_keys(&:to_sym)
+        transport[:type] = transport[:type].to_s.downcase
+        transport
+      end
+
+      def validate!
+        unless VALID_TRANSPORT_TYPES.include?(transport_type)
+          raise ArgumentError, "Invalid transport type: #{transport_type}. " \
+                               "Must be one of: #{VALID_TRANSPORT_TYPES.join(', ')}"
+        end
+
+        case transport_type
+        when "stdio"
+          raise ArgumentError, "StdIO transport requires :command" unless transport[:command]
+        when "ws", "websocket", "sse", "streamable-http", "http"
+          raise ArgumentError, "Transport requires :url" unless transport[:url]
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/mcp/transports/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module MCP
+    module Transports
+      # Base class for MCP transports
+      #
+      # @abstract Subclass and implement {#connect}, {#send_request}, {#close}
+      #
+      class Base
+        # @!attribute [r] config
+        #   @return [Hash] the transport configuration
+        attr_reader :config
+
+        # Creates a new transport instance.
+        #
+        # @param config [Hash] transport configuration options
+        def initialize(config)
+          @config = config.transform_keys(&:to_sym)
+        end
+
+        # Connect to the server
+        #
+        # @return [self]
+        #
+        def connect
+          raise NotImplementedError
+        end
+
+        # Send a JSON-RPC request
+        #
+        # @param message [Hash] JSON-RPC message
+        # @return [Hash] Response
+        #
+        def send_request(message)
+          raise NotImplementedError
+        end
+
+        # Close the connection
+        #
+        # @return [self]
+        #
+        def close
+          raise NotImplementedError
+        end
+
+        # Check if the transport is connected.
+        #
+        # @return [Boolean] true if connected
+        def connected?
+          false
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/mcp/transports/sse.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module MCP
+    module Transports
+      # Server-Sent Events transport for MCP servers
+      #
+      # Uses async-http for SSE streaming.
+      #
+      # @example
+      #   transport = SSE.new(url: "http://localhost:8080/sse")
+      #
+      class SSE < Base
+        # Creates a new SSE transport.
+        #
+        # @param config [Hash] transport configuration
+        # @option config [String] :url SSE server URL
+        def initialize(config)
+          super
+          @client = nil
+          @connected = false
+          @event_queue = []
+        end
+
+        # Connect to the MCP server via SSE.
+        #
+        # @return [self]
+        # @raise [MCPError] if async-http gem is not available
+        def connect
+          return self if @connected
+
+          require "async"
+          require "async/http/client"
+          require "async/http/endpoint"
+
+          url = @config[:url]
+
+          Async do
+            endpoint = Async::HTTP::Endpoint.parse(url)
+            @client = Async::HTTP::Client.new(endpoint)
+            @connected = true
+
+            # Initialize MCP protocol
+            send_initialize
+          end
+
+          self
+        rescue LoadError => e
+          raise MCPError, "async-http gem required for SSE transport: #{e.message}"
+        end
+
+        # Send a JSON-RPC request to the MCP server.
+        #
+        # @param message [Hash] JSON-RPC message
+        # @return [Hash] the response
+        # @raise [MCPError] if not connected
+        def send_request(message)
+          raise MCPError, "Not connected" unless @connected
+
+          require "async"
+          require "async/http/body/writable"
+
+          Async do
+            # POST the request
+            response = @client.post(
+              @config[:url],
+              { "Content-Type" => "application/json" },
+              [message.to_json]
+            )
+
+            # Read response
+            body = response.read
+            JSON.parse(body, symbolize_names: true)
+          end.wait
+        end
+
+        # Close the SSE connection.
+        #
+        # @return [self]
+        def close
+          return self unless @connected
+
+          @client&.close
+          @connected = false
+          @client = nil
+
+          self
+        end
+
+        # Check if the transport is connected.
+        #
+        # @return [Boolean] true if connected
+        def connected?
+          @connected
+        end
+
+        private
+
+        def send_initialize
+          send_request(
+            jsonrpc: "2.0",
+            id: 0,
+            method: "initialize",
+            params: {
+              protocolVersion: "2024-11-05",
+              capabilities: {},
+              clientInfo: {
+                name: "RobotLab",
+                version: RobotLab::VERSION
+              }
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/mcp/transports/stdio.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module RobotLab
+  module MCP
+    module Transports
+      # StdIO transport for local MCP servers
+      #
+      # Spawns a subprocess and communicates via stdin/stdout.
+      #
+      # @example
+      #   transport = Stdio.new(
+      #     command: "mcp-server-filesystem",
+      #     args: ["--root", "/data"],
+      #     env: { "DEBUG" => "true" }
+      #   )
+      #
+      class Stdio < Base
+        # Creates a new Stdio transport.
+        #
+        # @param config [Hash] transport configuration
+        # @option config [String] :command the command to execute
+        # @option config [Array<String>] :args command arguments
+        # @option config [Hash] :env environment variables
+        def initialize(config)
+          super
+          @stdin = nil
+          @stdout = nil
+          @stderr = nil
+          @wait_thread = nil
+          @connected = false
+        end
+
+        # Connect to the MCP server via stdio.
+        #
+        # @return [self]
+        # @raise [MCPError] if connection fails
+        def connect
+          return self if @connected
+
+          command = @config[:command]
+          args = @config[:args] || []
+          env = @config[:env] || {}
+
+          # Merge with current environment
+          full_env = ENV.to_h.merge(env.transform_keys(&:to_s))
+
+          @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(full_env, command, *args)
+          @connected = true
+
+          # Initialize MCP protocol
+          send_initialize
+
+          self
+        end
+
+        # Send a JSON-RPC request to the MCP server.
+        #
+        # @param message [Hash] JSON-RPC message
+        # @return [Hash] the response
+        # @raise [MCPError] if not connected or no response
+        def send_request(message)
+          raise MCPError, "Not connected" unless @connected
+
+          # Write JSON-RPC message
+          json = message.to_json
+          @stdin.puts(json)
+          @stdin.flush
+
+          # Read response, skipping notifications
+          loop do
+            response_line = @stdout.gets
+            raise MCPError, "No response from MCP server" unless response_line
+
+            parsed = JSON.parse(response_line, symbolize_names: true)
+
+            # Skip notifications (messages without an id)
+            next if parsed[:method] && !parsed.key?(:id)
+
+            # Return responses (messages with an id)
+            return parsed
+          end
+        end
+
+        # Close the connection to the MCP server.
+        #
+        # @return [self]
+        def close
+          return self unless @connected
+
+          @stdin&.close
+          @stdout&.close
+          @stderr&.close
+          @wait_thread&.kill if @wait_thread&.alive?
+
+          @connected = false
+          self
+        end
+
+        # Check if the transport is connected.
+        #
+        # @return [Boolean] true if connected and process is alive
+        def connected?
+          @connected && @wait_thread&.alive?
+        end
+
+        private
+
+        def send_initialize
+          send_request(
+            jsonrpc: "2.0",
+            id: 0,
+            method: "initialize",
+            params: {
+              protocolVersion: "2024-11-05",
+              capabilities: {},
+              clientInfo: {
+                name: "RobotLab",
+                version: RobotLab::VERSION
+              }
+            }
+          )
+
+          # Send initialized notification
+          @stdin.puts({ jsonrpc: "2.0", method: "notifications/initialized" }.to_json)
+          @stdin.flush
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/mcp/transports/streamable_http.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module MCP
+    module Transports
+      # Streamable HTTP transport for MCP servers
+      #
+      # Supports session management and reconnection.
+      #
+      # @example
+      #   transport = StreamableHTTP.new(
+      #     url: "https://server.smithery.ai/neon/mcp",
+      #     session_id: "abc123"
+      #   )
+      #
+      class StreamableHTTP < Base
+        # Creates a new StreamableHTTP transport.
+        #
+        # @param config [Hash] transport configuration
+        # @option config [String] :url HTTP server URL
+        # @option config [String] :session_id optional session identifier
+        # @option config [Proc] :auth_provider optional authentication callback
+        def initialize(config)
+          super
+          @client = nil
+          @connected = false
+          @session_id = config[:session_id]
+        end
+
+        # Connect to the MCP server via HTTP.
+        #
+        # @return [self]
+        # @raise [MCPError] if async-http gem is not available
+        def connect
+          return self if @connected
+
+          require "async"
+          require "async/http/client"
+          require "async/http/endpoint"
+
+          url = @config[:url]
+
+          Async do
+            endpoint = Async::HTTP::Endpoint.parse(url)
+            @client = Async::HTTP::Client.new(endpoint)
+            @connected = true
+
+            # Initialize MCP protocol
+            result = send_initialize
+            @session_id ||= result.dig(:serverInfo, :sessionId)
+          end
+
+          self
+        rescue LoadError => e
+          raise MCPError, "async-http gem required for HTTP transport: #{e.message}"
+        end
+
+        # Send a JSON-RPC request to the MCP server.
+        #
+        # @param message [Hash] JSON-RPC message
+        # @return [Hash] the response
+        # @raise [MCPError] if not connected
+        def send_request(message)
+          raise MCPError, "Not connected" unless @connected
+
+          require "async"
+
+          Async do
+            headers = {
+              "Content-Type" => "application/json",
+              "Accept" => "application/json"
+            }
+            headers["X-Session-ID"] = @session_id if @session_id
+
+            # Add auth if configured
+            if @config[:auth_provider]
+              auth_header = @config[:auth_provider].call
+              headers["Authorization"] = auth_header if auth_header
+            end
+
+            response = @client.post(
+              @config[:url],
+              headers,
+              [message.to_json]
+            )
+
+            body = response.read
+            JSON.parse(body, symbolize_names: true)
+          end.wait
+        end
+
+        # Close the HTTP connection.
+        #
+        # @return [self]
+        def close
+          return self unless @connected
+
+          @client&.close
+          @connected = false
+          @client = nil
+
+          self
+        end
+
+        # Check if the transport is connected.
+        #
+        # @return [Boolean] true if connected
+        def connected?
+          @connected
+        end
+
+        # Returns the session identifier.
+        #
+        # @return [String, nil] the session ID
+        def session_id
+          @session_id
+        end
+
+        private
+
+        def send_initialize
+          send_request(
+            jsonrpc: "2.0",
+            id: 0,
+            method: "initialize",
+            params: {
+              protocolVersion: "2024-11-05",
+              capabilities: {},
+              clientInfo: {
+                name: "RobotLab",
+                version: RobotLab::VERSION
+              }
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/mcp/transports/websocket.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module MCP
+    module Transports
+      # WebSocket transport for MCP servers
+      #
+      # Uses async-websocket for non-blocking communication.
+      #
+      # @example
+      #   transport = WebSocket.new(url: "ws://localhost:8080")
+      #
+      class WebSocket < Base
+        # Creates a new WebSocket transport.
+        #
+        # @param config [Hash] transport configuration
+        # @option config [String] :url WebSocket server URL
+        def initialize(config)
+          super
+          @connection = nil
+          @connected = false
+          @pending_requests = {}
+        end
+
+        # Connect to the MCP server via WebSocket.
+        #
+        # @return [self]
+        # @raise [MCPError] if async-websocket gem is not available
+        def connect
+          return self if @connected
+
+          require "async"
+          require "async/websocket/client"
+
+          url = @config[:url]
+
+          Async do
+            endpoint = Async::HTTP::Endpoint.parse(url)
+            @connection = Async::WebSocket::Client.connect(endpoint)
+            @connected = true
+
+            # Initialize MCP protocol
+            send_initialize
+          end
+
+          self
+        rescue LoadError => e
+          raise MCPError, "async-websocket gem required for WebSocket transport: #{e.message}"
+        end
+
+        # Send a JSON-RPC request to the MCP server.
+        #
+        # @param message [Hash] JSON-RPC message
+        # @return [Hash] the response
+        # @raise [MCPError] if not connected
+        def send_request(message)
+          raise MCPError, "Not connected" unless @connected
+
+          Async do
+            @connection.write(message.to_json)
+            @connection.flush
+
+            response_text = @connection.read
+            JSON.parse(response_text, symbolize_names: true)
+          end.wait
+        end
+
+        # Close the WebSocket connection.
+        #
+        # @return [self]
+        def close
+          return self unless @connected
+
+          @connection&.close
+          @connected = false
+          @connection = nil
+
+          self
+        end
+
+        # Check if the transport is connected.
+        #
+        # @return [Boolean] true if connected
+        def connected?
+          @connected
+        end
+
+        private
+
+        def send_initialize
+          send_request(
+            jsonrpc: "2.0",
+            id: 0,
+            method: "initialize",
+            params: {
+              protocolVersion: "2024-11-05",
+              capabilities: {},
+              clientInfo: {
+                name: "RobotLab",
+                version: RobotLab::VERSION
+              }
+            }
+          )
+        end
+      end
+    end
+  end
+end