Class: LLM::MCP

Inherits:
Object
  • Object
show all
Defined in:
lib/llm/mcp.rb,
lib/llm/mcp/rpc.rb,
lib/llm/mcp/error.rb,
lib/llm/mcp/router.rb,
lib/llm/mcp/command.rb,
lib/llm/mcp/mailbox.rb

Overview

The LLM::MCP class provides access to servers that implement the Model Context Protocol. MCP defines a standard way for clients and servers to exchange capabilities such as tools, prompts, resources, and other structured interactions.

In llm.rb, LLM::MCP currently supports stdio and HTTP transports and focuses on discovering tools that can be used through LLM::Context and LLM::Agent.

An MCP client is stateful. Coordinate lifecycle operations such as #start and #stop; request methods can be issued concurrently and responses are matched by JSON-RPC id.

Defined Under Namespace

Modules: Transport Classes: Command, Mailbox, Router

Constant Summary collapse

Error = 
Class.new(LLM::Error) do
  attr_reader :code, :data

  ##
  # @param [Hash] response
  #  The full response from the MCP process, including the error object
  # @return [LLM::MCP::Error]
  def self.from(response:)
    error = response.fetch("error")
    new(*error.values_at("message", "code", "data"))
  end

  ##
  # @param [String] message
  #  The error message
  # @param [Integer] code
  #  The error code
  # @param [Object] data
  #  Additional error data provided by the MCP process
  def initialize(message, code = nil, data = nil)
    super(message)
    @code = code
    @data = data
  end
end
MismatchError = 
Class.new(Error) do
  ##
  # @return [Integer, String]
  #  The request id the client was waiting for
  attr_reader :expected_id

  ##
  # @return [Integer, String]
  #  The response id received from the server
  attr_reader :actual_id

  ##
  # @param [Integer, String] expected_id
  #  The request id the client was waiting for
  # @param [Integer, String] actual_id
  #  The response id received from the server instead
  def initialize(expected_id:, actual_id:)
    @expected_id = expected_id
    @actual_id = actual_id
    super(message)
  end

  ##
  # @return [String]
  def message
    "mismatched MCP response id #{actual_id.inspect} " \
    "while waiting for #{expected_id.inspect}"
  end
end
TimeoutError = 
Class.new(Error)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(stdio: nil, http: nil, timeout: 30) ⇒ LLM::MCP

Returns A new MCP instance.

Parameters:

  • stdio (Hash, nil) (defaults to: nil) —

    The configuration for the stdio transport

  • http (Hash, nil) (defaults to: nil) —

    The configuration for the HTTP transport

  • timeout (Integer) (defaults to: 30) —

    The maximum amount of time to wait when reading from an MCP process

Options Hash (stdio:):

  • :argv (Array<String>) —

    The command to run for the MCP process

  • :env (Hash) —

    The environment variables to set for the MCP process

  • :cwd (String, nil) —

    The working directory for the MCP process

Options Hash (http:):

  • :url (String) —

    The URL for the MCP HTTP endpoint

  • :headers (Hash) —

    Extra headers for requests

  • :transport (LLM::Transport, Class) —

    Optional override with any Transport instance or subclass, similar to Provider



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/llm/mcp.rb', line 64

def initialize(stdio: nil, http: nil, timeout: 30)
  @timeout = timeout
  if stdio && http
    raise ArgumentError, "stdio and http are mutually exclusive"
  elsif stdio
    @command = Command.new(**stdio)
    @transport = Transport::Stdio.new(command:)
  elsif http
    persistent = http.delete(:persistent)
    transport = http.delete(:transport)
    transport ||= LLM::Transport::PersistentHTTP if persistent
    @transport = Transport::HTTP.new(**http, timeout:, transport:)
  else
    raise ArgumentError, "stdio or http is required"
  end
end

Class Method Details

.http(**http) ⇒ LLM::MCP

Builds an MCP client that uses the HTTP transport.

Parameters:

  • http (Hash) —

    The HTTP transport configuration

Returns:



41
42
43
 
# File 'lib/llm/mcp.rb', line 41

def self.http(**http)
  new(http:)
end

.stdio(**stdio) ⇒ LLM::MCP

Builds an MCP client that uses the stdio transport.

Parameters:

  • stdio (Hash) —

    The stdio transport configuration

Returns:



32
33
34
 
# File 'lib/llm/mcp.rb', line 32

def self.stdio(**stdio)
  new(stdio:)
end

Instance Method Details

#call_tool(name, arguments = {}) ⇒ Object

Calls a tool by name with the given arguments

Parameters:

  • name (String) —

    The name of the tool to call

  • arguments (Hash) (defaults to: {}) —

    The arguments to pass to the tool

Returns:

  • (Object) —

    The result of the tool call



155
156
157
158
 
# File 'lib/llm/mcp.rb', line 155

def call_tool(name, arguments = {})
  res = with_session { call(transport, "tools/call", {name:, arguments:}) }
  adapt_tool_result(res)
end

#start ⇒ void

This method returns an undefined value.

Starts the MCP process.



84
85
86
87
88
 
# File 'lib/llm/mcp.rb', line 84

def start
  transport.start
  call(transport, "initialize", {clientInfo: {name: "llm.rb", version: LLM::VERSION}})
  call(transport, "notifications/initialized")
end

#stop ⇒ void

This method returns an undefined value.

Stops the MCP process.



93
94
95
96
 
# File 'lib/llm/mcp.rb', line 93

def stop
  transport.stop
  nil
end

#run { ... } ⇒ void Also known as: session

This method returns an undefined value.

Starts the MCP client for the duration of a block and then stops it.

Yields:

  • Runs with the MCP client started

Raises:

  • (LocalJumpError) —

    When called without a block

  • (StandardError) —

    Propagates errors raised by #start, the block itself, or #stop



106
107
108
109
110
111
 
# File 'lib/llm/mcp.rb', line 106

def run
  start
  yield
ensure
  stop
end

#tools ⇒ Array<Class<LLM::Tool>>

Returns the tools provided by the MCP process.

Returns:



117
118
119
120
 
# File 'lib/llm/mcp.rb', line 117

def tools
  res = with_session { call(transport, "tools/list") }
  res["tools"].map { LLM::Tool.mcp(self, _1) }
end

#prompts ⇒ Array<LLM::Object>

Returns the prompts provided by the MCP process.

Returns:



125
126
127
128
 
# File 'lib/llm/mcp.rb', line 125

def prompts
  res = with_session { call(transport, "prompts/list") }
  LLM::Object.from(res["prompts"])
end

#find_prompt(name:, arguments: nil) ⇒ LLM::Object Also known as: get_prompt

Returns a prompt by name.

Parameters:

  • name (String) —

    The prompt name

  • arguments (Hash<String, String>, nil) (defaults to: nil) —

    The prompt arguments

Returns:



135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/llm/mcp.rb', line 135

def find_prompt(name:, arguments: nil)
  params = {name:}
  params[:arguments] = arguments if arguments
  res = with_session { call(transport, "prompts/get", params) }
  res["messages"] = [*res["messages"]].map do |message|
    LLM::Message.new(
      message["role"],
      adapt_content(message["content"]),
      {original_content: message["content"]}
    )
  end
  LLM::Object.from(res)
end