ask-mcp 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01bf6655c874ece6be6c44d5864e19c844f7edd1fa88c8f90b60b836092bcd90
-  data.tar.gz: 2cebafa8dd9d36901b5e78e81350c235ef837f1d4a010792f6c7d23982729969
+  metadata.gz: ae155e99332cb2a3fcec6b65c6d0ac20aa9b2b81b27f1e3aa3c667dc0c7a42fb
+  data.tar.gz: af84c5f5aae82c640e2c12316cde40444fe7733d6ad5aaddd6780242b98e1a1c
 SHA512:
-  metadata.gz: 292a26a5c625cd6e1b06d214ce5b3cd9e38a7562f8e388b8d2817ee4fc915d6f743301c23466c03d2f5e5f3399607a02ca07c2c32bc179696cb1c71386609d5c
-  data.tar.gz: 9c6395fbae61b1013fb72013dfd3d069f76956ad25efd88c62444b3f6c33823462a01c4cb91b129f1a7001a5fef3d7580b91986391128aea41b33c253221afda
+  metadata.gz: 62f473ff0fdc35b25adcdadf3aeb2a65c330767f7b73cc85bed204a32bff7fcc28f0348c2ee3f8e8ae1e3d7eaf3977714af67d67038c1be990d9feca2199d81f
+  data.tar.gz: e511364526282fcb429740dbd65bbce3e51d0bde06a06cb672e33a0c30b1b09e1971c663145f1b272d7e01015060349447bb7d53081b8dd9813dea02f19591e9

data/CHANGELOG.md

@@ -1,40 +1,45 @@
-## [0.2.0] - 2026-06-26
+## [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.
-- `Ask::MCP::Adapters::AskToolServer` — converts `Ask::Tool` instances to MCP
-  tool definitions and dispatches calls, enabling any Ask::Tool to be exposed
-  via MCP without modification.
-- `Ask::MCP::Server.start_stdio` entry point for easy one-line server setup.
-- `examples/` — reference usage in README "Running as an MCP Server" section.
+- 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
+- `Server::Stdio` now echoes back the client's requested protocol version
+  instead of hardcoding a value.
+
+## [0.3.0] - 2026-06-26
 
 ### Changed
-- Server Runtime adds 56 new tests across adapter, server stdio, integration,
-  and start_stdio entry point (170 total, up from 114).
-- `ask-mcp` gem description updated to reflect client + server capabilities.
-- Architecture section updated to include server/ and adapters/ask_tool_server.rb.
+- 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 (SSE/Stdio/StreamableHTTP), MessagesParser, OAuth, Client(17t with cache invalidation), Server(7t), Tool(8t), Messages(17t with serialization), integration tests(7t with mock server). Infrastructure: rubocop, overcommit, CI matrix, gemspec, 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 transport for local process MCP servers
-- SSE transport for remote Server-Sent Events MCP servers
-- Streamable HTTP transport for remote HTTP MCP servers
-- Tool, Resource, and Prompt data models with `from_h`/`to_h` serialization
-- Client lifecycle: initialize, capabilities discovery, session management
-- Tool calling, resource reading, and prompt retrieval
-- Token-based authentication (Bearer/Basic)
-- OAuth 2.1 authentication (client credentials + authorization code flows)
-- Ask::Tool adapter for integration with ask-agent
-- Thread-safe request/response matching with configurable timeouts
-- Server-side notifications handling (tools/resources/prompts list changed)
-- Comprehensive test suite with mock MCP server
-- Factory methods: `from_stdio`, `from_sse`, `from_http`, `connect`
-- Ability to cache or bypass caching for tools/resources/prompts
+- 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/README.md

@@ -2,9 +2,10 @@
 
 [![Gem Version](https://badge.fury.io/rb/ask-mcp.svg)](https://badge.fury.io/rb/ask-mcp)
 
-**Model Context Protocol (MCP) client for Ruby.** Connect to MCP servers via
-stdio, SSE, or Streamable HTTP transports. Discover tools, resources, and
-prompts. Supports the full MCP protocol with OAuth 2.1 authentication.
+**Model Context Protocol (MCP) client and server for Ruby.** Connect to MCP
+servers via stdio, SSE, or Streamable HTTP transports. Run as an MCP server
+to expose your own tools to any MCP client. No framework lock-in — just
+implement a couple of duck-typed methods and you're done.
 
 MCP is the industry standard for LLM tool discovery — the same protocol used by
 Claude Code, Codex, Cursor, and GitHub Copilot.
@@ -21,44 +22,49 @@ Or add to your Gemfile:
 gem "ask-mcp", "~> 0.1.0"
 ```
 
-## Quick Start
+## Quick Start — Client
+
+Connect to any MCP server and call its tools:
 
 ```ruby
 require "ask/mcp"
 
-# Connect to a local MCP server via stdio
 client = Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
 client.start
 
-# List available tools
 client.tools.each { |name, tool| puts "#{name}: #{tool.description}" }
 
-# Call a tool
 result = client.call_tool("read_file", path: "/tmp/test.txt")
 puts result
 
-# Clean up
 client.stop
 ```
 
+## Quick Start — Server
 
-## Running as an MCP Server
-
-`ask-mcp` can run as a standalone MCP server over stdio, exposing any
-`Ask::Tool` instances to MCP-compatible clients (Codex Desktop, Claude Code, etc.).
+Run as a standalone MCP server exposing your own tools to any MCP client
+(Codex, Claude Code, Cursor, etc.). Any object that responds to `name`,
+`description`, `params_schema`, and `call(args)` will work:
 
 ```ruby
 require "ask/mcp"
-require "ask-tools-shell"
-require "ask-web-search"
 
-tools = Ask::Tools::Shell::TOOLS.map(&:new)
-tools << Ask::Tools::WebSearch.new
+# Define your tools — no base class needed, just duck typing
+class Greeter
+  def name; "greet" end
+  def description; "Greets someone by name" end
+  def params_schema
+    { type: "object", properties: { "name" => { "type" => "string" } }, required: ["name"] }
+  end
+  def call(args = {})
+    "Hello, #{args['name']}!"
+  end
+end
 
+# Start the server (blocking — runs until stdin closes)
 Ask::MCP::Server.start_stdio(
   name: "my-server",
-  tools: tools,
-  capabilities: { tools: {} }
+  tools: [Greeter.new]
 )
 ```
 
@@ -69,14 +75,58 @@ Configure your MCP client:
   "mcpServers": {
     "my-server": {
       "command": "ruby",
-      "args": ["path/to/your/script.rb"]
+      "args": ["/path/to/your/server.rb"]
     }
   }
 }
 ```
 
-For a production example, see [llm-proxy](https://github.com/ask-rb/llm-proxy)
-which embeds the same server and adds rate limiting, auth, and monitoring.
+Tools can return any value the client can use. The server automatically wraps
+the result into MCP's `content` array format.
+
+### What about complex tools?
+
+The result object from `call(args)` should respond to `ok?` (or `ok`) and
+`output` / `error_message`. Use `OpenStruct` for simple cases:
+
+```ruby
+require "ostruct"
+
+class BashTool
+  def name; "bash" end
+  def description; "Run a shell command" end
+  def params_schema
+    { type: "object", properties: { "command" => { "type" => "string" } }, required: ["command"] }
+  end
+  def call(args = {})
+    output = `#{args['command']} 2>&1`
+    OpenStruct.new(ok?: true, output: output)
+  rescue => e
+    OpenStruct.new(ok?: false, error_message: e.message)
+  end
+end
+```
+
+For a production example with shell tools, file ops, and web search,
+see [llm-proxy](https://github.com/ask-rb/llm-proxy).
+
+### Using with ask-tools
+
+If you use the ask-rb ecosystem, you can expose Ask::Tool subclasses directly:
+
+```ruby
+require "ask/mcp"
+require "ask-tools-shell"
+require "ask-web-search"
+
+tools = Ask::Tools::Shell::TOOLS.map(&:new) + [Ask::Tools::WebSearch.new]
+
+Ask::MCP::Server.start_stdio(
+  name: "my-server",
+  tools: tools,
+  capabilities: { tools: {} }
+)
+```
 
 ## Transports
 
@@ -183,7 +233,6 @@ wrapped = Ask::MCP::Adapters::AskTool.wrap(client.tools)
 wrapped.each { |name, adapter| agent.register_tool(adapter.to_ask_tool) }
 ```
 
-
 ## Architecture
 
 ```
@@ -205,8 +254,9 @@ ask-mcp/
 │   └── token.rb                           # Token-based auth
 └── lib/ask/mcp/adapters/
     ├── ask_tool.rb                        # MCP::Tool → Ask::Tool adapter
-    └── ask_tool_server.rb                 # Ask::Tool → MCP server adapter (reverse)
+    └── tool_server.rb                     # Duck-typed tools → MCP server adapter
 ```
+
 ## Development
 
 ```bash

data/lib/ask/mcp/adapters/{ask_tool_server.rb → tool_server.rb}

@@ -3,19 +3,26 @@
 module Ask
   module MCP
     module Adapters
-      # Converts Ask::Tool instances into MCP tool definitions and dispatches
-      # calls. This is the server-direction adapter — it takes Ask::Tool objects
-      # (from tool packs like ask-tools-shell) and makes them available over MCP.
+      # Converts duck-typed tool objects into MCP tool definitions and dispatches
+      # calls. This is the server-direction adapter — it takes any objects that
+      # respond to +name+, +description+, +params_schema+, and +call(args)+ and
+      # exposes them over MCP.
       #
       # Usage:
-      #   adapter = AskToolServer.new(Ask::Tools::Shell.all)
-      #   adapter.definitions  # => [{ name: "bash", description: "...", inputSchema: {...} }]
-      #   adapter.call("bash", { command: "echo hi" })  # => { content: [...], isError: ... }
-      class AskToolServer
+      #   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 }
+      class ToolServer
         attr_reader :tools
 
-        # @param tools [Array<#call, #name, #description, #params_schema>] tool instances to expose.
-        #   Each tool must respond to name, description, params_schema, and call(args).
+        # @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 }
@@ -44,12 +51,10 @@ module Ask
             return error_result("Tool not found: #{name}")
           end
 
-          # Stringify keys — Ask::Tool subclasses expect string keys
           normalized = deep_stringify_keys(arguments)
           result = tool.call(normalized)
           wrap_result(result)
         rescue StandardError => e
-          # If the tool raised Ask::Tool::Halt, treat it as a success
           if defined?(Ask::Tool::Halt) && e.is_a?(Ask::Tool::Halt)
             return { content: [{ type: "text", text: e.content.to_s }], isError: false }
           end

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

@@ -1,70 +1,80 @@
 # 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
 
         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::AskToolServer.new(tools || [])
+          @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 +100,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 +124,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 +174,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.2.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/ask/mcp.rb

@@ -28,7 +28,7 @@ module Ask
 
     module Adapters
       autoload :AskTool, "ask/mcp/adapters/ask_tool"
-      autoload :AskToolServer, "ask/mcp/adapters/ask_tool_server"
+      autoload :ToolServer, "ask/mcp/adapters/tool_server"
     end
 
     class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-mcp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -80,8 +80,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 description: Connect to MCP servers via stdio, SSE, and Streamable HTTP transports.
-  Run as an MCP server to expose Ask::Tool instances. Discover tools, resources, and
-  prompts. OAuth 2.1 authentication.
+  Run as an MCP server exposing any Ruby object as a tool. Discover tools, resources,
+  and prompts. OAuth 2.1 authentication.
 email:
 - kaka@myrrlabs.com
 executables: []
@@ -95,7 +95,7 @@ files:
 - lib/ask-mcp.rb
 - lib/ask/mcp.rb
 - lib/ask/mcp/adapters/ask_tool.rb
-- lib/ask/mcp/adapters/ask_tool_server.rb
+- lib/ask/mcp/adapters/tool_server.rb
 - lib/ask/mcp/auth/oauth.rb
 - lib/ask/mcp/auth/token.rb
 - lib/ask/mcp/client.rb