ask-mcp 0.4.6 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8719aff67887e47eec36f7e8b8b7c822261cbf6e1120380580747691c4d2ef2b
-  data.tar.gz: a5c2006a33be93158838aa8fc0f0ae69c8f3a1ec2aa07fd1478cf88c50f2aa62
+  metadata.gz: d29dde6a951c940e97933e666e97f5df75483b9de280be3fcabcb184fd5e6091
+  data.tar.gz: 27cb99a853ae2daabb8f38910e8f14373d0af7d0c3f99ff79f054ed8a88c38bd
 SHA512:
-  metadata.gz: d5a909234ffdc34be3ee993118ae8145b971f120516e7eef66be8c1bf95b5a9b18e767a366e0abca51f5fd1d573186e60496404afeebcc2d66cc3d371a907a74
-  data.tar.gz: 8c058d280dd5da3aac82fcebe7aacddb3a7c5e8861375e987835294d99cfd6f4f79e12589f47b53773397267fbf7992a44f9548321b65cc6d6a108175fe800af
+  metadata.gz: ccfaa454b590f534bf0b91aa73c6a13894d4b9fd029a95ac4239ef00bcc29d0a0bf56cee54f2a1f1c941104d7f95b4d60e8d2c3ac235d0b3c1b4949b34a1428c
+  data.tar.gz: 40da8189f319185ea90e8e1a8cf8bed64aee140ce182fa439c8985f548878a44289f1ee95d48ca043928f97a85c24d460815e0deff8d7188f37e2b089de02237

data/CHANGELOG.md

@@ -1,3 +1,81 @@
+## 0.6.0
+
+- `Auth::Connect`: the browser OAuth flow for MCP servers, as a reusable
+  class. Discovers the authorization server behind a protected resource
+  (RFC 9728) and its endpoints (RFC 8414 / OIDC), registers the client on
+  the spot when the server allows it, builds the authorization URL with
+  PKCE, and redeems the redirected code — or a refresh token — for tokens.
+  HTTP rides a small injected seam, so hosts can bring their own client.
+
+## [0.5.0] - 2026-09-17
+
+### Added
+
+- **`Ask::MCP::Server::HTTP`, a Rack application serving MCP over the
+  stateless Streamable HTTP transport (2026-07-28)** — mount it wherever Rack
+  runs: `mount Ask::MCP::Server.rack_app(name: "anychat", tools: [...]) => "/mcp"`.
+  Every POST carries one JSON-RPC message and is answered with a single
+  `application/json` object; there are no sessions, no GET stream and no SSE
+  resumability, which is what the revision requires. The transport enforces
+  what the spec makes a server's job: `Origin` validation (403 for an origin
+  the host has not allowed), the required `MCP-Protocol-Version`, `Mcp-Method`
+  and `Mcp-Name` request headers validated against the body (400 with
+  `HeaderMismatch` -32020), the base64 sentinel form for header values that are
+  not plain ASCII, `UnsupportedProtocolVersionError` (-32022) listing the
+  versions it does support, 404 with -32601 for a method it does not implement,
+  202 for a notification, and 401 with `WWW-Authenticate` when `authenticate`
+  rejects a caller. `tools` may be a callable of the request context, which is
+  what lets a host expose a different tool set per caller.
+
+- **`Ask::MCP::Server::Core`, transport-agnostic message handling** — the
+  dispatch that used to live inside `Server::Stdio`, extracted so more than one
+  transport can share it. A Core turns one parsed message into the messages the
+  server wants to send and collects them in `#outbox`; `Stdio` overrides
+  `#deliver` to write to stdout as they are produced. Protocol state is
+  per-instance, so a stateless transport builds a Core per request.
+
+- **`serverInfo` in every stateless result's `_meta`** — servers SHOULD
+  identify themselves on each result so a client can attribute an answer
+  without a separate discovery round trip.
+
+### Changed
+
+- **`Ask::MCP::Server::Stdio` is now a thin subclass of `Core`** — the read
+  loop, the stdout writer and the `notify_*` methods remain. Wire behaviour is
+  unchanged; the init gate is now stated once instead of on each gated method.
+
+- **The client negotiates stateless servers correctly** — `server/discover` is
+  now sent as a *modern* request, carrying `MCP-Protocol-Version` and `_meta`,
+  because a compliant 2026-07-28 server refuses anything else. A version the
+  server does not implement comes back as `UnsupportedProtocolVersionError`;
+  the client retries once with the best version the server advertises instead
+  of falling back to the `initialize` handshake the revision removed.
+
+- **A JSON-RPC error on a non-200 response is delivered as a response, not
+  raised as a transport failure** — the spec has servers carry errors on 400
+  (header mismatch, unsupported version) and 404 (unknown method), so
+  `Transport::StreamableHTTP` surfaces those to the message handlers where the
+  pending request can pick them up. `ConnectionError` is reserved for responses
+  that are not JSON-RPC at all.
+
+### Fixed
+
+- **A server rejection now echoes the request id** — request-level errors
+  (header mismatch, unsupported version) carry the id of the request that
+  caused them, so a client can correlate a failure with what it sent. Errors
+  raised before the body is understood, and the 403 for an untrusted `Origin`,
+  carry no id, which the spec allows.
+
+- **A base64 `Mcp-Name` decodes as UTF-8** — base64 carries bytes and knows
+  nothing of encodings, so a decoded name was compared as ASCII-8BIT and never
+  matched the UTF-8 value in the body. The spec defines the payload as the
+  UTF-8 representation, so the decoded string is tagged as such.
+
+- **A stateless request naming an unspoken revision is refused** — version
+  mismatches are answered with `UnsupportedProtocolVersionError` (-32022) and
+  the list of versions the server does speak, replacing the generic
+  "not initialized" the legacy gate would have produced.
+
 ## [0.4.5] - 2026-08-12
 
 ### Added

data/lib/ask/mcp/auth/connect.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "uri"
+
+module Ask
+  module MCP
+    module Auth
+      # The browser dance that gives one person a credential for an MCP
+      # server: discover the authorization server behind the protected
+      # resource, register this client when the server allows it, hand the
+      # host a URL to send the browser to, and redeem the redirected code
+      # for tokens.
+      #
+      # Built for hosts that drive a real browser — a web action redirects
+      # to #authorization_url and its callback redeems the code — so the
+      # class keeps no browser state of its own. The caller carries the
+      # state and the PKCE verifier between the two steps, and persists
+      # #registered_client when dynamic registration produced one.
+      class Connect
+        class Error < StandardError; end
+
+        attr_reader :endpoint, :registered_client
+
+        def initialize(endpoint:, client_id: nil, client_secret: nil, http: Http)
+          @endpoint = endpoint
+          @client_id = client_id
+          @client_secret = client_secret
+          @http = http
+          @metadata = nil
+          @registered_client = nil
+        end
+
+        # The URL to send the browser to, with the PKCE verifier the caller
+        # must keep until the callback. The scope comes from the server's
+        # own advertised scopes unless the caller names one.
+        def authorization_url(redirect_uri:, state:, scope: nil, code_verifier: nil)
+          metadata = discover!
+          client = ensure_client!(redirect_uri)
+          verifier = code_verifier || self.class.generate_verifier
+
+          params = {
+            response_type: "code",
+            client_id: client[:client_id],
+            redirect_uri: redirect_uri,
+            state: state,
+            code_challenge: pkce_challenge(verifier),
+            code_challenge_method: "S256"
+          }
+          params[:scope] = scope || metadata[:scopes_supported]&.join(" ") || "mcp"
+
+          {url: "#{metadata[:authorization_endpoint]}?#{URI.encode_www_form(params)}", code_verifier: verifier}
+        end
+
+        # Redeem the redirected code. The same verifier the authorization
+        # step handed back comes along; the answer is the caller's token to
+        # store against whoever consented.
+        def exchange(code:, verifier:, redirect_uri:)
+          metadata = discover!
+          client = ensure_client!(redirect_uri)
+
+          params = {
+            grant_type: "authorization_code",
+            code: code,
+            redirect_uri: redirect_uri,
+            client_id: client[:client_id],
+            code_verifier: verifier
+          }
+          params[:client_secret] = client[:client_secret] if client[:client_secret]
+
+          token_response(@http.post_json(metadata[:token_endpoint], params))
+        end
+
+        # A fresh access token from the refresh token the server handed out.
+        def refresh(refresh_token:)
+          metadata = discover!
+          client = ensure_client!
+
+          params = {
+            grant_type: "refresh_token",
+            refresh_token: refresh_token,
+            client_id: client[:client_id]
+          }
+          params[:client_secret] = client[:client_secret] if client[:client_secret]
+
+          token_response(@http.post_json(metadata[:token_endpoint], params))
+        end
+
+        # Walk the chain MCP defines: the resource server names its
+        # authorization servers, and one of them names its endpoints. A
+        # server that publishes nothing is its own authorization server.
+        def discover!
+          return @metadata if @metadata
+
+          issuer = authorization_server_for(endpoint)
+          document = authorization_server_metadata(issuer)
+          unless document && document[:authorization_endpoint] && document[:token_endpoint]
+            raise Error, "no authorization server metadata at #{issuer}"
+          end
+
+          @metadata = {
+            issuer: issuer,
+            authorization_endpoint: document[:authorization_endpoint],
+            token_endpoint: document[:token_endpoint],
+            registration_endpoint: document[:registration_endpoint],
+            scopes_supported: document[:scopes_supported]
+          }
+        end
+
+        # The client this server knows us by: pre-registered credentials
+        # when the host has them, otherwise a registration the server
+        # created on the spot. The registered client is exposed for the
+        # host to persist — a registration that is remembered is one that
+        # is never asked for twice.
+        def ensure_client!(redirect_uri = nil)
+          return {client_id: @client_id, client_secret: @client_secret}.compact if @client_id
+
+          registration = @metadata && @metadata[:registration_endpoint]
+          raise Error, "no client credentials and #{endpoint} does not allow registration" unless registration
+          raise Error, "dynamic registration needs a redirect_uri" unless redirect_uri
+
+          @registered_client ||= begin
+            document = @http.post_json(registration, registration_params(redirect_uri))
+            {client_id: document[:client_id], client_secret: document[:client_secret]}.compact
+          end
+        end
+
+        def self.generate_verifier
+          Base64.urlsafe_encode64(SecureRandom.random_bytes(64)).delete("=")
+        end
+
+        def self.pkce_challenge(verifier)
+          Base64.urlsafe_encode64(Digest::SHA256.digest(verifier)).delete("=")
+        end
+
+        private
+
+        attr_reader :http
+
+        def registration_params(redirect_uri)
+          {
+            client_name: "Anychat",
+            redirect_uris: [redirect_uri],
+            grant_types: %w[authorization_code refresh_token],
+            response_types: %w[code],
+            token_endpoint_auth_method: "none",
+            application_type: "web"
+          }
+        end
+
+        def pkce_challenge(verifier)
+          self.class.pkce_challenge(verifier)
+        end
+
+        # RFC 9728: the resource server publishes its metadata under its own
+        # well-known path. The RFC allows the root form and a path-suffixed
+        # form; a server that publishes neither is treated as its own
+        # authorization server, which is how single-server setups behave.
+        def authorization_server_for(url)
+          uri = URI.parse(url.to_s)
+          candidates = [
+            well_known_uri(uri, "oauth-protected-resource"),
+            well_known_uri(uri, "oauth-protected-resource", suffix_path: uri.path)
+          ].compact
+
+          document = candidates.filter_map { |candidate| http.get_json(candidate) rescue nil }.first
+          servers = document && (document[:authorization_servers] || document["authorization_servers"])
+          Array(servers).first || "#{uri.scheme}://#{uri.host}#{uri.port == uri.default_port ? "" : ":#{uri.port}"}"
+        rescue URI::InvalidURIError
+          raise Error, "not a usable endpoint: #{endpoint.inspect}"
+        end
+
+        # RFC 8414 and OIDC discovery, same bargain: try the standard
+        # placements and take the first that answers.
+        def authorization_server_metadata(issuer)
+          issuer_uri = URI.parse(issuer.to_s)
+          [
+            well_known_uri(issuer_uri, "oauth-authorization-server"),
+            well_known_uri(issuer_uri, "oauth-authorization-server", suffix_path: issuer_uri.path),
+            well_known_uri(issuer_uri, "openid-configuration")
+          ].compact.filter_map { |candidate| http.get_json(candidate) rescue nil }.first
+        end
+
+        def well_known_uri(uri, name, suffix_path: nil)
+          path = suffix_path.to_s.sub(%r{/\z}, "")
+          base = "#{uri.scheme}://#{uri.host}#{uri.port == uri.default_port ? "" : ":#{uri.port}"}"
+          if path.empty?
+            "#{base}/.well-known/#{name}"
+          else
+            "#{base}/.well-known/#{name}#{path}"
+          end
+        end
+
+        def token_response(response)
+          unless response[:access_token]
+            raise Error, "token request did not return an access_token"
+          end
+
+          {
+            access_token: response[:access_token],
+            refresh_token: response[:refresh_token],
+            expires_at: response[:expires_in] ? Time.now + response[:expires_in].to_i : nil,
+            scope: response[:scope]
+          }
+        end
+
+        # A thin HTTP seam, so a host can bring its own client and tests can
+        # stay off the network. Form-encoded bodies, because that is what
+        # authorization servers speak at these endpoints.
+        module Http
+          module_function
+
+          def get_json(url)
+            require "httpx"
+
+            response = HTTPX.get(url)
+            return nil unless response.status == 200
+
+            JSON.parse(response.body.to_s, symbolize_names: true)
+          rescue JSON::ParserError
+            nil
+          end
+
+          def post_json(url, params)
+            require "httpx"
+
+            response = HTTPX.post(url, form: params)
+            unless response.status == 200 || response.status == 201
+              raise Error, "request to #{url} failed: #{response.status} #{response.body.to_s[0, 200]}"
+            end
+
+            JSON.parse(response.body.to_s, symbolize_names: true)
+          rescue JSON::ParserError
+            raise Error, "invalid JSON from #{url}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/mcp/client.rb

@@ -161,8 +161,23 @@ module Ask
         @transport.protocol_version = @protocol_version if @transport.respond_to?(:protocol_version=)
       end
 
+      # Probe the server as a *modern* request. A compliant 2026-07-28 server
+      # requires MCP-Protocol-Version and `_meta` on every request and refuses
+      # anything else, so the probe has to name a version before negotiation
+      # has happened. A version the server does not implement comes back as an
+      # UnsupportedProtocolVersionError naming the ones it does; retry once
+      # with the best of those. Answers false for a server that is not modern,
+      # which is the caller's cue to fall back to `initialize`.
       def discover_server
-        response = send_request_raw("server/discover", {}, timeout: 5)
+        response = probe_discover(Ask::MCP::SUPPORTED_PROTOCOL_VERSIONS.last)
+
+        if unsupported_version?(response)
+          chosen = advertised_protocol_version(response)
+          return false unless chosen
+
+          response = probe_discover(chosen)
+        end
+
         return false unless response.success?
 
         result = response.result
@@ -179,15 +194,43 @@ module Ask
         false
       end
 
+      def probe_discover(version)
+        @transport.protocol_version = version if @transport.respond_to?(:protocol_version=)
+        request = Native::Messages::Request.new(
+          method: "server/discover", params: meta_params(version), id: next_id
+        )
+        wait_for_response(request, timeout: 5)
+      end
+
+      def unsupported_version?(response)
+        return false if response.success?
+
+        error_of(response)[:code] == Native::Messages::ErrorCodes::UNSUPPORTED_PROTOCOL_VERSION
+      end
+
+      def advertised_protocol_version(response)
+        data = error_of(response)[:data]
+        supported = Array(data[:supported] || data["supported"])
+        Ask::MCP::SUPPORTED_PROTOCOL_VERSIONS.reverse.find { |version| supported.include?(version) }
+      end
+
+      def error_of(response)
+        error = response.error
+        { code: error[:code] || error["code"], data: error[:data] || error["data"] || {} }
+      end
+
       def reset_caches
         @tools_cache = nil
         @resources_cache = nil
         @prompts_cache = nil
       end
 
-      def meta_params
+      # The `_meta` envelope every stateless request carries. `version` is
+      # overridable so the discover probe can name a version before any
+      # negotiation has happened.
+      def meta_params(version = @protocol_version)
         meta = {
-          Native::Messages::Meta::PROTOCOL_VERSION_KEY => @protocol_version,
+          Native::Messages::Meta::PROTOCOL_VERSION_KEY => version,
           Native::Messages::Meta::CLIENT_CAPABILITIES_KEY => @options[:client_capabilities] || {},
           Native::Messages::Meta::CLIENT_INFO_KEY => { name: "ask-mcp", version: Ask::MCP::VERSION }
         }