"""Built-in tool for connecting to a Model Context Protocol (MCP) server.

This module provides the ``BuiltinMCPTool`` class, which carries MCP
server connection parameters (name, URL, headers, allowed tools) so that
an API provider can communicate with the server on behalf of the model.
The tool itself is not executed locally.
"""

from typing import Any, Dict, List, Optional

from litemind.agent.tools.builtin_tools.builtin_tool import BuiltinTool


class BuiltinMCPTool(BuiltinTool):
    """A built-in tool that connects to a Model Context Protocol (MCP) server.

    MCP tools are not executed locally; instead, the API provider
    communicates with the specified MCP server. This class carries the
    server connection parameters.
    """

    def __init__(
        self,
        server_name: str,
        server_url: str,
        headers: Optional[Dict[str, str]] = None,
        allowed_tools: Optional[List[str]] = None,
    ):
        """
        Initialize a built-in mcp tool given a server name, URL, and optionally headers and allowed tools.

        Parameters
        ----------
        server_name: str
            The name of the MCP server.
        server_url: str
            The URL of the MCP server.
        headers: Optional[Dict[str, str]]
            Optional headers to include in requests to the MCP server -- for example, authentication headers.
        allowed_tools: Optional[List[str]]
            A list of allowed tools that can be used with this MCP server. If None, all tools are allowed.


        """
        # Initialize the base tool, description is empty for now...
        super().__init__(
            name=f"{server_name} MCP server tool",
            description="Built-in MCP server tool",
        )

        # Set the server name and URL:
        self.server_name = server_name
        self.server_url = server_url
        self.headers = headers if headers is not None else {}
        self.allowed_tools = allowed_tools if allowed_tools is not None else []

    def _execute(self, *args, **kwargs) -> Any:
        """Raise RuntimeError because MCP tools are executed by the API provider."""
        raise RuntimeError(
            f"{BuiltinMCPTool.__name__} tool cannot be executed directly. It is a placeholder for built-in MCP functionality."
        )

    def pretty_string(self):
        """
        Return a pretty string representation of the tool.

        Returns
        -------
        str
            A pretty string representation of the tool.
        """
        return f"{self.name} (Built-in MCP tool, cannot be executed directly)"
