Skip to content

A platform for community discussion. Free, open, simple.

16.5 KB
Raw Blame
# frozen_string_literal: true

module DiscourseAi
  module Mcp
    class Client
      MCP_SESSION_ID_HEADER = "Mcp-Session-Id"
      JSONRPC_VERSION = "2.0"
      PROTOCOL_VERSION = "2025-11-25"
      MODERN_PROTOCOL_VERSION = "2026-07-28"
      SUPPORTED_CLASSIC_PROTOCOL_VERSIONS = [PROTOCOL_VERSION, "2025-03-26"].freeze
      SUPPORTED_PROTOCOL_VERSIONS = [
        MODERN_PROTOCOL_VERSION,
        *SUPPORTED_CLASSIC_PROTOCOL_VERSIONS,
      ].freeze
      MODERN_ERROR_CODES = [-32_020, -32_021, -32_022].freeze
      DISCOVERY_TOLERATED_STATUSES = [400, 404, 405].freeze
      CLASSIC_INITIALIZE_TOLERATED_STATUSES = [400].freeze
      POST_JSONRPC_OPTIONS = %i[
        params
        session_id
        accept_sse
        notification
        allow_result_error
        tolerate_statuses
        input_schema
        allow_oauth_retry
      ].freeze
      PROTOCOL_META_KEY = "io.modelcontextprotocol/protocolVersion"
      CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo"
      CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities"
      USER_AGENT = "Discourse AI MCP Client"
      MAX_RESPONSE_BODY_LENGTH = 5.megabytes

      Error = Class.new(StandardError)
      AuthorizationRequiredError = Class.new(Error)
      SessionExpiredError = Class.new(Error)
      UnauthorizedError =
        Class.new(Error) do
          attr_reader :challenge_header

          def initialize(message = nil, challenge_header: nil)
            @challenge_header = challenge_header
            super(message)
          end
        end

      Response = Struct.new(:payload, :session_id, :status, :headers, keyword_init: true)

      attr_reader :protocol_version

      def initialize(server, protocol_version: nil)
        @server = server
        if protocol_version.present? && !SUPPORTED_PROTOCOL_VERSIONS.include?(protocol_version)
          raise Error,
                I18n.t(
                  "discourse_ai.mcp_servers.errors.unsupported_protocol_version",
                  version: protocol_version,
                )
        end
        @protocol_version = protocol_version
      end

      def initialize_session
        @protocol_version = MODERN_PROTOCOL_VERSION
        probe = post_jsonrpc("server/discover", tolerate_statuses: DISCOVERY_TOLERATED_STATUSES)
        error = probe.payload["error"] if probe.payload.is_a?(Hash)
        if probe.payload.is_a?(Hash) && probe.payload["jsonrpc"] == JSONRPC_VERSION &&
             error.is_a?(Hash) && MODERN_ERROR_CODES.include?(error["code"])
          if error["code"] == -32_022
            supported = error["data"].is_a?(Hash) ? error["data"]["supported"] : nil
            supported = supported.is_a?(Array) ? supported : []
            version = SUPPORTED_PROTOCOL_VERSIONS.find { |candidate| supported.include?(candidate) }
            if version.nil?
              raise Error, I18n.t("discourse_ai.mcp_servers.errors.no_supported_version")
            end
            return initialize_classic_session(version) if version != MODERN_PROTOCOL_VERSION
          end

          raise_response_error!(
            probe.payload,
            fallback: "discourse_ai.mcp_servers.errors.modern_request_rejected",
          )
        end

        return initialize_classic_session if classic_fallback?(probe)

        raise_response_error!(probe.payload, status: probe.status) if probe.status >= 400

        result = extract_result!(probe.payload)
        unless result["supportedVersions"].is_a?(Array) &&
                 result["supportedVersions"].include?(MODERN_PROTOCOL_VERSION)
          raise Error, I18n.t("discourse_ai.mcp_servers.errors.invalid_discovery_response")
        end

        { session_id: nil, result: result.merge("protocolVersion" => MODERN_PROTOCOL_VERSION) }
      end

      def initialize_classic_session(offer = PROTOCOL_VERSION)
        if SUPPORTED_CLASSIC_PROTOCOL_VERSIONS.exclude?(offer)
          raise Error,
                I18n.t(
                  "discourse_ai.mcp_servers.errors.unsupported_protocol_version",
                  version: offer,
                )
        end

        @protocol_version = nil
        response =
          post_jsonrpc(
            "initialize",
            params: {
              protocolVersion: offer,
              capabilities: {
                tools: {
                },
              },
              clientInfo: {
                name: USER_AGENT,
                version: Discourse::VERSION::STRING,
              },
            },
            tolerate_statuses: CLASSIC_INITIALIZE_TOLERATED_STATUSES,
          )

        if offer == PROTOCOL_VERSION && rejected_classic_version?(response.payload)
          return initialize_classic_session("2025-03-26")
        end
        raise_response_error!(response.payload, status: response.status) if response.status >= 400

        result = extract_result!(response.payload)
        version = result["protocolVersion"]
        if version.blank?
          raise Error, I18n.t("discourse_ai.mcp_servers.errors.missing_protocol_version")
        end
        if !SUPPORTED_CLASSIC_PROTOCOL_VERSIONS.include?(version)
          return initialize_classic_session("2025-03-26") if offer == PROTOCOL_VERSION

          raise Error,
                I18n.t(
                  "discourse_ai.mcp_servers.errors.unsupported_protocol_version",
                  version: version,
                )
        end

        @protocol_version = version
        notify_initialized(response.session_id)

        { session_id: response.session_id, result: result }
      end

      def list_tools(session_id: nil)
        response = post_jsonrpc("tools/list", session_id: session_id)
        result = extract_result!(response.payload)
        Array(result["tools"]).reject do |tool|
          next false if protocol_version != MODERN_PROTOCOL_VERSION
          next true unless tool.is_a?(Hash)

          begin
            HeaderMapper.new(tool["inputSchema"]).annotations
            false
          rescue Error => error
            Rails.logger.warn("Invalid MCP tool #{tool["name"]}: #{error.message}")
            true
          end
        end
      end

      def call_tool(tool_name, arguments, session_id: nil, input_schema: nil)
        if protocol_version == MODERN_PROTOCOL_VERSION && input_schema.nil?
          tool = list_tools.find { |definition| definition["name"] == tool_name }
          if tool.nil?
            raise Error, I18n.t("discourse_ai.mcp_servers.errors.tool_unavailable", name: tool_name)
          end

          input_schema = tool["inputSchema"]
        end

        response =
          post_jsonrpc(
            "tools/call",
            params: {
              name: tool_name,
              arguments: arguments,
            },
            session_id: session_id,
            input_schema: input_schema,
            accept_sse: true,
            allow_result_error: true,
          )

        extract_result!(response.payload)
      end

      private

      attr_reader :server

      def notify_initialized(session_id)
        post_jsonrpc("notifications/initialized", session_id: session_id, notification: true)
      rescue Error => e
        Rails.logger.warn(
          "Discourse AI MCP initialize notification failed for server #{server.id}: #{e.message}",
        )
      end

      def post_jsonrpc(method, **options)
        options.assert_valid_keys(*POST_JSONRPC_OPTIONS)
        uri = validate_uri!
        params = options[:params]
        session_id = options[:session_id]

        if protocol_version == MODERN_PROTOCOL_VERSION
          params =
            (params || {}).merge(
              _meta: {
                PROTOCOL_META_KEY => protocol_version,
                CLIENT_INFO_META_KEY => {
                  name: USER_AGENT,
                  version: Discourse::VERSION::STRING,
                },
                CAPABILITIES_META_KEY => {
                },
              },
            )
        end

        payload = { jsonrpc: JSONRPC_VERSION, method: method }
        payload[:params] = params if params.present?
        payload[:id] = SecureRandom.uuid unless options[:notification]

        headers = default_headers(session_id: session_id)
        if protocol_version == MODERN_PROTOCOL_VERSION
          headers.merge!(
            HeaderMapper.request_headers(method, params, input_schema: options[:input_schema]),
          )
        end
        response, raw_body = perform_request(uri, payload, headers)

        handle_response(
          response,
          raw_body,
          session_id: session_id,
          allow_result_error: options[:allow_result_error],
          tolerate_statuses: options.fetch(:tolerate_statuses, []),
        )
      rescue UnauthorizedError => e
        if server.oauth? && options.fetch(:allow_oauth_retry, true) &&
             server.oauth_token_store.refresh_token.present?
          DiscourseAi::Mcp::OAuthFlow.refresh!(server)

          return post_jsonrpc(method, **options.merge(allow_oauth_retry: false))
        end

        discovery =
          DiscourseAi::Mcp::OAuthDiscovery.discover!(server, challenge_header: e.challenge_header)
        server.store_oauth_discovery!(discovery) if server.persisted?

        raise AuthorizationRequiredError,
              I18n.t(
                "discourse_ai.mcp_servers.errors.oauth_authorization_required",
                issuer: discovery.issuer,
              )
      rescue AuthorizationRequiredError
        raise
      rescue Net::ReadTimeout, Net::OpenTimeout
        raise Error, I18n.t("discourse_ai.mcp_servers.errors.timeout")
      rescue JSON::ParserError
        raise Error, I18n.t("discourse_ai.mcp_servers.errors.invalid_response")
      end

      def perform_request(uri, payload, headers)
        response = nil
        raw_body = +""
        total_bytes = 0

        FinalDestination::HTTP.start(
          uri.hostname,
          uri.port,
          use_ssl: uri.scheme == "https",
          open_timeout: server.timeout_seconds,
          read_timeout: server.timeout_seconds,
        ) do |http|
          request = FinalDestination::HTTP::Post.new(uri.request_uri)
          request["User-Agent"] = USER_AGENT
          headers.each { |key, value| request[key] = value }
          request.body = payload.to_json

          http.request(request) do |http_response|
            response = http_response
            http_response.read_body do |chunk|
              total_bytes += chunk.bytesize
              ensure_response_body_limit!(total_bytes)
              raw_body << chunk
            end
          end
        end

        [response, raw_body]
      end

      def handle_response(response, raw_body, session_id:, allow_result_error:, tolerate_statuses:)
        status = response.code.to_i

        if status == 404 && session_id.present? && protocol_version != MODERN_PROTOCOL_VERSION
          raise SessionExpiredError, I18n.t("discourse_ai.mcp_servers.errors.session_expired")
        end

        if status == 401 && server.oauth?
          raise UnauthorizedError.new(
                  I18n.t("discourse_ai.mcp_servers.errors.request_failed", status: status),
                  challenge_header: response["WWW-Authenticate"],
                )
        end

        body =
          begin
            if response["Content-Type"].to_s.include?("text/event-stream")
              parse_sse_body(raw_body)
            else
              parse_json_body(raw_body)
            end
          rescue JSON::ParserError
            unless tolerate_statuses == DISCOVERY_TOLERATED_STATUSES &&
                     tolerate_statuses.include?(status)
              raise
            end

            {}
          end

        return build_response(response, body, status) if tolerate_statuses.include?(status)

        if status < 200 || status >= 300
          if allow_result_error && tool_result_error?(body)
            return build_response(response, body, status)
          end

          raise_response_error!(body, status: status)
        end

        build_response(response, body, status)
      end

      def parse_json_body(body)
        return {} if body.blank?

        JSON.parse(body)
      end

      def parse_sse_body(raw_body)
        events = []
        buffer = raw_body.dup

        while (separator = sse_separator_end(buffer))
          event = parse_sse_event(buffer.slice!(0, separator))
          events << event if event.present?
        end

        event = parse_sse_event(buffer)
        events << event if event.present?

        events.reverse_each.find do |payload|
          payload.is_a?(Hash) && (payload.key?("result") || payload.key?("error"))
        end || {}
      end

      def default_headers(session_id:)
        ensure_oauth_access_token! if server.oauth?

        headers = {
          "Content-Type" => "application/json",
          "Accept" => "application/json, text/event-stream",
        }
        if server.auth_header.present? && (auth_header_value = server.auth_header_value).present?
          headers[server.auth_header] = auth_header_value
        end

        headers["MCP-Protocol-Version"] = protocol_version if protocol_version.present?
        headers[MCP_SESSION_ID_HEADER] = session_id if session_id.present? &&
          protocol_version != MODERN_PROTOCOL_VERSION
        headers
      end

      def classic_fallback?(response)
        return true if response.status == 400
        return method_not_found?(response.payload) if response.status == 200
        return false if [404, 405].exclude?(response.status)

        method_not_found?(response.payload) || !response.payload.is_a?(Hash) ||
          response.payload["jsonrpc"] != JSONRPC_VERSION
      end

      def method_not_found?(payload)
        payload.is_a?(Hash) && payload["jsonrpc"] == JSONRPC_VERSION &&
          payload["error"].is_a?(Hash) && payload["error"]["code"] == -32_601
      end

      def rejected_classic_version?(payload)
        return false unless payload.is_a?(Hash) && payload["jsonrpc"] == JSONRPC_VERSION

        error = payload["error"]
        return false unless error.is_a?(Hash) && error["code"].is_a?(Integer)
        return false if MODERN_ERROR_CODES.include?(error["code"])

        message = error["message"]
        message.is_a?(String) &&
          message.match?(
            /\b(?:unsupported|unrecognized|not supported|invalid)\s+(?:MCP\s+)?protocol\s+version\b|\bprotocol\s+version\b.*\b(?:unsupported|unrecognized|not supported|invalid)\b/i,
          )
      end

      def raise_response_error!(
        payload,
        status: nil,
        fallback: "discourse_ai.mcp_servers.errors.request_failed"
      )
        error = payload["error"] if payload.is_a?(Hash)
        message = error["message"] if error.is_a?(Hash)
        raise Error, message.presence || I18n.t(fallback, status: status)
      end

      def extract_result!(payload)
        unless payload.is_a?(Hash)
          raise Error, I18n.t("discourse_ai.mcp_servers.errors.invalid_response")
        end

        if payload["error"].present?
          raise_response_error!(
            payload,
            fallback: "discourse_ai.mcp_servers.errors.invalid_response",
          )
        end

        result = payload["result"] || {}
        unless result.is_a?(Hash)
          raise Error, I18n.t("discourse_ai.mcp_servers.errors.invalid_response")
        end

        result
      end

      def build_response(response, body, status)
        Response.new(
          payload: body,
          session_id: response[MCP_SESSION_ID_HEADER],
          status: status,
          headers: response.to_hash,
        )
      end

      def tool_result_error?(body)
        body.is_a?(Hash) && body.dig("result", "isError") == true
      end

      def validate_uri!
        uri = AiMcpServer.parse_public_uri(server.url)
        raise Error, I18n.t("discourse_ai.mcp_servers.invalid_url_not_https") if uri.nil?

        AiMcpServer.validate_hostname_public!(uri.hostname)
        uri
      rescue FinalDestination::SSRFError, SocketError, URI::InvalidURIError
        raise Error, I18n.t("discourse_ai.mcp_servers.invalid_url_not_reachable")
      end

      def ensure_response_body_limit!(size)
        return if size <= MAX_RESPONSE_BODY_LENGTH

        raise Error, I18n.t("discourse_ai.mcp_servers.errors.invalid_response")
      end

      def ensure_oauth_access_token!
        return if !server.oauth? || !server.oauth_needs_refresh?

        DiscourseAi::Mcp::OAuthFlow.refresh!(server)
      end

      def sse_separator_end(buffer)
        buffer.match(/\r?\n\r?\n/)&.end(0)
      end

      def parse_sse_event(raw_event)
        data =
          raw_event
            .lines(chomp: true)
            .grep(/\Adata:/)
            .map { |line| line.sub(/\Adata:\s?/, "") }
            .join("\n")

        return if data.blank? || data == "[DONE]"

        JSON.parse(data)
      end
    end
  end
end