odata_duty 0.31.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c58f2ad8e1d2a92312d71682cab83159e525dcd5ff2e774b64ccb1c2b91bdef2
-  data.tar.gz: d368f2c3fdbe2ea07508df7087290831694c281b2e22e07243a00393f43bfd52
+  metadata.gz: 5fc1895bad51713ec481fdb8d68fc3ba169512821b6da0411c1123a3589ec39b
+  data.tar.gz: 686c02c58e32d49007257aec13415afb1ad57469cca572c7caf2fcb0f6192e51
 SHA512:
-  metadata.gz: 5b288c003fc87adca34c4eb48f389c00d60dc69f0b4de8ec1c88b2046c7259f2c8f0f7168ce954a6ec021767b9cdc150fdfe7559d269ee54eeb61a3659be551b
-  data.tar.gz: 925162bd086fd4a22ccbff521380c67375387c2ae0f6aea954978d21d5d215cdec9b4c0ea3bec6cbdc3c3fbed0f8c17a045f345ef9ccab293bf6441f0c6a201e
+  metadata.gz: 913eadf1694619c01556d8988b1d6a4cc77b7f9697c496dad0735a6be0a812838a26341cb87c460fb0662a73db6541720fecefa46beee0edc61737799b514427
+  data.tar.gz: 3c497e407c716e90c7d27f1d94bbf9279742bfd6ee7699d2993e60fd877079871c4c70b7a0b2e56bb13b0f18f9cc9f6ce4312638feb7d9e07318f736fe427913

data/CHANGELOG.md

@@ -6,6 +6,41 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.32.0] - 2026-09-08
+
+### Added
+- `odata_skiptoken` argument on the MCP `list_<Set>` tool for entity sets that define
+  `od_next_link_skiptoken`, so an agent can follow a `@odata.nextLink` over MCP instead of
+  hitting a dead end (#76).
+- The MCP server `instructions` now describe the supported OData dialect — the `$filter`
+  grammar, `$search`, skiptoken paging, and what is explicitly unsupported — with each line
+  present only when some entity set can serve it (#76).
+- Generated descriptions on every `odata_*` read-tool argument, and `items.enum` of the entity
+  type's property names on `$select`/`odata_select` so an unknown property is rejected before
+  it reaches the service (#76).
+- `doc/using_paging.md`, covering `$top`, `$skip`, `$skiptoken`, and `od_next_link_skiptoken`
+  (#75).
+
+### Changed
+- **Breaking (MCP tool shape):** read tools (`list_`/`count_`/`get_<Set>`) now advertise
+  `odata_filter`, `odata_search`, `odata_top`, `odata_skip`, and `odata_skiptoken` only when
+  the entity set defines the matching hook, rather than offering every option and failing with
+  `NoImplementationError` when it is used. Filterability is inferred from any public
+  `od_filter_*` method. `odata_select` remains ungated (#76).
+- **Breaking (MCP tool shape):** `odata_select` is now an array of property names instead of a
+  comma-separated string (#76).
+- **Breaking (MCP server shape):** `instructions` was previously exactly the schema
+  `description:` and omitted when that was nil; it is now always present and carries the
+  generated dialect description (#76).
+- `$oas2` collection parameters: `$filter` is capability-gated on the same rule, and
+  `$top`/`$skip` carry `minimum: 0` (#76).
+- `$top`/`$skip` are validated as non-negative base-10 integers before dispatching to
+  `od_top`/`od_skip`, raising `InvalidQueryOptionError` for negative, non-numeric, or otherwise
+  malformed values instead of passing them through to consumer hooks (#75).
+
+`$metadata` and REST execution are unchanged — hiding a query-option parameter does not change
+what the service honors or rejects.
+
 ## [0.31.0] - 2026-08-16
 
 ### Added
@@ -84,7 +119,8 @@ All notable changes to this project are documented here. The format is based on
 See the [git tags](https://github.com/NEXL-LTS/odata_duty-ruby/tags) for the history of
 releases prior to 0.21.0.
 
-[Unreleased]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.31.0...HEAD
+[Unreleased]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.32.0...HEAD
+[0.32.0]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.31.0...v0.32.0
 [0.31.0]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.30.1...v0.31.0
 [0.30.1]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.30.0...v0.30.1
 [0.30.0]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.21.4...v0.30.0

data/lib/odata_duty/capability_hooks.rb

@@ -0,0 +1,9 @@
+module OdataDuty
+  module CapabilityHooks
+    FILTER_HOOK_PREFIX = 'od_filter_'.freeze
+
+    def self.filterable?(klass)
+      klass.public_instance_methods.any? { |name| name.start_with?(FILTER_HOOK_PREFIX) }
+    end
+  end
+end

data/lib/odata_duty/executor.rb

@@ -207,6 +207,7 @@ module OdataDuty
     end
 
     def apply_top(set_builder, top)
+      validate_non_negative_integer('$top', top)
       if !set_builder.respond_to?(:od_top) && top
         raise NoImplementationError, "$top not implemented for #{set_builder.class}"
       end
@@ -215,6 +216,7 @@ module OdataDuty
     end
 
     def apply_skip(set_builder, skip)
+      validate_non_negative_integer('$skip', skip)
       if !set_builder.respond_to?(:od_skip) && skip
         raise NoImplementationError, "$skip not implemented for #{set_builder.class}"
       end
@@ -222,6 +224,21 @@ module OdataDuty
       set_builder.od_skip(skip) if skip
     end
 
+    def validate_non_negative_integer(name, value)
+      return unless value
+      return if non_negative_integer?(value)
+
+      raise InvalidQueryOptionError, "'#{name}' must be a non-negative integer, got '#{value}'"
+    end
+
+    def non_negative_integer?(value)
+      return value >= 0 if value.is_a?(Integer)
+
+      Integer(value, 10) >= 0
+    rescue ArgumentError
+      false
+    end
+
     def apply_skiptoken(set_builder, skiptoken)
       if !set_builder.respond_to?(:od_skiptoken) && skiptoken
         raise NoImplementationError, "$skiptoken not implemented for #{set_builder.class}"

data/lib/odata_duty/mcp_input_schemas.rb

@@ -1,3 +1,5 @@
+require 'odata_duty/mcp_query_options'
+
 module OdataDuty
   module McpInputSchemas
     extend self
@@ -13,27 +15,43 @@ module OdataDuty
       '$select' => 'odata_select',
       '$search' => 'odata_search',
       '$top' => 'odata_top',
-      '$skip' => 'odata_skip'
+      '$skip' => 'odata_skip',
+      '$skiptoken' => 'odata_skiptoken'
     }.freeze
 
-    def count_input_schema(supports_search:)
-      properties = { alias_for('$filter') => { 'type' => 'string' } }
-      properties[alias_for('$search')] = { 'type' => 'string' } if supports_search
-      { 'properties' => properties, 'required' => [] }
+    UNGATED = nil
+
+    # `[query-option key, capability predicate]` in advertised order; `UNGATED` is always
+    # advertised. The argument shape for each key lives in McpQueryOptions.
+    LIST_QUERY_OPTIONS = [
+      ['$filter', :supports_filter?],
+      ['$select', UNGATED],
+      ['$search', :supports_search?],
+      ['$top', :supports_top?],
+      ['$skip', :supports_skip?],
+      ['$skiptoken', :supports_skiptoken?]
+    ].freeze
+
+    COUNT_QUERY_OPTIONS = [
+      ['$filter', :supports_filter?],
+      ['$search', :supports_search?]
+    ].freeze
+
+    def count_input_schema(endpoint)
+      { 'properties' => supported_query_options(COUNT_QUERY_OPTIONS, endpoint), 'required' => [] }
     end
 
-    def list_input_schema(supports_search:)
-      properties = {
-        alias_for('$filter') => query_option('string', 'OData $filter expression'),
-        alias_for('$select') => query_option('string', 'Comma-separated properties to return')
-      }
-      if supports_search
-        properties[alias_for('$search')] = query_option('string',
-                                                        'Search expression (AND, OR, NOT)')
+    def list_input_schema(endpoint)
+      { 'properties' => supported_query_options(LIST_QUERY_OPTIONS, endpoint), 'required' => [] }
+    end
+
+    def supported_query_options(gates, endpoint)
+      definitions = McpQueryOptions.definitions(endpoint.entity_type)
+      gates.each_with_object({}) do |(key, predicate), properties|
+        next if predicate && !endpoint.public_send(predicate)
+
+        properties[alias_for(key)] = definitions.fetch(key)
       end
-      properties[alias_for('$top')] = query_option('integer', 'Max records to return')
-      properties[alias_for('$skip')] = query_option('integer', 'Records to skip')
-      { 'properties' => properties, 'required' => [] }
     end
 
     # Raises when an entity property is literally named like a reserved `odata_*` alias and
@@ -68,7 +86,7 @@ module OdataDuty
     def get_input_schema(entity_type, tool_name:)
       key = entity_type.property_refs.first
       properties = { key.name => key.to_oas2 }
-      select_value = query_option('string', 'Comma-separated properties to return')
+      select_value = McpQueryOptions.select_option(entity_type)
       add_alias!(properties, entity_type, '$select', select_value, tool_name: tool_name)
       { 'properties' => properties, 'required' => [key.name] }
     end
@@ -81,9 +99,5 @@ module OdataDuty
     def alias_for(query_option_key)
       QUERY_OPTION_ALIASES.fetch(query_option_key)
     end
-
-    def query_option(type, description)
-      { 'type' => type, 'description' => description }
-    end
   end
 end

data/lib/odata_duty/mcp_instructions.rb

@@ -0,0 +1,60 @@
+module OdataDuty
+  # Builds the MCP server `instructions` document: the schema's own description followed by a
+  # description of the OData dialect the generated tools actually speak. A per-option line is
+  # included only when at least one entity set in the schema supports that query option, so the
+  # document never advertises a capability no tool exposes.
+  module McpInstructions
+    extend self
+
+    INTRO = 'This service exposes a subset of OData v4. Query options are passed to tools as ' \
+            '`odata_*` arguments (e.g. `odata_filter` is OData `$filter`).'.freeze
+
+    FILTER_LINE = '$filter: predicates of the form `<property> <op> <value>`. Operators: eq, ' \
+                  'ne, gt, ge, lt, le. Combine with all `and` or all `or` — mixing `and` with ' \
+                  '`or` is not supported, nor is parenthesised grouping. Functions (contains, ' \
+                  'startswith, tolower, …), arithmetic and `not` are not supported. String ' \
+                  'literals use single quotes; Edm.Date and Edm.DateTimeOffset values are ISO ' \
+                  '8601 (2024-01-31, 2024-01-31T00:00:00+00:00).'.freeze
+
+    SEARCH_LINE = '$search: terms combined with AND, OR, NOT. Parenthesised groups are not ' \
+                  'supported.'.freeze
+
+    PAGING_LINE = 'Paging: pass odata_skiptoken with the $skiptoken value from a prior ' \
+                  "response's @odata.nextLink.".freeze
+
+    UNSUPPORTED_LINE = '$orderby, $expand, $apply, $compute and $count=true are not ' \
+                       'supported.'.freeze
+
+    CLOSING = 'Each tool advertises only the query options its entity set supports.'.freeze
+
+    # `[line, capability predicate]` in document order; each line is included only when some
+    # endpoint answers true to its predicate.
+    OPTION_LINES = [
+      [FILTER_LINE, :supports_filter?],
+      [SEARCH_LINE, :supports_search?],
+      [PAGING_LINE, :supports_skiptoken?]
+    ].freeze
+
+    def build(schema)
+      [schema.description, dialect(schema)].compact.join("\n\n")
+    end
+
+    def dialect(schema)
+      [INTRO, option_lines(schema).join("\n"), CLOSING].join("\n\n")
+    end
+
+    def option_lines(schema)
+      supported = OPTION_LINES.filter_map do |line, predicate|
+        line if schema.endpoints.any? { |endpoint| advertises?(endpoint, predicate) }
+      end
+      supported + [UNSUPPORTED_LINE]
+    end
+
+    # `$filter` and `$search` reach a set through its `list_`/`count_` tools and paging through
+    # `list_`, all of which need a `collection` method — so a set without one advertises no
+    # query options at all, whatever hooks it defines.
+    def advertises?(endpoint, predicate)
+      endpoint.supports_collection? && endpoint.public_send(predicate)
+    end
+  end
+end

data/lib/odata_duty/mcp_query_options.rb

@@ -0,0 +1,59 @@
+module OdataDuty
+  # Argument definitions for the `odata_*` query-option keys `McpInputSchemas` advertises on the
+  # read tools, keyed by their `$`-prefixed OData spelling. Split out of `McpInputSchemas` so the
+  # `$select` shape has one definition shared by the gated list/count tables and `get_`.
+  module McpQueryOptions
+    extend self
+
+    FILTER_DESCRIPTION =
+      'OData $filter expression; see the service instructions for the grammar. Filtering is ' \
+      'supported for this entity set, but not every property or operator combination is ' \
+      'necessarily implemented — an unsupported combination returns an error rather than an ' \
+      'empty result. Property names are listed under odata_select. ' \
+      "Example: user_name eq 'Alice'".freeze
+
+    SELECT_DESCRIPTION = 'Properties to return; omit for all.'.freeze
+
+    SEARCH_DESCRIPTION =
+      'Free-text $search expression; terms combined with AND, OR, NOT. Parenthesised groups ' \
+      'are not supported.'.freeze
+
+    TOP_DESCRIPTION = 'Maximum number of records to return.'.freeze
+
+    SKIP_DESCRIPTION = 'Number of records to skip before returning results.'.freeze
+
+    SKIPTOKEN_DESCRIPTION =
+      'Continuation token for the next page. Take it from the $skiptoken query parameter of a ' \
+      "prior response's @odata.nextLink.".freeze
+
+    def definitions(entity_type)
+      {
+        '$filter' => string_option(FILTER_DESCRIPTION),
+        '$select' => select_option(entity_type),
+        '$search' => string_option(SEARCH_DESCRIPTION),
+        '$top' => integer_option(TOP_DESCRIPTION),
+        '$skip' => integer_option(SKIP_DESCRIPTION),
+        '$skiptoken' => string_option(SKIPTOKEN_DESCRIPTION)
+      }
+    end
+
+    # An array of property names rather than OData's comma-separated string, so the `enum` can
+    # advertise exactly which names are selectable and the MCP SDK rejects the rest before the
+    # tool handler runs. McpToolArguments joins the array back to `$select`'s OData spelling.
+    def select_option(entity_type)
+      names = entity_type.properties.map { |property| property.name.to_s }
+      { 'type' => 'array', 'description' => SELECT_DESCRIPTION,
+        'items' => { 'type' => 'string', 'enum' => names } }
+    end
+
+    def string_option(description)
+      { 'type' => 'string', 'description' => description }
+    end
+
+    # `minimum` lets the MCP SDK reject a negative paging argument against the tool schema
+    # before the handler runs, where over REST it reaches Executor's InvalidQueryOptionError.
+    def integer_option(description)
+      { 'type' => 'integer', 'minimum' => 0, 'description' => description }
+    end
+  end
+end

data/lib/odata_duty/mcp_server_builder.rb

@@ -1,24 +1,19 @@
 require 'mcp'
 require 'odata_duty/mcp_input_schemas'
 require 'odata_duty/mcp_identifier_validator'
+require 'odata_duty/mcp_instructions'
+require 'odata_duty/mcp_tool_arguments'
 require 'odata_duty/operation_verbs'
 
 module OdataDuty
   module McpServerBuilder
     extend self
 
-    # Inverse of McpInputSchemas::QUERY_OPTION_ALIASES: translates a tool call's `odata_*`
-    # arguments back to their `$`-prefixed OData spelling before they reach Executor.
-    QUERY_OPTION_SPELLINGS = McpInputSchemas::QUERY_OPTION_ALIASES.invert.freeze
-
     def build(schema)
       server = MCP::Server.new(
         name: schema.title,
         version: schema.version,
-        # Relies on the `mcp` gem's `initialize` response builder `.compact`-ing away a nil
-        # `instructions:`, so a schema without a description omits the key rather than sending
-        # `"instructions": null` — worth re-checking on `mcp` gem upgrades.
-        instructions: schema.description,
+        instructions: McpInstructions.build(schema),
         capabilities: { tools: {} }
       )
       schema.endpoints.each { |endpoint| register_endpoint_tools(server, schema, endpoint) }
@@ -47,7 +42,7 @@ module OdataDuty
     end
 
     def register_list_tool(server, schema, endpoint)
-      input_schema = McpInputSchemas.list_input_schema(supports_search: endpoint.supports_search?)
+      input_schema = McpInputSchemas.list_input_schema(endpoint)
       description = tool_description(OperationVerbs.list(endpoint.name), endpoint)
       tool_args = { name: "list_#{endpoint.name}", description: description,
                     input_schema: input_schema }
@@ -55,7 +50,7 @@ module OdataDuty
     end
 
     def register_count_tool(server, schema, endpoint)
-      input_schema = McpInputSchemas.count_input_schema(supports_search: endpoint.supports_search?)
+      input_schema = McpInputSchemas.count_input_schema(endpoint)
       description = tool_description(OperationVerbs.count(endpoint.name), endpoint)
       tool_args = { name: "count_#{endpoint.name}", description: description,
                     input_schema: input_schema }
@@ -108,23 +103,16 @@ module OdataDuty
     # (`[]` 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)
       McpIdentifierValidator.validate_tool_name!(tool_args[:name])
+      properties = tool_args[:input_schema].fetch('properties')
+      spellings = McpToolArguments.spellings_for(properties.keys)
       server.define_tool(**tool_args) do |server_context:, **args|
+        query_options = McpToolArguments.query_options_for(action, args, spellings)
         McpServerBuilder.run_tool(action, url: url_for.call(args), schema: schema,
                                           context: server_context[:context],
-                                          query_options: McpServerBuilder.query_options_for(action,
-                                                                                            args))
+                                          query_options: query_options)
       end
     end
 
-    # The `odata_*` aliases only stand in for OData query options on read (`:execute`) tools —
-    # `:create`/`:update`/`:delete` tools' arguments are property values, so a property literally
-    # named e.g. `odata_select` must reach Executor unchanged, not get aliased to `$select`.
-    def query_options_for(action, args)
-      return args.transform_keys(&:to_s) unless action == :execute
-
-      args.to_h { |key, value| [QUERY_OPTION_SPELLINGS.fetch(key.to_s, key.to_s), value] }
-    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:)

data/lib/odata_duty/mcp_tool_arguments.rb

@@ -0,0 +1,46 @@
+require 'odata_duty/mcp_input_schemas'
+
+module OdataDuty
+  # Translates a `tools/call` argument hash into the query options Executor expects, undoing the
+  # `odata_*` aliasing and array shapes McpInputSchemas advertises on the read tools.
+  module McpToolArguments
+    extend self
+
+    # Inverse of McpInputSchemas::QUERY_OPTION_ALIASES: translates a tool call's `odata_*`
+    # arguments back to their `$`-prefixed OData spelling before they reach Executor.
+    QUERY_OPTION_SPELLINGS = McpInputSchemas::QUERY_OPTION_ALIASES.invert.freeze
+
+    SELECT_OPTION = QUERY_OPTION_SPELLINGS.fetch(McpInputSchemas.alias_for('$select')).freeze
+
+    # The `odata_*` → `$`-prefixed spellings for the aliases one tool's input schema declares as
+    # query options, keyed off the schema's own property keys. McpInputSchemas keys entity
+    # properties by symbol and query-option aliases by string, so an entity property literally
+    # named `odata_skiptoken` — a `get_<Set>` tool's key, say — is not one of them.
+    def spellings_for(input_schema_keys)
+      QUERY_OPTION_SPELLINGS.slice(*input_schema_keys)
+    end
+
+    # The `odata_*` aliases only stand in for OData query options on read (`:execute`) tools —
+    # `:create`/`:update`/`:delete` tools' arguments are property values, so a property literally
+    # named e.g. `odata_select` must reach Executor unchanged, not get aliased to `$select`.
+    def query_options_for(action, args, spellings)
+      return args.transform_keys(&:to_s) unless action == :execute
+
+      args.to_h do |key, value|
+        name = key.to_s
+        spelling = spellings.fetch(name, name)
+        [spelling, query_option_value(spelling, value)]
+      end
+    end
+
+    # A declared `odata_select` is advertised as an array of property names, so it needs joining
+    # back to `$select`'s comma-separated OData spelling. Every other value is passed through as
+    # given — including an `odata_select` a tool never declared (on a `count_<Set>`, say), which
+    # is no more a query option than any other undeclared argument.
+    def query_option_value(spelling, value)
+      return value unless spelling == SELECT_OPTION
+
+      value.join(',')
+    end
+  end
+end

data/lib/odata_duty/oas2/collection_get_parameters.rb

@@ -0,0 +1,102 @@
+module OdataDuty
+  class OAS2
+    # The query-option parameters advertised on a collection GET operation. Each one is emitted
+    # only when the entity set can serve it, so the document never offers a query option the
+    # service would reject; `$select` is ungated, since the projection happens regardless.
+    module CollectionGetParameters
+      extend self
+
+      FILTER_NAME = '$filter'.freeze
+      SELECT_NAME = '$select'.freeze
+
+      COLLECTION_PARAMETERS = [
+        {
+          'name' => FILTER_NAME,
+          '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_NAME,
+          'in' => 'query',
+          'type' => 'array',
+          'items' => { 'type' => 'string' },
+          'collectionFormat' => 'csv',
+          'description' => 'Comma-separated list of properties to return'
+        },
+        {
+          'name' => '$top',
+          'in' => 'query',
+          'type' => 'integer',
+          'minimum' => 0,
+          'description' => 'Number of results to return'
+        },
+        {
+          'name' => '$skip',
+          'in' => 'query',
+          'type' => 'integer',
+          'minimum' => 0,
+          '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
+
+      # Query options gated on the resolver responding to the single hook that serves them.
+      # `$filter` is gated too, but on any `od_filter_*` hook rather than one name, so it goes
+      # through the entity set's capability predicate instead — see `supported?`.
+      PARAMETER_REQUIREMENTS = {
+        '$top' => :od_top,
+        '$count' => :count,
+        '$skip' => :od_skip,
+        '$skiptoken' => :od_skiptoken,
+        '$search' => :od_search
+      }.freeze
+
+      def build(entity_set, context)
+        instance = entity_set.resolver_class.new(context: context, init_args: entity_set.init_args)
+        parameters(entity_set.entity_type).select do |param|
+          supported?(param.fetch('name'), entity_set, instance)
+        end
+      end
+
+      def supported?(name, entity_set, instance)
+        return entity_set.supports_filter? if name == FILTER_NAME
+        return true unless PARAMETER_REQUIREMENTS.key?(name)
+
+        instance.respond_to?(PARAMETER_REQUIREMENTS.fetch(name))
+      end
+
+      # `$select`'s `enum` names the entity type's own properties, so that parameter cannot be
+      # static the way the rest of the list is.
+      def parameters(entity_type)
+        COLLECTION_PARAMETERS.map do |param|
+          next param unless param.fetch('name') == SELECT_NAME
+
+          items = param.fetch('items').merge('enum' => property_names(entity_type))
+          param.merge('items' => items)
+        end
+      end
+
+      def property_names(entity_type)
+        entity_type.properties.map { |property| property.name.to_s }
+      end
+    end
+  end
+end

data/lib/odata_duty/oas2/collection_get_path.rb

@@ -1,52 +1,8 @@
+require 'odata_duty/oas2/collection_get_parameters'
+
 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',
@@ -60,25 +16,12 @@ module OdataDuty
         }
       }.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}"
         }.merge(summary_and_description).merge(
           'produces' => ['application/json'],
-          'parameters' => parameters,
+          'parameters' => CollectionGetParameters.build(entity_set, context),
           'responses' => { '200' => oas2_success_response, 'default' => DEFAULT_ERROR_RESPONSE }
         )
       end

data/lib/odata_duty/schema_builder/endpoint.rb

@@ -56,6 +56,22 @@ module OdataDuty
         entity_set.supports_search?
       end
 
+      def supports_filter?
+        entity_set.supports_filter?
+      end
+
+      def supports_top?
+        entity_set.supports_top?
+      end
+
+      def supports_skip?
+        entity_set.supports_skip?
+      end
+
+      def supports_skiptoken?
+        entity_set.supports_skiptoken?
+      end
+
       def supports_collection?
         entity_set.supports_collection?
       end

data/lib/odata_duty/schema_builder/entity_set.rb

@@ -1,4 +1,5 @@
 require 'delegate'
+require_relative '../capability_hooks'
 require_relative 'container'
 
 module OdataDuty
@@ -23,13 +24,29 @@ module OdataDuty
 
       def supports_search?
         # Check if the resolver class supports search by looking for the od_search method
-        resolver_class.method_defined?(:od_search)
+        resolver_class.public_method_defined?(:od_search)
       end
 
       def supports_filter_or?
         resolver_class.method_defined?(:od_filter_or)
       end
 
+      def supports_filter?
+        CapabilityHooks.filterable?(resolver_class)
+      end
+
+      def supports_top?
+        resolver_class.public_method_defined?(:od_top)
+      end
+
+      def supports_skip?
+        resolver_class.public_method_defined?(:od_skip)
+      end
+
+      def supports_skiptoken?
+        resolver_class.public_method_defined?(:od_skiptoken)
+      end
+
       def supports_collection?
         # Check if the resolver class supports read by looking for the collection method
         resolver_class.method_defined?(:collection)

data/lib/odata_duty.rb

@@ -1,3 +1,4 @@
+require 'odata_duty/capability_hooks'
 require 'odata_duty/errors'
 require 'odata_duty/set_resolver'
 require 'odata_duty/schema_builder'
@@ -127,8 +128,12 @@ module OdataDuty
         raise ResourceNotFoundError, "No such entity #{id}" unless result
       end
 
-      def supports_search? = entity_set.method_defined?(:od_search)
+      def supports_search? = entity_set.public_method_defined?(:od_search)
       def supports_filter_or? = entity_set.method_defined?(:od_filter_or)
+      def supports_filter? = CapabilityHooks.filterable?(entity_set)
+      def supports_top? = entity_set.public_method_defined?(:od_top)
+      def supports_skip? = entity_set.public_method_defined?(:od_skip)
+      def supports_skiptoken? = entity_set.public_method_defined?(:od_skiptoken)
       def supports_collection? = entity_set.method_defined?(:collection)
       def supports_individual? = entity_set.method_defined?(:individual)
       def supports_count? = entity_set.method_defined?(:count)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: odata_duty
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.32.0
 platform: ruby
 authors:
 - Grant Petersen-Speelman
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -108,6 +108,7 @@ files:
 - lib/generators/odata_duty/install/templates/schema.rb.tt
 - lib/metadata.xml.erb
 - lib/odata_duty.rb
+- lib/odata_duty/capability_hooks.rb
 - lib/odata_duty/complex_type.rb
 - lib/odata_duty/context_wrapper.rb
 - lib/odata_duty/create_complex_type_hash_wrapper.rb
@@ -123,8 +124,12 @@ files:
 - lib/odata_duty/mapper_builder.rb
 - lib/odata_duty/mcp_identifier_validator.rb
 - lib/odata_duty/mcp_input_schemas.rb
+- lib/odata_duty/mcp_instructions.rb
+- lib/odata_duty/mcp_query_options.rb
 - lib/odata_duty/mcp_server_builder.rb
+- lib/odata_duty/mcp_tool_arguments.rb
 - lib/odata_duty/oas2.rb
+- lib/odata_duty/oas2/collection_get_parameters.rb
 - lib/odata_duty/oas2/collection_get_path.rb
 - lib/odata_duty/oas2/collection_post_path.rb
 - lib/odata_duty/oas2/individual_delete_path.rb