ask-mcp 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d29dde6a951c940e97933e666e97f5df75483b9de280be3fcabcb184fd5e6091
-  data.tar.gz: 27cb99a853ae2daabb8f38910e8f14373d0af7d0c3f99ff79f054ed8a88c38bd
+  metadata.gz: b2b34899f61be9226b77f6e212d5756555c86e52e17ba301fcf3eaa24f1d3a62
+  data.tar.gz: 51656c01a274744d51bb328d11f0f9dc84ac6f20fbe7fa5bb0b90125e670a2d3
 SHA512:
-  metadata.gz: ccfaa454b590f534bf0b91aa73c6a13894d4b9fd029a95ac4239ef00bcc29d0a0bf56cee54f2a1f1c941104d7f95b4d60e8d2c3ac235d0b3c1b4949b34a1428c
-  data.tar.gz: 40da8189f319185ea90e8e1a8cf8bed64aee140ce182fa439c8985f548878a44289f1ee95d48ca043928f97a85c24d460815e0deff8d7188f37e2b089de02237
+  metadata.gz: baec4cee8a4bdd42174107b545e0c7a144dd7a646f64e37f3ed09d3f57826a417a1a801ec5f06fc8aed7119a9357c41f524549e62b5c0446e756ebbd5df0171c
+  data.tar.gz: dfaddecd4733e04fa5fbac5ee68ae95031cf4e3111a9db7237170ac7601f261ddb25f7f82eab41f478a2aa010aa9c31c92ca385b2b41d4e615cf628363e43578

data/CHANGELOG.md

@@ -7,6 +7,18 @@
   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.
 
+- **`Ask::MCP::RuntimeExecutor`** — bridges MCP clients into the
+  `Ask::Runtime::ToolExecutor` interface. Wraps an `Ask::MCP::Client`,
+  implements `#execute(tool_call, context:)`, normalizes MCP content/result
+  shapes (array, hash, string, nil) into `ToolResult.success` or `failure`,
+  honors context cancellation before calling the client, and emits
+  `ToolStarted` / `ToolCompleted` / `ToolFailed` / `ToolCancelled` lifecycle
+  events via `context.event_sink` with terminal snapshots.
+
+- **`Ask::MCP::ToolDiscovery`** module — helper for discovering MCP tools
+  from a client and wrapping them as `Adapters::AskTool` or
+  `Ask::Tools::Tool` instances.
+
 ## [0.5.0] - 2026-09-17
 
 ### Added

data/README.md

@@ -161,6 +161,8 @@ annotations are excluded from `tools/list` on HTTP transports.
 | `server.notify_*_list_changed` | Emit change notifications to clients |
 | `Ask::MCP::Adapters::AskTool.wrap(tools_hash)` | Adapter from MCP tools to `Ask::Tool` instances for ask-agent |
 | `Ask::MCP::Adapters::ToolServer` | Adapter from duck-typed tools to MCP server tools |
+| `Ask::MCP::RuntimeExecutor.new(client)` | Bridge MCP client into `Ask::Runtime::ToolExecutor` |
+| `Ask::MCP::ToolDiscovery` | Discover MCP tools and wrap them as `AskTool` adapters |
 | `Ask::MCP::Auth::Token.new(token)` | Token-based auth (`apply(headers)`) |
 | `Ask::MCP::Auth::OAuth.new(client_id:, ...)` | OAuth for MCP; `discover!` (OIDC), `authenticate!`, `validate_iss!`, `apply(headers)` |
 | `Ask::MCP::Auth::ClientIdMetadataDocument` | Build/validate Client ID Metadata Documents (2026-07-28 client registration) |
@@ -188,6 +190,32 @@ wrapped.each { |name, adapter| agent.register_tool(adapter.to_ask_tool) }
 
 Expose `Ask::Tool` subclasses as an MCP server with `Ask::MCP::Server.start_stdio(name:, tools:, capabilities: { tools: {} })`; the `ToolServer` adapter handles them.
 
+### With ask-runtime
+
+Bridge an MCP client into `Ask::Runtime` tool-call pipelines:
+
+```ruby
+require "ask/mcp"
+require "ask/runtime"
+
+client = Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
+client.start
+
+executor = Ask::MCP::RuntimeExecutor.new(client)
+
+# Build a tool call and context
+call = Ask::Runtime::ToolCall.new(tool_name: "read_file", input: { path: "/tmp/test.txt" })
+ctx = Ask::Runtime::ExecutionContext.new(session_id: "s1", turn: 1)
+
+result = executor.execute(call, context: ctx)
+result.success?  # => true
+result.output    # => file contents
+
+# Discover and wrap tools for integration
+include Ask::MCP::ToolDiscovery
+tools = mcp_tools(client)   # => Hash{String => Adapters::AskTool}
+```
+
 ## Full documentation
 
 The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.

data/lib/ask/mcp/runtime_executor.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "ask/runtime"
+
+module Ask
+  module MCP
+    # Bridges an MCP Client into the Ask::Runtime::ToolExecutor interface.
+    #
+    # Wraps an Ask::MCP::Client and implements the execute() contract so that
+    # MCP tools can participate in Ask::Runtime tool-call pipelines.
+    #
+    #   executor = Ask::MCP::RuntimeExecutor.new(client)
+    #   result = executor.execute(tool_call, context: ctx)
+    #
+    # Responsibilities:
+    # - Delegates to client.call_tool(tool_call.tool_name, tool_call.input)
+    # - Normalizes MCP content/result shapes into ToolResult.success or failure
+    # - Honors context cancellation before calling the client
+    # - Emits ToolStarted / ToolCompleted / ToolFailed / ToolCancelled events
+    #   via context.event_sink with terminal snapshots
+    #
+    # Error handling:
+    # - MCP isError responses → ToolResult.failure
+    # - Client exceptions (ProtocolError, ConnectionError) → ToolResult.failure
+    # - Malformed/empty results → ToolResult.success with nil output
+    #
+    class RuntimeExecutor
+      include Ask::Runtime::ToolExecutor
+
+      # @param client [Ask::MCP::Client] an initialized MCP client
+      def initialize(client)
+        @client = client
+      end
+
+      # @return [Ask::MCP::Client] the underlying MCP client
+      attr_reader :client
+
+      # Create a RuntimeExecutor from a client.
+      #
+      # @param client [Ask::MCP::Client] an initialized MCP client
+      # @return [RuntimeExecutor]
+      def self.from_client(client)
+        new(client)
+      end
+
+      # Execute a tool call via the MCP client.
+      #
+      # @param tool_call [Ask::Runtime::ToolCall] the tool-call request
+      # @param context [Ask::Runtime::ExecutionContext, nil] execution context
+      # @return [Ask::Runtime::ToolResult] normalized result
+      def execute(tool_call, context: nil)
+        context ||= Ask::Runtime::ExecutionContext.new
+
+        started_call = transition(tool_call, :running, started_at: Time.now)
+        emit_event(Ask::Runtime::Events::ToolStarted,
+                    tool_call: started_call, execution_context: context)
+
+        return cancel(tool_call, context, "Cancelled before execution") if context.cancelled?
+
+        result = call_tool(tool_call)
+        return cancel(tool_call, context, "Cancelled during execution") if context.cancelled?
+
+        finished_at = Time.now
+        duration = finished_at - started_call.started_at
+
+        terminal_call = started_call.with(
+          state: result.success? ? :completed : :failed,
+          tool_result: result,
+          finished_at: finished_at
+        )
+
+        event_class = result.success? ? Ask::Runtime::Events::ToolCompleted : Ask::Runtime::Events::ToolFailed
+        emit_event(event_class,
+                    tool_call: terminal_call, tool_result: result,
+                    execution_context: context, duration: duration)
+
+        result_with_duration(result, duration)
+      end
+
+      private
+
+      def call_tool(tool_call)
+        response = @client.call_tool(tool_call.tool_name, tool_call.input)
+        normalize_result(response)
+      rescue Ask::MCP::Error, Ask::MCP::ConnectionError => e
+        Ask::Runtime::ToolResult.failure(e.message)
+      rescue => e
+        Ask::Runtime::ToolResult.failure("#{e.class}: #{e.message}")
+      end
+
+      # Normalize MCP tools/call response shapes into a ToolResult.
+      #
+      # MCP responses are one of:
+      #   Array  — [{ type: "text", text: "..." }, ...]
+      #   Hash   — { content: [...], isError: bool, ... }
+      #   String — plain text (some servers)
+      #   nil    — empty response
+      def normalize_result(response)
+        error = error?(response)
+        output = extract_output(response)
+
+        if error
+          msg = extract_error_message(response) ||
+                (output.is_a?(String) ? output : nil) ||
+                "MCP tool error"
+          Ask::Runtime::ToolResult.failure(msg)
+        else
+          Ask::Runtime::ToolResult.success(data: output)
+        end
+      end
+
+      def extract_output(response)
+        case response
+        when Array
+          extract_from_content_array(response)
+        when Hash
+          if response[:content] || response["content"]
+            extract_from_content_array(response[:content] || response["content"])
+          else
+            response
+          end
+        when String
+          response
+        when nil
+          nil
+        else
+          response.to_s
+        end
+      end
+
+      def extract_from_content_array(array)
+        return nil if array.nil? || array.empty?
+
+        if array.length == 1
+          item = array.first
+          if item.is_a?(Hash) && (item[:text] || item["text"])
+            return item[:text] || item["text"]
+          end
+          return array
+        end
+
+        texts = array.filter_map do |item|
+          item.is_a?(Hash) ? (item[:text] || item["text"]) : item&.to_s
+        end
+        texts.length == array.length ? texts.join("\n") : array
+      end
+
+      def error?(response)
+        return false unless response.is_a?(Hash)
+
+        response[:isError] || response["isError"]
+      end
+
+      def extract_error_message(response)
+        return unless response.is_a?(Hash)
+
+        content = response[:content] || response["content"]
+        return unless content.is_a?(Array) && content.any?
+
+        first = content.first
+        first[:text] || first["text"] if first.is_a?(Hash)
+      end
+
+      def cancel(tool_call, context, reason)
+        result = Ask::Runtime::ToolResult.cancelled(reason)
+        terminal_call = tool_call.with(
+          state: :cancelled,
+          tool_result: result,
+          finished_at: Time.now
+        )
+        duration = terminal_call.finished_at - terminal_call.created_at
+
+        emit_event(Ask::Runtime::Events::ToolCancelled,
+                    tool_call: terminal_call, tool_result: result,
+                    execution_context: context, duration: duration)
+
+        result
+      end
+
+      def transition(tool_call, state, **attrs)
+        tool_call.with(state: state, **attrs)
+      end
+
+      def result_with_duration(result, duration)
+        return result if result.duration == duration
+
+        Ask::Runtime::ToolResult.new(
+          result: result.result,
+          outcome: result.outcome,
+          duration: duration
+        )
+      end
+
+      def emit_event(event_class, **args)
+        timestamp = Time.now
+        event = event_class.new(**args, timestamp: timestamp)
+        sink = args[:execution_context].event_sink
+        event_type = event_class.name.split("::").last
+                     .gsub(/([a-z])([A-Z])/, '\1_\2')
+                     .downcase
+                     .to_sym
+        sink.emit(event_type, event: event)
+      rescue => e
+        warn "[ask-mcp][runtime_executor] event emission failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ask/mcp/tool_discovery.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ask
+  module MCP
+    # Helpers for discovering MCP tools and exposing them as Ask::Tool wrappers.
+    #
+    #   include Ask::MCP::ToolDiscovery
+    #   tools = mcp_tools(client)  # => Hash{String => Adapters::AskTool}
+    #
+    module ToolDiscovery
+      # Discover tools from an MCP client and wrap them as AskTool adapters.
+      #
+      # @param client [Ask::MCP::Client] an initialized MCP client
+      # @return [Hash{String => Adapters::AskTool}] tools keyed by name
+      def mcp_tools(client)
+        tools = client.tools
+        Adapters::AskTool.wrap(tools)
+      end
+
+      # Discover tools and convert them to Ask::Tools::Tool instances.
+      #
+      # @param client [Ask::MCP::Client] an initialized MCP client
+      # @return [Hash{String => Ask::Tools::Tool}] tools keyed by name
+      def mcp_ask_tools(client)
+        mcp_tools(client).transform_values(&:to_ask_tool)
+      end
+    end
+  end
+end

data/lib/ask/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module MCP
-    VERSION = "0.6.0"
+    VERSION = "0.6.1"
   end
 end

data/lib/ask/mcp.rb

@@ -24,6 +24,8 @@ module Ask
     autoload :Validator, "ask/mcp/validator"
     autoload :XMcpHeader, "ask/mcp/x_mcp_header"
     autoload :TraceContext, "ask/mcp/trace_context"
+    autoload :RuntimeExecutor, "ask/mcp/runtime_executor"
+    autoload :ToolDiscovery, "ask/mcp/tool_discovery"
 
     module Native
       autoload :Messages, "ask/mcp/native/messages"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-mcp
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -93,6 +93,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: ask-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+- !ruby/object:Gem::Dependency
+  name: ask-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 description: Connect to MCP servers via stdio, SSE, and Streamable HTTP transports.
   Run as an MCP server exposing any Ruby object as a tool. Discover tools, resources,
   and prompts. OAuth 2.1 authentication.
@@ -119,11 +147,13 @@ files:
 - lib/ask/mcp/native/messages.rb
 - lib/ask/mcp/prompt.rb
 - lib/ask/mcp/resource.rb
+- lib/ask/mcp/runtime_executor.rb
 - lib/ask/mcp/server.rb
 - lib/ask/mcp/server/core.rb
 - lib/ask/mcp/server/http.rb
 - lib/ask/mcp/server/stdio.rb
 - lib/ask/mcp/tool.rb
+- lib/ask/mcp/tool_discovery.rb
 - lib/ask/mcp/trace_context.rb
 - lib/ask/mcp/transport/sse.rb
 - lib/ask/mcp/transport/stdio.rb