swagger_mcp_tool 0.1.1

data/lib/swagger_mcp_tool/api_client.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'net/http'
+require 'openssl'
+require 'json'
+require 'mcp'
+require_relative 'helpers/request'
+require_relative 'logging'
+require_relative 'config'
+
+module SwaggerMCPTool
+  # The SwaggerMCPTool module provides tools and utilities for interacting with APIs
+  # using Swagger/OpenAPI specifications. It includes classes and helpers for making
+  # HTTP requests, handling responses, logging, and managing configuration.
+  #
+  # This module is intended to be used as part of the swagger_mcp_tool library,
+  # facilitating API client operations with robust error handling and logging.
+  #
+  # Example usage:
+  #   client = SwaggerMCPTool::ApiClient.new("https://api.example.com")
+  #   response = client.make_request(:get, "/v1/resource", { id: 123 })
+  #
+  # @see SwaggerMCPTool::ApiClient
+  # @see SwaggerMCPTool::Helpers::Request
+  # @see SwaggerMCPTool::Logging
+  class ApiClient
+    include SwaggerMCPTool::Helpers::Request
+    include SwaggerMCPTool::Logging
+
+    def initialize(base_url)
+      @base_url = base_url.chomp('/')
+      @config = Config.instance
+    end
+
+    def make_request(method, path, params = {}, headers = {}, server_context = {})
+      request_context = build_request_context(method, path, params, headers, server_context)
+
+      log_request_details(request_context)
+
+      response = execute_http_request(request_context)
+      process_response(response)
+    rescue StandardError => e
+      handle_request_error(e)
+    end
+
+    private
+
+    def execute_http_request(context)
+      processed_path, remaining_params = process_path_parameters(context[:original_path], context[:params])
+      uri = build_request_uri(processed_path, context[:method], remaining_params)
+
+      @config.logger.debug "Final URI: #{uri}"
+
+      http_client = create_http_client(uri)
+      request = create_http_request(context[:method], uri, remaining_params)
+
+      add_headers_to_request(request, context[:headers], context[:auth_token])
+
+      log_request_execution(context[:method], uri)
+      http_client.request(request)
+    end
+
+    def create_http_client(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+
+      configure_ssl(http, uri)
+      configure_timeouts(http)
+
+      http
+    end
+
+    def configure_ssl(http, uri)
+      return unless uri.scheme == 'https'
+
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+    end
+
+    def configure_timeouts(http)
+      http.open_timeout = 10
+      http.read_timeout = 30
+    end
+
+    def process_response(response)
+      if response.is_a?(Net::HTTPSuccess)
+        process_success_response(response)
+      else
+        process_error_response(response)
+      end
+    end
+
+    def process_success_response(response)
+      parsed_response = parse_response_body(response.body)
+
+      @config.logger.debug "API Response: #{parsed_response.inspect}"
+
+      create_mcp_response(format_success_response(parsed_response))
+    end
+
+    def process_error_response(response)
+      error_message = build_error_message(response)
+
+      @config.logger.error "API request failed: #{response.code} #{response.message}"
+      @config.logger.error "Response body: #{response.body}"
+
+      create_mcp_response(error_message)
+    end
+
+    def parse_response_body(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def format_success_response(parsed_response)
+      case parsed_response
+      when Hash, Array
+        JSON.pretty_generate(parsed_response)
+      else
+        parsed_response.to_s
+      end
+    end
+
+    def build_error_message(response)
+      error_message = "Error: #{response.code} #{response.message}\n"
+
+      error_body = parse_response_body(response.body)
+      error_message += case error_body
+                       when Hash, Array
+                         JSON.pretty_generate(error_body)
+                       else
+                         error_body.to_s
+                       end
+
+      error_message
+    end
+
+    def create_mcp_response(text)
+      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    end
+
+    def handle_request_error(error)
+      @config.logger.error "Error making API request: #{error.message}"
+      @config.logger.error error.backtrace.join("\n")
+
+      create_mcp_response("Error: #{error.message}")
+    end
+
+    def sanitize_headers_for_logging(headers)
+      headers.inspect.gsub(/"Authorization"=>"[^"]+"/, '"Authorization"=>"[REDACTED]"')
+    end
+  end
+end

data/lib/swagger_mcp_tool/auth_handler.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module SwaggerMCPTool
+  class AuthHandler
+    # Initialize with optional default auth settings
+    def initialize(default_auth = {})
+      @config = Config.instance
+      @default_auth = default_auth || {}
+      @auth_tokens = {}
+    end
+
+    # Set auth token for a user
+    def set_auth_token(user_id, token)
+      @auth_tokens[user_id.to_s] = token
+      @config.logger.info "Auth token set for user: #{user_id}"
+    end
+
+    # Get auth token for a user
+    def get_auth_token(user_id)
+      @auth_tokens[user_id.to_s] || @default_auth[:token] || @config.default_token
+    end
+
+    # Clear auth token for a user
+    def clear_auth_token(user_id)
+      @auth_tokens.delete(user_id.to_s)
+      @config.logger.info "Auth token cleared for user: #{user_id}"
+    end
+
+    # Check if a user has an auth token
+    def has_auth_token?(user_id)
+      @auth_tokens.key?(user_id.to_s) || @default_auth[:token].nil? == false || @config.default_token.nil? == false
+    end
+
+    # Get auth headers for a request
+    def get_auth_headers(user_id, api_key_header = nil)
+      headers = {}
+
+      token = get_auth_token(user_id)
+      if token
+        headers['Authorization'] = token.start_with?('Bearer ', 'Token ', 'Basic ') ? token : "Bearer #{token}"
+      end
+
+      # Add API key if provided
+      headers[api_key_header] = @default_auth[:api_key] if api_key_header && @default_auth[:api_key]
+
+      headers
+    end
+
+    # Process auth from Swagger security definitions
+    def process_swagger_security(swagger_spec)
+      return {} unless swagger_spec['securityDefinitions'] || swagger_spec['components']&.dig('securitySchemes')
+
+      # Get security definitions based on Swagger/OpenAPI version
+      security_defs = if swagger_spec['swagger'] == '2.0'
+                        swagger_spec['securityDefinitions'] || {}
+                      else
+                        swagger_spec['components']&.dig('securitySchemes') || {}
+                      end
+
+      auth_config = {}
+
+      security_defs.each_value do |definition|
+        type = definition['type']&.downcase
+
+        case type
+        when 'apikey'
+          auth_config[:api_key_name] = definition['name']
+          auth_config[:api_key_in] = definition['in'] # 'header' or 'query'
+        when 'oauth2', 'http'
+          scheme = definition['scheme']&.downcase
+          if scheme == 'bearer' || definition['bearerFormat'] || type == 'oauth2'
+            auth_config[:token_type] = 'Bearer'
+          elsif scheme == 'basic'
+            auth_config[:token_type] = 'Basic'
+          end
+        end
+      end
+
+      auth_config
+    end
+  end
+end

data/lib/swagger_mcp_tool/config.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'singleton'
+
+module SwaggerMCPTool
+  # Configuration management for SwaggerMCPTool
+  #
+  # This class uses the Singleton pattern to ensure a single configuration
+  # instance throughout the application lifecycle.
+  class Config
+    include Singleton
+
+    attr_accessor :server_port, :server_bind, :server_type,
+                  :log_level, :log_file, :swagger_url, :mcp_name,
+                  :mcp_name_for_human, :mcp_description_for_human,
+                  :mcp_description_for_model, :auth_type, :default_token,
+                  :prompts, :resources, :auth_header_name, :tools
+
+    DEFAULT_SERVER_PORT = 3001
+    DEFAULT_SERVER_BIND = '0.0.0.0'
+    DEFAULT_SERVER_TYPE = :puma
+    DEFAULT_LOG_LEVEL = Logger::INFO
+    DEFAULT_AUTH_HEADER_NAME = 'Token'
+    DEFAULT_SWAGGER_URL = 'https://petstore.swagger.io/v2/swagger.json'
+    DEFAULT_MCP_NAME = 'swagger_api_tools'
+    DEFAULT_MCP_NAME_FOR_HUMAN = 'Swagger API Tools'
+    DEFAULT_MCP_DESCRIPTION_FOR_HUMAN = 'Tools for interacting with APIs via Swagger/OpenAPI specifications'
+    DEFAULT_MCP_DESCRIPTION_FOR_MODEL = 'This MCP server provides tools for interacting with APIs via Swagger/OpenAPI specifications.'
+    DEFAULT_AUTH_TYPE = 'none'
+    DEFAULT_LOG_FILE = nil
+
+    def initialize
+      # Server settings
+      setup_server_defaults
+
+      # Swagger settings
+      setup_swagger_defaults
+
+      # MCP settings
+      setup_mcp_defaults
+
+      # Auth settings
+      setup_auth_defaults
+
+      # Tools, Prompts and resources
+      @tools = []
+      @resources = []
+      @prompts = [] # Will be generated lazily
+    end
+
+    def setup_server_defaults
+      @server_port = DEFAULT_SERVER_PORT
+      @server_bind = DEFAULT_SERVER_BIND
+      @server_type = DEFAULT_SERVER_TYPE
+      @log_level = DEFAULT_LOG_LEVEL
+      @log_file = nil
+      @auth_header_name = DEFAULT_AUTH_HEADER_NAME
+    end
+
+    def setup_swagger_defaults
+      @swagger_url = DEFAULT_SWAGGER_URL
+    end
+
+    def setup_mcp_defaults
+      @mcp_name = DEFAULT_MCP_NAME
+      @mcp_name_for_human = DEFAULT_MCP_NAME_FOR_HUMAN
+      @mcp_description_for_human = DEFAULT_MCP_DESCRIPTION_FOR_HUMAN
+      @mcp_description_for_model = DEFAULT_MCP_DESCRIPTION_FOR_MODEL
+    end
+
+    def setup_auth_defaults
+      @auth_type = DEFAULT_AUTH_TYPE
+      @default_token = nil
+    end
+
+    # Get the logger
+    def logger
+      @logger ||= create_logger
+    end
+
+    def create_logger
+      create_file_logger
+    rescue StandardError => e
+      logger = Logger.new($stdout)
+      logger.level = @log_level
+      logger.warn "Could not create log file #{@log_file} (#{e.message}), using stderr for logging"
+      logger
+    end
+
+    def create_file_logger
+      target = case @log_file
+               when $stdout, $stdout, 'STDOUT', 'stdout'
+                 $stdout
+               when $stderr, $stderr, 'STDERR', 'stderr'
+                 $stderr
+               when nil, ''
+                 $stderr
+               else
+                 @log_file
+               end
+      logger = Logger.new(target)
+      logger.level = @log_level
+      logger
+    end
+
+    # Configure the instance
+    def self.configure
+      return unless block_given?
+
+      config_instance = instance
+      yield config_instance
+      log_configuration_details(config_instance)
+      config_instance
+    rescue StandardError => e
+      config_instance.logger.error "Configuration failed: #{e.message}"
+      raise e
+    end
+
+    # Get server context
+    def to_context(request)
+      auth_header_name = self.auth_header_name || 'Authorization'
+      {
+        user_id: request.env['HTTP_X_USER_ID'] || '1',
+        auth_header_name.to_sym => request.env['HTTP_X_AUTH_TOKEN'],
+        username: request.env['HTTP_X_USERNAME'],
+        email: request.env['HTTP_X_EMAIL']
+      }
+    end
+
+    def self.log_configuration_details(config_instance)
+      logger = config_instance.logger
+      logger.info '=== CONFIGURATION COMPLETE ==='
+      logger.info  'Final config values:'
+      logger.info  "  server_port: #{config_instance.server_port}"
+      logger.info  "  mcp_name: #{config_instance.mcp_name}"
+      logger.info  "  auth_header_name: #{config_instance.auth_header_name}"
+      logger.info  "  prompts: #{config_instance.prompts}"
+    end
+
+    private_class_method :log_configuration_details
+  end
+end

data/lib/swagger_mcp_tool/helpers/parameter_processor.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module SwaggerMCPTool
+  module Helpers
+    module ParameterProcessor
+      SWAGGER_TO_JSON_SCHEMA_TYPES = {
+        'file' => 'string',
+        'integer' => 'integer',
+        'int' => 'integer',
+        'int32' => 'integer',
+        'int64' => 'integer',
+        'number' => 'number',
+        'float' => 'number',
+        'double' => 'number',
+        'boolean' => 'boolean',
+        'bool' => 'boolean',
+        'array' => 'array',
+        'object' => 'object'
+      }.freeze
+
+      private
+
+      def add_parameters_to_tool(tool_definition, operation)
+        parameters = operation['parameters']
+        return unless parameters.is_a?(Array)
+
+        parameters.each do |param|
+          process_single_parameter(tool_definition, param)
+        end
+      end
+
+      def process_single_parameter(tool_definition, param)
+        return if skip_parameter?(param)
+
+        resolved_param = resolve_parameter_reference(param)
+        return unless valid_parameter?(resolved_param)
+
+        add_parameter_to_schema(tool_definition, resolved_param)
+      end
+
+      def skip_parameter?(param)
+        param['in'] == 'header'
+      end
+
+      def resolve_parameter_reference(param)
+        return param unless param['$ref']
+
+        resolve_swagger_reference(param['$ref'])
+      rescue StandardError => e
+        @config.logger.debug "Failed to resolve parameter reference: #{e.message}"
+        param
+      end
+
+      def resolve_swagger_reference(ref_path)
+        return nil unless ref_path.is_a?(String)
+
+        path_parts = ref_path.sub('#/', '').split('/')
+        path_parts.reduce(@swagger_client.swagger_spec) { |acc, part| acc[part] }
+      end
+
+      def valid_parameter?(param)
+        param.is_a?(Hash) && param['name'].is_a?(String)
+      end
+
+      def add_parameter_to_schema(tool_definition, param)
+        param_name = param['name']
+        param_type = normalize_parameter_type(param['type'])
+
+        tool_definition['parameters']['properties'][param_name] = {
+          'type' => param_type,
+          'description' => param['description'] || param_name
+        }
+
+        return unless param['required']
+
+        tool_definition['parameters']['required'] << param_name
+      end
+
+      def normalize_parameter_type(swagger_type)
+        SWAGGER_TO_JSON_SCHEMA_TYPES[swagger_type] || 'string'
+      end
+    end
+  end
+end

data/lib/swagger_mcp_tool/helpers/request.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'net/http'
+require 'json'
+
+module SwaggerMCPTool
+  module Helpers
+    # Helper for HTTP request building and execution
+    module Request
+      def build_request_context(method, path, params, headers, server_context)
+        {
+          method: method.downcase,
+          original_path: path,
+          params: params,
+          headers: headers,
+          auth_token: server_context[@config.auth_header_name]
+        }
+      end
+
+      def create_http_request(method, uri, params)
+        req_method = request_methods(method.downcase)
+        request = req_method.new(uri.request_uri)
+
+        set_json_body(request, params) if body_required?(method.downcase)
+        request
+      end
+
+      def body_required?(method)
+        %w[post put patch].include?(method)
+      end
+
+      def request_methods(method)
+        {
+          get: Net::HTTP::Get,
+          post: Net::HTTP::Post,
+          put: Net::HTTP::Put,
+          delete: Net::HTTP::Delete,
+          patch: Net::HTTP::Patch
+        }[method] || Net::HTTP::Get
+      end
+
+      def set_json_body(request, params)
+        return if params.empty?
+
+        request.body = params.to_json
+        request.content_type = 'application/json'
+      end
+
+      def build_request_uri(path, method, params)
+        uri = URI("#{@base_url}#{path}")
+
+        # Add query parameters only for GET requests
+        uri.query = URI.encode_www_form(params) if method == 'get' && !params.empty?
+
+        uri
+      end
+
+      def add_headers_to_request(request, headers, auth_token)
+        # Add custom headers
+        headers.each { |key, value| request[key] = value }
+
+        # Add authorization header if available
+        add_authorization_header(request, auth_token)
+      end
+
+      def add_authorization_header(request, auth_token)
+        return unless auth_token && @config.auth_header_name
+
+        request[@config.auth_header_name] = auth_token
+        @config.logger.info 'Added authorization header for request'
+      end
+
+      def process_path_parameters(path, params)
+        return [path, params] unless path_has_placeholders?(path)
+
+        processed_path = path.dup
+        used_params = substitute_path_placeholders!(processed_path, params)
+        remaining_params = filter_unused_params(params, used_params)
+
+        [processed_path, remaining_params]
+      end
+
+      private
+
+      def path_has_placeholders?(path)
+        path.include?('{')
+      end
+
+      def substitute_path_placeholders!(path, params)
+        used_params = []
+
+        params.each do |key, value|
+          placeholder = "{#{key}}"
+
+          if path.include?(placeholder)
+            path.gsub!(placeholder, encode_path_value(value))
+            used_params << key
+          end
+        end
+
+        used_params
+      end
+
+      def encode_path_value(value)
+        URI.encode_www_form_component(value.to_s)
+      end
+
+      def filter_unused_params(params, used_params)
+        params.reject { |key, _| used_params.include?(key) }
+      end
+    end
+  end
+end

data/lib/swagger_mcp_tool/helpers/request_body_processor.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module SwaggerMCPTool
+  module Helpers
+    module RequestBodyProcessor
+      private
+
+      def add_request_body_to_tool(tool_definition, operation)
+        request_body = operation['requestBody']
+        return unless request_body_present?(request_body)
+
+        process_request_body_content(tool_definition, request_body['content'])
+      rescue StandardError => e
+        @config.logger.debug "Failed to process request body: #{e.message}"
+      end
+
+      def request_body_present?(request_body)
+        request_body && request_body['content']
+      end
+
+      def process_request_body_content(tool_definition, content)
+        return unless content.is_a?(Hash)
+
+        content_type = select_content_type(content)
+        return unless content_type
+
+        schema = extract_schema_from_content(content, content_type)
+        add_schema_properties_to_tool(tool_definition, schema) if schema
+      end
+
+      def select_content_type(content)
+        content.keys.first
+      end
+
+      def extract_schema_from_content(content, content_type)
+        content.dig(content_type, 'schema')
+      end
+
+      def add_schema_properties_to_tool(tool_definition, schema)
+        properties = schema['properties']
+        return unless properties.is_a?(Hash)
+
+        properties.each do |name, property|
+          add_property_to_tool(tool_definition, name, property)
+        end
+
+        add_required_fields_to_tool(tool_definition, schema['required'])
+      end
+
+      def add_property_to_tool(tool_definition, name, property)
+        tool_definition['parameters']['properties'][name] = {
+          'type' => property['type'] || 'string',
+          'description' => property['description'] || name
+        }
+      end
+
+      def add_required_fields_to_tool(tool_definition, required_fields)
+        return unless required_fields.is_a?(Array)
+
+        required_fields.each do |field_name|
+          tool_definition['parameters']['required'] << field_name
+        end
+      end
+    end
+  end
+end

data/lib/swagger_mcp_tool/helpers/swagger_validator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'json-schema'
+
+module SwaggerMCPTool
+  module Helpers
+    # Provides validation methods for Swagger (OpenAPI) specification structures.
+    # This module includes methods to validate the overall structure of a Swagger spec,
+    # ensure required keys are present, and check the structure of the 'paths' section.
+    # Intended to be included in classes that require Swagger spec validation logic.
+    #
+    # Example usage:
+    #   include SwaggerValidator
+    #   validate_swagger_spec!(swagger_spec_hash)
+    #
+    # Raises ArgumentError if the spec or paths are invalid.
+    #
+    # @see https://swagger.io/specification/
+    module SwaggerValidator
+      def validate_swagger_spec!(swagger_spec)
+        validate_spec_structure!(swagger_spec)
+        validate_paths_structure!(swagger_spec['paths'])
+      end
+
+      def validate_spec_structure!(swagger_spec)
+        raise ArgumentError, 'Swagger spec must be a Hash' unless swagger_spec.is_a?(Hash)
+
+        return if swagger_spec.key?('paths')
+
+        raise ArgumentError, 'Swagger spec must contain paths'
+      end
+
+      def validate_paths_structure!(paths)
+        raise ArgumentError, 'Paths must be a Hash' unless paths.is_a?(Hash)
+
+        return unless paths.empty?
+
+        @config.logger.warn 'No paths found in Swagger spec'
+      end
+    end
+  end
+end