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

mcp_agent/mcp_server_registry.py

@@ -0,0 +1,275 @@
+"""
+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 contextlib import asynccontextmanager
+from datetime import timedelta
+from typing import Callable, Dict, AsyncGenerator
+
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from mcp import ClientSession
+from mcp.client.stdio import (
+    StdioServerParameters,
+    stdio_client,
+    get_default_environment,
+)
+from mcp.client.sse import sse_client
+
+from mcp_agent.config import (
+    get_settings,
+    MCPServerAuthSettings,
+    MCPServerSettings,
+    Settings,
+)
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.mcp_connection_manager import MCPConnectionManager
+
+logger = get_logger(__name__)
+
+InitHookCallable = Callable[[ClientSession | None, MCPServerAuthSettings | None], bool]
+"""
+A type alias for an initialization hook function that is invoked after MCP server initialization.
+
+Args:
+    session (ClientSession | None): The client session for the server connection.
+    auth (MCPServerAuthSettings | None): The authentication configuration for the server.
+
+Returns:
+    bool: Result of the post-init hook (false indicates failure).
+"""
+
+
+class ServerRegistry:
+    """
+    A registry for managing server configurations and initialization logic.
+
+    The `ServerRegistry` class is responsible for loading server configurations
+    from a YAML file, registering initialization hooks, initializing servers,
+    and executing post-initialization hooks dynamically.
+
+    Attributes:
+        config_path (str): Path to the YAML configuration file.
+        registry (Dict[str, MCPServerSettings]): Loaded server configurations.
+        init_hooks (Dict[str, InitHookCallable]): Registered initialization hooks.
+    """
+
+    def __init__(self, config: Settings | None = None, config_path: str | 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.
+        """
+        self.registry = (
+            self.load_registry_from_file(config_path)
+            if config is None
+            else config.mcp.servers
+        )
+        self.init_hooks: Dict[str, InitHookCallable] = {}
+        self.connection_manager = MCPConnectionManager(self)
+
+    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 = get_settings(config_path).mcp.servers or {}
+        return servers
+
+    @asynccontextmanager
+    async def start_server(
+        self,
+        server_name: str,
+        client_session_factory: Callable[
+            [MemoryObjectReceiveStream, MemoryObjectSendStream, timedelta | None],
+            ClientSession,
+        ] = ClientSession,
+    ) -> AsyncGenerator[ClientSession, None]:
+        """
+        Starts the server process based on its configuration. To initialize, call initialize_server
+
+        Args:
+            server_name (str): The name of the server to initialize.
+
+        Returns:
+            StdioServerParameters: The server parameters for stdio transport.
+
+        Raises:
+            ValueError: If the server is not found or has an unsupported transport.
+        """
+        if server_name not in self.registry:
+            raise ValueError(f"Server '{server_name}' not found in registry.")
+
+        config = self.registry[server_name]
+
+        read_timeout_seconds = (
+            timedelta(config.read_timeout_seconds)
+            if config.read_timeout_seconds
+            else None
+        )
+
+        if config.transport == "stdio":
+            if not config.command or not config.args:
+                raise ValueError(
+                    f"Command and args are required for stdio transport: {server_name}"
+                )
+
+            server_params = StdioServerParameters(
+                command=config.command,
+                args=config.args,
+                env={**get_default_environment(), **(config.env or {})},
+            )
+
+            async with stdio_client(server_params) as (read_stream, write_stream):
+                session = client_session_factory(
+                    read_stream,
+                    write_stream,
+                    read_timeout_seconds,
+                )
+                async with session:
+                    logger.info(
+                        f"{server_name}: Connected to server using stdio transport."
+                    )
+                    try:
+                        yield session
+                    finally:
+                        logger.debug(f"{server_name}: Closed session to server")
+
+        elif config.transport == "sse":
+            if not config.url:
+                raise ValueError(f"URL is required for SSE transport: {server_name}")
+
+            # Use sse_client to get the read and write streams
+            async with sse_client(config.url) as (read_stream, write_stream):
+                session = client_session_factory(
+                    read_stream,
+                    write_stream,
+                    read_timeout_seconds,
+                )
+                async with session:
+                    logger.info(
+                        f"{server_name}: Connected to server using SSE transport."
+                    )
+                    try:
+                        yield session
+                    finally:
+                        logger.debug(f"{server_name}: Closed session to server")
+
+        # Unsupported transport
+        else:
+            raise ValueError(f"Unsupported transport: {config.transport}")
+
+    @asynccontextmanager
+    async def initialize_server(
+        self,
+        server_name: str,
+        client_session_factory: Callable[
+            [MemoryObjectReceiveStream, MemoryObjectSendStream, timedelta | None],
+            ClientSession,
+        ] = ClientSession,
+        init_hook: InitHookCallable = None,
+    ) -> AsyncGenerator[ClientSession, None]:
+        """
+        Initialize a server based on its configuration.
+        After initialization, also calls any registered or provided initialization hook for the server.
+
+        Args:
+            server_name (str): The name of the server to initialize.
+            init_hook (InitHookCallable): Optional initialization hook function to call after initialization.
+
+        Returns:
+            StdioServerParameters: The server parameters for stdio transport.
+
+        Raises:
+            ValueError: If the server is not found or has an unsupported transport.
+        """
+
+        if server_name not in self.registry:
+            raise ValueError(f"Server '{server_name}' not found in registry.")
+
+        config = self.registry[server_name]
+
+        async with self.start_server(
+            server_name, client_session_factory=client_session_factory
+        ) as session:
+            try:
+                logger.info(f"{server_name}: Initializing server...")
+                await session.initialize()
+                logger.info(f"{server_name}: Initialized.")
+
+                intialization_callback = (
+                    init_hook
+                    if init_hook is not None
+                    else self.init_hooks.get(server_name)
+                )
+
+                if intialization_callback:
+                    logger.info(f"{server_name}: Executing init hook")
+                    intialization_callback(session, config.auth)
+
+                logger.info(f"{server_name}: Up and running!")
+                yield session
+            finally:
+                logger.info(f"{server_name}: Ending server session.")
+
+    def register_init_hook(self, server_name: str, hook: InitHookCallable) -> None:
+        """
+        Register an initialization hook for a specific server. This will get called
+        after the server is initialized.
+
+        Args:
+            server_name (str): The name of the server.
+            hook (callable): The initialization function to register.
+        """
+        if server_name not in self.registry:
+            raise ValueError(f"Server '{server_name}' not found in registry.")
+
+        self.init_hooks[server_name] = hook
+
+    def execute_init_hook(self, server_name: str, session=None) -> bool:
+        """
+        Execute the initialization hook for a specific server.
+
+        Args:
+            server_name (str): The name of the server.
+            session: The session object to pass to the initialization hook.
+        """
+        if server_name in self.init_hooks:
+            hook = self.init_hooks[server_name]
+            config = self.registry[server_name]
+            logger.info(f"Executing init hook for '{server_name}'")
+            return hook(session, config.auth)
+        else:
+            logger.info(f"No init hook registered for '{server_name}'")
+
+    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

mcp_agent/progress_display.py

@@ -0,0 +1,10 @@
+"""
+Centralized progress display configuration for MCP Agent.
+Provides a shared progress display instance for consistent progress handling.
+"""
+
+from mcp_agent.console import console
+from mcp_agent.logging.rich_progress import RichProgressDisplay
+
+# Main progress display instance - shared across the application
+progress_display = RichProgressDisplay(console)

mcp_agent/resources/examples/decorator/main.py

@@ -0,0 +1,26 @@
+"""
+Example MCP Agent application showing simplified agent access.
+"""
+
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+agent_app = FastAgent("Interactive Agent Example")
+
+
+# Define the agent
+@agent_app.agent(
+    instruction="A simple agent that helps with basic tasks. Request Human Input when needed.",
+    servers=["mcp_root"],
+    #    model="gpt-4o", model override here takes precedence
+)
+async def main():
+    # use the --model= command line switch to specify model
+    async with agent_app.run() as agent:
+        await agent("print the next number in the sequence")
+        await agent.prompt(default="STOP")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/decorator/optimizer.py

@@ -0,0 +1,78 @@
+"""
+Example showing how to use the evaluator-optimizer functionality with the decorator API.
+This demonstrates creating an optimizer and evaluator to iteratively improve content.
+"""
+
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+agent_app = FastAgent("Cover Letter Writer")
+agent_app.app._human_input_callback = None
+
+
+# Define optimizer agent
+@agent_app.agent(
+    name="optimizer",
+    instruction="""You are a career coach specializing in cover letter writing.
+    You are tasked with generating a compelling cover letter given the job posting,
+    candidate details, and company information. Tailor the response to the company and job requirements.
+    """,
+    servers=["fetch"],
+    model="gpt-4o-mini",  # Using a capable model for content generation
+)
+# Define evaluator agent
+@agent_app.agent(
+    name="evaluator",
+    instruction="""Evaluate the following response based on the criteria below:
+    1. Clarity: Is the language clear, concise, and grammatically correct?
+    2. Specificity: Does the response include relevant and concrete details tailored to the job description?
+    3. Relevance: Does the response align with the prompt and avoid unnecessary information?
+    4. Tone and Style: Is the tone professional and appropriate for the context?
+    5. Persuasiveness: Does the response effectively highlight the candidate's value?
+    6. Grammar and Mechanics: Are there any spelling or grammatical issues?
+    7. Feedback Alignment: Has the response addressed feedback from previous iterations?
+
+    For each criterion:
+    - Provide a rating (EXCELLENT, GOOD, FAIR, or POOR).
+    - Offer specific feedback or suggestions for improvement.
+
+    Summarize your evaluation as a structured response with:
+    - Overall quality rating.
+    - Specific feedback and areas for improvement.""",
+    servers=[],  # Evaluator doesn't need special server access
+    model="sonnet",  # Using a capable model for evaluation
+)
+# Define the evaluator-optimizer workflow
+@agent_app.evaluator_optimizer(
+    name="cover_letter_writer",
+    optimizer="optimizer",  # Reference to optimizer agent
+    evaluator="evaluator",  # Reference to evaluator agent
+    min_rating="EXCELLENT",  # Strive for excellence
+    max_refinements=3,  # Maximum iterations
+)
+async def main():
+    async with agent_app.run() as agent:
+        job_posting = (
+            "Software Engineer at LastMile AI. Responsibilities include developing AI systems, "
+            "collaborating with cross-functional teams, and enhancing scalability. Skills required: "
+            "Python, distributed systems, and machine learning."
+        )
+        candidate_details = (
+            "Alex Johnson, 3 years in machine learning, contributor to open-source AI projects, "
+            "proficient in Python and TensorFlow. Motivated by building scalable AI systems to solve real-world problems."
+        )
+        company_information = (
+            "Look up from the LastMile AI About page: https://lastmileai.dev/about"
+        )
+
+        # Send the task
+        await agent.cover_letter_writer.send(
+            f"Write a cover letter for the following job posting: {job_posting}\n\n"
+            f"Candidate Details: {candidate_details}\n\n"
+            f"Company information: {company_information}",
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/decorator/orchestrator.py

@@ -0,0 +1,68 @@
+"""
+Example showing how to use the orchestrator functionality with the decorator API.
+This demonstrates creating multiple agents and an orchestrator to coordinate them.
+"""
+
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+agent_app = FastAgent("Orchestrator Example")
+
+
+# Define worker agents
+@agent_app.agent(
+    name="finder",
+    instruction="""You are an agent with access to the filesystem, 
+            as well as the ability to fetch URLs. Your job is to identify 
+            the closest match to a user's request, make the appropriate tool calls, 
+            and return the URI and CONTENTS of the closest match.""",
+    servers=["fetch", "filesystem"],
+    model="gpt-4o-mini",
+)
+@agent_app.agent(
+    name="writer",
+    instruction="""You are an agent that can write to the filesystem.
+            You are tasked with taking the user's input, addressing it, and 
+            writing the result to disk in the appropriate location.""",
+    servers=["filesystem"],
+    model="gpt-4o",
+)
+@agent_app.agent(
+    name="proofreader",
+    instruction=""""Review the short story for grammar, spelling, and punctuation errors.
+            Identify any awkward phrasing or structural issues that could improve clarity. 
+            Provide detailed feedback on corrections.""",
+    servers=["fetch"],
+    model="gpt-4o",
+)
+# Define the orchestrator to coordinate the other agents
+@agent_app.orchestrator(
+    name="document_processor",
+    instruction="""Load the student's short story from short_story.md, 
+    and generate a report with feedback across proofreading, 
+    factuality/logical consistency and style adherence. Use the style rules from 
+    https://apastyle.apa.org/learn/quick-guide-on-formatting and 
+    https://apastyle.apa.org/learn/quick-guide-on-references.
+    Write the graded report to graded_report.md in the same directory as short_story.md""",
+    agents=["finder", "writer", "proofreader"],
+    model="sonnet",  # Orchestrators typically need more capable models
+)
+async def main():
+    async with agent_app.run() as agent:
+        # The orchestrator can be used just like any other agent
+        task = (
+            """Load the student's short story from short_story.md, 
+        and generate a report with feedback across proofreading, 
+        factuality/logical consistency and style adherence. Use the style rules from 
+        https://apastyle.apa.org/learn/quick-guide-on-formatting and 
+        https://apastyle.apa.org/learn/quick-guide-on-references.
+        Write the graded report to graded_report.md in the same directory as short_story.md""",
+        )
+
+        # Send the task
+        await agent.send("document_processor", task)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/decorator/parallel.py

@@ -0,0 +1,81 @@
+"""
+Example MCP Agent application showing simplified agent access.
+"""
+
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+app = FastAgent(
+    "Parallel Workflow Example",
+    # config={
+    #     "human_input_handler": None  # Disable human input handling
+    # },
+)
+app.app._human_input_callback = None
+SHORT_STORY = """
+The Battle of Glimmerwood
+
+In the heart of Glimmerwood, a mystical forest knowed for its radiant trees, a small village thrived. 
+The villagers, who were live peacefully, shared their home with the forest's magical creatures, 
+especially the Glimmerfoxes whose fur shimmer like moonlight.
+
+One fateful evening, the peace was shaterred when the infamous Dark Marauders attack. 
+Lead by the cunning Captain Thorn, the bandits aim to steal the precious Glimmerstones which was believed to grant immortality.
+
+Amidst the choas, a young girl named Elara stood her ground, she rallied the villagers and devised a clever plan.
+Using the forests natural defenses they lured the marauders into a trap. 
+As the bandits aproached the village square, a herd of Glimmerfoxes emerged, blinding them with their dazzling light, 
+the villagers seized the opportunity to captured the invaders.
+
+Elara's bravery was celebrated and she was hailed as the "Guardian of Glimmerwood". 
+The Glimmerstones were secured in a hidden grove protected by an ancient spell.
+
+However, not all was as it seemed. The Glimmerstones true power was never confirm, 
+and whispers of a hidden agenda linger among the villagers.
+"""
+
+
+@app.agent(
+    name="proofreader",
+    instruction=""""Review the short story for grammar, spelling, and punctuation errors.
+    Identify any awkward phrasing or structural issues that could improve clarity. 
+    Provide detailed feedback on corrections.""",
+)
+@app.agent(
+    name="fact_checker",
+    model="gpt-4o",
+    instruction="""Verify the factual consistency within the story. Identify any contradictions,
+    logical inconsistencies, or inaccuracies in the plot, character actions, or setting. 
+    Highlight potential issues with reasoning or coherence.""",
+)
+@app.agent(
+    name="style_enforcer",
+    model="sonnet",
+    instruction="""Analyze the story for adherence to style guidelines.
+    Evaluate the narrative flow, clarity of expression, and tone. Suggest improvements to 
+    enhance storytelling, readability, and engagement.""",
+)
+@app.agent(
+    name="grader",
+    model="o3-mini.high",
+    instruction="""Compile the feedback from the Proofreader, Fact Checker, and Style Enforcer
+    into a structured report. Summarize key issues and categorize them by type. 
+    Provide actionable recommendations for improving the story, 
+    and give an overall grade based on the feedback.""",
+)
+@app.parallel(
+    fan_out=["proofreader", "fact_checker", "style_enforcer"],
+    fan_in="grader",
+    name="parallel",
+)
+async def main():
+    # Use the app's context manager
+    async with app.run() as agent:
+        await agent.send("parallel", f"student short story submission: {SHORT_STORY}")
+        # follow-on prompt to task agent
+        # await agent.prompt("style_enforcer", default="STOP")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/decorator/router.py

@@ -0,0 +1,56 @@
+"""
+Example MCP Agent application showing router workflow with decorator syntax.
+Demonstrates router's ability to either:
+1. Use tools directly to handle requests
+2. Delegate requests to specialized agents
+"""
+
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+agent_app = FastAgent(
+    "Router Workflow Example",
+)
+agent_app.app._human_input_callback = None
+
+# Sample requests demonstrating direct tool use vs agent delegation
+SAMPLE_REQUESTS = [
+    "Download and summarize https://llmindset.co.uk/posts/2024/12/mcp-build-notes/",  # Router handles directly with fetch
+    "Analyze the quality of the Python codebase in the current working directory",  # Delegated to code expert
+    "What are the key principles of effective beekeeping?",  # Delegated to general assistant
+]
+
+
+@agent_app.agent(
+    name="fetcher",
+    instruction="""You are an agent, with a tool enabling you to fetch URLs.""",
+    servers=["fetch"],
+    model="haiku",
+)
+@agent_app.agent(
+    name="code_expert",
+    instruction="""You are an expert in code analysis and software engineering.
+    When asked about code, architecture, or development practices,
+    you provide thorough and practical insights.""",
+    servers=["filesystem"],
+    model="gpt-4o",
+)
+@agent_app.agent(
+    name="general_assistant",
+    instruction="""You are a knowledgeable assistant that provides clear,
+    well-reasoned responses about general topics, concepts, and principles.""",
+)
+@agent_app.router(
+    name="llm_router",
+    model="sonnet",
+    agents=["code_expert", "general_assistant", "fetcher"],
+)
+async def main():
+    async with agent_app.run() as agent:
+        for request in SAMPLE_REQUESTS:
+            await agent.send("llm_router", request)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/decorator/tiny.py

@@ -0,0 +1,22 @@
+"""
+Example MCP Agent application showing simplified agent access.
+"""
+
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+agent_app = FastAgent("Interactive Agent Example")
+# agent_app.app._human_input_callback = None
+
+
+# Define the agent
+@agent_app.agent()
+async def main():
+    # use the --model= command line switch to specify model
+    async with agent_app.run() as agent:
+        await agent()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/mcp_researcher/main-evalopt.py

@@ -0,0 +1,53 @@
+import asyncio
+
+from mcp_agent.core.fastagent import FastAgent
+
+agents = FastAgent(name="Researcher")
+
+
+@agents.agent(
+    name="Researcher",
+    instruction="""
+You are a research assistant, with access to internet search (via Brave),
+website fetch, a python interpreter (you can install packages with uv) and a filesystem.
+Use the current working directory to save and create files with both the Interpreter and Filesystem tools.
+The interpreter has numpy, pandas, matplotlib and seaborn already installed.
+
+You must always provide a summary of the specific sources you have used in your research.
+    """,
+    servers=["brave", "interpreter", "filesystem", "fetch"],
+)
+@agents.agent(
+    name="Evaluator",
+    model="sonnet",
+    instruction="""
+Evaluate the response from the researcher based on the criteria:
+ - Sources cited. Has the researcher provided a summary of the specific sources used in the research?
+ - Validity. Has the researcher cross-checked and validated data and assumptions.
+ - Alignment. Has the researher acted and addressed feedback from any previous assessments?
+ 
+For each criterion:
+- Provide a rating (EXCELLENT, GOOD, FAIR, or POOR).
+- Offer specific feedback or suggestions for improvement.
+
+Summarize your evaluation as a structured response with:
+- Overall quality rating.
+- Specific feedback and areas for improvement.""",
+)
+@agents.evaluator_optimizer(
+    optimizer="Researcher",
+    evaluator="Evaluator",
+    max_refinements=5,
+    min_rating="EXCELLENT",
+    name="Researcher_Evaluator",
+)
+async def main():
+    async with agents.run() as agent:
+        await agent.prompt("Researcher_Evaluator")
+
+        print("Ask follow up quesions to the Researcher?")
+        await agent.prompt("Researcher", default="STOP")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())