mcp server proposal (#267)

* mcp server proposal

* Refactor MCP server implementation: rename MCPServer to MCPServerAdapter and update usage examples. Adjust error message for optional dependencies installation.

* Update MCPServerAdapter usage examples to remove unnecessary parameters in context manager instantiation.

* Refactor MCPServerAdapter to move optional dependency imports inside the class constructor, improving error handling for missing dependencies.

* Enhance MCPServerAdapter by adding type hinting for server parameters and improving error handling during server startup. Optional dependency imports are now conditionally loaded, ensuring clearer error messages for missing packages.

* Refactor MCPServerAdapter to improve error handling for missing 'mcp' package. Conditional imports are now used, prompting users to install the package if not found, enhancing user experience during server initialization.

* Refactor MCPServerAdapter to ensure proper cleanup after usage. Removed redundant exception handling and ensured that the server stops in a finally block, improving resource management.

* add documentation

* fix typo close -> stop

* add tests and fix double call with context manager

* Enhance MCPServerAdapter with logging capabilities and improved error handling during initialization. Added logging for cleanup errors and refined the structure for handling missing 'mcp' package dependencies.

---------

Co-authored-by: lorenzejay <lorenzejaytech@gmail.com>

src/crewai_tools/__init__.py

@@ -66,3 +66,7 @@ from .aws import (
     BedrockKBRetrieverTool,
     BedrockInvokeAgentTool,
 )
+
+from .adapters.mcp_adapter import (
+    MCPServerAdapter,
+)

src/crewai_tools/adapters/mcp_adapter.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+import logging
+from typing import Any, TYPE_CHECKING
+from crewai.tools import BaseTool
+
+"""
+MCPServer for CrewAI.
+
+
+"""
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from mcp import StdioServerParameters
+    from mcpadapt.core import MCPAdapt
+    from mcpadapt.crewai_adapter import CrewAIAdapter
+
+
+try:
+    from mcp import StdioServerParameters
+    from mcpadapt.core import MCPAdapt
+    from mcpadapt.crewai_adapter import CrewAIAdapter
+
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+
+
+class MCPServerAdapter:
+    """Manages the lifecycle of an MCP server and make its tools available to CrewAI.
+
+    Note: tools can only be accessed after the server has been started with the
+        `start()` method.
+
+    Attributes:
+        tools: The CrewAI tools available from the MCP server.
+
+    Usage:
+        # context manager + stdio
+        with MCPServerAdapter(...) as tools:
+            # tools is now available
+
+        # context manager + sse
+        with MCPServerAdapter({"url": "http://localhost:8000/sse"}) as tools:
+            # tools is now available
+
+        # manually stop mcp server
+        try:
+            mcp_server = MCPServerAdapter(...)
+            tools = mcp_server.tools
+            ...
+        finally:
+            mcp_server.stop()
+
+        # Best practice is ensure cleanup is done after use.
+        mcp_server.stop() # run after crew().kickoff()
+    """
+
+    def __init__(
+        self,
+        serverparams: StdioServerParameters | dict[str, Any],
+    ):
+        """Initialize the MCP Server
+
+        Args:
+            serverparams: The parameters for the MCP server it supports either a
+                `StdioServerParameters` or a `dict` respectively for STDIO and SSE.
+
+        """
+
+        super().__init__()
+        self._adapter = None
+        self._tools = None
+
+        if not MCP_AVAILABLE:
+            import click
+
+            if click.confirm(
+                "You are missing the 'mcp' package. Would you like to install it?"
+            ):
+                import subprocess
+
+                try:
+                    subprocess.run(["uv", "add", "mcp crewai-tools[mcp]"], check=True)
+
+                except subprocess.CalledProcessError:
+                    raise ImportError("Failed to install mcp package")
+            else:
+                raise ImportError(
+                    "`mcp` package not found, please run `uv add crewai-tools[mcp]`"
+                )
+
+        try:
+            self._serverparams = serverparams
+            self._adapter = MCPAdapt(self._serverparams, CrewAIAdapter())
+            self.start()
+
+        except Exception as e:
+            if self._adapter is not None:
+                try:
+                    self.stop()
+                except Exception as stop_e:
+                    logger.error(f"Error during stop cleanup: {stop_e}")
+            raise RuntimeError(f"Failed to initialize MCP Adapter: {e}") from e
+
+    def start(self):
+        """Start the MCP server and initialize the tools."""
+        self._tools = self._adapter.__enter__()
+
+    def stop(self):
+        """Stop the MCP server"""
+        self._adapter.__exit__(None, None, None)
+
+    @property
+    def tools(self) -> list[BaseTool]:
+        """The CrewAI tools available from the MCP server.
+
+        Raises:
+            ValueError: If the MCP server is not started.
+
+        Returns:
+            The CrewAI tools available from the MCP server.
+        """
+        if self._tools is None:
+            raise ValueError(
+                "MCP server not started, run `mcp_server.start()` first before accessing `tools`"
+            )
+        return self._tools
+
+    def __enter__(self):
+        """
+        Enter the context manager. Note that `__init__()` already starts the MCP server.
+        So tools should already be available.
+        """
+        return self.tools
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """Exit the context manager."""
+        return self._adapter.__exit__(exc_type, exc_value, traceback)