connectors 0.1.0

data/lib/connectors/mcp/protocol/LICENSE

@@ -0,0 +1,216 @@
+The MCP project is undergoing a licensing transition from the MIT License to the Apache License, Version 2.0 ("Apache-2.0"). All new code and specification contributions to the project are licensed under Apache-2.0. Documentation contributions (excluding specifications) are licensed under CC-BY-4.0.
+
+Contributions for which relicensing consent has been obtained are licensed under Apache-2.0. Contributions made by authors who originally licensed their work under the MIT License and who have not yet granted explicit permission to relicense remain licensed under the MIT License.
+
+No rights beyond those granted by the applicable original license are conveyed for such contributions.
+
+---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on behalf
+      of the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+---
+
+MIT License
+
+Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Creative Commons Attribution 4.0 International (CC-BY-4.0)
+
+Documentation in this project (excluding specifications) is licensed under
+CC-BY-4.0. See https://creativecommons.org/licenses/by/4.0/legalcode for
+the full license text.

data/lib/connectors/mcp/protocol/README.md

@@ -0,0 +1,8 @@
+# MCP protocol schema
+
+Unmodified generated JSON Schema for MCP 2026-07-28 from:
+https://github.com/modelcontextprotocol/modelcontextprotocol/blob/3f6e5e17e2a83b47dfb37b20d159e0e27efa316c/schema/2026-07-28/schema.json
+
+The upstream license is included in LICENSE. This file is vendored to make response validation deterministic and avoid runtime network schema resolution. Update it only alongside protocol contract tests and a protocol-version change. Client compatibility normalization (absent resultType) lives in ProtocolSchema, not in this source artifact.
+
+Application correction (2026-09-22): `ProtocolSchema` corrects only the in-memory `ElicitResult.content` numeric union from `integer` to `number`. The normative TypeScript definition at the same commit, [schema.ts line 3148](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/3f6e5e17e2a83b47dfb37b20d159e0e27efa316c/schema/2026-07-28/schema.ts#L3148), permits `string | number | boolean | string[]`. The generated JSON incorrectly narrows that member. The vendored JSON remains unmodified; `interaction_spec.rb` covers accepting a decimal form response.

data/lib/connectors/mcp/protocol_schema.rb

@@ -0,0 +1,30 @@
+module Connectors
+  module MCP
+    # The normative schema is an offline, pinned upstream artifact; do not recreate its types here.
+    module ProtocolSchema
+      DOCUMENT = JSON.parse(File.read(File.join(__dir__, "protocol/2026-07-28.json"))).freeze
+      VALIDATORS = %w[Tool CallToolResult InputRequiredResult ElicitRequest ElicitResult].to_h do |name|
+        document = DOCUMENT
+        if name == "ElicitResult"
+          # Normative schema.ts at the pinned commit, line 3148, permits `number`.
+          # The generated JSON incorrectly narrows this union member to integer.
+          document = DOCUMENT.deep_dup
+          alternatives = document.fetch("$defs").fetch(name).fetch("properties").fetch("content").fetch("additionalProperties").fetch("anyOf")
+          alternatives.last["type"] = %w[string number boolean]
+        end
+        [ name, JSONSchemer.schema(document.merge("$ref" => "#/$defs/#{name}"), ref_resolver: ->(_) { raise ProtocolError, "External protocol reference" }) ]
+      end.freeze
+      module_function
+
+      def validate!(name, value)
+        candidate = value
+        if %w[CallToolResult InputRequiredResult].include?(name) && value.is_a?(Hash) && !value.key?("resultType")
+          candidate = value.merge("resultType" => "complete")
+        end
+        Timeout.timeout(Connectors.configuration.mcp.schema_timeout, ProtocolError, "Protocol validation deadline exceeded") do
+          raise ProtocolError, "Invalid MCP #{name}" unless VALIDATORS.fetch(name).valid?(candidate)
+        end
+      end
+    end
+  end
+end

data/lib/connectors/mcp/schema.rb

@@ -0,0 +1,45 @@
+module Connectors
+  module MCP
+    class Schema
+      DIALECTS = %w[https://json-schema.org/draft/2020-12/schema http://json-schema.org/draft-07/schema#].freeze
+      def initialize(schema)
+        raise ValidationError, "Tool schema must be an object" unless schema.is_a?(Hash)
+        dialect = schema.fetch("$schema", DIALECTS.first)
+        raise ValidationError, "Unsupported schema dialect" unless DIALECTS.include?(dialect)
+        check_complexity!(schema)
+        resolver = ->(_uri) { raise ValidationError, "External schema references are disabled" }
+        @schema = JSONSchemer.schema(schema, ref_resolver: resolver)
+        bounded { raise ValidationError, "Invalid tool schema" unless @schema.valid_schema? }
+      rescue JSONSchemer::UnknownRef
+        raise ValidationError, "Unresolved schema reference"
+      end
+
+      def validate!(value)
+        bounded { raise ValidationError, "Value does not satisfy tool schema" unless @schema.valid?(value) }
+      rescue JSONSchemer::UnknownRef
+        raise ValidationError, "Unresolved schema reference"
+      end
+
+      private
+
+      def bounded(&block)
+        Timeout.timeout(Connectors.configuration.mcp.schema_timeout, ValidationError, "Schema validation deadline exceeded", &block)
+      end
+
+      def check_complexity!(schema)
+        nodes = [ [ schema, 0 ] ]
+        count = 0
+        until nodes.empty?
+          node, depth = nodes.pop
+          count += 1
+          raise ValidationError, "Schema is too complex" if count > Connectors.configuration.mcp.max_schema_nodes || depth > 50
+          children = node.is_a?(Hash) ? node.values : (node.is_a?(Array) ? node : [])
+          if node.is_a?(Hash) && node["$ref"].is_a?(String) && !node["$ref"].start_with?("#")
+            raise ValidationError, "External schema references are disabled"
+          end
+          children.each { |child| nodes << [ child, depth + 1 ] }
+        end
+      end
+    end
+  end
+end

data/lib/connectors/mcp/settings.rb

@@ -0,0 +1,27 @@
+module Connectors
+  module MCP
+    class Settings
+      attr_accessor :private_hosts, :allow_loopback_http, :client_name, :callback_url,
+                    :client_metadata_url, :open_timeout, :request_timeout, :stream_timeout,
+                    :max_bytes, :max_pages, :max_tools, :max_rounds, :transaction_ttl,
+                    :schema_timeout, :max_schema_nodes, :elicitation_modes, :assertion_provider
+
+      def initialize
+        @private_hosts = []
+        @allow_loopback_http = false
+        @client_name = "Connectors"
+        @open_timeout = 5
+        @request_timeout = 30
+        @stream_timeout = 300
+        @max_bytes = 4 * 1024 * 1024
+        @max_pages = 100
+        @max_tools = 1000
+        @max_rounds = 10
+        @transaction_ttl = 15.minutes
+        @schema_timeout = 1
+        @max_schema_nodes = 10_000
+        @elicitation_modes = []
+      end
+    end
+  end
+end

data/lib/connectors/mcp/token_endpoint.rb

@@ -0,0 +1,48 @@
+require "base64"
+
+module Connectors
+  module MCP
+    class TokenEndpoint
+      def self.exchange(metadata:, client:, params:)
+        method = client.fetch("token_endpoint_auth_method", "none")
+        supported = metadata.fetch("token_endpoint_auth_methods_supported", [ "client_secret_basic" ])
+        # Public clients are permitted when the AS omits auth-method metadata.
+        unless supported.include?(method) || (method == "none" && !metadata.key?("token_endpoint_auth_methods_supported"))
+          raise ConfigurationRequired, "Client authentication method is not advertised"
+        end
+        headers = { "Accept" => "application/json", "Content-Type" => "application/x-www-form-urlencoded" }
+        form = params.merge("client_id" => client.fetch("client_id"))
+        case method
+        when "none"
+          raise ConfigurationRequired, "Confidential client cannot use public authentication" if client["client_secret"].present?
+        when "client_secret_basic"
+          pair = %w[client_id client_secret].map { |key| URI.encode_www_form_component(client.fetch(key)) }.join(":")
+          headers["Authorization"] = "Basic #{Base64.strict_encode64(pair)}"
+          form.delete("client_id")
+        when "client_secret_post"
+          form["client_secret"] = client.fetch("client_secret")
+        when "private_key_jwt"
+          signer = Connectors.configuration.mcp.assertion_provider or raise ConfigurationRequired, "Client assertion provider is required"
+          form["client_assertion_type"] = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+          form["client_assertion"] = signer.call(client.fetch("client_id"), metadata.fetch("token_endpoint"))
+        else
+          raise ConfigurationRequired, "Unsupported client authentication method"
+        end
+        tokens = HTTP.new.json(url: metadata.fetch("token_endpoint"), method: :post, headers: headers, body: URI.encode_www_form(form))
+        unless tokens["access_token"].is_a?(String) && tokens["access_token"].match?(/\A[A-Za-z0-9\-._~+\/]+=*\z/) && tokens["token_type"].to_s.casecmp?("Bearer")
+          raise ProtocolError, "Invalid OAuth token response"
+        end
+        if tokens.key?("expires_in")
+          raise ProtocolError, "Invalid token expiry" unless tokens["expires_in"].is_a?(Numeric) && tokens["expires_in"].finite? && tokens["expires_in"] >= 0
+          tokens["expires_at"] = Time.current.to_f + tokens["expires_in"]
+        end
+        if tokens.key?("refresh_token") && !tokens["refresh_token"].is_a?(String)
+          raise ProtocolError, "Invalid refresh token"
+        end
+        tokens
+      rescue KeyError
+        raise ConfigurationRequired, "Incomplete OAuth client information"
+      end
+    end
+  end
+end

data/lib/connectors/mcp/transport.rb

@@ -0,0 +1,105 @@
+module Connectors
+  module MCP
+    class Transport
+      def initialize(url:, headers: {}, capabilities: {})
+        @url, @headers, @capabilities = url, headers, capabilities
+      end
+
+      def request(method, params = {}, parameter_headers: {}, subscription: false, cancellation: nil)
+        id = SecureRandom.uuid
+        request = ::MCP::Client::ModernEnvelope.stamp(
+          { jsonrpc: "2.0", id: id, method: method, params: params },
+          protocol_version: PROTOCOL_VERSION,
+          client_info: { name: Connectors.configuration.mcp.client_name, version: Connectors::VERSION },
+          capabilities: @capabilities)
+        headers = @headers.merge("Content-Type" => "application/json", "Accept" => "application/json, text/event-stream",
+          "MCP-Protocol-Version" => PROTOCOL_VERSION, "Mcp-Method" => method).merge(parameter_headers)
+        headers["Mcp-Name"] = ::MCP::Client::McpParamHeaders.encode_value(params.fetch("name")) if method == "tools/call"
+        json = +""
+        parser = EventStreamParser::Parser.new
+        acknowledged = false
+        filter = {}
+        HTTP.new.call(url: @url, method: :post, headers: headers, body: JSON.generate(request), stream: subscription, cancellation: cancellation) do |chunk, response_headers|
+          case response_headers["content-type"].to_s.split(";").first
+          when "application/json"
+            raise ProtocolError, "Subscriptions require an event stream" if subscription
+            json << chunk
+          when "text/event-stream"
+            parser.feed(chunk) do |_type, data, _event_id|
+              next if data.empty?
+              message = parse(data)
+              if message.key?("id")
+                validate_response!(message, id)
+                raise ProtocolError, "Subscription completed before acknowledgment" if subscription && !acknowledged
+                if subscription && message.dig("result", "_meta", "io.modelcontextprotocol/subscriptionId") != id
+                  raise ProtocolError, "Invalid subscription completion correlation"
+                end
+                return message.fetch("result")
+              end
+              validate_notification!(message)
+              if subscription
+                subscription_id = message.dig("params", "_meta", "io.modelcontextprotocol/subscriptionId")
+                raise ProtocolError, "Invalid subscription correlation" unless subscription_id == id
+                unless acknowledged
+                  raise ProtocolError, "Missing subscription acknowledgment" unless message["method"] == "notifications/subscriptions/acknowledged"
+                  filter = message.dig("params", "notifications")
+                  requested = params.fetch("notifications", {})
+                  unless filter.is_a?(Hash) && filter.all? { |key, value| value == true && requested[key] == true }
+                    raise ProtocolError, "Invalid acknowledged subscription filter"
+                  end
+                  acknowledged = true
+                else
+                  key = { "notifications/tools/list_changed" => "toolsListChanged", "notifications/prompts/list_changed" => "promptsListChanged", "notifications/resources/list_changed" => "resourcesListChanged" }[message["method"]]
+                  raise ProtocolError, "Notification violates subscription filter" unless key && filter[key]
+                end
+                yield message if block_given?
+              end
+            end
+          else
+            raise ProtocolError, "Unsupported MCP response content type"
+          end
+        end
+        raise TransportError, "MCP stream ended without a result; outcome may be unknown" if json.empty?
+        message = parse(json)
+        validate_response!(message, id)
+        message.fetch("result")
+      rescue HTTPError => error
+        if error.status == 401 || (error.status == 403 && challenge(error)["error"] == "insufficient_scope")
+          raise AuthorizationRequired.new(challenge(error))
+        end
+        raise
+      end
+
+      private
+
+      def challenge(error)
+        ::MCP::Client::OAuth::Discovery.parse_www_authenticate(error.headers["www-authenticate"])
+      end
+
+      def parse(data)
+        value = JSON.parse(data)
+        raise ProtocolError, "Invalid JSON-RPC envelope" unless value.is_a?(Hash) && value["jsonrpc"] == "2.0"
+        value
+      rescue JSON::ParserError
+        raise ProtocolError, "Malformed MCP JSON"
+      end
+
+      def validate_notification!(message)
+        raise ProtocolError, "Invalid server notification" unless message["method"].is_a?(String) && !message.key?("result") && !message.key?("error")
+      end
+
+      def validate_response!(message, id)
+        raise ProtocolError, "Mismatched JSON-RPC response ID" unless message["id"] == id
+        if message.key?("error") && !message.key?("result")
+          error = message["error"]
+          raise ProtocolError, "Malformed JSON-RPC error" unless error.is_a?(Hash) && error["code"].is_a?(Integer) && error["message"].is_a?(String)
+          # Remote error text/data can include secrets; do not expose it via exceptions.
+          raise ProtocolError.new("Remote MCP protocol error (#{error['code']})", code: error["code"])
+        end
+        result = message["result"]
+        raise ProtocolError, "Invalid JSON-RPC result" if message.key?("error") || message.key?("method") || !result.is_a?(Hash)
+        raise ProtocolError, "Unknown MCP result type" unless %w[complete input_required].include?(result.fetch("resultType", "complete"))
+      end
+    end
+  end
+end

data/lib/connectors/mcp.rb

@@ -0,0 +1,69 @@
+require "mcp"
+require "mcp/client"
+require "mcp/client/modern_envelope"
+require "mcp/client/mcp_param_headers"
+require "mcp/client/oauth/discovery"
+require "mcp/client/oauth/pkce"
+require "json_schemer"
+require "event_stream_parser"
+require "time"
+
+module Connectors
+  module MCP
+    PROTOCOL_VERSION = "2026-07-28".freeze
+    class Error < Connectors::Error; end
+    class AccessDenied < Error; end
+    class ValidationError < Error; end
+    class ProtocolError < Error
+      attr_reader :code
+      def initialize(message, code: nil)
+        @code = code
+        super(message)
+      end
+    end
+    class TransportError < Error; end
+    class ConfigurationRequired < Error; end
+    class Cancelled < Error; end
+    class AuthorizationRequired < Error
+      attr_reader :challenge, :fingerprint
+      def initialize(challenge = {}, fingerprint: nil)
+        @challenge = challenge
+        @fingerprint = fingerprint
+        super("MCP owner authorization required")
+      end
+    end
+    class HTTPError < TransportError
+      attr_reader :status, :headers, :body
+      def initialize(status:, headers:, body:)
+        @status, @headers, @body = status, headers, body
+        super("Remote HTTP request failed (#{status})")
+      end
+
+      # Retry-After permits delay-seconds or an HTTP date. Do not reflect
+      # arbitrary upstream header content into host responses.
+      def retry_after
+        value = headers["retry-after"].to_s
+        return value if value.match?(/\A[0-9]+\z/)
+        Time.httpdate(value).httpdate
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end
+
+require "connectors/mcp/settings"
+require "connectors/mcp/cancellation"
+require "connectors/mcp/access"
+require "connectors/mcp/pending_transaction"
+require "connectors/mcp/http"
+require "connectors/mcp/connection_config"
+require "connectors/mcp/authorization_discovery"
+require "connectors/mcp/token_endpoint"
+require "connectors/mcp/authorization"
+require "connectors/mcp/authorization_context"
+require "connectors/mcp/schema"
+require "connectors/mcp/protocol_schema"
+require "connectors/mcp/transport"
+require "connectors/mcp/interaction"
+require "connectors/mcp/client"

data/lib/connectors/middleware/authenticate_generic.rb

@@ -0,0 +1,79 @@
+require "base64"
+
+module Connectors
+  module Middleware
+    # Faraday middleware that applies a connector's declarative
+    # `authenticate type: :generic, properties: {...}` block to every
+    # outgoing request, mirroring n8n's `IAuthenticateGeneric` runtime
+    # (n8n source: packages/workflow/src/interfaces.ts:278-288 + the
+    # request-helpers consumer at
+    # packages/core/src/node-execute-functions.ts).
+    #
+    # The Grant's credentials hash supplies values for the
+    # `={{$credentials.x}}` templates inside `properties`. Resolution runs
+    # per-request so credentials that rotate between requests (e.g. after a
+    # `preAuthentication` hook lands in Phase 3) are reflected immediately.
+    class AuthenticateGeneric < Faraday::Middleware
+      def initialize(app, grant:, authenticate_config:)
+        super(app)
+        @grant   = grant
+        @config  = authenticate_config
+      end
+
+      def call(env)
+        properties = resolved_properties
+        apply_headers(env, properties[:headers] || properties["headers"])
+        apply_query(env,   properties[:qs]      || properties["qs"])
+        apply_body(env,    properties[:body]    || properties["body"])
+        apply_basic_auth(env, properties[:auth] || properties["auth"])
+
+        @app.call(env)
+      end
+
+      private
+
+      def resolved_properties
+        return {} if @config.nil?
+        AuthInjection.resolve(@config[:properties] || @config["properties"] || {}, @grant.credentials_hash)
+      end
+
+      def apply_headers(env, headers)
+        return if headers.nil? || headers.empty?
+        headers.each { |k, v| env.request_headers[k.to_s] = v.to_s }
+      end
+
+      def apply_query(env, qs)
+        return if qs.nil? || qs.empty?
+        # Faraday 2.x doesn't expose `env.params` reliably during middleware
+        # execution — the canonical mutation point is `env.url.query`. Merge
+        # with any existing query string so per-request params from the
+        # caller aren't clobbered.
+        existing = env.url.query ? URI.decode_www_form(env.url.query).to_h : {}
+        merged   = existing.merge(qs.each_with_object({}) { |(k, v), h| h[k.to_s] = v.to_s })
+        env.url.query = URI.encode_www_form(merged)
+      end
+
+      # JSON-body injection only — most provider auth that sends creds in
+      # the body uses JSON. If a non-Hash body is in flight (form-encoded,
+      # multipart), leave it alone; Faraday's body coercion already ran by
+      # the time this middleware sees the env.
+      def apply_body(env, body)
+        return if body.nil? || body.empty?
+        return unless env.body.is_a?(Hash)
+        body.each { |k, v| env.body[k.to_s] = v }
+      end
+
+      # n8n's `IRequestOptionsSimplifiedAuth.auth` shortcut for HTTP Basic
+      # (interfaces.ts:198-202). Sets the `Authorization: Basic ...` header
+      # directly so we don't double-handle.
+      def apply_basic_auth(env, auth)
+        return if auth.nil?
+        username = auth[:username] || auth["username"]
+        password = auth[:password] || auth["password"]
+        return if username.nil? && password.nil?
+        encoded = Base64.strict_encode64("#{username}:#{password}")
+        env.request_headers["Authorization"] = "Basic #{encoded}"
+      end
+    end
+  end
+end