ask-mcp 0.4.0 → 0.4.2

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

@@ -9,23 +9,33 @@ module Ask
       # MCP server over stdio transport.
       class Stdio
         MAX_RESULT_CACHE = 100
+        # Deprecated: use Ask::MCP::PROTOCOL_VERSION (the canonical constant).
+        PROTOCOL_VERSION = Ask::MCP::PROTOCOL_VERSION
 
         attr_reader :name, :tools, :capabilities, :resources, :prompts
 
         def initialize(name:, tools: [], capabilities: {}, resources: {}, prompts: {},
-                       debug: false, tool_timeout: nil)
+                       resource_templates: {}, debug: false, tool_timeout: nil,
+                       cache_ttl_ms: 60_000, cache_scope: "private")
           @name = name
           @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 || [])
           @initialized = false
           @running = false
           @shutdown_requested = false
           @result_cache = {}
+          # Negotiated protocol version. nil until the client tells us which
+          # revision it speaks (legacy `initialize` or stateless `_meta`).
+          @protocol_version = nil
+          @stateless = false
         end
 
         def start
@@ -66,6 +76,22 @@ module Ask
           @running
         end
 
+        # Emit notifications/tools/list_changed (2026-07-28: consumed by
+        # clients on the shared stdio channel or on a subscriptions/listen
+        # stream). Call these after your tool/resource/prompt sets change.
+        # Safe to call from any thread; writes are flushed immediately.
+        def notify_tools_list_changed
+          send_notification("notifications/tools/list_changed")
+        end
+
+        def notify_resources_list_changed
+          send_notification("notifications/resources/list_changed")
+        end
+
+        def notify_prompts_list_changed
+          send_notification("notifications/prompts/list_changed")
+        end
+
         private
 
         def graceful_shutdown
@@ -88,9 +114,21 @@ module Ask
           params = msg[:params] || {}
           has_id = msg.key?(:id)
 
+          # Stateless (2026-07-28) requests carry the protocol version in
+          # `_meta` instead of an `initialize` handshake. Detecting it here
+          # unlocks all handlers without the legacy @initialized gate.
+          if (meta_version = meta_protocol_version(params))
+            @protocol_version = meta_version
+            @stateless = true
+            @initialized = true
+            debug_log "Stateless request (protocol #{meta_version})"
+          end
+
           case method
           when "initialize"
             handle_initialize(id, params)
+          when "server/discover"
+            handle_discover(id)
           when "notifications/initialized"
             @initialized = true
             debug_log "Client initialized"
@@ -100,17 +138,50 @@ module Ask
           when "tools/call"
             return send_error(id, -32000, "Server not initialized") unless @initialized
             handle_tool_call(id, params)
+          when "resources/list"
+            return send_error(id, -32000, "Server not initialized") unless @initialized
+            handle_resources_list(id)
+          when "resources/read"
+            return send_error(id, -32000, "Server not initialized") unless @initialized
+            handle_resource_read(id, params)
+          when "resources/templates/list"
+            return send_error(id, -32000, "Server not initialized") unless @initialized
+            handle_resources_templates_list(id)
+          when "prompts/list"
+            return send_error(id, -32000, "Server not initialized") unless @initialized
+            handle_prompts_list(id)
+          when "prompts/get"
+            return send_error(id, -32000, "Server not initialized") unless @initialized
+            handle_prompt_get(id, params)
           when "ping"
-            send_result(id, {}) if has_id
+            # ping was removed in 2026-07-28; legacy clients still use it.
+            if stateless_mode?
+              send_error(id, -32601, "Method not found: ping") if has_id
+            else
+              send_result(id, {}) if has_id
+            end
           else
             debug_log "Unknown method: #{method}"
             send_error(id, -32601, "Method not found: #{method}") if has_id
           end
         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: Ask::MCP::VERSION }
+          })
+          debug_log "server/discover answered"
+        end
+
         def handle_initialize(id, params)
           @initialized = true
-          client_version = params[:protocolVersion] || PROTOCOL_VERSION
+          @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,
@@ -126,7 +197,54 @@ module Ask
         def handle_tools_list(id)
           defs = @adapter.definitions
           debug_log "tools/list returning #{defs.length} tool definitions"
-          send_result(id, { tools: defs })
+          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? ? -32_602 : 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)
@@ -161,10 +279,82 @@ module Ask
           })
         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)
+          # 2026-07-28: all results carry `resultType`. Legacy peers tolerate
+          # the field, but we only add it for stateless peers to keep the
+          # legacy wire output unchanged.
+          result = result.merge(resultType: "complete") if stateless_mode?
           $stdout.puts({ jsonrpc: "2.0", id: id, result: result }.to_json)
         end
 
+        # Write a server→client notification (no id). stdout is sync'd in
+        # #start, so this is safe to call from any thread.
+        def send_notification(method, params = {})
+          msg = { jsonrpc: "2.0", method: method }
+          msg[:params] = params unless params.empty?
+          $stdout.puts(msg.to_json)
+        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
+
+        # 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)
           $stdout.puts({ jsonrpc: "2.0", id: id, error: { code: code, message: message } }.to_json)
         end

data/lib/ask/mcp/server.rb

@@ -43,9 +43,14 @@ module Ask
       # @param name [String] server name
       # @param tools [Array<#call, #name, #description, #params_schema>] tool instances to expose
       # @param capabilities [Hash] MCP capabilities (default: { tools: {} })
+      # @param resources [Hash{String => #to_h, #content}] uri → resource objects
+      # @param prompts [Hash{String => #to_h, #messages}] name → prompt objects
       # @param debug [Boolean] enable stderr debug logging
-      def self.start_stdio(name:, tools: [], capabilities: { tools: {} }, debug: false)
-        Stdio.new(name: name, tools: tools, capabilities: capabilities, debug: debug).start
+      def self.start_stdio(name:, tools: [], capabilities: { tools: {} }, resources: {},
+                            prompts: {}, resource_templates: {}, debug: false)
+        Stdio.new(name: name, tools: tools, capabilities: capabilities,
+                  resources: resources, prompts: prompts,
+                  resource_templates: resource_templates, debug: debug).start
       end
     end
   end

data/lib/ask/mcp/tool.rb

@@ -3,12 +3,14 @@
 module Ask
   module MCP
     class Tool
-      attr_reader :name, :description, :input_schema
+      attr_reader :name, :description, :input_schema, :title, :icons
 
-      def initialize(name:, description: "", input_schema: {})
+      def initialize(name:, description: "", input_schema: {}, title: nil, icons: [])
         @name = name
         @description = description
         @input_schema = input_schema
+        @title = title
+        @icons = icons
       end
 
       def to_ask_tool
@@ -22,18 +24,23 @@ module Ask
       end
 
       def to_h
-        {
+        h = {
           name: @name,
           description: @description,
           inputSchema: @input_schema
         }
+        h[:title] = @title if @title
+        h[:icons] = @icons if @icons.any?
+        h
       end
 
       def self.from_h(hash)
         new(
           name: hash[:name] || hash["name"],
           description: hash[:description] || hash["description"] || "",
-          input_schema: hash[:inputSchema] || hash["input_schema"] || hash[:input_schema] || hash["inputSchema"] || {}
+          input_schema: hash[:inputSchema] || hash["input_schema"] || hash[:input_schema] || hash["inputSchema"] || {},
+          title: hash[:title] || hash["title"],
+          icons: hash[:icons] || hash["icons"] || []
         )
       end
     end

data/lib/ask/mcp/trace_context.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ask
+  module MCP
+    # OpenTelemetry trace context propagation via MCP `_meta` (2026-07-28,
+    # SEP-414). The convention reserves three `_meta` keys — `traceparent`,
+    # `tracestate`, `baggage` — so traces can span the client/server boundary.
+    module TraceContext
+      KEYS = %w[traceparent tracestate baggage].freeze
+
+      module_function
+
+      # Extract trace context from arbitrary HTTP-style headers, matching
+      # names case-insensitively and accepting Rack's HTTP_* env convention.
+      #
+      #   TraceContext.from_headers(rack_env)
+      #   # => { "traceparent" => "00-...", "tracestate" => "..." }
+      def from_headers(headers)
+        headers.each_with_object({}) do |(name, value), out|
+          key = name.to_s.downcase
+          key = key.delete_prefix("http_") if key.start_with?("http_")
+          next unless KEYS.include?(key)
+
+          out[key] = value.to_s
+        end
+      end
+
+      # Extract trace context from an MCP request's `_meta` hash (keys may be
+      # symbols or strings, as the JSON parser symbolizes keys).
+      def from_meta(meta)
+        meta = meta || {}
+        KEYS.each_with_object({}) do |key, out|
+          value = meta[key] || meta[key.to_sym]
+          out[key] = value.to_s if value
+        end
+      end
+    end
+  end
+end

data/lib/ask/mcp/transport/sse.rb

@@ -3,6 +3,10 @@
 module Ask
   module MCP
     module Transport
+      # HTTP+SSE transport (2024-11-05). DEPRECATED since 2025-03-26 and
+      # reclassified as Deprecated under the MCP feature lifecycle in
+      # 2026-07-28 (SEP-2596). Keep working for legacy servers; new
+      # integrations should use StreamableHTTP instead.
       class SSE
         attr_reader :url
 
@@ -42,7 +46,7 @@ module Ask
           @http&.close
         end
 
-        def send(message)
+        def send(message, _headers = {})
           require "httpx"
 
           data = message.is_a?(String) ? message : message.to_json

data/lib/ask/mcp/transport/stdio.rb

@@ -50,7 +50,7 @@ module Ask
           # Process already exited
         end
 
-        def send(message)
+        def send(message, _headers = {})
           data = message.is_a?(String) ? message : message.to_json
           @mutex.synchronize do
             @stdin&.puts(data)

data/lib/ask/mcp/transport/streamable_http.rb

@@ -1,10 +1,28 @@
 # frozen_string_literal: true
 
+require "base64"
+
 module Ask
   module MCP
     module Transport
+      # Streamable HTTP transport (2026-07-28 shape).
+      #
+      # Every JSON-RPC message is its own HTTP POST to the single MCP
+      # endpoint. Each POST carries the mirrored request-metadata headers:
+      #   - MCP-Protocol-Version (matching the body's `_meta` protocolVersion)
+      #   - Mcp-Method (the JSON-RPC method)
+      #   - Mcp-Name (params.name / params.uri for tools/call, resources/read,
+      #     prompts/get)
+      # The server answers with either a single `application/json` object or
+      # an SSE stream scoped to the request; the client must handle both,
+      # chosen per response by Content-Type.
+      #
+      # Protocol-level sessions, the GET stream endpoint, and Last-Event-ID
+      # resumability were removed in 2026-07-28 and are not implemented.
       class StreamableHTTP
         attr_reader :url
+        # Set by the client after negotiation; sent as MCP-Protocol-Version.
+        attr_accessor :protocol_version
 
         def initialize(url, options = {})
           @url = url
@@ -12,7 +30,8 @@ module Ask
           @running = false
           @message_handlers = []
           @http = nil
-          @session_id = nil
+          @protocol_version = nil
+          @listen_thread = nil
         end
 
         def on_message(&block)
@@ -23,7 +42,7 @@ module Ask
           require "httpx"
 
           headers = { "Content-Type" => "application/json" }
-          headers["Accept"] = "text/event-stream" if @options[:stream]
+          headers["Accept"] = "application/json, text/event-stream"
           headers.merge!(@options[:headers]) if @options[:headers]
 
           @http = HTTPX.with(
@@ -36,21 +55,52 @@ module Ask
 
         def stop
           @running = false
+          @listen_thread&.kill
           @http&.close
         end
 
-        def send(message)
+        # Send a JSON-RPC message. `extra_headers` (e.g. Mcp-Param-* mirrored
+        # from tool parameters) are merged into the request metadata headers.
+        def send(message, extra_headers = {})
           data = message.is_a?(String) ? message : message.to_json
-
-          if @options[:stream]
-            send_streaming(data)
-          else
-            send_request_response(data)
-          end
+          headers = request_headers(message).merge(extra_headers)
+          response = @http.post(@url, body: data, headers: headers)
+          handle_response(response)
         rescue HTTPX::Error => e
           raise ConnectionError, "HTTP error: #{e.message}"
         end
 
+        # Open a long-lived notification stream via subscriptions/listen
+        # (2026-07-28). The response SSE stream stays open; delivered
+        # notifications (e.g. notifications/tools/list_changed,
+        # notifications/resources/updated) are passed to on_message handlers.
+        # The notifications filter is a Hash like
+        #   { toolsListChanged: true, resourceSubscriptions: ["uri"] }
+        # Close the stream by calling #close_listen or #stop.
+        def listen(notifications)
+          require "httpx"
+
+          request = Native::Messages::Request.new(
+            method: "subscriptions/listen",
+            params: { notifications: notifications },
+            id: @options[:listen_id] || 1
+          )
+          headers = request_headers(request)
+          response = @http.post(@url, body: request.to_json, headers: headers)
+
+          unless response.status == 200
+            raise ConnectionError, "HTTP #{response.status}: #{response.body.to_s[0..200]}"
+          end
+
+          @listen_thread = Thread.new { read_sse_stream(response) }
+          self
+        end
+
+        def close_listen
+          @listen_thread&.kill
+          @listen_thread = nil
+        end
+
         def running?
           @running
         end
@@ -59,45 +109,71 @@ module Ask
           stop
         end
 
+        # Encode a value for use as an HTTP header value per the spec: plain
+        # visible ASCII passes through; anything else (non-ASCII, control
+        # characters, leading/trailing whitespace, or a value matching the
+        # Base64 sentinel pattern) is encoded as =?base64?...?=.
+        def encode_header_value(value)
+          str = value.to_s
+          header_safe?(str) ? str : "=?base64?#{Base64.strict_encode64(str)}?="
+        end
+
         private
 
-        def send_request_response(data)
-          response = @http.post(@url, body: data)
+        def request_headers(message)
+          headers = { "Accept" => "application/json, text/event-stream" }
+
+          if message.is_a?(Native::Messages::Request) || message.is_a?(Native::Messages::Notification)
+            headers["Mcp-Method"] = message.method
+            headers["MCP-Protocol-Version"] = @protocol_version if @protocol_version
+            if %w[tools/call resources/read prompts/get].include?(message.method) && message.params
+              value = message.params[:name] || message.params[:uri] ||
+                      message.params["name"] || message.params["uri"]
+              headers["Mcp-Name"] = encode_header_value(value) if value
+            end
+          end
+
+          headers
+        end
+
+        def handle_response(response)
           status = response.status
+          if status == 202
+            # Notification accepted, no body.
+            return response
+          end
+          unless status == 200
+            raise ConnectionError, "HTTP #{status}: #{response.body.to_s[0..200]}"
+          end
 
-          if status == 200 || status == 202
+          content_type = response.headers["content-type"].to_s
+          if content_type.include?("text/event-stream")
+            read_sse_stream(response)
+          else
             body = response.body.to_s
             if body && !body.empty?
               message = Native::Messages::Parser.parse(body)
               @message_handlers.each { |handler| handler.call(message) }
             end
-          elsif status == 204
-            # No content — nothing to process
-          else
-            raise ConnectionError, "HTTP #{status}: #{response.body.to_s[0..200]}"
           end
 
           response
         end
 
-        def send_streaming(data)
-          response = @http.post(@url, body: data)
-
-          unless response.status == 200
-            raise ConnectionError, "HTTP #{response.status}: #{response.body.to_s[0..200]}"
-          end
-
+        # Read an SSE stream, delivering each `data:` payload as a parsed
+        # message. Lines beginning with a colon are SSE comments (keep-alive)
+        # and are ignored. Returns when the server closes the stream.
+        def read_sse_stream(response)
           buffer = +""
           response.body.each do |chunk|
             buffer << chunk
             while (line = buffer.slice!(/\A.*\n/))
               line = line.strip
-              next if line.empty?
+              next if line.empty? || line.start_with?(":")
 
               if line.start_with?("data: ")
-                data_line = line[6..]
                 begin
-                  message = Native::Messages::Parser.parse(data_line)
+                  message = Native::Messages::Parser.parse(line[6..])
                   @message_handlers.each { |handler| handler.call(message) }
                 rescue JSON::ParserError
                   # Skip non-JSON data lines
@@ -106,6 +182,12 @@ module Ask
             end
           end
         end
+
+        def header_safe?(str)
+          return false if str.start_with?("=?base64?") && str.end_with?("?=")
+          return false unless str == str.strip
+          str.each_char.all? { |c| c.ord >= 0x20 && c.ord <= 0x7E }
+        end
       end
     end
   end

data/lib/ask/mcp/validator.rb

@@ -19,7 +19,7 @@ module Ask
         string_schema = deep_stringify_keys(@schema)
         data = arguments.is_a?(Hash) ? deep_stringify_keys(arguments) : arguments
 
-        errors = JSON::Validator.fully_validate(string_schema, data)
+        errors = validate_with_dialect_fallback(string_schema, data)
         if errors.any?
           raise ValidationError, "Validation failed: #{errors.join(", ")}"
         end
@@ -36,6 +36,24 @@ module Ask
 
       private
 
+      # The json-schema gem implements drafts 1-7 but not JSON Schema 2020-12,
+      # which MCP 2025-11-25 declares as the default dialect. Most 2020-12
+      # schemas only use keywords shared with earlier drafts, so validating
+      # them still works — but the gem rejects the 2020-12 metaschema itself
+      # ("Schema not found: .../draft/2020-12/schema"). When a schema declares
+      # the 2020-12 dialect, strip the $schema key and retry.
+      def validate_with_dialect_fallback(schema, data)
+        JSON::Validator.fully_validate(schema, data)
+      rescue JSON::Schema::SchemaError, JSON::Schema::JsonParseError => e
+        if schema["$schema"].to_s.include?("2020-12")
+          cleaned = schema.dup
+          cleaned.delete("$schema")
+          JSON::Validator.fully_validate(cleaned, data)
+        else
+          raise e
+        end
+      end
+
       def deep_stringify_keys(obj)
         case obj
         when Hash

data/lib/ask/mcp/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module MCP
-    VERSION = "0.4.0"
+    VERSION = "0.4.2"
   end
 end