ruby-mcp-client 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f797750d8f5a6f1b742411418f77c8352cc89e8879e77ba51bcb7257f9de6db
-  data.tar.gz: 104e26ec1506bebae21b5b4e70508db0159d3ef8b9b69148720fed202633d7e8
+  metadata.gz: 94f8597a5cddfa1f86b6e09401b652d2c7aa3bd4eefc8771712b7c03d99772a8
+  data.tar.gz: b303e3056719fea1a62cf4eeff76156e6e3ed68d134d48aa3ce969e8095d85be
 SHA512:
-  metadata.gz: 20aa894d62ed87e70d50f92b7ce4b60839855f7ce9697f476c7822dcf99167f62030bfbd90f1d5c50d535cc78a075e35f25086e0b3f09d57c3d0bd9f4c8ff35e
-  data.tar.gz: dd252c97f599834a3f1e4f9a3acf0c7e98489c247c4601a3d038f8af646c431ef0245ed00b33cb61ea387c296ee5c63c99a8487bf8b9b3ed68be5bfd4e5a5f55
+  metadata.gz: da1d04e7aee8207ff32a2db24df14c2b832b8f5fd6acf36c6b8f22b86cf802d99de5514a608a6336f1973949a34a8829c8f71a5b2dadc68ebff50ed7d4d23bc7
+  data.tar.gz: e75630074326e81fddbc006f3bcd8b848c474792ac73c2e9f883722b49b0aeb2da31bb824263234599b279974c7c2445ce6d4d06766a0e447753e8060b248d8f

data/README.md

@@ -40,6 +40,14 @@ with popular AI services with built-in conversions:
 - `to_anthropic_tools()` - Formats tools for Anthropic Claude API
 - `to_google_tools()` - Formats tools for Google Vertex AI API (automatically removes "$schema" keys not accepted by Vertex AI)
 
+## MCP 2025-03-26 Protocol Features
+
+This Ruby MCP Client implements key features from the latest MCP specification (Protocol Revision: 2025-03-26):
+
+### Implemented Features
+- **OAuth 2.1 Authorization Framework** - Complete authentication with PKCE, dynamic client registration, server discovery, and runtime configuration
+- **Streamable HTTP Transport** - Enhanced transport with Server-Sent Event formatted responses and session management
+
 ## Usage
 
 ### Basic Client Usage
@@ -549,6 +557,69 @@ client.cleanup
 
 This enables compatibility with MCP servers that maintain state between requests and require session identification.
 
+## OAuth 2.1 Authentication
+
+The Ruby MCP Client includes comprehensive OAuth 2.1 support for secure authentication with MCP servers:
+
+```ruby
+require 'mcp_client'
+
+# Create an OAuth-enabled HTTP server
+server = MCPClient::OAuthClient.create_http_server(
+  server_url: 'https://api.example.com/mcp',
+  redirect_uri: 'http://localhost:8080/callback',
+  scope: 'mcp:read mcp:write'
+)
+
+# Check if authorization is needed
+unless MCPClient::OAuthClient.valid_token?(server)
+  # Start OAuth flow
+  auth_url = MCPClient::OAuthClient.start_oauth_flow(server)
+  puts "Please visit: #{auth_url}"
+
+  # After user authorization, complete the flow
+  # token = MCPClient::OAuthClient.complete_oauth_flow(server, code, state)
+end
+
+# Use the server normally
+server.connect
+tools = server.list_tools
+```
+
+### Manual OAuth Provider
+
+For more control over the OAuth flow:
+
+```ruby
+# Create OAuth provider directly
+oauth_provider = MCPClient::Auth::OAuthProvider.new(
+  server_url: 'https://api.example.com/mcp',
+  redirect_uri: 'http://localhost:8080/callback',
+  scope: 'mcp:read mcp:write'
+)
+
+# Update configuration at runtime
+oauth_provider.scope = 'mcp:read mcp:write admin'
+oauth_provider.redirect_uri = 'http://localhost:9000/callback'
+
+# Start authorization flow
+auth_url = oauth_provider.start_authorization_flow
+
+# Complete flow after user authorization
+token = oauth_provider.complete_authorization_flow(code, state)
+```
+
+### OAuth Features
+
+- **OAuth 2.1 compliance** with PKCE for security
+- **Automatic server discovery** via `.well-known` endpoints
+- **Dynamic client registration** when supported by servers
+- **Token refresh** and automatic token management
+- **Pluggable storage** for tokens and client credentials
+- **Runtime configuration** via getter/setter methods
+
+For complete OAuth documentation, see [OAUTH.md](OAUTH.md).
+
 ## Key Features
 
 ### Client Features

data/lib/mcp_client/auth/oauth_provider.rb

@@ -0,0 +1,514 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'uri'
+require_relative '../auth'
+
+module MCPClient
+  module Auth
+    # OAuth 2.1 provider for MCP client authentication
+    # Handles the complete OAuth flow including server discovery, client registration,
+    # authorization, token exchange, and refresh
+    class OAuthProvider
+      # @!attribute [rw] redirect_uri
+      #   @return [String] OAuth redirect URI
+      # @!attribute [rw] scope
+      #   @return [String, nil] OAuth scope
+      # @!attribute [rw] logger
+      #   @return [Logger] Logger instance
+      # @!attribute [rw] storage
+      #   @return [Object] Storage backend for tokens and client info
+      # @!attribute [r] server_url
+      #   @return [String] The MCP server URL (normalized)
+      attr_accessor :redirect_uri, :scope, :logger, :storage
+      attr_reader :server_url
+
+      # Initialize OAuth provider
+      # @param server_url [String] The MCP server URL (used as OAuth resource parameter)
+      # @param redirect_uri [String] OAuth redirect URI (default: http://localhost:8080/callback)
+      # @param scope [String, nil] OAuth scope
+      # @param logger [Logger, nil] Optional logger
+      # @param storage [Object, nil] Storage backend for tokens and client info
+      def initialize(server_url:, redirect_uri: 'http://localhost:8080/callback', scope: nil, logger: nil, storage: nil)
+        self.server_url = server_url
+        self.redirect_uri = redirect_uri
+        self.scope = scope
+        self.logger = logger || Logger.new($stdout, level: Logger::WARN)
+        self.storage = storage || MemoryStorage.new
+        @http_client = create_http_client
+      end
+
+      # @param url [String] Server URL to normalize
+      def server_url=(url)
+        @server_url = normalize_server_url(url)
+      end
+
+      # Get current access token (refresh if needed)
+      # @return [Token, nil] Current valid access token or nil
+      def access_token
+        token = storage.get_token(server_url)
+        logger.debug("OAuth access_token: retrieved token=#{token ? 'present' : 'nil'} for #{server_url}")
+        return nil unless token
+
+        # Return token if still valid
+        return token unless token.expired? || token.expires_soon?
+
+        # Try to refresh if we have a refresh token
+        refresh_token(token) if token.refresh_token
+      end
+
+      # Start OAuth authorization flow
+      # @return [String] Authorization URL to redirect user to
+      # @raise [MCPClient::Errors::ConnectionError] if server discovery fails
+      def start_authorization_flow
+        # Discover authorization server
+        server_metadata = discover_authorization_server
+
+        # Register client if needed
+        client_info = get_or_register_client(server_metadata)
+
+        # Generate PKCE parameters
+        pkce = PKCE.new
+        storage.set_pkce(server_url, pkce)
+
+        # Generate state parameter
+        state = SecureRandom.urlsafe_base64(32)
+        storage.set_state(server_url, state)
+
+        # Build authorization URL
+        build_authorization_url(server_metadata, client_info, pkce, state)
+      end
+
+      # Complete OAuth authorization flow with authorization code
+      # @param code [String] Authorization code from callback
+      # @param state [String] State parameter from callback
+      # @return [Token] Access token
+      # @raise [MCPClient::Errors::ConnectionError] if token exchange fails
+      # @raise [ArgumentError] if state parameter doesn't match
+      def complete_authorization_flow(code, state)
+        # Verify state parameter
+        stored_state = storage.get_state(server_url)
+        raise ArgumentError, 'Invalid state parameter' unless stored_state == state
+
+        # Get stored PKCE and client info
+        pkce = storage.get_pkce(server_url)
+        client_info = storage.get_client_info(server_url)
+        server_metadata = discover_authorization_server
+
+        raise MCPClient::Errors::ConnectionError, 'Missing PKCE or client info' unless pkce && client_info
+
+        # Exchange authorization code for tokens
+        token = exchange_authorization_code(server_metadata, client_info, code, pkce)
+
+        # Store token
+        storage.set_token(server_url, token)
+
+        # Clean up temporary data
+        storage.delete_pkce(server_url)
+        storage.delete_state(server_url)
+
+        token
+      end
+
+      # Apply OAuth authorization to HTTP request
+      # @param request [Faraday::Request] HTTP request to authorize
+      # @return [void]
+      def apply_authorization(request)
+        token = access_token
+        logger.debug("OAuth apply_authorization: token=#{token ? 'present' : 'nil'}")
+        return unless token
+
+        logger.debug("OAuth applying authorization header: #{token.to_header[0..20]}...")
+        request.headers['Authorization'] = token.to_header
+      end
+
+      # Handle 401 Unauthorized response (for server discovery)
+      # @param response [Faraday::Response] HTTP response
+      # @return [ResourceMetadata, nil] Resource metadata if found
+      def handle_unauthorized_response(response)
+        www_authenticate = response.headers['WWW-Authenticate'] || response.headers['www-authenticate']
+        return nil unless www_authenticate
+
+        # Parse WWW-Authenticate header to extract resource metadata URL
+        # Format: Bearer resource="https://example.com/.well-known/oauth-protected-resource"
+        if (match = www_authenticate.match(/resource="([^"]+)"/))
+          resource_metadata_url = match[1]
+          fetch_resource_metadata(resource_metadata_url)
+        end
+      end
+
+      private
+
+      # Normalize server URL to canonical form
+      # @param url [String] Server URL
+      # @return [String] Normalized URL
+      def normalize_server_url(url)
+        uri = URI.parse(url)
+
+        # Use lowercase scheme and host
+        uri.scheme = uri.scheme.downcase
+        uri.host = uri.host.downcase
+
+        # Remove default ports
+        uri.port = nil if (uri.scheme == 'http' && uri.port == 80) || (uri.scheme == 'https' && uri.port == 443)
+
+        # Remove trailing slash for empty path or just "/"
+        if uri.path.nil? || uri.path.empty? || uri.path == '/'
+          uri.path = ''
+        elsif uri.path.end_with?('/')
+          uri.path = uri.path.chomp('/')
+        end
+
+        # Remove fragment
+        uri.fragment = nil
+
+        uri.to_s
+      end
+
+      # Create HTTP client for OAuth requests
+      # @return [Faraday::Connection] HTTP client
+      def create_http_client
+        Faraday.new do |f|
+          f.request :retry, max: 3, interval: 1, backoff_factor: 2
+          f.options.timeout = 30
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # Build OAuth discovery URL from server URL
+      # Uses only the origin (scheme + host + port) for discovery
+      # @param server_url [String] Full MCP server URL
+      # @return [String] Discovery URL
+      def build_discovery_url(server_url)
+        uri = URI.parse(server_url)
+
+        # Build origin URL (scheme + host + port)
+        origin = "#{uri.scheme}://#{uri.host}"
+        origin += ":#{uri.port}" if uri.port && !default_port?(uri)
+
+        "#{origin}/.well-known/oauth-protected-resource"
+      end
+
+      # Check if URI uses default port for its scheme
+      # @param uri [URI] Parsed URI
+      # @return [Boolean] true if using default port
+      def default_port?(uri)
+        (uri.scheme == 'http' && uri.port == 80) ||
+          (uri.scheme == 'https' && uri.port == 443)
+      end
+
+      # Discover authorization server metadata
+      # @return [ServerMetadata] Authorization server metadata
+      # @raise [MCPClient::Errors::ConnectionError] if discovery fails
+      def discover_authorization_server
+        # Try to get from storage first
+        if (cached = storage.get_server_metadata(server_url))
+          return cached
+        end
+
+        # Build discovery URL using the origin (scheme + host + port) only
+        discovery_url = build_discovery_url(server_url)
+
+        # Fetch resource metadata to find authorization server
+        resource_metadata = fetch_resource_metadata(discovery_url)
+
+        # Get first authorization server
+        auth_server_url = resource_metadata.authorization_servers.first
+        raise MCPClient::Errors::ConnectionError, 'No authorization servers found' unless auth_server_url
+
+        # Fetch authorization server metadata
+        server_metadata = fetch_server_metadata("#{auth_server_url}/.well-known/oauth-authorization-server")
+
+        # Cache the metadata
+        storage.set_server_metadata(server_url, server_metadata)
+
+        server_metadata
+      end
+
+      # Fetch resource metadata from URL
+      # @param url [String] Resource metadata URL
+      # @return [ResourceMetadata] Resource metadata
+      # @raise [MCPClient::Errors::ConnectionError] if fetch fails
+      def fetch_resource_metadata(url)
+        logger.debug("Fetching resource metadata from: #{url}")
+
+        response = @http_client.get(url) do |req|
+          req.headers['Accept'] = 'application/json'
+        end
+
+        unless response.success?
+          raise MCPClient::Errors::ConnectionError, "Failed to fetch resource metadata: HTTP #{response.status}"
+        end
+
+        data = JSON.parse(response.body)
+        ResourceMetadata.from_h(data)
+      rescue JSON::ParserError => e
+        raise MCPClient::Errors::ConnectionError, "Invalid resource metadata JSON: #{e.message}"
+      rescue Faraday::Error => e
+        raise MCPClient::Errors::ConnectionError, "Network error fetching resource metadata: #{e.message}"
+      end
+
+      # Fetch authorization server metadata from URL
+      # @param url [String] Server metadata URL
+      # @return [ServerMetadata] Server metadata
+      # @raise [MCPClient::Errors::ConnectionError] if fetch fails
+      def fetch_server_metadata(url)
+        logger.debug("Fetching server metadata from: #{url}")
+
+        response = @http_client.get(url) do |req|
+          req.headers['Accept'] = 'application/json'
+        end
+
+        unless response.success?
+          raise MCPClient::Errors::ConnectionError, "Failed to fetch server metadata: HTTP #{response.status}"
+        end
+
+        data = JSON.parse(response.body)
+        ServerMetadata.from_h(data)
+      rescue JSON::ParserError => e
+        raise MCPClient::Errors::ConnectionError, "Invalid server metadata JSON: #{e.message}"
+      rescue Faraday::Error => e
+        raise MCPClient::Errors::ConnectionError, "Network error fetching server metadata: #{e.message}"
+      end
+
+      # Get or register OAuth client
+      # @param server_metadata [ServerMetadata] Authorization server metadata
+      # @return [ClientInfo] Client information
+      # @raise [MCPClient::Errors::ConnectionError] if registration fails
+      def get_or_register_client(server_metadata)
+        # Try to get existing client info from storage
+        if (client_info = storage.get_client_info(server_url)) && !client_info.client_secret_expired?
+          return client_info
+        end
+
+        # Register new client if server supports it
+        if server_metadata.supports_registration?
+          register_client(server_metadata)
+        else
+          raise MCPClient::Errors::ConnectionError,
+                'Dynamic client registration not supported and no client credentials found'
+        end
+      end
+
+      # Register OAuth client dynamically
+      # @param server_metadata [ServerMetadata] Authorization server metadata
+      # @return [ClientInfo] Registered client information
+      # @raise [MCPClient::Errors::ConnectionError] if registration fails
+      def register_client(server_metadata)
+        logger.debug("Registering OAuth client at: #{server_metadata.registration_endpoint}")
+
+        metadata = ClientMetadata.new(
+          redirect_uris: [redirect_uri],
+          token_endpoint_auth_method: 'none', # Public client
+          grant_types: %w[authorization_code refresh_token],
+          response_types: ['code'],
+          scope: scope
+        )
+
+        response = @http_client.post(server_metadata.registration_endpoint) do |req|
+          req.headers['Content-Type'] = 'application/json'
+          req.headers['Accept'] = 'application/json'
+          req.body = metadata.to_h.to_json
+        end
+
+        unless response.success?
+          raise MCPClient::Errors::ConnectionError, "Client registration failed: HTTP #{response.status}"
+        end
+
+        data = JSON.parse(response.body)
+        client_info = ClientInfo.new(
+          client_id: data['client_id'],
+          client_secret: data['client_secret'],
+          client_id_issued_at: data['client_id_issued_at'],
+          client_secret_expires_at: data['client_secret_expires_at'],
+          metadata: metadata
+        )
+
+        # Store client info
+        storage.set_client_info(server_url, client_info)
+
+        client_info
+      rescue JSON::ParserError => e
+        raise MCPClient::Errors::ConnectionError, "Invalid client registration response: #{e.message}"
+      rescue Faraday::Error => e
+        raise MCPClient::Errors::ConnectionError, "Network error during client registration: #{e.message}"
+      end
+
+      # Build authorization URL
+      # @param server_metadata [ServerMetadata] Server metadata
+      # @param client_info [ClientInfo] Client information
+      # @param pkce [PKCE] PKCE parameters
+      # @param state [String] State parameter
+      # @return [String] Authorization URL
+      def build_authorization_url(server_metadata, client_info, pkce, state)
+        params = {
+          response_type: 'code',
+          client_id: client_info.client_id,
+          redirect_uri: redirect_uri,
+          scope: scope,
+          state: state,
+          code_challenge: pkce.code_challenge,
+          code_challenge_method: pkce.code_challenge_method,
+          resource: server_url
+        }.compact
+
+        uri = URI.parse(server_metadata.authorization_endpoint)
+        uri.query = URI.encode_www_form(params)
+        uri.to_s
+      end
+
+      # Exchange authorization code for access token
+      # @param server_metadata [ServerMetadata] Server metadata
+      # @param client_info [ClientInfo] Client information
+      # @param code [String] Authorization code
+      # @param pkce [PKCE] PKCE parameters
+      # @return [Token] Access token
+      # @raise [MCPClient::Errors::ConnectionError] if token exchange fails
+      def exchange_authorization_code(server_metadata, client_info, code, pkce)
+        logger.debug("Exchanging authorization code for token at: #{server_metadata.token_endpoint}")
+
+        params = {
+          grant_type: 'authorization_code',
+          code: code,
+          redirect_uri: redirect_uri,
+          client_id: client_info.client_id,
+          code_verifier: pkce.code_verifier,
+          resource: server_url
+        }
+
+        response = @http_client.post(server_metadata.token_endpoint) do |req|
+          req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+          req.headers['Accept'] = 'application/json'
+          req.body = URI.encode_www_form(params)
+        end
+
+        unless response.success?
+          raise MCPClient::Errors::ConnectionError, "Token exchange failed: HTTP #{response.status} - #{response.body}"
+        end
+
+        data = JSON.parse(response.body)
+        Token.new(
+          access_token: data['access_token'],
+          token_type: data['token_type'] || 'Bearer',
+          expires_in: data['expires_in'],
+          scope: data['scope'],
+          refresh_token: data['refresh_token']
+        )
+      rescue JSON::ParserError => e
+        raise MCPClient::Errors::ConnectionError, "Invalid token response: #{e.message}"
+      rescue Faraday::Error => e
+        raise MCPClient::Errors::ConnectionError, "Network error during token exchange: #{e.message}"
+      end
+
+      # Refresh access token
+      # @param token [Token] Current token with refresh token
+      # @return [Token, nil] New access token or nil if refresh failed
+      def refresh_token(token)
+        return nil unless token.refresh_token
+
+        logger.debug('Refreshing access token')
+
+        server_metadata = discover_authorization_server
+        client_info = storage.get_client_info(server_url)
+
+        return nil unless server_metadata && client_info
+
+        params = {
+          grant_type: 'refresh_token',
+          refresh_token: token.refresh_token,
+          client_id: client_info.client_id,
+          resource: server_url
+        }
+
+        response = @http_client.post(server_metadata.token_endpoint) do |req|
+          req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+          req.headers['Accept'] = 'application/json'
+          req.body = URI.encode_www_form(params)
+        end
+
+        unless response.success?
+          logger.warn("Token refresh failed: HTTP #{response.status}")
+          return nil
+        end
+
+        data = JSON.parse(response.body)
+        new_token = Token.new(
+          access_token: data['access_token'],
+          token_type: data['token_type'] || 'Bearer',
+          expires_in: data['expires_in'],
+          scope: data['scope'],
+          refresh_token: data['refresh_token'] || token.refresh_token
+        )
+
+        storage.set_token(server_url, new_token)
+        new_token
+      rescue JSON::ParserError => e
+        logger.warn("Invalid token refresh response: #{e.message}")
+        nil
+      rescue Faraday::Error => e
+        logger.warn("Network error during token refresh: #{e.message}")
+        nil
+      end
+
+      # Simple in-memory storage for OAuth data
+      class MemoryStorage
+        def initialize
+          @tokens = {}
+          @client_infos = {}
+          @server_metadata = {}
+          @pkce_data = {}
+          @state_data = {}
+        end
+
+        def get_token(server_url)
+          @tokens[server_url]
+        end
+
+        def set_token(server_url, token)
+          @tokens[server_url] = token
+        end
+
+        def get_client_info(server_url)
+          @client_infos[server_url]
+        end
+
+        def set_client_info(server_url, client_info)
+          @client_infos[server_url] = client_info
+        end
+
+        def get_server_metadata(server_url)
+          @server_metadata[server_url]
+        end
+
+        def set_server_metadata(server_url, metadata)
+          @server_metadata[server_url] = metadata
+        end
+
+        def get_pkce(server_url)
+          @pkce_data[server_url]
+        end
+
+        def set_pkce(server_url, pkce)
+          @pkce_data[server_url] = pkce
+        end
+
+        def delete_pkce(server_url)
+          @pkce_data.delete(server_url)
+        end
+
+        def get_state(server_url)
+          @state_data[server_url]
+        end
+
+        def set_state(server_url, state)
+          @state_data[server_url] = state
+        end
+
+        def delete_state(server_url)
+          @state_data.delete(server_url)
+        end
+      end
+    end
+  end
+end