fast-agent-mcp 0.2.36__tar.gz → 0.2.37__tar.gz

{fast_agent_mcp-0.2.36 → fast_agent_mcp-0.2.37}/.gitignore

@@ -85,7 +85,7 @@ ipython_config.py
 # pyenv
 #   For a library or package, you might want to ignore these files since the code is
 #   intended to run in multiple environments; otherwise, check them in:
-# .python-version
+.python-version
 
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
@@ -160,6 +160,9 @@ examples/**/*.secrets.yaml
 # but make sure example files are
 !examples/**/*.secrets.yaml.example
 
+# Build-generated resources (copied from examples/ during build)
+src/mcp_agent/resources/examples/
+
 # Test data files
 examples/mcp_root_test/test_data/*.png
 

{fast_agent_mcp-0.2.36 → fast_agent_mcp-0.2.37}/LICENSE

@@ -186,7 +186,7 @@ APPENDIX: How to apply the Apache License to your work.
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-Copyright [2025] [llmindset.co.uk]
+Copyright 2025 llmindset.co.uk
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

{fast_agent_mcp-0.2.36 → fast_agent_mcp-0.2.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.2.36
+Version: 0.2.37
 Summary: Define, Prompt and Test MCP enabled Agents and Workflows
 Author-email: Shaun Smith <fastagent@llmindset.co.uk>
 License:                                  Apache License
@@ -191,7 +191,7 @@ License:                                  Apache License
               same "printed page" as the copyright notice for easier
               identification within third-party archives.
         
-        Copyright [2025] [llmindset.co.uk]
+        Copyright 2025 llmindset.co.uk
         
         Licensed under the Apache License, Version 2.0 (the "License");
         you may not use this file except in compliance with the License.
@@ -208,22 +208,23 @@ License-File: LICENSE
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Requires-Dist: a2a-sdk>=0.2.9
 Requires-Dist: aiohttp>=3.11.13
 Requires-Dist: anthropic>=0.55.0
 Requires-Dist: azure-identity>=1.14.0
 Requires-Dist: deprecated>=1.2.18
+Requires-Dist: email-validator>=2.2.0
 Requires-Dist: fastapi>=0.115.6
 Requires-Dist: google-genai
 Requires-Dist: mcp==1.10.1
 Requires-Dist: openai>=1.93.0
 Requires-Dist: opentelemetry-distro>=0.50b0
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.29.0
-Requires-Dist: opentelemetry-instrumentation-anthropic>=0.40.7; python_version >= '3.10' and python_version < '4.0'
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.40.14; python_version >= '3.10' and python_version < '4.0'
 Requires-Dist: opentelemetry-instrumentation-google-genai>=0.2b0
-Requires-Dist: opentelemetry-instrumentation-mcp>=0.40.7; python_version >= '3.10' and python_version < '4.0'
-Requires-Dist: opentelemetry-instrumentation-openai>=0.0.40.7; python_version >= '3.10' and python_version < '4.0'
+Requires-Dist: opentelemetry-instrumentation-mcp>=0.40.14; python_version >= '3.10' and python_version < '4.0'
+Requires-Dist: opentelemetry-instrumentation-openai>=0.40.14; python_version >= '3.10' and python_version < '4.0'
 Requires-Dist: prompt-toolkit>=3.0.50
 Requires-Dist: pydantic-settings>=2.7.0
 Requires-Dist: pydantic>=2.10.4
@@ -261,7 +262,9 @@ Description-Content-Type: text/markdown
 > [!TIP]
 > Documentation site is in production here : https://fast-agent.ai. Feel free to feed back what's helpful and what's not. There is also an LLMs.txt [here](https://fast-agent.ai/llms.txt)
 
-**`fast-agent`** enables you to create and interact with sophisticated Agents and Workflows in minutes. It is the first framework with complete, end-to-end tested MCP Feature support including Sampling. Both Anthropic (Haiku, Sonnet, Opus) and OpenAI models (gpt-4o/gpt-4.1 family, o1/o3 family) are supported.
+**`fast-agent`** enables you to create and interact with sophisticated Agents and Workflows in minutes. It is the first framework with complete, end-to-end tested MCP Feature support including Sampling. Model support is comprehensive with native support for Anthropic, OpenAI and Google as well as Azure, Ollama, Deepseek and dozens of others via TensorZero.
+
+![multi_model_trim](https://github.com/user-attachments/assets/c8bf7474-2c41-4ef3-8924-06e29907d7c6)
 
 The simple declarative syntax lets you concentrate on composing your Prompts and MCP Servers to [build effective agents](https://www.anthropic.com/research/building-effective-agents).
 

{fast_agent_mcp-0.2.36 → fast_agent_mcp-0.2.37}/README.md

@@ -12,7 +12,9 @@
 > [!TIP]
 > Documentation site is in production here : https://fast-agent.ai. Feel free to feed back what's helpful and what's not. There is also an LLMs.txt [here](https://fast-agent.ai/llms.txt)
 
-**`fast-agent`** enables you to create and interact with sophisticated Agents and Workflows in minutes. It is the first framework with complete, end-to-end tested MCP Feature support including Sampling. Both Anthropic (Haiku, Sonnet, Opus) and OpenAI models (gpt-4o/gpt-4.1 family, o1/o3 family) are supported.
+**`fast-agent`** enables you to create and interact with sophisticated Agents and Workflows in minutes. It is the first framework with complete, end-to-end tested MCP Feature support including Sampling. Model support is comprehensive with native support for Anthropic, OpenAI and Google as well as Azure, Ollama, Deepseek and dozens of others via TensorZero.
+
+![multi_model_trim](https://github.com/user-attachments/assets/c8bf7474-2c41-4ef3-8924-06e29907d7c6)
 
 The simple declarative syntax lets you concentrate on composing your Prompts and MCP Servers to [build effective agents](https://www.anthropic.com/research/building-effective-agents).
 

fast_agent_mcp-0.2.37/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! 🚀

fast_agent_mcp-0.2.37/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_mcp-0.2.37/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()