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

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"

mcp_agent/resources/examples/mcp/elicitations/fastagent.secrets.yaml.example

@@ -0,0 +1,17 @@
+# Secrets configuration for elicitation examples
+#
+# Rename this file to fastagent.secrets.yaml and add your API keys
+# to use the account_creation.py example with real LLMs
+
+# OpenAI
+openai_api_key: "sk-..."
+
+# Anthropic
+anthropic_api_key: "sk-ant-..."
+
+# Google (Gemini)
+google_api_key: "..."
+
+# Other providers - see documentation for full list
+# groq_api_key: "..."
+# mistral_api_key: "..."

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

@@ -0,0 +1,111 @@
+"""
+Quick Start: Elicitation Forms Demo
+
+This example demonstrates the elicitation forms feature of fast-agent.
+
+When Read Resource requests are sent to the MCP Server, it generates an Elicitation
+which creates a form for the user to fill out.
+The results are returned to the demo program which prints out the results in a rich format.
+"""
+
+import asyncio
+
+from rich.console import Console
+from rich.panel import Panel
+
+from mcp_agent.core.fastagent import FastAgent
+from mcp_agent.mcp.helpers.content_helpers import get_resource_text
+
+fast = FastAgent("Elicitation Forms Demo", quiet=True)
+console = Console()
+
+
+@fast.agent(
+    "forms-demo",
+    servers=[
+        "elicitation_forms_server",
+    ],
+)
+async def main():
+    """Run the improved forms demo showcasing all elicitation features."""
+    async with fast.run() as agent:
+        console.print("\n[bold cyan]Welcome to the Elicitation Forms Demo![/bold cyan]\n")
+        console.print("This demo shows how to collect structured data using MCP Elicitations.")
+        console.print("We'll present several forms and display the results collected for each.\n")
+
+        # Example 1: Event Registration
+        console.print("[bold yellow]Example 1: Event Registration Form[/bold yellow]")
+        console.print(
+            "[dim]Demonstrates: string validation, email format, URL format, date format[/dim]"
+        )
+        result = await agent.get_resource("elicitation://event-registration")
+
+        if result_text := get_resource_text(result):
+            panel = Panel(
+                result_text,
+                title="🎫 Registration Confirmation",
+                border_style="green",
+                expand=False,
+            )
+            console.print(panel)
+        else:
+            console.print("[red]No registration data received[/red]")
+
+        console.print("\n" + "─" * 50 + "\n")
+
+        # Example 2: Product Review
+        console.print("[bold yellow]Example 2: Product Review Form[/bold yellow]")
+        console.print(
+            "[dim]Demonstrates: number validation (range), radio selection, multiline text[/dim]"
+        )
+        result = await agent.get_resource("elicitation://product-review")
+
+        if result_text := get_resource_text(result):
+            review_panel = Panel(
+                result_text, title="🛍️ Product Review", border_style="cyan", expand=False
+            )
+            console.print(review_panel)
+
+        console.print("\n" + "─" * 50 + "\n")
+
+        # Example 3: Account Settings
+        console.print("[bold yellow]Example 3: Account Settings Form[/bold yellow]")
+        console.print(
+            "[dim]Demonstrates: boolean selections, radio selection, number validation[/dim]"
+        )
+        result = await agent.get_resource("elicitation://account-settings")
+
+        if result_text := get_resource_text(result):
+            settings_panel = Panel(
+                result_text, title="⚙️ Account Settings", border_style="blue", expand=False
+            )
+            console.print(settings_panel)
+
+        console.print("\n" + "─" * 50 + "\n")
+
+        # Example 4: Service Appointment
+        console.print("[bold yellow]Example 4: Service Appointment Booking[/bold yellow]")
+        console.print(
+            "[dim]Demonstrates: string validation, radio selection, boolean, datetime format[/dim]"
+        )
+        result = await agent.get_resource("elicitation://service-appointment")
+
+        if result_text := get_resource_text(result):
+            appointment_panel = Panel(
+                result_text, title="🔧 Appointment Confirmed", border_style="magenta", expand=False
+            )
+            console.print(appointment_panel)
+
+        console.print("\n[bold green]✅ Demo Complete![/bold green]")
+        console.print("\n[bold cyan]Features Demonstrated:[/bold cyan]")
+        console.print("• [green]String validation[/green] (min/max length)")
+        console.print("• [green]Number validation[/green] (range constraints)")
+        console.print("• [green]Radio selections[/green] (enum dropdowns)")
+        console.print("• [green]Boolean selections[/green] (checkboxes)")
+        console.print("• [green]Format validation[/green] (email, URL, date, datetime)")
+        console.print("• [green]Multiline text[/green] (expandable text areas)")
+        console.print("\nThese forms demonstrate natural, user-friendly data collection patterns!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Demonstration of Custom Elicitation Handler
+
+This example demonstrates a custom elicitation handler that creates
+an interactive game character creation experience with dice rolls,
+visual gauges, and fun interactions.
+"""
+
+import asyncio
+
+# Import our custom handler from the separate module
+from game_character_handler import game_character_elicitation_handler
+from rich.console import Console
+from rich.panel import Panel
+
+from mcp_agent.core.fastagent import FastAgent
+from mcp_agent.mcp.helpers.content_helpers import get_resource_text
+
+fast = FastAgent("Game Character Creator", quiet=True)
+console = Console()
+
+
+@fast.agent(
+    "character-creator",
+    servers=["elicitation_game_server"],
+    # Register our handler from game_character_handler.py
+    elicitation_handler=game_character_elicitation_handler,
+)
+async def main():
+    """Run the game character creator with custom elicitation handler."""
+    async with fast.run() as agent:
+        console.print(
+            Panel(
+                "[bold cyan]Welcome to the Character Creation Studio![/bold cyan]\n\n"
+                "Create your hero with our magical character generator.\n"
+                "Watch as the cosmic dice determine your fate!",
+                title="🎮 Game Time 🎮",
+                border_style="magenta",
+            )
+        )
+
+        # Trigger the character creation
+        result = await agent.get_resource("elicitation://game-character")
+
+        if result_text := get_resource_text(result):
+            character_panel = Panel(
+                result_text, title="📜 Your Character 📜", border_style="green", expand=False
+            )
+            console.print(character_panel)
+
+            console.print("\n[italic]Your character is ready for adventure![/italic]")
+            console.print("[dim]The tavern door opens, and your journey begins...[/dim]\n")
+
+            # Fun ending based on character
+            if "Powerful character" in result_text:
+                console.print("⚔️  [bold]The realm trembles at your might![/bold]")
+            elif "Challenging build" in result_text:
+                console.print("🎯 [bold]True heroes are forged through adversity![/bold]")
+            else:
+                console.print("🗡️  [bold]Your legend begins now![/bold]")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())