fast-agent-mcp 0.1.10__py3-none-any.whl → 0.1.12__py3-none-any.whl

mcp_agent/core/types.py

@@ -7,7 +7,9 @@ from typing import Dict, Union, TypeAlias, TYPE_CHECKING
 from mcp_agent.agents.agent import Agent
 from mcp_agent.workflows.orchestrator.orchestrator import Orchestrator
 from mcp_agent.workflows.parallel.parallel_llm import ParallelLLM
-from mcp_agent.workflows.evaluator_optimizer.evaluator_optimizer import EvaluatorOptimizerLLM
+from mcp_agent.workflows.evaluator_optimizer.evaluator_optimizer import (
+    EvaluatorOptimizerLLM,
+)
 from mcp_agent.workflows.router.router_llm import LLMRouter
 
 # Avoid circular imports
@@ -19,4 +21,4 @@ WorkflowType: TypeAlias = Union[
     Orchestrator, ParallelLLM, EvaluatorOptimizerLLM, LLMRouter
 ]
 AgentOrWorkflow: TypeAlias = Union[Agent, WorkflowType]
-ProxyDict: TypeAlias = Dict[str, "BaseAgentProxy"]  # Forward reference as string
+ProxyDict: TypeAlias = Dict[str, "BaseAgentProxy"]  # Forward reference as string

mcp_agent/core/validation.py

@@ -5,14 +5,18 @@ Validation utilities for FastAgent configuration and dependencies.
 from typing import Dict, List, Any
 from mcp_agent.core.agent_types import AgentType
 from mcp_agent.workflows.llm.augmented_llm import AugmentedLLM
-from mcp_agent.core.exceptions import ServerConfigError, AgentConfigError, CircularDependencyError
+from mcp_agent.core.exceptions import (
+    ServerConfigError,
+    AgentConfigError,
+    CircularDependencyError,
+)
 
 
 def validate_server_references(context, agents: Dict[str, Dict[str, Any]]) -> None:
     """
     Validate that all server references in agent configurations exist in config.
     Raises ServerConfigError if any referenced servers are not defined.
-    
+
     Args:
         context: Application context
         agents: Dictionary of agent configurations
@@ -39,7 +43,7 @@ def validate_workflow_references(agents: Dict[str, Dict[str, Any]]) -> None:
     Validate that all workflow references point to valid agents/workflows.
     Also validates that referenced agents have required configuration.
     Raises AgentConfigError if any validation fails.
-    
+
     Args:
         agents: Dictionary of agent configurations
     """
@@ -133,11 +137,11 @@ def validate_workflow_references(agents: Dict[str, Dict[str, Any]]) -> None:
 
 
 def get_dependencies(
-    name: str, 
+    name: str,
     agents: Dict[str, Dict[str, Any]],
-    visited: set, 
-    path: set, 
-    agent_type: AgentType = None
+    visited: set,
+    path: set,
+    agent_type: AgentType = None,
 ) -> List[str]:
     """
     Get dependencies for an agent in topological order.
@@ -184,9 +188,7 @@ def get_dependencies(
         # Get dependencies from sequence agents
         sequence = config.get("sequence", config.get("agents", []))
         for agent_name in sequence:
-            deps.extend(
-                get_dependencies(agent_name, agents, visited, path, agent_type)
-            )
+            deps.extend(get_dependencies(agent_name, agents, visited, path, agent_type))
 
     # Add this agent after its dependencies
     deps.append(name)
@@ -197,10 +199,7 @@ def get_dependencies(
 
 
 def get_parallel_dependencies(
-    name: str, 
-    agents: Dict[str, Dict[str, Any]],
-    visited: set, 
-    path: set
+    name: str, agents: Dict[str, Dict[str, Any]], visited: set, path: set
 ) -> List[str]:
     """
     Get dependencies for a parallel agent in topological order.
@@ -218,4 +217,4 @@ def get_parallel_dependencies(
     Raises:
         CircularDependencyError: If circular dependency detected
     """
-    return get_dependencies(name, agents, visited, path, AgentType.PARALLEL)
+    return get_dependencies(name, agents, visited, path, AgentType.PARALLEL)

mcp_agent/logging/transport.py

@@ -290,7 +290,7 @@ class AsyncEventBus:
             # Update transport if provided
             cls._instance.transport = transport
         return cls._instance
-        
+
     @classmethod
     def reset(cls) -> None:
         """
@@ -302,7 +302,7 @@ class AsyncEventBus:
             # Signal shutdown
             cls._instance._running = False
             cls._instance._stop_event.set()
-            
+
             # Clear the singleton instance
             cls._instance = None
 

mcp_agent/mcp/gen_client.py

@@ -6,7 +6,7 @@ from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStre
 from mcp import ClientSession
 
 from mcp_agent.logging.logger import get_logger
-from mcp_agent.mcp_server_registry import ServerRegistry
+from mcp_agent.mcp.interfaces import ServerRegistryProtocol
 from mcp_agent.mcp.mcp_agent_client_session import MCPAgentClientSession
 
 logger = get_logger(__name__)
@@ -15,7 +15,7 @@ logger = get_logger(__name__)
 @asynccontextmanager
 async def gen_client(
     server_name: str,
-    server_registry: ServerRegistry,
+    server_registry: ServerRegistryProtocol,
     client_session_factory: Callable[
         [MemoryObjectReceiveStream, MemoryObjectSendStream, timedelta | None],
         ClientSession,
@@ -41,7 +41,7 @@ async def gen_client(
 
 async def connect(
     server_name: str,
-    server_registry: ServerRegistry,
+    server_registry: ServerRegistryProtocol,
     client_session_factory: Callable[
         [MemoryObjectReceiveStream, MemoryObjectSendStream, timedelta | None],
         ClientSession,
@@ -67,7 +67,7 @@ async def connect(
 
 async def disconnect(
     server_name: str | None,
-    server_registry: ServerRegistry,
+    server_registry: ServerRegistryProtocol,
 ) -> None:
     """
     Disconnect from the specified server. If server_name is None, disconnect from all servers.

mcp_agent/mcp/interfaces.py

@@ -0,0 +1,186 @@
+"""
+Interface definitions to prevent circular imports.
+This module defines protocols (interfaces) that can be used to break circular dependencies.
+"""
+
+from contextlib import asynccontextmanager
+from typing import (
+    Any,
+    AsyncGenerator,
+    Callable,
+    Generic,
+    List,
+    Optional,
+    Protocol,
+    Type,
+    TypeVar,
+)
+
+from mcp import ClientSession
+from mcp.types import CreateMessageRequestParams
+from pydantic import Field
+
+from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+
+
+class ServerRegistryProtocol(Protocol):
+    """
+    Protocol defining the minimal interface of ServerRegistry needed by gen_client.
+    This allows gen_client to depend on this protocol rather than the full ServerRegistry class.
+    """
+
+    @asynccontextmanager
+    async def initialize_server(
+        self,
+        server_name: str,
+        client_session_factory=None,
+        init_hook=None,
+    ) -> AsyncGenerator[ClientSession, None]:
+        """Initialize a server and yield a client session."""
+        ...
+
+    @property
+    def connection_manager(self) -> "ConnectionManagerProtocol":
+        """Get the connection manager."""
+        ...
+
+
+class ConnectionManagerProtocol(Protocol):
+    """
+    Protocol defining the minimal interface of ConnectionManager needed.
+    """
+
+    async def get_server(
+        self,
+        server_name: str,
+        client_session_factory=None,
+    ):
+        """Get a server connection."""
+        ...
+
+    async def disconnect_server(self, server_name: str) -> None:
+        """Disconnect from a server."""
+        ...
+
+    async def disconnect_all_servers(self) -> None:
+        """Disconnect from all servers."""
+        ...
+
+
+# Type variables for generic protocols
+MessageParamT = TypeVar("MessageParamT")
+"""A type representing an input message to an LLM."""
+
+MessageT = TypeVar("MessageT")
+"""A type representing an output message from an LLM."""
+
+ModelT = TypeVar("ModelT")
+"""A type representing a structured output message from an LLM."""
+
+
+class RequestParams(CreateMessageRequestParams):
+    """
+    Parameters to configure the AugmentedLLM 'generate' requests.
+    """
+
+    messages: None = Field(exclude=True, default=None)
+    """
+    Ignored. 'messages' are removed from CreateMessageRequestParams 
+    to avoid confusion with the 'message' parameter on 'generate' method.
+    """
+
+    maxTokens: int = 2048
+    """The maximum number of tokens to sample, as requested by the server."""
+
+    model: str | None = None
+    """
+    The model to use for the LLM generation.
+    If specified, this overrides the 'modelPreferences' selection criteria.
+    """
+
+    use_history: bool = True
+    """
+    Include the message history in the generate request.
+    """
+
+    max_iterations: int = 10
+    """
+    The maximum number of iterations to run the LLM for.
+    """
+
+    parallel_tool_calls: bool = True
+    """
+    Whether to allow multiple tool calls per iteration.
+    Also known as multi-step tool use.
+    """
+
+
+class AugmentedLLMProtocol(Protocol, Generic[MessageParamT, MessageT]):
+    """Protocol defining the interface for augmented LLMs"""
+
+    async def generate(
+        self,
+        message: str | MessageParamT | List[MessageParamT],
+        request_params: RequestParams | None = None,
+    ) -> List[MessageT]:
+        """Request an LLM generation, which may run multiple iterations, and return the result"""
+
+    async def generate_str(
+        self,
+        message: str | MessageParamT | List[MessageParamT],
+        request_params: RequestParams | None = None,
+    ) -> str:
+        """Request an LLM generation and return the string representation of the result"""
+
+    async def generate_structured(
+        self,
+        message: str | MessageParamT | List[MessageParamT],
+        response_model: Type[ModelT],
+        request_params: RequestParams | None = None,
+    ) -> ModelT:
+        """Request a structured LLM generation and return the result as a Pydantic model."""
+
+    async def generate_prompt(
+        self, prompt: PromptMessageMultipart, request_params: RequestParams | None
+    ) -> str:
+        """Request an LLM generation and return a string representation of the result"""
+
+    async def apply_prompt(
+        self,
+        multipart_messages: List["PromptMessageMultipart"],
+        request_params: RequestParams | None = None,
+    ) -> str:
+        """
+        Apply a list of PromptMessageMultipart messages directly to the LLM.
+        This is a cleaner interface to _apply_prompt_template_provider_specific.
+
+        Args:
+            multipart_messages: List of PromptMessageMultipart objects
+            request_params: Optional parameters to configure the LLM request
+
+        Returns:
+            String representation of the assistant's response
+        """
+
+
+class ModelFactoryClassProtocol(Protocol):
+    """
+    Protocol defining the minimal interface of the ModelFactory class needed by sampling.
+    This allows sampling.py to depend on this protocol rather than the concrete ModelFactory class.
+    """
+
+    @classmethod
+    def create_factory(
+        cls, model_string: str, request_params: Optional[RequestParams] = None
+    ) -> Callable[..., AugmentedLLMProtocol[Any, Any]]:
+        """
+        Creates a factory function that can be used to construct an LLM instance.
+
+        Args:
+            model_string: The model specification string
+            request_params: Optional parameters to configure LLM behavior
+
+        Returns:
+            A factory function that can create an LLM instance
+        """
+        ...

mcp_agent/mcp/mcp_agent_client_session.py

@@ -24,6 +24,7 @@ from pydantic import AnyUrl
 from mcp_agent.config import MCPServerSettings
 from mcp_agent.context_dependent import ContextDependent
 from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.sampling import sample
 
 logger = get_logger(__name__)
 
@@ -40,7 +41,12 @@ async def list_roots(ctx: ClientSession) -> ListRootsResult:
         and ctx.session.server_config.roots
     ):
         roots = [
-            Root(uri=AnyUrl(root.uri), name=root.name)
+            Root(
+                uri=AnyUrl(
+                    root.server_uri_alias or root.uri,
+                ),
+                name=root.name,
+            )
             for root in ctx.session.server_config.roots
         ]
     return ListRootsResult(roots=roots or [])
@@ -58,7 +64,9 @@ class MCPAgentClientSession(ClientSession, ContextDependent):
     """
 
     def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs, list_roots_callback=list_roots)
+        super().__init__(
+            *args, **kwargs, list_roots_callback=list_roots, sampling_callback=sample
+        )
         self.server_config: Optional[MCPServerSettings] = None
 
     async def send_request(

mcp_agent/mcp/mcp_aggregator.py

@@ -16,6 +16,7 @@ from mcp.server.stdio import stdio_server
 from mcp.types import (
     CallToolResult,
     ListToolsResult,
+    TextContent,
     Tool,
     Prompt,
 )
@@ -459,7 +460,10 @@ class MCPAggregator(ContextDependent):
 
         if server_name is None or local_tool_name is None:
             logger.error(f"Error: Tool '{name}' not found")
-            return CallToolResult(isError=True, message=f"Tool '{name}' not found")
+            return CallToolResult(
+                isError=True,
+                content=[TextContent(type="text", text=f"Tool '{name}' not found")],
+            )
 
         logger.info(
             "Requesting tool call",
@@ -477,7 +481,9 @@ class MCPAggregator(ContextDependent):
             operation_name=local_tool_name,
             method_name="call_tool",
             method_args={"name": local_tool_name, "arguments": arguments},
-            error_factory=lambda msg: CallToolResult(isError=True, message=msg),
+            error_factory=lambda msg: CallToolResult(
+                isError=True, content=[TextContent(type="text", text=msg)]
+            ),
         )
 
     async def get_prompt(
@@ -898,7 +904,10 @@ class MCPCompoundServer(Server):
             result = await self.aggregator.call_tool(name=name, arguments=arguments)
             return result.content
         except Exception as e:
-            return CallToolResult(isError=True, message=f"Error calling tool: {e}")
+            return CallToolResult(
+                isError=True,
+                content=[TextContent(type="text", text=f"Error calling tool: {e}")],
+            )
 
     async def _get_prompt(
         self, name: str = None, arguments: dict[str, str] = None

mcp_agent/mcp/sampling.py

@@ -0,0 +1,140 @@
+"""
+This simplified implementation directly converts between MCP types and PromptMessageMultipart.
+"""
+
+from mcp import ClientSession
+from mcp.types import (
+    CreateMessageRequestParams,
+    CreateMessageResult,
+)
+
+from mcp_agent.core.agent_types import AgentConfig
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.interfaces import AugmentedLLMProtocol
+
+from mcp_agent.workflows.llm.sampling_converter import SamplingConverter
+
+logger = get_logger(__name__)
+
+
+def create_sampling_llm(
+    params: CreateMessageRequestParams, model_string: str
+) -> AugmentedLLMProtocol:
+    """
+    Create an LLM instance for sampling without tools support.
+    This utility function creates a minimal LLM instance based on the model string.
+
+    Args:
+        mcp_ctx: The MCP ClientSession
+        model_string: The model to use (e.g. "passthrough", "claude-3-5-sonnet-latest")
+
+    Returns:
+        An initialized LLM instance ready to use
+    """
+    from mcp_agent.workflows.llm.model_factory import ModelFactory
+    from mcp_agent.agents.agent import Agent
+
+    app_context = None
+    try:
+        from mcp_agent.context import get_current_context
+
+        app_context = get_current_context()
+    except Exception:
+        logger.warning("App context not available for sampling call")
+
+    agent = Agent(
+        config=sampling_agent_config(params),
+        context=app_context,
+        connection_persistence=False,
+    )
+
+    # Create the LLM using the factory
+    factory = ModelFactory.create_factory(model_string)
+    llm = factory(agent=agent)
+
+    # Attach the LLM to the agent
+    agent._llm = llm
+
+    return llm
+
+
+async def sample(
+    mcp_ctx: ClientSession, params: CreateMessageRequestParams
+) -> CreateMessageResult:
+    """
+    Handle sampling requests from the MCP protocol using SamplingConverter.
+
+    This function:
+    1. Extracts the model from the request
+    2. Uses SamplingConverter to convert types
+    3. Calls the LLM's generate_prompt method
+    4. Returns the result as a CreateMessageResult
+
+    Args:
+        mcp_ctx: The MCP ClientSession
+        params: The sampling request parameters
+
+    Returns:
+        A CreateMessageResult containing the LLM's response
+    """
+    model = None
+    try:
+        # Extract model from server config
+        if (
+            hasattr(mcp_ctx, "session")
+            and hasattr(mcp_ctx.session, "server_config")
+            and mcp_ctx.session.server_config
+            and hasattr(mcp_ctx.session.server_config, "sampling")
+            and mcp_ctx.session.server_config.sampling.model
+        ):
+            model = mcp_ctx.session.server_config.sampling.model
+
+        if model is None:
+            raise ValueError("No model configured")
+
+        # Create an LLM instance
+        llm = create_sampling_llm(params, model)
+
+        # Extract all messages from the request params
+        if not params.messages:
+            raise ValueError("No messages provided")
+
+        # Convert all SamplingMessages to PromptMessageMultipart objects
+        conversation = SamplingConverter.convert_messages(params.messages)
+
+        # Extract request parameters using our converter
+        request_params = SamplingConverter.extract_request_params(params)
+
+        # Use the new public apply_prompt method which is cleaner than calling the protected method
+        llm_response = await llm.apply_prompt(conversation, request_params)
+        logger.info(f"Complete sampling request : {llm_response[:50]}...")
+
+        # Create result using our converter
+        return SamplingConverter.create_message_result(
+            response=llm_response, model=model
+        )
+    except Exception as e:
+        logger.error(f"Error in sampling: {str(e)}")
+        return SamplingConverter.error_result(
+            error_message=f"Error in sampling: {str(e)}", model=model
+        )
+
+
+def sampling_agent_config(
+    params: CreateMessageRequestParams = None,
+) -> AgentConfig:
+    """
+    Build a sampling AgentConfig based on request parameters.
+
+    Args:
+        params: Optional CreateMessageRequestParams that may contain a system prompt
+
+    Returns:
+        An initialized AgentConfig for use in sampling
+    """
+    # Use systemPrompt from params if available, otherwise use default
+    instruction = "You are a helpful AI Agent."
+    if params and hasattr(params, "systemPrompt") and params.systemPrompt is not None:
+        instruction = params.systemPrompt
+
+    return AgentConfig(name="sampling_agent", instruction=instruction, servers=[])

mcp_agent/mcp/stdio.py

@@ -14,7 +14,7 @@ from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStre
 logger = get_logger(__name__)
 
 
-# TODO this will be removed when client library 1.4.2 is released
+# TODO this will be removed when client library with https://github.com/modelcontextprotocol/python-sdk/pull/343 is released
 @asynccontextmanager
 async def stdio_client_with_rich_stderr(server: StdioServerParameters):
     """
@@ -95,7 +95,6 @@ async def stdio_client_with_rich_stderr(server: StdioServerParameters):
             async with write_stream_reader:
                 async for message in write_stream_reader:
                     json = message.model_dump_json(by_alias=True, exclude_none=True)
-                    print(f"**********{id(process.stdin)}")
                     await process.stdin.send(
                         (json + "\n").encode(
                             encoding=server.encoding,

mcp_agent/mcp_server/__init__.py

@@ -1,4 +1,4 @@
 # Import and re-export AgentMCPServer to avoid circular imports
 from mcp_agent.mcp_server.agent_server import AgentMCPServer
 
-__all__ = ["AgentMCPServer"]
+__all__ = ["AgentMCPServer"]

mcp_agent/resources/examples/internal/agent.py

@@ -6,7 +6,7 @@ fast = FastAgent("FastAgent Example")
 
 
 # Define the agent
-@fast.agent(servers=["fetch"])
+@fast.agent(servers=["fetch", "mcp_hfspace"])
 async def main():
     # use the --model command line switch or agent arguments to change model
     async with fast.run() as agent:

mcp_agent/resources/examples/internal/fastagent.config.yaml

@@ -50,3 +50,6 @@ mcp:
     category:
       command: "uv"
       args: ["run", "prompt_category.py"]
+    mcp_hfspace:
+      command: "npx"
+      args: ["@llmindset/mcp-hfspace"]

mcp_agent/resources/examples/prompting/__init__.py

@@ -1,3 +1,3 @@
 """
 Prompting examples package for MCP Agent.
-"""
+"""

mcp_agent/ui/console_display.py

@@ -250,14 +250,14 @@ class ConsoleDisplay:
 
         if agent_name:
             content.append(f" for {agent_name}", style="cyan italic")
-            
+
         # Add template arguments if provided
         if arguments:
             content.append("\n\nArguments:", style="cyan")
             for key, value in arguments.items():
                 content.append(f"\n  {key}: ", style="cyan bold")
                 content.append(value, style="white")
-                
+
         if description:
             content.append("\n\n", style="default")
             content.append(description, style="dim white")

mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py

@@ -10,7 +10,8 @@ from mcp_agent.workflows.llm.augmented_llm import (
     ModelT,
     RequestParams,
 )
-from mcp_agent.agents.agent import Agent, AgentConfig
+from mcp_agent.agents.agent import Agent
+from mcp_agent.core.agent_types import AgentConfig
 from mcp_agent.logging.logger import get_logger
 from mcp_agent.workflows.llm.augmented_llm_passthrough import PassthroughLLM
 
@@ -68,7 +69,6 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
     def _initialize_default_params(self, kwargs: dict) -> RequestParams:
         """Initialize default parameters using the workflow's settings."""
         return RequestParams(
-            modelPreferences=self.model_preferences,
             systemPrompt=self.instruction,
             parallel_tool_calls=True,
             max_iterations=10,