fast-agent-mcp 0.2.36__py3-none-any.whl → 0.2.37__py3-none-any.whl

mcp_agent/mcp/mcp_aggregator.py

@@ -217,19 +217,30 @@ class MCPAggregator(ContextDependent):
 
                 # Create a wrapper to capture the parameters for the client session
                 def session_factory(read_stream, write_stream, read_timeout, **kwargs):
-                    # Get agent's model if this aggregator is part of an agent
-                    agent_model = None
-                    if hasattr(self, 'config') and self.config and hasattr(self.config, 'model'):
+                    # Get agent's model and name if this aggregator is part of an agent
+                    agent_model: str | None = None
+                    agent_name: str | None = None
+                    elicitation_handler = None
+
+                    # Check if this aggregator is part of an Agent (which has config)
+                    # Import here to avoid circular dependency
+                    from mcp_agent.agents.base_agent import BaseAgent
+
+                    if isinstance(self, BaseAgent):
                         agent_model = self.config.model
-                    
+                        agent_name = self.config.name
+                        elicitation_handler = self.config.elicitation_handler
+
                     return MCPAgentClientSession(
                         read_stream,
                         write_stream,
                         read_timeout,
                         server_name=server_name,
                         agent_model=agent_model,
+                        agent_name=agent_name,
+                        elicitation_handler=elicitation_handler,
                         tool_list_changed_callback=self._handle_tool_list_changed,
-                        **kwargs  # Pass through any additional kwargs like server_config
+                        **kwargs,  # Pass through any additional kwargs like server_config
                     )
 
                 await self._persistent_connection_manager.get_server(
@@ -278,19 +289,27 @@ class MCPAggregator(ContextDependent):
             else:
                 # Create a factory function for the client session
                 def create_session(read_stream, write_stream, read_timeout, **kwargs):
-                    # Get agent's model if this aggregator is part of an agent
-                    agent_model = None
-                    if hasattr(self, 'config') and self.config and hasattr(self.config, 'model'):
+                    # Get agent's model and name if this aggregator is part of an agent
+                    agent_model: str | None = None
+                    agent_name: str | None = None
+
+                    # Check if this aggregator is part of an Agent (which has config)
+                    # Import here to avoid circular dependency
+                    from mcp_agent.agents.base_agent import BaseAgent
+
+                    if isinstance(self, BaseAgent):
                         agent_model = self.config.model
-                    
+                        agent_name = self.config.name
+
                     return MCPAgentClientSession(
                         read_stream,
                         write_stream,
                         read_timeout,
                         server_name=server_name,
                         agent_model=agent_model,
+                        agent_name=agent_name,
                         tool_list_changed_callback=self._handle_tool_list_changed,
-                        **kwargs  # Pass through any additional kwargs like server_config
+                        **kwargs,  # Pass through any additional kwargs like server_config
                     )
 
                 async with gen_client(
@@ -812,7 +831,9 @@ class MCPAggregator(ContextDependent):
             messages=[],
         )
 
-    async def list_prompts(self, server_name: str | None = None, agent_name: str | None = None) -> Mapping[str, List[Prompt]]:
+    async def list_prompts(
+        self, server_name: str | None = None, agent_name: str | None = None
+    ) -> Mapping[str, List[Prompt]]:
         """
         List available prompts from one or all servers.
 
@@ -940,11 +961,23 @@ class MCPAggregator(ContextDependent):
                 if self.connection_persistence:
                     # Create a factory function that will include our parameters
                     def create_session(read_stream, write_stream, read_timeout):
+                        # Get agent name if available
+                        agent_name: str | None = None
+
+                        # Import here to avoid circular dependency
+                        from mcp_agent.agents.base_agent import BaseAgent
+
+                        if isinstance(self, BaseAgent):
+                            agent_name = self.config.name
+                            elicitation_handler = self.config.elicitation_handler
+
                         return MCPAgentClientSession(
                             read_stream,
                             write_stream,
                             read_timeout,
                             server_name=server_name,
+                            agent_name=agent_name,
+                            elicitation_handler=elicitation_handler,
                             tool_list_changed_callback=self._handle_tool_list_changed,
                         )
 
@@ -956,11 +989,23 @@ class MCPAggregator(ContextDependent):
                 else:
                     # Create a factory function for the client session
                     def create_session(read_stream, write_stream, read_timeout):
+                        # Get agent name if available
+                        agent_name: str | None = None
+
+                        # Import here to avoid circular dependency
+                        from mcp_agent.agents.base_agent import BaseAgent
+
+                        if isinstance(self, BaseAgent):
+                            agent_name = self.config.name
+                            elicitation_handler = self.config.elicitation_handler
+
                         return MCPAgentClientSession(
                             read_stream,
                             write_stream,
                             read_timeout,
                             server_name=server_name,
+                            agent_name=agent_name,
+                            elicitation_handler=elicitation_handler,
                             tool_list_changed_callback=self._handle_tool_list_changed,
                         )
 

mcp_agent/mcp/mcp_connection_manager.py

@@ -166,10 +166,7 @@ class ServerConnection:
         )
 
         session = self._client_session_factory(
-            read_stream, 
-            send_stream, 
-            read_timeout,
-            server_config=self.server_config
+            read_stream, send_stream, read_timeout, server_config=self.server_config
         )
 
         self.session = session
@@ -220,19 +217,34 @@ async def _server_lifecycle_task(server_conn: ServerConnection) -> None:
 
         if "ExceptionGroup" in type(exc).__name__ and hasattr(exc, "exceptions"):
             # Handle ExceptionGroup better by extracting the actual errors
-            error_messages = []
-            for subexc in exc.exceptions:
-                if isinstance(subexc, HTTPStatusError):
-                    # Special handling for HTTP errors to make them more user-friendly
-                    error_messages.append(
-                        f"HTTP Error: {subexc.response.status_code} {subexc.response.reason_phrase} for URL: {subexc.request.url}"
-                    )
-                else:
-                    error_messages.append(f"Error: {type(subexc).__name__}: {subexc}")
-                if hasattr(subexc, "__cause__") and subexc.__cause__:
-                    error_messages.append(
-                        f"Caused by: {type(subexc.__cause__).__name__}: {subexc.__cause__}"
-                    )
+            def extract_errors(exception_group):
+                """Recursively extract meaningful errors from ExceptionGroups"""
+                messages = []
+                for subexc in exception_group.exceptions:
+                    if "ExceptionGroup" in type(subexc).__name__ and hasattr(subexc, "exceptions"):
+                        # Recursively handle nested ExceptionGroups
+                        messages.extend(extract_errors(subexc))
+                    elif isinstance(subexc, HTTPStatusError):
+                        # Special handling for HTTP errors to make them more user-friendly
+                        messages.append(
+                            f"HTTP Error: {subexc.response.status_code} {subexc.response.reason_phrase} for URL: {subexc.request.url}"
+                        )
+                    else:
+                        # Show the exception type and message, plus the root cause if available
+                        error_msg = f"{type(subexc).__name__}: {subexc}"
+                        messages.append(error_msg)
+
+                        # If there's a root cause, show that too as it's often the most informative
+                        if hasattr(subexc, "__cause__") and subexc.__cause__:
+                            messages.append(
+                                f"Caused by: {type(subexc.__cause__).__name__}: {subexc.__cause__}"
+                            )
+                return messages
+
+            error_messages = extract_errors(exc)
+            # If we didn't extract any meaningful errors, fall back to the original exception
+            if not error_messages:
+                error_messages = [f"{type(exc).__name__}: {exc}"]
             server_conn._error_message = error_messages
         else:
             # For regular exceptions, keep the traceback but format it more cleanly
@@ -309,7 +321,7 @@ class MCPConnectionManager(ContextDependent):
             self._tg = self._task_group
             logger.info(f"Auto-created task group for server: {server_name}")
 
-        config = self.server_registry.registry.get(server_name)
+        config = self.server_registry.get_server_config(server_name)
         if not config:
             raise ValueError(f"Server '{server_name}' not found in registry.")
 

mcp_agent/mcp_server/agent_server.py

@@ -65,6 +65,8 @@ class AgentMCPServer:
         @self.mcp_server.tool(
             name=f"{agent_name}_send",
             description=f"Send a message to the {agent_name} agent",
+            structured_output=False,
+            # MCP 1.10.1 turns every tool in to a structured output
         )
         async def send_message(message: str, ctx: MCPContext) -> str:
             """Send a message to the agent and return its response."""

mcp_agent/mcp_server_registry.py

@@ -73,7 +73,11 @@ class ServerRegistry:
         """
         if config is None:
             self.registry = self.load_registry_from_file(config_path)
-        elif config.mcp is not None and hasattr(config.mcp, 'servers') and config.mcp.servers is not None:
+        elif (
+            config.mcp is not None
+            and hasattr(config.mcp, "servers")
+            and config.mcp.servers is not None
+        ):
             # Ensure config.mcp exists, has a 'servers' attribute, and it's not None
             self.registry = config.mcp.servers
         else:
@@ -95,13 +99,17 @@ class ServerRegistry:
         Raises:
             ValueError: If the configuration is invalid.
         """
-        servers = {} 
+        servers = {}
 
         settings = get_settings(config_path)
-        
-        if settings.mcp is not None and hasattr(settings.mcp, 'servers') and settings.mcp.servers is not None:
+
+        if (
+            settings.mcp is not None
+            and hasattr(settings.mcp, "servers")
+            and settings.mcp.servers is not None
+        ):
             return settings.mcp.servers
-        
+
         return servers
 
     @asynccontextmanager
@@ -164,7 +172,7 @@ class ServerRegistry:
                     read_stream,
                     write_stream,
                     read_timeout_seconds,
-                    None,  # No callback for stdio
+                    server_config=config,
                 )
                 async with session:
                     logger.info(f"{server_name}: Connected to server using stdio transport.")
@@ -192,7 +200,7 @@ class ServerRegistry:
                     read_stream,
                     write_stream,
                     read_timeout_seconds,
-                    None,  # No callback for stdio
+                    server_config=config,
                 )
                 async with session:
                     logger.info(f"{server_name}: Connected to server using SSE transport.")
@@ -216,7 +224,7 @@ class ServerRegistry:
                     read_stream,
                     write_stream,
                     read_timeout_seconds,
-                    None,  # No callback for stdio
+                    server_config=config,
                 )
                 async with session:
                     logger.info(f"{server_name}: Connected to server using HTTP transport.")

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

@@ -1,7 +1,6 @@
 import asyncio
 
 from mcp_agent.core.fastagent import FastAgent
-from mcp_agent.llm.augmented_llm import RequestParams
 
 # Create the application
 fast = FastAgent("Data Analysis (Roots)")
@@ -21,8 +20,8 @@ Data files are accessible from the /mnt/data/ directory (this is the current wor
 Visualisations should be saved as .png files in the current working directory.
 """,
     servers=["interpreter"],
-    request_params=RequestParams(maxTokens=8192),
 )
+@fast.agent(name="another_test", instruction="", servers=["filesystem"])
 async def main() -> None:
     # Use the app's context manager
     async with fast.run() as agent:

mcp_agent/resources/examples/mcp/elicitations/README.md

@@ -0,0 +1,157 @@
+# Quick Start: MCP Elicitations
+
+This quickstart demonstrates **fast-agent**'s elicitation feature - a powerful way to collect structured data from users through forms and interactive prompts.
+
+## What are Elicitations?
+
+Elicitations allow MCP servers to request structured input from users through type-safe forms. This enables:
+- User preference collection
+- Account registration flows  
+- Configuration wizards
+- Interactive feedback forms
+- Any scenario requiring structured user input
+
+## Examples Included
+
+### 1. Forms Demo (`forms_demo.py`)
+A showcase of different form types with beautiful rich console output. Uses the passthrough model to display forms directly to users.
+
+```bash
+uv run forms_demo.py
+```
+
+This example demonstrates:
+- User profile collection
+- Preference settings
+- Simple yes/no ratings
+- Detailed feedback forms
+
+### 2. Account Creation Assistant (`account_creation.py`)
+An AI-powered account creation workflow where the LLM initiates the account signup process and the user fills out the form.
+
+```bash
+# Configure your LLM first (edit fastagent.config.yaml)
+uv run account_creation.py --model gpt-4o
+```
+
+This example shows:
+- LLM initiating elicitation via tool calls
+- User filling out the form (not the LLM)
+- Tool call errors when user cancels/declines
+- Success handling when form is completed
+
+### 3. Game Character Creator (`game_character.py` + `game_character_handler.py`)
+A whimsical example with custom elicitation handling, featuring animated dice rolls and visual effects.
+
+```bash
+uv run game_character.py
+```
+
+Features:
+- Custom elicitation handler (in separate module for clarity)
+- Animated progress bars and typewriter effects
+- Epic dice roll mechanics with cosmic bonuses
+- Interactive character creation with theatrical flair
+- Demonstrates proper handler file organization
+
+## Getting Started
+
+1. **Setup your environment:**
+   ```bash
+   # Activate your Python environment
+   source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+   
+   # Install dependencies if needed
+   uv pip install fast-agent-mcp
+   ```
+
+2. **For the account creation example**, rename `fastagent.secrets.yaml.example` to `fastagent.secrets.yaml` and add your API keys.
+
+3. **Run an example:**
+   ```bash
+   # Try the forms demo first (quiet mode enabled programmatically)
+   uv run forms_demo.py
+   ```
+
+## How Elicitations Work
+
+### Elicitation Modes
+
+**fast-agent** supports these elicitation modes:
+
+1. **`forms`** - Shows forms to users (great with passthrough model)
+2. **`auto_cancel`** - Automatically cancels all elicitations
+3. **`none`** - No elicitation handling
+4. **Custom handler** - Use your own handler function (overrides mode setting)
+
+Configure modes in `fastagent.config.yaml`:
+
+```yaml
+mcp:
+  servers:
+    my_server:
+      command: "uv"
+      args: ["run", "server.py"]
+      elicitation:
+        mode: "forms"  # or "auto" or "custom"
+```
+
+### Creating Your Own Elicitations
+
+#### Basic Server-Side Elicitation
+
+```python
+from pydantic import BaseModel, Field
+
+class UserPrefs(BaseModel):
+    theme: str = Field(
+        description="Color theme",
+        json_schema_extra={
+            "enum": ["light", "dark"],
+            "enumNames": ["Light Mode", "Dark Mode"]
+        }
+    )
+    notifications: bool = Field(True, description="Enable notifications?")
+
+# In your MCP server:
+result = await mcp.get_context().elicit(
+    "Configure your preferences",
+    schema=UserPrefs
+)
+```
+
+#### Custom Elicitation Handler
+
+For advanced interactive experiences, create a custom handler:
+
+```python
+async def my_custom_handler(context, params) -> ElicitResult:
+    # Your custom logic here - animations, special effects, etc.
+    content = {"field": "value"}
+    return ElicitResult(action="accept", content=content)
+
+# Register with your agent:
+@fast.agent(
+    "my-agent",
+    servers=["my_server"],
+    elicitation_handler=my_custom_handler
+)
+```
+
+See `game_character_handler.py` for a complete example with animations and effects.
+
+## Next Steps
+
+- Explore the example code to understand different patterns
+- Try modifying the forms in `elicitation_server.py`
+- Create your own custom elicitation handlers
+- Check the [documentation](https://fast-agent.ai) for advanced features
+
+## Tips
+
+- Use `rich` for beautiful console output
+- Test with passthrough model first, then try real LLMs
+- Custom handlers enable creative interactions
+- Validate user input in your schemas using Pydantic
+
+Happy form building! 🚀

mcp_agent/resources/examples/mcp/elicitations/elicitation_account_server.py

@@ -0,0 +1,88 @@
+"""
+MCP Server for Account Creation Demo
+
+This server provides an account signup form that can be triggered
+by tools, demonstrating LLM-initiated elicitations.
+
+Note: Following MCP spec, we don't collect sensitive information like passwords.
+"""
+
+import logging
+import sys
+
+from mcp.server.elicitation import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    DeclinedElicitation,
+)
+from mcp.server.fastmcp import FastMCP
+from pydantic import BaseModel, Field
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger("elicitation_account_server")
+
+# Create MCP server
+mcp = FastMCP("Account Creation Server", log_level="INFO")
+
+
+@mcp.tool()
+async def create_user_account(service_name: str = "MyApp") -> str:
+    """
+    Create a new user account for the specified service.
+
+    Args:
+        service_name: The name of the service to create an account for
+
+    Returns:
+        Status message about the account creation
+    """
+    # This tool triggers the elicitation form
+    logger.info(f"Creating account for service: {service_name}")
+
+    class AccountSignup(BaseModel):
+        username: str = Field(description="Choose a username", min_length=3, max_length=20)
+        email: str = Field(description="Your email address", json_schema_extra={"format": "email"})
+        full_name: str = Field(description="Your full name", max_length=30)
+
+        language: str = Field(
+            default="en",
+            description="Preferred language",
+            json_schema_extra={
+                "enum": [
+                    "en",
+                    "zh",
+                    "es",
+                    "fr",
+                    "de",
+                    "ja",
+                ],
+                "enumNames": ["English", "中文", "Español", "Français", "Deutsch", "日本語"],
+            },
+        )
+        agree_terms: bool = Field(description="I agree to the terms of service")
+        marketing_emails: bool = Field(False, description="Send me product updates")
+
+    result = await mcp.get_context().elicit(
+        f"Create Your {service_name} Account", schema=AccountSignup
+    )
+
+    match result:
+        case AcceptedElicitation(data=data):
+            if not data.agree_terms:
+                return "❌ Account creation failed: You must agree to the terms of service"
+            else:
+                return f"✅ Account created successfully for {service_name}!\nUsername: {data.username}\nEmail: {data.email}"
+        case DeclinedElicitation():
+            return f"❌ Account creation for {service_name} was declined by user"
+        case CancelledElicitation():
+            return f"❌ Account creation for {service_name} was cancelled by user"
+
+
+if __name__ == "__main__":
+    logger.info("Starting account creation server...")
+    mcp.run()