Skip to content

armgit / letta

Public Imported from GitHub
0

Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.

feat: Add async MCP clients (#1882)

Matthew Zhou4a9fc2003ef2
diff --git a/letta/services/mcp/__init__.py b/letta/services/mcp/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/letta/services/mcp/base_client.py b/letta/services/mcp/base_client.py
new file mode 100644
index 000000000..270792a90
--- /dev/null
+++ b/letta/services/mcp/base_client.py
@@ -0,0 +1,67 @@
+from contextlib import AsyncExitStack
+from typing import Optional, Tuple
+
+from mcp import ClientSession
+from mcp import Tool as MCPTool
+from mcp.types import TextContent
+
+from letta.functions.mcp_client.types import BaseServerConfig
+from letta.log import get_logger
+
+logger = get_logger(__name__)
+
+
+# TODO: Get rid of Async prefix on this class name once we deprecate old sync code
+class AsyncBaseMCPClient:
+ def __init__(self, server_config: BaseServerConfig):
+ self.server_config = server_config
+ self.exit_stack = AsyncExitStack()
+ self.session: Optional[ClientSession] = None
+ self.initialized = False
+
+ async def connect_to_server(self):
+ try:
+ await self._initialize_connection(self.server_config)
+ await self.session.initialize()
+ self.initialized = True
+ except Exception as e:
+ logger.error(
+ f"Connecting to MCP server failed. Please review your server config: {self.server_config.model_dump_json(indent=4)}"
+ )
+ raise e
+
+ async def _initialize_connection(self, exit_stack: AsyncExitStack[bool | None], server_config: BaseServerConfig) -> None:
+ raise NotImplementedError("Subclasses must implement _initialize_connection")
+
+ async def list_tools(self) -> list[MCPTool]:
+ self._check_initialized()
+ response = await self.session.list_tools()
+ return response.tools
+
+ async def execute_tool(self, tool_name: str, tool_args: dict) -> Tuple[str, bool]:
+ self._check_initialized()
+ result = await self.session.call_tool(tool_name, tool_args)
+ parsed_content = []
+ for content_piece in result.content:
+ if isinstance(content_piece, TextContent):
+ parsed_content.append(content_piece.text)
+ print("parsed_content (text)", parsed_content)
+ else:
+ parsed_content.append(str(content_piece))
+ print("parsed_content (other)", parsed_content)
+ if len(parsed_content) > 0:
+ final_content = " ".join(parsed_content)
+ else:
+ # TODO move hardcoding to constants
+ final_content = "Empty response from tool"
+
+ return final_content, result.isError
+
+ def _check_initialized(self):
+ if not self.initialized:
+ logger.error("MCPClient has not been initialized")
+ raise RuntimeError("MCPClient has not been initialized")
+
+ async def cleanup(self):
+ """Clean up resources"""
+ await self.exit_stack.aclose()
diff --git a/letta/services/mcp/sse_client.py b/letta/services/mcp/sse_client.py
new file mode 100644
index 000000000..5bfebf753
--- /dev/null
+++ b/letta/services/mcp/sse_client.py
@@ -0,0 +1,25 @@
+from contextlib import AsyncExitStack
+
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+
+from letta.functions.mcp_client.types import SSEServerConfig
+from letta.log import get_logger
+from letta.services.mcp.base_client import AsyncBaseMCPClient
+
+# see: https://modelcontextprotocol.io/quickstart/user
+MCP_CONFIG_TOPLEVEL_KEY = "mcpServers"
+
+logger = get_logger(__name__)
+
+
+# TODO: Get rid of Async prefix on this class name once we deprecate old sync code
+class AsyncSSEMCPClient(AsyncBaseMCPClient):
+ async def _initialize_connection(self, exit_stack: AsyncExitStack[bool | None], server_config: SSEServerConfig) -> None:
+ sse_cm = sse_client(url=server_config.server_url)
+ sse_transport = await exit_stack.enter_async_context(sse_cm)
+ self.stdio, self.write = sse_transport
+
+ # Create and enter the ClientSession context manager
+ session_cm = ClientSession(self.stdio, self.write)
+ self.session = await exit_stack.enter_async_context(session_cm)
diff --git a/letta/services/mcp/stdio_client.py b/letta/services/mcp/stdio_client.py
new file mode 100644
index 000000000..ca9c4c44e
--- /dev/null
+++ b/letta/services/mcp/stdio_client.py
@@ -0,0 +1,19 @@
+from contextlib import AsyncExitStack
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from letta.functions.mcp_client.types import StdioServerConfig
+from letta.log import get_logger
+from letta.services.mcp.base_client import AsyncBaseMCPClient
+
+logger = get_logger(__name__)
+
+
+# TODO: Get rid of Async prefix on this class name once we deprecate old sync code
+class AsyncStdioMCPClient(AsyncBaseMCPClient):
+ async def _initialize_connection(self, exit_stack: AsyncExitStack[bool | None], server_config: StdioServerConfig) -> None:
+ server_params = StdioServerParameters(command=server_config.command, args=server_config.args)
+ stdio_transport = await exit_stack.enter_async_context(stdio_client(server_params))
+ self.stdio, self.write = stdio_transport
+ self.session = await exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
diff --git a/letta/services/mcp/types.py b/letta/services/mcp/types.py
new file mode 100644
index 000000000..2d8b7af6d
--- /dev/null
+++ b/letta/services/mcp/types.py
@@ -0,0 +1,48 @@
+from enum import Enum
+from typing import List, Optional
+
+from mcp import Tool
+from pydantic import BaseModel, Field
+
+
+class MCPTool(Tool):
+ """A simple wrapper around MCP's tool definition (to avoid conflict with our own)"""
+
+
+class MCPServerType(str, Enum):
+ SSE = "sse"
+ STDIO = "stdio"
+
+
+class BaseServerConfig(BaseModel):
+ server_name: str = Field(..., description="The name of the server")
+ type: MCPServerType
+
+
+class SSEServerConfig(BaseServerConfig):
+ type: MCPServerType = MCPServerType.SSE
+ server_url: str = Field(..., description="The URL of the server (MCP SSE client will connect to this URL)")
+
+ def to_dict(self) -> dict:
+ values = {
+ "transport": "sse",
+ "url": self.server_url,
+ }
+ return values
+
+
+class StdioServerConfig(BaseServerConfig):
+ type: MCPServerType = MCPServerType.STDIO
+ command: str = Field(..., description="The command to run (MCP 'local' client will run this command)")
+ args: List[str] = Field(..., description="The arguments to pass to the command")
+ env: Optional[dict[str, str]] = Field(None, description="Environment variables to set")
+
+ def to_dict(self) -> dict:
+ values = {
+ "transport": "stdio",
+ "command": self.command,
+ "args": self.args,
+ }
+ if self.env is not None:
+ values["env"] = self.env
+ return values