Module: Msf::MCP::Tools::ToolHelper

Included in:
CredentialInfo, HostInfo, LootInfo, ModuleCheck, ModuleExecute, ModuleInfo, ModuleResults, NoteInfo, RunningStats, SearchModules, ServiceInfo, SessionList, SessionRead, SessionStop, SessionWrite, VulnerabilityInfo
Defined in:
lib/msf/core/mcp/tools/tool_helper.rb

Overview

Shared helper methods for MCP tools.

Provides a standard way to build error responses that comply with the MCP protocol, returning a normal result with ‘isError: true` instead of raising exceptions that the MCP server would wrap as internal errors.

Constant Summary collapse

DANGEROUS_MODE_DISABLED_MESSAGE = 
'This tool requires dangerous actions mode to be enabled. ' \
'Enable it with: --enable-dangerous-actions flag, MSF_MCP_DANGEROUS_ACTIONS=true environment ' \
'variable, or mcp.dangerous_actions: true in config file.'

Instance Method Summary collapse

Instance Method Details

#dangerous_mode_required!(server_context) ⇒ void

This method returns an undefined value.

Guard a dangerous tool invocation by checking the dangerous_actions flag in the server context.

Parameters:

  • server_context (Hash) —

    Server context with :dangerous_actions key

Raises:



44
45
46
47
48
 
# File 'lib/msf/core/mcp/tools/tool_helper.rb', line 44

def dangerous_mode_required!(server_context)
  return if server_context[:dangerous_actions] == true

  raise DangerousModeDisabledError, DANGEROUS_MODE_DISABLED_MESSAGE
end

#tool_error_response(message) ⇒ ::MCP::Tool::Response

Build a standard MCP error response.

Parameters:

  • message (String) —

    Human-readable error message

Returns:

  • (::MCP::Tool::Response) —

    Response with isError flag set



29
30
31
32
33
34
 
# File 'lib/msf/core/mcp/tools/tool_helper.rb', line 29

def tool_error_response(message)
  ::MCP::Tool::Response.new(
    [{ type: 'text', text: message }],
    error: true
  )
end

#with_tool_context(server_context, rate_limit_key, dangerous: false) {|msf_client| ... } ⇒ ::MCP::Tool::Response

Wrap a tool’s call body with the standard dangerous-mode gate, rate limiter check, and error-to-response mapping. Yields the msf_client to the caller so the block only has to do input validation, the RPC call, and response shaping.

Any exception raised by the block that matches one of the well-known MCP error classes is converted into an MCP tool error response via #tool_error_response. Other exceptions propagate to the MCP server so it can render them as internal errors.

Parameters:

  • server_context (Hash) —

    The tool’s server context. Must contain :msf_client and :rate_limiter. When dangerous: true, must also contain :dangerous_actions.

  • rate_limit_key (String) —

    Rate limiter bucket name, typically the tool name without the msf_ prefix.

  • dangerous (Boolean) (defaults to: false) —

    When true, calls #dangerous_mode_required! before the rate-limit check so a blocked tool never consumes rate.

Yield Parameters:

Returns:

  • (::MCP::Tool::Response) 


71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/msf/core/mcp/tools/tool_helper.rb', line 71

def with_tool_context(server_context, rate_limit_key, dangerous: false)
  dangerous_mode_required!(server_context) if dangerous
  rate_limiter = server_context[:rate_limiter]
  rate_limiter.check_rate_limit!(rate_limit_key)
  yield server_context[:msf_client]
rescue Msf::MCP::Tools::DangerousModeDisabledError, Msf::MCP::Security::ValidationError => e
  tool_error_response(e.message)
rescue Msf::MCP::Security::RateLimitExceededError => e
  tool_error_response("Rate limit exceeded: #{e.message}")
rescue Msf::MCP::Metasploit::AuthenticationError => e
  tool_error_response("Authentication failed: #{e.message}")
rescue Msf::MCP::Metasploit::APIError => e
  tool_error_response("Metasploit API error: #{e.message}")
end