Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add resync tool endpoint (#2812)
jnjpng2aae4bf0dbb4
diff --git a/fern/openapi-overrides.yml b/fern/openapi-overrides.ymlindex 8c7d73a0c..f91dd8aad 100644--- a/fern/openapi-overrides.yml+++ b/fern/openapi-overrides.yml@@ -60,6 +60,9 @@ paths:/v1/tools/mcp/servers/{mcp_server_name}/{mcp_tool_name}:post:summary: "Add MCP Tool"+ /v1/tools/mcp/servers/{mcp_server_name}/resync:+ post:+ x-fern-ignore: true/v1/tools/mcp/servers/{mcp_server_name}:patch:summary: "Update MCP Server"diff --git a/fern/openapi.json b/fern/openapi.jsonindex f54701d93..721f07241 100644--- a/fern/openapi.json+++ b/fern/openapi.json@@ -1005,6 +1005,61 @@}}},+ "/v1/tools/mcp/servers/{mcp_server_name}/resync": {+ "post": {+ "tags": ["tools"],+ "summary": "Resync Mcp Server Tools",+ "description": "Resync tools for an MCP server by:\n1. Fetching current tools from the MCP server\n2. Deleting tools that no longer exist on the server\n3. Updating schemas for existing tools\n4. Adding new tools from the server\n\nReturns a summary of changes made.",+ "operationId": "resync_mcp_server_tools",+ "parameters": [+ {+ "name": "mcp_server_name",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "title": "Mcp Server Name"+ }+ },+ {+ "name": "agent_id",+ "in": "query",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Agent Id"+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Successful Response",+ "content": {+ "application/json": {+ "schema": {}+ }+ }+ },+ "422": {+ "description": "Validation Error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ }+ }+ }+ }+ },"/v1/tools/mcp/servers/{mcp_server_name}/{mcp_tool_name}": {"post": {"tags": ["tools"],diff --git a/letta/functions/schema_generator.py b/letta/functions/schema_generator.pyindex 8c657f436..545f88734 100644--- a/letta/functions/schema_generator.py+++ b/letta/functions/schema_generator.py@@ -622,7 +622,7 @@ def generate_tool_schema_for_mcp(format_value = option["format"]if types:# Deduplicate types using set- field_props["type"] = list(set(types))+ field_props["type"] = list(dict.fromkeys(types))# Only add format if the field is not optional (doesn't have null type)if format_value and len(field_props["type"]) == 1 and "null" not in field_props["type"]:field_props["format"] = format_valuediff --git a/letta/schemas/mcp.py b/letta/schemas/mcp.pyindex e49f177ac..5412bc336 100644--- a/letta/schemas/mcp.py+++ b/letta/schemas/mcp.py@@ -1,5 +1,5 @@from datetime import datetime-from typing import Any, Dict, Optional, Union+from typing import Any, Dict, List, Optional, Unionfrom pydantic import Field@@ -175,3 +175,11 @@ class MCPOAuthSessionUpdate(BaseMCPOAuth):client_secret: Optional[str] = Field(None, description="OAuth client secret")redirect_uri: Optional[str] = Field(None, description="OAuth redirect URI")status: Optional[OAuthSessionStatus] = Field(None, description="Session status")+++class MCPServerResyncResult(LettaBase):+ """Result of resyncing MCP server tools."""++ deleted: List[str] = Field(default_factory=list, description="List of deleted tool names")+ updated: List[str] = Field(default_factory=list, description="List of updated tool names")+ added: List[str] = Field(default_factory=list, description="List of added tool names")diff --git a/letta/server/rest_api/routers/v1/tools.py b/letta/server/rest_api/routers/v1/tools.pyindex efd03b0b9..0838838d1 100644--- a/letta/server/rest_api/routers/v1/tools.py+++ b/letta/server/rest_api/routers/v1/tools.py@@ -587,6 +587,48 @@ async def list_mcp_tools_by_server(return mcp_tools[email protected]("/mcp/servers/{mcp_server_name}/resync", operation_id="resync_mcp_server_tools")+async def resync_mcp_server_tools(+ mcp_server_name: str,+ server: SyncServer = Depends(get_letta_server),+ actor_id: Optional[str] = Header(None, alias="user_id"),+ agent_id: Optional[str] = None,+):+ """+ Resync tools for an MCP server by:+ 1. Fetching current tools from the MCP server+ 2. Deleting tools that no longer exist on the server+ 3. Updating schemas for existing tools+ 4. Adding new tools from the server++ Returns a summary of changes made.+ """+ actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)++ try:+ result = await server.mcp_manager.resync_mcp_server_tools(mcp_server_name=mcp_server_name, actor=actor, agent_id=agent_id)+ return result+ except ValueError as e:+ raise HTTPException(+ status_code=404,+ detail={+ "code": "MCPServerNotFoundError",+ "message": str(e),+ "mcp_server_name": mcp_server_name,+ },+ )+ except Exception as e:+ logger.error(f"Unexpected error refreshing MCP server tools: {e}")+ raise HTTPException(+ status_code=404,+ detail={+ "code": "MCPRefreshError",+ "message": f"Failed to refresh MCP server tools: {str(e)}",+ "mcp_server_name": mcp_server_name,+ },+ )++@router.post("/mcp/servers/{mcp_server_name}/{mcp_tool_name}", response_model=Tool, operation_id="add_mcp_tool")async def add_mcp_tool(mcp_server_name: str,diff --git a/letta/services/mcp_manager.py b/letta/services/mcp_manager.pyindex 775181c96..8668984a4 100644--- a/letta/services/mcp_manager.py+++ b/letta/services/mcp_manager.py@@ -6,7 +6,7 @@ from datetime import datetime, timedeltafrom typing import Any, Dict, List, Optional, Tuple, Unionfrom fastapi import HTTPException-from sqlalchemy import delete, null+from sqlalchemy import delete, desc, null, selectfrom starlette.requests import Requestimport letta.constants as constants@@ -23,17 +23,19 @@ from letta.log import get_loggerfrom letta.orm.errors import NoResultFoundfrom letta.orm.mcp_oauth import MCPOAuth, OAuthSessionStatusfrom letta.orm.mcp_server import MCPServer as MCPServerModel+from letta.orm.tool import Tool as ToolModelfrom letta.schemas.mcp import (MCPOAuthSession,MCPOAuthSessionCreate,MCPOAuthSessionUpdate,MCPServer,+ MCPServerResyncResult,UpdateMCPServer,UpdateSSEMCPServer,UpdateStdioMCPServer,UpdateStreamableHTTPMCPServer,)-from letta.schemas.tool import Tool as PydanticTool, ToolCreate+from letta.schemas.tool import Tool as PydanticTool, ToolCreate, ToolUpdatefrom letta.schemas.user import User as PydanticUserfrom letta.server.db import db_registryfrom letta.services.mcp.sse_client import MCP_CONFIG_TOPLEVEL_KEY, AsyncSSEMCPClient@@ -147,6 +149,117 @@ class MCPManager:# failed to add - handle error?return None+ @enforce_types+ async def resync_mcp_server_tools(+ self, mcp_server_name: str, actor: PydanticUser, agent_id: Optional[str] = None+ ) -> MCPServerResyncResult:+ """+ Resync tools for an MCP server by:+ 1. Fetching current tools from the MCP server+ 2. Deleting tools that no longer exist on the server+ 3. Updating schemas for existing tools+ 4. Adding new tools from the server++ Returns a result with:+ - deleted: List of deleted tool names+ - updated: List of updated tool names+ - added: List of added tool names+ """+ # Get the MCP server ID+ mcp_server_id = await self.get_mcp_server_id_by_name(mcp_server_name, actor=actor)+ if not mcp_server_id:+ raise ValueError(f"MCP server '{mcp_server_name}' not found")++ # Fetch current tools from MCP server+ try:+ current_mcp_tools = await self.list_mcp_server_tools(mcp_server_name, actor=actor, agent_id=agent_id)+ except Exception as e:+ logger.error(f"Failed to fetch tools from MCP server {mcp_server_name}: {e}")+ raise HTTPException(+ status_code=404,+ detail={+ "code": "MCPServerUnavailable",+ "message": f"Could not connect to MCP server {mcp_server_name} to resync tools",+ "error": str(e),+ },+ )++ # Get all persisted tools for this MCP server+ async with db_registry.async_session() as session:+ # Query for tools with MCP metadata matching this server+ # Using JSON path query to filter by metadata+ persisted_tools = await ToolModel.list_async(+ db_session=session,+ organization_id=actor.organization_id,+ )++ # Filter tools that belong to this MCP server+ mcp_tools = []+ for tool in persisted_tools:+ if tool.metadata_ and constants.MCP_TOOL_TAG_NAME_PREFIX in tool.metadata_:+ if tool.metadata_[constants.MCP_TOOL_TAG_NAME_PREFIX].get("server_id") == mcp_server_id:+ mcp_tools.append(tool)++ # Create maps for easier comparison+ current_tool_map = {tool.name: tool for tool in current_mcp_tools}+ persisted_tool_map = {tool.name: tool for tool in mcp_tools}++ deleted_tools = []+ updated_tools = []+ added_tools = []++ # 1. Delete tools that no longer exist on the server+ for tool_name, persisted_tool in persisted_tool_map.items():+ if tool_name not in current_tool_map:+ # Delete the tool (cascade will handle agent detachment)+ await persisted_tool.hard_delete_async(db_session=session, actor=actor)+ deleted_tools.append(tool_name)+ logger.info(f"Deleted MCP tool {tool_name} as it no longer exists on server {mcp_server_name}")++ # Commit deletions+ await session.commit()++ # 2. Update existing tools and add new tools+ for tool_name, current_tool in current_tool_map.items():+ if tool_name in persisted_tool_map:+ # Update existing tool+ persisted_tool = persisted_tool_map[tool_name]+ tool_create = ToolCreate.from_mcp(mcp_server_name=mcp_server_name, mcp_tool=current_tool)++ # Check if schema has changed+ if persisted_tool.json_schema != tool_create.json_schema:+ # Update the tool+ update_data = ToolUpdate(+ description=tool_create.description,+ json_schema=tool_create.json_schema,+ source_code=tool_create.source_code,+ )++ await self.tool_manager.update_tool_by_id_async(tool_id=persisted_tool.id, tool_update=update_data, actor=actor)+ updated_tools.append(tool_name)+ logger.info(f"Updated MCP tool {tool_name} with new schema from server {mcp_server_name}")+ else:+ # Add new tool+ # Skip INVALID tools+ if current_tool.health and current_tool.health.status == "INVALID":+ logger.warning(+ f"Skipping invalid tool {tool_name} from MCP server {mcp_server_name}: {', '.join(current_tool.health.reasons)}"+ )+ continue++ tool_create = ToolCreate.from_mcp(mcp_server_name=mcp_server_name, mcp_tool=current_tool)+ await self.tool_manager.create_mcp_tool_async(+ tool_create=tool_create, mcp_server_name=mcp_server_name, mcp_server_id=mcp_server_id, actor=actor+ )+ added_tools.append(tool_name)+ logger.info(f"Added new MCP tool {tool_name} from server {mcp_server_name}")++ return MCPServerResyncResult(+ deleted=deleted_tools,+ updated=updated_tools,+ added=added_tools,+ )+@enforce_typesasync def list_mcp_servers(self, actor: PydanticUser) -> List[MCPServer]:"""List all MCP servers available"""@@ -209,8 +322,6 @@ class MCPManager:# This ensures OAuth sessions created during testing get linked to the serverserver_url = getattr(mcp_server, "server_url", None)if server_url:- from sqlalchemy import select-result = await session.execute(select(MCPOAuth).where(MCPOAuth.server_url == server_url,@@ -326,26 +437,9 @@ class MCPManager:)return mcp_server.to_pydantic()- # @enforce_types- # async def delete_mcp_server(self, mcp_server_name: str, actor: PydanticUser) -> None:- # """Delete an existing tool."""- # with db_registry.session() as session:- # mcp_server_id = await self.get_mcp_server_id_by_name(mcp_server_name, actor)- # mcp_server = await MCPServerModel.read_async(db_session=session, identifier=mcp_server_id, actor=actor)- # if not mcp_server:- # raise HTTPException(- # status_code=404, # Not Found- # detail={- # "code": "MCPServerNotFoundError",- # "message": f"MCP server {mcp_server_name} not found",- # "mcp_server_name": mcp_server_name,- # },- # )- # mcp_server.delete(session, actor=actor) # Re-raise other database-related errors-@enforce_typesasync def delete_mcp_server_by_id(self, mcp_server_id: str, actor: PydanticUser) -> None:- """Delete a MCP server by its ID."""+ """Delete a MCP server by its ID and associated tools and OAuth sessions."""async with db_registry.async_session() as session:try:mcp_server = await MCPServerModel.read_async(db_session=session, identifier=mcp_server_id, actor=actor)@@ -353,6 +447,22 @@ class MCPManager:raise NoResultFound(f"MCP server with id {mcp_server_id} not found.")server_url = getattr(mcp_server, "server_url", None)+ # Get all tools with matching metadata+ stmt = select(ToolModel).where(ToolModel.organization_id == actor.organization_id)+ result = await session.execute(stmt)+ all_tools = result.scalars().all()++ # Filter and delete tools that belong to this MCP server+ tools_deleted = 0+ for tool in all_tools:+ if tool.metadata_ and constants.MCP_TOOL_TAG_NAME_PREFIX in tool.metadata_:+ if tool.metadata_[constants.MCP_TOOL_TAG_NAME_PREFIX].get("server_id") == mcp_server_id:+ await tool.hard_delete_async(db_session=session, actor=actor)+ tools_deleted = 1+ logger.info(f"Deleted MCP tool {tool.name} associated with MCP server {mcp_server_id}")++ if tools_deleted > 0:+ logger.info(f"Deleted {tools_deleted} MCP tools associated with MCP server {mcp_server_id}")# Delete OAuth sessions for the same user and server URL in the same transaction# This handles orphaned sessions that were created during testing/connection@@ -557,8 +667,6 @@ class MCPManager:@enforce_typesasync def get_oauth_session_by_server(self, server_url: str, actor: PydanticUser) -> Optional[MCPOAuthSession]:"""Get the latest OAuth session by server URL, organization, and user."""- from sqlalchemy import desc, select-async with db_registry.async_session() as session:# Query for OAuth session matching organization, user, server URL, and status# Order by updated_at desc to get the most recent record@@ -673,8 +781,6 @@ class MCPManager:cutoff_time = datetime.now() - timedelta(hours=max_age_hours)async with db_registry.async_session() as session:- from sqlalchemy import select-# Find expired sessionsresult = await session.execute(select(MCPOAuth).where(MCPOAuth.created_at < cutoff_time))expired_sessions = result.scalars().all()diff --git a/tests/test_managers.py b/tests/test_managers.pyindex 73882f49b..a751eec79 100644--- a/tests/test_managers.py+++ b/tests/test_managers.py@@ -10931,6 +10931,117 @@ async def test_mcp_server_delete_removes_all_sessions_for_url_and_user(server, dassert await server.mcp_manager.get_oauth_session_by_id(orphaned.id, actor=default_user) is None+async def test_mcp_server_resync_tools(server, default_user, default_organization):+ """Test that resyncing MCP server tools correctly handles added, deleted, and updated tools."""+ from unittest.mock import AsyncMock, MagicMock, patch++ from letta.functions.mcp_client.types import MCPTool, MCPToolHealth+ from letta.schemas.mcp import MCPServer as PydanticMCPServer, MCPServerType+ from letta.schemas.tool import ToolCreate++ # Create MCP server+ mcp_server = await server.mcp_manager.create_mcp_server(+ PydanticMCPServer(+ server_name=f"test_resync_{uuid.uuid4().hex[:8]}",+ server_type=MCPServerType.SSE,+ server_url="https://test-resync.example.com/mcp",+ organization_id=default_organization.id,+ ),+ actor=default_user,+ )+ mcp_server_id = mcp_server.id++ try:+ # Create initial persisted tools (simulating previously added tools)+ # Use sync method like in the existing mcp_tool fixture+ tool1_create = ToolCreate.from_mcp(+ mcp_server_name=mcp_server.server_name,+ mcp_tool=MCPTool(+ name="tool1",+ description="Tool 1",+ inputSchema={"type": "object", "properties": {"param1": {"type": "string"}}},+ ),+ )+ tool1 = server.tool_manager.create_or_update_mcp_tool(+ tool_create=tool1_create,+ mcp_server_name=mcp_server.server_name,+ mcp_server_id=mcp_server_id,+ actor=default_user,+ )++ tool2_create = ToolCreate.from_mcp(+ mcp_server_name=mcp_server.server_name,+ mcp_tool=MCPTool(+ name="tool2",+ description="Tool 2 to be deleted",+ inputSchema={"type": "object", "properties": {"param2": {"type": "number"}}},+ ),+ )+ tool2 = server.tool_manager.create_or_update_mcp_tool(+ tool_create=tool2_create,+ mcp_server_name=mcp_server.server_name,+ mcp_server_id=mcp_server_id,+ actor=default_user,+ )++ # Mock the list_mcp_server_tools to return updated tools from server+ # tool1 is updated, tool2 is deleted, tool3 is added+ updated_tools = [+ MCPTool(+ name="tool1",+ description="Tool 1 Updated",+ inputSchema={"type": "object", "properties": {"param1": {"type": "string"}, "param1b": {"type": "boolean"}}},+ health=MCPToolHealth(status="VALID", reasons=[]),+ ),+ MCPTool(+ name="tool3",+ description="Tool 3 New",+ inputSchema={"type": "object", "properties": {"param3": {"type": "array"}}},+ health=MCPToolHealth(status="VALID", reasons=[]),+ ),+ ]++ with patch.object(server.mcp_manager, "list_mcp_server_tools", new_callable=AsyncMock) as mock_list_tools:+ mock_list_tools.return_value = updated_tools++ # Run resync+ result = await server.mcp_manager.resync_mcp_server_tools(+ mcp_server_name=mcp_server.server_name,+ actor=default_user,+ )++ # Verify the resync result+ assert len(result.deleted) == 1+ assert "tool2" in result.deleted++ assert len(result.updated) == 1+ assert "tool1" in result.updated++ assert len(result.added) == 1+ assert "tool3" in result.added++ # Verify tool2 was actually deleted+ try:+ deleted_tool = server.tool_manager.get_tool_by_id(tool_id=tool2.id, actor=default_user)+ assert False, "Tool2 should have been deleted"+ except Exception:+ pass # Expected - tool should be deleted++ # Verify tool1 was updated with new schema+ updated_tool1 = server.tool_manager.get_tool_by_id(tool_id=tool1.id, actor=default_user)+ assert "param1b" in updated_tool1.json_schema["parameters"]["properties"]++ # Verify tool3 was added+ tools = await server.tool_manager.list_tools_async(actor=default_user, names=["tool3"])+ assert len(tools) == 1+ assert tools[0].name == "tool3"++ finally:+ # Clean up+ await server.mcp_manager.delete_mcp_server_by_id(mcp_server_id, actor=default_user)++# ======================================================================================================================# FileAgent Tests# ======================================================================================================================