fast-agent-mcp 0.1.13__py3-none-any.whl → 0.2.0__py3-none-any.whl

mcp_agent/mcp/gen_client.py

@@ -28,7 +28,9 @@ async def gen_client(
     For persistent connections, use connect() or MCPConnectionManager instead.
     """
     if not server_registry:
-        raise ValueError("Server registry not found in the context. Please specify one either on this method, or in the context.")
+        raise ValueError(
+            "Server registry not found in the context. Please specify one either on this method, or in the context."
+        )
 
     async with server_registry.initialize_server(
         server_name=server_name,
@@ -51,7 +53,9 @@ async def connect(
     If required, callers can specify their own message receive loop and ClientSession class constructor to customize further.
     """
     if not server_registry:
-        raise ValueError("Server registry not found in the context. Please specify one either on this method, or in the context.")
+        raise ValueError(
+            "Server registry not found in the context. Please specify one either on this method, or in the context."
+        )
 
     server_connection = await server_registry.connection_manager.get_server(
         server_name=server_name,
@@ -69,7 +73,9 @@ async def disconnect(
     Disconnect from the specified server. If server_name is None, disconnect from all servers.
     """
     if not server_registry:
-        raise ValueError("Server registry not found in the context. Please specify one either on this method, or in the context.")
+        raise ValueError(
+            "Server registry not found in the context. Please specify one either on this method, or in the context."
+        )
 
     if server_name:
         await server_registry.connection_manager.disconnect_server(server_name=server_name)

mcp_agent/mcp/interfaces.py

@@ -8,10 +8,11 @@ from typing import (
     Any,
     AsyncContextManager,
     Callable,
-    Generic,
+    Dict,
     List,
     Optional,
     Protocol,
+    Tuple,
     Type,
     TypeVar,
     Union,
@@ -19,9 +20,11 @@ from typing import (
 )
 
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
-from mcp import ClientSession
-from mcp.types import PromptMessage
+from deprecated import deprecated
+from mcp import ClientSession, GetPromptResult, ReadResourceResult
+from pydantic import BaseModel
 
+from mcp_agent.core.prompt import Prompt
 from mcp_agent.core.request_params import RequestParams
 from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
 
@@ -83,71 +86,90 @@ class ServerConnection(Protocol):
     def session(self) -> ClientSession: ...
 
 
-# Regular invariant type variables
-MessageParamT = TypeVar("MessageParamT")
-MessageT = TypeVar("MessageT")
-ModelT = TypeVar("ModelT")
+ModelT = TypeVar("ModelT", bound=BaseModel)
 
-# Variance-annotated type variables
-MessageParamT_co = TypeVar("MessageParamT_co", contravariant=True)
-MessageT_co = TypeVar("MessageT_co")
 
-
-class AugmentedLLMProtocol(Protocol, Generic[MessageParamT_co, MessageT_co]):
+class AugmentedLLMProtocol(Protocol):
     """Protocol defining the interface for augmented LLMs"""
 
-    async def generate(
-        self,
-        message: Union[str, MessageParamT_co, List[MessageParamT_co]],
-        request_params: RequestParams | None = None,
-    ) -> List[MessageT_co]:
-        """Request an LLM generation, which may run multiple iterations, and return the result"""
-        ...
-
-    async def generate_str(
-        self,
-        message: Union[str, MessageParamT_co, List[MessageParamT_co]],
-        request_params: RequestParams | None = None,
-    ) -> str:
-        """Request an LLM generation and return the string representation of the result"""
-        ...
-
     async def structured(
         self,
-        prompt: Union[str, PromptMessage, PromptMessageMultipart, List[str]],
+        prompt: List[PromptMessageMultipart],
         model: Type[ModelT],
-        request_params: RequestParams | None,
-    ) -> ModelT:
+        request_params: RequestParams | None = None,
+    ) -> Tuple[ModelT | None, PromptMessageMultipart]:
         """Apply the prompt and return the result as a Pydantic model, or None if coercion fails"""
         ...
 
-    async def generate_prompt(
-        self,
-        prompt: Union[str, PromptMessage, PromptMessageMultipart, List[str]],
-        request_params: RequestParams | None,
-    ) -> str:
-        """Request an LLM generation and return a string representation of the result"""
-        ...
-
-    async def apply_prompt(
+    async def generate(
         self,
-        multipart_messages: List["PromptMessageMultipart"],
+        multipart_messages: List[PromptMessageMultipart],
         request_params: RequestParams | None = None,
-    ) -> str:
+    ) -> PromptMessageMultipart:
         """
         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
+            A PromptMessageMultipart containing the Assistant response, including Tool Content
         """
         ...
 
 
+class AgentProtocol(AugmentedLLMProtocol, Protocol):
+    """Protocol defining the standard agent interface"""
+
+    name: str
+
+    async def __call__(self, message: Union[str, PromptMessageMultipart] | None = None) -> str:
+        """Make the agent callable for sending messages directly."""
+        ...
+
+    async def send(self, message: Union[str, PromptMessageMultipart]) -> str:
+        """Send a message to the agent and get a response"""
+        ...
+
+    async def prompt(self, default_prompt: str = "") -> str:
+        """Start an interactive prompt session with the agent"""
+        ...
+
+    async def apply_prompt(self, prompt_name: str, arguments: Dict[str, str] | None = None) -> str:
+        """Apply an MCP prompt template by name"""
+        ...
+
+    async def get_prompt(self, prompt_name: str) -> GetPromptResult: ...
+
+    async def list_prompts(self, server_name: str | None) -> Dict[str, List[Prompt]]: ...
+
+    async def get_resource(self, server_name: str, resource_uri: str) -> ReadResourceResult: ...
+
+    @deprecated
+    async def generate_str(self, message: str, request_params: RequestParams | None) -> str:
+        """Generate a response. Deprecated: please use send instead"""
+        ...
+
+    async def with_resource(
+        self,
+        prompt_content: Union[str, PromptMessageMultipart],
+        server_name: str,
+        resource_name: str,
+    ) -> str:
+        """Send a message with an attached MCP resource"""
+        ...
+
+    async def initialize(self) -> None:
+        """Initialize the agent and connect to MCP servers"""
+        ...
+
+    async def shutdown(self) -> None:
+        """Shut down the agent and close connections"""
+        ...
+
+
 class ModelFactoryClassProtocol(Protocol):
     """
     Protocol defining the minimal interface of the ModelFactory class needed by sampling.
@@ -157,7 +179,7 @@ class ModelFactoryClassProtocol(Protocol):
     @classmethod
     def create_factory(
         cls, model_string: str, request_params: Optional[RequestParams] = None
-    ) -> Callable[..., AugmentedLLMProtocol[Any, Any]]:
+    ) -> Callable[..., Any]:
         """
         Creates a factory function that can be used to construct an LLM instance.
 

mcp_agent/mcp/logger_textio.py

@@ -0,0 +1,97 @@
+"""
+Utilities for MCP stdio client integration with our logging system.
+"""
+
+import io
+import sys
+from typing import TextIO
+
+from mcp_agent.logging.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class LoggerTextIO(TextIO):
+    """
+    A TextIO implementation that logs to our application logger.
+    This implements the full TextIO interface as specified by Python.
+
+    Args:
+        server_name: The name of the server to include in logs
+    """
+
+    def __init__(self, server_name: str) -> None:
+        super().__init__()
+        self.server_name = server_name
+        # Use a StringIO for buffering
+        self._buffer = io.StringIO()
+        # Keep track of complete and partial lines
+        self._line_buffer = ""
+
+    def write(self, s: str) -> int:
+        """
+        Write data to our buffer and log any complete lines.
+        """
+        if not s:
+            return 0
+
+        # Handle line buffering for clean log output
+        text = self._line_buffer + s
+        lines = text.split("\n")
+
+        # If the text ends with a newline, the last line is complete
+        if text.endswith("\n"):
+            complete_lines = lines
+            self._line_buffer = ""
+        else:
+            # Otherwise, the last line is incomplete
+            complete_lines = lines[:-1]
+            self._line_buffer = lines[-1]
+
+        # Log complete lines but at debug level instead of info to prevent console spam
+        for line in complete_lines:
+            if line.strip():  # Only log non-empty lines
+                logger.debug(f"{self.server_name} (stderr): {line}")
+
+        # Always write to the underlying buffer
+        return self._buffer.write(s)
+
+    def flush(self) -> None:
+        """Flush the internal buffer."""
+        self._buffer.flush()
+
+    def close(self) -> None:
+        """Close the stream."""
+        # Log any remaining content in the line buffer
+        if self._line_buffer and self._line_buffer.strip():
+            logger.debug(f"{self.server_name} (stderr): {self._line_buffer}")
+        self._buffer.close()
+
+    def readable(self) -> bool:
+        return False
+
+    def writable(self) -> bool:
+        return True
+
+    def seekable(self) -> bool:
+        return False
+
+    def fileno(self) -> int:
+        """
+        Return a file descriptor for this stream.
+        We use sys.stderr's fileno since TextIO is expected to return a real file descriptor.
+        """
+        return sys.stderr.fileno()
+
+
+def get_stderr_handler(server_name: str) -> TextIO:
+    """
+    Get a stderr handler that routes MCP server errors to our logger.
+
+    Args:
+        server_name: The name of the server to include in logs
+
+    Returns:
+        A TextIO object that can be used as stderr by MCP
+    """
+    return LoggerTextIO(server_name)

mcp_agent/mcp/mcp_agent_client_session.py

@@ -91,7 +91,9 @@ class MCPAgentClientSession(ClientSession, ContextDependent):
             logger.error("send_notification failed", data=e)
             raise
 
-    async def _send_response(self, request_id: RequestId, response: SendResultT | ErrorData) -> None:
+    async def _send_response(
+        self, request_id: RequestId, response: SendResultT | ErrorData
+    ) -> None:
         logger.debug(
             f"send_response: request_id={request_id}, response=",
             data=response.model_dump(),
@@ -109,10 +111,16 @@ class MCPAgentClientSession(ClientSession, ContextDependent):
         )
         return await super()._received_notification(notification)
 
-    async def send_progress_notification(self, progress_token: str | int, progress: float, total: float | None = None) -> None:
+    async def send_progress_notification(
+        self, progress_token: str | int, progress: float, total: float | None = None
+    ) -> None:
         """
         Sends a progress notification for a request that is currently being
         processed.
         """
-        logger.debug("send_progress_notification: progress_token={progress_token}, progress={progress}, total={total}")
-        return await super().send_progress_notification(progress_token=progress_token, progress=progress, total=total)
+        logger.debug(
+            "send_progress_notification: progress_token={progress_token}, progress={progress}, total={total}"
+        )
+        return await super().send_progress_notification(
+            progress_token=progress_token, progress=progress, total=total
+        )

mcp_agent/mcp/mcp_agent_server.py

@@ -17,7 +17,9 @@ async def run() -> None:
         await app._mcp_server.run(
             read_stream,
             write_stream,
-            app._mcp_server.create_initialization_options(notification_options=NotificationOptions(tools_changed=True, resources_changed=True)),
+            app._mcp_server.create_initialization_options(
+                notification_options=NotificationOptions(tools_changed=True, resources_changed=True)
+            ),
         )