legate 0.1.0

data/examples/advanced/mcp/legate_mcp_server_resource_example.rb

@@ -0,0 +1,182 @@
+# File: ./examples/advanced/mcp/legate_mcp_server_resource_example.rb
+# !/usr/bin/env ruby
+# frozen_string_literal: true
+
+# --- Example: Exposing a multi-tool Legate Agent via MCP ---
+# -------------------------------------------------------------
+
+ENV['LEGATE_LOG_LEVEL'] = 'ERROR'
+ENV['LEGATE_LOG_TARGET'] = 'STDERR'
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'legate'
+Legate.load_environment # Handle Bundler, Dotenv, etc.
+require 'fast_mcp'
+# require 'thread' # No longer needed
+# require 'json' # No longer needed
+# require 'singleton' # No longer needed
+require 'logger'
+require 'securerandom'
+require 'net/http' # Needed for CatFactResource
+require 'uri'      # Needed for CatFactResource
+
+# Load the necessary Legate MCP components
+require 'legate/mcp'
+require 'legate/mcp/server/legate_direct_agent_adapter'
+
+# Load Legate components for direct agent instantiation
+require 'legate/agent'
+require 'legate/session_service/in_memory'
+
+# --- Load ALL required Legate Tool Classes ---
+require 'legate/tools/calculator'
+require 'legate/tools/agent_tool'
+require 'legate/tools/random_number_tool'
+require 'legate/tools/sleepy_tool'
+require 'legate/tools/cat_facts'
+require 'legate/tools/check_job_status_tool'
+require 'legate/tools/echo'
+# ------------------------------------------
+
+# === FastMcp Components Setup ===
+
+# --- NEW: Define MCP Resources based on Legate Tool functionality ---
+
+# 1. Random Number Resource
+class RandomNumberResource < FastMcp::Resource
+  include Singleton
+  uri 'random_number'
+  resource_name 'RandomNumber'
+  description 'Provides a random floating-point number between 0 and 1.'
+  mime_type 'application/json'
+
+  def read
+    # Generate a new random number on each read
+    { value: rand }
+  end
+
+  def content
+    JSON.generate(read)
+  end
+end
+
+# 2. Cat Fact Resource
+class CatFactResource < FastMcp::Resource
+  include Singleton
+  uri 'catfact'
+  resource_name 'CurrentCatFact'
+  description 'Provides a random cat fact from catfact.ninja.'
+  mime_type 'application/json'
+
+  CATFACT_API_URI = URI('https://catfact.ninja/fact')
+
+  def read
+    # Fetch a new fact on each read
+    response = Net::HTTP.get_response(CATFACT_API_URI)
+    if response.is_a?(Net::HTTPSuccess)
+      data = JSON.parse(response.body)
+      { fact: data['fact'] || 'Could not retrieve fact.' }
+    else
+      Legate.logger.error("CatFactResource: Failed to fetch cat fact. Status: #{response.code}")
+      { fact: "Error fetching fact: #{response.code}" }
+    end
+  rescue StandardError => e
+    Legate.logger.error("CatFactResource: Error fetching cat fact: #{e.message}")
+    { fact: "Error fetching fact: #{e.message}" }
+  end
+
+  def content
+    JSON.generate(read)
+  end
+end
+
+# --- NEW: Define MCP Tools to explicitly interact with the new Resources ---
+
+class GetNewRandomNumberTool < FastMcp::Tool
+  description 'Gets a new random number from the RandomNumber resource.'
+  tool_name 'getrandomnumber'
+  arguments {}
+  def call(**_args)
+    # Access the singleton instance and read its current state
+    RandomNumberResource.instance.read[:value]
+  end
+end
+
+class GetNewCatFactTool < FastMcp::Tool
+  description 'Gets a new cat fact from the CatFact resource.'
+  tool_name 'getcatfact'
+  arguments {}
+  def call(**_args)
+    # Access the singleton instance and trigger a read
+    CatFactResource.instance.read[:fact]
+  end
+end
+
+# --- 1. Instantiate Master Legate Agent and Wrap it ---
+begin
+  # List all the tool CLASSES to be given to the agent
+  all_tool_classes = [
+    Legate::Tools::Calculator,
+    Legate::Tools::AgentTool,
+    Legate::Tools::RandomNumberTool,
+    Legate::Tools::SleepyTool,
+    Legate::Tools::CatFacts,
+    Legate::Tools::CheckJobStatusTool,
+    Legate::Tools::Echo,
+    GetNewRandomNumberTool,
+    GetNewCatFactTool
+  ]
+
+  # Create the Legate::Agent instance with all tools
+  master_agent = Legate::Agent.new(
+    name: 'master_agent',
+    description: 'An agent with access to all built-in Legate tools.',
+    model_name: 'gemini-3.5-flash',
+    tool_classes: all_tool_classes
+  )
+
+  # Create a session service instance
+  session_service = Legate::SessionService::InMemory.new
+
+  # Use the direct adapter to wrap the master agent instance
+  AdaptedMasterAgentTool = Legate::Mcp::Server::LegateDirectAgentAdapter.wrap(master_agent, session_service)
+rescue StandardError => e
+  warn "Error setting up Legate Master Agent or Adapter: #{e.message}"
+  warn e.backtrace.join("\n")
+  exit(1)
+end
+# === End FastMcp Components Setup ===
+
+# === Setup and Start the MCP Server ===
+
+mcp_server = FastMcp::Server.new(
+  name: 'Legate Master Agent Server', # Updated server name
+  version: Legate::VERSION
+)
+
+# Register the new Resources
+mcp_server.register_resource(RandomNumberResource)
+mcp_server.register_resource(CatFactResource)
+
+# Register the Tools (Master Agent + Resource-specific tools)
+mcp_server.register_tools(
+  AdaptedMasterAgentTool,
+  GetNewRandomNumberTool,
+  GetNewCatFactTool
+)
+
+# Start the server using STDIO transport
+warn '--- Starting Legate Master Agent MCP Server (STDIO) ---'
+warn "Resources: #{[RandomNumberResource.uri, CatFactResource.uri].join(', ')}"
+warn "Tools Available: #{[AdaptedMasterAgentTool.tool_name, GetNewRandomNumberTool.tool_name,
+                          GetNewCatFactTool.tool_name].join(', ')}"
+warn 'Waiting for MCP client requests on STDIN...'
+begin
+  mcp_server.start
+rescue Interrupt
+rescue StandardError => e
+  warn "MCP server crashed: #{e.class} - #{e.message}"
+  warn e.backtrace.join("\n")
+ensure
+  warn "\n--- Legate Master Agent MCP Server Stopped ---"
+end

data/examples/advanced/mcp/mcp_resource_server_example.rb

@@ -0,0 +1,309 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# --- Usage ---
+# 1. Run this script from your project root:
+#    bundle exec ruby examples/advanced/mcp/mcp_resource_server_example.rb
+#
+# 2. In another terminal, inspect using mcp-inspector:
+#    npx mcp-inspector --stdio 'bundle exec ruby examples/advanced/mcp/mcp_resource_server_example.rb'
+#
+# 3. Example inspector commands:
+#    > resources/list
+#    > resources/read {"uri": "counter"}
+#    > tools/list # Should show counter tools AND run_calculator_agent
+#    > tools/call {"name": "run_calculator_agent", "arguments": {"prompt": "What is 5 * 8?"}}
+#    > tools/call {"name": "run_calculator_agent", "arguments": {"prompt": "Add 100 and 23"}}
+#    > tools/call {"name": "incrementcounter", "arguments": {}}
+# -------------------------------------------------------------
+
+# --- IMPORTANT: Configure Legate logging for MCP compatibility ---
+# Configure ENV variables before requiring Legate to control logging
+ENV['LEGATE_LOG_LEVEL'] = 'ERROR' # Set high level to minimize Legate output
+ENV['LEGATE_LOG_TARGET'] = 'STDERR' # Redirect Legate logs to STDERR
+
+# Now load the libraries
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'legate'
+Legate.load_environment # Handle Bundler, Dotenv, etc.
+require 'fast_mcp' # Load the fast-mcp library
+require 'json'     # Needed for JSON generation in #content
+require 'singleton' # Needed for Singleton pattern
+require 'logger' # For Logger constant access
+# ---------------------------------------------
+
+# === Legate Components Setup ===
+
+# 1. Define the Legate Agent that uses the Calculator
+calculator_agent = Legate::Agent.new(
+  name: 'calculator_agent_instance', # Runtime instance name
+  description: 'An agent that can perform calculations.',
+  model_name: 'gemini-test-model', # Specify a model (even if dummy for this example)
+  tool_classes: [Legate::Tools::Calculator] # Provide the CLASS
+)
+# Start the agent runtime (needed for run_task)
+calculator_agent.start
+
+# 2. Create a Session Service for the Agent
+# Using InMemory for this self-contained example
+session_service = Legate::SessionService::InMemory.new
+
+# === End Legate Components Setup ===
+
+# === FastMcp Components Setup ===
+
+# --- 1. Define the Counter Resource ---
+class CounterResource < FastMcp::Resource
+  include Singleton # Use Singleton pattern
+
+  # --- Define metadata via class methods ---
+  def self.uri
+    'counter'
+  end
+
+  def self.resource_name
+    'Counter' # Changed back to capitalized as per original example convention
+  end
+
+  def self.description
+    'A simple counter resource'
+  end
+
+  def self.mime_type
+    'application/json'
+  end
+  # --- End metadata via class methods ---
+
+  attr_reader :count
+
+  def initialize # Singleton's initialize
+    # Removed super call
+    @count = 0
+    @lock = Mutex.new
+  end
+
+  def read; @lock.synchronize { { value: @count } }; end
+  def content; JSON.generate(read); end
+
+  def increment
+    new_value = nil
+    @lock.synchronize {
+      @count += 1
+      new_value = @count
+    }
+    notify_change # Moved here
+    new_value
+  end
+
+  def decrement
+    new_value = nil
+    @lock.synchronize {
+      @count -= 1
+      new_value = @count
+    }
+    notify_change # Moved here
+    new_value
+  end
+
+  def get_value; @lock.synchronize { @count }; end
+end
+
+# --- 2. Define Counter Tools ---
+class IncrementCounterTool < FastMcp::Tool
+  # --- Define metadata via class methods ---
+  def self.tool_name
+    'incrementcounter'
+  end
+
+  def self.description
+    'Increments the counter resource by 1'
+  end
+  # --- End metadata via class methods ---
+
+  # Server accessor needed by FastMcp for notify_change
+  attr_accessor :server
+
+  arguments {} # Define arguments block
+  def call(**_args)
+    counter = CounterResource.instance
+    new_value = counter.increment # Resource handles notify_change
+    "Counter incremented. New value: #{new_value}"
+  end
+end
+
+class DecrementCounterTool < FastMcp::Tool
+  # --- Define metadata via class methods ---
+  def self.tool_name
+    'decrementcounter'
+  end
+
+  def self.description
+    'Decrements the counter resource by 1'
+  end
+  # --- End metadata via class methods ---
+
+  # Server accessor needed by FastMcp for notify_change
+  attr_accessor :server
+
+  arguments {} # Define arguments block
+  def call(**_args)
+    counter = CounterResource.instance
+    new_value = counter.decrement # Resource handles notify_change
+    "Counter decremented. New value: #{new_value}"
+  end
+end
+
+class GetCounterTool < FastMcp::Tool
+  # --- Define metadata via class methods ---
+  def self.tool_name
+    'getcounter'
+  end
+
+  def self.description
+    'Gets the current value of the counter resource'
+  end
+  # --- End metadata via class methods ---
+
+  # Server accessor needed by FastMcp
+  attr_accessor :server
+
+  arguments {} # Define arguments block
+  def call(**_args)
+    counter = CounterResource.instance
+    counter.get_value
+  end
+end
+
+# --- 3. Define the Legate Agent Adapter Tool ---
+class InlineAgentToolAdapter < FastMcp::Tool
+  # --- Define metadata via class methods ---
+  def self.tool_name
+    'run_calculator_agent'
+  end
+
+  def self.description
+    'Runs the internal Legate Calculator Agent with the given prompt.'
+  end
+  # --- End metadata via class methods ---
+
+  # Server accessor needed by FastMcp
+  attr_accessor :server
+
+  # --- Define arguments using DSL block ---
+  arguments do
+    required(:prompt).filled(:string).description('The user input/prompt for the agent')
+  end
+  # --- End arguments block ---
+
+  # --- Use class variables for dependencies (workaround for class-based registration) ---
+  @@agent = nil
+  @@session_service = nil
+
+  # Class method to set up the references needed *before* registration
+  def self.setup(agent, session_service)
+    @@agent = agent
+    @@session_service = session_service
+  end
+  # --- End class variables setup ---
+
+  # No instance initialize needed if dependencies are class-level
+
+  def call(prompt:)
+    # Make sure dependencies are set up via the class method
+    raise 'Agent not configured via InlineAgentToolAdapter.setup' unless @@agent
+    raise 'Session service not configured via InlineAgentToolAdapter.setup' unless @@session_service
+
+    temp_session = nil
+    # Legate logs are silenced via ENV var setup
+
+    begin
+      temp_session = @@session_service.create_session(
+        app_name: @@agent.name, # Use agent name from class variable
+        user_id: "mcp_inline_#{SecureRandom.hex(4)}"
+      )
+
+      final_event = @@agent.run_task( # Use agent from class variable
+        session_id: temp_session.id,
+        user_input: prompt,
+        session_service: @@session_service # Use service from class variable
+      )
+
+      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]
+      when :error
+        err_msg = result_content[:error_message] || 'Agent execution failed.'
+        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.'
+        { status: 'pending', job_id: job_id, message: msg }
+      else
+        raise StandardError, "Agent task finished with unknown status: #{result_content[:status]}"
+      end
+    rescue StandardError => e
+      # Log error to STDERR since Legate logger might be fully silenced
+      warn "InlineAgentToolAdapter Error during call: #{e.class} - #{e.message}"
+      warn e.backtrace.first(5).join("\n")
+      raise # Re-raise the error for fast-mcp to handle
+    ensure
+      if temp_session && @@session_service
+        begin
+          @@session_service.delete_session(session_id: temp_session.id)
+        rescue StandardError => e
+          # Log deletion error to STDERR
+          warn "InlineAgentToolAdapter: Error deleting temp session #{temp_session.id}: #{e.message}"
+        end
+      end
+    end
+  end
+end
+# --- End Legate Agent Adapter Tool ---
+
+# === Setup and Start the MCP Server ===
+
+# --- Configure the adapter class BEFORE registration ---
+InlineAgentToolAdapter.setup(calculator_agent, session_service)
+# --- END Configure Adapter ---
+
+# --- Create server without logger (following sample) ---
+mcp_server = FastMcp::Server.new(
+  name: 'Legate Combined Example Server',
+  version: Legate::VERSION
+)
+# --- END ---
+
+# Register the resource class
+mcp_server.register_resource(CounterResource)
+
+# --- Register TOOL CLASSES ---
+mcp_server.register_tools(
+  IncrementCounterTool,
+  DecrementCounterTool,
+  GetCounterTool,
+  InlineAgentToolAdapter # Register the adapter class
+)
+# --- END Registration ---
+
+# Start the server (defaults to STDIO transport)
+# Output status messages to STDERR so they don't interfere with STDOUT protocol
+warn '--- Starting Legate Combined MCP Server (STDIO) ---'
+warn 'Resource: counter'
+warn 'Tools: incrementcounter, decrementcounter, getcounter, run_calculator_agent'
+warn 'Waiting for MCP client requests on STDIN...'
+begin
+  mcp_server.start # This uses STDIO by default
+rescue Interrupt
+  # Expected on Ctrl+C
+rescue StandardError => e
+  warn "MCP server crashed: #{e.class} - #{e.message}"
+  warn e.backtrace.join("\n")
+ensure
+  warn "\n--- Legate Combined MCP Server Stopped ---"
+  # Ensure the Legate agent runtime is stopped on exit
+  calculator_agent.stop if calculator_agent&.running?
+end

data/examples/advanced/mcp/mcp_server_async.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# --- Configure Logging First! ---
+# Set log level and target *before* requiring Legate to ensure logger initializes correctly.
+ENV['LEGATE_LOG_LEVEL'] = 'ERROR' # Or INFO/DEBUG for more verbose output
+ENV['LEGATE_LOG_TARGET'] = 'STDERR' # Send logs to STDERR to avoid interfering with MCP STDOUT communication
+# -------------------------------
+
+# Example: Exposing Async Legate Tools via MCP using fast-mcp
+#
+# This example demonstrates how to wrap an asynchronous Legate tool (like SleepyTool)
+# and the necessary Legate::Tools::CheckJobStatusTool using the LegateToolAdapter
+# so they can be called by an MCP client.
+#
+# Requires:
+#   - legate gem with MCP support installed
+#   - fast-mcp gem installed
+#
+# To Run:
+#   1. Execute this script: `bundle exec ruby examples/advanced/mcp/mcp_server_async.rb`
+#   2. In another terminal, use mcp-inspector: `npx @modelcontextprotocol/inspector examples/advanced/mcp/mcp_server_async.rb`
+#   3. In the inspector:
+#      - Call 'start_sleepy_job' (tool name from SleepyTool metadata) with duration (e.g., 5 seconds).
+#      - Observe the pending response with a job_id.
+#      - Call 'check_job_status' with the received job_id.
+#      - Check status repeatedly until it shows success or error.
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'legate'
+Legate.load_environment # Handle Bundler, Dotenv, etc.
+require 'fast_mcp' # Load fast-mcp gem
+
+# Ensure required Legate components are loaded
+require 'legate/tools/base_async_job_tool'
+require 'legate/tools/sleepy_tool' # Example async tool
+require 'legate/tools/check_job_status_tool' # Tool to check job status
+require 'legate/mcp/server/legate_tool_adapter' # The adapter itself
+
+# --- Create the FastMcp Server Instance ---
+Legate.logger.info('Creating fast-mcp server...')
+# Use the logger from Legate for consistency
+mcp_server = FastMcp::Server.new(name: 'legate-async-mcp-server', version: '1.0.0')
+
+# --- Wrap the Legate Tools using the Adapter ---
+Legate.logger.info('Wrapping Legate tools for MCP...')
+
+begin
+  # Wrap the asynchronous tool (SleepyTool)
+  wrapped_sleepy_tool = Legate::Mcp::Server::LegateToolAdapter.wrap(Legate::Tools::SleepyTool)
+  Legate.logger.info("Wrapped SleepyTool as: #{wrapped_sleepy_tool.tool_name}")
+
+  # Wrap the CheckJobStatusTool
+  wrapped_check_job_tool = Legate::Mcp::Server::LegateToolAdapter.wrap(Legate::Tools::CheckJobStatusTool)
+  Legate.logger.info("Wrapped CheckJobStatusTool as: #{wrapped_check_job_tool.tool_name}")
+
+  # --- Register Wrapped Tools with the FastMcp Server ---
+  Legate.logger.info('Registering wrapped tools with fast-mcp server...')
+  mcp_server.register_tool(wrapped_sleepy_tool)
+  mcp_server.register_tool(wrapped_check_job_tool)
+rescue ArgumentError => e
+  Legate.logger.fatal("Failed to wrap Legate tools: #{e.message}")
+  Legate.logger.fatal('Ensure the Legate::Tool classes have complete metadata.')
+  exit(1)
+rescue StandardError => e
+  Legate.logger.fatal("An unexpected error occurred during setup: #{e.message}")
+  Legate.logger.fatal(e.backtrace.join("\n"))
+  exit(1)
+end
+
+# --- Start the Server (using STDIO transport) ---
+Legate.logger.info('Starting fast-mcp server with STDIO transport...')
+# This will block and listen for JSON-RPC messages on STDIN/STDOUT
+mcp_server.start
+
+Legate.logger.info('Server finished.')

data/examples/advanced/mcp/mcp_server_async_tools.rb

@@ -0,0 +1,122 @@
+# File: examples/advanced/mcp/mcp_server_async_tools.rb
+# frozen_string_literal: true
+
+# --- Example: MCP Server with Async Legate Tools ---
+#
+# This script demonstrates how to expose both async tools and the
+# CheckJobStatusTool via MCP. It shows:
+# 1. How to wrap async tools for MCP exposure
+# 2. How to expose the CheckJobStatusTool
+# 3. How to use both tools together via MCP
+#
+# Prerequisites:
+#   - Run `bundle install` to install dependencies
+#   - Run this script: bundle exec ruby examples/advanced/mcp/mcp_server_async_tools.rb
+#
+# Example MCP client interactions:
+#   Initialize server:
+#   {"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}
+#
+#   List tools:
+#   {"jsonrpc": "2.0", "method": "listTools", "params": {}, "id": 2}
+#
+#   Call SleepyTool:
+#   {"jsonrpc": "2.0", "method": "callTool", "params": {"name": "sleepy_tool", "parameters": {"duration": 5}}, "id": 3}
+#
+#   Check job status:
+#   {"jsonrpc": "2.0", "method": "callTool", "params": {"name": "check_job_status", "parameters": {"job_id": "job_id_from_sleepy_tool"}}, "id": 4}
+#
+# -------------------------------------------------------------
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'legate'
+Legate.load_environment # Handle Bundler, Dotenv, etc.
+
+require 'legate'
+require 'legate/mcp'
+require 'fast_mcp'
+require 'legate/tools/sleepy_tool'
+require 'legate/tools/check_job_status_tool'
+
+# Configure Legate logger
+Legate.logger.level = Logger::INFO
+
+# Create and register the SleepyTool
+class SleepyToolWrapper < FastMcp::Tool
+  description 'Sleep for a specified duration'
+
+  arguments do
+    required(:duration).filled(:integer, gt?: 0).description('Duration to sleep in seconds')
+    required(:message).filled(:string).description('A message to include in the final result')
+  end
+
+  def call(args)
+    tool = Legate::Tools::SleepyTool.new
+    context = Legate::ToolContext.new(
+      session_id: 'mcp-session',
+      user_id: 'mcp-user',
+      app_name: 'mcp-server',
+      tool_registry: Legate::ToolRegistry.new
+    )
+    result = tool.execute({ duration: args[:duration], message: args[:message] }, context)
+
+    case result[:status]
+    when :success
+      result[:result]
+    when :pending
+      {
+        status: 'pending',
+        job_id: result[:job_id],
+        message: "Sleepy job started with duration #{args[:duration]}s and message: #{args[:message]}"
+      }
+    when :error
+      raise StandardError, result[:error_message]
+    end
+  end
+end
+
+# Create and register the CheckJobStatusTool
+class CheckJobStatusToolWrapper < FastMcp::Tool
+  description 'Check the status of a background job'
+
+  arguments do
+    required(:job_id).filled(:string, min_size?: 1).description('The ID of the job to check')
+  end
+
+  def call(args)
+    tool = Legate::Tools::CheckJobStatusTool.new
+    context = Legate::ToolContext.new(
+      session_id: 'mcp-session',
+      user_id: 'mcp-user',
+      app_name: 'mcp-server',
+      tool_registry: Legate::ToolRegistry.new
+    )
+    result = tool.execute({ job_id: args[:job_id] }, context)
+
+    case result[:status]
+    when :success
+      result[:result]
+    when :pending
+      { status: 'pending', job_id: args[:job_id], message: result[:message] }
+    when :error
+      raise StandardError, result[:error_message]
+    end
+  end
+end
+
+# Register the tools with the server
+server = FastMcp::Server.new(
+  name: 'async-tools',
+  version: '1.0.0'
+)
+
+server.register_tool(SleepyToolWrapper)
+server.register_tool(CheckJobStatusToolWrapper)
+
+# Start the server
+Legate.logger.info('Starting MCP server with async tools...')
+begin
+  server.start
+rescue Interrupt
+  Legate.logger.info('Shutting down MCP server...')
+end