ask-mcp 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90e04370e4d5b1136abb513220b68beb46a5ca2c74d8f7ca694fa59297f8f32e
-  data.tar.gz: 17f2accea77cefc0ea51fedcc3879e219fff47760999b0ba39e0e168d30dbfe1
+  metadata.gz: 909c171336e0497c2377c2f4106e1ec0314adbbbf15791819caf6be0c9d04035
+  data.tar.gz: 5a5e95508499f38e310cce0052fcd4c9dfd2c95f8a4e965621c37d35c392293d
 SHA512:
-  metadata.gz: d8a481b9467e8f4d6d4d305da61346855f4d27ac94de77f109ac528e704599c18aee5a9c5deb64f7edb71a71b4e446cc1801149df21891d15eefdcb441eb1d09
-  data.tar.gz: b78ccc9a910fbfbeaf2e273ce6169279e4195624871f89356d6564ab6cd46380dd876951544e90b2f3b3b57328ae00180c6d218e1d66afa5416090c5703e1560
+  metadata.gz: 52526b46e9574fb4289ddde3b7ff340945eead680763ad7ece3903a8bea89a5a535cb3b9951b0236f6749808b22254c9f4b691133eff56e24a7438eb68ae8743
+  data.tar.gz: be8c62053892b8aa52e5216fcb58c7857ecfdff12b025173d9cd1be1a384cced8dd41ef4f9e17ca531fe6d869743dbc63caad275fbccb82014ddd4d94d49c3a2

data/CHANGELOG.md

@@ -1,37 +1,59 @@
-## [0.3.0] - 2026-06-26
+## [0.4.1] - 2026-07-31
 
 ### Changed
-- Renamed `Adapters::AskToolServer` → `Adapters::ToolServer` — the adapter is
-  now duck-typed and works with any Ruby object, not just Ask::Tool instances.
-- README fully rewritten: leads with a general-purpose duck-typed server example
-  instead of ask-tools-specific code. ask-rb integration is now a sub-section.
-- Gemspec description updated to reflect general-purpose positioning.
 
-## [0.2.0] - 2026-06-26
+- **`ToolServer` result wrapping** — plain `String` results are always treated
+  as success; result-like objects (`Ask::Result`, OpenStruct, etc.) use
+  `ok?`/`ok` and `output`/`error_message`; any other value is treated as
+  success with `to_s` used for the response.
+
+### Fixed
+
+- **Stdio server protocol version** — pins `PROTOCOL_VERSION` to
+  `2025-06-18` and echoes it back in the `initialize` response.
+
+## [0.4.0] - 2026-06-26
 
 ### Added
-- Server Runtime: `Ask::MCP::Server::Stdio` — run as an MCP server over stdio
-  with full initialize handshake, tool discovery, and tool call dispatch.
-- `Adapters::AskToolServer` — converts tools to MCP definitions and dispatches calls.
-- `Ask::MCP::Server.start_stdio` entry point for easy one-line server setup.
+- Request ID deduplication — retried `tools/call` with the same ID returns
+  cached result instead of re-executing the tool.
+- SIGTERM/SIGHUP graceful shutdown — closes stdin to unblock the read loop
+  so the current tool call can finish before the process exits.
+- Configurable `tool_timeout` option — prevents hung tool calls from
+  blocking the server indefinitely.
+- `ping` handler for MCP keepalive support.
+- 10 new tests: request dedup (3), tool timeout (2), SIGTERM (1),
+  multiline JSON safety (3), ping (1) — 180 total.
 
 ### Changed
-- 56 new tests across adapter, server stdio, integration, and start_stdio (170 total).
+- `Server::Stdio` now echoes back the client's requested protocol version
+  instead of hardcoding a value.
+
+## [0.3.0] - 2026-06-26
+
+### Changed
+- Renamed `Adapters::AskToolServer` → `Adapters::ToolServer` — duck-typed,
+  works with any Ruby object, not just Ask::Tool instances.
+- README rewritten to lead with general-purpose duck-typed server example.
+- ask-rb integration is now a documented sub-section.
+
+## [0.2.0] - 2026-06-26
+
+### Added
+- Server Runtime: `Ask::MCP::Server::Stdio` with full initialize handshake.
+- `Server.start_stdio` entry point for one-line server setup.
+- 56 new tests (170 total at time of release).
 
 ## [0.1.1] - 2026-06-25
 
 ### Changed
-- Major test expansion: Transport tests, MessagesParser, OAuth, Client, Server, Tool, Messages, integration. Rubocop, overcommit, CI matrix, SimpleCov.
+- Major test expansion across all modules.
 
 ## [0.1.0] - 2026-06-10
 
 ### Added
-- Core MCP client with full JSON-RPC 2.0 message layer
-- stdio, SSE, and Streamable HTTP transports
-- Tool, Resource, and Prompt data models
-- Client lifecycle, tool calling, resource reading, prompt retrieval
-- Token-based and OAuth 2.1 authentication
-- Ask::Tool adapter for ask-agent integration
-- Thread-safe request/response matching with configurable timeouts
-- Server-side notifications handling
-- Factory methods: `from_stdio`, `from_sse`, `from_http`, `connect`
+- Core MCP client with JSON-RPC 2.0 message layer.
+- stdio, SSE, and Streamable HTTP transports.
+- Tool, Resource, Prompt data models.
+- OAuth 2.1 and token-based authentication.
+- ask-agent integration via AskTool adapter.

data/lib/ask/mcp/adapters/tool_server.rb

@@ -8,28 +8,18 @@ module Ask
       # respond to +name+, +description+, +params_schema+, and +call(args)+ and
       # exposes them over MCP.
       #
-      # Usage:
-      #   class MyTool
-      #     def name; "hello" end
-      #     def description; "Says hello" end
-      #     def params_schema; nil end
-      #     def call(args = {}); OpenStruct.new(ok?: true, output: "Hello!") end
-      #   end
-      #
-      #   adapter = ToolServer.new([MyTool.new])
-      #   adapter.definitions  # => [{ name: "hello", ... }]
-      #   adapter.call("hello", {})  # => { content: [...], isError: false }
+      # Tools can return:
+      #   - An object responding to #ok?/#ok and #output/#error_message (Ask::Result style)
+      #   - A plain String (treated as success)
+      #   - Any other value (treated as success, .to_s is used for the response)
       class ToolServer
         attr_reader :tools
 
-        # @param tools [Array<#call, #name, #description, #params_schema>] tool instances to expose
         def initialize(tools = [])
           @tools = tools
           @tool_map = tools.each_with_object({}) { |t, h| h[t.name] = t }
         end
 
-        # MCP tool definitions for tools/list
-        # @return [Array<Hash>]
         def definitions
           @tools.map do |tool|
             schema = tool.params_schema || { type: "object", properties: {}, required: [] }
@@ -41,10 +31,6 @@ module Ask
           end
         end
 
-        # Call a tool and wrap the result in MCP format
-        # @param name [String] tool name
-        # @param arguments [Hash] arguments (may have symbol or string keys)
-        # @return [Hash] { content: [...], isError: true/false }
         def call(name, arguments = {})
           tool = @tool_map[name]
           unless tool
@@ -64,18 +50,31 @@ module Ask
         private
 
         def wrap_result(result)
-          if result.respond_to?(:ok?) ? result.ok? : result.ok
-            output = result.respond_to?(:output) ? result.output : result.to_s
-            text = output.is_a?(Hash) ? (output[:summary] || output.to_s) : output.to_s
-            { content: [{ type: "text", text: text }], isError: false }
-          else
-            msg = result.respond_to?(:error_message) ? result.error_message : result.to_s
-            { content: [{ type: "text", text: "Error: #{msg}" }], isError: true }
+          # Plain strings are always a success
+          if result.is_a?(String)
+            return { content: [{ type: "text", text: result }], isError: false }
+          end
+
+          # Result-like objects (Ask::Result, OpenStruct, etc.)
+          if result.respond_to?(:ok?) || result.respond_to?(:ok)
+            ok = result.respond_to?(:ok?) ? result.ok? : result.ok
+            return success_result(result, ok) if ok
+            return error_result(result.respond_to?(:error_message) ? result.error_message : result.to_s)
           end
+
+          # Everything else — treat as success
+          text = result.is_a?(Hash) ? (result[:summary] || result.to_s) : result.to_s
+          { content: [{ type: "text", text: text }], isError: false }
+        end
+
+        def success_result(result, _ok)
+          output = result.respond_to?(:output) ? result.output : result.to_s
+          text = output.is_a?(Hash) ? (output[:summary] || output.to_s) : output.to_s
+          { content: [{ type: "text", text: text }], isError: false }
         end
 
         def error_result(message)
-          { content: [{ type: "text", text: message }], isError: true }
+          { content: [{ type: "text", text: "Error: #{message}" }], isError: true }
         end
 
         def deep_stringify_keys(obj)

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

@@ -1,70 +1,81 @@
 # frozen_string_literal: true
 
 require "json"
+require "timeout"
 
 module Ask
   module MCP
     class Server
       # MCP server over stdio transport.
-      #
-      # Reads JSON-RPC 2.0 messages from stdin and writes responses to stdout.
-      # Designed to be spawned as a child process by MCP clients (Codex Desktop,
-      # Claude Code, etc.) with command/args config.
-      #
-      # Usage:
-      #   Server::Stdio.new(name: "my-server", tools: my_tools).start
-      #
       class Stdio
-        PROTOCOL_VERSION = "0.1.0"
+        MAX_RESULT_CACHE = 100
+        PROTOCOL_VERSION = "2025-06-18"
 
         attr_reader :name, :tools, :capabilities, :resources, :prompts
 
-        def initialize(name:, tools: [], capabilities: {}, resources: {}, prompts: {}, debug: false)
+        def initialize(name:, tools: [], capabilities: {}, resources: {}, prompts: {},
+                       debug: false, tool_timeout: nil)
           @name = name
           @capabilities = capabilities
           @resources = resources
           @prompts = prompts
           @debug = debug
+          @tool_timeout = tool_timeout
 
           @adapter = Adapters::ToolServer.new(tools || [])
           @initialized = false
           @running = false
+          @shutdown_requested = false
+          @result_cache = {}
         end
 
-        # Start the server (blocking). Processes stdin until EOF.
         def start
           @running = true
           $stdout.sync = true
 
+          # Graceful shutdown: on TERM/HUP, set flag and close stdin to
+          # unblock the read loop so the current tool call can finish.
+          trap("TERM") { graceful_shutdown }
+          trap("HUP")  { graceful_shutdown }
+
           debug_log "Server starting: #{@name} (PID #{Process.pid})"
           debug_log "Tools: #{@adapter.definitions.map { |d| d[:name] }.join(', ')}"
 
-          while @running && (line = $stdin.gets)
+          while @running && !@shutdown_requested && (line = $stdin.gets)
             line = line.strip
             next if line.empty?
-
             process_line(line)
           end
 
           debug_log "stdin closed — exiting"
         rescue Errno::EBADF, IOError
-          # stdin closed externally
+          # stdin closed externally (e.g. from trap handler)
+        rescue SignalException
+          # SIGTERM or SIGHUP during blocked read
         ensure
           @running = false
+          @shutdown_requested = false
+          trap("TERM", "DEFAULT")
+          trap("HUP", "DEFAULT")
         end
 
-        # Stop the server (non-blocking, closes stdin to unblock the read loop).
         def stop
           @running = false
         end
 
-        # Is the server still running?
         def running?
           @running
         end
 
         private
 
+        def graceful_shutdown
+          @shutdown_requested = true
+          # Close stdin to unblock $stdin.gets so the signal handler
+          # returns promptly and the process exits cleanly.
+          $stdin.close rescue nil
+        end
+
         def process_line(line)
           msg = JSON.parse(line, symbolize_names: true)
           handle_message(msg)
@@ -90,17 +101,20 @@ module Ask
           when "tools/call"
             return send_error(id, -32000, "Server not initialized") unless @initialized
             handle_tool_call(id, params)
+          when "ping"
+            send_result(id, {}) if has_id
           else
             debug_log "Unknown method: #{method}"
             send_error(id, -32601, "Method not found: #{method}") if has_id
           end
         end
 
-        def handle_initialize(id, _params)
+        def handle_initialize(id, params)
           @initialized = true
-          debug_log "Handling initialize (id=#{id.inspect})"
+          client_version = params[:protocolVersion] || PROTOCOL_VERSION
+          debug_log "Handling initialize (id=#{id.inspect}, version=#{client_version})"
           send_result(id, {
-            protocolVersion: PROTOCOL_VERSION,
+            protocolVersion: client_version,
             capabilities: @capabilities,
             serverInfo: {
               name: @name,
@@ -111,20 +125,41 @@ module Ask
         end
 
         def handle_tools_list(id)
-          debug_log "Handling tools/list (id=#{id.inspect})"
           defs = @adapter.definitions
           debug_log "tools/list returning #{defs.length} tool definitions"
           send_result(id, { tools: defs })
         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 = @adapter.call(tool_name, arguments)
+          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
 
         def send_result(id, result)
@@ -140,6 +175,11 @@ module Ask
           ts = Time.now.strftime("%H:%M:%S.%L")
           $stderr.puts "[#{ts}] [ask-mcp] #{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

data/lib/ask/mcp/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module MCP
-    VERSION = "0.3.0"
+    VERSION = "0.4.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-mcp
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Kaka Ruto