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

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

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

@@ -0,0 +1,297 @@
+"""
+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, TypedDict
+
+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")
+
+
+class TitledEnumOption(TypedDict):
+    """Type definition for oneOf/anyOf schema options."""
+
+    const: str
+    title: str
+
+
+def _create_enum_schema_options(data: dict[str, str]) -> list[TitledEnumOption]:
+    """Convert a dictionary to oneOf/anyOf schema format.
+
+    Args:
+        data: Dictionary mapping enum values to display titles
+
+    Returns:
+        List of schema options with 'const' and 'title' fields
+
+    Example:
+        >>> _create_enum_schema_options({"dark": "Dark Mode", "light": "Light Mode"})
+        [{"const": "dark", "title": "Dark Mode"}, {"const": "light", "title": "Light Mode"}]
+    """
+    return [{"const": k, "title": v} for k, v in data.items()]
+
+
+@mcp.resource(uri="elicitation://event-registration")
+async def event_registration() -> ReadResourceResult:
+    """Register for a tech conference event."""
+    workshop_names = {
+        "ai_basics": "AI Fundamentals",
+        "llm_apps": "Building LLM Applications",
+        "prompt_eng": "Prompt Engineering",
+        "rag_systems": "RAG Systems",
+        "fine_tuning": "Model Fine-tuning",
+        "deployment": "Production Deployment",
+    }
+
+    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: str | None = Field(
+            None, description="Your company website (optional)", json_schema_extra={"format": "uri"}
+        )
+        workshops: list[str] = Field(
+            description="Select the workshops you want to attend",
+            min_length=1,
+            max_length=3,
+            json_schema_extra={
+                "items": {
+                    "enum": list(workshop_names.keys()),
+                    "enumNames": list(workshop_names.values()),
+                },
+                "uniqueItems": True,
+            },
+        )
+        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'}",
+                f"🎓 Workshops ({len(data.workshops)} selected):",
+            ]
+            for workshop in data.workshops:
+                lines.append(f"   • {workshop_names.get(workshop, workshop)}")
+            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."""
+    categories = {
+        "electronics": "Electronics",
+        "books": "Books & Media",
+        "clothing": "Clothing",
+        "home": "Home & Garden",
+        "sports": "Sports & Outdoors",
+    }
+
+    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={"oneOf": _create_enum_schema_options(categories)},
+        )
+        review_text: str = Field(
+            description="Tell us about your experience",
+            default="""Great product!
+Here's what I loved:
+
+- Excellent build quality
+- Fast shipping
+- Works as advertised
+
+One minor issue:
+- Instructions could be clearer
+
+Overall, highly recommended!""",
+            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: {categories.get(data.category, data.category)}",
+                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."""
+
+    themes = {"light": "Light Theme", "dark": "Dark Theme", "auto": "Auto (System)"}
+
+    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(
+            "dark",
+            description="Choose your preferred theme",
+            json_schema_extra={"oneOf": _create_enum_schema_options(themes)},
+        )
+        privacy_public: bool = Field(False, description="Make your profile public?")
+        items_per_page: int = Field(
+            25, 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: {themes.get(data.theme, data.theme)}",
+                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)
+        phone_number: str = Field(
+            "555-", description="Contact phone number", min_length=10, max_length=20
+        )
+        vehicle_type: str = Field(
+            default="sedan",
+            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"📞 Phone: {data.phone_number}",
+                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()

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

fast_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"

fast_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: "..."