ask-mcp 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d5c902336445279874512b3b83fea5c1f19b0de0640ceefe6d0bc61c6dd6f4e
-  data.tar.gz: a4b94e8307ef2d7b8aa2b2a6fee63a14dd45584f910f6db1c1db4b0826728699
+  metadata.gz: 207c163681c8ee59bc9c869627cb6c053ca5e3824bb2e7eafd4669152c0a86cf
+  data.tar.gz: '029f07e479189995bb8b9aa7b4e09eb7e70308851789a4a9e05ab09a80e56568'
 SHA512:
-  metadata.gz: ef659cb4cedd858c26a7cb8acb5a5cbef3f7dc4d4ec8bd88967cfbcb0437e94d333eb34d7336147298b172ea04fd1715bcae7e2de2ba5133e0b3b81a3d3cd1bf
-  data.tar.gz: 2bf513b38edd2eb62c72ad385908c7483972d11a802f22c5f6b7f8389110d55f2650c5c7ac6ba4a733a135a5de3424b35f2437455d43f466667dfe22c1a3c88d
+  metadata.gz: 823681d47e782fa73574987dfdb65f7a0ef53ff68d8dfb46d3537995d1bfa04a231bac6ec53b6b4fa03f7c34276ee6181d339644b821a391dffbcc9642a42303
+  data.tar.gz: 4118870bcb52e14efccb0d1fec411c01af5d68e5b62111a5c6818d952004f63a8198c35f7264997f7922a41a7418fb6851a31bd3a20e182ead6fbd685011ef8f

data/CHANGELOG.md

@@ -1,3 +1,72 @@
+## [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/adapters/tool_server.rb

@@ -47,6 +47,9 @@ module Ask
           end
 
           normalized = deep_stringify_keys(arguments)
+          violation = schema_violation(tool, normalized)
+          return error_result(violation) if violation
+
           result = tool.call(normalized)
           wrap_result(result)
         rescue StandardError => e
@@ -58,6 +61,30 @@ module Ask
 
         private
 
+        # Rejects arguments that don't match the tool's declared schema with
+        # a clear message — an unknown or missing parameter surfaces as such
+        # instead of leaking a raw ArgumentError from deep inside the tool.
+        # A tool that declares no schema (or no properties) accepts anything,
+        # preserving the duck-typed behavior for minimal tools.
+        def schema_violation(tool, args)
+          schema = tool.params_schema
+          return nil if schema.nil? || schema.empty?
+
+          properties = schema["properties"] || schema[:properties] || {}
+          allowed = properties.keys.map(&:to_s)
+          return nil if allowed.empty?
+
+          required = Array(schema["required"] || schema[:required]).map(&:to_s)
+
+          missing = required - args.keys
+          return "Missing required parameter(s) for #{tool.name}: #{missing.join(", ")}" if missing.any?
+
+          extra = args.keys - allowed
+          return "Unknown parameter(s) #{extra.join(", ")} for #{tool.name}. Expected: #{allowed.join(", ")}" if extra.any?
+
+          nil
+        end
+
         def wrap_result(result)
           # Plain strings are always a success
           if result.is_a?(String)

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 }
         }

data/lib/ask/mcp/server/core.rb

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+
+module Ask
+  module MCP
+    class Server
+      # Transport-agnostic MCP request processing.
+      #
+      # A Core owns one server's tools, resources and prompts and turns a
+      # single parsed JSON-RPC message into the messages the server wants to
+      # send back. Transports differ only in how those messages reach the
+      # client: Stdio writes each one to $stdout as it is produced, the HTTP
+      # transport collects them in #outbox and renders a response.
+      #
+      # Negotiated protocol state (`@protocol_version`) lives on the instance,
+      # so a stateless transport builds a Core per request rather than sharing
+      # one across callers.
+      class Core
+        MAX_RESULT_CACHE = 100
+
+        attr_reader :name, :tools, :capabilities, :resources, :prompts,
+                    :resource_templates, :outbox
+
+        # The protocol version a request declares in params `_meta`, or nil for
+        # a legacy request that expects an `initialize` handshake. Handles both
+        # symbol and string key forms (the JSON parser symbolizes all keys).
+        def self.declared_protocol_version(params)
+          meta = params[:meta] || params[:_meta] || {}
+          key = Native::Messages::Meta::PROTOCOL_VERSION_KEY
+          meta[key] || meta[key.to_sym] || meta[key.to_s]
+        end
+
+        def initialize(name:, version: nil, tools: [], capabilities: { tools: {} },
+                       resources: {}, prompts: {}, resource_templates: {},
+                       debug: false, tool_timeout: nil, cache_ttl_ms: 60_000,
+                       cache_scope: "private")
+          @name = name
+          @server_version = version || Ask::MCP::VERSION
+          @tools = tools || []
+          @capabilities = capabilities
+          @resources = resources
+          @prompts = prompts
+          @resource_templates = resource_templates
+          @debug = debug
+          @tool_timeout = tool_timeout
+          @cache_ttl_ms = cache_ttl_ms
+          @cache_scope = cache_scope
+
+          @adapter = Adapters::ToolServer.new(@tools)
+          @outbox = []
+          @initialized = false
+          @result_cache = {}
+          # Negotiated protocol version. nil until the client tells us which
+          # revision it speaks (legacy `initialize` or stateless `_meta`).
+          @protocol_version = nil
+        end
+
+        # Methods held behind the legacy gate. A stateless (2026-07-28) request
+        # opens them by declaring its version; a legacy client opens them with
+        # `initialize`.
+        GATED_METHODS = %w[
+          tools/list tools/call
+          resources/list resources/read resources/templates/list
+          prompts/list prompts/get
+        ].freeze
+
+        # Process one JSON-RPC message (symbolized keys). Every message the
+        # server produces is handed to #deliver, in order.
+        def handle_message(msg)
+          method = msg[:method]
+          id = msg[:id]
+          params = msg[:params] || {}
+          has_id = msg.key?(:id)
+
+          # A stateless (2026-07-28) request carries its protocol version in
+          # `_meta` instead of an `initialize` handshake; a version this server
+          # does not speak is answered here and the message stops.
+          version = meta_protocol_version(params)
+          if version && !supported_version?(version)
+            return send_error(id, Native::Messages::ErrorCodes::UNSUPPORTED_PROTOCOL_VERSION,
+                              "Unsupported protocol version: #{version}")
+          end
+
+          adopt_version(version)
+          return send_error(id, -32_000, "Server not initialized") if gated?(method) && !@initialized
+
+          case method
+          when "initialize"
+            handle_initialize(id, params)
+          when "server/discover"
+            handle_discover(id)
+          when "notifications/initialized"
+            @initialized = true
+            debug_log "Client initialized"
+          when "tools/list"
+            handle_tools_list(id)
+          when "tools/call"
+            handle_tool_call(id, params)
+          when "resources/list"
+            handle_resources_list(id)
+          when "resources/read"
+            handle_resource_read(id, params)
+          when "resources/templates/list"
+            handle_resources_templates_list(id)
+          when "prompts/list"
+            handle_prompts_list(id)
+          when "prompts/get"
+            handle_prompt_get(id, params)
+          when "ping"
+            # ping was removed in 2026-07-28; legacy clients still use it.
+            if stateless_mode?
+              send_error(id, Native::Messages::ErrorCodes::METHOD_NOT_FOUND, "Method not found: ping") if has_id
+            elsif has_id
+              send_result(id, {})
+            end
+          else
+            debug_log "Unknown method: #{method}"
+            send_error(id, Native::Messages::ErrorCodes::METHOD_NOT_FOUND, "Method not found: #{method}") if has_id
+          end
+        end
+
+        private
+
+        # Hand an outbound message to the transport. The default collects into
+        # #outbox; Stdio overrides this to write to $stdout as messages appear.
+        def deliver(message)
+          @outbox << message
+        end
+
+        # Adopt the protocol version a stateless (2026-07-28) request declares
+        # in `_meta`; that declaration is what unlocks the handlers without the
+        # legacy gate. A legacy request declares nothing, so the gate stands.
+        def adopt_version(version)
+          return if version.nil?
+
+          @protocol_version = version
+          @initialized = true
+          debug_log "Stateless request (protocol #{version})"
+        end
+
+        # server/discover (2026-07-28): advertise supported protocol versions,
+        # capabilities, and identity. Clients call it before anything else to
+        # select a version (or as a backward-compat probe on stdio).
+        def handle_discover(id)
+          send_result(id, {
+                        protocolVersions: Ask::MCP::SUPPORTED_PROTOCOL_VERSIONS,
+                        capabilities: @capabilities,
+                        serverInfo: { name: @name, version: @server_version }
+                      })
+          debug_log "server/discover answered"
+        end
+
+        def handle_initialize(id, params)
+          @initialized = true
+          @protocol_version = params[:protocolVersion] || Ask::MCP::PROTOCOL_VERSION
+          client_version = params[:protocolVersion] || Ask::MCP::PROTOCOL_VERSION
+          debug_log "Handling initialize (id=#{id.inspect}, version=#{client_version})"
+          send_result(id, {
+                        protocolVersion: client_version,
+                        capabilities: @capabilities,
+                        serverInfo: {
+                          name: @name,
+                          version: @server_version
+                        }
+                      })
+          debug_log "Initialize complete"
+        end
+
+        def handle_tools_list(id)
+          defs = @adapter.definitions
+          debug_log "tools/list returning #{defs.length} tool definitions"
+          send_result(id, cacheable({ tools: defs }))
+        end
+
+        def handle_resources_list(id)
+          defs = @resources.values.map { |r| resource_to_h(r) }
+          debug_log "resources/list returning #{defs.length} resources"
+          send_result(id, cacheable({ resources: defs }))
+        end
+
+        def handle_resources_templates_list(id)
+          defs = @resource_templates.values.map { |t| template_to_h(t) }
+          debug_log "resources/templates/list returning #{defs.length} templates"
+          send_result(id, cacheable({ resourceTemplates: defs }))
+        end
+
+        def handle_resource_read(id, params)
+          uri = params[:uri].to_s
+          resource = @resources[uri]
+          if resource.nil?
+            code = stateless_mode? ? Native::Messages::ErrorCodes::INVALID_PARAMS : Native::Messages::ErrorCodes::RESOURCE_NOT_FOUND
+            return send_error(id, code, "Resource not found: #{uri}")
+          end
+
+          contents = if resource.respond_to?(:content)
+                       resource.content
+                     elsif resource.respond_to?(:read)
+                       resource.read
+                     else
+                       [{ uri: uri, text: "" }]
+                     end
+          send_result(id, cacheable({ contents: contents }))
+        end
+
+        def handle_prompts_list(id)
+          defs = @prompts.values.map { |p| prompt_to_h(p) }
+          debug_log "prompts/list returning #{defs.length} prompts"
+          send_result(id, cacheable({ prompts: defs }))
+        end
+
+        def handle_prompt_get(id, params)
+          name = params[:name].to_s
+          prompt = @prompts[name]
+          if prompt.nil?
+            return send_error(id, Native::Messages::ErrorCodes::PROMPT_NOT_FOUND, "Prompt not found: #{name}")
+          end
+
+          messages = prompt.respond_to?(:messages) ? prompt.messages : []
+          send_result(id, { messages: messages })
+        end
+
+        def handle_tool_call(id, params)
+          cache_key = id.to_s
+
+          # Return cached result for retried requests (same ID, already processed)
+          if @result_cache.key?(cache_key)
+            debug_log "Returning cached result for id=#{id}"
+            return send_result(id, @result_cache[cache_key])
+          end
+
+          tool_name = params[:name].to_s
+          arguments = params[:arguments] || {}
+
+          debug_log "Handling tools/call: #{tool_name} (id=#{id.inspect})"
+
+          result = if @tool_timeout
+                     Timeout.timeout(@tool_timeout) { @adapter.call(tool_name, arguments) }
+                   else
+                     @adapter.call(tool_name, arguments)
+                   end
+
+          @result_cache[cache_key] = result
+          trim_cache
+
+          send_result(id, result)
+        rescue Timeout::Error
+          debug_log "Tool call timed out: #{tool_name}"
+          send_result(id, {
+                        content: [{ type: "text", text: "Tool call timed out: #{tool_name}" }],
+                        isError: true
+                      })
+        end
+
+        # Serialize a resource object for resources/list. Prefers to_h (the
+        # Resource value object emits title/icons/description/mimeType);
+        # otherwise builds the shape from duck-typed accessors.
+        def resource_to_h(resource)
+          return resource.to_h if resource.respond_to?(:to_h)
+
+          h = { uri: resource.uri, name: resource.name }
+          h[:title] = resource.title if resource.respond_to?(:title) && resource.title
+          h[:description] = resource.description if resource.respond_to?(:description) && resource.description
+          h[:mimeType] = resource.mime_type if resource.respond_to?(:mime_type) && resource.mime_type
+          h[:icons] = resource.icons if resource.respond_to?(:icons) && resource.icons&.any?
+          h
+        end
+
+        def template_to_h(template)
+          return template.to_h if template.respond_to?(:to_h)
+
+          h = { uriTemplate: template.uri_template, name: template.name }
+          h[:title] = template.title if template.respond_to?(:title) && template.title
+          h[:mimeType] = template.mime_type if template.respond_to?(:mime_type) && template.mime_type
+          h[:icons] = template.icons if template.respond_to?(:icons) && template.icons&.any?
+          h
+        end
+
+        def prompt_to_h(prompt)
+          return prompt.to_h if prompt.respond_to?(:to_h)
+
+          h = { name: prompt.name }
+          h[:title] = prompt.title if prompt.respond_to?(:title) && prompt.title
+          h[:description] = prompt.description if prompt.respond_to?(:description) && prompt.description
+          h[:arguments] = prompt.arguments if prompt.respond_to?(:arguments) && prompt.arguments&.any?
+          h[:icons] = prompt.icons if prompt.respond_to?(:icons) && prompt.icons&.any?
+          h
+        end
+
+        def send_result(id, result)
+          result = result.merge(stateless_result_fields) if stateless_mode?
+          deliver({ jsonrpc: "2.0", id: id, result: result })
+        end
+
+        # 2026-07-28: every result carries `resultType`, and servers SHOULD
+        # identify themselves in `_meta` so a client can attribute an answer
+        # without a separate discovery round trip. Legacy peers tolerate both
+        # fields, but we only emit them for stateless peers so the legacy wire
+        # output is unchanged.
+        def stateless_result_fields
+          {
+            resultType: "complete",
+            _meta: { Native::Messages::Meta::SERVER_INFO_KEY => server_info }
+          }
+        end
+
+        def server_info
+          { name: @name, version: @server_version }
+        end
+
+        # Build a server→client notification (no id).
+        def send_notification(method, params = {})
+          msg = { jsonrpc: "2.0", method: method }
+          msg[:params] = params unless params.empty?
+          deliver(msg)
+        end
+
+        # 2026-07-28 CacheableResult: freshness hints (ttlMs) and scope
+        # (public/private) on list/read results so clients and shared
+        # intermediaries may cache them. Only emitted for stateless peers.
+        def cacheable(result)
+          return result unless stateless_mode?
+
+          result.merge(ttlMs: @cache_ttl_ms, cacheScope: @cache_scope)
+        end
+
+        # True once a 2026-07-28 stateless peer has been detected.
+        def stateless_mode?
+          @protocol_version == Ask::MCP::LATEST_PROTOCOL_VERSION
+        end
+
+        def supported_version?(version)
+          Ask::MCP::SUPPORTED_PROTOCOL_VERSIONS.include?(version)
+        end
+
+        def gated?(method)
+          GATED_METHODS.include?(method)
+        end
+
+        # Read the protocol version a stateless client advertises in params
+        # `_meta`. Returns nil for legacy requests. Handles both symbol and
+        # string key forms (the JSON parser symbolizes all keys).
+        def meta_protocol_version(params)
+          meta = params[:meta] || params[:_meta] || {}
+          meta_value(meta, Native::Messages::Meta::PROTOCOL_VERSION_KEY)
+        end
+
+        def meta_value(meta, key)
+          meta[key] || meta[key.to_sym] || meta[key.to_s]
+        end
+
+        def send_error(id, code, message)
+          deliver({ jsonrpc: "2.0", id: id, error: { code: code, message: message } })
+        end
+
+        def debug_log(msg)
+          return unless @debug
+
+          ts = Time.now.strftime("%H:%M:%S.%L")
+          warn "[#{ts}] [#{@name}] #{msg}"
+        end
+
+        def trim_cache
+          return if @result_cache.size <= MAX_RESULT_CACHE
+
+          @result_cache.shift(@result_cache.size - MAX_RESULT_CACHE)
+        end
+      end
+    end
+  end
+end