connectors 0.1.0

data/lib/connectors/mcp/client.rb

@@ -0,0 +1,137 @@
+module Connectors
+  module MCP
+    class Client
+      def initialize(grant:, actor:, principals: nil, cancellation: nil)
+        @access = Access.new(grant: grant, actor: actor, principals: principals)
+        @cancellation = cancellation
+      end
+
+      def tools
+        @access.require!
+        fingerprint = @access.fingerprint
+        result = []
+        cursors = Set.new
+        cursor = nil
+        Connectors.configuration.mcp.max_pages.times do
+          @access.require!
+          unchanged!(fingerprint)
+          page = request("tools/list", cursor.nil? ? {} : { "cursor" => cursor })
+          raise ProtocolError, "Invalid tools page" unless page.fetch("resultType", "complete") == "complete" && page["tools"].is_a?(Array)
+          page["tools"].each do |tool|
+            raise ProtocolError, "Invalid tool descriptor" unless tool.is_a?(Hash) && tool["name"].is_a?(String) && !tool["name"].empty?
+            scan = ::MCP::Client::McpParamHeaders.scan(tool["inputSchema"])
+            next unless scan[:valid] && scan[:declarations].none? { |d| d[:type] == "number" }
+            ProtocolSchema.validate!("Tool", tool)
+            Schema.new(tool["inputSchema"])
+            Schema.new(tool["outputSchema"]) if tool.key?("outputSchema")
+            if (previous = result.find { |t| t["name"] == tool["name"] })
+              raise ProtocolError, "Conflicting tool definitions" unless previous == tool
+            else
+              result << tool
+            end
+            raise ProtocolError, "Tool catalog exceeds limit" if result.size > Connectors.configuration.mcp.max_tools
+          end
+          cursor = page["nextCursor"]
+          return result if cursor.nil?
+          raise ProtocolError, "Invalid or repeated pagination cursor" unless cursor.is_a?(String) && cursors.add?(cursor)
+        end
+        raise ProtocolError, "Tool pagination exceeds limit"
+      end
+
+      def call_tool(name:, arguments:)
+        @access.require!(:editor)
+        fingerprint = @access.fingerprint
+        raise ValidationError, "Tool arguments must be an object" unless arguments.is_a?(Hash)
+        tool = tools.find { |t| t["name"] == name } or raise ValidationError, "Unknown MCP tool"
+        Schema.new(tool["inputSchema"]).validate!(arguments)
+        params = { "name" => name, "arguments" => arguments }
+        invoke(tool, params, fingerprint: fingerprint)
+      end
+
+      def subscribe
+        raise ArgumentError, "A notification consumer is required" unless block_given?
+        @access.require!
+        fingerprint = @access.fingerprint
+        transport.request("subscriptions/listen", { "notifications" => { "toolsListChanged" => true } }, subscription: true, cancellation: @cancellation) do |message|
+          @access.require!
+          unchanged!(fingerprint)
+          yield message
+        end
+      end
+
+      def resume(interaction_id:, responses:)
+        Interaction.new(@access).resume(id: interaction_id, responses: responses) do |tool, params, rounds, fingerprint|
+          invoke(tool, params, rounds: rounds, fingerprint: fingerprint)
+        end
+      end
+
+      private
+
+      def invoke(tool, params, rounds: 0, fingerprint:)
+        @access.require!(:editor)
+        unchanged!(fingerprint)
+        headers = ::MCP::Client::McpParamHeaders.build(::MCP::Client::McpParamHeaders.scan(tool["inputSchema"])[:declarations], params["arguments"])
+        result = request("tools/call", params, parameter_headers: headers, fingerprint: fingerprint)
+        if result["resultType"] == "input_required"
+          return Interaction.new(@access).pause(tool: tool, params: params, result: result, rounds: rounds, fingerprint: fingerprint)
+        end
+        ProtocolSchema.validate!("CallToolResult", result)
+        if tool.key?("outputSchema") && !result["isError"]
+          raise ValidationError, "Missing structured tool result" unless result.key?("structuredContent")
+          Schema.new(tool["outputSchema"]).validate!(result["structuredContent"])
+        end
+        result
+      end
+
+      def transport
+        @token = nil
+        data = @access.configuration
+        fingerprint = @access.fingerprint
+        headers = data.fetch("headers", {}).dup
+        case data.fetch("auth_mode", "none")
+        when "bearer" then headers["Authorization"] = "Bearer #{data.fetch('bearer_token')}"
+        when "oauth"
+          begin
+            @token = authorization.access_token
+            headers["Authorization"] = "Bearer #{@token}"
+          rescue AuthorizationRequired
+            # Probe without credentials to obtain the authoritative resource/scope challenge.
+          end
+        end
+        unchanged!(fingerprint)
+        modes = Connectors.configuration.mcp.elicitation_modes
+        capabilities = modes.empty? ? {} : { "elicitation" => modes.to_h { |mode| [ mode, {} ] } }
+        Transport.new(url: data.fetch("server_url"), headers: headers, capabilities: capabilities)
+      end
+
+      def authorization
+        Authorization.new(grant: @access.grant, actor: @access.actor, principals: @access.principals)
+      end
+
+      def request(method, params, fingerprint: nil, **options)
+        role = method == "tools/call" ? :editor : :viewer
+        @access.require!(role)
+        fingerprint ||= @access.fingerprint
+        unchanged!(fingerprint)
+        begin
+          result = transport.request(method, params, cancellation: @cancellation, **options)
+        rescue AuthorizationRequired => error
+          @access.require!(role)
+          unchanged!(fingerprint)
+          if error.challenge["error"] == "insufficient_scope" || !@token
+            raise AuthorizationRequired.new(error.challenge, fingerprint: fingerprint)
+          end
+          authorization.refresh(expected_token: @token)
+          result = transport.request(method, params, cancellation: @cancellation, **options)
+        end
+        @access.require!(role)
+        unchanged!(fingerprint)
+        result
+      end
+
+      def unchanged!(fingerprint)
+        raise AccessDenied, "MCP connection changed during the request" unless fingerprint == @access.fingerprint
+      end
+    end
+  end
+end

data/lib/connectors/mcp/connection_config.rb

@@ -0,0 +1,48 @@
+module Connectors
+  module MCP
+    class ConnectionConfig
+      FIELDS = %w[server_url auth_mode bearer_token headers client_information authorization_server].freeze
+      PUBLIC_FIELDS = %w[server_url auth_mode authorization_server].freeze
+      RESERVED_HEADERS = /\A(?:host|content-.*|accept|connection|transfer-encoding|cookie|proxy-.*|mcp-.*)\z/i
+
+      def self.resolve(data, connector:, **options)
+        fixed = connector.mcp_config
+        raise ValidationError, "Connector does not support MCP" unless fixed
+        fixed.each do |key, value|
+          raise ValidationError, "#{key} is fixed for this MCP provider" if data.key?(key) && data[key] != value
+        end
+        if fixed["auth_mode"] == "oauth" && (data.keys & %w[bearer_token headers]).any?
+          raise ValidationError, "This MCP provider requires OAuth authentication"
+        end
+        validate!(fixed.merge(data), **options)
+      end
+
+      def self.validate!(data, internal: false, require_secrets: true)
+        allowed = internal ? FIELDS + [ "mcp_oauth" ] : FIELDS
+        raise ValidationError, "Unsupported MCP credential fields" if (data.keys - allowed).any?
+        HTTP.new.validate_url!(data.fetch("server_url", ""))
+        mode = data.fetch("auth_mode", "none")
+        raise ValidationError, "Unsupported MCP authentication mode" unless %w[none bearer headers oauth].include?(mode)
+        if mode == "bearer" && (require_secrets || data.key?("bearer_token")) && (!data["bearer_token"].is_a?(String) || data["bearer_token"].blank? || data["bearer_token"].match?(/[\r\n]/))
+          raise ValidationError, "A valid bearer token is required"
+        end
+        headers = data.fetch("headers", {})
+        raise ValidationError, "Headers must be an object" unless headers.is_a?(Hash)
+        headers.each do |key, value|
+          unless key.is_a?(String) && key.match?(::MCP::Client::McpParamHeaders::RFC9110_TOKEN) && !key.match?(RESERVED_HEADERS) && value.is_a?(String) && !value.match?(/[\r\n\x00]/)
+            raise ValidationError, "Invalid or reserved MCP header"
+          end
+          raise ValidationError, "Authorization header requires headers auth mode" if key.casecmp?("authorization") && mode != "headers"
+        end
+        if data["client_information"] && !data["client_information"].is_a?(Hash)
+          raise ValidationError, "Client information must be an object"
+        end
+        data
+      end
+
+      def self.public_data(data)
+        data.slice(*PUBLIC_FIELDS)
+      end
+    end
+  end
+end

data/lib/connectors/mcp/http.rb

@@ -0,0 +1,108 @@
+require "net/http"
+require "ipaddr"
+require "socket"
+require "timeout"
+
+module Connectors
+  module MCP
+    # Pins the validated address while retaining the hostname for TLS/SNI.
+    # Redirects and environment proxies are deliberately not followed.
+    class HTTP
+      Response = Data.define(:status, :headers, :body)
+      BLOCKED = %w[0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 127.0.0.0/8 169.254.0.0/16 172.16.0.0/12 192.0.0.0/24 192.168.0.0/16 198.18.0.0/15 224.0.0.0/4 240.0.0.0/4 ::/128 ::1/128 fc00::/7 fe80::/10 ff00::/8].map { |s| IPAddr.new(s) }.freeze
+
+      def initialize(settings: Connectors.configuration.mcp)
+        @settings = settings
+      end
+
+      def validate_url!(url)
+        uri = URI.parse(url.to_s)
+        raise ConfigurationRequired, "Invalid MCP destination" unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.fragment
+        loopback = uri.hostname == "localhost" || IPAddr.new(uri.hostname).loopback? rescue false
+        unless uri.scheme == "https" || (@settings.allow_loopback_http && loopback && uri.scheme == "http")
+          raise ConfigurationRequired, "MCP destinations require HTTPS"
+        end
+        uri
+      rescue URI::InvalidURIError
+        raise ConfigurationRequired, "Invalid MCP destination"
+      end
+
+      def call(url:, method: :get, headers: {}, body: nil, stream: false, cancellation: nil, &consumer)
+        cancellation_key = nil
+        cancellation&.check!
+        timeout = stream ? @settings.stream_timeout : @settings.request_timeout
+        raise ConfigurationRequired, "Request limits must be positive" unless timeout.to_f.positive? && @settings.max_bytes.to_i.positive?
+        raise ValidationError, "MCP request exceeds size limit" if body && body.bytesize > @settings.max_bytes
+        Timeout.timeout(timeout, TransportError, "MCP request deadline exceeded") do
+          uri = validate_url!(url)
+          addresses = Addrinfo.getaddrinfo(uri.hostname, uri.port, nil, :STREAM).map(&:ip_address).uniq
+          raise TransportError, "MCP destination could not be resolved" if addresses.empty?
+          permitted = @settings.private_hosts.include?(uri.hostname) || (@settings.allow_loopback_http && addresses.all? { |ip| IPAddr.new(ip).loopback? })
+          unless permitted || addresses.none? { |ip| blocked?(ip) }
+            raise ConfigurationRequired, "MCP destination resolves to a restricted network"
+          end
+          connection = Net::HTTP.new(uri.hostname, uri.port, nil)
+          connection.ipaddr = addresses.first
+          connection.use_ssl = uri.scheme == "https"
+          connection.open_timeout = @settings.open_timeout
+          connection.read_timeout = timeout
+          connection.write_timeout = timeout
+          connection.max_retries = 0
+          request = Net::HTTPGenericRequest.new(method.to_s.upcase, !body.nil?, true, uri.request_uri, headers)
+          request.body = body if body
+          connection.start do |http|
+            cancellation_key = cancellation&.attach do
+              begin
+                http.finish if http.started?
+              rescue IOError
+                # The response may have closed the connection concurrently.
+              end
+            end
+            http.request(request) do |response|
+              status = response.code.to_i
+              response_headers = response.each_header.to_h
+              content = +""
+              size = 0
+              response.read_body do |chunk|
+                cancellation&.check!
+                size += chunk.bytesize
+                raise TransportError, "MCP response exceeds size limit" if size > @settings.max_bytes
+                if consumer && status.between?(200, 299)
+                  consumer.call(chunk, response_headers)
+                else
+                  content << chunk
+                end
+              end
+              result = Response.new(status: status, headers: response_headers, body: content)
+              raise HTTPError.new(status: status, headers: response_headers, body: content) unless status.between?(200, 299)
+              return result
+            end
+          end
+        end
+      rescue IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError
+        cancellation&.check!
+        raise TransportError, "MCP network request failed"
+      ensure
+        cancellation&.detach(cancellation_key) if cancellation_key
+      end
+
+      def json(**options)
+        response = call(**options)
+        raise ProtocolError, "Expected JSON metadata" unless response.headers["content-type"].to_s.split(";").first == "application/json"
+        parsed = JSON.parse(response.body)
+        raise ProtocolError, "Expected JSON object" unless parsed.is_a?(Hash)
+        parsed
+      rescue JSON::ParserError
+        raise ProtocolError, "Invalid JSON metadata"
+      end
+
+      private
+
+      def blocked?(address)
+        ip = IPAddr.new(address)
+        ip = ip.native if ip.ipv4_mapped?
+        BLOCKED.any? { |range| range.include?(ip) }
+      end
+    end
+  end
+end

data/lib/connectors/mcp/interaction.rb

@@ -0,0 +1,82 @@
+module Connectors
+  module MCP
+    class Interaction
+      def initialize(access)
+        @access = access
+      end
+
+      def pause(tool:, params:, result:, rounds:, fingerprint:)
+        ProtocolSchema.validate!("InputRequiredResult", result)
+        raise ProtocolError, "MCP interaction round limit exceeded" if rounds >= Connectors.configuration.mcp.max_rounds
+        requests = result.fetch("inputRequests", {})
+        raise ProtocolError, "Invalid MCP input requests" unless requests.is_a?(Hash) && (requests.any? || result["requestState"].is_a?(String))
+        if result.key?("requestState") && !result["requestState"].is_a?(String)
+          raise ProtocolError, "Invalid MCP request state"
+        end
+        requests.each_value { |request| validate_request!(request) }
+        @access.require!(:editor)
+        raise AccessDenied, "MCP connection changed" unless fingerprint == @access.fingerprint
+        record = Connectors::McpInteraction.create!(grant: @access.grant, actor_key: @access.actor_key, fingerprint: fingerprint,
+          expires_at: Connectors.configuration.mcp.transaction_ttl.from_now,
+          payload: { "tool" => tool, "params" => params, "result" => result, "rounds" => rounds })
+        # The opaque server state stays encrypted at rest, never in a caller-controlled resume payload.
+        result.except("requestState").merge("interaction_id" => record.id)
+      end
+
+      def resume(id:, responses:)
+        @access.require!(:editor)
+        record = Connectors::McpInteraction.find_by(id: id, grant_id: @access.grant.id)
+        raise AccessDenied, "Unknown MCP interaction" unless record
+        payload = record.claim!(@access) do |pending|
+          validate_responses!(pending.fetch("result").fetch("inputRequests", {}), responses)
+        end
+        claimed = true
+        params = payload.fetch("params").except("inputResponses", "requestState")
+        params["inputResponses"] = responses unless responses.empty?
+        params["requestState"] = payload["result"]["requestState"] if payload["result"].key?("requestState")
+        yield payload.fetch("tool"), params, payload.fetch("rounds") + 1, record.fingerprint
+      ensure
+        record.update!(status: "consumed", payload: { "cleared" => true }) if claimed
+      end
+
+      private
+
+      def validate_request!(request)
+        ProtocolSchema.validate!("ElicitRequest", request)
+        unless request.is_a?(Hash) && request["method"] == "elicitation/create" && request["params"].is_a?(Hash)
+          raise ProtocolError, "Unsupported MCP input request"
+        end
+        params = request["params"]
+        mode = params.fetch("mode", "form")
+        raise ProtocolError, "Unadvertised elicitation mode" unless Connectors.configuration.mcp.elicitation_modes.include?(mode)
+        raise ProtocolError, "Invalid elicitation message" unless params["message"].is_a?(String)
+        case mode
+        when "url" then HTTP.new.validate_url!(params["url"])
+        when "form" then Schema.new(params["requestedSchema"])
+        else raise ProtocolError, "Unsupported elicitation mode"
+        end
+      end
+
+      def validate_responses!(requests, responses)
+        unless responses.is_a?(Hash) && responses.keys.sort == requests.keys.sort
+          raise ValidationError, "Input responses must match the pending requests"
+        end
+        requests.each do |key, request|
+          response = responses[key]
+          ProtocolSchema.validate!("ElicitResult", response)
+          unless response.is_a?(Hash) && %w[accept decline cancel].include?(response["action"])
+            raise ValidationError, "Invalid elicitation action"
+          end
+          mode = request["params"].fetch("mode", "form")
+          if mode == "form" && response["action"] == "accept"
+            Schema.new(request["params"]["requestedSchema"]).validate!(response["content"])
+          elsif response.key?("content")
+            raise ValidationError, "This elicitation response must omit content"
+          end
+        end
+      rescue ProtocolError
+        raise ValidationError, "Invalid elicitation response"
+      end
+    end
+  end
+end

data/lib/connectors/mcp/pending_transaction.rb

@@ -0,0 +1,26 @@
+module Connectors
+  module MCP
+    module PendingTransaction
+      extend ActiveSupport::Concern
+      included do
+        belongs_to :grant, class_name: "Connectors::Grant"
+        serialize :payload, coder: JSON, type: Hash
+        encrypts :payload
+        scope :expired, -> { where(expires_at: ..Time.current) }
+      end
+
+      def claim!(access)
+        with_lock do
+          access.require!(self.class::REQUIRED_ROLE)
+          unless status == "pending" && expires_at > Time.current && grant_id == access.grant.id && actor_key == access.actor_key && fingerprint == access.fingerprint
+            raise AccessDenied, "MCP transaction is expired, changed, or already used"
+          end
+          data = payload.deep_dup
+          yield data if block_given?
+          update!(status: "claimed")
+          data
+        end
+      end
+    end
+  end
+end