ruby-mcp-client 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e56ef84106ab19bf3028b31dd7ce362cfb58f244743057271f14a83409153f0
-  data.tar.gz: 96f0e42875d80032c24056c1dbd9c6417b3db994538838736fa52f303e0d4f85
+  metadata.gz: e99574cdccfbab39918f6576fc7c896b5208599313bd69e2f39df5b529c82c22
+  data.tar.gz: 823177bc1a531d773514b9d9da8d3d6f0f2aa15f6e8562e8c0123adcdb38911c
 SHA512:
-  metadata.gz: 48b7cd77ab406967bc4cd5fe79c5c1511a8eb2c9e4c9ebc27b31b8386e175a435d1a620ffcfa7871044188061b3f0718875d009f2a4ef7d030786ad11bcbde35
-  data.tar.gz: 11f845c21895b67d0a308267972936fcf07df042e33de6417b69ee486f1739a8768f25b698bbbad92fdbef3acf0e6ec42eaffa525896b9e77e50e86960c7daf8
+  metadata.gz: bc352d545dbabb90322ab473eaff7c6d52111ccd6e4812baa8b6507dc720024e23752b4a68481dc5b83722d2c9c4b6b3a36a17821998fc745cd8164e57ac8380
+  data.tar.gz: 72b2cdc279b54f2b10cbac22755086edee67792bd18e035d167f2855ad1d5dc5999c87d98e17bef83a70632459003bbd4af516414fe0e7b78b918fc2b2c5a8ce

data/README.md

@@ -38,7 +38,7 @@ Implements **MCP 2025-11-25** specification:
 - **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
+- **Tasks**: Task-augmented `tools/call` — create with a `ttl`, poll `tasks/get`, retrieve via `tasks/result`, plus `tasks/list` and `tasks/cancel`
 - **Audio**: Audio content type support
 - **OAuth 2.1**: PKCE, server discovery, dynamic registration
 
@@ -107,6 +107,11 @@ end
 prompts = client.list_prompts
 result = client.get_prompt('greeting', { name: 'Alice' })
 
+# Pagination: list_tools and list_prompts automatically follow the server's
+# nextCursor and return the COMPLETE set across all pages (with a per-call
+# safety bound and an identical-cursor loop guard). No manual cursor handling
+# is required.
+
 # Resources
 result = client.list_resources
 contents = client.read_resource('file:///example.txt')
@@ -124,9 +129,12 @@ end
 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
+# Defaults follow the MCP ToolAnnotations schema: when a hint is absent the
+# client assumes the less-safe value, so an un-annotated tool is treated as
+# writable, potentially destructive, and open-world.
+tool.read_only_hint?      # Defaults to false; tool may modify its environment
+tool.destructive_hint?    # Defaults to true; tool may perform destructive updates
+tool.idempotent_hint?     # Defaults to false; repeated calls may have additional effects
 tool.open_world_hint?     # Defaults to true; tool may interact with external entities
 
 # Legacy annotations
@@ -200,6 +208,39 @@ client.on_notification do |server, method, params|
 end
 ```
 
+### Tasks (Long-running, task-augmented tools)
+
+A task-capable server (one advertising `tasks.requests.tools.call`) can run a tool
+whose `execution.taskSupport` is `optional` or `required` as a background task:
+the call returns immediately with a task handle, and the result is fetched later.
+
+```ruby
+tool = client.find_tool('long_job')
+tool.supports_task?   # execution.taskSupport is optional/required?
+
+# Create the task (returns immediately); ttl is the requested lifetime in ms
+task = client.call_tool_as_task('long_job', { input: 'data' }, ttl: 60_000)
+
+# Poll until the task reaches a terminal (or input-required) status,
+# honoring the server's suggested poll interval
+until task.terminal? || task.input_required?
+  sleep((task.poll_interval || 1000) / 1000.0)
+  task = client.get_task(task.task_id)   # tasks/get
+end
+
+# Retrieve the underlying result (e.g. a CallToolResult) via tasks/result
+result = client.get_task_result(task.task_id)
+
+# List and cancel tasks
+page = client.list_tasks               # { tasks: [...], next_cursor: ... }
+client.cancel_task(task.task_id)       # tasks/cancel
+
+# React to server-pushed status updates
+client.on_notification do |server, method, params|
+  puts "Task #{params['taskId']} -> #{params['status']}" if method == 'notifications/tasks/status'
+end
+```
+
 ### Elicitation (Server-initiated user interactions)
 
 ```ruby
@@ -243,6 +284,18 @@ client = MCPClient.create_client(
 client = MCPClient.create_client(server_definition_file: 'servers.json')
 ```
 
+### Retries
+
+The `retries:` option controls automatic retry with exponential backoff. Only
+failures where the request most likely did **not** complete at the server are
+retried: transport/network errors and HTTP **5xx** responses. Application-level
+failures — a JSON-RPC error response or an HTTP **4xx** — are **never** retried,
+because the server already processed or rejected the request and re-sending
+would risk re-executing a non-idempotent `tools/call`. Retryable server failures
+raise `MCPClient::Errors::TransientServerError`, a subclass of
+`MCPClient::Errors::ServerError`, so existing `rescue ServerError` handlers are
+unaffected.
+
 ### Faraday Customization
 
 ```ruby
@@ -334,9 +387,65 @@ See `examples/` for complete implementations:
 - `gemini_ai_mcp.rb` - Google Vertex AI integration
 - `ruby_llm_mcp.rb` - RubyLLM integration (OpenAI provider)
 
+## Running the Examples
+
+The `examples/run_all_examples.sh` harness runs every example that can run on the current machine — self-contained stdio servers, the Python/Flask/FastMCP echo and elicitation servers, `npx`-based MCP servers, and (optionally) the paid LLM integrations. It starts and tears down each server automatically and prints a `PASS`/`FAIL`/`SKIP` summary. `tasks_example.rb` is always skipped (it needs a task-capable remote server); `oauth_browser_auth.rb` is interactive and only runs when you opt in with `RUN_OAUTH=1`.
+
+### Prerequisites
+
+Run `bundle install` first. The script preflight-checks the following and prints a warning (it does **not** abort) for anything missing; affected examples are then skipped or fail:
+
+- `ruby`, `bundle`, `curl`, `lsof` - on `PATH`
+- `python3` (or `$PYTHON`) plus a separate `python` binary - on `PATH`
+- Python packages `flask`, `fastmcp`, `mcp` - importable by `$PYTHON`
+- `npx` (Node) - needed by the `npx`-based example (`json_input`) and by every LLM example, which spawn `npx` filesystem/Playwright servers
+
+### Usage
+
+```bash
+examples/run_all_examples.sh                       # run everything runnable on this machine
+RUN_AI=0 examples/run_all_examples.sh              # skip the paid-LLM examples
+RUN_NPX=0 examples/run_all_examples.sh             # skip the npx-based example (json_input)
+LOG_DIR=/path examples/run_all_examples.sh         # write logs to a chosen dir
+PYTHON=python3.12 TIMEOUT=180 examples/run_all_examples.sh  # override interpreter and per-example timeout
+```
+
+### Environment Knobs
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `RUN_AI` | `1` | Set to `0` to skip the LLM integrations, which make **real, paid** API calls. |
+| `RUN_NPX` | `1` | Set to `0` (or leave `npx` off `PATH`) to skip the `npx`-based example (`json_input`). The LLM examples spawn `npx` servers too, but are gated by `RUN_AI` and their API keys instead. |
+| `PYTHON` | `python3` | Interpreter used to launch the Python/Flask/FastMCP servers and run the import preflight checks. |
+| `TIMEOUT` | `120` | Per-example wall-clock timeout in seconds; a timeout is reported as a `FAIL`. |
+| `LOG_DIR` | fresh `mktemp` dir | Directory for per-example and per-server logs; the path is printed after preflight and in the summary. |
+
+### Secrets and API Keys
+
+Real secrets live in `examples/secrets.env`, which is **gitignored** and sourced automatically (every `KEY=value` line is exported) when present. Copy the tracked template to get started:
+
+```bash
+cp examples/secrets.env.example examples/secrets.env
+# then set ZAPIER_MCP_TOKEN=... to enable the Zapier streamable-HTTP example
+```
+
+Set `ZAPIER_MCP_TOKEN` (from the Zapier MCP setup page, "Option 1: Authorization header") to run `streamable_http_example.rb` and `oauth_example.rb` against Zapier; override `ZAPIER_MCP_URL` if your connect URL differs. To run the interactive `oauth_browser_auth.rb`, set `MCP_SERVER_URL` (e.g. an ngrok tunnel to your OAuth-protected MCP server) in `secrets.env` and pass `RUN_OAUTH=1`. The LLM examples each need their own credentials in the environment and are skipped without them:
+
+- `ruby_anthropic_mcp.rb` - `ANTHROPIC_API_KEY` (+ `npx`)
+- `openai_ruby_mcp.rb` - `OPENAI_API_KEY` (+ `npx`)
+- `ruby_openai_mcp.rb`, `ruby_llm_mcp.rb` - `OPENAI_API_KEY` (+ `npx`, plus a Playwright MCP server on `:8931`)
+- `gemini_ai_mcp.rb` - a Vertex service-account JSON at `VERTEX_CREDENTIALS_FILE` (default `examples/google-credentials.json`, + `npx`)
+
+### How Pass/Fail Is Judged
+
+Most examples print their own success/failure marks but exit `0` regardless, so the harness combines the exit code with a scan of the output rather than trusting the exit status alone. An example `FAIL`s when it exits nonzero, times out (exit `124`), prints a hard-error signature (a Ruby/Python traceback, `Connection refused`, `uninitialized constant`, and similar), prints a `❌` mark, or is missing its expected success marker; otherwise it `PASS`es. (The `❌` check is suppressed with `IGNORE_XMARK=1` for the interactive elicitation demos, where `❌` can be legitimate "declined" output.) The script exits `0` only if zero examples failed — `SKIP`s do not affect the exit status.
+
+For deeper, per-topic walkthroughs see [`examples/README.md`](examples/README.md), [`examples/README_ECHO_SERVER.md`](examples/README_ECHO_SERVER.md), [`examples/STREAMABLE_HTTP_TESTING.md`](examples/STREAMABLE_HTTP_TESTING.md), and [`examples/elicitation/README.md`](examples/elicitation/README.md).
+
 ## OAuth 2.1 Authentication
 
 ```ruby
+require 'mcp_client'
 require 'mcp_client/auth/browser_oauth'
 
 oauth = MCPClient::Auth::OAuthProvider.new(

data/lib/mcp_client/auth/oauth_provider.rb

@@ -41,6 +41,10 @@ module MCPClient
         self.storage = storage || MemoryStorage.new
         @extra_client_metadata = client_metadata
         @http_client = create_http_client
+        # Protected resource metadata learned from a 401 WWW-Authenticate
+        # challenge, reused by discovery so a challenge-advertised metadata URL
+        # is not re-derived (and possibly missed).
+        @challenge_resource_metadata = nil
       end
 
       # @param url [String] Server URL to normalize
@@ -142,12 +146,37 @@ module MCPClient
         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)
+        url = extract_resource_metadata_url(www_authenticate)
+        return nil unless url
+
+        # This URL was explicitly advertised by the 401 challenge, so a 404 is a
+        # misconfiguration to surface (strict), not a speculative miss to skip.
+        metadata = fetch_resource_metadata(url, strict: true)
+        # Reuse this challenge-advertised metadata during the subsequent OAuth
+        # flow instead of re-deriving (and possibly missing) the well-known URL.
+        @challenge_resource_metadata = metadata
+        metadata
+      end
+
+      # Extract the protected-resource-metadata URL from a WWW-Authenticate header.
+      # Per RFC 9728 the parameter is `resource_metadata`; a legacy `resource`
+      # parameter is accepted as a fallback for older servers.
+      # @param header [String] the WWW-Authenticate header value
+      # @return [String, nil] the metadata URL if present
+      def extract_resource_metadata_url(header)
+        # Auth-params may include optional whitespace around '=' (RFC 7235).
+        # Quoted form: resource_metadata = "https://..."
+        if (m = header.match(/resource_metadata\s*=\s*"([^"]+)"/))
+          return m[1]
+        end
+
+        # Unquoted token form: resource_metadata = https://...
+        if (m = header.match(/resource_metadata\s*=\s*([^,\s]+)/))
+          return m[1]
         end
+
+        # Legacy fallback: resource="https://..."
+        header.match(/resource\s*=\s*"([^"]+)"/)&.captures&.first
       end
 
       private
@@ -213,6 +242,55 @@ module MCPClient
           (uri.scheme == 'https' && uri.port == 443)
       end
 
+      # Build the scheme://host[:port] origin for a parsed URI.
+      # @param uri [URI] Parsed URI
+      # @return [String] origin string
+      def origin_of(uri)
+        origin = "#{uri.scheme}://#{uri.host}"
+        origin += ":#{uri.port}" if uri.port && !default_port?(uri)
+        origin
+      end
+
+      # Protected Resource Metadata well-known URLs to try, in priority order
+      # (RFC 9728 §3.1). When the resource identifier has a path, the well-known
+      # segment is inserted between the host and the path; a root-level URL is
+      # always tried as a fallback.
+      # @param server_url [String] the MCP server (protected resource) URL
+      # @return [Array<String>] ordered candidate URLs
+      def protected_resource_metadata_urls(server_url)
+        uri = URI.parse(server_url)
+        origin = origin_of(uri)
+        path = uri.path.to_s
+
+        urls = []
+        urls << "#{origin}/.well-known/oauth-protected-resource#{path}" unless path.empty? || path == '/'
+        urls << "#{origin}/.well-known/oauth-protected-resource"
+        urls.uniq
+      end
+
+      # Authorization Server Metadata well-known URLs to try, in priority order
+      # (RFC 8414 §3.1 path-insertion plus OpenID Connect Discovery). When the
+      # issuer has a path, the well-known segment is INSERTED between host and
+      # path (not appended); the OIDC path-append form is also tried.
+      # @param issuer [String] the authorization server issuer URL
+      # @return [Array<String>] ordered candidate URLs
+      def authorization_server_metadata_urls(issuer)
+        uri = URI.parse(issuer)
+        origin = origin_of(uri)
+        path = uri.path.to_s
+
+        urls = []
+        if path.empty? || path == '/'
+          urls << "#{origin}/.well-known/oauth-authorization-server"
+          urls << "#{origin}/.well-known/openid-configuration"
+        else
+          urls << "#{origin}/.well-known/oauth-authorization-server#{path}"
+          urls << "#{origin}/.well-known/openid-configuration#{path}"
+          urls << "#{origin}#{path}/.well-known/openid-configuration"
+        end
+        urls.uniq
+      end
+
       # Discover authorization server metadata
       # Tries multiple discovery patterns:
       # 1. oauth-authorization-server (MCP spec pattern - server is its own auth server)
@@ -220,63 +298,274 @@ module MCPClient
       # @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))
+        # A fresh 401 challenge is authoritative and overrides any cached
+        # (possibly stale or direct-discovered) authorization server metadata.
+        cached = storage.get_server_metadata(server_url) unless @challenge_resource_metadata
+        if cached
+          # Validate the cached entry before use so a persisted/older cache with
+          # an HTTP endpoint or without S256 is still rejected.
+          validate_server_metadata!(cached)
           return cached
         end
 
-        server_metadata = nil
+        discover_and_cache_authorization_server
+      end
 
-        # Primary discovery: oauth-authorization-server (MCP spec pattern)
-        # Used by servers that are both resource and authorization server
-        begin
-          discovery_url = build_discovery_url(server_url, :authorization_server)
-          logger.debug("Attempting OAuth discovery: #{discovery_url}")
-          server_metadata = fetch_server_metadata(discovery_url)
-        rescue MCPClient::Errors::ConnectionError => e
-          logger.debug("oauth-authorization-server discovery failed: #{e.message}")
-        end
+      # Discover authorization server metadata, validate it, and cache it.
+      # @return [ServerMetadata]
+      # @raise [MCPClient::Errors::ConnectionError] if discovery or validation fails
+      def discover_and_cache_authorization_server
+        previous = storage.get_server_metadata(server_url)
 
-        # Fallback discovery: oauth-protected-resource (delegation pattern)
-        # Used by resource servers that delegate to external authorization servers
-        unless server_metadata
-          begin
-            discovery_url = build_discovery_url(server_url, :protected_resource)
-            logger.debug("Attempting OAuth discovery: #{discovery_url}")
-
-            resource_metadata = fetch_resource_metadata(discovery_url)
-            auth_server_url = resource_metadata.authorization_servers.first
-
-            if auth_server_url
-              server_metadata = fetch_server_metadata("#{auth_server_url}/.well-known/oauth-authorization-server")
-            end
-          rescue MCPClient::Errors::ConnectionError => e
-            logger.debug("oauth-protected-resource discovery failed: #{e.message}")
-          end
-        end
+        # RFC 9728: Protected Resource Metadata is authoritative — try it first,
+        # then fall back to treating the MCP server origin as its own AS.
+        server_metadata = discover_via_protected_resource || discover_via_direct_authorization_server
 
         unless server_metadata
           raise MCPClient::Errors::ConnectionError,
-                'OAuth discovery failed: no valid endpoints found'
+                'OAuth discovery failed: no valid authorization server metadata found'
         end
 
-        # Cache the metadata
+        # Validate BEFORE caching so invalid metadata is never persisted.
+        validate_server_metadata!(server_metadata)
+
+        invalidate_client_info_on_as_change(previous, server_metadata)
+
         storage.set_server_metadata(server_url, server_metadata)
+        @challenge_resource_metadata = nil # consumed
+        server_metadata
+      end
+
+      # When a 401 challenge changes the authorization server, per-AS state cached
+      # under this server_url becomes invalid: a client_id registered with the
+      # previous AS would fail as invalid_client, and memoized scopes belong to
+      # the old AS. Discard both so the new flow re-registers and re-discovers.
+      # @param previous [ServerMetadata, nil] previously cached AS metadata
+      # @param current [ServerMetadata] newly discovered AS metadata
+      def invalidate_client_info_on_as_change(previous, current)
+        return unless previous && previous.issuer != current.issuer
+
+        logger.debug('Authorization server changed; discarding client and scopes from the previous AS')
+
+        # Prefer an explicit delete; fall back to the always-available
+        # set_client_info(nil) so custom storage backends are handled too.
+        if storage.respond_to?(:delete_client_info)
+          storage.delete_client_info(server_url)
+        else
+          storage.set_client_info(server_url, nil)
+        end
+
+        @supported_scopes = nil
+      end
+
+      # Apply the PKCE-support and HTTPS-endpoint checks to server metadata.
+      # @param server_metadata [ServerMetadata]
+      # @raise [MCPClient::Errors::ConnectionError] if a check fails
+      def validate_server_metadata!(server_metadata)
+        verify_pkce_support!(server_metadata)
+        enforce_https_endpoints!(server_metadata)
+      end
+
+      # PRM-first discovery: fetch Protected Resource Metadata and then the
+      # authorization server it advertises.
+      # @return [ServerMetadata, nil] AS metadata, or nil if no PRM document exists
+      # @raise [MCPClient::Errors::ConnectionError] if PRM is malformed or mismatched
+      def discover_via_protected_resource
+        # A missing PRM document (return nil) permits the direct-AS fallback. But
+        # once PRM IS found it is authoritative: any subsequent failure must be a
+        # hard error, never a silent fallback to an authorization server the PRM
+        # did not advertise.
+        resource_metadata = @challenge_resource_metadata ||
+                            fetch_first_resource_metadata(protected_resource_metadata_urls(server_url))
+        return nil unless resource_metadata
+
+        validate_resource_matches!(resource_metadata)
+
+        auth_server_url = Array(resource_metadata.authorization_servers).first
+        unless auth_server_url
+          raise MCPClient::Errors::ConnectionError,
+                'Protected resource metadata does not advertise any authorization_servers'
+        end
+
+        server_metadata = fetch_first_server_metadata(authorization_server_metadata_urls(auth_server_url))
+        unless server_metadata
+          raise MCPClient::Errors::ConnectionError,
+                "Authorization server advertised by protected resource metadata (#{auth_server_url}) " \
+                'could not be discovered'
+        end
 
         server_metadata
       end
 
-      # Fetch resource metadata from URL
+      # Legacy/self-hosted discovery: treat the MCP server ORIGIN as its own
+      # authorization server issuer.
+      # @return [ServerMetadata, nil]
+      def discover_via_direct_authorization_server
+        origin = origin_of(URI.parse(server_url))
+        fetch_first_server_metadata(authorization_server_metadata_urls(origin))
+      end
+
+      # Fetch the first Protected Resource Metadata document that resolves.
+      #
+      # PRM is authoritative: a candidate that genuinely does not exist (HTTP
+      # 404) is skipped so the next candidate is tried, but a candidate that
+      # exists yet is malformed or errors (bad JSON, 5xx, network failure) is a
+      # HARD failure — it must not silently fall through to a root PRM or the
+      # direct-AS path, which could point at a different authorization server.
+      # @param urls [Array<String>] candidate URLs
+      # @return [ResourceMetadata, nil]
+      def fetch_first_resource_metadata(urls)
+        urls.each do |url|
+          md = fetch_resource_metadata(url) # returns nil only for a 404 (absent); raises otherwise
+          return md if md
+        end
+        nil
+      end
+
+      # Fetch the first Authorization Server Metadata document that resolves.
+      # The oauth-authorization-server and openid-configuration forms are
+      # genuine alternatives, so any failing candidate is skipped to try the next.
+      # @param urls [Array<String>] candidate URLs
+      # @return [ServerMetadata, nil]
+      def fetch_first_server_metadata(urls)
+        urls.each do |url|
+          md = try_fetch_server_metadata(url)
+          return md if md
+        end
+        nil
+      end
+
+      # Non-raising server-metadata fetch used while iterating candidates.
+      def try_fetch_server_metadata(url)
+        fetch_server_metadata(url)
+      rescue MCPClient::Errors::ConnectionError => e
+        logger.debug("Authorization server metadata candidate failed (#{url}): #{e.message}")
+        nil
+      end
+
+      # Verify the authorization server supports PKCE S256 (RFC 8414 / MCP).
+      # Refuses when S256 is explicitly not offered; warns (and proceeds, since
+      # the client always uses S256) when the field is not advertised at all.
+      # @param server_metadata [ServerMetadata]
+      # @raise [MCPClient::Errors::ConnectionError] if S256 is explicitly unsupported
+      def verify_pkce_support!(server_metadata)
+        methods = server_metadata.code_challenge_methods_supported
+        if methods.nil?
+          logger.warn(
+            'Authorization server metadata omits code_challenge_methods_supported; ' \
+            'proceeding with PKCE S256'
+          )
+        elsif !methods.include?('S256')
+          raise MCPClient::Errors::ConnectionError,
+                'Authorization server does not support PKCE S256 ' \
+                '(code_challenge_methods_supported does not include "S256")'
+        end
+      end
+
+      # Require HTTPS for all discovered authorization server endpoints, with a
+      # localhost exception for local development.
+      # @param server_metadata [ServerMetadata]
+      def enforce_https_endpoints!(server_metadata)
+        enforce_https!(server_metadata.authorization_endpoint, 'authorization endpoint')
+        enforce_https!(server_metadata.token_endpoint, 'token endpoint')
+        return unless server_metadata.registration_endpoint
+
+        enforce_https!(server_metadata.registration_endpoint, 'registration endpoint')
+      end
+
+      # @param url [String, nil] endpoint URL
+      # @param label [String] human-readable endpoint name for errors
+      # @raise [MCPClient::Errors::ConnectionError] if the URL is not HTTPS (non-localhost)
+      def enforce_https!(url, label)
+        return if url.nil?
+
+        uri = URI.parse(url)
+        return if uri.scheme == 'https'
+        # Dev exception is only for plain HTTP on a loopback host — not any other
+        # scheme (e.g. ftp://localhost). Use #hostname (not #host) so an IPv6
+        # loopback like http://[::1]:9292 matches without the surrounding brackets.
+        return if uri.scheme == 'http' && %w[localhost 127.0.0.1 ::1].include?(uri.hostname)
+
+        raise MCPClient::Errors::ConnectionError, "OAuth #{label} must use HTTPS: #{url}"
+      rescue URI::InvalidURIError
+        raise MCPClient::Errors::ConnectionError, "OAuth #{label} is not a valid URL: #{url}"
+      end
+
+      # Validate the PRM `resource` identifies this server (RFC 9728 confused
+      # deputy protection). Path/canonicalization differences on the same host
+      # are tolerated; a different host is rejected.
+      # @param resource_metadata [ResourceMetadata]
+      # @raise [MCPClient::Errors::ConnectionError] on host mismatch
+      def validate_resource_matches!(resource_metadata)
+        # RFC 9728 requires `resource`; without it the confused-deputy check is
+        # impossible, so a PRM that omits it must be rejected (not trusted).
+        if resource_metadata.resource.nil?
+          raise MCPClient::Errors::ConnectionError,
+                'Protected resource metadata is missing the required "resource" identifier'
+        end
+
+        # Require an EXACT canonical match (scheme/host/port/path). A same-host
+        # match is not enough: a host that serves multiple resources/tenants
+        # must not have one tenant's PRM trusted for another.
+        advertised = resource_identity(resource_metadata.resource)
+        expected = resource_identity(server_url)
+        return if advertised == expected
+
+        raise MCPClient::Errors::ConnectionError,
+              "Protected resource metadata resource (#{resource_metadata.resource}) " \
+              "does not match the server URL (#{server_url})"
+      end
+
+      # Canonical resource identity (scheme, host, port, path, query) used for
+      # the confused-deputy comparison. The query is included because the
+      # `resource` parameter sent in the authorization and token requests is the
+      # full server URL (some servers distinguish resources by query, e.g.
+      # ?serverId=a vs ?serverId=b); only the fragment is ignored. Rejects a
+      # non-absolute URL, since the value is untrusted server input.
+      # @param url [String] a resource URL
+      # @return [String] canonical identity string
+      # @raise [MCPClient::Errors::ConnectionError] if the URL is not an absolute URI
+      def resource_identity(url)
+        uri = URI.parse(url)
+        unless uri.scheme && uri.host
+          raise MCPClient::Errors::ConnectionError, "Invalid resource URL (must be absolute): #{url}"
+        end
+
+        scheme = uri.scheme.downcase
+        host = uri.host.downcase
+        port = uri.port
+        port = nil if (scheme == 'http' && port == 80) || (scheme == 'https' && port == 443)
+        path = uri.path.to_s
+        path = '' if path == '/'
+        path = path.chomp('/') while path.end_with?('/')
+        query = uri.query ? "?#{uri.query}" : ''
+
+        "#{scheme}://#{host}#{":#{port}" if port}#{path}#{query}"
+      rescue URI::InvalidURIError
+        raise MCPClient::Errors::ConnectionError, "Invalid resource URL: #{url}"
+      end
+
+      # Fetch resource metadata from URL.
+      #
+      # Returns nil when the document is genuinely absent (HTTP 404) so a
+      # discovery loop can try the next candidate. Any other failure — a
+      # non-404 error status, malformed JSON, or a network error — raises,
+      # because PRM is authoritative and such a response must not be silently
+      # skipped in favor of a different authorization server.
       # @param url [String] Resource metadata URL
-      # @return [ResourceMetadata] Resource metadata
-      # @raise [MCPClient::Errors::ConnectionError] if fetch fails
-      def fetch_resource_metadata(url)
+      # @param strict [Boolean] when true, a 404 raises instead of returning nil
+      #   (used for a URL explicitly advertised by a 401 challenge)
+      # @return [ResourceMetadata, nil] metadata, or nil if a speculative URL returns 404
+      # @raise [MCPClient::Errors::ConnectionError] on any non-404 failure, or on 404 when strict
+      def fetch_resource_metadata(url, strict: false)
         logger.debug("Fetching resource metadata from: #{url}")
 
         response = @http_client.get(url) do |req|
           req.headers['Accept'] = 'application/json'
         end
 
+        return nil if response.status == 404 && !strict
+
         unless response.success?
           raise MCPClient::Errors::ConnectionError, "Failed to fetch resource metadata: HTTP #{response.status}"
         end
@@ -612,6 +901,10 @@ module MCPClient
           @client_infos[server_url] = client_info
         end
 
+        def delete_client_info(server_url)
+          @client_infos.delete(server_url)
+        end
+
         def get_server_metadata(server_url)
           @server_metadata[server_url]
         end

data/lib/mcp_client/auth.rb

@@ -225,7 +225,8 @@ module MCPClient
     # OAuth authorization server metadata
     class ServerMetadata
       attr_reader :issuer, :authorization_endpoint, :token_endpoint, :registration_endpoint,
-                  :scopes_supported, :response_types_supported, :grant_types_supported
+                  :scopes_supported, :response_types_supported, :grant_types_supported,
+                  :code_challenge_methods_supported
 
       # @param issuer [String] Issuer identifier URL
       # @param authorization_endpoint [String] Authorization endpoint URL
@@ -234,8 +235,10 @@ module MCPClient
       # @param scopes_supported [Array<String>, nil] Supported OAuth scopes
       # @param response_types_supported [Array<String>, nil] Supported response types
       # @param grant_types_supported [Array<String>, nil] Supported grant types
+      # @param code_challenge_methods_supported [Array<String>, nil] Supported PKCE code challenge methods (RFC 8414)
       def initialize(issuer:, authorization_endpoint:, token_endpoint:, registration_endpoint: nil,
-                     scopes_supported: nil, response_types_supported: nil, grant_types_supported: nil)
+                     scopes_supported: nil, response_types_supported: nil, grant_types_supported: nil,
+                     code_challenge_methods_supported: nil)
         @issuer = issuer
         @authorization_endpoint = authorization_endpoint
         @token_endpoint = token_endpoint
@@ -243,6 +246,7 @@ module MCPClient
         @scopes_supported = scopes_supported
         @response_types_supported = response_types_supported
         @grant_types_supported = grant_types_supported
+        @code_challenge_methods_supported = code_challenge_methods_supported
       end
 
       # Check if dynamic client registration is supported
@@ -261,7 +265,8 @@ module MCPClient
           registration_endpoint: @registration_endpoint,
           scopes_supported: @scopes_supported,
           response_types_supported: @response_types_supported,
-          grant_types_supported: @grant_types_supported
+          grant_types_supported: @grant_types_supported,
+          code_challenge_methods_supported: @code_challenge_methods_supported
         }.compact
       end
 
@@ -276,7 +281,9 @@ module MCPClient
           registration_endpoint: data[:registration_endpoint] || data['registration_endpoint'],
           scopes_supported: data[:scopes_supported] || data['scopes_supported'],
           response_types_supported: data[:response_types_supported] || data['response_types_supported'],
-          grant_types_supported: data[:grant_types_supported] || data['grant_types_supported']
+          grant_types_supported: data[:grant_types_supported] || data['grant_types_supported'],
+          code_challenge_methods_supported: data[:code_challenge_methods_supported] ||
+            data['code_challenge_methods_supported']
         )
       end
     end