ruby-mcp-client 0.9.1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79251746d1952caddd00b917b914d5ddb47c742c960914a39bf6a7f7a7073d35
-  data.tar.gz: 98522398f4bcb491c59d794f6e869d9570c0ddfc3fba40eb584e21079ea913e2
+  metadata.gz: 8e56ef84106ab19bf3028b31dd7ce362cfb58f244743057271f14a83409153f0
+  data.tar.gz: 96f0e42875d80032c24056c1dbd9c6417b3db994538838736fa52f303e0d4f85
 SHA512:
-  metadata.gz: bb37b670e9e54baf9dfc280d0be09047e43236439ae94f0fd8acb1277a0acc1f0eba33661a3d1fa49c25d11493b6a70c283be66fab91420a1ba2b2fbe7360499
-  data.tar.gz: 840c2a9685114762396106e5e7cc327ac2e0c3639575cf4eb3f4a41b50d6bc3c19a705d5405bcd1f7504fa1961c3f5ce5796105e77d780b53515255a3151539c
+  metadata.gz: 48b7cd77ab406967bc4cd5fe79c5c1511a8eb2c9e4c9ebc27b31b8386e175a435d1a620ffcfa7871044188061b3f0718875d009f2a4ef7d030786ad11bcbde35
+  data.tar.gz: 11f845c21895b67d0a308267972936fcf07df042e33de6417b69ee486f1739a8768f25b698bbbad92fdbef3acf0e6ec42eaffa525896b9e77e50e86960c7daf8

data/README.md

@@ -28,16 +28,18 @@ Built-in API conversions: `to_openai_tools()`, `to_anthropic_tools()`, `to_googl
 
 ## MCP Protocol Support
 
-Implements **MCP 2025-06-18** specification:
+Implements **MCP 2025-11-25** specification:
 
-- **Tools**: list, call, streaming, annotations, structured outputs
+- **Tools**: list, call, streaming, annotations (hint-style), structured outputs, title
 - **Prompts**: list, get with parameters
-- **Resources**: list, read, templates, subscriptions, pagination
+- **Resources**: list, read, templates, subscriptions, pagination, ResourceLink content
 - **Elicitation**: Server-initiated user interactions (stdio, SSE, Streamable HTTP)
 - **Roots**: Filesystem scope boundaries with change notifications
-- **Sampling**: Server-requested LLM completions
-- **Completion**: Autocomplete for prompts/resources
+- **Sampling**: Server-requested LLM completions with modelPreferences
+- **Completion**: Autocomplete for prompts/resources with context
 - **Logging**: Server log messages with level filtering
+- **Tasks**: Structured task management with progress tracking
+- **Audio**: Audio content type support
 - **OAuth 2.1**: PKCE, server discovery, dynamic registration
 
 ## Quick Connect API (Recommended)
@@ -114,12 +116,20 @@ contents.each do |content|
 end
 ```
 
-## MCP 2025-06-18 Features
+## MCP 2025-11-25 Features
 
 ### Tool Annotations
 
 ```ruby
 tool = client.find_tool('delete_user')
+
+# Hint-style annotations (MCP 2025-11-25)
+tool.read_only_hint?      # Defaults to true; tool does not modify environment
+tool.destructive_hint?    # Defaults to false; tool may perform destructive updates
+tool.idempotent_hint?     # Defaults to false; repeated calls have no additional effect
+tool.open_world_hint?     # Defaults to true; tool may interact with external entities
+
+# Legacy annotations
 tool.read_only?              # Safe to execute?
 tool.destructive?            # Warning: destructive operation
 tool.requires_confirmation?  # Needs user confirmation
@@ -293,10 +303,36 @@ client = Anthropic::Client.new(access_token: ENV['ANTHROPIC_API_KEY'])
 # Use tools with Claude API
 ```
 
+### RubyLLM
+
+```ruby
+require 'mcp_client'
+require 'ruby_llm'
+
+RubyLLM.configure { |c| c.openai_api_key = ENV['OPENAI_API_KEY'] }
+mcp = MCPClient.connect('http://localhost:8931/mcp')  # Playwright MCP
+
+# Wrap each MCP tool as a RubyLLM tool
+tools = mcp.list_tools.map do |t|
+  tool_name = t.name
+  Class.new(RubyLLM::Tool) do
+    description t.description
+    params t.schema
+    define_method(:name) { tool_name }
+    define_method(:execute) { |**args| mcp.call_tool(tool_name, args) }
+  end.new
+end
+
+chat = RubyLLM.chat(model: 'gpt-4o-mini')
+tools.each { |tool| chat.with_tool(tool) }
+response = chat.ask('Navigate to google.com and tell me the page title')
+```
+
 See `examples/` for complete implementations:
 - `ruby_openai_mcp.rb`, `openai_ruby_mcp.rb` - OpenAI integration
 - `ruby_anthropic_mcp.rb` - Anthropic integration
 - `gemini_ai_mcp.rb` - Google Vertex AI integration
+- `ruby_llm_mcp.rb` - RubyLLM integration (OpenAI provider)
 
 ## OAuth 2.1 Authentication
 

data/lib/mcp_client/audio_content.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of MCP audio content (MCP 2025-11-25)
+  # Used for base64-encoded audio data in messages and tool results
+  class AudioContent
+    # @!attribute [r] data
+    #   @return [String] base64-encoded audio data
+    # @!attribute [r] mime_type
+    #   @return [String] MIME type of the audio (e.g., 'audio/wav', 'audio/mpeg', 'audio/ogg')
+    # @!attribute [r] annotations
+    #   @return [Hash, nil] optional annotations that provide hints to clients
+    attr_reader :data, :mime_type, :annotations
+
+    # Initialize audio content
+    # @param data [String] base64-encoded audio data
+    # @param mime_type [String] MIME type of the audio
+    # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    def initialize(data:, mime_type:, annotations: nil)
+      raise ArgumentError, 'AudioContent requires data' if data.nil? || data.empty?
+      raise ArgumentError, 'AudioContent requires mime_type' if mime_type.nil? || mime_type.empty?
+
+      @data = data
+      @mime_type = mime_type
+      @annotations = annotations
+    end
+
+    # Create an AudioContent instance from JSON data
+    # @param data [Hash] JSON data from MCP server
+    # @return [MCPClient::AudioContent] audio content instance
+    def self.from_json(json_data)
+      new(
+        data: json_data['data'],
+        mime_type: json_data['mimeType'],
+        annotations: json_data['annotations']
+      )
+    end
+
+    # Get the decoded audio content
+    # @return [String] decoded binary audio data
+    def content
+      require 'base64'
+      Base64.decode64(@data)
+    end
+  end
+end

data/lib/mcp_client/auth/oauth_provider.rb

@@ -14,7 +14,7 @@ module MCPClient
       # @!attribute [rw] redirect_uri
       #   @return [String] OAuth redirect URI
       # @!attribute [rw] scope
-      #   @return [String, nil] OAuth scope
+      #   @return [String, Symbol, nil] OAuth scope (use :all for all server-supported scopes)
       # @!attribute [rw] logger
       #   @return [Logger] Logger instance
       # @!attribute [rw] storage
@@ -27,15 +27,19 @@ module MCPClient
       # 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 scope [String, Symbol, nil] OAuth scope (use :all for all server-supported scopes)
       # @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)
+      # @param client_metadata [Hash] Extra OIDC client metadata fields for DCR registration.
+      #   Supported keys: :client_name, :client_uri, :logo_uri, :tos_uri, :policy_uri, :contacts
+      def initialize(server_url:, redirect_uri: 'http://localhost:8080/callback', scope: nil, logger: nil, storage: nil,
+                     client_metadata: {})
         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
+        @extra_client_metadata = client_metadata
         @http_client = create_http_client
       end
 
@@ -58,6 +62,14 @@ module MCPClient
         refresh_token(token) if token.refresh_token
       end
 
+      # Return the scopes supported by the authorization server
+      # Discovers server metadata and returns the scopes_supported list.
+      # @return [Array<String>] supported scopes, or empty array if not advertised
+      # @raise [MCPClient::Errors::ConnectionError] if server discovery fails
+      def supported_scopes
+        @supported_scopes ||= discover_authorization_server.scopes_supported || []
+      end
+
       # Start OAuth authorization flow
       # @return [String] Authorization URL to redirect user to
       # @raise [MCPClient::Errors::ConnectionError] if server discovery fails
@@ -328,12 +340,15 @@ module MCPClient
       def register_client(server_metadata)
         logger.debug("Registering OAuth client at: #{server_metadata.registration_endpoint}")
 
+        resolved_scope = scope == :all ? supported_scopes.join(' ') : scope
+
         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
+          scope: resolved_scope,
+          **@extra_client_metadata
         )
 
         response = @http_client.post(server_metadata.registration_endpoint) do |req|
@@ -355,7 +370,13 @@ module MCPClient
           token_endpoint_auth_method: data['token_endpoint_auth_method'] || 'none',
           grant_types: data['grant_types'] || %w[authorization_code refresh_token],
           response_types: data['response_types'] || ['code'],
-          scope: data['scope']
+          scope: data['scope'],
+          client_name: data['client_name'],
+          client_uri: data['client_uri'],
+          logo_uri: data['logo_uri'],
+          tos_uri: data['tos_uri'],
+          policy_uri: data['policy_uri'],
+          contacts: data['contacts']
         )
 
         # Warn if server changed redirect_uri
@@ -396,11 +417,13 @@ module MCPClient
         # Use the redirect_uri that was actually registered
         registered_redirect_uri = client_info.metadata.redirect_uris.first
 
+        resolved_scope = scope == :all ? supported_scopes.join(' ') : scope
+
         params = {
           response_type: 'code',
           client_id: client_info.client_id,
           redirect_uri: registered_redirect_uri,
-          scope: scope,
+          scope: resolved_scope,
           state: state,
           code_challenge: pkce.code_challenge,
           code_challenge_method: pkce.code_challenge_method,

data/lib/mcp_client/auth.rb

@@ -86,21 +86,38 @@ module MCPClient
 
     # OAuth client metadata for registration and authorization
     class ClientMetadata
-      attr_reader :redirect_uris, :token_endpoint_auth_method, :grant_types, :response_types, :scope
+      attr_reader :redirect_uris, :token_endpoint_auth_method, :grant_types, :response_types, :scope,
+                  :client_name, :client_uri, :logo_uri, :tos_uri, :policy_uri, :contacts
 
       # @param redirect_uris [Array<String>] List of valid redirect URIs
       # @param token_endpoint_auth_method [String] Authentication method for token endpoint
       # @param grant_types [Array<String>] Supported grant types
       # @param response_types [Array<String>] Supported response types
       # @param scope [String, nil] Requested scope
+      # @param client_name [String, nil] Human-readable client name
+      # @param client_uri [String, nil] URL of the client home page
+      # @param logo_uri [String, nil] URL of the client logo
+      # @param tos_uri [String, nil] URL of the client terms of service
+      # @param policy_uri [String, nil] URL of the client privacy policy
+      # @param contacts [Array<String>, nil] List of contact emails for the client
+      # rubocop:disable Metrics/ParameterLists
       def initialize(redirect_uris:, token_endpoint_auth_method: 'none',
                      grant_types: %w[authorization_code refresh_token],
-                     response_types: ['code'], scope: nil)
+                     response_types: ['code'], scope: nil,
+                     client_name: nil, client_uri: nil, logo_uri: nil,
+                     tos_uri: nil, policy_uri: nil, contacts: nil)
+        # rubocop:enable Metrics/ParameterLists
         @redirect_uris = redirect_uris
         @token_endpoint_auth_method = token_endpoint_auth_method
         @grant_types = grant_types
         @response_types = response_types
         @scope = scope
+        @client_name = client_name
+        @client_uri = client_uri
+        @logo_uri = logo_uri
+        @tos_uri = tos_uri
+        @policy_uri = policy_uri
+        @contacts = contacts
       end
 
       # Convert to hash for HTTP requests
@@ -111,7 +128,13 @@ module MCPClient
           token_endpoint_auth_method: @token_endpoint_auth_method,
           grant_types: @grant_types,
           response_types: @response_types,
-          scope: @scope
+          scope: @scope,
+          client_name: @client_name,
+          client_uri: @client_uri,
+          logo_uri: @logo_uri,
+          tos_uri: @tos_uri,
+          policy_uri: @policy_uri,
+          contacts: @contacts
         }.compact
       end
     end
@@ -180,7 +203,13 @@ module MCPClient
           grant_types: metadata_data[:grant_types] || metadata_data['grant_types'] ||
                        %w[authorization_code refresh_token],
           response_types: metadata_data[:response_types] || metadata_data['response_types'] || ['code'],
-          scope: metadata_data[:scope] || metadata_data['scope']
+          scope: metadata_data[:scope] || metadata_data['scope'],
+          client_name: metadata_data[:client_name] || metadata_data['client_name'],
+          client_uri: metadata_data[:client_uri] || metadata_data['client_uri'],
+          logo_uri: metadata_data[:logo_uri] || metadata_data['logo_uri'],
+          tos_uri: metadata_data[:tos_uri] || metadata_data['tos_uri'],
+          policy_uri: metadata_data[:policy_uri] || metadata_data['policy_uri'],
+          contacts: metadata_data[:contacts] || metadata_data['contacts']
         )
       end
 
@@ -288,10 +317,41 @@ module MCPClient
       attr_reader :code_verifier, :code_challenge, :code_challenge_method
 
       # Generate PKCE parameters
-      def initialize
-        @code_verifier = generate_code_verifier
-        @code_challenge = generate_code_challenge(@code_verifier)
-        @code_challenge_method = 'S256'
+      # @param code_verifier [String, nil] Existing code verifier (for deserialization)
+      # @param code_challenge [String, nil] Existing code challenge (for deserialization)
+      # @param code_challenge_method [String] Challenge method (default: 'S256')
+      def initialize(code_verifier: nil, code_challenge: nil, code_challenge_method: nil)
+        @code_verifier = code_verifier || generate_code_verifier
+        @code_challenge = code_challenge || generate_code_challenge(@code_verifier)
+        @code_challenge_method = code_challenge_method || 'S256'
+      end
+
+      # Convert to hash for serialization
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          code_verifier: @code_verifier,
+          code_challenge: @code_challenge,
+          code_challenge_method: @code_challenge_method
+        }
+      end
+
+      # Create PKCE instance from hash
+      # @param data [Hash] Hash with PKCE parameters (symbol or string keys)
+      # @return [PKCE] New PKCE instance
+      # @raise [ArgumentError] If required parameters are missing
+      # @note code_challenge_method is optional and defaults to 'S256'.
+      #   The code_challenge is not re-validated against code_verifier;
+      #   callers are expected to provide values from a prior to_h round-trip.
+      def self.from_h(data)
+        verifier = data[:code_verifier] || data['code_verifier']
+        challenge = data[:code_challenge] || data['code_challenge']
+        method = data[:code_challenge_method] || data['code_challenge_method']
+
+        raise ArgumentError, 'Missing code_verifier' unless verifier
+        raise ArgumentError, 'Missing code_challenge' unless challenge
+
+        new(code_verifier: verifier, code_challenge: challenge, code_challenge_method: method)
       end
 
       private