fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/mcp/ui_agent.py

@@ -0,0 +1,48 @@
+"""
+MCP Agent with UI support using mixin pattern.
+
+This module provides a concrete agent class that combines McpAgent
+with UI functionality through the mixin pattern.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fast_agent.agents import McpAgent
+from fast_agent.mcp.ui_mixin import McpUIMixin
+
+if TYPE_CHECKING:
+    from fast_agent.context import Context
+
+
+class McpAgentWithUI(McpUIMixin, McpAgent):
+    """
+    MCP Agent with UI resource handling capabilities.
+
+    This class combines the base McpAgent functionality with UI resource
+    processing using the mixin pattern. It's a clean, type-safe way to add
+    UI functionality without the complexity of wrapper classes.
+
+    Usage:
+        agent = McpAgentWithUI(config, context=context, ui_mode="auto")
+    """
+
+    def __init__(
+        self,
+        config,
+        context: "Context | None" = None,
+        ui_mode: str = "auto",
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize the agent with UI capabilities.
+
+        Args:
+            config: Agent configuration
+            context: Application context
+            ui_mode: UI mode - "disabled", "enabled", or "auto"
+            **kwargs: Additional arguments passed to parent classes
+        """
+        # Initialize both parent classes with the ui_mode parameter
+        super().__init__(config=config, context=context, ui_mode=ui_mode, **kwargs)

fast_agent/mcp/ui_mixin.py

@@ -0,0 +1,209 @@
+"""
+MCP UI Mixin - Clean mixin pattern for MCP UI functionality.
+
+This module provides a mixin class that can be combined with McpAgent
+to add UI resource handling without modifying the base agent implementation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+from mcp.types import CallToolResult, ContentBlock, EmbeddedResource
+
+from fast_agent.constants import MCP_UI
+from fast_agent.ui.mcp_ui_utils import open_links_in_browser, ui_links_from_channel
+
+if TYPE_CHECKING:
+    from rich.text import Text
+
+    from fast_agent.types import PromptMessageExtended
+
+
+class McpUIMixin:
+    """
+    Mixin that adds MCP-UI resource handling to any agent.
+
+    This mixin can be combined with any agent class to add UI resource
+    extraction and display functionality. It overrides run_tools to
+    intercept tool results and extract UI resources.
+
+    Usage:
+        class MyAgentWithUI(McpUIMixin, McpAgent):
+            def __init__(self, *args, ui_mode: str = "auto", **kwargs):
+                super().__init__(*args, **kwargs)
+                self._ui_mode = ui_mode
+    """
+
+    def __init__(self, *args, ui_mode: str = "auto", **kwargs):
+        """Initialize the mixin with UI mode configuration."""
+        super().__init__(*args, **kwargs)
+        self._ui_mode: str = ui_mode
+        self._pending_ui_resources: list[ContentBlock] = []
+
+    def set_ui_mode(self, mode: str) -> None:
+        """
+        Set the UI mode for handling MCP-UI resources.
+
+        Args:
+            mode: One of "disabled", "enabled", or "auto"
+        """
+        if mode not in ("disabled", "enabled", "auto"):
+            mode = "auto"
+        self._ui_mode = mode
+
+    async def run_tools(self, request: "PromptMessageExtended") -> "PromptMessageExtended":
+        """
+        Override run_tools to extract and handle UI resources.
+
+        This method intercepts tool results, extracts any UI resources,
+        and adds them to the message channels for later display.
+        """
+        # If UI is disabled, just pass through to parent
+        if self._ui_mode == "disabled":
+            return await super().run_tools(request)  # type: ignore
+
+        # Run the tools normally via parent implementation
+        result = await super().run_tools(request)  # type: ignore
+
+        # Extract UI resources from tool results
+        if result and result.tool_results:
+            processed_results, ui_blocks = self._extract_ui_from_tool_results(result.tool_results)
+
+            # For mode 'auto', only act when we actually extracted something
+            if self._ui_mode == "enabled" or (self._ui_mode == "auto" and ui_blocks):
+                # Update tool_results with UI resources removed
+                result.tool_results = processed_results
+
+                # Add UI resources to channels
+                channels = result.channels or {}
+                current = channels.get(MCP_UI, [])
+                channels[MCP_UI] = current + ui_blocks
+                result.channels = channels
+
+                # Store for display after assistant message
+                self._pending_ui_resources = ui_blocks
+
+        return result
+
+    async def show_assistant_message(
+        self,
+        message: "PromptMessageExtended",
+        bottom_items: list[str] | None = None,
+        highlight_items: str | list[str] | None = None,
+        max_item_length: int | None = None,
+        name: str | None = None,
+        model: str | None = None,
+        additional_message: "Text" | None = None,
+    ) -> None:
+        """Override to display UI resources after showing assistant message."""
+        # Show the assistant message normally via parent
+        await super().show_assistant_message(  # type: ignore
+            message,
+            bottom_items,
+            highlight_items,
+            max_item_length,
+            name=name,
+            model=model,
+            additional_message=additional_message,
+        )
+
+        # Handle any pending UI resources from the previous user message
+        if self._ui_mode != "disabled":
+            await self._display_ui_resources_from_history()
+
+    async def _display_ui_resources_from_history(self) -> None:
+        """
+        Check message history for UI resources and display them.
+
+        This looks at the previous user message for any UI resources
+        that should be displayed after the assistant's response.
+        """
+        try:
+            history = self.message_history  # type: ignore
+            if history and len(history) >= 2:
+                prev = history[-2]
+                if prev and prev.role == "user":
+                    channels = prev.channels or {}
+                    ui_resources = channels.get(MCP_UI, []) if isinstance(channels, dict) else []
+                    if ui_resources:
+                        await self._display_ui_resources(ui_resources)
+        except Exception:
+            # Silently handle any errors in UI display
+            pass
+
+    async def _display_ui_resources(self, resources: Sequence[ContentBlock]) -> None:
+        """
+        Display UI resources by creating links and optionally opening in browser.
+
+        Args:
+            resources: List of UI resource content blocks
+        """
+        links = ui_links_from_channel(resources)
+        if links:
+            # Display links in console
+            await self.display.show_mcp_ui_links(links)  # type: ignore
+
+            # Auto-open in browser if in auto mode
+            if self._ui_mode == "auto":
+                open_links_in_browser(links, mcp_ui_mode=self._ui_mode)
+
+    def _extract_ui_from_tool_results(
+        self,
+        tool_results: dict[str, CallToolResult],
+    ) -> tuple[dict[str, CallToolResult], list[ContentBlock]]:
+        """
+        Extract UI resources from tool results.
+
+        Returns a tuple of (cleaned_tool_results, extracted_ui_blocks).
+        """
+        if not tool_results:
+            return tool_results, []
+
+        extracted_ui: list[ContentBlock] = []
+        new_results: dict[str, CallToolResult] = {}
+
+        for key, result in tool_results.items():
+            try:
+                ui_blocks, other_blocks = self._split_ui_blocks(list(result.content or []))
+                if ui_blocks:
+                    extracted_ui.extend(ui_blocks)
+
+                # Recreate CallToolResult without UI blocks
+                new_results[key] = CallToolResult(content=other_blocks, isError=result.isError)
+            except Exception:
+                # Pass through untouched on any error
+                new_results[key] = result
+
+        return new_results, extracted_ui
+
+    def _split_ui_blocks(
+        self, blocks: list[ContentBlock]
+    ) -> tuple[list[ContentBlock], list[ContentBlock]]:
+        """
+        Split content blocks into UI and non-UI blocks.
+
+        Returns tuple of (ui_blocks, other_blocks).
+        """
+        ui_blocks: list[ContentBlock] = []
+        other_blocks: list[ContentBlock] = []
+
+        for block in blocks or []:
+            if self._is_ui_embedded_resource(block):
+                ui_blocks.append(block)
+            else:
+                other_blocks.append(block)
+
+        return ui_blocks, other_blocks
+
+    def _is_ui_embedded_resource(self, block: ContentBlock) -> bool:
+        """Check if a content block is a UI embedded resource."""
+        try:
+            if isinstance(block, EmbeddedResource):
+                res = block.resource
+                uri = res.uri if res else None
+                if uri is not None:
+                    return str(uri).startswith("ui://")
+        except Exception:
+            pass
+        return False

fast_agent/mcp_server_registry.py

@@ -0,0 +1,89 @@
+"""
+This module defines a `ServerRegistry` class for managing MCP server configurations
+and initialization logic.
+
+The class loads server configurations from a YAML file,
+supports dynamic registration of initialization hooks, and provides methods for
+server initialization.
+"""
+
+
+from fast_agent.config import (
+    MCPServerSettings,
+    Settings,
+    get_settings,
+)
+from fast_agent.core.logging.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ServerRegistry:
+    """
+    Maps MCP Server configurations to names; can be populated from a YAML file (other formats soon)
+
+    Attributes:
+        config_path (str): Path to the YAML configuration file.
+        registry (dict[str, MCPServerSettings]): Loaded server configurations.
+    """
+
+    registry: dict[str, MCPServerSettings] = {}
+
+    def __init__(
+        self,
+        config: Settings | None = None,
+    ) -> None:
+        """
+        Initialize the ServerRegistry with a configuration file.
+
+        Args:
+            config (Settings): The Settings object containing the server configurations.
+            config_path (str): Path to the YAML configuration file.
+        """
+        if config is not None and config.mcp is not None:
+            self.registry = config.mcp.servers or {}
+
+    ## TODO-- leaving this here to support more file formats to add servers
+    def load_registry_from_file(
+        self, config_path: str | None = None
+    ) -> dict[str, MCPServerSettings]:
+        """
+        Load the YAML configuration file and validate it.
+
+        Returns:
+            dict[str, MCPServerSettings]: A dictionary of server configurations.
+
+        Raises:
+            ValueError: If the configuration is invalid.
+        """
+        servers = {}
+
+        settings = get_settings(config_path)
+
+        if (
+            settings.mcp is not None
+            and hasattr(settings.mcp, "servers")
+            and settings.mcp.servers is not None
+        ):
+            return settings.mcp.servers
+
+        return servers
+
+    def get_server_config(self, server_name: str) -> MCPServerSettings | None:
+        """
+        Get the configuration for a specific server.
+
+        Args:
+            server_name (str): The name of the server.
+
+        Returns:
+            MCPServerSettings: The server configuration.
+        """
+
+        server_config = self.registry.get(server_name)
+        if server_config is None:
+            logger.warning(f"Server '{server_name}' not found in registry.")
+            return None
+        elif server_config.name is None:
+            server_config.name = server_name
+        return server_config

fast_agent/resources/examples/data-analysis/analysis-campaign.py

@@ -0,0 +1,189 @@
+import asyncio
+
+from fast_agent import FastAgent
+from fast_agent.llm.fastagent_llm import RequestParams
+
+# Create the application
+fast = FastAgent("Data Analysis & Campaign Generator")
+
+
+# Original data analysis components
+@fast.agent(
+    name="data_analysis",
+    instruction="""
+You have access to a Python 3.12 interpreter and you can use this to analyse and process data. 
+Common analysis packages such as Pandas, Seaborn and Matplotlib are already installed. 
+You can add further packages if needed.
+Data files are accessible from the /mnt/data/ directory (this is the current working directory).
+Visualisations should be saved as .png files in the current working directory.
+Extract key insights that would be compelling for a social media campaign.
+""",
+    servers=["interpreter"],
+    request_params=RequestParams(maxTokens=8192),
+    model="sonnet",
+)
+@fast.agent(
+    "evaluator",
+    """You are collaborating with a Data Analysis tool that has the capability to analyse data and produce visualisations.
+    You must make sure that the tool has:
+     - Considered the best way for a Human to interpret the data
+     - Produced insightful visualisations.
+     - Provided a high level summary report for the Human.
+     - Has had its findings challenged, and justified
+     - Extracted compelling insights suitable for social media promotion
+    """,
+    request_params=RequestParams(maxTokens=8192),
+    model="gpt-4.1",
+)
+@fast.evaluator_optimizer(
+    "analysis_tool",
+    generator="data_analysis",
+    evaluator="evaluator",
+    max_refinements=3,
+    min_rating="EXCELLENT",
+)
+# Research component using Brave search
+@fast.agent(
+    "context_researcher",
+    """You are a research specialist who provides cultural context for different regions.
+    For any given data insight and target language/region, research:
+    1. Cultural sensitivities related to presenting this type of data
+    2. Local social media trends and preferences
+    3. Region-specific considerations for marketing campaigns
+    
+    Always provide actionable recommendations for adapting content to each culture.
+    """,
+    servers=["fetch", "brave"],  # Using the fetch MCP server for Brave search
+    request_params=RequestParams(temperature=0.3),
+    model="gpt-4.1",
+)
+# Social media content generator
+@fast.agent(
+    "campaign_generator",
+    """Generate engaging social media content based on data insights.
+    Create compelling, shareable content that:
+    - Highlights key research findings in an accessible way
+    - Uses appropriate tone for the platform (Twitter/X, LinkedIn, Instagram, etc.)
+    - Is concise and impactful
+    - Includes suggested hashtags and posting schedule
+    
+    Format your response with clear sections for each platform.
+    Save different campaign elements as separate files in the current directory.
+    """,
+    servers=["filesystem"],  # Using filesystem MCP server to save files
+    request_params=RequestParams(temperature=0.7),
+    model="sonnet",
+    use_history=False,
+)
+# Translation agents with cultural adaptation
+@fast.agent(
+    "translate_fr",
+    """Translate social media content to French with cultural adaptation.
+    Consider French cultural norms, expressions, and social media preferences.
+    Ensure the translation maintains the impact of the original while being culturally appropriate.
+    Save the translated content to a file with appropriate naming.
+    """,
+    model="haiku",
+    use_history=False,
+    servers=["filesystem"],
+)
+@fast.agent(
+    "translate_es",
+    """Translate social media content to Spanish with cultural adaptation.
+    Consider Spanish-speaking cultural contexts, expressions, and social media preferences.
+    Ensure the translation maintains the impact of the original while being culturally appropriate.
+    Save the translated content to a file with appropriate naming.
+    """,
+    model="haiku",
+    use_history=False,
+    servers=["filesystem"],
+)
+@fast.agent(
+    "translate_de",
+    """Translate social media content to German with cultural adaptation.
+    Consider German cultural norms, expressions, and social media preferences.
+    Ensure the translation maintains the impact of the original while being culturally appropriate.
+    Save the translated content to a file with appropriate naming.
+    """,
+    model="haiku",
+    use_history=False,
+    servers=["filesystem"],
+)
+@fast.agent(
+    "translate_ja",
+    """Translate social media content to Japanese with cultural adaptation.
+    Consider Japanese cultural norms, expressions, and social media preferences.
+    Ensure the translation maintains the impact of the original while being culturally appropriate.
+    Save the translated content to a file with appropriate naming.
+    """,
+    model="haiku",
+    use_history=False,
+    servers=["filesystem"],
+)
+# Parallel workflow for translations
+@fast.parallel(
+    "translate_campaign",
+    instruction="Translates content to French, Spanish, German and Japanese. Supply the content to translate, translations will be saved to the filesystem.",
+    fan_out=["translate_fr", "translate_es", "translate_de", "translate_ja"],
+    include_request=True,
+)
+# Cultural sensitivity review agent
+@fast.agent(
+    "cultural_reviewer",
+    """Review all translated content for cultural sensitivity and appropriateness.
+    For each language version, evaluate:
+    - Cultural appropriateness
+    - Potential misunderstandings or sensitivities
+    - Effectiveness for the target culture
+    
+    Provide specific recommendations for any needed adjustments and save a review report.
+    """,
+    servers=["filesystem"],
+    request_params=RequestParams(temperature=0.2),
+)
+# Campaign optimization workflow
+@fast.evaluator_optimizer(
+    "campaign_optimizer",
+    generator="campaign_generator",
+    evaluator="cultural_reviewer",
+    max_refinements=2,
+    min_rating="EXCELLENT",
+)
+# Main workflow orchestration
+@fast.orchestrator(
+    "research_campaign_creator",
+    instruction="""
+    Create a complete multi-lingual social media campaign based on data analysis results.
+    The workflow will:
+    1. Analyze the provided data and extract key insights
+    2. Research cultural contexts for target languages
+    3. Generate appropriate social media content
+    4. Translate and culturally adapt the content
+    5. Review and optimize all materials
+    6. Save all campaign elements to files
+    """,
+    agents=[
+        "analysis_tool",
+        "context_researcher",
+        "campaign_optimizer",
+        "translate_campaign",
+    ],
+    model="sonnet",  # Using a more capable model for orchestration
+    request_params=RequestParams(maxTokens=8192),
+    plan_type="full",
+)
+async def main() -> None:
+    # Use the app's context manager
+    print(
+        "WARNING: This workflow will likely run for >10 minutes and consume a lot of tokens. Press Enter to accept the default prompt and proceed"
+    )
+
+    async with fast.run() as agent:
+        await agent.interactive(
+            "research_campaign_creator",
+            default_prompt="Analyze the CSV file in the current directory and create a comprehensive multi-lingual social media campaign based on the findings. Save all campaign elements as separate files.",
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/data-analysis/analysis.py

@@ -0,0 +1,68 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("Data Analysis (Roots)")
+
+
+# The sample data is under Database Contents License (DbCL) v1.0.
+# Available here : https://www.kaggle.com/datasets/pavansubhasht/ibm-hr-analytics-attrition-dataset
+
+
+@fast.agent(
+    name="data_analysis",
+    instruction="""
+You have access to a Python 3.12 interpreter and you can use this to analyse and process data. 
+Common analysis packages such as Pandas, Seaborn and Matplotlib are already installed. 
+You can add further packages if needed.
+Data files are accessible from the /mnt/data/ directory (this is the current working directory).
+Visualisations should be saved as .png files in the current working directory.
+
+{{serverInstructions}}
+
+""",
+    servers=["interpreter"],
+)
+# @fast.agent(name="another_test", instruction="", servers=["filesystem"])
+async def main() -> None:
+    # Use the app's context manager
+    async with fast.run() as agent:
+        await agent.interactive()
+        await agent.data_analysis(
+            "There is a csv file in the current directory. "
+            "Analyse the file, produce a detailed description of the data, and any patterns it contains.",
+        )
+        await agent.data_analysis(
+            "Consider the data, and how to usefully group it for presentation to a Human. Find insights, using the Python Interpreter as needed.\n"
+            "Use MatPlotLib to produce insightful visualisations. Save them as '.png' files in the current directory. Be sure to run the code and save the files.\n"
+            "Produce a summary with major insights to the data",
+        )
+        await agent()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+
+############################################################################################################
+# Example of evaluator/optimizer flow
+############################################################################################################
+# @fast.agent(
+#     "evaluator",
+#     """You are collaborating with a Data Analysis tool that has the capability to analyse data and produce visualisations.
+#     You must make sure that the tool has:
+#      - Considered the best way for a Human to interpret the data
+#      - Produced insightful visualasions.
+#      - Provided a high level summary report for the Human.
+#      - Has had its findings challenged, and justified
+#     """,
+#     request_params=RequestParams(maxTokens=8192),
+# )
+# @fast.evaluator_optimizer(
+#     "analysis_tool",
+#     generator="data_analysis",
+#     evaluator="evaluator",
+#     max_refinements=3,
+#     min_rating="EXCELLENT",
+# )

fast_agent/resources/examples/data-analysis/fastagent.config.yaml

@@ -0,0 +1,41 @@
+default_model: sonnet
+
+# on windows, adjust the mount point to be the full path e.g. x:/temp/data-analysis/mount-point:/mnt/data/
+
+mcp:
+  servers:
+    interpreter:
+      command: "docker"
+      args:
+        [
+          "run",
+          "-i",
+          "--rm",
+          "--pull=always",
+          "-v",
+          "./mount-point:/mnt/data/",
+          "ghcr.io/evalstate/mcp-py-repl:latest",
+        ]
+      roots:
+        - uri: "file://./mount-point/"
+          name: "test_data"
+          server_uri_alias: "file:///mnt/data/"
+    filesystem:
+      # On windows update the command and arguments to use `node` and the absolute path to the server.
+      # Use `npm i -g @modelcontextprotocol/server-filesystem` to install the server globally.
+      # Use `npm -g root` to find the global node_modules path.`
+      # command: "node"
+      # args: ["c:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js","."]
+      command: "npx"
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "./mount-point/"]
+    fetch:
+      command: "uvx"
+      args: ["mcp-server-fetch"]
+    brave:
+      # On windows replace the command and args line to use `node` and the absolute path to the server.
+      # Use `npm i -g @modelcontextprotocol/server-brave-search` to install the server globally.
+      # Use `npm -g root` to find the global node_modules path.`
+      # command: "node"
+      # args: ["c:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-brave-search/dist/index.js"]
+      command: "npx"
+      args: ["-y", "@modelcontextprotocol/server-brave-search"]