phronomy 0.11.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a6262c12bc063819c0e1656699f47666b06b182747d6ce85843d2a74988c358
-  data.tar.gz: 6529858071913e61a6a840fe03e36620322bfddd50e415b054314124f9b7fcd1
+  metadata.gz: dd9fb679db0e4d4c582a82dad543ca0d93806878e0936404cd4255d2a48a741b
+  data.tar.gz: 511a6bfb90ec0524aafb201996bc251c9b1923a2d3ff4d1b389aa7d62f2d3395
 SHA512:
-  metadata.gz: 6b1441aab8f7197c23bd84fea750388280ee00036e729f47de13b0113249261f72fb10f01b5e9a78fb2464fcb0ebac5fd07d91eef7d4b5e83fb973b463c0630e
-  data.tar.gz: d9c0401177c9d59900543c7ff5bbae698401fa0dc5ca7e33272458f41eddff2fa61caa501a5735b273f59b44de96e1fc70b0c5a648bb159066f7facd18b5aa82
+  metadata.gz: 9efc33585c40e3d5b4559121cd5654c9687608ff05ab684818e27ac5d4672264352fb68fbf4efa6436ed8666a0b194acfdcea7511fce67a5eda50e690cd80803
+  data.tar.gz: 0142742c7875411622ad37ae2918164130bd84fe237da2e100b69578f67380a08c61ae6ca77cfdcac5892ea7bd56140c39b374b8d0543d11cd359bda587f12df

data/CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [Unreleased]
+## [0.13.0] - 2026-07-23
 
 ### Added
 
@@ -49,6 +49,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `_stream_impl`, and `Suspendable#resume` have been removed.  Behaviour is unchanged
   — guardrails still run before any filters and `GuardrailError` still propagates.
 
+### Changed
+
+- **MCP transport replaced by official `mcp` gem** (closes #280, #365):
+  The hand-rolled `StdioTransport` and `HttpTransport` (~260 lines) have been
+  replaced by `MCP::Client::Stdio` and `MCP::Client::HTTP` from the official
+  `mcp` gem (v0.25.0+). Adds the `mcp >= 0.3` runtime dependency.
+  - Built-in 4 MiB size limits for stdout, stderr, and HTTP responses
+  - Automatic MCP `initialize` handshake on every connection
+  - SSE response parsing handled by the SDK
+  - `from_server` and `execute` convert SDK errors into `Phronomy::ToolError`
+  - Removes all `Thread.new` usage from `mcp.rb`; entry removed from
+    `THREAD_NEW_ALLOWLIST` in `thread_invariants_spec.rb`
+
+- **`CancellationToken` bridged into MCP `call_tool`** (Issue #390):
+  `Mcp#execute` now accepts a `cancellation_token:` keyword argument.
+  When provided, the token is bridged to `MCP::Cancellation` via `on_cancel`,
+  so an explicit `cancel!` propagates into the in-flight `call_tool` request
+  as a MCP `notifications/cancelled` message.
+
+- **`config[:tool_timeout]` forwarded to `BlockingAdapterPool`** (Issue #390):
+  `ToolExecutor.call_async` and `Capability::Base#call_async` now accept a
+  `config:` keyword. `config[:tool_timeout]` is passed as the `timeout:` to
+  `pool.submit`, enabling the same abandoned-operation tracking that LLM calls
+  already use via `config[:llm_timeout]`.
+
 
 
 ## [0.10.0] - 2026-06-08

data/README.md

@@ -46,7 +46,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | **Knowledge** — Static context injection with pluggable loaders, splitters, and vector stores; `static_knowledge_refresh!` for runtime cache invalidation | Beta |
 | **`VectorStore#size`** — Returns document count for all three backends (InMemory, RedisSearch, Pgvector) | Beta |
 | **`VectorStore::AsyncBackend` mixin** — Pluggable async interface for `VectorStore`; default pool-backed implementations for `search_async`, `add_async`, `remove_async`, `clear_async`; backends with native async drivers override individual methods to bypass `BlockingAdapterPool` entirely; all existing backends remain unchanged | Beta |
-| **MCP Tool** — `Phronomy::Tools::Mcp`: Model Context Protocol server integration; `Phronomy::Tools::Agent`: wraps an agent class as a callable tool via `from_agent` | Beta |
+| **MCP Tool** — `Phronomy::Tools::Mcp`: Model Context Protocol server integration via the official `mcp` gem; `Phronomy::Tools::Agent`: wraps an agent class as a callable tool via `from_agent` | Beta |
 | **Vector Search Tool** — `Phronomy::Tools::VectorSearch`: wraps a `VectorStore` and `Embeddings` adapter as a callable agent tool via `from_store` | Beta |
 
 **Execution and reliability**
@@ -57,9 +57,9 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | **Agent EventLoop Mode** — `Agent#invoke` (non-blocking via EventLoop), `Agent#invoke_async` + `Task#map` (child-agent pattern for Workflow integration), parallel tool dispatch via `ParallelToolChat` | Experimental |
 | **`invoke_async` / `call_async`** — `Agent::Base#invoke_async` and `Workflow#invoke_async` return a `Task`; `Agent::Context::Capability::Base#call_async` similarly; compatible with EventLoop and standalone contexts | Experimental |
 | **`Task#map`** — transforms a `Task`'s completed value via a block; returns a new `Task` whose value is the block's return value; if the source task fails or is cancelled the mapped task propagates the error without calling the block; primary use-case: `invoke_async.map { \|r\| ctx.merge(answer: r[:output]) }` to wire agent results into a `WorkflowContext` | Experimental |
-| **CancellationToken** — Cooperative cancellation via `cancel!`/`cancelled?`/`raise_if_cancelled!`; `timeout_after(seconds)` for monotonic-clock deadlines; optional `deadline:` (wall-clock) for backward compatibility; passed as `config: { cancellation_token: token }` to agents and `dispatch_parallel`; injected into `tool.execute` when the method declares a `cancellation_token:` keyword | Experimental |
+| **CancellationToken** — Cooperative cancellation via `cancel!`/`cancelled?`/`raise_if_cancelled!`; `timeout_after(seconds)` for monotonic-clock deadlines; optional `deadline:` (wall-clock) for backward compatibility; passed as `config: { cancellation_token: token }` to agents and `dispatch_parallel`; injected into `tool.execute` when the method declares a `cancellation_token:` keyword; bridged to `MCP::Cancellation` in `Phronomy::Tools::Mcp#execute` | Experimental |
 | **`dispatch_parallel` / `fan_out` `force_kill:` option** — `force_kill: false` (default) leaves timed-out workers running and raises `TimeoutError` immediately; `force_kill: true` restores the old `Thread#kill` behaviour with a `logger.warn` | Beta |
-| **`execution_mode` DSL on `Agent::Context::Capability::Base`** — Declares how a tool's `execute` should be dispatched: `:cooperative` (same scheduler thread), `:blocking_io` (default; offloaded to `BlockingAdapterPool`), `:cpu_bound`, `:external_process` | Experimental |
+| **`execution_mode` DSL on `Agent::Context::Capability::Base`** — Declares how a tool's `execute` should be dispatched: `:cooperative` (same scheduler thread), `:blocking_io` (default; offloaded to `BlockingAdapterPool`), `:cpu_bound`, `:external_process`; `config[:tool_timeout]` sets the per-submit timeout forwarded to `BlockingAdapterPool` for abandoned-operation tracking | Experimental |
 | **`invocation_context:` keyword on `Agent#invoke` / `Workflow#invoke`** — Pass a `Phronomy::InvocationContext` directly; `thread_id`, `cancellation_token`, and `deadline`-based timeout are derived from it; `task_id` / `parent_task_id` appear in trace spans automatically; `config:` keys remain supported as backward-compat aliases | Beta |
 | **`ConcurrencyGate` — unified backpressure** — Counting semaphore that enforces per-resource concurrency caps (`max_concurrent_agent_tasks`, `max_concurrent_tool_tasks`, `max_concurrent_workflow_tasks`, `max_concurrent_llm_calls`, `max_concurrent_vector_searches`); configured via `Phronomy.configure`; backpressure behaviour follows the global `backpressure` setting (`:wait`, `:raise`/`:reject`, `:timeout`); `nil` cap = unlimited (default) | Beta |
 | **Cooperative scheduler yield points** — `Runtime#yield` (cooperative yield; yields the current task's time slice); `Runtime#yield_if_needed(every: N)` (thread-local counter, yields every N calls); CPU-bound detection when `blocking_detect_threshold_ms` is set (warns and increments `non_yield_threshold_violation_count` when a task runs longer than the threshold without yielding); `starvation_threshold_ms` configuration field (default: 50ms) | Beta |

data/lib/phronomy/agent/base.rb

@@ -1173,7 +1173,7 @@ module Phronomy
             effective_name = resolved.new.name
             rejected_class = Class.new(resolved) do
               tool_name effective_name
-              define_method(:call) do |_args|
+              define_method(:call) do |_args, **_kwargs|
                 "Tool execution denied: scope :#{scope} is not permitted."
               end
             end
@@ -1199,9 +1199,9 @@ module Phronomy
           effective_name = resolved.new.name
           resolved = Class.new(resolved) do
             tool_name effective_name
-            define_method(:call) do |args|
+            define_method(:call) do |args, **kwargs|
               if handler.call(name, args)
-                super(args)
+                super(args, **kwargs)
               else
                 "Tool execution denied."
               end
@@ -1216,8 +1216,8 @@ module Phronomy
         effective_name4 = resolved.new.name
         Class.new(resolved) do
           tool_name effective_name4
-          define_method(:call) do |args|
-            result = super(args)
+          define_method(:call) do |args, **kwargs|
+            result = super(args, **kwargs)
             result_filters.inject(result) { |val, f| f.call(val, tool_name: name, args: args) }
           end
         end

data/lib/phronomy/agent/context/capability/base.rb

@@ -369,11 +369,12 @@ module Phronomy
           # @return [#await]
           # @api public
           # mutant:disable
-          def call_async(args, cancellation_token: nil)
+          def call_async(args, cancellation_token: nil, config: {})
             Phronomy::Agent::ToolExecutor.call_async(
               tool: self,
               args: args,
-              cancellation_token: cancellation_token
+              cancellation_token: cancellation_token,
+              config: config
             )
           end
 

data/lib/phronomy/agent/invocation_session.rb

@@ -298,27 +298,36 @@ module Phronomy
           end
         end
 
-        # Execute the tool off the EventLoop thread via Runtime.instance.spawn.
-        # Tool implementations (e.g. Orchestrator sub-agent dispatch) may call
-        # agent.invoke_async().wait_result which would deadlock if run directly on the
-        # EventLoop dispatch thread. Returning a Task causes
-        # PhaseMachineBuilder#dispatch_task to await the result off the EventLoop
-        # and post :action_completed back when done.
+        # Dispatch the tool off the EventLoop thread via ToolExecutor, which
+        # routes based on the tool's execution_mode class attribute:
+        #   :blocking_io (default) → BlockingAdapterPool (bounded thread pool)
+        #   :cooperative           → Runtime.instance.spawn (scheduler task)
+        # Wrap the awaitable in Task.deferred so FSMSession recognises it as
+        # an async action and sets async_pending = true.
         tc_id = tc.id
         tc_args = tc.arguments
         tc_name = tc.name
-        Phronomy::Runtime.instance.spawn(name: "tool-exec:#{tc_name}") do
-          result = tool_instance.call(tc_args)
-          ctx.chat.add_message(
-            role: :tool,
-            content: result.to_s,
-            tool_call_id: tc_id
-          )
-          ctx.pending_tool_call = nil
-          ctx.tool_call_pending = false
-          ctx.approval_required = false
-          ctx
+        ct = ctx.config[:cancellation_token]
+        awaitable = tool_instance.call_async(tc_args, cancellation_token: ct, config: ctx.config)
+        result_task = Phronomy::Task.deferred(name: "tool-exec:#{tc_name}")
+        awaitable.on_complete do |result, error|
+          if error
+            result_task.backend.unblock(nil, error)
+            result_task.transition!(:failed, error: error)
+          else
+            ctx.chat.add_message(
+              role: :tool,
+              content: result.to_s,
+              tool_call_id: tc_id
+            )
+            ctx.pending_tool_call = nil
+            ctx.tool_call_pending = false
+            ctx.approval_required = false
+            result_task.backend.unblock(ctx, nil)
+            result_task.transition!(:completed, value: ctx)
+          end
         end
+        result_task
       end
       private_class_method :executing_tool_action
 

data/lib/phronomy/agent/tool_executor.rb

@@ -54,11 +54,15 @@ module Phronomy
       # @param tool               [Phronomy::Agent::Context::Capability::Base] the tool instance to invoke
       # @param args               [Hash]                 argument hash to pass to {Tool::Base#call}
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @param config             [Hash] invocation config forwarded from the agent pipeline.
+      #                           Recognised keys: +:tool_timeout+ (seconds; passed as the
+      #                           +BlockingAdapterPool#submit+ timeout so that timed-out
+      #                           operations are tracked as abandoned rather than silently dropped).
       # @param runtime            [Phronomy::Runtime]    runtime to use for spawning
       #                           (defaults to {Runtime.instance}; injectable for tests)
       # @return [#await] a {Phronomy::Task} or {BlockingAdapterPool::PendingOperation}
       # @api private
-      def self.call_async(tool:, args:, cancellation_token: nil, runtime: Phronomy::Runtime.instance)
+      def self.call_async(tool:, args:, cancellation_token: nil, config: {}, runtime: Phronomy::Runtime.instance)
         ct = cancellation_token
         mode = tool.class.execution_mode
 
@@ -100,7 +104,10 @@ module Phronomy
           end
         else
           # Submit directly to pool — no wrapping Task thread required.
-          pool.submit(cancellation_token: ct) { tool.call(args, cancellation_token: ct) }
+          # Pass tool_timeout so the pool can track timed-out operations as
+          # abandoned, consistent with how LLM calls use config[:llm_timeout].
+          timeout = config[:tool_timeout]
+          pool.submit(cancellation_token: ct, timeout: timeout) { tool.call(args, cancellation_token: ct) }
         end
       end
     end

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -252,9 +252,9 @@ module Phronomy
         effective_name = prepared.new.name
         Class.new(prepared) do
           tool_name effective_name
-          define_method(:call) do |args|
+          define_method(:call) do |args, **kwargs|
             self._orchestrator_context = orch.instance_variable_get(:@_orchestrator_context)
-            super(args)
+            super(args, **kwargs)
           end
         end
       end

data/lib/phronomy/tools/mcp.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-require "json"
-require "net/http"
-require "open3"
-require "securerandom"
+require "mcp"
 require "shellwords"
 require "uri"
 
@@ -12,11 +9,12 @@ 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 (mcp gem) for transport handling, which provides
+    # built-in support for the MCP initialize handshake, size limits, and SSE.
+    #
     # 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.
     #
     # @example
     #   web_search = Phronomy::Tools::Mcp.from_server(
@@ -35,39 +33,62 @@ module Phronomy
         #   - "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
         # @api public
-        def from_server(server_uri, tool_name:)
-          # 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)
+        def from_server(server_uri, tool_name:, headers: {})
+          # Use a short-lived client only to discover the tool definition, then close.
+          # Each Mcp instance creates its own client so concurrent agent threads
+          # never share IO streams, eliminating the need for synchronisation.
+          transport = build_transport(server_uri, headers: headers)
+          client = MCP::Client.new(transport: transport)
           begin
-            tool_def = transport.fetch_tool(tool_name)
+            client.connect
+            tool_def = extract_tool_def(client, tool_name.to_s, server_uri)
+          rescue ArgumentError
+            raise
+          rescue => e
+            raise Phronomy::ToolError, "MCP connection failed: #{e.message}"
           ensure
             transport.close
           end
-          build_tool_class(tool_name, server_uri, tool_def).new
+          build_tool_class(tool_name, server_uri, tool_def, headers: headers).new
         end
 
         private
 
-        def build_transport(uri)
+        def build_transport(uri, headers: {})
           scheme, path = uri.split("://", 2)
           case scheme
           when "stdio"
-            StdioTransport.new(path)
+            argv = Shellwords.split(path)
+            MCP::Client::Stdio.new(command: argv[0], args: argv[1..])
           when "http", "https"
-            HttpTransport.new(uri)
+            MCP::Client::HTTP.new(url: uri, headers: headers)
           else
             raise ArgumentError, "Unsupported MCP transport scheme: #{scheme.inspect}. Supported: 'stdio://', 'http://', 'https://'."
           end
         end
 
-        def build_tool_class(tool_name, server_uri, tool_def)
+        def extract_tool_def(client, tool_name, server_uri)
+          mcp_tool = client.tools.find { |t| t.name == tool_name }
+          raise ArgumentError, "Tool #{tool_name.inspect} not found on MCP server #{server_uri.inspect}" unless mcp_tool
+
+          properties = mcp_tool.input_schema&.dig("properties") || {}
+          required_names = mcp_tool.input_schema&.dig("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)
 
           # Register description and params from the MCP tool definition.
           klass.description(tool_def[:description] || tool_name)
@@ -78,333 +99,55 @@ module Phronomy
             klass.param(p[:name].to_sym, **opts)
           end
 
-          # Each instance creates its own transport so concurrent agent threads
-          # never share IO streams, eliminating the need for synchronisation.
+          # Each instance creates its own MCP client so concurrent agent threads
+          # never share IO streams.
           klass.define_method(:initialize) do
             uri = self.class.instance_variable_get(:@mcp_server_uri)
-            @mcp_transport = self.class.send(:build_transport, uri)
-          end
-
-          klass.define_method(:execute) do |**args|
-            @mcp_transport.call_tool(tool_name, args)
+            hdrs = self.class.instance_variable_get(:@mcp_headers) || {}
+            transport = self.class.send(:build_transport, uri, headers: hdrs)
+            @mcp_client = MCP::Client.new(transport: transport)
+            @mcp_client.connect
+          end
+
+          klass.define_method(:execute) do |cancellation_token: nil, **args|
+            # Bridge Phronomy::CancellationToken to MCP::Cancellation so that
+            # explicit cancel! calls propagate into the in-flight MCP request.
+            # Deadline-based expiry is handled cooperatively by BlockingAdapterPool
+            # (the worker slot is marked abandoned); no extra handling is needed here.
+            mcp_cancel = nil
+            if cancellation_token
+              mcp_cancel = MCP::Cancellation.new
+              cancellation_token.on_cancel { mcp_cancel.cancel(reason: "phronomy_cancelled") }
+            end
+            begin
+              response = @mcp_client.call_tool(
+                name: tool_name,
+                arguments: args.transform_keys(&:to_s),
+                cancellation: mcp_cancel
+              )
+            rescue => e
+              raise Phronomy::ToolError, "MCP call failed: #{e.message}"
+            end
+            if response["error"]
+              err_msg = response.dig("error", "message") || response["error"].to_s
+              raise Phronomy::ToolError, "MCP server returned error: #{err_msg}"
+            end
+            content = response.dig("result", "content")
+            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
           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).
+          # Allow callers to deterministically shut down the underlying transport.
           klass.define_method(:close) do
-            @mcp_transport.close
+            @mcp_client.transport.close
           end
 
           klass
         end
-      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
-
-        # 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
-          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 = defn.dig("inputSchema", "required") || []
-          {
-            description: defn["description"],
-            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {}, required_names: required_names)
-          }
-        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}"
-          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
-          end
-        end
-
-        private
-
-        # 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
-          end
-
-          if @startup_timeout
-            unless IO.select([@stdout], nil, nil, @startup_timeout)
-              close
-              raise Phronomy::ToolError,
-                "MCP stdio server did not start within #{@startup_timeout} seconds"
-            end
-            line = @stdout.gets
-            @stdout.ungetbyte(line) if line
-          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)
-            raise Phronomy::ToolError,
-              "MCP stdio server did not respond within #{@read_timeout} seconds"
-          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
-          end
-        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
-        end
-
-        # HTTP connections are stateless; close is a no-op, defined so that
-        # both transport classes share the same interface as StdioTransport.
-        def close
-        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
-
-          required_names = defn.dig("inputSchema", "required") || []
-          {
-            description: defn["description"],
-            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {}, required_names: required_names)
-          }
-        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")
-
-          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
-        end
-
-        private
-
-        def rpc_call(method, params)
-          payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
-
-          http = Net::HTTP.new(@uri.host, @uri.port)
-          http.use_ssl = (@uri.scheme == "https")
-          http.open_timeout = @open_timeout
-          http.read_timeout = @read_timeout
-
-          path = @uri.path.empty? ? "/" : @uri.path
-          path = "#{path}?#{@uri.query}" if @uri.query
-
-          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
-
-          http_response = http.request(request)
-
-          unless http_response.is_a?(Net::HTTPSuccess)
-            raise Phronomy::ToolError,
-              "MCP HTTP server returned #{http_response.code}: #{http_response.body}"
-          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
-        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")
-        end
 
         def parse_schema_params(properties, required_names: [])
           properties.map do |name, schema|

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.11.1"
+  VERSION = "0.13.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-19 00:00:00.000000000 Z
+date: 2026-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -64,6 +64,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
 description: Phronomy is a Ruby AI agent framework that provides composable building
   blocks — Agents, Workflows, Tools, Filters, and Tracing — for building AI agents
   in Ruby. Powered by RubyLLM for LLM abstraction.