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

mcp_agent/mcp/prompts/prompt_helpers.py

@@ -0,0 +1,327 @@
+"""
+Helper functions for working with PromptMessage and PromptMessageMultipart objects.
+
+These utilities simplify extracting content from nested message structures
+without repetitive type checking.
+"""
+
+from typing import List, Optional, Union, cast
+
+from mcp.types import (
+    BlobResourceContents,
+    EmbeddedResource,
+    ImageContent,
+    PromptMessage,
+    TextContent,
+    TextResourceContents,
+)
+
+from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+
+
+def get_text(content: Union[TextContent, ImageContent, EmbeddedResource]) -> Optional[str]:
+    """
+    Extract text content from a content object if available.
+
+    Args:
+        content: A content object (TextContent, ImageContent, or EmbeddedResource)
+
+    Returns:
+        The text content as a string or None if not a text content
+    """
+    if isinstance(content, TextContent):
+        return content.text
+
+    if isinstance(content, EmbeddedResource):
+        if isinstance(content.resource, TextResourceContents):
+            return content.resource.text
+
+    return None
+
+
+def get_image_data(content: Union[TextContent, ImageContent, EmbeddedResource]) -> Optional[str]:
+    """
+    Extract image data from a content object if available.
+
+    Args:
+        content: A content object (TextContent, ImageContent, or EmbeddedResource)
+
+    Returns:
+        The image data as a base64 string or None if not an image content
+    """
+    if isinstance(content, ImageContent):
+        return content.data
+
+    if isinstance(content, EmbeddedResource):
+        if isinstance(content.resource, BlobResourceContents):
+            # This assumes the blob might be an image, which isn't always true
+            # Consider checking the mimeType if needed
+            return content.resource.blob
+
+    return None
+
+
+def get_resource_uri(content: Union[TextContent, ImageContent, EmbeddedResource]) -> Optional[str]:
+    """
+    Extract resource URI from an EmbeddedResource if available.
+
+    Args:
+        content: A content object (TextContent, ImageContent, or EmbeddedResource)
+
+    Returns:
+        The resource URI as a string or None if not an embedded resource
+    """
+    if isinstance(content, EmbeddedResource):
+        return str(content.resource.uri)
+
+    return None
+
+
+def is_text_content(content: Union[TextContent, ImageContent, EmbeddedResource]) -> bool:
+    """
+    Check if the content is text content.
+
+    Args:
+        content: A content object (TextContent, ImageContent, or EmbeddedResource)
+
+    Returns:
+        True if the content is TextContent, False otherwise
+    """
+    return isinstance(content, TextContent)
+
+
+def is_image_content(content: Union[TextContent, ImageContent, EmbeddedResource]) -> bool:
+    """
+    Check if the content is image content.
+
+    Args:
+        content: A content object (TextContent, ImageContent, or EmbeddedResource)
+
+    Returns:
+        True if the content is ImageContent, False otherwise
+    """
+    return isinstance(content, ImageContent)
+
+
+def is_resource_content(content: Union[TextContent, ImageContent, EmbeddedResource]) -> bool:
+    """
+    Check if the content is an embedded resource.
+
+    Args:
+        content: A content object (TextContent, ImageContent, or EmbeddedResource)
+
+    Returns:
+        True if the content is EmbeddedResource, False otherwise
+    """
+    return isinstance(content, EmbeddedResource)
+
+
+class MessageContent:
+    """
+    Helper class for working with message content in both PromptMessage and
+    PromptMessageMultipart objects.
+    """
+
+    @staticmethod
+    def get_all_text(message: Union[PromptMessage, PromptMessageMultipart]) -> List[str]:
+        """
+        Extract all text content from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            List of text strings from all text content parts
+        """
+        if isinstance(message, PromptMessage):
+            text = get_text(message.content)
+            return [text] if text is not None else []
+
+        result = []
+        for content in message.content:
+            text = get_text(content)
+            if text is not None:
+                result.append(text)
+
+        return result
+
+    @staticmethod
+    def join_text(
+        message: Union[PromptMessage, PromptMessageMultipart], separator: str = "\n\n"
+    ) -> str:
+        """
+        Join all text content in a message with a separator.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+            separator: String to use as separator (default: newlines)
+
+        Returns:
+            Joined text string
+        """
+        return separator.join(MessageContent.get_all_text(message))
+
+    @staticmethod
+    def get_first_text(message: Union[PromptMessage, PromptMessageMultipart]) -> Optional[str]:
+        """
+        Get the first available text content from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            First text content or None if no text content exists
+        """
+        if isinstance(message, PromptMessage):
+            return get_text(message.content)
+
+        for content in message.content:
+            text = get_text(content)
+            if text is not None:
+                return text
+
+        return None
+
+    @staticmethod
+    def has_text_at_first_position(message: Union[PromptMessage, PromptMessageMultipart]) -> bool:
+        """
+        Check if a message has a TextContent at the first position.
+        This is a common case when dealing with messages that start with text.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            True if the message has TextContent at first position, False otherwise
+        """
+        if isinstance(message, PromptMessage):
+            return isinstance(message.content, TextContent)
+
+        # For multipart messages, check if there's at least one item and the first is TextContent
+        return len(message.content) > 0 and isinstance(message.content[0], TextContent)
+
+    @staticmethod
+    def get_text_at_first_position(
+        message: Union[PromptMessage, PromptMessageMultipart],
+    ) -> Optional[str]:
+        """
+        Get the text from the first position of a message if it's TextContent.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            The text content at the first position if it's TextContent,
+            None otherwise
+        """
+        if not MessageContent.has_text_at_first_position(message):
+            return None
+
+        if isinstance(message, PromptMessage):
+            return cast("TextContent", message.content).text
+
+        # Safe to cast since we've verified the first item is TextContent
+        return cast("TextContent", message.content[0]).text
+
+    @staticmethod
+    def get_all_images(message: Union[PromptMessage, PromptMessageMultipart]) -> List[str]:
+        """
+        Extract all image data from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            List of image data strings from all image content parts
+        """
+        if isinstance(message, PromptMessage):
+            img_data = get_image_data(message.content)
+            return [img_data] if img_data is not None else []
+
+        result = []
+        for content in message.content:
+            img_data = get_image_data(content)
+            if img_data is not None:
+                result.append(img_data)
+
+        return result
+
+    @staticmethod
+    def get_first_image(message: Union[PromptMessage, PromptMessageMultipart]) -> Optional[str]:
+        """
+        Get the first available image data from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            First image data or None if no image content exists
+        """
+        if isinstance(message, PromptMessage):
+            return get_image_data(message.content)
+
+        for content in message.content:
+            img_data = get_image_data(content)
+            if img_data is not None:
+                return img_data
+
+        return None
+
+    @staticmethod
+    def get_all_resources(
+        message: Union[PromptMessage, PromptMessageMultipart],
+    ) -> List[EmbeddedResource]:
+        """
+        Extract all embedded resources from a message.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            List of EmbeddedResource objects
+        """
+        if isinstance(message, PromptMessage):
+            if isinstance(message.content, EmbeddedResource):
+                return [message.content]
+            return []
+
+        return [content for content in message.content if isinstance(content, EmbeddedResource)]
+
+    @staticmethod
+    def has_text(message: Union[PromptMessage, PromptMessageMultipart]) -> bool:
+        """
+        Check if the message has any text content.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            True if the message has text content, False otherwise
+        """
+        return len(MessageContent.get_all_text(message)) > 0
+
+    @staticmethod
+    def has_images(message: Union[PromptMessage, PromptMessageMultipart]) -> bool:
+        """
+        Check if the message has any image content.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            True if the message has image content, False otherwise
+        """
+        return len(MessageContent.get_all_images(message)) > 0
+
+    @staticmethod
+    def has_resources(message: Union[PromptMessage, PromptMessageMultipart]) -> bool:
+        """
+        Check if the message has any embedded resources.
+
+        Args:
+            message: A PromptMessage or PromptMessageMultipart
+
+        Returns:
+            True if the message has embedded resources, False otherwise
+        """
+        return len(MessageContent.get_all_resources(message)) > 0

mcp_agent/mcp/prompts/prompt_load.py

@@ -0,0 +1,109 @@
+from pathlib import Path
+from typing import List, Literal
+
+from mcp.server.fastmcp.prompts.base import (
+    AssistantMessage,
+    Message,
+    UserMessage,
+)
+from mcp.types import PromptMessage, TextContent
+
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp import mime_utils, resource_utils
+from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+from mcp_agent.mcp.prompts.prompt_template import (
+    PromptContent,
+    PromptTemplate,
+    PromptTemplateLoader,
+)
+
+# Define message role type
+MessageRole = Literal["user", "assistant"]
+logger = get_logger("prompt_load")
+
+
+def cast_message_role(role: str) -> MessageRole:
+    """Cast a string role to a MessageRole literal type"""
+    if role == "user" or role == "assistant":
+        return role  # type: ignore
+    # Default to user if the role is invalid
+    logger.warning(f"Invalid message role: {role}, defaulting to 'user'")
+    return "user"
+
+
+def create_messages_with_resources(
+    content_sections: List[PromptContent], prompt_files: List[Path]
+) -> List[PromptMessage]:
+    """
+    Create a list of messages from content sections, with resources properly handled.
+
+    This implementation produces one message for each content section's text,
+    followed by separate messages for each resource (with the same role type
+    as the section they belong to).
+
+    Args:
+        content_sections: List of PromptContent objects
+        prompt_files: List of prompt files (to help locate resource files)
+
+    Returns:
+        List of Message objects
+    """
+
+    messages = []
+
+    for section in content_sections:
+        # Convert to our literal type for role
+        role = cast_message_role(section.role)
+
+        # Add the text message
+        messages.append(create_content_message(section.text, role))
+
+        # Add resource messages with the same role type as the section
+        for resource_path in section.resources:
+            try:
+                # Load resource with information about its type
+                resource_content, mime_type, is_binary = resource_utils.load_resource_content(
+                    resource_path, prompt_files
+                )
+
+                # Create and add the resource message
+                resource_message = create_resource_message(
+                    resource_path, resource_content, mime_type, is_binary, role
+                )
+                messages.append(resource_message)
+            except Exception as e:
+                logger.error(f"Error loading resource {resource_path}: {e}")
+
+    return messages
+
+
+def create_content_message(text: str, role: MessageRole) -> PromptMessage:
+    """Create a text content message with the specified role"""
+    return PromptMessage(role=role, content=TextContent(type="text", text=text))
+
+
+def create_resource_message(
+    resource_path: str, content: str, mime_type: str, is_binary: bool, role: MessageRole
+) -> Message:
+    """Create a resource message with the specified content and role"""
+    message_class = UserMessage if role == "user" else AssistantMessage
+
+    if mime_utils.is_image_mime_type(mime_type):
+        # For images, create an ImageContent
+        image_content = resource_utils.create_image_content(data=content, mime_type=mime_type)
+        return message_class(content=image_content)
+    else:
+        # For other resources, create an EmbeddedResource
+        embedded_resource = resource_utils.create_embedded_resource(
+            resource_path, content, mime_type, is_binary
+        )
+        return message_class(content=embedded_resource)
+
+
+def load_prompt(file: Path) -> List[PromptMessage]:
+    template: PromptTemplate = PromptTemplateLoader().load_from_file(file)
+    return create_messages_with_resources(template.content_sections, [file])
+
+
+def load_prompt_multipart(file: Path) -> List[PromptMessageMultipart]:
+    return PromptMessageMultipart.to_multipart(load_prompt(file))