legate 0.1.0

data/lib/legate/mcp/server/legate_agent_adapter.rb

@@ -0,0 +1,170 @@
+# File: lib/legate/mcp/server/legate_agent_adapter.rb
+# frozen_string_literal: true
+
+require 'fast_mcp'
+require 'json' # Needed to parse tools
+require 'securerandom'
+require_relative '../../agent'
+require_relative '../../tool_registry'
+require_relative '../../session_service/base' # Need base for type check
+require_relative '../../event' # Needed for result processing
+require_relative '../../errors'
+require_relative '../../global_tool_manager' # Added require
+require_relative '../../global_definition_registry' # For definition lookups
+
+module Legate
+  module Mcp
+    module Server
+      # (Experimental) Adapter to expose an entire Legate::Agent (defined in GlobalDefinitionRegistry)
+      # as a single, simple tool via fast-mcp.
+      # The agent runs ephemerally for each call
+      class LegateAgentAdapter < FastMcp::Tool
+        # --- Class Configuration ---
+        # Using class instance variables set by `wrap`
+        class << self
+          attr_reader :agent_definition_name, :session_service
+        end
+        # -------------------------
+
+        # Dynamically creates a new FastMcp::Tool subclass that wraps an Legate Agent definition.
+        #
+        # @param agent_definition_name [String] The name of the agent definition in GlobalDefinitionRegistry.
+        # @param session_service_instance [Legate::SessionService::Base] The session service to use for temporary sessions.
+        # @return [Class<LegateAgentAdapter>] A new anonymous class inheriting from LegateAgentAdapter.
+        def self.wrap(agent_definition_name, session_service_instance)
+          raise ArgumentError, 'Agent definition name must be a non-empty String.' unless agent_definition_name.is_a?(String) && !agent_definition_name.empty?
+          raise ArgumentError, 'Session service instance must inherit from Legate::SessionService::Base.' unless session_service_instance.is_a?(Legate::SessionService::Base)
+
+          # Create the anonymous adapter class
+          Class.new(LegateAgentAdapter) do
+            # Store config on the generated class
+            @agent_definition_name = agent_definition_name
+            @session_service = session_service_instance
+
+            # Set fast-mcp tool metadata
+            # Use a modified tool name to avoid clashes if agent name = tool name
+            tool_name "run_agent_#{agent_definition_name}"
+            description "Runs the Legate Agent '#{agent_definition_name}' with the given prompt."
+
+            # Define the single prompt argument
+            arguments do
+              required(:prompt).filled(:string).description('The user input/prompt for the agent')
+            end
+
+            Mcp.logger.info("Created fast-mcp adapter for Legate agent definition: '#{agent_definition_name}'")
+          end
+        end
+
+        # Executes the wrapped Legate Agent for a single turn.
+        # Loads definition, creates temp session, runs task, cleans up.
+        #
+        # @param prompt [String] The user prompt.
+        # @return [Any] The final result payload from the agent's execution.
+        # @raise [StandardError] If agent execution fails or returns an error status.
+        def call(prompt:)
+          # Retrieve config from the *class* instance variables
+          agent_name = self.class.agent_definition_name
+          session_service = self.class.session_service
+          unless agent_name && session_service
+            raise NotImplementedError,
+                  'LegateAgentAdapter must be configured using .wrap first.'
+          end
+
+          Mcp.logger.info("Executing Legate Agent '#{agent_name}' via MCP adapter with prompt: '#{prompt}'")
+
+          agent = nil
+          temp_session = nil
+          begin
+            # 1. Load Agent Definition from GlobalDefinitionRegistry
+            Mcp.logger.debug("Loading agent definition '#{agent_name}' from GlobalDefinitionRegistry...")
+            agent_definition_object = Legate::GlobalDefinitionRegistry.find(agent_name.to_sym)
+
+            # Try get_definition if available (expanded API from Phase 2)
+            if !agent_definition_object && Legate::GlobalDefinitionRegistry.respond_to?(:get_definition)
+              definition_hash = Legate::GlobalDefinitionRegistry.get_definition(agent_name)
+              agent_definition_object = Legate::AgentDefinition.from_hash(definition_hash) if definition_hash
+            end
+
+            raise Legate::Mcp::Error, "Agent definition '#{agent_name}' not found in GlobalDefinitionRegistry." unless agent_definition_object
+
+            Mcp.logger.debug("Agent definition loaded for '#{agent_name}'.")
+
+            Mcp.logger.debug("AgentDefinition object ready: #{agent_definition_object.name}, Model=#{agent_definition_object.model_name}")
+
+            # 2. Create Temporary Session
+            Mcp.logger.debug('Creating temporary session...')
+            temp_session = session_service.create_session(app_name: agent_name,
+                                                          user_id: "mcp_temp_#{SecureRandom.hex(4)}")
+            Mcp.logger.debug("Temporary session created: #{temp_session.id}")
+
+            # 3. Instantiate Agent
+            Mcp.logger.debug("Instantiating agent '#{agent_definition_object.name}' with its definition object and session service...")
+
+            agent = Legate::Agent.new(
+              definition: agent_definition_object,
+              session_service: session_service # Pass the session_service from adapter config
+            )
+            # Tool loading is handled by Legate::Agent#initialize based on the definition object.
+
+            # 4. Start Agent & Run Task
+            Mcp.logger.debug('Starting ephemeral agent runtime...')
+            agent.start
+            Mcp.logger.debug("Running task in temp session #{temp_session.id}...")
+            final_event = agent.run_task(
+              session_id: temp_session.id,
+              user_input: prompt,
+              session_service: session_service
+            )
+            Mcp.logger.debug("Agent run_task finished. Final event: #{final_event.inspect}")
+
+            # 5. Process Result
+            raise StandardError, "Agent task finished with unexpected event format: #{final_event.inspect}" unless final_event.is_a?(Legate::Event) && final_event.role == :agent && final_event.content.is_a?(Hash)
+
+            result_content = final_event.content
+
+            case result_content[:status]
+            when :success
+              result_content[:result] # Return result payload
+            when :error
+              err_msg = result_content[:error_message] || 'Agent execution failed.'
+              Mcp.logger.error("Agent '#{agent_name}' execution failed: #{err_msg}")
+              raise StandardError, "Agent Error: #{err_msg}"
+            when :pending
+              job_id = result_content[:job_id] # Assuming key is :job_id
+              msg = result_content[:message] || 'Agent task resulted in a pending job.'
+              Mcp.logger.warn("Agent '#{agent_name}' execution ended with pending status (Job: #{job_id}). Returning as structured data.")
+              # Return pending structure similar to LegateToolAdapter for consistency
+              { status: 'pending', job_id: job_id, message: msg }
+            else
+              raise StandardError, "Agent task finished with unknown status: #{result_content[:status]}"
+            end
+          rescue Legate::Mcp::Error, StandardError => e
+            # Catch errors during setup or execution within the adapter
+            Mcp.logger.error("Error during LegateAgentAdapter call for '#{agent_name}': #{e.class} - #{e.message}")
+            Mcp.logger.error(e.backtrace.join("\n"))
+            # Let fast-mcp handle the error
+            raise StandardError, "Failed to run agent '#{agent_name}': #{e.message}"
+          ensure
+            # 6. Cleanup: Stop Agent & Delete Session
+            if agent&.running?
+              begin
+                Mcp.logger.debug('Stopping ephemeral agent runtime...')
+                agent.stop
+              rescue StandardError => e
+                Mcp.logger.error("Error stopping agent runtime during cleanup: #{e.message}")
+              end
+            end
+            if temp_session && session_service
+              begin
+                Mcp.logger.debug("Deleting temporary session: #{temp_session.id}")
+                session_service.delete_session(session_id: temp_session.id)
+              rescue StandardError => e
+                Mcp.logger.error("Error deleting temporary session #{temp_session.id}: #{e.message}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legate/mcp/server/legate_direct_agent_adapter.rb

@@ -0,0 +1,140 @@
+# File: lib/legate/mcp/server/legate_direct_agent_adapter.rb
+# frozen_string_literal: true
+
+require 'fast_mcp'
+require 'securerandom'
+require_relative '../../agent'
+require_relative '../../session_service/base'
+require_relative '../../event'
+require_relative '../../errors'
+
+module Legate
+  module Mcp
+    module Server
+      # Adapter to expose an Legate::Agent instance directly as a single tool via fast-mcp.
+      # The agent is used ephemerally for each call.
+      class LegateDirectAgentAdapter < FastMcp::Tool
+        class << self
+          attr_reader :legate_agent_instance, :session_service
+        end
+
+        # Dynamically creates a new FastMcp::Tool subclass that wraps the given Legate::Agent instance.
+        #
+        # @param agent_instance [Legate::Agent] The initialized Legate::Agent instance to wrap.
+        # @param session_service_instance [Legate::SessionService::Base] The session service for temporary sessions.
+        # @return [Class<LegateDirectAgentAdapter>] A new anonymous class inheriting from LegateDirectAgentAdapter.
+        def self.wrap(agent_instance, session_service_instance)
+          raise ArgumentError, 'Provided object is not a valid Legate::Agent instance.' unless agent_instance.is_a?(Legate::Agent)
+          raise ArgumentError, 'Session service instance must inherit from Legate::SessionService::Base.' unless session_service_instance.is_a?(Legate::SessionService::Base)
+
+          agent_name = agent_instance.name
+          agent_description = agent_instance.description
+
+          # Create the anonymous adapter class
+          Class.new(LegateDirectAgentAdapter) do
+            # Store instances on the generated class
+            @legate_agent_instance = agent_instance
+            @session_service = session_service_instance
+
+            # Set fast-mcp tool metadata
+            tool_name "run_agent_#{agent_name}" # Or just agent_name if desired
+            description "Runs the Legate Agent '#{agent_name}': #{agent_description}"
+
+            # Define the single prompt argument
+            arguments do
+              required(:prompt).filled(:string).description('The user input/prompt for the agent')
+            end
+
+            Mcp.logger.info("Created direct fast-mcp adapter for Legate agent instance: '#{agent_name}'")
+          end
+        end
+
+        # Executes the wrapped Legate Agent instance for a single turn.
+        #
+        # @param prompt [String] The user prompt.
+        # @return [Any] The final result payload from the agent's execution.
+        # @raise [StandardError] If agent execution fails or returns an error status.
+        def call(prompt:)
+          # Retrieve instances from the *class* instance variables
+          agent = self.class.legate_agent_instance
+          session_service = self.class.session_service
+          unless agent && session_service
+            raise NotImplementedError,
+                  'LegateDirectAgentAdapter must be configured using .wrap first.'
+          end
+
+          agent_name = agent.name
+          Mcp.logger.info("Executing Legate Agent '#{agent_name}' via direct MCP adapter with prompt: '#{prompt}'")
+
+          temp_session = nil
+          was_agent_already_running = agent.running?
+          begin
+            # 1. Create Temporary Session
+            Mcp.logger.debug('Creating temporary session...')
+            temp_session = session_service.create_session(app_name: agent_name,
+                                                          user_id: "mcp_direct_#{SecureRandom.hex(4)}")
+            Mcp.logger.debug("Temporary session created: #{temp_session.id}")
+
+            # 2. Ensure Agent is Running
+            unless was_agent_already_running
+              Mcp.logger.debug('Starting ephemeral agent runtime...')
+              agent.start
+            end
+
+            # 3. Run Task
+            Mcp.logger.debug("Running task in temp session #{temp_session.id}...")
+            final_event = agent.run_task(
+              session_id: temp_session.id,
+              user_input: prompt,
+              session_service: session_service
+            )
+            Mcp.logger.debug("Agent run_task finished. Final event: #{final_event.inspect}")
+
+            # 4. Process Result
+            raise StandardError, "Agent task finished with unexpected event format: #{final_event.inspect}" unless final_event.is_a?(Legate::Event) && final_event.role == :agent && final_event.content.is_a?(Hash)
+
+            result_content = final_event.content
+
+            case result_content[:status]
+            when :success
+              result_content[:result] # Return result payload
+            when :error
+              err_msg = result_content[:error_message] || 'Agent execution failed.'
+              Mcp.logger.error("Agent '#{agent_name}' execution failed: #{err_msg}")
+              raise StandardError, "Agent Error: #{err_msg}"
+            when :pending
+              job_id = result_content[:job_id]
+              msg = result_content[:message] || 'Agent task resulted in a pending job.'
+              Mcp.logger.warn("Agent '#{agent_name}' execution ended with pending status (Job: #{job_id}). Returning as structured data.")
+              { status: 'pending', job_id: job_id, message: msg }
+            else
+              raise StandardError, "Agent task finished with unknown status: #{result_content[:status]}"
+            end
+          rescue StandardError => e
+            Mcp.logger.error("Error during LegateDirectAgentAdapter call for '#{agent_name}': #{e.class} - #{e.message}")
+            Mcp.logger.error(e.backtrace.join("\n"))
+            raise StandardError, "Failed to run agent '#{agent_name}': #{e.message}"
+          ensure
+            # 5. Cleanup
+            if !was_agent_already_running && agent&.running?
+              begin
+                Mcp.logger.debug('Stopping ephemeral agent runtime...')
+                agent.stop
+              rescue StandardError => e
+                Mcp.logger.error("Error stopping agent runtime during cleanup: #{e.message}")
+              end
+            end
+            if temp_session && session_service
+              begin
+                Mcp.logger.debug("Deleting temporary session: #{temp_session.id}")
+                session_service.delete_session(session_id: temp_session.id)
+              rescue StandardError => e
+                Mcp.logger.error("Error deleting temporary session #{temp_session.id}: #{e.message}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legate/mcp/server/legate_tool_adapter.rb

@@ -0,0 +1,119 @@
+# File: lib/legate/mcp/server/legate_tool_adapter.rb
+# frozen_string_literal: true
+
+require 'fast_mcp'
+require_relative '../../tool'
+require_relative '../../tool_context'
+require_relative '../util/schema_converter'
+require_relative '../../errors'
+
+module Legate
+  module Mcp
+    module Server
+      # Base adapter class to expose an Legate::Tool as an MCP tool via fast-mcp.
+      # Use the `wrap` class method to dynamically create subclasses for specific Legate tools.
+      class LegateToolAdapter < FastMcp::Tool
+        # Use standard class instance variables for inheritable attributes
+        class << self
+          attr_reader :legate_tool_class # Provide a reader
+        end
+
+        # Dynamically creates a new FastMcp::Tool subclass that wraps the given Legate::Tool class.
+        #
+        # @param legate_tool_class [Class<Legate::Tool>] The Legate::Tool class to wrap.
+        # @return [Class<LegateToolAdapter>] A new anonymous class inheriting from LegateToolAdapter.
+        # @raise [ArgumentError] if the provided class is not an Legate::Tool.
+        def self.wrap(legate_tool_class)
+          raise ArgumentError, "Provided class #{legate_tool_class} is not a valid Legate::Tool class." unless legate_tool_class.is_a?(Class) && legate_tool_class < Legate::Tool
+
+          metadata = legate_tool_class.tool_metadata
+          # Check metadata hash and required keys
+          raise ArgumentError, "Legate::Tool #{legate_tool_class} has incomplete metadata (missing name or description)." unless metadata.is_a?(Hash) && metadata[:name] && metadata[:description]
+
+          mcp_tool_name = metadata[:name].to_s
+          mcp_description = metadata[:description]
+          legate_params = metadata[:parameters] || {}
+
+          # Convert Legate params to a Dry::Schema proc
+          schema_proc = Legate::Mcp::Util::SchemaConverter.legate_to_dry_schema(legate_params)
+
+          # Create the anonymous adapter class
+          Class.new(LegateToolAdapter) do
+            @legate_tool_class = legate_tool_class
+
+            # Use fast-mcp DSL methods inside the class definition block
+            tool_name mcp_tool_name # Use DSL method
+            description mcp_description
+            arguments(&schema_proc) if schema_proc
+
+            Legate.logger.info("Created fast-mcp adapter for Legate tool: #{legate_tool_class} as '#{mcp_tool_name}'")
+          end
+        end
+
+        # The `call` method executed by fast-mcp when the tool is invoked.
+        # Instantiates the wrapped Legate tool, executes it with a dummy context,
+        # and translates the result/error.
+        #
+        # @param args [Hash] Keyword arguments matching the defined schema.
+        # @return [Any] The successful result payload for the MCP response.
+        # @raise [StandardError] If the Legate tool returns an error status.
+        # @raise [NotImplementedError] If the Legate tool returns a pending status (needs CheckJobStatusTool).
+        def call(**args)
+          # Access the class instance variable via the reader
+          tool_class = self.class.legate_tool_class
+          raise NotImplementedError, 'LegateToolAdapter cannot be used directly, use .wrap first.' unless tool_class
+
+          legate_instance = tool_class.new
+
+          # Convert string keys from MCP/fast-mcp back to symbols for Legate tool
+          legate_params = args.transform_keys(&:to_sym)
+
+          # Create a dummy/minimal context for the Legate tool execution
+          # TODO: Can we provide more meaningful context if running within a larger MCP session?
+          dummy_context = Legate::ToolContext.new(
+            session_id: SecureRandom.uuid, # Generic ID
+            user_id: 'mcp_user',
+            app_name: 'mcp_server',
+            tool_registry: Legate::ToolRegistry.new # Create a new, empty registry for this dummy context
+            # No session_service available here easily
+          )
+
+          Legate.logger.info("Executing Legate tool '#{self.class.tool_name}' via MCP adapter with params: #{legate_params.inspect}")
+
+          begin
+            result_hash = legate_instance.execute(legate_params, dummy_context)
+          rescue StandardError => e
+            # Catch errors during the tool's execute method itself
+            Mcp.logger.error("Error during underlying Legate tool execution for '#{self.class.tool_name}': #{e.class} - #{e.message}")
+            # Let fast-mcp handle this standard error, it should map to an MCP error response
+            raise StandardError, "Execution Error in Legate tool '#{self.class.tool_name}': #{e.message}"
+          end
+
+          Legate.logger.debug("Legate tool '#{self.class.tool_name}' returned hash: #{result_hash.inspect}")
+
+          # Translate Legate result hash to MCP return/error
+          case result_hash[:status]
+          when :success
+            result_hash[:result] # Return the raw result for MCP
+          when :error
+            error_message = result_hash[:error_message] || "Unknown error from Legate tool '#{self.class.tool_name}'"
+            Legate.logger.error("Legate tool '#{self.class.tool_name}' reported error: #{error_message}")
+            # Raise a standard error, fast-mcp should convert this to an MCP error response
+            raise StandardError, error_message
+          when :pending
+            job_id = result_hash[:job_id] # Assuming the key is :job_id now
+            message = result_hash[:message] || "Legate tool '#{self.class.tool_name}' started an async job."
+            Legate.logger.info("Legate tool '#{self.class.tool_name}' returned pending status (Job ID: #{job_id})")
+            # Return a structured hash indicating pending status (as per FR2.2 recommendation)
+            # Requires CheckJobStatusTool to be exposed separately via MCP.
+            { status: 'pending', job_id: job_id, message: message }
+          else
+            unknown_status_msg = "Legate tool '#{self.class.tool_name}' returned unknown status: #{result_hash[:status]}"
+            Mcp.logger.error(unknown_status_msg)
+            raise StandardError, unknown_status_msg
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legate/mcp/tool_wrapper.rb

@@ -0,0 +1,138 @@
+# File: lib/legate/mcp/tool_wrapper.rb
+# frozen_string_literal: true
+
+require_relative '../tool'
+require_relative '../tool_registry'
+require_relative 'util/schema_converter'
+require_relative 'client' # Need client for execution
+require_relative '../errors'
+
+module Legate
+  module Mcp
+    # Base class for dynamically created Legate::Tool wrappers around external MCP tools.
+    # Instances of anonymous subclasses generated by `from_mcp_schema` are used.
+    class ToolWrapper < Legate::Tool
+      # General description for the base wrapper concept
+      tool_description 'Internal base class for dynamically wrapping external MCP tools. Instances are generated automatically.'
+
+      class << self
+        # References stored on the dynamically created subclass
+        attr_accessor :mcp_client, :mcp_tool_name, :mcp_input_schema
+      end
+
+      # Creates a new anonymous Legate::Tool subclass that wraps an external MCP tool.
+      # Registers the new tool class with the provided Legate::ToolRegistry instance.
+      #
+      # @param mcp_schema [Hash] The tool schema hash from MCP server.
+      # @param mcp_client [Legate::Mcp::Client] The client instance.
+      # @param tool_registry [Legate::ToolRegistry] The specific registry instance to register with.
+      # @return [Class] The newly created anonymous ToolWrapper subclass, or nil.
+      def self.from_mcp_schema(mcp_schema, mcp_client, tool_registry)
+        # Validate inputs including the registry
+        unless mcp_schema.is_a?(Hash) && mcp_schema[:name] &&
+               mcp_client.is_a?(Legate::Mcp::Client) &&
+               tool_registry.is_a?(Legate::ToolRegistry)
+          Mcp.logger.error('Invalid input for ToolWrapper.from_mcp_schema: Schema, Client, or Registry invalid.')
+          return nil
+        end
+
+        mcp_name = mcp_schema[:name]
+        mcp_description = mcp_schema[:description] || "MCP Tool: #{mcp_name}"
+        mcp_input_schema = mcp_schema[:inputSchema] || {}
+        mcp_properties = mcp_input_schema[:properties] || {}
+        mcp_required = mcp_input_schema[:required] || []
+
+        legate_params = Util::SchemaConverter.json_to_legate(mcp_properties, mcp_required)
+
+        # Create anonymous class
+        wrapper_class = Class.new(ToolWrapper) do
+          # --- CAPTURE local variables for use in method definitions ---
+          captured_mcp_name_sym = mcp_name.to_sym
+          captured_mcp_description = mcp_description
+          captured_legate_params = legate_params
+
+          # Store references needed for execution on the class itself
+          self.mcp_client = mcp_client
+          self.mcp_tool_name = mcp_name # Keep original string name for execution
+          self.mcp_input_schema = mcp_input_schema
+
+          # --- Define the tool_metadata method explicitly on this anonymous class ---
+          define_singleton_method(:tool_metadata) do
+            {
+              name: captured_mcp_name_sym,
+              description: captured_mcp_description,
+              parameters: captured_legate_params
+            }
+          end
+
+          # --- ALSO explicitly define the individual readers for robustness ---
+          # (These might be called by other parts of Legate or ToolRegistry indirectly)
+          define_singleton_method(:tool_name) { captured_mcp_name_sym }
+          define_singleton_method(:description) { captured_mcp_description }
+          define_singleton_method(:parameters_definition) { captured_legate_params }
+
+          # --- Keep the original define_metadata call as well for global registration ---
+          # Although redundant for metadata retrieval via tool_metadata, it handles global registration.
+          define_metadata(
+            name: captured_mcp_name_sym,
+            description: captured_mcp_description,
+            parameters: captured_legate_params
+          )
+        end
+
+        Mcp.logger.info("Created Legate Tool wrapper for MCP tool: '#{mcp_name}'")
+
+        # Register with the PROVIDED registry instance
+        begin
+          tool_registry.register(mcp_name.to_sym, wrapper_class)
+          Mcp.logger.debug("Registered wrapper for MCP tool '#{mcp_name}' with provided ToolRegistry.")
+        rescue Legate::ToolRegistry::ToolExistsError => e
+          Mcp.logger.warn("MCP Tool '#{mcp_name}' conflicts with an existing tool in provided registry: #{e.message}")
+        rescue StandardError => e
+          Mcp.logger.error("Failed to register wrapper for MCP tool '#{mcp_name}' with provided registry: #{e.message}")
+          return nil
+        end
+
+        wrapper_class
+      end
+
+      # Executes the wrapped MCP tool via the stored MCP client.
+      #
+      # @param params [Hash] Parameters provided by the Legate agent/planner.
+      # @param context [Legate::ToolContext] The execution context (less relevant for external tools).
+      # @return [Hash] Legate status hash ({status: :success/:error, result:/error_message:}).
+      def perform_execution(params, _context)
+        self.class.mcp_client || begin
+          Mcp.logger.error("MCP Client not configured for tool wrapper: #{self.class.mcp_tool_name}")
+          return { status: :error, error_message: 'Internal configuration error: MCP Client missing.' }
+        end
+
+        mcp_tool_name_str = self.class.mcp_tool_name
+        mcp_client_instance = self.class.mcp_client
+
+        Mcp.logger.info("Executing wrapped MCP tool '#{mcp_tool_name_str}' with params: #{params.inspect}")
+
+        # TODO: V1.1 - Translate Legate params back to JSON structure based on mcp_input_schema?
+        # For V1, assume flat hash structure matches between Legate and MCP tool for basic types.
+        mcp_args = params.transform_keys(&:to_s) # Convert symbol keys back to strings for JSON
+
+        begin
+          result = mcp_client_instance.call_tool(mcp_tool_name_str, mcp_args)
+          Mcp.logger.info("MCP tool '#{mcp_tool_name_str}' executed successfully.")
+          { status: :success, result: result }
+        rescue Legate::Mcp::RemoteToolError => e
+          Mcp.logger.error("MCP tool '#{mcp_tool_name_str}' returned an error: #{e}")
+          { status: :error, error_message: "MCP Tool Error: #{e.message}",
+            error_details: { code: e.code, data: e.data } }
+        rescue Legate::Mcp::ConnectionError, Legate::Mcp::ProtocolError => e
+          Mcp.logger.error("MCP communication error during '#{mcp_tool_name_str}' execution: #{e.message}")
+          { status: :error, error_message: "MCP Communication Error: #{e.message}" }
+        rescue StandardError => e
+          Mcp.logger.error("Unexpected error during MCP tool '#{mcp_tool_name_str}' execution: #{e.class} - #{e.message}")
+          Mcp.logger.error(e.backtrace.join("\n"))
+          { status: :error, error_message: "Internal Error: #{e.message}" }
+        end
+      end
+    end
+  end
+end