phronomy 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b5c5fc2f42107629541d051e1330e90e48298ccf19192440e7be77a30b6ca68
-  data.tar.gz: 78e4440ec72afb39b7021810c8cdfc8de44f94f15d97442f91000eff50aa967c
+  metadata.gz: dd9fb679db0e4d4c582a82dad543ca0d93806878e0936404cd4255d2a48a741b
+  data.tar.gz: 511a6bfb90ec0524aafb201996bc251c9b1923a2d3ff4d1b389aa7d62f2d3395
 SHA512:
-  metadata.gz: 79c98ed427ae1c55d245f871ba9248279199496b27535dfaca2b94d89998bfa95583c8b87a7c192f00f5143c755f6234a4f513ec37c86172ea2c286579e9b72a
-  data.tar.gz: 30d8c27a6a0a0d003da85438ee903fc73af648079c83ab42618ce53d98570b9cfaa39144a71c49e8cce77d94b0f679bb82b87b484e06e654eb8298379e8dc093
+  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/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

@@ -308,7 +308,7 @@ module Phronomy
         tc_args = tc.arguments
         tc_name = tc.name
         ct = ctx.config[:cancellation_token]
-        awaitable = tool_instance.call_async(tc_args, cancellation_token: ct)
+        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

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/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(
@@ -41,12 +39,18 @@ module Phronomy
         # @return [Mcp] a configured subclass instance ready for use with an Agent
         # @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.
+          # 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
@@ -59,14 +63,27 @@ module Phronomy
           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, headers: headers)
+            MCP::Client::HTTP.new(url: uri, headers: headers)
           else
             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 { |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)
@@ -82,336 +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)
             hdrs = self.class.instance_variable_get(:@mcp_headers) || {}
-            @mcp_transport = self.class.send(:build_transport, uri, headers: hdrs)
-          end
-
-          klass.define_method(:execute) do |**args|
-            @mcp_transport.call_tool(tool_name, args)
+            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
-            # 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.
-          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.12.0"
+  VERSION = "0.13.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  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.