encom 0.1.0

data/lib/encom/error_codes.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Encom
+  # Defines standard JSON-RPC error codes and MCP-specific error codes
+  module ErrorCodes
+    # Standard JSON-RPC error codes
+    PARSE_ERROR = -32_700
+    INVALID_REQUEST = -32_600
+    METHOD_NOT_FOUND = -32_601
+    INVALID_PARAMS = -32_602
+    INTERNAL_ERROR = -32_603
+
+    # MCP specific error codes
+    TOOL_EXECUTION_ERROR = -32_000
+    PROTOCOL_ERROR = -32_001
+  end
+end

data/lib/encom/server/tool.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Encom
+  class Server
+    class Tool
+      attr_reader :name, :description, :schema
+
+      # Initialize a new tool
+      #
+      # @param name [Symbol, String] The name of the tool
+      # @param description [String] A description of what the tool does
+      # @param schema [Hash] A hash describing the input schema for the tool
+      # @param proc [Proc] A proc that implements the tool's functionality
+      def initialize(name:, description:, schema:, proc:)
+        @name = name
+        @description = description
+        @schema = schema
+        @proc = proc
+      end
+
+      def definition
+        {
+          name: @name.to_s,
+          description: @description,
+          inputSchema: schema_definition
+        }.compact
+      end
+
+      def call(arguments)
+        result = nil
+        
+        begin
+          if @proc.parameters.first && @proc.parameters.first[0] == :keyreq
+            # If the proc expects keyword arguments, pass the arguments hash
+            result = @proc.call(**arguments)
+          else
+            # Otherwise, pass arguments as an array
+            result = @proc.call(*arguments)
+          end
+          
+          # Ensure the result is in the standard format
+          standardize_tool_response(result)
+        rescue StandardError => e
+          # Return error in MCP-compliant format as per docs
+          {
+            isError: true,
+            content: [
+              {
+                type: 'text',
+                text: "Error: #{e.message}"
+              }
+            ]
+          }
+        end
+      end
+
+      private
+
+      # Standardize tool response to ensure it conforms to the MCP format
+      # 
+      # @param result [Hash, String, Array, Object] The raw result from the tool proc
+      # @return [Hash] A standardized response hash with content array
+      def standardize_tool_response(result)
+        # If the result is already in the expected format (has content array), return it
+        return result if result.is_a?(Hash) && result[:content].is_a?(Array)
+        
+        # If it's a hash with isError, leave it as is
+        return result if result.is_a?(Hash) && result[:isError]
+        
+        # If it's a string, convert to text content
+        if result.is_a?(String)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: result
+              }
+            ]
+          }
+        end
+        
+        # If it's an array, assume it's already a content array
+        if result.is_a?(Array)
+          return {
+            content: result
+          }
+        end
+        
+        # For any other type, convert to string and wrap as text
+        {
+          content: [
+            {
+              type: 'text',
+              text: result.to_s
+            }
+          ]
+        }
+      end
+
+      def schema_definition
+        properties = {}
+        required = []
+
+        @schema.each do |key, value|
+          properties[key] = if value.is_a?(Hash)
+                              {
+                                type: ruby_type_to_json_type(value[:type]),
+                                description: value[:description]
+                              }.compact
+                            else
+                              {
+                                type: ruby_type_to_json_type(value)
+                              }.compact
+                            end
+        end
+
+        @proc.parameters.each do |param_type, param_name|
+          required << param_name.to_s if param_type == :keyreq
+        end
+
+        {
+          type: 'object',
+          properties: properties,
+          required: required
+        }
+      end
+
+      def ruby_type_to_json_type(type)
+        return nil unless type
+
+        case type.to_s
+        when 'Integer'
+          'number'
+        when 'String'
+          'string'
+        when 'TrueClass', 'FalseClass', 'Boolean'
+          'boolean'
+        when 'Float'
+          'number'
+        when 'Array'
+          'array'
+        when 'Hash'
+          'object'
+        else
+          type.to_s.downcase
+        end
+      end
+    end
+  end
+end

data/lib/encom/server.rb

@@ -0,0 +1,294 @@
+require 'encom/server/tool'
+require 'json'
+
+module Encom
+  class Server
+    LATEST_PROTOCOL_VERSION = '2024-11-05'
+    SUPPORTED_PROTOCOL_VERSIONS = [
+      LATEST_PROTOCOL_VERSION
+      # Add more supported versions as they're developed
+    ].freeze
+
+    class << self
+      def name(server_name = nil)
+        @server_name ||= server_name
+      end
+
+      def version(version = nil)
+        @version ||= version
+      end
+
+      def tool(tool_name, description, schema, proc)
+        @tools ||= []
+        @tools << Tool.new(name: tool_name, description:, schema:, proc:)
+      end
+
+      attr_reader :tools
+    end
+
+    attr_reader :transport, :capabilities
+
+    def initialize(options = {})
+      @message_id = 0
+      @capabilities = options[:capabilities] || {
+        roots: {
+          listChanged: true
+        },
+        sampling: {},
+        tools: {}
+      }
+      
+      # Validate protocol version immediately
+      protocol_version = options[:protocol_version] || LATEST_PROTOCOL_VERSION
+      unless SUPPORTED_PROTOCOL_VERSIONS.include?(protocol_version)
+        raise ArgumentError, "Unsupported protocol version: #{protocol_version}. Supported versions: #{SUPPORTED_PROTOCOL_VERSIONS.join(', ')}"
+      end
+      
+      @protocol_version = protocol_version
+      @transport = nil
+    end
+
+    def name
+      self.class.name
+    end
+
+    def version
+      self.class.version
+    end
+
+    def tools
+      self.class.tools
+    end
+
+    def call_tool(name, arguments)
+      tool = tools.find { |t| t.name.to_s == name.to_s || t.name == name.to_sym }
+      raise "Unknown tool: #{name}" unless tool
+      tool.call(arguments)
+    end
+
+    # Run the server with the specified transport
+    def run(transport_class, transport_options = {})
+      @transport = transport_class.new(self, transport_options)
+      @transport.start
+    rescue StandardError => e
+      $stderr.puts "Error running server: #{e.message}"
+      $stderr.puts e.backtrace.join("\n") if transport_options[:debug]
+      raise
+    end
+
+    # Process incoming JSON-RPC message
+    def process_message(message)
+      return unless message.is_a?(Hash)
+
+      if @transport && @transport.respond_to?(:debug)
+        @transport.debug "Processing message: #{message.inspect}"
+      end
+
+      # Check for jsonrpc version
+      unless message[:jsonrpc] == '2.0'
+        if message[:id]
+          respond_error(message[:id], Encom::ErrorCodes::INVALID_REQUEST, 'Invalid JSON-RPC request')
+        end
+        return
+      end
+
+      # Process request by method
+      case message[:method]
+      when 'initialize'
+        handle_initialize(message)
+      when 'initialized'
+        handle_initialized(message)
+      when 'resources/list'
+        handle_resources_list(message)
+      when 'roots/list'
+        handle_roots_list(message)
+      when 'sampling/prepare'
+        handle_sampling_prepare(message)
+      when 'sampling/sample'
+        handle_sampling_sample(message)
+      when 'tools/list'
+        handle_tools_list(message)
+      when 'tools/call'
+        handle_tools_call(message)
+      when 'shutdown'
+        handle_shutdown(message)
+      else
+        if message[:id]
+          if @transport && @transport.respond_to?(:debug)
+            @transport.debug "Unknown method: #{message[:method]}"
+          end
+          respond_error(message[:id], Encom::ErrorCodes::METHOD_NOT_FOUND, "Method not found: #{message[:method]}")
+        end
+      end
+    rescue StandardError => e
+      if @transport && @transport.respond_to?(:debug)
+        @transport.debug "Error processing message: #{e.message}\n#{e.backtrace.join("\n")}"
+      end
+      
+      if message && message[:id]
+        respond_error(message[:id], Encom::ErrorCodes::INTERNAL_ERROR, "Internal error: #{e.message}")
+      end
+    end
+
+    # Generate and send a JSON-RPC response
+    def respond(id, result)
+      return unless @transport
+
+      response = {
+        jsonrpc: "2.0",
+        id: id,
+        result: result
+      }
+
+      @transport.send_message(response)
+    end
+
+    # Generate and send a JSON-RPC error response
+    def respond_error(id, code, message, data = nil)
+      return unless @transport
+
+      response = {
+        jsonrpc: "2.0",
+        id: id,
+        error: {
+          code: code,
+          message: message
+        }
+      }
+      response[:error][:data] = data if data
+
+      @transport.send_message(response)
+    end
+
+    # Handle initialize request
+    def handle_initialize(message)
+      client_protocol_version = message[:params][:protocolVersion]
+      client_capabilities = message[:params][:capabilities]
+      client_info = message[:params][:clientInfo]
+
+      server_info = {
+        name: name,
+        version: version
+      }
+
+      # Debug log the received protocol version
+      if @transport && @transport.respond_to?(:debug)
+        @transport.debug "Received initialize request with protocol version: #{client_protocol_version}"
+        @transport.debug "Supported protocol versions: #{SUPPORTED_PROTOCOL_VERSIONS.inspect}"
+      end
+
+      # Check if the requested protocol version is supported
+      if SUPPORTED_PROTOCOL_VERSIONS.include?(client_protocol_version)
+        # Use the requested version if supported
+        protocol_version = client_protocol_version
+        
+        if @transport && @transport.respond_to?(:debug)
+          @transport.debug "Protocol version #{protocol_version} is supported, sending success response"
+        end
+        
+        # Send initialize response
+        respond(message[:id], {
+          protocolVersion: protocol_version,
+          capabilities: @capabilities,
+          serverInfo: server_info
+        })
+      else
+        # Return an error for unsupported protocol versions
+        if @transport && @transport.respond_to?(:debug)
+          @transport.debug "Protocol version error: Client requested unsupported version #{client_protocol_version}"
+        end
+        
+        respond_error(
+          message[:id],
+          Encom::ErrorCodes::PROTOCOL_ERROR,
+          "Unsupported protocol version: #{client_protocol_version}",
+          { supportedVersions: SUPPORTED_PROTOCOL_VERSIONS }
+        )
+      end
+    end
+
+    # Handle initialized notification
+    def handle_initialized(message)
+      # No response needed for notifications
+    end
+
+    # Handle resources/list request
+    def handle_resources_list(message)
+      # Default implementation returns an empty list
+      respond(message[:id], {
+        resources: []
+      })
+    end
+
+    # Handle roots/list request
+    def handle_roots_list(message)
+      # Default implementation returns an empty list
+      respond(message[:id], {
+        roots: []
+      })
+    end
+
+    # Handle sampling/prepare request
+    def handle_sampling_prepare(message)
+      # Default implementation returns a simple response
+      respond(message[:id], {
+        prepared: false,
+        samplingId: nil
+      })
+    end
+
+    # Handle sampling/sample request
+    def handle_sampling_sample(message)
+      # Default implementation returns a simple response
+      respond(message[:id], {
+        completion: "Sampling not implemented",
+        completionId: nil
+      })
+    end
+
+    # Handle tools/list request
+    def handle_tools_list(message)
+      tool_definitions = tools ? tools.map(&:definition) : []
+      
+      respond(message[:id], {
+        tools: tool_definitions
+      })
+    end
+
+    # Handle tools/call request
+    def handle_tools_call(message)
+      tool_name = message[:params][:name]
+      arguments = message[:params][:arguments] || {}
+      
+      begin
+        result = call_tool(tool_name, arguments)
+        respond(message[:id], result)
+      rescue StandardError => e
+        respond_error(message[:id], Encom::ErrorCodes::TOOL_EXECUTION_ERROR, "Tool execution error: #{e.message}")
+      end
+    end
+
+    # Handle JSON-RPC shutdown request
+    def handle_shutdown(message)
+      if message[:id]
+        # If it's a request with ID, respond with a success result
+        respond(message[:id], {
+          shutdown: true
+        })
+      end
+      # Initiate clean shutdown
+      shutdown
+    end
+
+    # Shutdown the server and clean up
+    def shutdown
+      return if @shutting_down
+      @shutting_down = true
+      
+      if @transport
+        @transport.stop
+        @transport = nil
+      end
+    end
+  end
+end

data/lib/encom/server_transport/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Encom
+  module ServerTransport
+    class Base
+      attr_reader :server
+
+      def initialize(server, options = {})
+        @server = server
+        @options = options
+        @debug = options[:debug] || false
+      end
+
+      # Start the transport - must be implemented by subclasses
+      def start
+        raise NotImplementedError, 'Subclasses must implement #start'
+      end
+
+      # Stop the transport - must be implemented by subclasses
+      def stop
+        raise NotImplementedError, 'Subclasses must implement #stop'
+      end
+
+      # Send a message through the transport - must be implemented by subclasses
+      def send_message(message)
+        raise NotImplementedError, 'Subclasses must implement #send_message'
+      end
+
+      # Process an incoming message - default implementation delegates to server
+      def process_message(message)
+        @server.process_message(message)
+      end
+
+      # Log debug information if debug is enabled
+      def debug(message)
+        return unless @debug
+
+        warn "[Encom::ServerTransport] #{message}"
+      end
+    end
+  end
+end

data/lib/encom/server_transport/stdio.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'encom/server_transport/base'
+
+module Encom
+  module ServerTransport
+    class Stdio < Base
+      def start
+        debug 'Starting StdIO transport server'
+        debug 'Listening on stdin, writing to stdout...'
+
+        # Enable line buffering for stdout
+        $stdout.sync = true
+
+        # Set up signal handlers for graceful shutdown
+        setup_signal_handlers
+
+        @running = true
+
+        # Process messages until stdin is closed or shutdown is requested
+        while @running && (line = $stdin.gets)
+          begin
+            message = JSON.parse(line, symbolize_names: true)
+            debug "Received: #{message.inspect}"
+            process_message(message)
+          rescue JSON::ParserError => e
+            debug "Error parsing message: #{e.message}"
+            next
+          rescue StandardError => e
+            debug "Error processing message: #{e.message}"
+            next
+          end
+        end
+
+        debug 'StdIO transport server stopped'
+      end
+
+      def stop
+        debug 'Stopping StdIO transport server'
+        @running = false
+        # No specific cleanup needed for stdio beyond setting running to false
+      end
+
+      def send_message(message)
+        json = JSON.generate(message)
+        debug "Sending: #{message.inspect}"
+        puts json # Write to stdout
+        $stdout.flush
+        true
+      end
+
+      def debug(message)
+        return unless @debug
+
+        warn "[Encom::ServerTransport::Stdio] #{message}"
+      end
+
+      private
+
+      def setup_signal_handlers
+        # Handle INT (CTRL+C) and TERM signals for graceful shutdown
+        trap('INT') { handle_signal('INT') }
+        trap('TERM') { handle_signal('TERM') }
+      end
+
+      def handle_signal(signal)
+        debug "Received #{signal} signal, shutting down..."
+        stop
+      end
+    end
+  end
+end