nat.utils.exception_handlers.mcp

Attributes

logger

Functions

format_mcp_error(→ None)	Format MCP errors for CLI display with structured logging and user guidance.
_extract_url(→ str)	Extract URL from function arguments using clean fallback chain.
extract_primary_exception(→ Exception)	Extract the most relevant exception from a group.
convert_to_mcp_error(→ nat.tool.mcp.exceptions.MCPError)	Convert single exception to appropriate MCPError.
handle_mcp_exceptions(...)	Decorator that handles exceptions and converts them to MCPErrors.
mcp_exception_handler(...)	Simplified decorator for methods that have self.url attribute.

Module Contents

logger

format_mcp_error(

error: nat.tool.mcp.exceptions.MCPError,

include_traceback: bool = False,

) → None

Format MCP errors for CLI display with structured logging and user guidance.

Logs structured error information for debugging and displays user-friendly error messages with actionable suggestions to stderr.

Args:

error (MCPError): MCPError instance containing message, url, category, suggestions, and original_exception include_traceback (bool, optional): Whether to include the traceback in the error message. Defaults to False.

_extract_url(

args: tuple,

kwargs: dict[str, Any],

url_param: str,

func_name: str,

) → str

Extract URL from function arguments using clean fallback chain.

Args:

args: Function positional arguments kwargs: Function keyword arguments url_param (str): Parameter name containing the URL func_name (str): Function name for logging

Returns:

str: URL string or “unknown” if extraction fails

extract_primary_exception(exceptions: list[Exception]) → Exception

Extract the most relevant exception from a group.

Prioritizes connection errors over others for better user experience.

Args:

exceptions (list[Exception]): List of exceptions from ExceptionGroup

Returns:

Exception: Most relevant exception for user feedback

convert_to_mcp_error(

exception: Exception,

url: str,

) → nat.tool.mcp.exceptions.MCPError

Convert single exception to appropriate MCPError.

Args:

exception (Exception): Single exception to convert url (str): MCP server URL for context

Returns:

MCPError: Appropriate MCPError subclass

handle_mcp_exceptions(

url_param: str = 'url',

) → collections.abc.Callable[Ellipsis, Any]

Decorator that handles exceptions and converts them to MCPErrors.

This decorator wraps MCP client methods and converts low-level exceptions to structured MCPError instances with helpful user guidance.

Args:

url_param (str): Name of the parameter or attribute containing the MCP server URL

Returns:

Callable[…, Any]: Decorated function

Example:

@handle_mcp_exceptions("url")
async def get_tools(self, url: str):
    # Method implementation
    pass

@handle_mcp_exceptions("url")  # Uses self.url
async def get_tool(self):
    # Method implementation
    pass

mcp_exception_handler(

func: collections.abc.Callable[Ellipsis, Any],

) → collections.abc.Callable[Ellipsis, Any]

Simplified decorator for methods that have self.url attribute.

This is a convenience decorator that assumes the URL is available as self.url. Follows the same pattern as schema_exception_handler in this directory.

Args:

func (Callable[…, Any]): The function to decorate

Returns:

Callable[…, Any]: Decorated function