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

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()

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

@@ -0,0 +1,232 @@
+"""
+MCP Server for Basic Elicitation Forms Demo
+
+This server provides various elicitation resources that demonstrate
+different form types and validation patterns.
+"""
+
+import logging
+import sys
+from typing import Optional
+
+from mcp import ReadResourceResult
+from mcp.server.elicitation import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    DeclinedElicitation,
+)
+from mcp.server.fastmcp import FastMCP
+from mcp.types import TextResourceContents
+from pydantic import AnyUrl, 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_forms_server")
+
+# Create MCP server
+mcp = FastMCP("Elicitation Forms Demo Server", log_level="INFO")
+
+
+@mcp.resource(uri="elicitation://event-registration")
+async def event_registration() -> ReadResourceResult:
+    """Register for a tech conference event."""
+
+    class EventRegistration(BaseModel):
+        name: str = Field(description="Your full name", min_length=2, max_length=100)
+        email: str = Field(description="Your email address", json_schema_extra={"format": "email"})
+        company_website: Optional[str] = Field(
+            None, description="Your company website (optional)", json_schema_extra={"format": "uri"}
+        )
+        event_date: str = Field(
+            description="Which event date works for you?", json_schema_extra={"format": "date"}
+        )
+        dietary_requirements: Optional[str] = Field(
+            None, description="Any dietary requirements? (optional)", max_length=200
+        )
+
+    result = await mcp.get_context().elicit(
+        "Register for the fast-agent conference - fill out your details",
+        schema=EventRegistration,
+    )
+
+    match result:
+        case AcceptedElicitation(data=data):
+            lines = [
+                f"✅ Registration confirmed for {data.name}",
+                f"📧 Email: {data.email}",
+                f"🏢 Company: {data.company_website or 'Not provided'}",
+                f"📅 Event Date: {data.event_date}",
+                f"🍽️ Dietary Requirements: {data.dietary_requirements or 'None'}",
+            ]
+            response = "\n".join(lines)
+        case DeclinedElicitation():
+            response = "Registration declined - no ticket reserved"
+        case CancelledElicitation():
+            response = "Registration cancelled - please try again later"
+
+    return ReadResourceResult(
+        contents=[
+            TextResourceContents(
+                mimeType="text/plain", uri=AnyUrl("elicitation://event-registration"), text=response
+            )
+        ]
+    )
+
+
+@mcp.resource(uri="elicitation://product-review")
+async def product_review() -> ReadResourceResult:
+    """Submit a product review with rating and comments."""
+
+    class ProductReview(BaseModel):
+        rating: int = Field(description="Rate this product (1-5 stars)", ge=1, le=5)
+        satisfaction: float = Field(
+            description="Overall satisfaction score (0.0-10.0)", ge=0.0, le=10.0
+        )
+        category: str = Field(
+            description="What type of product is this?",
+            json_schema_extra={
+                "enum": ["electronics", "books", "clothing", "home", "sports"],
+                "enumNames": [
+                    "Electronics",
+                    "Books & Media",
+                    "Clothing",
+                    "Home & Garden",
+                    "Sports & Outdoors",
+                ],
+            },
+        )
+        review_text: str = Field(
+            description="Tell us about your experience", min_length=10, max_length=1000
+        )
+
+    result = await mcp.get_context().elicit(
+        "Share your product review - Help others make informed decisions!", schema=ProductReview
+    )
+
+    match result:
+        case AcceptedElicitation(data=data):
+            stars = "⭐" * data.rating
+            lines = [
+                "🎯 Product Review Submitted!",
+                f"⭐ Rating: {stars} ({data.rating}/5)",
+                f"📊 Satisfaction: {data.satisfaction}/10.0",
+                f"📦 Category: {data.category.replace('_', ' ').title()}",
+                f"💬 Review: {data.review_text}",
+            ]
+            response = "\n".join(lines)
+        case DeclinedElicitation():
+            response = "Review declined - no feedback submitted"
+        case CancelledElicitation():
+            response = "Review cancelled - you can submit it later"
+
+    return ReadResourceResult(
+        contents=[
+            TextResourceContents(
+                mimeType="text/plain", uri=AnyUrl("elicitation://product-review"), text=response
+            )
+        ]
+    )
+
+
+@mcp.resource(uri="elicitation://account-settings")
+async def account_settings() -> ReadResourceResult:
+    """Configure your account settings and preferences."""
+
+    class AccountSettings(BaseModel):
+        email_notifications: bool = Field(True, description="Receive email notifications?")
+        marketing_emails: bool = Field(False, description="Subscribe to marketing emails?")
+        theme: str = Field(
+            description="Choose your preferred theme",
+            json_schema_extra={
+                "enum": ["light", "dark", "auto"],
+                "enumNames": ["Light Theme", "Dark Theme", "Auto (System)"],
+            },
+        )
+        privacy_public: bool = Field(False, description="Make your profile public?")
+        items_per_page: int = Field(description="Items to show per page (10-100)", ge=10, le=100)
+
+    result = await mcp.get_context().elicit("Update your account settings", schema=AccountSettings)
+
+    match result:
+        case AcceptedElicitation(data=data):
+            lines = [
+                "⚙️ Account Settings Updated!",
+                f"📧 Email notifications: {'On' if data.email_notifications else 'Off'}",
+                f"📬 Marketing emails: {'On' if data.marketing_emails else 'Off'}",
+                f"🎨 Theme: {data.theme.title()}",
+                f"👥 Public profile: {'Yes' if data.privacy_public else 'No'}",
+                f"📄 Items per page: {data.items_per_page}",
+            ]
+            response = "\n".join(lines)
+        case DeclinedElicitation():
+            response = "Settings unchanged - keeping current preferences"
+        case CancelledElicitation():
+            response = "Settings update cancelled"
+
+    return ReadResourceResult(
+        contents=[
+            TextResourceContents(
+                mimeType="text/plain", uri=AnyUrl("elicitation://account-settings"), text=response
+            )
+        ]
+    )
+
+
+@mcp.resource(uri="elicitation://service-appointment")
+async def service_appointment() -> ReadResourceResult:
+    """Schedule a car service appointment."""
+
+    class ServiceAppointment(BaseModel):
+        customer_name: str = Field(description="Your full name", min_length=2, max_length=50)
+        vehicle_type: str = Field(
+            description="What type of vehicle do you have?",
+            json_schema_extra={
+                "enum": ["sedan", "suv", "truck", "motorcycle", "other"],
+                "enumNames": ["Sedan", "SUV/Crossover", "Truck", "Motorcycle", "Other"],
+            },
+        )
+        needs_loaner: bool = Field(description="Do you need a loaner vehicle?")
+        appointment_time: str = Field(
+            description="Preferred appointment date and time",
+            json_schema_extra={"format": "date-time"},
+        )
+        priority_service: bool = Field(False, description="Is this an urgent repair?")
+
+    result = await mcp.get_context().elicit(
+        "Schedule your vehicle service appointment", schema=ServiceAppointment
+    )
+
+    match result:
+        case AcceptedElicitation(data=data):
+            lines = [
+                "🔧 Service Appointment Scheduled!",
+                f"👤 Customer: {data.customer_name}",
+                f"🚗 Vehicle: {data.vehicle_type.title()}",
+                f"🚙 Loaner needed: {'Yes' if data.needs_loaner else 'No'}",
+                f"📅 Appointment: {data.appointment_time}",
+                f"⚡ Priority service: {'Yes' if data.priority_service else 'No'}",
+            ]
+            response = "\n".join(lines)
+        case DeclinedElicitation():
+            response = "Appointment cancelled - call us when you're ready!"
+        case CancelledElicitation():
+            response = "Appointment scheduling cancelled"
+
+    return ReadResourceResult(
+        contents=[
+            TextResourceContents(
+                mimeType="text/plain",
+                uri=AnyUrl("elicitation://service-appointment"),
+                text=response,
+            )
+        ]
+    )
+
+
+if __name__ == "__main__":
+    logger.info("Starting elicitation forms demo server...")
+    mcp.run()

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

@@ -0,0 +1,164 @@
+"""
+MCP Server for Game Character Creation
+
+This server provides a fun game character creation form
+that can be used with custom handlers.
+"""
+
+import logging
+import random
+import sys
+
+from mcp import ReadResourceResult
+from mcp.server.elicitation import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    DeclinedElicitation,
+)
+from mcp.server.fastmcp import FastMCP
+from mcp.types import TextResourceContents
+from pydantic import AnyUrl, 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_game_server")
+
+# Create MCP server
+mcp = FastMCP("Game Character Creation Server", log_level="INFO")
+
+
+@mcp.resource(uri="elicitation://game-character")
+async def game_character() -> ReadResourceResult:
+    """Fun game character creation form for the whimsical example."""
+
+    class GameCharacter(BaseModel):
+        character_name: str = Field(description="Name your character", min_length=2, max_length=30)
+        character_class: str = Field(
+            description="Choose your class",
+            json_schema_extra={
+                "enum": ["warrior", "mage", "rogue", "ranger", "paladin", "bard"],
+                "enumNames": [
+                    "⚔️ Warrior",
+                    "🔮 Mage",
+                    "🗡️ Rogue",
+                    "🏹 Ranger",
+                    "🛡️ Paladin",
+                    "🎵 Bard",
+                ],
+            },
+        )
+        strength: int = Field(description="Strength (3-18)", ge=3, le=18, default=10)
+        intelligence: int = Field(description="Intelligence (3-18)", ge=3, le=18, default=10)
+        dexterity: int = Field(description="Dexterity (3-18)", ge=3, le=18, default=10)
+        charisma: int = Field(description="Charisma (3-18)", ge=3, le=18, default=10)
+        lucky_dice: bool = Field(False, description="Roll for a lucky bonus?")
+
+    result = await mcp.get_context().elicit("🎮 Create Your Game Character!", schema=GameCharacter)
+
+    match result:
+        case AcceptedElicitation(data=data):
+            lines = [
+                f"🎭 Character Created: {data.character_name}",
+                f"Class: {data.character_class.title()}",
+                f"Stats: STR:{data.strength} INT:{data.intelligence} DEX:{data.dexterity} CHA:{data.charisma}",
+            ]
+
+            if data.lucky_dice:
+                dice_roll = random.randint(1, 20)
+                if dice_roll >= 15:
+                    bonus = random.choice(
+                        [
+                            "🎁 Lucky! +2 to all stats!",
+                            "🌟 Critical! Found a magic item!",
+                            "💰 Jackpot! +100 gold!",
+                        ]
+                    )
+                    lines.append(f"🎲 Dice Roll: {dice_roll} - {bonus}")
+                else:
+                    lines.append(f"🎲 Dice Roll: {dice_roll} - No bonus this time!")
+
+            total_stats = data.strength + data.intelligence + data.dexterity + data.charisma
+            if total_stats > 50:
+                lines.append("💪 Powerful character build!")
+            elif total_stats < 30:
+                lines.append("🎯 Challenging build - good luck!")
+
+            response = "\n".join(lines)
+        case DeclinedElicitation():
+            response = "Character creation declined - returning to menu"
+        case CancelledElicitation():
+            response = "Character creation cancelled"
+
+    return ReadResourceResult(
+        contents=[
+            TextResourceContents(
+                mimeType="text/plain", uri=AnyUrl("elicitation://game-character"), text=response
+            )
+        ]
+    )
+
+
+@mcp.tool()
+async def roll_new_character(campaign_name: str = "Adventure") -> str:
+    """
+    Roll a new character for your campaign.
+
+    Args:
+        campaign_name: The name of the campaign
+
+    Returns:
+        Character details or status message
+    """
+
+    class GameCharacter(BaseModel):
+        character_name: str = Field(description="Name your character", min_length=2, max_length=30)
+        character_class: str = Field(
+            description="Choose your class",
+            json_schema_extra={
+                "enum": ["warrior", "mage", "rogue", "ranger", "paladin", "bard"],
+                "enumNames": [
+                    "⚔️ Warrior",
+                    "🔮 Mage",
+                    "🗡️ Rogue",
+                    "🏹 Ranger",
+                    "🛡️ Paladin",
+                    "🎵 Bard",
+                ],
+            },
+        )
+        strength: int = Field(description="Strength (3-18)", ge=3, le=18, default=10)
+        intelligence: int = Field(description="Intelligence (3-18)", ge=3, le=18, default=10)
+        dexterity: int = Field(description="Dexterity (3-18)", ge=3, le=18, default=10)
+        charisma: int = Field(description="Charisma (3-18)", ge=3, le=18, default=10)
+        lucky_dice: bool = Field(False, description="Roll for a lucky bonus?")
+
+    result = await mcp.get_context().elicit(
+        f"🎮 Create Character for {campaign_name}!", schema=GameCharacter
+    )
+
+    match result:
+        case AcceptedElicitation(data=data):
+            response = f"🎭 {data.character_name} the {data.character_class.title()} joins {campaign_name}!\n"
+            response += f"Stats: STR:{data.strength} INT:{data.intelligence} DEX:{data.dexterity} CHA:{data.charisma}"
+
+            if data.lucky_dice:
+                dice_roll = random.randint(1, 20)
+                if dice_roll >= 15:
+                    response += f"\n🎲 Lucky roll ({dice_roll})! Starting with bonus equipment!"
+                else:
+                    response += f"\n🎲 Rolled {dice_roll} - Standard starting gear."
+
+            return response
+        case DeclinedElicitation():
+            return f"Character creation for {campaign_name} was declined"
+        case CancelledElicitation():
+            return f"Character creation for {campaign_name} was cancelled"
+
+
+if __name__ == "__main__":
+    logger.info("Starting game character creation server...")
+    mcp.run()

mcp_agent/resources/examples/mcp/elicitations/fastagent.config.yaml

@@ -0,0 +1,35 @@
+# Model string takes format:
+#   <provider>.<model_string>.<reasoning_effort?> (e.g. anthropic.claude-3-5-sonnet-20241022 or openai.o3-mini.low)
+#
+# Can be overriden with a command line switch --model=<model>, or within the Agent decorator.
+# Check here for current details: https://fast-agent.ai/models/
+default_model: "passthrough"
+
+# Logging and Console Configuration
+logger:
+  level: "error"
+  type: "console"
+
+# MCP Server Configuration
+mcp:
+  servers:
+    # Forms demo server - interactive form examples
+    elicitation_forms_server:
+      command: "uv"
+      args: ["run", "elicitation_forms_server.py"]
+      elicitation:
+        mode: "forms" # Shows forms to users (default)
+
+    # Account creation server - for CALL_TOOL demos
+    elicitation_account_server:
+      command: "uv"
+      args: ["run", "elicitation_account_server.py"]
+      elicitation:
+        mode: "forms"
+
+    # Game character server - for custom handler demos
+    elicitation_game_server:
+      command: "uv"
+      args: ["run", "elicitation_game_server.py"]
+      elicitation:
+        mode: "forms"