Class: GroqRuby::MCP::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/groq_ruby/mcp/client.rb

Overview

High-level MCP client. Wraps a Transport and exposes the operations a Groq agent typically needs: handshake, list tools, invoke tools, list/read resources.

Synchronous on the outside (every public method blocks until the server responds or times out), thread-safe on the inside (the transport’s reader thread fulfils a per-id Queue).

Examples:

client = GroqRuby::MCP::Client.connect(server_config)
tools = client.tools_list
result = client.tools_call(name: "read_file", arguments: {path: "/tmp/x"})
client.stop

Constant Summary collapse

DEFAULT_REQUEST_TIMEOUT = 
30.0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(transport, request_timeout: DEFAULT_REQUEST_TIMEOUT) ⇒ Client

Returns a new instance of Client.

Parameters:

  • transport (Transport)
  • request_timeout (Numeric) (defaults to: DEFAULT_REQUEST_TIMEOUT) 


41
42
43
44
45
46
47
48
49
 
# File 'lib/groq_ruby/mcp/client.rb', line 41

def initialize(transport, request_timeout: DEFAULT_REQUEST_TIMEOUT)
  @transport = transport
  @request_timeout = request_timeout
  @next_id = 0
  @id_mutex = Mutex.new
  @pending = {}
  @pending_mutex = Mutex.new
  @transport.on_message { |msg| handle_message(msg) }
end

Instance Attribute Details

#server_capabilities ⇒ Hash (readonly)

Returns the server’s advertised capabilities.

Returns:

  • (Hash) —

    the server’s advertised capabilities



37
38
39
 
# File 'lib/groq_ruby/mcp/client.rb', line 37

def server_capabilities
  @server_capabilities
end

#server_name ⇒ String? (readonly)

Returns the server-reported name, populated after handshake.

Returns:

  • (String, nil) —

    the server-reported name, populated after handshake



33
34
35
 
# File 'lib/groq_ruby/mcp/client.rb', line 33

def server_name
  @server_name
end

#server_version ⇒ String? (readonly)

Returns the server-reported version, populated after handshake.

Returns:

  • (String, nil) —

    the server-reported version, populated after handshake



35
36
37
 
# File 'lib/groq_ruby/mcp/client.rb', line 35

def server_version
  @server_version
end

Class Method Details

.connect(config, request_timeout: DEFAULT_REQUEST_TIMEOUT) ⇒ Client

Connect to a server via the default stdio transport and complete the initialize handshake. Caller must call #stop when done.

Parameters:

  • config (ServerConfig)
  • request_timeout (Numeric) (defaults to: DEFAULT_REQUEST_TIMEOUT) —

    seconds to wait for any single response

Returns:



27
28
29
30
 
# File 'lib/groq_ruby/mcp/client.rb', line 27

def self.connect(config, request_timeout: DEFAULT_REQUEST_TIMEOUT)
  transport = Transports::Stdio.spawn(config)
  new(transport, request_timeout: request_timeout).tap(&:initialize_session)
end

Instance Method Details

#initialize_session ⇒ Hash

Run the JSON-RPC ‘initialize` handshake. Called automatically by connect; safe to call again to re-handshake.

Returns:

  • (Hash) —

    the server’s response payload



54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/groq_ruby/mcp/client.rb', line 54

def initialize_session
  result = request("initialize", {
    protocolVersion: PROTOCOL_VERSION,
    capabilities: {},
    clientInfo: {name: "groq_ruby", version: GroqRuby::VERSION}
  })
  info = result["serverInfo"] || {}
  @server_name = info["name"]
  @server_version = info["version"]
  @server_capabilities = result["capabilities"] || {}
  notify("notifications/initialized")
  result
end

#prompts_get(name, arguments = {}) ⇒ Hash

Render a prompt template by name with the given arguments.

Parameters:

  • name (String)
  • arguments (Hash) (defaults to: {})

Returns:

  • (Hash) —

    ‘messages` array as returned by the server



105
106
107
 
# File 'lib/groq_ruby/mcp/client.rb', line 105

def prompts_get(name, arguments = {})
  request("prompts/get", {name: name, arguments: arguments})
end

#prompts_list ⇒ Array<Prompt>

Returns every prompt template advertised by the server.

Returns:

  • (Array<Prompt>) —

    every prompt template advertised by the server



96
97
98
99
 
# File 'lib/groq_ruby/mcp/client.rb', line 96

def prompts_list
  result = request("prompts/list", {})
  Array(result["prompts"]).map { |h| Prompt.from_hash(h) }
end

#resources_list ⇒ Array<Resource>

Returns every resource advertised by the server.

Returns:

  • (Array<Resource>) —

    every resource advertised by the server



83
84
85
86
 
# File 'lib/groq_ruby/mcp/client.rb', line 83

def resources_list
  result = request("resources/list", {})
  Array(result["resources"]).map { |h| Resource.from_hash(h) }
end

#resources_read(uri) ⇒ Hash

Read a resource by URI.

Parameters:

  • uri (String)

Returns:

  • (Hash) —

    ‘contents` array as returned by the server



91
92
93
 
# File 'lib/groq_ruby/mcp/client.rb', line 91

def resources_read(uri)
  request("resources/read", {uri: uri})
end

#stop ⇒ Object

Close the underlying transport. Idempotent.



119
120
121
 
# File 'lib/groq_ruby/mcp/client.rb', line 119

def stop
  @transport.stop
end

#supports?(capability) ⇒ Boolean

Returns true when the handshake reported that the server advertises the given capability (‘“tools”`, `“resources”`, `“prompts”`). Useful for probing which Bridge features to enable.

Parameters:

  • capability (String)

Returns:

  • (Boolean) 


114
115
116
 
# File 'lib/groq_ruby/mcp/client.rb', line 114

def supports?(capability)
  @server_capabilities&.key?(capability) || false
end

#tools_call(name:, arguments: {}) ⇒ Hash

Invoke a tool on the server.

Parameters:

  • name (String)
  • arguments (Hash) (defaults to: {})

Returns:

  • (Hash) —

    the server’s tool-call result (may include ‘isError`)



78
79
80
 
# File 'lib/groq_ruby/mcp/client.rb', line 78

def tools_call(name:, arguments: {})
  request("tools/call", {name: name, arguments: arguments})
end

#tools_list ⇒ Array<Tool>

Returns every tool advertised by the server.

Returns:

  • (Array<Tool>) —

    every tool advertised by the server



69
70
71
72
 
# File 'lib/groq_ruby/mcp/client.rb', line 69

def tools_list
  result = request("tools/list", {})
  Array(result["tools"]).map { |h| Tool.from_hash(h) }
end