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

mcp_agent/mcp/resource_utils.py

@@ -1,13 +1,15 @@
 import base64
 from pathlib import Path
 from typing import List, Optional, Tuple
+
 from mcp.types import (
-    EmbeddedResource,
-    TextResourceContents,
     BlobResourceContents,
+    EmbeddedResource,
     ImageContent,
+    TextResourceContents,
 )
 from pydantic import AnyUrl
+
 import mcp_agent.mcp.mime_utils as mime_utils
 
 HTTP_TIMEOUT = 10  # Default timeout for HTTP requests
@@ -25,9 +27,7 @@ def find_resource_file(resource_path: str, prompt_files: List[Path]) -> Optional
     return None
 
 
-def load_resource_content(
-    resource_path: str, prompt_files: List[Path]
-) -> ResourceContent:
+def load_resource_content(resource_path: str, prompt_files: List[Path]) -> ResourceContent:
     """
     Load a resource's content and determine its mime type
 
@@ -71,9 +71,6 @@ def create_resource_uri(path: str) -> str:
     return f"resource://fast-agent/{Path(path).name}"
 
 
-# Add this to your resource_utils.py module
-
-
 def create_resource_reference(uri: str, mime_type: str) -> "EmbeddedResource":
     """
     Create a reference to a resource without embedding its content directly.
@@ -101,9 +98,7 @@ def create_resource_reference(uri: str, mime_type: str) -> "EmbeddedResource":
     return EmbeddedResource(type="resource", resource=resource_contents)
 
 
-def create_embedded_resource(
-    resource_path: str, content: str, mime_type: str, is_binary: bool = False
-) -> EmbeddedResource:
+def create_embedded_resource(resource_path: str, content: str, mime_type: str, is_binary: bool = False) -> EmbeddedResource:
     """Create an embedded resource content object"""
     # Format a valid resource URI string
     resource_uri_str = create_resource_uri(resource_path)
@@ -141,9 +136,7 @@ def create_image_content(data: str, mime_type: str) -> ImageContent:
     )
 
 
-def create_blob_resource(
-    resource_path: str, content: str, mime_type: str
-) -> EmbeddedResource:
+def create_blob_resource(resource_path: str, content: str, mime_type: str) -> EmbeddedResource:
     """Create an embedded resource for binary data"""
     return EmbeddedResource(
         type="resource",
@@ -155,9 +148,7 @@ def create_blob_resource(
     )
 
 
-def create_text_resource(
-    resource_path: str, content: str, mime_type: str
-) -> EmbeddedResource:
+def create_text_resource(resource_path: str, content: str, mime_type: str) -> EmbeddedResource:
     """Create an embedded resource for text data"""
     return EmbeddedResource(
         type="resource",

mcp_agent/mcp/sampling.py

@@ -1,27 +1,22 @@
 """
-Module for handling MCP Sampling functionality without causing circular imports.
-This module is carefully designed to avoid circular imports in the agent system.
+This simplified implementation directly converts between MCP types and PromptMessageMultipart.
 """
 
 from mcp import ClientSession
 from mcp.types import (
     CreateMessageRequestParams,
     CreateMessageResult,
-    TextContent,
 )
 
+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.mcp.prompt_message_multipart import PromptMessageMultipart
-
-# Protocol is sufficient to describe the interface - no need for TYPE_CHECKING imports
+from mcp_agent.workflows.llm.sampling_converter import SamplingConverter
 
 logger = get_logger(__name__)
 
 
-def create_sampling_llm(
-    mcp_ctx: ClientSession, model_string: str
-) -> AugmentedLLMProtocol:
+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.
@@ -33,11 +28,9 @@ def create_sampling_llm(
     Returns:
         An initialized LLM instance ready to use
     """
+    from mcp_agent.agents.agent import Agent
     from mcp_agent.workflows.llm.model_factory import ModelFactory
-    from mcp_agent.agents.agent import Agent, AgentConfig
 
-    # Get application context from global state if available
-    # We don't try to extract it from mcp_ctx as they're different contexts
     app_context = None
     try:
         from mcp_agent.context import get_current_context
@@ -46,20 +39,10 @@ def create_sampling_llm(
     except Exception:
         logger.warning("App context not available for sampling call")
 
-    # Create a minimal agent configuration
-    agent_config = AgentConfig(
-        name="sampling_agent",
-        instruction="You are a sampling agent.",
-        servers=[],  # No servers needed
-    )
-
-    # Create agent with our application context (not the MCP context)
-    # Set connection_persistence=False to avoid server connections
     agent = Agent(
-        config=agent_config,
+        config=sampling_agent_config(params),
         context=app_context,
-        server_names=[],  # Make sure no server connections are attempted
-        connection_persistence=False,  # Avoid server connection management
+        connection_persistence=False,
     )
 
     # Create the LLM using the factory
@@ -72,13 +55,22 @@ def create_sampling_llm(
     return llm
 
 
-async def sample(
-    mcp_ctx: ClientSession, params: CreateMessageRequestParams
-) -> CreateMessageResult:
+async def sample(mcp_ctx: ClientSession, params: CreateMessageRequestParams) -> CreateMessageResult:
     """
-    Handle sampling requests from the MCP protocol.
-    This function extracts the model from the server config and
-    returns a simple response using the specified model.
+    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:
@@ -95,39 +87,45 @@ async def sample(
         if model is None:
             raise ValueError("No model configured")
 
-        # Create an LLM instance using our utility function
-        llm = create_sampling_llm(mcp_ctx, model)
-
-        # Get user message from the request params
-        user_message = params.messages[0].content.text
-
-        # Create a multipart prompt message with the user's input
-        prompt = PromptMessageMultipart(
-            role="user", content=[TextContent(type="text", text=user_message)]
-        )
-
-        try:
-            # Use the LLM to generate a response
-            logger.info(f"Processing input: {user_message[:50]}...")
-            llm_response = await llm.generate_prompt(prompt, None)
-            logger.info(f"Generated response: {llm_response[:50]}...")
-        except Exception as e:
-            # If there's an error in LLM processing, fall back to echo
-            logger.error(f"Error generating response: {str(e)}")
-            llm_response = f"Echo response: {user_message}"
-
-        # Return the LLM-generated response
-        return CreateMessageResult(
-            role="assistant",
-            content=TextContent(type="text", text=llm_response),
-            model=model,
-            stopReason="endTurn",
-        )
+        # 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 CreateMessageResult(
-            role="assistant",
-            content=TextContent(type="text", text=f"Error in sampling: {str(e)}"),
-            model=model or "unknown",
-            stopReason="error",
-        )
+        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

@@ -2,14 +2,19 @@
 Custom implementation of stdio_client that handles stderr through rich console.
 """
 
-from contextlib import asynccontextmanager
 import subprocess
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
 import anyio
+import mcp.types as types
 from anyio.streams.text import TextReceiveStream
 from mcp.client.stdio import StdioServerParameters, get_default_environment
-import mcp.types as types
+
 from mcp_agent.logging.logger import get_logger
-from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+
+if TYPE_CHECKING:
+    from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 
 logger = get_logger(__name__)
 
@@ -45,11 +50,9 @@ async def stdio_client_with_rich_stderr(server: StdioServerParameters):
 
     if process.returncode is not None:
         logger.debug(f"return code (early){process.returncode}")
-        raise RuntimeError(
-            f"Process terminated immediately with code {process.returncode}"
-        )
+        raise RuntimeError(f"Process terminated immediately with code {process.returncode}")
 
-    async def stdout_reader():
+    async def stdout_reader() -> None:
         assert process.stdout, "Opened process is missing stdout"
         try:
             async with read_stream_writer:
@@ -89,7 +92,7 @@ async def stdio_client_with_rich_stderr(server: StdioServerParameters):
     #     except anyio.ClosedResourceError:
     #         await anyio.lowlevel.checkpoint()
 
-    async def stdin_writer():
+    async def stdin_writer() -> None:
         assert process.stdin, "Opened process is missing stdin"
         try:
             async with write_stream_reader:

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/mcp_server/agent_server.py

@@ -1,10 +1,10 @@
 # src/mcp_agent/mcp_server/agent_server.py
 
+from mcp.server.fastmcp import Context as MCPContext
 from mcp.server.fastmcp import FastMCP
 
 # Remove circular import
 from mcp_agent.core.agent_app import AgentApp
-from mcp.server.fastmcp import Context as MCPContext
 
 
 class AgentMCPServer:
@@ -15,21 +15,20 @@ class AgentMCPServer:
         agent_app: AgentApp,
         server_name: str = "FastAgent-MCP-Server",
         server_description: str = None,
-    ):
+    ) -> None:
         self.agent_app = agent_app
         self.mcp_server = FastMCP(
             name=server_name,
-            instructions=server_description
-            or f"This server provides access to {len(agent_app.agents)} agents",
+            instructions=server_description or f"This server provides access to {len(agent_app.agents)} agents",
         )
         self.setup_tools()
 
-    def setup_tools(self):
+    def setup_tools(self) -> None:
         """Register all agents as MCP tools."""
         for agent_name, agent_proxy in self.agent_app._agents.items():
             self.register_agent_tools(agent_name, agent_proxy)
 
-    def register_agent_tools(self, agent_name: str, agent_proxy):
+    def register_agent_tools(self, agent_name: str, agent_proxy) -> None:
         """Register tools for a specific agent."""
 
         # Basic send message tool
@@ -42,9 +41,7 @@ class AgentMCPServer:
 
             # Get the agent's context
             agent_context = None
-            if hasattr(agent_proxy, "_agent") and hasattr(
-                agent_proxy._agent, "context"
-            ):
+            if hasattr(agent_proxy, "_agent") and hasattr(agent_proxy._agent, "context"):
                 agent_context = agent_proxy._agent.context
 
             # Define the function to execute
@@ -57,7 +54,7 @@ class AgentMCPServer:
             else:
                 return await execute_send()
 
-    def run(self, transport: str = "sse", host: str = "0.0.0.0", port: int = 8000):
+    def run(self, transport: str = "sse", host: str = "0.0.0.0", port: int = 8000) -> None:
         """Run the MCP server."""
         if transport == "sse":
             # For running as a web server
@@ -66,9 +63,7 @@ class AgentMCPServer:
 
         self.mcp_server.run(transport=transport)
 
-    async def run_async(
-        self, transport: str = "sse", host: str = "0.0.0.0", port: int = 8000
-    ):
+    async def run_async(self, transport: str = "sse", host: str = "0.0.0.0", port: int = 8000) -> None:
         """Run the MCP server asynchronously."""
         if transport == "sse":
             self.mcp_server.settings.host = host
@@ -77,9 +72,7 @@ class AgentMCPServer:
         else:  # stdio
             await self.mcp_server.run_stdio_async()
 
-    async def with_bridged_context(
-        self, agent_context, mcp_context, func, *args, **kwargs
-    ):
+    async def with_bridged_context(self, agent_context, mcp_context, func, *args, **kwargs):
         """
         Execute a function with bridged context between MCP and agent
 
@@ -98,7 +91,7 @@ class AgentMCPServer:
         agent_context.mcp_context = mcp_context
 
         # Create bridged progress reporter
-        async def bridged_progress(progress, total=None):
+        async def bridged_progress(progress, total=None) -> None:
             if mcp_context:
                 await mcp_context.report_progress(progress, total)
             if original_progress_reporter:

mcp_agent/mcp_server_registry.py

@@ -9,25 +9,25 @@ server initialization.
 
 from contextlib import asynccontextmanager
 from datetime import timedelta
-from typing import Callable, Dict, AsyncGenerator
+from typing import AsyncGenerator, Callable, Dict
 
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from mcp import ClientSession
+from mcp.client.sse import sse_client
 from mcp.client.stdio import (
     StdioServerParameters,
     get_default_environment,
 )
-from mcp_agent.mcp.stdio import stdio_client_with_rich_stderr
-from mcp.client.sse import sse_client
 
 from mcp_agent.config import (
-    get_settings,
     MCPServerAuthSettings,
     MCPServerSettings,
     Settings,
+    get_settings,
 )
 from mcp_agent.logging.logger import get_logger
 from mcp_agent.mcp.mcp_connection_manager import MCPConnectionManager
+from mcp_agent.mcp.stdio import stdio_client_with_rich_stderr
 
 logger = get_logger(__name__)
 
@@ -58,7 +58,7 @@ class ServerRegistry:
         init_hooks (Dict[str, InitHookCallable]): Registered initialization hooks.
     """
 
-    def __init__(self, config: Settings | None = None, config_path: str | None = None):
+    def __init__(self, config: Settings | None = None, config_path: str | None = None) -> None:
         """
         Initialize the ServerRegistry with a configuration file.
 
@@ -66,17 +66,11 @@ class ServerRegistry:
             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.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]:
+    def load_registry_from_file(self, config_path: str | None = None) -> Dict[str, MCPServerSettings]:
         """
         Load the YAML configuration file and validate it.
 
@@ -116,17 +110,11 @@ class ServerRegistry:
 
         config = self.registry[server_name]
 
-        read_timeout_seconds = (
-            timedelta(config.read_timeout_seconds)
-            if config.read_timeout_seconds
-            else None
-        )
+        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}"
-                )
+                raise ValueError(f"Command and args are required for stdio transport: {server_name}")
 
             server_params = StdioServerParameters(
                 command=config.command,
@@ -144,9 +132,7 @@ class ServerRegistry:
                     read_timeout_seconds,
                 )
                 async with session:
-                    logger.info(
-                        f"{server_name}: Connected to server using stdio transport."
-                    )
+                    logger.info(f"{server_name}: Connected to server using stdio transport.")
                     try:
                         yield session
                     finally:
@@ -164,9 +150,7 @@ class ServerRegistry:
                     read_timeout_seconds,
                 )
                 async with session:
-                    logger.info(
-                        f"{server_name}: Connected to server using SSE transport."
-                    )
+                    logger.info(f"{server_name}: Connected to server using SSE transport.")
                     try:
                         yield session
                     finally:
@@ -206,19 +190,13 @@ class ServerRegistry:
 
         config = self.registry[server_name]
 
-        async with self.start_server(
-            server_name, client_session_factory=client_session_factory
-        ) as session:
+        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)
-                )
+                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")

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

@@ -172,7 +172,7 @@ Extract key insights that would be compelling for a social media campaign.
     request_params=RequestParams(maxTokens=8192),
     plan_type="full",
 )
-async def main():
+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"

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

@@ -23,7 +23,7 @@ Visualisations should be saved as .png files in the current working directory.
     servers=["interpreter"],
     request_params=RequestParams(maxTokens=8192),
 )
-async def main():
+async def main() -> None:
     # Use the app's context manager
     async with fast.run() as agent:
         await agent(

mcp_agent/resources/examples/data-analysis/slides.py

@@ -0,0 +1,110 @@
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from mcp_agent.core.fastagent import FastAgent
+from mcp_agent.mcp.prompts.prompt_load import load_prompt_multipart
+from mcp_agent.workflows.llm.augmented_llm import RequestParams
+
+if TYPE_CHECKING:
+    from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+
+# 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
+
+# The CSS files are distributed under the MIT License from the excellent
+# marpstyle project : https://github.com/cunhapaulo/marpstyle
+
+
+@fast.agent(
+    name="slides",
+    servers=["filesystem"],
+    instruction="""
+You produce compelling slide decks for impactful presentations. You usually try and keep the pack to between
+8-12 slides, with key insights at the start, backed up with data, diagrams and analysis as available. You 
+are able to help direct colour, style and and questions for enhancing the presentation. Produced charts and
+visualisations will be in the ./mount-point/ directory. You output MARP markdown files.
+""",
+    request_params=RequestParams(maxTokens=8192),
+)
+@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.
+""",
+    servers=["interpreter"],
+    request_params=RequestParams(maxTokens=8192),
+)
+@fast.orchestrator(
+    name="orchestrator",
+    plan_type="iterative",
+    agents=["slides", "data_analysis"],
+)
+async def main() -> None:
+    # Use the app's context manager
+    async with fast.run() as agent:
+        prompts: list[PromptMessageMultipart] = load_prompt_multipart(Path("slides.md"))
+        await agent.slides.apply_prompt_messages(prompts)
+
+        await agent.orchestrator.send(
+            "Produce a compelling presentation for the CSV data file in the /mnt/data/ directory."
+            "The slides agent will produce a presentation, make sure to consult it first for "
+            "colour scheme and formatting guidance. Make sure that any 'call-outs' have a distinct"
+            "background to ensure they stand out."
+            "Make sure the presentation is impactful, concise and visualises key insights in to the data"
+            " in a compelling way."
+            "The presentation is by the 'llmindset team' and produced in 'march 2025'."
+            "Produce it step-by-step; long responses without checking in are likely to exceed"
+            "maximum output token limits."
+        )
+        # colours: str = await agent.slides.send("Tell the Data Analysis agent what colour schemes and chart sizes you prefer for the presentation")
+
+        # analysis: str = await agent.data_analysis.send(
+        #     "Examine the CSV file in /mnt/data, produce a detailed analysis of the data,"
+        #     "and any patterns it contains. Visualise some of the key points, saving .png files to"
+        #     "your current workig folder (/mnt/data). Respond with a summary of your findings, and a list"
+        #     "of visualiations and their filenames ready to incorporate in to a slide deck. The presentation agent has"
+        #     f"specified the following style guidelines for generated charts:\n {colours}"
+        # )
+        # await agent.slides.send(
+        #     "Produce a MARP Presentation for the this analysis. You will find the visualisations in "
+        #     f"in the ./mount-point/ folder. The analysis follows....\n{analysis}"
+        # )
+
+        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",
+# )

mcp_agent/resources/examples/internal/agent.py

@@ -1,4 +1,5 @@
 import asyncio
+
 from mcp_agent.core.fastagent import FastAgent
 
 # Create the application
@@ -7,7 +8,7 @@ fast = FastAgent("FastAgent Example")
 
 # Define the agent
 @fast.agent(servers=["fetch", "mcp_hfspace"])
-async def main():
+async def main() -> None:
     # use the --model command line switch or agent arguments to change model
     async with fast.run() as agent:
         await agent.prompt()

mcp_agent/resources/examples/internal/job.py

@@ -5,6 +5,7 @@ PMO Job Description Generator Agent
 """
 
 import asyncio
+
 from mcp_agent.core.fastagent import FastAgent
 
 # Create the application
@@ -57,7 +58,7 @@ fast = FastAgent("PMO Job Description Generator")
     min_rating="EXCELLENT",
     max_refinements=2,
 )
-async def main():
+async def main() -> None:
     async with fast.run() as agent:
         roles = [
             "PMO Director",