fast-agent-mcp 0.0.7__py3-none-any.whl → 0.0.9__py3-none-any.whl

mcp_agent/cli/commands/bootstrap.py

@@ -8,40 +8,45 @@ from rich.table import Table
 from rich.panel import Panel
 
 app = typer.Typer(
-    help="Create example applications and learn MCP Agent patterns",
-    no_args_is_help=True,
+    help="Create example applications",
+    no_args_is_help=False,  # Allow showing our custom help instead
 )
 console = Console()
 
 EXAMPLE_TYPES = {
-    "decorator": {
-        "description": "Decorator pattern example showing different agent composition approaches",
-        "details": """
-        The decorator example shows how to:
-        - Compose agents using the decorator pattern
-        - Add capabilities like optimization and routing
-        - Run agents in parallel
-        - Handle complex agent interactions
-        """,
+    "workflow": {
+        "description": "Example workflows, demonstrating each of the patterns in Anthropic's\n"
+        "'Building Effective Agents' paper. Some agents use the 'fetch'\n"
+        "and filesystem MCP Servers.",
         "files": [
-            "main.py",
-            "optimizer.py",
+            "chaining.py",
+            "evaluator.py",
+            "human_input.py",
             "orchestrator.py",
             "parallel.py",
             "router.py",
-            "tiny.py",
         ],
+        "create_subdir": False,
     },
     "researcher": {
-        "description": "Research agent example with evaluation optimization",
-        "details": """
-        The researcher example demonstrates:
-        - Building a research-focused agent
-        - Implementing evaluation strategies
-        - Optimizing agent responses
-        - Handling complex research tasks
-        """,
-        "files": ["main.py", "main-evalopt.py"],
+        "description": "Research agent example with additional evaluation/optimization\n"
+        "example. Uses Brave Search and Docker MCP Servers.\n"
+        "Creates examples in a 'researcher' subdirectory.",
+        "files": [
+            "researcher.py",
+            "researcher-eval.py",
+            "mcp_agent.secrets.yaml.example",
+        ],
+        "create_subdir": True,
+    },
+    "data-analysis": {
+        "description": "Data analysis agent examples that demonstrate working with\n"
+        "datasets, performing statistical analysis, and generating visualizations.\n"
+        "Creates examples in a 'data-analysis' subdirectory with mount-point for data.\n"
+        "Uses MCP 'roots' feature for mapping",
+        "files": ["analysis.py", "fastagent.config.yaml"],
+        "mount_point_files": ["WA_Fn-UseC_-HR-Employee-Attrition.csv"],
+        "create_subdir": True,
     },
 }
 
@@ -52,19 +57,35 @@ def copy_example_files(
     """Copy example files from resources to target directory."""
     created = []
 
-    # During development, use the source directory
+    # Determine if we should create a subdirectory for this example type
+    example_info = EXAMPLE_TYPES[example_type]
+    if example_info["create_subdir"]:
+        target_dir = target_dir / example_type
+        if not target_dir.exists():
+            target_dir.mkdir(parents=True)
+            console.print(f"Created subdirectory: {target_dir}")
+
+    # Create mount-point directory if needed
+    mount_point_files = example_info.get("mount_point_files", [])
+    if mount_point_files:
+        mount_point_dir = target_dir / "mount-point"
+        if not mount_point_dir.exists():
+            mount_point_dir.mkdir(parents=True)
+            console.print(f"Created mount-point directory: {mount_point_dir}")
+
+    # Use the resources directory from the package
     source_dir = (
         Path(__file__).parent.parent.parent
         / "resources"
         / "examples"
-        / ("decorator" if example_type == "decorator" else "mcp_researcher")
+        / ("workflows" if example_type == "workflow" else f"{example_type}")
     )
 
     if not source_dir.exists():
         console.print(f"[red]Error: Source directory not found: {source_dir}[/red]")
         return created
 
-    for filename in EXAMPLE_TYPES[example_type]["files"]:
+    for filename in example_info["files"]:
         source = source_dir / filename
         target = target_dir / filename
 
@@ -78,125 +99,143 @@ def copy_example_files(
                 continue
 
             shutil.copy2(source, target)
-            created.append(filename)
-            console.print(f"[green]Created[/green] {filename}")
+            created.append(str(target.relative_to(target_dir.parent)))
+            console.print(f"[green]Created[/green] {created[-1]}")
 
         except Exception as e:
             console.print(f"[red]Error copying {filename}: {str(e)}[/red]")
 
+    # Copy mount-point files if any
+    if mount_point_files:
+        source_mount_point = source_dir / "mount-point"
+        for filename in mount_point_files:
+            source = source_mount_point / filename
+            target = mount_point_dir / filename
+
+            try:
+                if not source.exists():
+                    console.print(f"[red]Error: Source file not found: {source}[/red]")
+                    continue
+
+                if target.exists() and not force:
+                    console.print(
+                        f"[yellow]Skipping[/yellow] mount-point/{filename} (already exists)"
+                    )
+                    continue
+
+                shutil.copy2(source, target)
+                created.append(f"{example_type}/mount-point/{filename}")
+                console.print(f"[green]Created[/green] mount-point/{filename}")
+
+            except Exception as e:
+                console.print(
+                    f"[red]Error copying mount-point/{filename}: {str(e)}[/red]"
+                )
+
     return created
 
 
-def show_examples_overview():
-    """Show an overview of available examples."""
-    console.print("\n[bold]MCP Agent Example Applications[/bold]")
-    console.print("Learn how to build effective agents through practical examples\n")
+def show_overview():
+    """Display an overview of available examples in a nicely formatted table."""
+    console.print("\n[bold cyan]FastAgent Example Applications[/bold cyan]")
+    console.print("Build agents and compose workflows through practical examples\n")
 
-    # Create a table for the examples
-    table = Table(title="Available Examples")
-    table.add_column("Example", style="green")
+    # Create a table for better organization
+    table = Table(
+        show_header=True, header_style="bold magenta", box=None, padding=(0, 2)
+    )
+    table.add_column("Example")
     table.add_column("Description")
-    table.add_column("Files", style="blue")
+    table.add_column("Files")
 
     for name, info in EXAMPLE_TYPES.items():
-        table.add_row(name, info["description"], "\n".join(info["files"]))
+        files_list = "\n".join(f"• {f}" for f in info["files"])
+        if "mount_point_files" in info:
+            files_list += "\n[blue]mount-point:[/blue]\n" + "\n".join(
+                f"• {f}" for f in info["mount_point_files"]
+            )
+        table.add_row(f"[green]{name}[/green]", info["description"], files_list)
 
     console.print(table)
 
-    # Show usage instructions
-    console.print("\n[bold]Usage:[/bold]")
-    console.print("1. Create a new example:")
-    console.print("   mcp-agent bootstrap create <example-name>")
-    console.print("\n2. Specify a directory:")
-    console.print(
-        "   mcp-agent bootstrap create <example-name> --directory ./my-project"
-    )
-    console.print("\n3. Force overwrite existing files:")
-    console.print("   mcp-agent bootstrap create <example-name> --force")
-
-    console.print("\n[bold]Examples:[/bold]")
-    console.print("   mcp-agent bootstrap create decorator")
-    console.print(
-        "   mcp-agent bootstrap create researcher --directory ./research-agent"
+    # Show usage instructions in a panel
+    usage_text = (
+        "[bold]Commands:[/bold]\n"
+        "  fastagent bootstrap workflow DIR      Create workflow examples in DIR\n"
+        "  fastagent bootstrap researcher DIR    Create researcher example in 'researcher' subdirectory\n"
+        "  fastagent bootstrap data-analysis DIR Create data analysis examples in 'data-analysis' subdirectory\n\n"
+        "[bold]Options:[/bold]\n"
+        "  --force            Overwrite existing files\n\n"
+        "[bold]Examples:[/bold]\n"
+        "  fastagent bootstrap workflow .              Create in current directory\n"
+        "  fastagent bootstrap researcher .            Create in researcher subdirectory\n"
+        "  fastagent bootstrap data-analysis . --force Force overwrite files in data-analysis subdirectory"
     )
+    console.print(Panel(usage_text, title="Usage", border_style="blue"))
 
 
-@app.callback(invoke_without_command=True)
-def main(ctx: typer.Context):
-    """Bootstrap example applications to learn MCP Agent patterns.
+@app.command()
+def workflow(
+    directory: Path = typer.Argument(
+        Path("."),
+        help="Directory where workflow examples will be created",
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Force overwrite existing files"
+    ),
+):
+    """Create workflow pattern examples."""
+    target_dir = directory.resolve()
+    if not target_dir.exists():
+        target_dir.mkdir(parents=True)
+        console.print(f"Created directory: {target_dir}")
 
-    Create working examples that demonstrate different agent patterns and capabilities.
-    Use these as starting points for your own agent applications.
-    """
-    if ctx.invoked_subcommand is None:
-        show_examples_overview()
+    created = copy_example_files("workflow", target_dir, force)
+    _show_completion_message("workflow", created)
 
 
 @app.command()
-def create(
-    example_type: str = typer.Argument(
-        None, help="Type of example to create (decorator or researcher)"
-    ),
-    directory: str = typer.Option(
-        ".", "--directory", "-d", help="Directory where example files will be created"
+def researcher(
+    directory: Path = typer.Argument(
+        Path("."),
+        help="Directory where researcher examples will be created (in 'researcher' subdirectory)",
     ),
     force: bool = typer.Option(
         False, "--force", "-f", help="Force overwrite existing files"
     ),
 ):
-    """Create a new example application.
-
-    This will create a set of example files based on the chosen type:
-
-    \b
-    - decorator: Decorator pattern example showing different agent composition approaches
-    - researcher: Research agent example with evaluation optimization
-    """
-    if not example_type:
-        show_examples_overview()
-        return
-
-    example_type = example_type.lower()
-    if example_type not in EXAMPLE_TYPES:
-        console.print(f"[red]Error:[/red] Unknown example type '{example_type}'")
-        console.print("\nAvailable types:")
-        for name in EXAMPLE_TYPES:
-            console.print(f"  - {name}")
-        raise typer.Exit(1)
-
-    target_dir = Path(directory).resolve()
+    """Create researcher pattern examples."""
+    target_dir = directory.resolve()
     if not target_dir.exists():
         target_dir.mkdir(parents=True)
         console.print(f"Created directory: {target_dir}")
 
-    # Show example details
-    console.print(f"\n[bold]Creating {example_type} example[/bold]")
-    console.print(
-        Panel(
-            EXAMPLE_TYPES[example_type]["details"].strip(),
-            title="About this example",
-            expand=False,
-        )
-    )
+    created = copy_example_files("researcher", target_dir, force)
+    _show_completion_message("researcher", created)
 
-    if not force:
-        # Check for existing files first
-        existing = []
-        for f in EXAMPLE_TYPES[example_type]["files"]:
-            if (target_dir / f).exists():
-                existing.append(f)
 
-        if existing:
-            console.print(
-                "\n[yellow]Warning:[/yellow] The following files already exist:"
-            )
-            for f in existing:
-                console.print(f"  - {f}")
-            console.print("\nUse --force to overwrite existing files")
-            raise typer.Exit(1)
+@app.command()
+def data_analysis(
+    directory: Path = typer.Argument(
+        Path("."),
+        help="Directory where data analysis examples will be created (creates 'data-analysis' subdirectory with mount-point)",
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Force overwrite existing files"
+    ),
+):
+    """Create data analysis examples with sample dataset."""
+    target_dir = directory.resolve()
+    if not target_dir.exists():
+        target_dir.mkdir(parents=True)
+        console.print(f"Created directory: {target_dir}")
 
-    created = copy_example_files(example_type, target_dir, force)
+    created = copy_example_files("data-analysis", target_dir, force)
+    _show_completion_message("data-analysis", created)
 
+
+def _show_completion_message(example_type: str, created: list[str]):
+    """Show completion message and next steps."""
     if created:
         console.print("\n[green]Setup completed successfully![/green]")
         console.print("\nCreated files:")
@@ -204,18 +243,41 @@ def create(
             console.print(f"  - {f}")
 
         console.print("\n[bold]Next Steps:[/bold]")
-        if example_type == "decorator":
-            console.print("1. Review main.py for the basic example")
-            console.print("2. Check other files for different composition patterns:")
-            console.print("   - optimizer.py: Add optimization capabilities")
-            console.print("   - router.py: Route requests to different agents")
+        if example_type == "workflow":
+            console.print("1. Review chaining.py for the basic workflow example")
+            console.print("2. Check other examples:")
             console.print("   - parallel.py: Run agents in parallel")
-            console.print("3. Run with: python main.py")
-        else:
-            console.print("1. Review main.py for the basic researcher example")
+            console.print("   - router.py: Route requests between agents")
+            console.print("   - evaluator.py: Add evaluation capabilities")
+            console.print("   - human_input.py: Incorporate human feedback")
+            console.print("3. Run an example with: uv run <example>.py")
+            console.print(
+                "4. Try a different model with --model=<model>, or update the agent config"
+            )
+
+        elif example_type == "researcher":
+            console.print(
+                "1. Set up the Brave MCP Server (get an API key from https://brave.com/search/api/)"
+            )
+            console.print("2. Try `uv run researcher.py` for the basic version")
+            console.print(
+                "3. Try `uv run researcher-eval.py` for the eval/optimize version"
+            )
+        elif example_type == "data-analysis":
+            console.print(
+                "1. Run uv `analysis.py` to perform data analysis and visualization"
+            )
+            console.print("2. The dataset is available in the mount-point directory:")
+            console.print("   - mount-point/WA_Fn-UseC_-HR-Employee-Attrition.csv")
             console.print(
-                "2. Try main-evalopt.py for the evaluation optimization version"
+                "On Windows platforms, please edit the fastagent.config.yaml and adjust the volume mount point."
             )
-            console.print("3. Run with: python main.py or python main-evalopt.py")
     else:
         console.print("\n[yellow]No files were created.[/yellow]")
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context):
+    """Create example applications and learn FastAgent patterns."""
+    if ctx.invoked_subcommand is None:
+        show_overview()

mcp_agent/cli/commands/setup.py

@@ -22,28 +22,31 @@ FASTAGENT_CONFIG_TEMPLATE = """
 default_model: sonnet
 
 # Logging and Console Configuration:
-logging:
+logger:
     # level: "debug" | "info" | "warning" | "error"
     # type: "none" | "console" | "file" | "http"
     # path: "/path/to/logfile.jsonl"
 
     
     # Switch the progress display on or off
-    # progress_display: true
+    progress_display: true
 
     # Show chat User/Assistant messages on the console
-    # show_chat: true
+    show_chat: true
     # Show tool calls on the console
-    # show_tools: true
+    show_tools: true
     # Truncate long tool responses on the console 
-    # truncate_tools: true
+    truncate_tools: true
 
 # MCP Servers
 mcp:
     servers:
         fetch:
             command: "uvx"
-            args: ["mcp-server-fetch"]    
+            args: ["mcp-server-fetch"]
+        filesystem:
+            command: "npx"
+            args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
 
 """
 
@@ -51,6 +54,8 @@ FASTAGENT_SECRETS_TEMPLATE = """
 # FastAgent Secrets Configuration
 # WARNING: Keep this file secure and never commit to version control
 
+# Alternatively set OPENAI_API_KEY and ANTHROPIC_API_KEY environment variables. Config file takes precedence.
+
 openai:
     api_key: <your-api-key-here>
 anthropic:
@@ -110,17 +115,14 @@ import asyncio
 from mcp_agent.core.fastagent import FastAgent
 
 # Create the application
-agent_app = FastAgent("FastAgent Example")
-# Uncomment the below to disable human input callback tool
-# agent_app.app._human_input_callback = None
+fast = FastAgent("FastAgent Example")
 
 
 # Define the agent
-@agent_app.agent(servers=["fetch"])
-# @agent_app.agent(servers=["fetch"])
+@fast.agent(servers=["fetch"])
 async def main():
-    # use the --model= command line switch to specify model
-    async with agent_app.run() as agent:
+    # use the --model command line switch or agent arguments to change model
+    async with fast.run() as agent:
         await agent()
 
 
@@ -217,11 +219,13 @@ def init(
 
     if created:
         console.print("\n[green]Setup completed successfully![/green]")
-        if "fastagent-secrets.yaml" in created:
+        if "fastagent.secrets.yaml" in created:
             console.print("\n[yellow]Important:[/yellow] Remember to:")
-            console.print("1. Add your API keys to fastagent-secrets.yaml")
             console.print(
-                "2. Keep fastagent-secrets.yaml secure and never commit it to version control"
+                "1. Add your API keys to fastagent-secrets.yaml or set OPENAI_API_KEY and ANTHROPIC_API_KEY environment variables"
+            )
+            console.print(
+                "2. Keep fastagent.secrets.yaml secure and never commit it to version control"
             )
         console.print("\nTo get started, run:")
         console.print("  uv run agent.py")

mcp_agent/core/exceptions.py

@@ -0,0 +1,47 @@
+"""
+Custom exceptions for the FastAgent framework.
+Enables user-friendly error handling for common issues.
+"""
+
+
+class FastAgentError(Exception):
+    """Base exception class for FastAgent errors"""
+
+    def __init__(self, message: str, details: str = ""):
+        self.message = message
+        self.details = details
+        super().__init__(f"{message}\n\n{details}" if details else message)
+
+
+class ServerConfigError(FastAgentError):
+    """Raised when there are issues with MCP server configuration
+    Example: Server name referenced in agent.servers[] but not defined in config
+    """
+
+    def __init__(self, message: str, details: str = ""):
+        super().__init__(message, details)
+
+
+class AgentConfigError(FastAgentError):
+    """Raised when there are issues with Agent or Workflow configuration
+    Example: Parallel fan-in references unknown agent
+    """
+
+    def __init__(self, message: str, details: str = ""):
+        super().__init__(message, details)
+
+
+class ProviderKeyError(FastAgentError):
+    """Raised when there are issues with LLM provider API keys
+    Example: OpenAI/Anthropic key not configured but model requires it
+    """
+
+    def __init__(self, message: str, details: str = ""):
+        super().__init__(message, details)
+
+
+class ServerInitializationError(FastAgentError):
+    """Raised when a server fails to initialize properly."""
+
+    def __init__(self, message: str, details: str = ""):
+        super().__init__(message, details)