phronomy 0.12.0 → 0.14.0

data/lib/phronomy/tools/mcp.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
-require "net/http"
-require "open3"
-require "securerandom"
+require "mcp"
 require "shellwords"
 require "uri"
 
@@ -12,44 +10,73 @@ module Phronomy
     # A Phronomy::Agent::Context::Capability::Base subclass that wraps a tool exposed by an external
     # MCP (Model Context Protocol) server.
     #
+    # Uses the official MCP Ruby SDK v1.x for transport handling, which provides
+    # the MCP initialize handshake, HTTP/SSE parsing, and request cancellation.
+    #
     # Supports two transport schemes:
-    # - <b>"stdio://\<command\>"</b> — spawns a child process that communicates via
-    #   newline-delimited JSON-RPC on stdin/stdout.
-    # - <b>"http://\<url\>"</b> / <b>"https://\<url\>"</b> — connects to a running
-    #   HTTP/SSE MCP server using +net/http+.
+    # - <b>"stdio://\<command\>"</b> — spawns a child process via MCP::Client::Stdio.
+    # - <b>"http://\<url\>"</b> / <b>"https://\<url\>"</b> — connects via MCP::Client::HTTP.
+    #
+    # Each generated tool instance owns one MCP client. Calls, reconnects, and
+    # explicit close operations are serialized because the SDK's stdio transport
+    # does not support concurrent response readers.
     #
     # @example
     #   web_search = Phronomy::Tools::Mcp.from_server(
     #     "stdio://./mcp-server",
     #     tool_name: "search_web"
     #   )
-    #   agent = MyAgent.new
     #   agent_class.tools(web_search)
     class Mcp < Phronomy::Agent::Context::Capability::Base
+      SUPPORTED_SCHEMA_DIALECTS = [
+        "https://json-schema.org/draft/2020-12/schema",
+        "https://json-schema.org/draft/2020-12/schema#"
+      ].freeze
+      SUPPORTED_ROOT_KEYS = %w[$schema type properties required title description additionalProperties].freeze
+      SUPPORTED_PROPERTY_KEYS = %w[type description enum title].freeze
+      IGNORED_PROPERTY_KEYS = %w[
+        minimum maximum exclusiveMinimum exclusiveMaximum multipleOf
+        minLength maxLength pattern format default examples
+      ].freeze
+      SUPPORTED_TYPES = %w[string integer number boolean].freeze
+      MCP_CLEANUP_POOL_SIZE = 2
+      MCP_CLEANUP_QUEUE_SIZE = 100
+
+      private_constant :SUPPORTED_SCHEMA_DIALECTS,
+        :SUPPORTED_ROOT_KEYS,
+        :SUPPORTED_PROPERTY_KEYS,
+        :IGNORED_PROPERTY_KEYS,
+        :SUPPORTED_TYPES,
+        :MCP_CLEANUP_POOL_SIZE,
+        :MCP_CLEANUP_QUEUE_SIZE
+
       class << self
         # Build a Mcp instance by querying a running MCP server for the
         # tool definition identified by +tool_name+.
         #
+        # +additionalProperties+ omitted from the remote schema is accepted, but
+        # Phronomy still exposes and accepts only parameters declared in +properties+.
+        #
         # @param server_uri [String] URI of the MCP server.
-        #   Supported schemes:
-        #   - "stdio://<command>"  — spawn a child process
-        #   - "http://<url>" / "https://<url>" — connect to an HTTP/SSE server
         # @param tool_name [String] the tool name as registered in the MCP server
-        # @param headers [Hash] additional HTTP request headers forwarded to every
-        #   request (tool discovery and tool execution). Ignored for stdio transports.
-        #   Typical use: <tt>headers: { "Authorization" => "Bearer #{ENV['API_KEY']}" }</tt>
-        # @return [Mcp] a configured subclass instance ready for use with an Agent
+        # @param headers [Hash] additional HTTP headers forwarded to discovery and execution
+        # @return [Mcp] configured tool instance
         # @api public
         def from_server(server_uri, tool_name:, headers: {})
-          # Use a short-lived transport only to query the tool definition,
-          # then close it.  Each Mcp instance creates its own transport
-          # so that concurrent callers never share IO streams.
-          transport = build_transport(server_uri, headers: headers)
+          transport = nil
           begin
-            tool_def = transport.fetch_tool(tool_name)
+            transport = build_transport(server_uri, headers: headers)
+            client = MCP::Client.new(transport: transport)
+            client.connect
+            tool_def = extract_tool_def(client, tool_name.to_s, server_uri)
+          rescue ArgumentError, Phronomy::ToolError
+            raise
+          rescue => e
+            raise Phronomy::ToolError, "MCP connection failed: #{e.message}"
           ensure
-            transport.close
+            close_transport_safely(transport)
           end
+
           build_tool_class(tool_name, server_uri, tool_def, headers: headers).new
         end
 
@@ -59,372 +86,385 @@ module Phronomy
           scheme, path = uri.split("://", 2)
           case scheme
           when "stdio"
-            StdioTransport.new(path)
+            argv = Shellwords.split(path.to_s)
+            if argv.empty? || argv[0].to_s.empty?
+              raise ArgumentError, "MCP stdio URI must include a command"
+            end
+
+            MCP::Client::Stdio.new(command: argv[0], args: argv[1..])
           when "http", "https"
-            HttpTransport.new(uri, headers: headers)
+            MCP::Client::HTTP.new(url: uri, headers: headers)
           else
-            raise ArgumentError, "Unsupported MCP transport scheme: #{scheme.inspect}. Supported: 'stdio://', 'http://', 'https://'."
+            raise ArgumentError,
+              "Unsupported MCP transport scheme: #{scheme.inspect}. " \
+              "Supported: 'stdio://', 'http://', 'https://'."
+          end
+        end
+
+        def extract_tool_def(client, tool_name, server_uri)
+          mcp_tool = client.tools.find { |tool| tool.name == tool_name }
+          unless mcp_tool
+            raise ArgumentError,
+              "Tool #{tool_name.inspect} not found on MCP server #{server_uri.inspect}"
           end
+
+          validate_supported_schema!(
+            mcp_tool.input_schema,
+            output_schema: mcp_tool.output_schema,
+            tool_name: mcp_tool.name
+          )
+
+          input_schema = mcp_tool.input_schema
+          properties = input_schema.fetch("properties", {})
+          required_names = input_schema.fetch("required", [])
+
+          {
+            description: mcp_tool.description || tool_name,
+            parameters: parse_schema_params(properties, required_names: required_names)
+          }
         end
 
         def build_tool_class(tool_name, server_uri, tool_def, headers: {})
           klass = Class.new(Mcp)
           klass.tool_name(tool_name)
           klass.instance_variable_set(:@mcp_server_uri, server_uri)
-          klass.instance_variable_set(:@mcp_headers, headers)
+          klass.instance_variable_set(:@mcp_headers, headers.dup.freeze)
 
-          # Register description and params from the MCP tool definition.
           klass.description(tool_def[:description] || tool_name)
-          (tool_def[:parameters] || []).each do |p|
-            opts = {type: p[:type]&.to_sym || :string, desc: p[:description].to_s}
-            opts[:required] = p[:required] if p.key?(:required)
-            opts[:enum] = p[:enum] if p.key?(:enum)
-            klass.param(p[:name].to_sym, **opts)
+          (tool_def[:parameters] || []).each do |parameter|
+            options = {
+              type: parameter.fetch(:type).to_sym,
+              desc: parameter[:description].to_s,
+              required: parameter.fetch(:required, false)
+            }
+            options[:enum] = parameter[:enum] if parameter.key?(:enum)
+            klass.param(parameter.fetch(:name).to_sym, **options)
           end
 
-          # Each instance creates its own transport so concurrent agent threads
-          # never share IO streams, eliminating the need for synchronisation.
-          klass.define_method(:initialize) do
-            uri = self.class.instance_variable_get(:@mcp_server_uri)
-            hdrs = self.class.instance_variable_get(:@mcp_headers) || {}
-            @mcp_transport = self.class.send(:build_transport, uri, headers: hdrs)
+          klass
+        end
+
+        def parse_schema_params(properties, required_names: [])
+          properties.map do |name, schema|
+            parameter = {
+              name: name.to_s,
+              type: schema.fetch("type"),
+              description: schema["description"].to_s,
+              required: required_names.include?(name.to_s)
+            }
+            parameter[:enum] = schema["enum"] if schema.key?("enum")
+            parameter
           end
+        end
 
-          klass.define_method(:execute) do |**args|
-            @mcp_transport.call_tool(tool_name, args)
+        def validate_supported_schema!(input_schema, output_schema:, tool_name:)
+          unless input_schema.is_a?(Hash) && input_schema["type"] == "object"
+            raise Phronomy::ToolError,
+              "MCP tool #{tool_name.inspect} must use an object input schema"
           end
 
-          # Allow callers to deterministically shut down the underlying child
-          # process (stdio) or release the HTTP connection.  For HttpTransport
-          # this is a no-op.  After close, calling execute will reopen the
-          # transport automatically (stdio restarts the child process; HTTP
-          # opens a fresh connection per call).
-          klass.define_method(:close) do
-            @mcp_transport.close
+          dialect = input_schema["$schema"]
+          if dialect && !SUPPORTED_SCHEMA_DIALECTS.include?(dialect)
+            raise Phronomy::ToolError,
+              "MCP tool #{tool_name.inspect} uses unsupported JSON Schema dialect #{dialect.inspect}"
           end
 
-          klass
-        end
-      end
+          unknown_root = input_schema.keys - SUPPORTED_ROOT_KEYS
+          if unknown_root.any?
+            raise Phronomy::ToolError,
+              "MCP tool #{tool_name.inspect} uses unsupported root schema keywords: " \
+              "#{unknown_root.join(", ")}"
+          end
 
-      # -----------------------------------------------------------------------
-      # Transports
-      # -----------------------------------------------------------------------
-
-      # Minimal stdio transport implementing a subset of the MCP JSON-RPC protocol.
-      # Keeps the child process alive for the lifetime of this transport instance
-      # so that session state (registered resources, tool context, etc.) is preserved
-      # across multiple calls.
-      class StdioTransport
-        # @param command         [String]  shell command to spawn the MCP server process
-        # @param read_timeout    [Integer] seconds to wait for the server's JSON-RPC response
-        #   before raising {Phronomy::ToolError}. Mirrors the +read_timeout+ option on
-        #   {HttpTransport}. Defaults to 30 seconds.
-        # @param env             [Hash, nil] environment variable overrides for the subprocess.
-        #   When provided, only these variables are added/overridden; the parent environment
-        #   is still inherited. Use +nil+ as a value to unset a variable in the child process
-        #   (e.g. +{ "SECRET" => nil }+). An empty string value (+""+ ) sets the variable to
-        #   an empty string — it does NOT unset it.
-        # @param cwd             [String, nil] working directory for the subprocess.
-        #   Defaults to the current process's working directory.
-        # @param startup_timeout [Numeric, nil] seconds to wait for the server to
-        #   emit its first line on stdout before raising {Phronomy::ToolError}.
-        #   When nil (default), no startup check is performed.
-        # @api public
-        def initialize(command, read_timeout: 30, env: nil, cwd: nil, startup_timeout: nil)
-          # Split the command string into an argv array so that Open3 executes
-          # it directly without going through the shell, preventing injection.
-          @command = Shellwords.split(command)
-          @read_timeout = read_timeout
-          @env = env
-          @cwd = cwd
-          @startup_timeout = startup_timeout
-          @stdin = nil
-          @stdout = nil
-          @stderr = nil
-          @wait_thr = nil
-          @stderr_thread = nil
-          @stderr_op = nil
-        end
+          additional_properties = input_schema["additionalProperties"]
+          unless additional_properties.nil? || additional_properties == false
+            raise Phronomy::ToolError,
+              "MCP tool #{tool_name.inspect} uses additionalProperties: " \
+              "#{additional_properties.inspect} (only false or omission is supported)"
+          end
 
-        # Shut down the child process and close its IO streams.
-        def close
-          @stdin&.close
-          @stdout&.close
-          @stderr&.close
-          @stdin = nil
-          @stdout = nil
-          @stderr = nil
-          stderr_thread = @stderr_thread
-          stderr_op = @stderr_op
-          wait_thr = @wait_thr
-          @stderr_thread = nil
-          @stderr_op = nil
-          @wait_thr = nil
-          stderr_thread&.join(1)
-          begin
-            stderr_op&.blocking_wait(timeout: 1.0)
-          rescue
-            nil
+          properties = input_schema["properties"] || {}
+          unless properties.is_a?(Hash)
+            raise Phronomy::ToolError,
+              "MCP tool #{tool_name.inspect} has an invalid properties schema"
           end
-          wait_thr&.join(5)
-        end
 
-        # Retrieve the tool definition from the server using the MCP `tools/list` method.
-        # @param tool_name [String]
-        # @return [Hash] { description:, parameters: }
-        # @api public
-        def fetch_tool(tool_name)
-          response = rpc_call("tools/list", {})
-          tools = response.dig("result", "tools") || []
-          defn = tools.find { |t| t["name"] == tool_name }
-          raise ArgumentError, "Tool #{tool_name.inspect} not found on MCP server #{@command.inspect}" unless defn
+          required_names = input_schema["required"] || []
+          unless required_names.is_a?(Array) && required_names.all? { |name| name.is_a?(String) }
+            raise Phronomy::ToolError,
+              "MCP tool #{tool_name.inspect} has an invalid required list"
+          end
 
-          required_names = defn.dig("inputSchema", "required") || []
-          {
-            description: defn["description"],
-            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {}, required_names: required_names)
-          }
-        end
+          unknown_required = required_names - properties.keys
+          if unknown_required.any?
+            raise Phronomy::ToolError,
+              "MCP tool #{tool_name.inspect} requires undefined parameters: " \
+              "#{unknown_required.inspect}"
+          end
 
-        # Call a tool on the MCP server using the `tools/call` method.
-        # @param tool_name [String]
-        # @param args [Hash]
-        # @return [Object] the tool result
-        # @api public
-        def call_tool(tool_name, args)
-          response = rpc_call("tools/call", {name: tool_name, arguments: args})
-          if response["error"]
-            err_msg = response.dig("error", "message") || response["error"].to_s
-            raise Phronomy::ToolError, "MCP server returned error: #{err_msg}"
+          properties.each do |name, schema|
+            validate_property_schema!(tool_name, name, schema)
           end
-          content = response.dig("result", "content")
 
-          # MCP content is an array of content blocks; extract text blocks.
-          if content.is_a?(Array)
-            texts = content.select { |c| c["type"] == "text" }.map { |c| c["text"] }
-            (texts.length == 1) ? texts.first : texts
-          else
-            content
+          if output_schema
+            warn_mcp(
+              "[Phronomy] MCP tool '#{tool_name}' has an output schema; " \
+              "Phronomy does not yet use it for validation"
+            )
           end
         end
 
-        private
+        def validate_property_schema!(tool_name, name, schema)
+          unless name.is_a?(String)
+            raise Phronomy::ToolError,
+              "MCP tool #{tool_name.inspect} has a non-string property key: #{name.inspect}"
+          end
+          unless schema.is_a?(Hash)
+            raise Phronomy::ToolError,
+              "MCP parameter #{name.inspect} must have an object schema"
+          end
 
-        # Ensure the child process is running, spawning it if necessary.
-        def ensure_started!
-          return if @stdin && !@stdin.closed?
-
-          popen3_opts = {}
-          popen3_opts[:chdir] = @cwd if @cwd
-
-          argv = @env ? [@env, *@command] : @command
-          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(*argv, **popen3_opts)
-          # Drain stderr asynchronously to prevent the pipe buffer from filling
-          # and deadlocking the child process. Errors inside the drain thread are
-          # silently ignored since stderr content is diagnostics-only.
-          #
-          # Prefer BlockingAdapterPool when a Runtime is configured so that this
-          # file eventually needs no direct Thread.new (Issue #360). Fall back to
-          # Thread.new when no pool is available (no EventLoop / bare invocation).
-          pool = begin; Phronomy::Runtime.instance&.blocking_io; rescue; nil; end
-          if pool
-            @stderr_op = pool.submit {
-              begin
-                @stderr.read
-              rescue
-                nil
-              end
-            }
-            @stderr_thread = nil
-          else
-            @stderr_thread = Thread.new {
-              begin
-                @stderr.read
-              rescue
-                nil
-              end
-            }
-            @stderr_op = nil
+          type = schema["type"]
+          unless type.is_a?(String) && SUPPORTED_TYPES.include?(type)
+            raise Phronomy::ToolError,
+              "MCP parameter #{name.inspect} uses unsupported type #{type.inspect}"
           end
 
-          if @startup_timeout
-            unless IO.select([@stdout], nil, nil, @startup_timeout)
-              close
+          if schema.key?("enum")
+            enum = schema["enum"]
+            unless enum.is_a?(Array)
               raise Phronomy::ToolError,
-                "MCP stdio server did not start within #{@startup_timeout} seconds"
+                "MCP parameter #{name.inspect} has an invalid enum (must be an Array)"
             end
-            # Do NOT call @stdout.gets here: gets() blocks until a newline arrives,
-            # which hangs indefinitely when the server emits no startup line or a
-            # partial line without '\n'.  IO.select already confirmed the server is
-            # alive and responsive; the first rpc_call will consume actual output.
+            validate_enum_values!(type, enum, tool_name: tool_name, parameter_name: name)
           end
-        end
 
-        def rpc_call(method, params)
-          ensure_started!
-          payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
-          @stdin.puts(payload)
-          unless IO.select([@stdout], nil, nil, @read_timeout)
+          ignored = IGNORED_PROPERTY_KEYS.select { |key| schema.key?(key) }
+          if ignored.any?
+            warn_mcp(
+              "[Phronomy] MCP tool '#{tool_name}' parameter '#{name}' has " \
+              "constraint keywords #{ignored.inspect}; they will be ignored"
+            )
+          end
+
+          unknown_property = schema.keys - SUPPORTED_PROPERTY_KEYS - IGNORED_PROPERTY_KEYS
+          if unknown_property.any?
             raise Phronomy::ToolError,
-              "MCP stdio server did not respond within #{@read_timeout} seconds"
+              "MCP parameter #{name.inspect} uses unsupported schema keywords: " \
+              "#{unknown_property.join(", ")}"
           end
-          raw = @stdout.gets
-          raise Phronomy::ToolError, "MCP server closed the connection unexpectedly" if raw.nil?
-          JSON.parse(raw)
         end
 
-        def parse_schema_params(properties, required_names: [])
-          properties.map do |name, schema|
-            param = {
-              name: name.to_s,
-              type: schema["type"] || "string",
-              description: schema["description"].to_s,
-              required: required_names.include?(name.to_s)
-            }
-            param[:enum] = schema["enum"] if schema["enum"]
-            param
+        def validate_enum_values!(type, values, tool_name:, parameter_name:)
+          valid = values.all? do |value|
+            case type
+            when "string" then value.is_a?(String)
+            when "integer" then value.is_a?(Integer)
+            when "number" then value.is_a?(Numeric)
+            when "boolean" then value == true || value == false
+            end
           end
+          return if valid
+
+          raise Phronomy::ToolError,
+            "MCP tool #{tool_name.inspect} parameter #{parameter_name.inspect} " \
+            "has enum values incompatible with #{type}"
         end
-      end
 
-      # HTTP/HTTPS transport implementing JSON-RPC over HTTP with SSE support.
-      #
-      # Sends JSON-RPC POST requests to the MCP server endpoint.
-      # Accepts both plain JSON responses (Content-Type: application/json) and
-      # Server-Sent Events streams (Content-Type: text/event-stream), covering
-      # both the 2024-11-05 and 2025-03-26 MCP HTTP transport specifications.
-      #
-      # @example
-      #   tool = Phronomy::Tools::Mcp.from_server(
-      #     "http://localhost:8080/mcp",
-      #     tool_name: "weather_lookup"
-      #   )
-      class HttpTransport
-        # @param base_url     [String]  full URL of the MCP endpoint, e.g. "http://localhost:8080/mcp"
-        # @param open_timeout [Integer] TCP connection timeout in seconds (default: 5)
-        # @param read_timeout [Integer] HTTP read timeout in seconds (default: 30)
-        # @param headers      [Hash]    additional HTTP request headers (e.g. Authorization).
-        #   Merged on top of the default Content-Type and Accept headers; caller-supplied
-        #   values override defaults when keys collide.
-        # @api public
-        def initialize(base_url, open_timeout: 5, read_timeout: 30, headers: {})
-          @uri = URI.parse(base_url)
-          @open_timeout = open_timeout
-          @read_timeout = read_timeout
-          @extra_headers = headers
+        def warn_mcp(message)
+          if Phronomy.configuration.logger
+            Phronomy.configuration.logger.warn(message)
+          else
+            Kernel.warn(message)
+          end
         end
 
-        # HTTP connections are stateless; close is a no-op, defined so that
-        # both transport classes share the same interface as StdioTransport.
-        def close
+        def close_transport_safely(transport)
+          transport&.close
+        rescue
+          nil
         end
+      end
 
-        # Retrieve the tool definition from the server using MCP `tools/list`.
-        # @param tool_name [String]
-        # @return [Hash] { description:, parameters: }
-        # @api public
-        def fetch_tool(tool_name)
-          response = rpc_call("tools/list", {})
-          tools = response.dig("result", "tools") || []
-          defn = tools.find { |t| t["name"] == tool_name }
-          raise ArgumentError, "Tool #{tool_name.inspect} not found on MCP server #{@uri}" unless defn
+      # @api private
+      def initialize
+        @mcp_call_mutex = Mutex.new
+        @mcp_client = nil
+        build_and_connect_client!
+      end
 
-          required_names = defn.dig("inputSchema", "required") || []
-          {
-            description: defn["description"],
-            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {}, required_names: required_names)
-          }
+      # Executes the remote MCP tool.
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @return [String, Array, Hash]
+      # @api public
+      def execute(cancellation_token: nil, **args)
+        @mcp_call_mutex.synchronize do
+          ensure_mcp_client!
+          perform_mcp_call(cancellation_token: cancellation_token, args: args)
         end
+      end
 
-        # Call a tool on the MCP server using MCP `tools/call`.
-        # @param tool_name [String]
-        # @param args [Hash]
-        # @return [Object] the tool result
-        # @api public
-        def call_tool(tool_name, args)
-          response = rpc_call("tools/call", {name: tool_name, arguments: args})
-          if response["error"]
-            err_msg = response.dig("error", "message") || response["error"].to_s
-            raise Phronomy::ToolError, "MCP HTTP server returned error: #{err_msg}"
-          end
-          content = response.dig("result", "content")
+      # Closes the currently connected client synchronously. A transport already
+      # detached after cancellation is owned by the Runtime cleanup pool and is
+      # drained during Runtime shutdown; this method does not wait for that older
+      # cleanup operation.
+      #
+      # The instance can be used again after close; the next call reconnects.
+      # @return [void]
+      # @api public
+      def close
+        @mcp_call_mutex.synchronize { invalidate_mcp_client! }
+      end
 
-          if content.is_a?(Array)
-            texts = content.select { |c| c["type"] == "text" }.map { |c| c["text"] }
-            (texts.length == 1) ? texts.first : texts
-          else
-            content
-          end
+      private
+
+      def perform_mcp_call(cancellation_token:, args:)
+        mcp_cancellation = build_mcp_cancellation(cancellation_token)
+        response = begin
+          @mcp_client.call_tool(
+            name: self.class.tool_name,
+            arguments: args.transform_keys(&:to_s),
+            cancellation: mcp_cancellation
+          )
+        rescue MCP::CancelledError => e
+          invalidate_mcp_client_after_cancellation!
+          message = "MCP tool call was cancelled"
+          message += ": #{e.reason}" if e.respond_to?(:reason) && e.reason
+          raise Phronomy::CancellationError, message
+        rescue MCP::Client::SessionExpiredError
+          recover_expired_session!
+        rescue MCP::Client::ServerError => e
+          raise Phronomy::ToolError,
+            "MCP server returned error (#{e.code}): #{e.message}"
+        rescue MCP::Client::InputRequiredError => e
+          raise Phronomy::ToolError,
+            "MCP tool requires unsupported multi-round-trip input: #{e.message}"
+        rescue MCP::Client::ValidationError => e
+          raise Phronomy::ToolError,
+            "MCP response validation failed: #{e.message}"
+        rescue MCP::Client::RequestHandlerError => e
+          raise Phronomy::ToolError,
+            "MCP request handler failed: #{e.message}"
+        rescue => e
+          raise Phronomy::ToolError, "MCP call failed: #{e.message}"
         end
 
-        private
+        result = validate_call_tool_response!(response)
+        format_tool_result(result)
+      end
 
-        def rpc_call(method, params)
-          payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
+      def build_mcp_cancellation(cancellation_token)
+        return nil unless cancellation_token
 
-          http = Net::HTTP.new(@uri.host, @uri.port)
-          http.use_ssl = (@uri.scheme == "https")
-          http.open_timeout = @open_timeout
-          http.read_timeout = @read_timeout
+        mcp_cancellation = MCP::Cancellation.new
+        cancellation_token.on_cancel do
+          mcp_cancellation.cancel(reason: "phronomy_cancelled")
+        end
+        mcp_cancellation
+      end
 
-          path = @uri.path.empty? ? "/" : @uri.path
-          path = "#{path}?#{@uri.query}" if @uri.query
+      def recover_expired_session!
+        begin
+          @mcp_client.connect
+        rescue => reconnect_error
+          invalidate_mcp_client!
+          raise Phronomy::ToolError,
+            "MCP session expired and reconnection failed: #{reconnect_error.message}"
+        end
 
-          request = Net::HTTP::Post.new(path)
-          request["Content-Type"] = "application/json"
-          request["Accept"] = "application/json, text/event-stream"
-          @extra_headers.each { |k, v| request[k.to_s] = v.to_s }
-          request.body = payload
+        raise Phronomy::ToolError,
+          "MCP session expired; the connection was restored, but the tool call was not replayed"
+      end
 
-          http_response = http.request(request)
+      def validate_call_tool_response!(response)
+        unless response.is_a?(Hash)
+          raise Phronomy::ToolError, "MCP tool returned a non-object response"
+        end
 
-          unless http_response.is_a?(Net::HTTPSuccess)
-            raise Phronomy::ToolError,
-              "MCP HTTP server returned #{http_response.code}: #{http_response.body}"
-          end
+        result = response["result"]
+        unless result.is_a?(Hash)
+          raise Phronomy::ToolError, "MCP tool response is missing a valid result"
+        end
 
-          content_type = http_response["Content-Type"] || ""
-          if content_type.include?("text/event-stream")
-            parse_sse_response(http_response.body)
-          else
-            JSON.parse(http_response.body)
-          end
+        content = result["content"]
+        unless content.is_a?(Array)
+          raise Phronomy::ToolError, "MCP tool result is missing valid content"
+        end
+        unless content.all? { |item| item.is_a?(Hash) }
+          raise Phronomy::ToolError,
+            "MCP tool result contains an invalid content item"
+        end
+        if result.key?("isError") && result["isError"] != true && result["isError"] != false
+          raise Phronomy::ToolError, "MCP tool result has an invalid isError value"
         end
 
-        # Parse an SSE response body and extract the last JSON-RPC message.
-        # SSE lines are in the format "data: <json>".
-        def parse_sse_response(body)
-          result = nil
-          body.each_line do |line|
-            line = line.strip
-            next unless line.start_with?("data: ")
-
-            data = line.delete_prefix("data: ")
-            next if data == "[DONE]"
-
-            begin
-              parsed = JSON.parse(data)
-              result = parsed if parsed.is_a?(Hash) && parsed["jsonrpc"]
-            rescue JSON::ParserError
-              next
-            end
-          end
-          result || raise(Phronomy::ToolError, "No valid JSON-RPC response found in SSE stream")
+        result
+      end
+
+      def format_tool_result(result)
+        content = result.fetch("content")
+        texts = content.filter_map do |item|
+          item["text"] if item["type"] == "text" && item["text"].is_a?(String)
         end
 
-        def parse_schema_params(properties, required_names: [])
-          properties.map do |name, schema|
-            param = {
-              name: name.to_s,
-              type: schema["type"] || "string",
-              description: schema["description"].to_s,
-              required: required_names.include?(name.to_s)
-            }
-            param[:enum] = schema["enum"] if schema["enum"]
-            param
-          end
+        if result["isError"] == true
+          message = texts.join("\n")
+          message = JSON.generate(result["structuredContent"] || content) if message.empty?
+          return "MCP tool execution error: #{message}"
+        end
+
+        return texts.first if texts.length == 1
+        return texts if texts.any?
+
+        result["structuredContent"] || content
+      end
+
+      def ensure_mcp_client!
+        build_and_connect_client! unless @mcp_client
+      end
+
+      def build_and_connect_client!
+        transport = nil
+        begin
+          uri = self.class.instance_variable_get(:@mcp_server_uri)
+          headers = self.class.instance_variable_get(:@mcp_headers) || {}
+          transport = self.class.send(:build_transport, uri, headers: headers)
+          client = MCP::Client.new(transport: transport)
+          client.connect
+          @mcp_client = client
+        rescue => e
+          self.class.send(:close_transport_safely, transport)
+          raise Phronomy::ToolError, "MCP connection failed: #{e.message}"
+        end
+      end
+
+      def invalidate_mcp_client!
+        old_client = @mcp_client
+        @mcp_client = nil
+        self.class.send(:close_transport_safely, old_client&.transport)
+      end
+
+      def invalidate_mcp_client_after_cancellation!
+        old_client = @mcp_client
+        @mcp_client = nil
+        return unless old_client
+
+        schedule_transport_cleanup(old_client.transport)
+      end
+
+      def schedule_transport_cleanup(transport)
+        cleanup_pool = Phronomy::Runtime.instance.pool(
+          :mcp_cleanup,
+          size: MCP_CLEANUP_POOL_SIZE,
+          queue_size: MCP_CLEANUP_QUEUE_SIZE
+        )
+        cleanup_pool.submit(on_full: :raise) do
+          self.class.send(:close_transport_safely, transport)
         end
+      rescue Phronomy::BackpressureError, Phronomy::PoolShutdownError
+        # During shutdown or an exceptional cleanup burst, prefer a bounded
+        # synchronous fallback over leaking the child process/socket.
+        self.class.send(:close_transport_safely, transport)
       end
     end
   end