hitch-rails 0.2.0

data/app/models/hitch/mcp/internal/sdk_adapter/response_normalizer.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "rubygems/requirement"
+require "rubygems/version"
+
+module Hitch
+  module MCP
+    module Internal
+      class SDKAdapter
+        class ResponseNormalizer
+          SERVER_INFO_META_KEY = "io.modelcontextprotocol/serverInfo"
+
+          class << self
+            def call(response:, method:, server_info:, request_id:, tool_response:)
+              new(response, method, server_info, request_id, tool_response).call
+            end
+          end
+
+          def initialize(response, method, server_info, request_id, tool_response)
+            @response = response
+            @method = method
+            @server_info = server_info
+            @request_id = request_id
+            @tool_response = tool_response
+          end
+
+          def call
+            return internal_error unless response.is_a?(Hash)
+
+            result_present = member?(response, :result)
+            error_present = member?(response, :error)
+            return internal_error if result_present == error_present
+            return internal_error if duplicate_member?(response, :result) || duplicate_member?(response, :error)
+
+            error = read(response, :error)
+            if error_present
+              return internal_error unless error.is_a?(Hash) && read(error, :code).is_a?(Integer)
+
+              return normalize_error
+            end
+
+            result = read(response, :result)
+            return internal_error unless result.is_a?(Hash)
+
+            normalized = {
+              jsonrpc: "2.0",
+              id: copy(request_id),
+              result: copy(result)
+            }
+            result = normalized.fetch(:result)
+
+            normalize_tool_error(result) if read(result, :isError) == true
+            normalize_final_result(result)
+            deep_freeze(normalized)
+          end
+
+          private
+
+          attr_reader :response, :method, :server_info, :request_id, :tool_response
+
+          def internal_error
+            deep_freeze(
+              jsonrpc: "2.0",
+              id: copy(request_id),
+              error: { code: -32603, message: "Internal error" }
+            )
+          end
+
+          def normalize_error
+            error = read(response, :error)
+            code = read(error, :code)
+            deep_freeze(
+              jsonrpc: "2.0",
+              id: copy(request_id),
+              error: { code: code, message: public_error_message(code) }
+            )
+          end
+
+          # Hitch owns the final wire shape on every supported SDK line rather
+          # than trusting what crossed the boundary. On mcp 1.1 this also
+          # papered over gaps since fixed upstream (ruby-sdk#389,
+          # modelcontextprotocol#3040); on mcp >= 1.2 the SDK's own modern
+          # shaping is envelope-gated and Hitch strips _meta before the SDK
+          # sees it, so the shape is Hitch's job either way. resultType is
+          # always "complete": multi-round-trip requests are unsupported.
+          def normalize_final_result(result)
+            result[:resultType] = "complete"
+            normalize_discovery(result) if method == "server/discover"
+            normalize_private_listing(result) if %w[server/discover tools/list].include?(method)
+            normalize_server_identity(result)
+          end
+
+          def normalize_tool_error(result)
+            explicit_text = ResultNormalizer.explicit_error_text(tool_response)
+            result.delete(:structuredContent)
+            result.delete("structuredContent")
+            result.delete(:_meta)
+            result.delete("_meta")
+            result[:content] = [
+              { type: "text", text: explicit_text || Protocol::GENERIC_TOOL_ERROR }
+            ]
+            result[:isError] = true
+          end
+
+          def normalize_discovery(result)
+            result.delete(:serverInfo)
+            result.delete("serverInfo")
+            result[:supportedVersions] = [ Protocol::VERSION ]
+            result[:capabilities] = { tools: {} }
+          end
+
+          def server_identity
+            server_info.each_with_object({}) do |(key, value), identity|
+              identity[key.to_s] = stringify(value) unless key.to_s == "instructions"
+            end
+          end
+
+          def normalize_server_identity(result)
+            meta = read(result, :_meta)
+            meta = meta.is_a?(Hash) ? stringify(meta) : {}
+            meta[SERVER_INFO_META_KEY] = server_identity
+            result[:_meta] = meta
+          end
+
+          def normalize_private_listing(result)
+            result[:ttlMs] = 0
+            result[:cacheScope] = "private"
+          end
+
+          def public_error_message(code)
+            case code
+            when -32601 then "Method not found"
+            when -32602 then "Invalid params"
+            when -32603 then "Internal error"
+            else "Request failed"
+            end
+          end
+
+          def read(hash, key)
+            JsonValues.read(hash, key)
+          end
+
+          def member?(hash, key)
+            hash.key?(key) || hash.key?(key.to_s)
+          end
+
+          def duplicate_member?(hash, key)
+            hash.key?(key) && hash.key?(key.to_s)
+          end
+
+          def copy(value)
+            JsonValues.copy(value)
+          end
+
+          def stringify(value)
+            case value
+            when Hash then value.to_h { |key, child| [ key.to_s, stringify(child) ] }
+            when Array then value.map { |child| stringify(child) }
+            when String then value.dup
+            else value
+            end
+          end
+
+          def deep_freeze(value)
+            JsonValues.deep_freeze(value)
+          end
+        end
+
+        private_constant :ResponseNormalizer
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/sdk_adapter.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module Hitch
+  module MCP
+    module Internal
+      class SDKAdapter
+        STRUCTURAL_PARAMS = {
+          "server/discover" => [],
+          "tools/list" => %w[cursor],
+          "tools/call" => %w[name arguments]
+        }.freeze
+        SDK_REQUEST_ID = "hitch_request"
+
+        class << self
+          def call(**arguments)
+            new(**arguments).call
+          end
+
+          # Builds the SDK-facing tool wrapper once per registry snapshot —
+          # ::MCP::Tool.define compiles the JSON schemas eagerly, which is the
+          # cost this memoization exists to stop paying per tool per request.
+          # The block closes over nothing request-scoped: each request routes
+          # through the dispatcher its own ::MCP::Server carries in
+          # server_context, so a shared wrapper can never see another
+          # request's principal.
+          def build_sdk_tool(name:, description:, input_schema:, output_schema: nil, annotations: nil)
+            name = validate_tool_name!(name)
+            ::MCP::Tool.define(
+              name: name,
+              description: description,
+              input_schema: input_schema,
+              output_schema: output_schema,
+              annotations: annotations
+            ) do |server_context:, **arguments|
+              server_context.fetch(:hitch_dispatch).call(name, server_context, arguments)
+            end
+          end
+
+          def validate_tool_name!(name)
+            return name if Protocol.tool_name?(name)
+
+            raise ArgumentError,
+              "tool name must be 1-#{Protocol::MAX_TOOL_NAME_LENGTH} ASCII letters, digits, " \
+                "underscore, dot, or dash"
+          end
+        end
+
+        def initialize(verified_request:, tools:, context:, server_info:)
+          @request = frozen_hash!(verified_request)
+          @tools = tools.dup.freeze
+          @context = context
+          @server_info = frozen_hash!(server_info)
+          @tool_responses = []
+        end
+
+        def call
+          return method_not_found unless Protocol::METHODS.include?(request_method)
+          return invalid_params if reserved_server_context?
+
+          response = build_server.handle(structural_request)
+          ResponseNormalizer.call(
+            response: response,
+            method: request_method,
+            server_info: server_info,
+            request_id: read(request, "id"),
+            tool_response: @tool_responses.last
+          )
+        end
+
+        private
+
+        attr_reader :request, :tools, :context, :server_info
+
+        def request_method
+          read(request, "method")
+        end
+
+        # The server itself stays per-request on purpose: the SDK binds
+        # server_context at construction (1.2.0 server.rb:222) with no
+        # per-handle alternative, so a fresh thin server is what keeps one
+        # request's principal out of another's. The
+        # expensive part — schema compilation inside ::MCP::Tool.define — is
+        # memoized per snapshot entry and only assembled here.
+        def build_server
+          # The endpoint boundary has already validated server_info against the
+          # supported key set; the SDK constructor only needs symbol keywords.
+          ::MCP::Server.new(
+            **server_info.transform_keys(&:to_sym),
+            tools: sdk_tools,
+            capabilities: { tools: {} },
+            server_context: { hitch_context: context, hitch_dispatch: dispatch }.freeze,
+            configuration: sdk_configuration,
+            ttl_ms: 0,
+            cache_scope: "private"
+          )
+        end
+
+        def sdk_tools
+          tools.map do |definition|
+            next definition.sdk_tool if definition.respond_to?(:sdk_tool)
+
+            annotations = definition.annotations if definition.respond_to?(:annotations)
+            self.class.build_sdk_tool(
+              name: definition.name,
+              description: definition.description,
+              input_schema: definition.input_schema,
+              output_schema: definition.output_schema,
+              annotations: annotations
+            )
+          end
+        end
+
+        # Request-scoped state rides this lambda instead of the shared tool
+        # wrappers: the response capture feeds ResponseNormalizer's explicit
+        # tool-error text, and the name lookup resolves the wrapper's call to
+        # this request's admitted definitions.
+        def dispatch
+          tools_by_name = tools.to_h { |definition| [ definition.name, definition ] }
+          captured = @tool_responses
+          lambda do |name, server_context, arguments|
+            tools_by_name.fetch(name).call(server_context:, **arguments)
+              .tap { |response| captured << response }
+          end.freeze
+        end
+
+        # No protocol_version pin: on the modern wire every request carries its
+        # version, and both supported SDK lines default their stable version to
+        # 2026-07-28 — the value we used to pin. mcp 1.2.0 rejects pinning a
+        # modern version outright.
+        # validate_tool_call_results stays explicitly false (also the SDK
+        # default on both supported lines): Hitch's ResultNormalizer already
+        # schema-validates every structured result inside framework-owned
+        # Tool.call, before the SDK sees it, so the SDK pass was a second
+        # validation of the same bytes. Hitch's is the one that stays — the
+        # boundary posture is to not trust the SDK's.
+        def sdk_configuration
+          ::MCP::Configuration.new(
+            validate_tool_call_arguments: true,
+            validate_tool_call_results: false,
+            exception_reporter: ->(_exception, _data) { },
+            around_request: ->(_data, &handler) { handler.call },
+            instrumentation_callback: ->(_data) { }
+          )
+        end
+
+        def structural_request
+          params = read(request, "params")
+          structural_params = STRUCTURAL_PARAMS.fetch(request_method).each_with_object({}) do |key, result|
+            copy_fixed_key(result, params, key)
+          end
+
+          # SDK 1.1 merges request _meta into a Hash server_context. Hitch has
+          # already verified and copied that metadata into its own Context, so it
+          # must not cross this boundary and dilute the one authority wrapper.
+
+          deep_freeze(
+            jsonrpc: read(request, "jsonrpc"),
+            id: SDK_REQUEST_ID,
+            method: request_method,
+            params: structural_params
+          )
+        end
+
+        def reserved_server_context?
+          return false unless request_method == "tools/call"
+
+          arguments = read(read(request, "params"), "arguments")
+          arguments.instance_of?(Hash) && arguments.key?("server_context")
+        end
+
+        def method_not_found
+          protocol_error(-32601, "Method not found")
+        end
+
+        def invalid_params
+          protocol_error(-32602, "Invalid params")
+        end
+
+        def protocol_error(code, message)
+          {
+            jsonrpc: "2.0",
+            id: read(request, "id"),
+            error: { code: code, message: message }
+          }.then { |response| deep_freeze(response) }
+        end
+
+        def copy_fixed_key(target, source, key)
+          return unless source.is_a?(Hash)
+
+          if source.key?(key)
+            target[key.to_sym] = JsonValues.deep_string_copy_and_freeze(source[key])
+          elsif source.key?(key.to_sym)
+            target[key.to_sym] = JsonValues.deep_string_copy_and_freeze(source[key.to_sym])
+          end
+        end
+
+        def read(hash, key)
+          JsonValues.read(hash, key)
+        end
+
+        # Both inputs arrive already normalized — VerifiedRequest's product and
+        # the memoized ServerInfo are deep-frozen, string-keyed copies, and
+        # those two producers own that guarantee. The adapter spot-checks the
+        # cheap top level and holds references instead of re-walking
+        # up-to-1MiB request trees on every call.
+        def frozen_hash!(value)
+          unless value.is_a?(Hash) && value.frozen?
+            raise ArgumentError, "verified request and server info must be frozen Hash values"
+          end
+
+          value
+        end
+
+        def deep_freeze(value)
+          JsonValues.deep_freeze(value)
+        end
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/server_info.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    module Internal
+      # Validates the host's mcp.server_info result into the frozen,
+      # string-keyed identity hash the SDK boundary requires.
+      module ServerInfo
+        KEY_MAP = {
+          "name" => "name",
+          "version" => "version",
+          "title" => "title",
+          "instructions" => "instructions",
+          name: "name",
+          version: "version",
+          title: "title",
+          instructions: "instructions"
+        }.freeze
+
+        module_function
+
+        def normalize(value)
+          raise ArgumentError, "mcp.server_info must return a Hash" unless value.is_a?(Hash)
+
+          unknown = value.keys - KEY_MAP.keys
+          raise ArgumentError, "mcp.server_info contains unsupported keys" unless unknown.empty?
+
+          canonical_keys = value.keys.map { |key| KEY_MAP.fetch(key) }
+          raise ArgumentError, "mcp.server_info contains duplicate keys" unless canonical_keys.uniq == canonical_keys
+
+          normalized = value.to_h do |key, field|
+            [ KEY_MAP.fetch(key).dup.freeze, string_field(field) ]
+          end
+          %w[name version].each do |required|
+            field = normalized[required]
+            raise ArgumentError, "mcp.server_info requires name and version" unless field.is_a?(String) && !field.empty?
+          end
+          normalized.freeze
+        end
+
+        def string_field(value)
+          raise ArgumentError, "mcp.server_info values must be strings" unless value.is_a?(String)
+
+          value.dup.freeze
+        end
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/verified_request.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hitch
+  module MCP
+    module Internal
+      # Builds the one immutable request value that may cross into the SDK.
+      # HTTP media and body-size admission happen before this object sees bytes.
+      class VerifiedRequest
+        CLIENT_INFO_KEY = "io.modelcontextprotocol/clientInfo"
+        CLIENT_INFO_STRING_KEYS = %w[name version title description websiteUrl].freeze
+
+        class Failure < StandardError
+          attr_reader :http_status, :code, :request_id, :data
+
+          def initialize(http_status:, code:, message:, request_id: nil, data: nil)
+            @http_status = http_status
+            @code = code
+            @request_id = request_id
+            @data = data
+            super(message)
+          end
+        end
+
+        class << self
+          def call(raw_body:, headers:)
+            new(raw_body, headers).call
+          end
+        end
+
+        def initialize(raw_body, headers)
+          @raw_body = raw_body
+          @headers = headers
+        end
+
+        def call
+          parsed = parse
+          validate_json_values!(parsed)
+          request_id = validate_envelope!(parsed)
+          validate_metadata!(parsed, request_id)
+          validate_protocol_and_method_headers!(parsed, request_id)
+          validate_method!(parsed, request_id)
+          validate_call_shape!(parsed, request_id)
+          validate_name_header!(parsed, request_id)
+          validate_reserved_arguments!(parsed, request_id)
+          # The parse output is freshly built and aliased by nothing, so the
+          # product needs freezing, not another copy of the whole tree.
+          JsonValues.deep_freeze(parsed)
+        end
+
+        private
+
+        attr_reader :raw_body, :headers
+
+        def parse
+          source = raw_body.dup.force_encoding(Encoding::UTF_8)
+          parse_error! unless source.valid_encoding?
+
+          JSON.parse(source, allow_duplicate_key: false)
+        rescue JSON::ParserError => error
+          if error.message.include?("duplicate key")
+            failure!(400, -32600, "Invalid Request")
+          else
+            parse_error!
+          end
+        rescue JSON::GeneratorError, JSON::NestingError
+          parse_error!
+        end
+
+        def validate_json_values!(value)
+          case value
+          when Hash
+            value.each do |key, child|
+              parse_error! unless key.is_a?(String) && key.valid_encoding?
+
+              validate_json_values!(child)
+            end
+          when Array
+            value.each { |child| validate_json_values!(child) }
+          when String
+            parse_error! unless value.valid_encoding?
+          when Float
+            invalid_request! unless value.finite?
+          end
+        end
+
+        def validate_envelope!(request)
+          invalid_request! unless request.is_a?(Hash)
+          invalid_request! unless request["jsonrpc"] == "2.0"
+          invalid_request! unless request.key?("id")
+          invalid_request! unless request["id"].is_a?(String) || request["id"].is_a?(Numeric)
+          invalid_request! unless request["method"].is_a?(String)
+          invalid_request! unless request["params"].is_a?(Hash)
+
+          request.fetch("id")
+        end
+
+        def validate_metadata!(request, request_id)
+          metadata = request.fetch("params")["_meta"]
+          invalid_params!(request_id, 400) unless metadata.is_a?(Hash)
+
+          version = metadata["io.modelcontextprotocol/protocolVersion"]
+          capabilities = metadata["io.modelcontextprotocol/clientCapabilities"]
+          invalid_params!(request_id, 400) unless version.is_a?(String)
+          invalid_params!(request_id, 400) unless capabilities.is_a?(Hash)
+
+          return unless metadata.key?(CLIENT_INFO_KEY)
+
+          client_info = metadata[CLIENT_INFO_KEY]
+
+          valid = client_info.is_a?(Hash) &&
+            client_info["name"].is_a?(String) && !client_info["name"].empty? &&
+            client_info["version"].is_a?(String) && !client_info["version"].empty? &&
+            valid_client_info_strings?(client_info) &&
+            valid_client_info_icons?(client_info)
+          invalid_params!(request_id, 400) unless valid
+        end
+
+        def valid_client_info_strings?(client_info)
+          CLIENT_INFO_STRING_KEYS.all? do |key|
+            !client_info.key?(key) || client_info[key].is_a?(String)
+          end
+        end
+
+        def valid_client_info_icons?(client_info)
+          return true unless client_info.key?("icons")
+
+          icons = client_info["icons"]
+          icons.is_a?(Array) && icons.all? do |icon|
+            icon.is_a?(Hash) &&
+              icon["src"].is_a?(String) &&
+              (!icon.key?("mimeType") || icon["mimeType"].is_a?(String)) &&
+              (!icon.key?("sizes") || icon["sizes"].is_a?(Array) && icon["sizes"].all?(String))
+          end
+        end
+
+        def validate_protocol_and_method_headers!(request, request_id)
+          metadata = request.fetch("params").fetch("_meta")
+          protocol_version = HeaderField.single(headers.fetch(:protocol_version, nil))
+          method = HeaderField.single(headers.fetch(:method, nil))
+
+          header_mismatch!(request_id) unless protocol_version == metadata.fetch("io.modelcontextprotocol/protocolVersion")
+          header_mismatch!(request_id) unless method == request.fetch("method")
+
+          return if protocol_version == Protocol::VERSION
+
+          failure!(
+            400,
+            -32022,
+            "Unsupported protocol version",
+            request_id: request_id,
+            data: {
+              "supportedVersions" => [ Protocol::VERSION ],
+              "supported" => [ Protocol::VERSION ],
+              "requested" => protocol_version
+            }
+          )
+        end
+
+        def validate_method!(request, request_id)
+          return if Protocol::METHODS.include?(request.fetch("method"))
+
+          failure!(404, -32601, "Method not found", request_id: request_id)
+        end
+
+        def validate_call_shape!(request, request_id)
+          return unless request.fetch("method") == "tools/call"
+
+          params = request.fetch("params")
+          name = params["name"]
+          arguments = params["arguments"]
+          invalid_params!(request_id, 200) unless name.is_a?(String) && !name.empty?
+          invalid_params!(request_id, 200) unless !params.key?("arguments") || arguments.is_a?(Hash)
+        end
+
+        def validate_name_header!(request, request_id)
+          supplied_name = headers.fetch(:name, nil)
+
+          if request.fetch("method") == "tools/call"
+            expected_name = request.fetch("params").fetch("name")
+            header_mismatch!(request_id) unless HeaderField.single(supplied_name) == expected_name
+          elsif !supplied_name.nil?
+            header_mismatch!(request_id)
+          end
+        end
+
+        def validate_reserved_arguments!(request, request_id)
+          return unless request.fetch("method") == "tools/call"
+
+          arguments = request.fetch("params")["arguments"]
+          return unless arguments
+
+          invalid_params!(request_id, 200) if arguments.key?("server_context")
+        end
+
+        def parse_error!
+          failure!(400, -32700, "Parse error")
+        end
+
+        def invalid_request!
+          failure!(400, -32600, "Invalid Request")
+        end
+
+        def invalid_params!(request_id, http_status)
+          failure!(http_status, -32602, "Invalid params", request_id: request_id)
+        end
+
+        def header_mismatch!(request_id)
+          failure!(400, -32020, "HeaderMismatch", request_id: request_id)
+        end
+
+        def failure!(http_status, code, message, request_id: nil, data: nil)
+          raise Failure.new(
+            http_status: http_status,
+            code: code,
+            message: message,
+            request_id: request_id,
+            data: deep_copy_and_freeze(data)
+          )
+        end
+
+        def deep_copy_and_freeze(value)
+          JsonValues.deep_string_copy_and_freeze(value)
+        end
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    # Framework-owned collaborators behind the public MCP surface (Endpoint,
+    # Tool, Registry, Result, Context). Nothing under this namespace is host
+    # API; shapes here may change in any release without notice.
+    module Internal
+    end
+  end
+end