Class: SwarmSDK::V3::MCP::Connector

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/v3/mcp/connector.rb

Overview

Manages the full MCP client lifecycle

Connects to an MCP server, discovers available tools, and provides methods to call tools and convert them to RubyLLM::Tool instances. Accepts an optional ‘transport:` for dependency injection in tests.

Examples:

Production usage

server = ServerDefinition.new(name: :api, type: :http, url: "http://localhost:3000/mcp")
connector = Connector.new(server)
connector.connect!
connector.available_tools  #=> [#<MCP::Client::Tool name="echo" ...>]
connector.call_tool("echo", message: "hello")
connector.disconnect!

Test usage with injected transport

connector = Connector.new(server_def, transport: mock_transport)
connector.connect!

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(server_definition, transport: nil) ⇒ Connector

Create a new connector

Examples:

Connector.new(server_def)
Connector.new(server_def, transport: mock_transport)

Parameters:

  • server_definition (ServerDefinition) —

    Server configuration

  • transport (Object, nil) (defaults to: nil) —

    Optional transport for dependency injection. Must respond to ‘send_request(request:)`. When nil, the transport is built automatically from the server definition.



40
41
42
43
44
45
46
 
# File 'lib/swarm_sdk/v3/mcp/connector.rb', line 40

def initialize(server_definition, transport: nil)
  @server_definition = server_definition
  @injected_transport = transport
  @client = nil
  @transport = nil
  @available_tools = []
end

Instance Attribute Details

#available_tools ⇒ Array<MCP::Client::Tool> (readonly)

Returns Discovered MCP tools.

Returns:

  • (Array<MCP::Client::Tool>) —

    Discovered MCP tools



28
29
30
 
# File 'lib/swarm_sdk/v3/mcp/connector.rb', line 28

def available_tools
  @available_tools
end

#server_definition ⇒ ServerDefinition (readonly)

Returns Server configuration.

Returns:



25
26
27
 
# File 'lib/swarm_sdk/v3/mcp/connector.rb', line 25

def server_definition
  @server_definition
end

Instance Method Details

#call_tool(name, **arguments) ⇒ String

Call an MCP tool by name

Examples:

connector.call_tool("echo", message: "hello")
#=> "hello"

Parameters:

  • name (String, Symbol) —

    Tool name

  • arguments (Hash) —

    Tool arguments

Returns:

  • (String) —

    Tool result content

Raises:

  • (McpError) —

    If the tool is not found



83
84
85
86
87
88
89
 
# File 'lib/swarm_sdk/v3/mcp/connector.rb', line 83

def call_tool(name, **arguments)
  tool = @available_tools.find { |t| t.name == name.to_s }
  raise McpError, "Unknown MCP tool: #{name}" unless tool

  result = @client.call_tool(tool: tool, arguments: arguments)
  extract_content(result)
end

#connect! ⇒ self

Connect to the MCP server and discover tools

Builds or uses the injected transport, creates an MCP::Client, and fetches the list of available tools from the server.

Examples:

connector.connect!
connector.available_tools.map(&:name) #=> ["echo", "read_file"]

Returns:

  • (self) —

    Returns self for chaining

Raises:

  • (McpError) —

    If the connection or tool discovery fails



59
60
61
62
63
64
 
# File 'lib/swarm_sdk/v3/mcp/connector.rb', line 59

def connect!
  @transport = @injected_transport || build_transport
  @client = ::MCP::Client.new(transport: @transport)
  @available_tools = @client.tools
  self
end

#connected? ⇒ Boolean

Whether the connector is currently connected

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/swarm_sdk/v3/mcp/connector.rb', line 69

def connected?
  !@client.nil?
end

#disconnect! ⇒ void

This method returns an undefined value.

Disconnect from the MCP server

Closes the transport and clears all state. Safe to call multiple times or when not connected.



111
112
113
114
115
116
 
# File 'lib/swarm_sdk/v3/mcp/connector.rb', line 111

def disconnect!
  @transport.close if @transport.respond_to?(:close)
  @client = nil
  @transport = nil
  @available_tools = []
end

#to_ruby_llm_tools ⇒ Array<RubyLLM::Tool>

Convert MCP tools to RubyLLM::Tool instances

Filters tools based on the server definition’s tool list, then creates RubyLLM::Tool proxies for each.

Examples:

tools = connector.to_ruby_llm_tools
chat.with_tools(*tools)

Returns:

  • (Array<RubyLLM::Tool>) —

    RubyLLM-compatible tool instances



101
102
103
 
# File 'lib/swarm_sdk/v3/mcp/connector.rb', line 101

def to_ruby_llm_tools
  tools_to_expose.map { |mcp_tool| ToolProxy.create(mcp_tool, self) }
end