Module: VectorMCP::Handlers::Core

Defined in:
lib/vector_mcp/handlers/core.rb

Overview

Provides default handlers for the core MCP methods. These methods are typically registered on a Server instance. All public methods are designed to be called by the server's message dispatching logic.

See Also:

  • Server#setup_default_handlers

Class Method Summary collapse

Class Method Details

.call_tool(params, session, server) ⇒ Hash

Handles the tools/call request.

Parameters:

  • params (Hash) —

    The request parameters. Expected keys: "name" (String), "arguments" (Hash, optional).

  • session (VectorMCP::Session) —

    The current session.

  • server (VectorMCP::Server) —

    The server instance.

Returns:

  • (Hash) —

    A hash containing the tool call result or an error indication. Example success: { isError: false, content: [{ type: "text", ... }] }

Raises:



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/vector_mcp/handlers/core.rb', line 57

def self.call_tool(params, session, server)
  tool_name = params["name"]
  context = create_tool_context(tool_name, params, session, server)

  begin
    session_context = authenticate_request!(session, server, operation_type: :tool_call, operation_name: tool_name)

    context = server.middleware_manager.execute_hooks(:before_tool_call, context)
    return handle_middleware_error(context) if context.error?

    tool_name = context.params["name"] || tool_name
    arguments = context.params["arguments"] || {}
    tool = find_tool!(tool_name, server)
    authorize_action!(session_context, :call, tool, server)
    validate_tool_arguments!(tool_name, tool, arguments)

    result = execute_tool_handler(tool, arguments, session)
    context.result = build_tool_result(result)

    context = server.middleware_manager.execute_hooks(:after_tool_call, context)
    context.result
  rescue StandardError => e
    handle_tool_error(e, context, server)
  end
end

.cancel_request_notification(params, _session, server) ⇒ void

This method returns an undefined value.

Handles the $/cancelRequest notification from the client.

Parameters:

  • params (Hash) —

    The notification parameters. Expected key: "id".

  • _session (VectorMCP::Session) —

    The current session (ignored).

  • server (VectorMCP::Server) —

    The server instance.



231
232
233
234
235
236
 
# File 'lib/vector_mcp/handlers/core.rb', line 231

def self.cancel_request_notification(params, _session, server)
  request_id = params["id"]
  server.logger.info("Received cancellation request for ID: #{request_id}")
  # Application-specific cancellation logic would go here
  # Access in-flight requests via server.in_flight_requests[request_id]
end

.get_prompt(params, session, server) ⇒ Hash

Handles the prompts/get request. Validates arguments and the structure of the prompt handler's response.

Parameters:

  • params (Hash) —

    The request parameters. Expected keys: "name" (String), "arguments" (Hash, optional).

  • session (VectorMCP::Session) —

    The current session.

  • server (VectorMCP::Server) —

    The server instance.

Returns:

  • (Hash) —

    The result from the prompt's handler, which should conform to MCP's GetPromptResult.

Raises:



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/vector_mcp/handlers/core.rb', line 186

def self.get_prompt(params, session, server)
  prompt_name = params["name"]

  # Create middleware context
  context = VectorMCP::Middleware::Context.new(
    operation_type: :prompt_get,
    operation_name: prompt_name,
    params: params,
    session: session,
    server: server,
    metadata: { start_time: Time.now }
  )

  begin
    execute_prompt_request(context, prompt_name, session, server)
  rescue StandardError => e
    # Set error in context and execute error hooks
    context.error = e
    context = server.middleware_manager.execute_hooks(:on_prompt_error, context)

    # Re-raise unless middleware handled the error
    raise e unless context.result

    context.result
  end
end

.initialized_notification(_params, _session, server) ⇒ void

This method returns an undefined value.

Handles the initialized notification from the client.

Parameters:

  • _params (Hash) —

    The notification parameters (ignored).

  • _session (VectorMCP::Session) —

    The current session (ignored, but state is on server).

  • server (VectorMCP::Server) —

    The server instance.



221
222
223
 
# File 'lib/vector_mcp/handlers/core.rb', line 221

def self.initialized_notification(_params, _session, server)
  server.logger.info("Session initialized")
end

.list_prompts(_params, session, server) ⇒ Hash

Handles the prompts/list request. If the server supports dynamic prompt lists, this clears the listChanged flag.

Parameters:

Returns:

  • (Hash) —

    A hash containing an array of prompt definitions. Example: { prompts: [ { name: "my_prompt", ... } ] }



143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/vector_mcp/handlers/core.rb', line 143

def self.list_prompts(_params, session, server)
  session_context = authenticate_request!(session, server, operation_type: :prompt_list, operation_name: "prompts/list")
  prompts = filter_authorized_items(server.prompts.values, session_context, server)

  # Once the list is supplied, clear the listChanged flag
  result = {
    prompts: prompts.map(&:as_mcp_definition)
  }
  server.clear_prompts_list_changed if server.respond_to?(:clear_prompts_list_changed)
  result
end

.list_resources(_params, session, server) ⇒ Hash

Handles the resources/list request.

Parameters:

Returns:

  • (Hash) —

    A hash containing an array of resource definitions. Example: { resources: [ { uri: "memory://data", name: "My Data", ... } ] }



90
91
92
93
94
95
96
97
 
# File 'lib/vector_mcp/handlers/core.rb', line 90

def self.list_resources(_params, session, server)
  session_context = authenticate_request!(session, server, operation_type: :resource_list, operation_name: "resources/list")
  resources = filter_authorized_items(server.resources.values, session_context, server)

  {
    resources: resources.map(&:as_mcp_definition)
  }
end

.list_roots(_params, session, server) ⇒ Hash

Handles the roots/list request. Returns the list of available roots and clears the listChanged flag.

Parameters:

Returns:

  • (Hash) —

    A hash containing an array of root definitions. Example: { roots: [ { uri: "file:///path/to/dir", name: "My Project" } ] }



163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/vector_mcp/handlers/core.rb', line 163

def self.list_roots(_params, session, server)
  session_context = authenticate_request!(session, server, operation_type: :root_list, operation_name: "roots/list")
  roots = filter_authorized_items(server.roots.values, session_context, server)

  # Once the list is supplied, clear the listChanged flag
  result = {
    roots: roots.map(&:as_mcp_definition)
  }
  server.clear_roots_list_changed if server.respond_to?(:clear_roots_list_changed)
  result
end

.list_tools(_params, session, server) ⇒ Hash

Handles the tools/list request.

Parameters:

Returns:

  • (Hash) —

    A hash containing an array of tool definitions. Example: { tools: [ { name: "my_tool", ... } ] }



36
37
38
39
40
41
42
43
 
# File 'lib/vector_mcp/handlers/core.rb', line 36

def self.list_tools(_params, session, server)
  session_context = authenticate_request!(session, server, operation_type: :tool_list, operation_name: "tools/list")
  tools = filter_authorized_items(server.tools.values, session_context, server)

  {
    tools: tools.map(&:as_mcp_definition)
  }
end

.ping(_params, _session, _server) ⇒ Hash

Handles the ping request.

Parameters:

  • _params (Hash) —

    The request parameters (ignored).

  • _session (VectorMCP::Session) —

    The current session (ignored).

  • _server (VectorMCP::Server) —

    The server instance (ignored).

Returns:

  • (Hash) —

    An empty hash, as per MCP spec for ping.



25
26
27
 
# File 'lib/vector_mcp/handlers/core.rb', line 25

def self.ping(_params, _session, _server)
  {}
end

.read_resource(params, session, server) ⇒ Hash

Handles the resources/read request.

Parameters:

  • params (Hash) —

    The request parameters. Expected key: "uri" (String).

  • session (VectorMCP::Session) —

    The current session.

  • server (VectorMCP::Server) —

    The server instance.

Returns:

  • (Hash) —

    A hash containing an array of content items from the resource. Example: { contents: [{ type: "text", text: "...", uri: "memory://data" }] }

Raises:



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/vector_mcp/handlers/core.rb', line 110

def self.read_resource(params, session, server)
  uri_s = params["uri"]
  context = create_resource_context(uri_s, params, session, server)

  begin
    session_context = authenticate_request!(session, server, operation_type: :resource_read, operation_name: uri_s)

    context = server.middleware_manager.execute_hooks(:before_resource_read, context)
    return handle_middleware_error(context) if context.error?

    uri_s = context.params["uri"] || uri_s
    resource = find_resource!(uri_s, server)
    authorize_action!(session_context, :read, resource, server)

    content_raw = execute_resource_handler(resource, context.params, session)
    contents = process_resource_content(content_raw, resource, uri_s)

    context.result = { contents: contents }
    context = server.middleware_manager.execute_hooks(:after_resource_read, context)
    context.result
  rescue StandardError => e
    handle_resource_error(e, context, server)
  end
end