odata_duty 0.30.0

data/lib/odata_duty/mcp_server_builder.rb

@@ -0,0 +1,107 @@
+require 'mcp'
+require 'odata_duty/mcp_input_schemas'
+
+module OdataDuty
+  module McpServerBuilder
+    extend self
+
+    def build(schema)
+      server = MCP::Server.new(
+        name: schema.title,
+        version: schema.version,
+        capabilities: { tools: {} }
+      )
+      schema.endpoints.each { |endpoint| register_endpoint_tools(server, schema, endpoint) }
+      server
+    end
+
+    def register_endpoint_tools(server, schema, endpoint)
+      register_collection_tools(server, schema, endpoint) if endpoint.supports_collection?
+      register_get_tool(server, schema, endpoint) if endpoint.supports_individual?
+      register_create_tool(server, schema, endpoint) if endpoint.supports_create?
+      register_update_tool(server, schema, endpoint) if endpoint.supports_update?
+      register_delete_tool(server, schema, endpoint) if endpoint.supports_delete?
+    end
+
+    def register_collection_tools(server, schema, endpoint)
+      register_list_tool(server, schema, endpoint)
+      register_count_tool(server, schema, endpoint) if endpoint.supports_count?
+    end
+
+    def register_update_tool(server, schema, endpoint)
+      register_key_tool(server, schema, endpoint, :update, 'Update an existing')
+    end
+
+    def register_delete_tool(server, schema, endpoint)
+      register_key_tool(server, schema, endpoint, :delete, 'Delete an existing')
+    end
+
+    def register_list_tool(server, schema, endpoint)
+      input_schema = McpInputSchemas.list_input_schema(supports_search: endpoint.supports_search?)
+      define_tool(server, schema, :execute,
+                  url_for: ->(_args) { endpoint.url },
+                  name: "list_#{endpoint.name}",
+                  description: "List #{endpoint.name} records", input_schema: input_schema)
+    end
+
+    def register_count_tool(server, schema, endpoint)
+      input_schema = McpInputSchemas.count_input_schema(supports_search: endpoint.supports_search?)
+      define_tool(server, schema, :execute,
+                  url_for: ->(_args) { "#{endpoint.url}/$count" },
+                  name: "count_#{endpoint.name}",
+                  description: "Count #{endpoint.name} records", input_schema: input_schema)
+    end
+
+    def register_create_tool(server, schema, endpoint)
+      define_tool(server, schema, :create,
+                  url_for: ->(_args) { endpoint.url },
+                  name: "create_#{endpoint.name}",
+                  description: "Create a new #{endpoint.name} record",
+                  input_schema: McpInputSchemas.create_input_schema(endpoint.entity_type))
+    end
+
+    def register_get_tool(server, schema, endpoint)
+      define_tool(server, schema, :execute,
+                  url_for: keyed_url_for(endpoint),
+                  name: "get_#{endpoint.name}",
+                  description: "Get a single #{endpoint.name} record by ID",
+                  input_schema: McpInputSchemas.get_input_schema(endpoint.entity_type))
+    end
+
+    def register_key_tool(server, schema, endpoint, action, verb)
+      input_schema = McpInputSchemas.public_send("#{action}_input_schema", endpoint.entity_type)
+      define_tool(server, schema, action,
+                  url_for: keyed_url_for(endpoint),
+                  name: "#{action}_#{endpoint.name}",
+                  description: "#{verb} #{endpoint.name} record", input_schema: input_schema)
+    end
+
+    # Builds the `<url>('<key>')` locator from the tool arguments. The dynamic `args[key]` lookup
+    # has no mutation-testable equivalent (the key is always present, enforced by the SDK's
+    # required-argument check), so this is the one MCP subject left on the .mutant.yml ignore list.
+    def keyed_url_for(endpoint)
+      key = endpoint.entity_type.property_refs.first.name
+      ->(args) { "#{endpoint.url}('#{args[key]}')" }
+    end
+
+    # On the .mutant.yml ignore list: `server_context[:context]` has only equivalent mutants
+    # (`[]` vs `fetch`/`dig`); the key is always present, so no public-API test distinguishes them.
+    def define_tool(server, schema, action, url_for:, **tool_args)
+      server.define_tool(**tool_args) do |server_context:, **args|
+        McpServerBuilder.run_tool(action, url: url_for.call(args), schema: schema,
+                                          context: server_context[:context],
+                                          query_options: args.transform_keys(&:to_s))
+      end
+    end
+
+    # On the .mutant.yml ignore list: `e.message` has only an equivalent mutant (`e`), since an
+    # OdataDuty::Error renders identically to its message in the text content block.
+    def run_tool(action, url:, schema:, context:, query_options:)
+      result = Executor.public_send(action, url: url, context: context,
+                                            query_options: query_options, schema: schema)
+      MCP::Tool::Response.new([{ type: 'text', text: result.to_s }])
+    rescue OdataDuty::Error => e
+      MCP::Tool::Response.new([{ type: 'text', text: e.message }], error: true)
+    end
+  end
+end

data/lib/odata_duty/oas2/collection_get_path.rb

@@ -0,0 +1,97 @@
+module OdataDuty
+  class OAS2
+    CollectionGetPath = Struct.new(:entity_set, :context) do
+      COLLECTION_PARAMETERS = [
+        {
+          'name' => '$filter',
+          'in' => 'query',
+          'type' => 'string',
+          'description' => 'Filter the results, supporting `and` and flat `or` combinations'
+        },
+        {
+          'name' => '$search',
+          'in' => 'query',
+          'type' => 'string',
+          'description' => 'Search using structured expressions with AND, OR, NOT operators'
+        },
+        {
+          'name' => '$select',
+          'in' => 'query',
+          'type' => 'array',
+          'items' => { 'type' => 'string' },
+          'collectionFormat' => 'csv',
+          'description' => 'Comma-separated list of properties to return'
+        },
+        {
+          'name' => '$top',
+          'in' => 'query',
+          'type' => 'integer',
+          'description' => 'Number of results to return'
+        },
+        {
+          'name' => '$skip',
+          'in' => 'query',
+          'type' => 'integer',
+          'description' => 'Number of results to skip'
+        },
+        {
+          'name' => '$count',
+          'in' => 'query',
+          'type' => 'boolean',
+          'description' => 'Include count of the results'
+        },
+        {
+          'name' => '$skiptoken',
+          'in' => 'query',
+          'type' => 'string',
+          'description' => 'Token for next page of results'
+        }
+      ].freeze
+      COLLECTION_RESPONSE_DEFAULTS = {
+        '@odata.nextLink' => {
+          'type' => 'string',
+          'description' => 'Url for next page of results',
+          'x-nullable' => true
+        },
+        '@odata.count' => {
+          'type' => 'integer',
+          'description' => 'Total count of results, if $count set to true',
+          'x-nullable' => true
+        }
+      }.freeze
+
+      PARAMETER_REQUIREMENTS = {
+        '$top' => :od_top,
+        '$count' => :count,
+        '$skip' => :od_skip,
+        '$skiptoken' => :od_skiptoken,
+        '$search' => :od_search
+      }.freeze
+
+      def to_oas2
+        instance = entity_set.resolver_class.new(context: context, init_args: entity_set.init_args)
+        parameters = COLLECTION_PARAMETERS.select do |param|
+          !PARAMETER_REQUIREMENTS.key?(param['name']) ||
+            instance.respond_to?(PARAMETER_REQUIREMENTS[param['name']])
+        end
+        {
+          'operationId' => "GetCollectionOf#{entity_set.name}",
+          'produces' => ['application/json'],
+          'parameters' => parameters,
+          'responses' => { '200' => oas2_success_response, 'default' => DEFAULT_ERROR_RESPONSE }
+        }
+      end
+
+      def oas2_success_response
+        { 'description' => 'Collection Response',
+          'schema' => {
+            'type' => 'object',
+            'properties' => { 'value' => {
+              'type' => 'array',
+              'items' => { '$ref' => "#/definitions/#{entity_set.entity_type_name}" }
+            } }.merge(COLLECTION_RESPONSE_DEFAULTS)
+          } }
+      end
+    end
+  end
+end

data/lib/odata_duty/oas2/collection_post_path.rb

@@ -0,0 +1,63 @@
+module OdataDuty
+  class OAS2
+    class CollectionPostPath
+      def self.to_oas2(entity_set)
+        path_info = new(entity_set)
+        {
+          'operationId' => path_info.operation_id,
+          'produces' => path_info.produces,
+          'parameters' => path_info.parameters,
+          'responses' => path_info.responses
+        }
+      end
+
+      def self.request_body_definition(entity_set)
+        writable = entity_set.entity_type.properties.select(&:settable_on_create?)
+        definition = { 'type' => 'object',
+                       'properties' => writable.to_h { |p| [p.name.to_s, p.to_oas2] } }
+        required = writable.reject(&:nullable).map { |p| p.name.to_s }
+        definition['required'] = required unless required.empty?
+        ["#{entity_set.entity_type.name}Create", definition]
+      end
+
+      def initialize(entity_set)
+        @entity_set = entity_set
+      end
+
+      def operation_id
+        "Create#{@entity_set.name}"
+      end
+
+      def produces
+        ['application/json']
+      end
+
+      def parameters
+        [
+          {
+            'name' => 'body', 'in' => 'body', 'required' => true, 'schema' => create_schema
+          }
+        ]
+      end
+
+      def responses
+        {
+          '200' => { 'description' => 'Success', 'schema' => entity_type_schema },
+          '201' => { 'description' => 'Created', 'schema' => entity_type_schema },
+          'default' => { 'description' => 'Unexpected error',
+                         'schema' => { '$ref' => '#/definitions/Error' } }
+        }
+      end
+
+      private
+
+      def entity_type_schema
+        { '$ref' => "#/definitions/#{@entity_set.entity_type.name}" }
+      end
+
+      def create_schema
+        { '$ref' => "#/definitions/#{@entity_set.entity_type.name}Create" }
+      end
+    end
+  end
+end

data/lib/odata_duty/oas2/individual_delete_path.rb

@@ -0,0 +1,42 @@
+module OdataDuty
+  class OAS2
+    class IndividualDeletePath
+      def self.to_oas2(entity_set)
+        path_info = new(entity_set)
+        {
+          'operationId' => path_info.operation_id,
+          'parameters' => path_info.parameters,
+          'responses' => path_info.responses
+        }
+      end
+
+      def initialize(entity_set)
+        @entity_set = entity_set
+      end
+
+      def operation_id
+        "Delete#{@entity_set.name}"
+      end
+
+      def parameters
+        [
+          { 'name' => 'id', 'in' => 'path', 'required' => true, 'type' => id_type }
+        ]
+      end
+
+      def responses
+        {
+          '204' => { 'description' => 'No Content' },
+          'default' => { 'description' => 'Unexpected error',
+                         'schema' => { '$ref' => '#/definitions/Error' } }
+        }
+      end
+
+      private
+
+      def id_type
+        @entity_set.entity_type.integer_property_ref? ? 'integer' : 'string'
+      end
+    end
+  end
+end

data/lib/odata_duty/oas2/individual_get_path.rb

@@ -0,0 +1,37 @@
+module OdataDuty
+  class OAS2
+    class IndividualGetPath < SimpleDelegator
+      def to_oas2
+        {
+          'operationId' => "GetIndividual#{name}ById",
+          'produces' => ['application/json'],
+          'parameters' => oas2_parameters,
+          'responses' => oas2_responses
+        }
+      end
+
+      def oas2_parameters
+        [
+          {
+            'name' => 'id',
+            'in' => 'path',
+            'required' => true,
+            'type' => entity_type.integer_property_ref? ? 'integer' : 'string'
+          }
+        ]
+      end
+
+      def oas2_responses
+        {
+          '200' => {
+            'description' => 'Individual Response',
+            'schema' => {
+              '$ref' => "#/definitions/#{entity_type_name}"
+            }
+          },
+          'default' => DEFAULT_ERROR_RESPONSE
+        }
+      end
+    end
+  end
+end

data/lib/odata_duty/oas2/individual_patch_path.rb

@@ -0,0 +1,63 @@
+module OdataDuty
+  class OAS2
+    class IndividualPatchPath
+      def self.to_oas2(entity_set)
+        path_info = new(entity_set)
+        {
+          'operationId' => path_info.operation_id,
+          'produces' => path_info.produces,
+          'parameters' => path_info.parameters,
+          'responses' => path_info.responses
+        }
+      end
+
+      def self.request_body_definition(entity_set)
+        writable = entity_set.entity_type.properties.select(&:settable_on_update?)
+        definition = { 'type' => 'object',
+                       'properties' => writable.to_h { |p| [p.name.to_s, p.to_oas2] } }
+        ["#{entity_set.entity_type.name}Update", definition]
+      end
+
+      def initialize(entity_set)
+        @entity_set = entity_set
+      end
+
+      def operation_id
+        "Update#{@entity_set.name}"
+      end
+
+      def produces
+        ['application/json']
+      end
+
+      def parameters
+        [
+          { 'name' => 'id', 'in' => 'path', 'required' => true, 'type' => id_type },
+          { 'name' => 'body', 'in' => 'body', 'required' => true, 'schema' => update_schema }
+        ]
+      end
+
+      def responses
+        {
+          '200' => { 'description' => 'Success', 'schema' => entity_type_schema },
+          'default' => { 'description' => 'Unexpected error',
+                         'schema' => { '$ref' => '#/definitions/Error' } }
+        }
+      end
+
+      private
+
+      def id_type
+        @entity_set.entity_type.integer_property_ref? ? 'integer' : 'string'
+      end
+
+      def entity_type_schema
+        { '$ref' => "#/definitions/#{@entity_set.entity_type.name}" }
+      end
+
+      def update_schema
+        { '$ref' => "#/definitions/#{@entity_set.entity_type.name}Update" }
+      end
+    end
+  end
+end

data/lib/odata_duty/oas2.rb

@@ -0,0 +1,113 @@
+require_relative 'context_wrapper'
+require_relative 'schema_builder/endpoint'
+
+module OdataDuty
+  class OAS2
+    def self.build_json(schema, context: nil)
+      builder = new(schema, context: context)
+      builder.add_error_definition
+      builder.add_enum_definitions
+      builder.add_complex_definitions
+      builder.add_request_body_definitions
+      builder.add_collection_paths
+      builder.add_individual_paths
+      builder.hash
+    end
+
+    attr_reader :hash, :schema, :context, :info, :paths, :definitions
+
+    def initialize(schema, context:)
+      @schema = schema
+      @context = context
+      @info = {}
+      @paths = {}
+      @definitions = {}
+      @hash = { 'swagger' => '2.0', 'info' => info, 'host' => schema.host,
+                'schemes' => [schema.scheme], 'basePath' => schema.base_path,
+                'paths' => paths, 'definitions' => definitions }
+      info['version'] = schema.version if schema.version
+      info['title'] = schema.title if schema.title
+    end
+
+    ERROR_PROPERTIES = {
+      'code' => { 'type' => 'string', 'description' => 'A service-defined error code.' },
+      'message' => { 'type' => 'string', 'description' => 'A human-readable message.' },
+      'target' => { 'type' => 'string', 'description' => 'The target of the error.',
+                    'x-nullable' => true }
+    }.freeze
+    def add_error_definition
+      definitions['Error'] = {
+        'type' => 'object',
+        'properties' => {
+          'error' => {
+            'type' => 'object',
+            'properties' => ERROR_PROPERTIES
+          }
+        }
+      }
+    end
+
+    def add_enum_definitions
+      schema.enum_types.each do |enum_type|
+        definitions[enum_type.name] = enum_type.to_oas2
+      end
+    end
+
+    def add_complex_definitions
+      (schema.complex_types + schema.entity_types).each do |complex_type|
+        definitions[complex_type.name] = complex_type.to_oas2
+      end
+    end
+
+    def add_request_body_definitions
+      schema.collection_entity_sets.select(&:supports_create?).each do |entity_set|
+        register_definition(CollectionPostPath.request_body_definition(entity_set))
+      end
+      schema.individual_entity_sets.select(&:supports_update?).each do |entity_set|
+        register_definition(IndividualPatchPath.request_body_definition(entity_set))
+      end
+    end
+
+    def add_collection_paths
+      schema.collection_entity_sets.each do |entity_set|
+        path = { 'get' => CollectionGetPath.new(entity_set, wrap_context(entity_set)).to_oas2 }
+        path['post'] = CollectionPostPath.to_oas2(entity_set) if entity_set.supports_create?
+        paths["/#{entity_set.url}"] = path
+      end
+    end
+
+    def add_individual_paths
+      schema.individual_entity_sets.each do |entity_set|
+        path = { 'get' => IndividualGetPath.new(entity_set).to_oas2 }
+        path['patch'] = IndividualPatchPath.to_oas2(entity_set) if entity_set.supports_update?
+        path['delete'] = IndividualDeletePath.to_oas2(entity_set) if entity_set.supports_delete?
+        paths["/#{entity_set.url}({id})"] = path
+      end
+    end
+
+    DEFAULT_ERROR_RESPONSE = {
+      'description' => 'Unexpected error',
+      'schema' => {
+        '$ref' => '#/definitions/Error'
+      }
+    }.freeze
+
+    private
+
+    def register_definition((name, definition))
+      definitions[name] = definition
+    end
+
+    def wrap_context(entity_set)
+      ContextWrapper.new(@context, base_url: schema.base_url,
+                                   endpoint: SchemaBuilder::Endpoint.new(entity_set),
+                                   query_options: nil)
+    end
+  end
+end
+
+require 'odata_duty/oas2/collection_get_path'
+require 'odata_duty/oas2/collection_post_path'
+require 'odata_duty/oas2/individual_get_path'
+require 'odata_duty/oas2/individual_patch_path'
+require 'odata_duty/oas2/individual_delete_path'

data/lib/odata_duty/parslet_search_expression.rb

@@ -0,0 +1,163 @@
+require 'parslet'
+
+module OdataDuty
+  class SearchExpression
+    attr_reader :terms, :operator
+
+    def initialize(terms, operator = :and)
+      @terms = terms
+      @operator = operator
+    end
+
+    def or?
+      @operator == :or
+    end
+
+    def and?
+      @operator == :and
+    end
+
+    def self.parse(search_string)
+      return new([]) unless search_string.match?(/\S/)
+
+      parse_tree = build_parse_tree(search_string)
+      validate_parse_tree(parse_tree)
+      transform(parse_tree)
+    end
+
+    def self.build_parse_tree(search_string)
+      parser = ParsletSearchExpressionParser.new
+      parser.parse(search_string)
+    rescue Parslet::ParseFailed => e
+      if search_string.include?('(') || search_string.include?(')')
+        raise NoImplementationError, 'Parentheses are not supported'
+      end
+      if search_string.include?(' AND ') && search_string.include?(' OR ')
+        raise NoImplementationError, 'Mixed AND/OR operators are not supported'
+      end
+
+      raise InvalidQueryOptionError, "Invalid search expression: #{e}"
+    end
+
+    def self.validate_parse_tree(parse_tree)
+      and_sub_tree = parse_tree[:explicit_and_expr] || parse_tree[:implicit_and_expr]
+      return unless and_sub_tree
+
+      contains_or = and_sub_tree.any? { |t| t.dig(:term, :word) == 'OR' }
+      raise NoImplementationError, 'Mixed AND/OR operators are not supported' if contains_or
+    end
+
+    def self.transform(parse_tree)
+      transformer = ParsletSearchExpressionTransformer.new
+      transformer.apply(parse_tree)
+    end
+  end
+
+  class SearchTerm
+    attr_reader :value, :negated
+
+    def initialize(value, negated:)
+      @value = value
+      @negated = negated
+    end
+
+    def not?
+      @negated
+    end
+
+    def to_s
+      prefix = ('NOT ' if @negated)
+      quoted = @value.include?(' ') ? "\"#{@value}\"" : @value
+      "#{prefix}#{quoted}"
+    end
+  end
+
+  class ParsletSearchExpressionParser < Parslet::Parser
+    # Basic elements
+    rule(:space) { match('\s').repeat(1) }
+    rule(:space?) { space.maybe }
+
+    # Word characters - alphanumeric, dots, commas, hyphens, underscores
+    rule(:word_char) { match('[a-zA-Z0-9,.\-_]') }
+    rule(:word) { word_char.repeat(1).as(:word) }
+
+    # Quoted phrases
+    rule(:quoted_phrase) do
+      str('"') >>
+        (str('"').absent? >> any).repeat.as(:phrase) >>
+        str('"')
+    end
+
+    # NOT operator
+    rule(:not_operator) { str('NOT') >> space }
+
+    # Basic term (word or quoted phrase)
+    rule(:basic_term) { quoted_phrase | word }
+
+    # Term with optional negation
+    rule(:term) do
+      (not_operator >> basic_term).as(:negated_term) |
+        basic_term.as(:term)
+    end
+
+    # Operators
+    rule(:and_operator) { space >> str('AND') >> space }
+    rule(:or_operator) { space >> str('OR') >> space }
+    rule(:implicit_and) { space }
+
+    # Simplified expression rules
+    rule(:or_expression) { term >> (or_operator >> term).repeat(1) }
+    rule(:explicit_and_expression) { term >> (and_operator >> term).repeat(1) }
+    rule(:implicit_and_expression) { term >> (implicit_and >> term).repeat(1) }
+    rule(:single_term_expression) { term }
+
+    # Main expression - try each pattern
+    rule(:expression) do
+      or_expression.as(:or_expr) |
+        explicit_and_expression.as(:explicit_and_expr) |
+        implicit_and_expression.as(:implicit_and_expr) |
+        single_term_expression.as(:single_term)
+    end
+
+    # Root rule
+    rule(:search_expression) { space? >> expression >> space? }
+
+    root(:search_expression)
+  end
+
+  class ParsletSearchExpressionTransformer < Parslet::Transform
+    rule(word: simple(:word)) { word.to_s }
+    rule(phrase: simple(:phrase)) { phrase.to_s }
+
+    rule(term: simple(:term)) do
+      SearchTerm.new(term.to_s, negated: false)
+    end
+
+    rule(negated_term: simple(:term)) do
+      SearchTerm.new(term.to_s, negated: true)
+    end
+
+    # Single term expressions
+    rule(single_term: simple(:term)) do
+      SearchExpression.new([term], :and)
+    end
+
+    # OR expressions
+    rule(or_expr: sequence(:terms)) do
+      # Multiple terms in OR expression
+      SearchExpression.new(terms, :or)
+    end
+
+    # Explicit AND expressions
+    rule(explicit_and_expr: sequence(:terms)) do
+      # Multiple terms in explicit AND expression
+      SearchExpression.new(terms, :and)
+    end
+
+    # Implicit AND expressions
+    rule(implicit_and_expr: sequence(:terms)) do
+      # Multiple terms in implicit AND expression
+      SearchExpression.new(terms, :and)
+    end
+  end
+end