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

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

@@ -0,0 +1,256 @@
+"""
+Custom Elicitation Handler for Game Character Creation
+
+This module provides a whimsical custom elicitation handler that creates
+an interactive game character creation experience with dice rolls,
+visual gauges, and animated effects.
+"""
+
+import asyncio
+import random
+from typing import TYPE_CHECKING, Any, Dict
+
+from mcp.shared.context import RequestContext
+from mcp.types import ElicitRequestParams, ElicitResult
+from rich.console import Console
+from rich.progress import BarColumn, Progress, TextColumn
+from rich.prompt import Confirm
+from rich.table import Table
+
+from mcp_agent.logging.logger import get_logger
+
+if TYPE_CHECKING:
+    from mcp import ClientSession
+
+logger = get_logger(__name__)
+console = Console()
+
+
+async def game_character_elicitation_handler(
+    context: RequestContext["ClientSession", Any],
+    params: ElicitRequestParams,
+) -> ElicitResult:
+    """Custom handler that creates an interactive character creation experience."""
+    logger.info(f"Game character elicitation handler called: {params.message}")
+
+    if params.requestedSchema:
+        properties = params.requestedSchema.get("properties", {})
+        content: Dict[str, Any] = {}
+
+        console.print("\n[bold magenta]🎮 Character Creation Studio 🎮[/bold magenta]\n")
+
+        # Character name with typewriter effect
+        if "character_name" in properties:
+            console.print("[cyan]✨ Generating your character's name...[/cyan] ", end="")
+            name_prefixes = ["Hero", "Legend", "Epic", "Mighty", "Brave", "Noble"]
+            name_suffixes = ["blade", "heart", "storm", "fire", "shadow", "star"]
+
+            name = f"{random.choice(name_prefixes)}{random.choice(name_suffixes)}{random.randint(1, 999)}"
+
+            for char in name:
+                console.print(char, end="", style="bold green")
+                await asyncio.sleep(0.03)
+            console.print("\n")
+            content["character_name"] = name
+
+        # Class selection with visual menu and fate dice
+        if "character_class" in properties:
+            class_enum = properties["character_class"].get("enum", [])
+            class_names = properties["character_class"].get("enumNames", class_enum)
+
+            table = Table(title="🎯 Choose Your Destiny", show_header=False, box=None)
+            table.add_column("Option", style="cyan", width=8)
+            table.add_column("Class", style="yellow", width=20)
+            table.add_column("Description", style="dim", width=30)
+
+            descriptions = [
+                "Master of sword and shield",
+                "Wielder of arcane mysteries",
+                "Silent shadow striker",
+                "Nature's deadly archer",
+                "Holy warrior of light",
+                "Inspiring magical performer",
+            ]
+
+            for i, (cls, name, desc) in enumerate(zip(class_enum, class_names, descriptions)):
+                table.add_row(f"[{i + 1}]", name, desc)
+
+            console.print(table)
+
+            # Dramatic fate dice roll
+            console.print("\n[bold yellow]🎲 The Fates decide your path...[/bold yellow]")
+            for _ in range(8):
+                dice_face = random.choice(["⚀", "⚁", "⚂", "⚃", "⚄", "⚅"])
+                console.print(f"\r  Rolling... {dice_face}", end="")
+                await asyncio.sleep(0.2)
+
+            fate_roll = random.randint(1, 6)
+            selected_idx = (fate_roll - 1) % len(class_enum)
+            console.print(f"\n  🎲 Fate dice: [bold red]{fate_roll}[/bold red]!")
+            console.print(
+                f"✨ Destiny has chosen: [bold yellow]{class_names[selected_idx]}[/bold yellow]!\n"
+            )
+            content["character_class"] = class_enum[selected_idx]
+
+        # Stats rolling with animated progress bars and cosmic effects
+        stat_names = ["strength", "intelligence", "dexterity", "charisma"]
+        stats_info = {
+            "strength": {"emoji": "💪", "desc": "Physical power"},
+            "intelligence": {"emoji": "🧠", "desc": "Mental acuity"},
+            "dexterity": {"emoji": "🏃", "desc": "Agility & speed"},
+            "charisma": {"emoji": "✨", "desc": "Personal magnetism"},
+        }
+
+        console.print("[bold]🌟 Rolling cosmic dice for your abilities...[/bold]\n")
+
+        with Progress(
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(bar_width=25, style="cyan", complete_style="green"),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+            console=console,
+        ) as progress:
+            for stat in stat_names:
+                if stat in properties:
+                    # Roll 3d6 for classic D&D feel with bonus potential
+                    rolls = [random.randint(1, 6) for _ in range(3)]
+                    total = sum(rolls)
+
+                    # Add cosmic bonus chance
+                    if random.random() < 0.15:  # 15% chance for cosmic boost
+                        cosmic_bonus = random.randint(1, 3)
+                        total = min(18, total + cosmic_bonus)
+                        cosmic_text = f" ✨+{cosmic_bonus} COSMIC✨"
+                    else:
+                        cosmic_text = ""
+
+                    stat_info = stats_info.get(stat, {"emoji": "📊", "desc": stat.title()})
+                    task = progress.add_task(
+                        f"{stat_info['emoji']} {stat.capitalize()}: {stat_info['desc']}", total=18
+                    )
+
+                    # Animate the progress bar with suspense
+                    for i in range(total + 1):
+                        progress.update(task, completed=i)
+                        await asyncio.sleep(0.04)
+
+                    content[stat] = total
+                    console.print(
+                        f"   🎲 Rolled: {rolls} = [bold green]{total}[/bold green]{cosmic_text}"
+                    )
+
+        # Lucky dice legendary challenge
+        if "lucky_dice" in properties:
+            console.print("\n" + "=" * 60)
+            console.print("[bold yellow]🎰 LEGENDARY CHALLENGE: Lucky Dice! 🎰[/bold yellow]")
+            console.print("The ancient dice of fortune whisper your name...")
+            console.print("Do you dare tempt fate for legendary power?")
+            console.print("=" * 60)
+
+            # Epic dice rolling sequence
+            console.print("\n[cyan]🌟 Rolling the Dice of Destiny...[/cyan]")
+
+            for i in range(15):
+                dice_faces = ["⚀", "⚁", "⚂", "⚃", "⚄", "⚅"]
+                d20_faces = ["🎲"] * 19 + ["💎"]  # Special diamond for 20
+
+                if i < 10:
+                    face = random.choice(dice_faces)
+                else:
+                    face = random.choice(d20_faces)
+
+                console.print(f"\r  [bold]{face}[/bold] Rolling...", end="")
+                await asyncio.sleep(0.15)
+
+            final_roll = random.randint(1, 20)
+
+            if final_roll == 20:
+                console.print("\r  [bold red]💎 NATURAL 20! 💎[/bold red]")
+                console.print("  [bold green]🌟 LEGENDARY SUCCESS! 🌟[/bold green]")
+                console.print("  [gold1]You have been blessed by the gods themselves![/gold1]")
+                bonus_text = "🏆 Divine Champion status unlocked!"
+            elif final_roll >= 18:
+                console.print(f"\r  [bold yellow]⭐ {final_roll} - EPIC ROLL! ⭐[/bold yellow]")
+                bonus_text = "🎁 Epic treasure discovered!"
+            elif final_roll >= 15:
+                console.print(f"\r  [green]🎲 {final_roll} - Great success![/green]")
+                bonus_text = "🌟 Rare magical item found!"
+            elif final_roll >= 10:
+                console.print(f"\r  [yellow]🎲 {final_roll} - Good fortune.[/yellow]")
+                bonus_text = "🗡️ Modest blessing received."
+            elif final_roll == 1:
+                console.print("\r  [bold red]💀 CRITICAL FUMBLE! 💀[/bold red]")
+                bonus_text = "😅 Learning experience gained... try again!"
+            else:
+                console.print(f"\r  [dim]🎲 {final_roll} - The dice are silent.[/dim]")
+                bonus_text = "🎯 Your destiny remains unwritten."
+
+            console.print(f"  [italic]{bonus_text}[/italic]")
+            content["lucky_dice"] = final_roll >= 10
+
+        # Epic character summary with theatrical flair
+        console.print("\n" + "=" * 70)
+        console.print("[bold cyan]📜 Your Character Has Been Rolled! 📜[/bold cyan]")
+        console.print("=" * 70)
+
+        # Show character summary
+        total_stats = sum(content.get(stat, 10) for stat in stat_names if stat in content)
+
+        # Create a simple table
+        stats_table = Table(show_header=False, box=None)
+        stats_table.add_column("Label", style="cyan", width=15)
+        stats_table.add_column("Value", style="bold white")
+
+        if "character_name" in content:
+            stats_table.add_row("Name:", content["character_name"])
+        if "character_class" in content:
+            class_idx = class_enum.index(content["character_class"])
+            stats_table.add_row("Class:", class_names[class_idx])
+
+        stats_table.add_row("", "")  # Empty row for spacing
+
+        # Add stats
+        for stat in stat_names:
+            if stat in content:
+                stat_label = f"{stat.capitalize()}:"
+                stats_table.add_row(stat_label, str(content[stat]))
+
+        stats_table.add_row("", "")
+        stats_table.add_row("Total Power:", str(total_stats))
+
+        console.print(stats_table)
+
+        # Power message
+        if total_stats > 60:
+            console.print("✨ [bold gold1]The realm trembles before your might![/bold gold1] ✨")
+        elif total_stats > 50:
+            console.print("⚔️ [bold green]A formidable hero rises![/bold green] ⚔️")
+        elif total_stats < 35:
+            console.print("🎯 [bold blue]The underdog's tale begins![/bold blue] 🎯")
+        else:
+            console.print("🗡️ [bold white]Adventure awaits the worthy![/bold white] 🗡️")
+
+        # Ask for confirmation
+        console.print("\n[bold yellow]Do you accept this character?[/bold yellow]")
+        console.print("[dim]Press Enter to accept, 'n' to decline, or Ctrl+C to cancel[/dim]\n")
+
+        try:
+            accepted = Confirm.ask("Accept character?", default=True)
+
+            if accepted:
+                console.print(
+                    "\n[bold green]✅ Character accepted! Your adventure begins![/bold green]"
+                )
+                return ElicitResult(action="accept", content=content)
+            else:
+                console.print(
+                    "\n[yellow]❌ Character declined. The fates will roll again...[/yellow]"
+                )
+                return ElicitResult(action="decline")
+        except KeyboardInterrupt:
+            console.print("\n[red]❌ Character creation cancelled![/red]")
+            return ElicitResult(action="cancel")
+
+    else:
+        # No schema, return a fun message
+        content = {"response": "⚔️ Ready for adventure! ⚔️"}
+        return ElicitResult(action="accept", content=content)

mcp_agent/resources/examples/{prompting/agent.py → mcp/elicitations/tool_call.py}

@@ -3,19 +3,18 @@ import asyncio
 from mcp_agent.core.fastagent import FastAgent
 
 # Create the application
-fast = FastAgent("FastAgent Example")
+fast = FastAgent("fast-agent example")
 
 
 # Define the agent
 @fast.agent(
-    "agent",
     instruction="You are a helpful AI Agent",
-    servers=["prompts"],  # , "imgetage", "hfspace"],
+    servers=["elicitation_account_server"],
 )
-async def main() -> None:
+async def main():
     # use the --model command line switch or agent arguments to change model
     async with fast.run() as agent:
-        await agent()
+        await agent.send('***CALL_TOOL create_user_account {"service_name": "fast-agent"}')
 
 
 if __name__ == "__main__":

mcp_agent/resources/examples/mcp/state-transfer/agent_two.py

@@ -3,7 +3,7 @@ import asyncio
 from mcp_agent.core.fastagent import FastAgent
 
 # Create the application
-fast = FastAgent("fast-agent agent_two (mcp host)")
+fast = FastAgent("fast-agent agent_two (mcp client)")
 
 
 # Define the agent

mcp_agent/resources/examples/mcp/state-transfer/fastagent.config.yaml

@@ -9,7 +9,7 @@ default_model: gpt-4.1
 
 # Logging and Console Configuration:
 logger:
-  # Switched off to avoid cluttering the console
+  # Switched off to avoid polluting the console
   progress_display: false
 
   # Show chat User/Assistant messages on the console

mcp_agent/resources/examples/mcp/state-transfer/fastagent.secrets.yaml.example

@@ -12,3 +12,4 @@ deepseek:
   api_key: <your-api-key-here>
 openrouter:
   api_key: <your-api-key-here>
+

mcp_agent/resources/examples/workflows/evaluator.py

@@ -40,7 +40,7 @@ fast = FastAgent("Evaluator-Optimizer")
     Summarize your evaluation as a structured response with:
     - Overall quality rating.
     - Specific feedback and areas for improvement.""",
-    model="gpt-4o",
+    model="gpt-4.1",
 )
 # Define the evaluator-optimizer workflow
 @fast.evaluator_optimizer(

mcp_agent/resources/examples/workflows/graded_report.md

@@ -0,0 +1,89 @@
+# Graded Report: "The Kittens Castle Adventure"
+
+## Proofreading Feedback
+
+### Spelling Errors
+1. "Adventuer" → "Adventure"
+2. "lil" → "little"
+3. "name" → "named"
+4. "threw" → "through"
+5. "mystirus" → "mysterious"
+6. "forrest" → "forest"
+7. "was" → "were"
+8. "an" → "and"
+9. "Suddenlee" → "Suddenly"
+10. "sawd" → "saw"
+11. "somthing" → "something"
+12. "chese" → "cheese"
+13. "windos" → "windows"
+14. "turrits" → "turrets"
+15. "tuch" → "touch"
+16. "clowds" → "clouds"
+17. "doars" → "doors"
+18. "enuff" → "enough"
+19. "elefant" → "elephant"
+20. "sed" → "said"
+21. "tale" → "tail"
+22. "poofy" → "puffy"
+23. "fowned" → "found"
+24. "meowed" → added missing period
+25. "smallist" → "smallest"
+26. "rond" → "round"
+27. "climed" → "climbed"
+28. "slip-slidin" → "slip-sliding"
+29. "smoth" → "smooth"
+30. "surfase" → "surface"
+31. "ful" → "full"
+32. "dangling" → added missing period
+33. "JINGEL" → "jingle"
+34. "paradyse" → "paradise"
+35. "figur" → "figure"
+36. "gaurd" → "guard"
+37. "sumthing" → "something"
+38. "mor" → "more"
+39. "hudeld" → "huddled"
+40. "togethar" → "together"
+41. "there" → "their"
+42. "happan" → "happen"
+43. "amazeing" → "amazing"
+
+### Grammar and Syntax Errors
+1. Inconsistent verb tenses throughout the story
+2. Improper use of articles (a/an)
+3. Missing punctuation
+4. Lack of subject-verb agreement
+5. Incorrect capitalization
+
+### Style and Formatting Recommendations
+1. Use standard capitalization for proper nouns
+2. Maintain consistent verb tense (past tense recommended)
+3. Use proper punctuation
+4. Avoid excessive use of exclamation points
+5. Use standard spelling for all words
+
+## Factuality and Logical Consistency
+- The story is a fictional narrative about three kittens, so traditional factual constraints do not strictly apply
+- The narrative maintains internal logical consistency
+- The cliffhanger ending leaves room for imagination
+
+## Style Adherence
+### APA Formatting Guidelines
+- Title should be centered and in title case
+- Use 12-point Times New Roman font (not applicable in markdown)
+- Double-spacing recommended (not applicable in markdown)
+- 1-inch margins (not applicable in markdown)
+
+### Recommendations for Improvement
+1. Proofread and correct all spelling errors
+2. Maintain consistent grammar and syntax
+3. Use standard English spelling
+4. Add more descriptive language
+5. Develop a more structured narrative arc
+
+## Overall Assessment
+**Writing Quality**: Needs Significant Improvement
+**Creativity**: Excellent
+**Potential**: High
+
+### Suggested Revision
+Revise the text to correct spelling, grammar, and syntax while preserving the original creative narrative and imaginative elements.

mcp_agent/resources/examples/workflows/orchestrator.py

@@ -13,7 +13,7 @@ fast = FastAgent("Orchestrator-Workers")
 @fast.agent(
     "author",
     instruction="""You are to role play a poorly skilled writer, 
-    who makes frequent grammar, punctuations and spelling errors. You enjoy
+    who makes frequent grammar, punctuation and spelling errors. You enjoy
     writing short stories, but the narrative doesn't always make sense""",
     servers=["filesystem"],
 )
@@ -25,7 +25,7 @@ fast = FastAgent("Orchestrator-Workers")
             the closest match to a user's request, make the appropriate tool calls, 
             and return the URI and CONTENTS of the closest match.""",
     servers=["fetch", "filesystem"],
-    model="gpt-4o",
+    model="gpt-4.1",
 )
 @fast.agent(
     name="writer",
@@ -40,19 +40,17 @@ fast = FastAgent("Orchestrator-Workers")
             Identify any awkward phrasing or structural issues that could improve clarity. 
             Provide detailed feedback on corrections.""",
     servers=["fetch"],
-    model="gpt-4o",
+    model="gpt-4.1",
 )
 # Define the orchestrator to coordinate the other agents
 @fast.orchestrator(
-    name="orchestrate",
-    agents=["finder", "writer", "proofreader"],
-    plan_type="full",
+    name="orchestrate", agents=["finder", "writer", "proofreader"], plan_type="full", model="sonnet"
 )
 async def main() -> None:
     async with fast.run() as agent:
-        await agent.author(
-            "write a 250 word short story about kittens discovering a castle, and save it to short_story.md"
-        )
+        # await agent.author(
+        #     "write a 250 word short story about kittens discovering a castle, and save it to short_story.md"
+        # )
 
         # The orchestrator can be used just like any other agent
         task = """Load the student's short story from short_story.md, 

mcp_agent/resources/examples/workflows/parallel.py

@@ -25,7 +25,6 @@ fast = FastAgent(
     instruction="""Verify the factual consistency within the story. Identify any contradictions,
     logical inconsistencies, or inaccuracies in the plot, character actions, or setting. 
     Highlight potential issues with reasoning or coherence.""",
-    model="gpt-4.1-mini",
 )
 @fast.agent(
     name="style_enforcer",
@@ -40,7 +39,6 @@ fast = FastAgent(
     into a structured report. Summarize key issues and categorize them by type. 
     Provide actionable recommendations for improving the story, 
     and give an overall grade based on the feedback.""",
-    model="o3-mini.low",
 )
 @fast.parallel(
     fan_out=["proofreader", "fact_checker", "style_enforcer"],

mcp_agent/resources/examples/workflows/short_story.md

@@ -0,0 +1,13 @@
+The Kittens Castle Adventuer
+
+One sunny day, three lil kittens name Whiskers, Socks, and Mittens was walkin threw a mystirus forrest. They hadnt never seen such a big forrest before! The trees was tall an spooky, an the ground was coverd in moss an stikks.
+
+Suddenlee, thru the trees, they sawd somthing HUUUUGE! It was a castell, but not just eny castell. This castell was made of sparkling chese an glittery windos. The turrits was so high they tuch the clowds, an the doars was big enuff for a elefant to walk threw!
+
+"Lookk!" sed Whiskers, his tale all poofy wit exsitement. "We fowned a castell!" Socks meowed loudly an jumped up an down. Mittens, who was the smallist kitten, just stared wit her big rond eyes.
+
+They climed up the cheesy walls, slip-slidin on the smoth surfase. Inside, they discoverd rooms ful of soft pillows an dangling strings an shiny things that went JINGEL when they tuch them. It was like a kitten paradyse!
+
+But then, a big shadowy figur apeared... was it the castell gaurd? Or sumthing mor mystirus? The kittens hudeld togethar, there lil hearts beating fast. What wud happan next in there amazeing adventuer?
+
+THE END??

mcp_agent/resources/examples/in_dev/agent_build.py

@@ -1,84 +0,0 @@
-"""
-This demonstrates creating multiple agents and an orchestrator to coordinate them.
-"""
-
-import asyncio
-
-from mcp_agent.core.fastagent import FastAgent
-from mcp_agent.llm.augmented_llm import RequestParams
-
-# Create the application
-fast = FastAgent("Agent Builder")
-
-
-@fast.agent(
-    "agent_expert",
-    instruction="""
-You design agent workflows, adhering to 'Building Effective Agents' (details to follow). 
-
-You provide concise specific guidance on design and composition. Prefer simple solutions, 
-and don't nest workflows more than one level deep. 
-
-Your objective is to produce a single '.py' agent in the style of the examples.
-
-Keep the application simple, concentrationg on defining Agent instructions, MCP Servers and
-appropriate use of Workflows. 
-
-The style of the program should be like the examples you have been shown, with a minimum of
-additional code, using only very simple Python where absolutely necessary.
-
-Concentrate on the quality of the Agent instructions and "warmup" prompts given to them.
-
-Keep requirements minimal: focus on building the prompts and the best workflow. The program
-is expected to be adjusted and refined later.
-
-If you are unsure about how to proceed, request input from the Human.
-
-Use the filesystem tools to save your completed fastagent program, in an appropriately named '.py' file. 
-
- """,
-    servers=["filesystem", "fetch"],
-    request_params=RequestParams(maxTokens=8192),
-)
-# Define worker agents
-@fast.agent(
-    "requirements_capture",
-    instruction="""
-You help the Human define their requirements for building Agent based systems.
-
-Keep questions short, simple and minimal, always offering to complete the questioning
-if desired. If uncertain about something, respond asking the 'agent_expert' for guidance.
-
-Do not interrogate the Human, prefer to move the process on, as more details can be requested later 
-if needed. Remind the Human of this.
- """,
-    human_input=True,
-)
-# Define the orchestrator to coordinate the other agents
-@fast.orchestrator(
-    name="agent_builder",
-    agents=["agent_expert", "requirements_capture"],
-    model="sonnet",
-    plan_type="iterative",
-    request_params=RequestParams(maxTokens=8192),
-    plan_iterations=5,
-)
-async def main() -> None:
-    async with fast.run() as agent:
-        CODER_WARMUP = """
-- Read this paper: https://www.anthropic.com/research/building-effective-agents" to understand how 
-and when to use different types of Agents and Workflow types.
-
-- Read this README https://raw.githubusercontent.com/evalstate/fast-agent/refs/heads/main/README.md file
-to see how to use "fast-agent" framework.
-
-- Look at the 'fastagent.config.yaml' file to see the available and configured MCP Servers.
-
-"""
-        await agent.agent_expert(CODER_WARMUP)
-
-        await agent.agent_builder()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

mcp_agent/resources/examples/in_dev/css-LICENSE.txt

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2021-2024 Paulo Cunha
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.