fast-agent-mcp 0.2.39__py3-none-any.whl → 0.2.41__py3-none-any.whl

mcp_agent/cli/commands/go.py

@@ -1,16 +1,20 @@
 """Run an interactive agent directly from the command line."""
 
 import asyncio
+import shlex
 import sys
 from typing import Dict, List, Optional
 
 import typer
 
+from mcp_agent.cli.commands.server_helpers import add_servers_to_config, generate_server_name
 from mcp_agent.cli.commands.url_parser import generate_server_configs, parse_server_urls
 from mcp_agent.core.fastagent import FastAgent
+from mcp_agent.ui.console_display import ConsoleDisplay
 
 app = typer.Typer(
-    help="Run an interactive agent directly from the command line without creating an agent.py file"
+    help="Run an interactive agent directly from the command line without creating an agent.py file",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
 )
 
 
@@ -23,11 +27,11 @@ async def _run_agent(
     message: Optional[str] = None,
     prompt_file: Optional[str] = None,
     url_servers: Optional[Dict[str, Dict[str, str]]] = None,
+    stdio_servers: Optional[Dict[str, Dict[str, str]]] = None,
 ) -> None:
     """Async implementation to run an interactive agent."""
     from pathlib import Path
 
-    from mcp_agent.config import MCPServerSettings, MCPSettings
     from mcp_agent.mcp.prompts.prompt_load import load_prompt_multipart
 
     # Create the FastAgent instance
@@ -40,41 +44,69 @@ async def _run_agent(
 
     fast = FastAgent(**fast_kwargs)
 
-    # Add URL-based servers to the context configuration
-    if url_servers:
-        # Initialize the app to ensure context is ready
-        await fast.app.initialize()
+    # Add all dynamic servers to the configuration
+    await add_servers_to_config(fast, url_servers)
+    await add_servers_to_config(fast, stdio_servers)
 
-        # Initialize mcp settings if needed
-        if not hasattr(fast.app.context.config, "mcp"):
-            fast.app.context.config.mcp = MCPSettings()
+    # Check if we have multiple models (comma-delimited)
+    if model and "," in model:
+        # Parse multiple models
+        models = [m.strip() for m in model.split(",") if m.strip()]
 
-        # Initialize servers dictionary if needed
-        if (
-            not hasattr(fast.app.context.config.mcp, "servers")
-            or fast.app.context.config.mcp.servers is None
-        ):
-            fast.app.context.config.mcp.servers = {}
+        # Create an agent for each model
+        fan_out_agents = []
+        for i, model_name in enumerate(models):
+            agent_name = f"{model_name}"
 
-        # Add each URL server to the config
-        for server_name, server_config in url_servers.items():
-            server_settings = {"transport": server_config["transport"], "url": server_config["url"]}
+            # Define the agent with specified parameters
+            agent_kwargs = {"instruction": instruction, "name": agent_name}
+            if server_list:
+                agent_kwargs["servers"] = server_list
+            agent_kwargs["model"] = model_name
 
-            # Add headers if present in the server config
-            if "headers" in server_config:
-                server_settings["headers"] = server_config["headers"]
+            @fast.agent(**agent_kwargs)
+            async def model_agent():
+                pass
 
-            fast.app.context.config.mcp.servers[server_name] = MCPServerSettings(**server_settings)
+            fan_out_agents.append(agent_name)
 
-    # Define the agent with specified parameters
-    agent_kwargs = {"instruction": instruction}
-    if server_list:
-        agent_kwargs["servers"] = server_list
-    if model:
-        agent_kwargs["model"] = model
+        # Create a silent fan-in agent for cleaner output
+        @fast.agent(
+            name="aggregate",
+            model="silent",
+            instruction="You are a silent agent that combines outputs from parallel agents.",
+        )
+        async def fan_in_agent():
+            pass
 
-    # Handle prompt file and message options
-    if message or prompt_file:
+        # Create a parallel agent with silent fan_in
+        @fast.parallel(
+            name="parallel",
+            fan_out=fan_out_agents,
+            fan_in="aggregate",
+            include_request=True,
+        )
+        async def cli_agent():
+            async with fast.run() as agent:
+                if message:
+                    await agent.parallel.send(message)
+                    display = ConsoleDisplay(config=None)
+                    display.show_parallel_results(agent.parallel)
+                elif prompt_file:
+                    prompt = load_prompt_multipart(Path(prompt_file))
+                    await agent.parallel.generate(prompt)
+                    display = ConsoleDisplay(config=None)
+                    display.show_parallel_results(agent.parallel)
+                else:
+                    await agent.interactive(agent_name="parallel", pretty_print_parallel=True)
+    else:
+        # Single model - use original behavior
+        # Define the agent with specified parameters
+        agent_kwargs = {"instruction": instruction}
+        if server_list:
+            agent_kwargs["servers"] = server_list
+        if model:
+            agent_kwargs["model"] = model
 
         @fast.agent(**agent_kwargs)
         async def cli_agent():
@@ -88,12 +120,8 @@ async def _run_agent(
                     response = await agent.default.generate(prompt)
                     # Print the response text and exit
                     print(response.last_text())
-    else:
-        # Standard interactive mode
-        @fast.agent(**agent_kwargs)
-        async def cli_agent():
-            async with fast.run() as agent:
-                await agent.interactive()
+                else:
+                    await agent.interactive()
 
     # Run the agent
     await cli_agent()
@@ -109,6 +137,7 @@ def run_async_agent(
     model: Optional[str] = None,
     message: Optional[str] = None,
     prompt_file: Optional[str] = None,
+    stdio_commands: Optional[List[str]] = None,
 ):
     """Run the async agent function with proper loop handling."""
     server_list = servers.split(",") if servers else None
@@ -129,6 +158,60 @@ def run_async_agent(
             print(f"Error parsing URLs: {e}")
             return
 
+    # Generate STDIO server configurations if provided
+    stdio_servers = None
+
+    if stdio_commands:
+        stdio_servers = {}
+        for i, stdio_cmd in enumerate(stdio_commands):
+            # Parse the stdio command string
+            try:
+                parsed_command = shlex.split(stdio_cmd)
+                if not parsed_command:
+                    print(f"Error: Empty stdio command: {stdio_cmd}")
+                    continue
+
+                command = parsed_command[0]
+                initial_args = parsed_command[1:] if len(parsed_command) > 1 else []
+
+                # Generate a server name from the command
+                if initial_args:
+                    # Try to extract a meaningful name from the args
+                    for arg in initial_args:
+                        if arg.endswith(".py") or arg.endswith(".js") or arg.endswith(".ts"):
+                            base_name = generate_server_name(arg)
+                            break
+                    else:
+                        # Fallback to command name
+                        base_name = generate_server_name(command)
+                else:
+                    base_name = generate_server_name(command)
+
+                # Ensure unique server names when multiple servers
+                server_name = base_name
+                if len(stdio_commands) > 1:
+                    server_name = f"{base_name}_{i + 1}"
+
+                # Build the complete args list
+                stdio_command_args = initial_args.copy()
+
+                # Add this server to the configuration
+                stdio_servers[server_name] = {
+                    "transport": "stdio",
+                    "command": command,
+                    "args": stdio_command_args,
+                }
+
+                # Add STDIO server to the server list
+                if not server_list:
+                    server_list = [server_name]
+                else:
+                    server_list.append(server_name)
+
+            except ValueError as e:
+                print(f"Error parsing stdio command '{stdio_cmd}': {e}")
+                continue
+
     # Check if we're already in an event loop
     try:
         loop = asyncio.get_event_loop()
@@ -153,6 +236,7 @@ def run_async_agent(
                 message=message,
                 prompt_file=prompt_file,
                 url_servers=url_servers,
+                stdio_servers=stdio_servers,
             )
         )
     finally:
@@ -171,7 +255,7 @@ def run_async_agent(
             pass
 
 
-@app.callback(invoke_without_command=True)
+@app.callback(invoke_without_command=True, no_args_is_help=False)
 def go(
     ctx: typer.Context,
     name: str = typer.Option("FastAgent CLI", "--name", help="Name for the agent"),
@@ -191,7 +275,7 @@ def go(
         None, "--auth", help="Bearer token for authorization with URL-based servers"
     ),
     model: Optional[str] = typer.Option(
-        None, "--model", help="Override the default model (e.g., haiku, sonnet, gpt-4)"
+        None, "--model", "--models", help="Override the default model (e.g., haiku, sonnet, gpt-4)"
     ),
     message: Optional[str] = typer.Option(
         None, "--message", "-m", help="Message to send to the agent (skips interactive mode)"
@@ -199,6 +283,15 @@ def go(
     prompt_file: Optional[str] = typer.Option(
         None, "--prompt-file", "-p", help="Path to a prompt file to use (either text or JSON)"
     ),
+    npx: Optional[str] = typer.Option(
+        None, "--npx", help="NPX package and args to run as MCP server (quoted)"
+    ),
+    uvx: Optional[str] = typer.Option(
+        None, "--uvx", help="UVX package and args to run as MCP server (quoted)"
+    ),
+    stdio: Optional[str] = typer.Option(
+        None, "--stdio", help="Command to run as STDIO MCP server (quoted)"
+    ),
 ) -> None:
     """
     Run an interactive agent directly from the command line.
@@ -209,6 +302,10 @@ def go(
         fast-agent go --prompt-file=my-prompt.txt --model=haiku
         fast-agent go --url=http://localhost:8001/mcp,http://api.example.com/sse
         fast-agent go --url=https://api.example.com/mcp --auth=YOUR_API_TOKEN
+        fast-agent go --npx "@modelcontextprotocol/server-filesystem /path/to/data"
+        fast-agent go --uvx "mcp-server-fetch --verbose"
+        fast-agent go --stdio "python my_server.py --debug"
+        fast-agent go --stdio "uv run server.py --config=settings.json"
 
     This will start an interactive session with the agent, using the specified model
     and instruction. It will use the default configuration from fastagent.config.yaml
@@ -222,7 +319,22 @@ def go(
         --auth                Bearer token for authorization with URL-based servers
         --message, -m         Send a single message and exit
         --prompt-file, -p     Use a prompt file instead of interactive mode
+        --npx                 NPX package and args to run as MCP server (quoted)
+        --uvx                 UVX package and args to run as MCP server (quoted)
+        --stdio               Command to run as STDIO MCP server (quoted)
     """
+    # Collect all stdio commands from convenience options
+    stdio_commands = []
+
+    if npx:
+        stdio_commands.append(f"npx {npx}")
+
+    if uvx:
+        stdio_commands.append(f"uvx {uvx}")
+
+    if stdio:
+        stdio_commands.append(stdio)
+
     run_async_agent(
         name=name,
         instruction=instruction,
@@ -233,4 +345,5 @@ def go(
         model=model,
         message=message,
         prompt_file=prompt_file,
+        stdio_commands=stdio_commands,
     )

mcp_agent/cli/commands/quickstart.py

@@ -383,12 +383,16 @@ def _show_completion_message(example_type: str, created: list[str]) -> None:
                 "On Windows platforms, please edit the fastagent.config.yaml and adjust the volume mount point."
             )
         elif example_type == "state-transfer":
-            console.print("Check https://fast-agent.ai for quick start walkthroughs")
+            console.print(
+                "Check [cyan][link=https://fast-agent.ai]fast-agent.ai[/link][/cyan] for quick start walkthroughs"
+            )
         elif example_type == "elicitations":
-            console.print("1. Try the forms demo: uv run forms_demo.py")
-            console.print("2. For the AI assistant example, configure your API keys first")
+            console.print("1. Go to the `elicitations` subdirectory (cd elicitations)")
+            console.print("2. Try the forms demo: uv run forms_demo.py")
             console.print("3. Run the game character creator: uv run game_character.py")
-            console.print("4. Check the README.md for detailed information about elicitations")
+            console.print(
+                "Check [cyan][link=https://fast-agent.ai/mcp/elicitations/]https://fast-agent.ai/mcp/elicitations/[/link][/cyan] for more details"
+            )
     else:
         console.print("\n[yellow]No files were created.[/yellow]")
 

mcp_agent/cli/commands/server_helpers.py

@@ -0,0 +1,106 @@
+"""Helper functions for server configuration and naming."""
+
+from typing import Any, Dict
+
+
+def generate_server_name(identifier: str) -> str:
+    """Generate a clean server name from various identifiers.
+
+    Args:
+        identifier: Package name, file path, or other identifier
+
+    Returns:
+        Clean server name with only alphanumeric and underscore characters
+
+    Examples:
+        >>> generate_server_name("@modelcontextprotocol/server-filesystem")
+        'server_filesystem'
+        >>> generate_server_name("./src/my-server.py")
+        'src_my_server'
+        >>> generate_server_name("my-mcp-server")
+        'my_mcp_server'
+    """
+
+    # Remove leading ./ if present
+    if identifier.startswith("./"):
+        identifier = identifier[2:]
+
+    # Handle npm package names with org prefix (only if no file extension)
+    has_file_ext = any(identifier.endswith(ext) for ext in [".py", ".js", ".ts"])
+    if "/" in identifier and not has_file_ext:
+        # This is likely an npm package, take the part after the last slash
+        identifier = identifier.split("/")[-1]
+
+    # Remove file extension for common script files
+    for ext in [".py", ".js", ".ts"]:
+        if identifier.endswith(ext):
+            identifier = identifier[: -len(ext)]
+            break
+
+    # Replace special characters with underscores
+    # Remove @ prefix if present
+    identifier = identifier.lstrip("@")
+
+    # Replace non-alphanumeric characters with underscores
+    server_name = ""
+    for char in identifier:
+        if char.isalnum():
+            server_name += char
+        else:
+            server_name += "_"
+
+    # Clean up multiple underscores
+    while "__" in server_name:
+        server_name = server_name.replace("__", "_")
+
+    # Remove leading/trailing underscores
+    server_name = server_name.strip("_")
+
+    return server_name
+
+
+async def add_servers_to_config(fast_app: Any, servers: Dict[str, Dict[str, Any]]) -> None:
+    """Add server configurations to the FastAgent app config.
+
+    This function handles the repetitive initialization and configuration
+    of MCP servers, ensuring the app is initialized and the config
+    structure exists before adding servers.
+
+    Args:
+        fast_app: The FastAgent instance
+        servers: Dictionary of server configurations
+    """
+    if not servers:
+        return
+
+    from mcp_agent.config import MCPServerSettings, MCPSettings
+
+    # Initialize the app to ensure context is ready
+    await fast_app.app.initialize()
+
+    # Initialize mcp settings if needed
+    if not hasattr(fast_app.app.context.config, "mcp"):
+        fast_app.app.context.config.mcp = MCPSettings()
+
+    # Initialize servers dictionary if needed
+    if (
+        not hasattr(fast_app.app.context.config.mcp, "servers")
+        or fast_app.app.context.config.mcp.servers is None
+    ):
+        fast_app.app.context.config.mcp.servers = {}
+
+    # Add each server to the config
+    for server_name, server_config in servers.items():
+        # Build server settings based on transport type
+        server_settings = {"transport": server_config["transport"]}
+
+        # Add transport-specific settings
+        if server_config["transport"] == "stdio":
+            server_settings["command"] = server_config["command"]
+            server_settings["args"] = server_config["args"]
+        elif server_config["transport"] in ["http", "sse"]:
+            server_settings["url"] = server_config["url"]
+            if "headers" in server_config:
+                server_settings["headers"] = server_config["headers"]
+
+        fast_app.app.context.config.mcp.servers[server_name] = MCPServerSettings(**server_settings)

mcp_agent/cli/constants.py

@@ -0,0 +1,25 @@
+"""Shared constants for CLI routing and commands."""
+
+# Options that should automatically route to the 'go' command
+GO_SPECIFIC_OPTIONS = {
+    "--npx",
+    "--uvx",
+    "--stdio",
+    "--url",
+    "--model",
+    "--models",
+    "--instruction",
+    "-i",
+    "--message",
+    "-m",
+    "--prompt-file",
+    "-p",
+    "--servers",
+    "--auth",
+    "--name",
+    "--config-path",
+    "-c",
+}
+
+# Known subcommands that should not trigger auto-routing
+KNOWN_SUBCOMMANDS = {"go", "setup", "check", "bootstrap", "quickstart", "--help", "-h", "--version"}

mcp_agent/cli/main.py

@@ -48,7 +48,7 @@ def show_welcome() -> None:
     console.print(table)
 
     console.print(
-        "\n[italic]get started with:[/italic] [bold][cyan]fast-agent[/cyan][/bold] [green]setup[/green]"
+        "\n[italic]get started with:[/italic] [bold][cyan]fast-agent[/cyan][/bold] [green]setup[/green]. visit [cyan][link=https://fast-agent.ai]fast-agent.ai[/link][/cyan] for more information."
     )
 
 

mcp_agent/config.py

@@ -6,7 +6,7 @@ for the application configuration.
 import os
 import re
 from pathlib import Path
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional, Tuple
 
 from pydantic import BaseModel, ConfigDict, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -175,6 +175,17 @@ class GoogleSettings(BaseModel):
     model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
 
 
+class XAISettings(BaseModel):
+    """
+    Settings for using xAI Grok models in the fast-agent application.
+    """
+
+    api_key: str | None = None
+    base_url: str | None = "https://api.x.ai/v1"
+
+    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+
+
 class GenericSettings(BaseModel):
     """
     Settings for using OpenAI models in the fast-agent application.
@@ -296,6 +307,57 @@ class LoggerSettings(BaseModel):
     """Enable markup in console output. Disable for outputs that may conflict with rich console formatting"""
 
 
+def find_fastagent_config_files(start_path: Path) -> Tuple[Optional[Path], Optional[Path]]:
+    """
+    Find FastAgent configuration files with standardized behavior.
+
+    Returns:
+        Tuple of (config_path, secrets_path) where either can be None if not found.
+
+    Strategy:
+    1. Find config file recursively from start_path upward
+    2. Prefer secrets file in same directory as config file
+    3. If no secrets file next to config, search recursively from start_path
+    """
+    config_path = None
+    secrets_path = None
+
+    # First, find the config file with recursive search
+    current = start_path.resolve()
+    while current != current.parent:
+        potential_config = current / "fastagent.config.yaml"
+        if potential_config.exists():
+            config_path = potential_config
+            break
+        current = current.parent
+
+    # If config file found, prefer secrets file in the same directory
+    if config_path:
+        potential_secrets = config_path.parent / "fastagent.secrets.yaml"
+        if potential_secrets.exists():
+            secrets_path = potential_secrets
+        else:
+            # If no secrets file next to config, do recursive search from start
+            current = start_path.resolve()
+            while current != current.parent:
+                potential_secrets = current / "fastagent.secrets.yaml"
+                if potential_secrets.exists():
+                    secrets_path = potential_secrets
+                    break
+                current = current.parent
+    else:
+        # No config file found, just search for secrets file
+        current = start_path.resolve()
+        while current != current.parent:
+            potential_secrets = current / "fastagent.secrets.yaml"
+            if potential_secrets.exists():
+                secrets_path = potential_secrets
+                break
+            current = current.parent
+
+    return config_path, secrets_path
+
+
 class Settings(BaseSettings):
     """
     Settings class for the fast-agent application.
@@ -339,6 +401,9 @@ class Settings(BaseSettings):
     google: GoogleSettings | None = None
     """Settings for using DeepSeek models in the fast-agent application"""
 
+    xai: XAISettings | None = None
+    """Settings for using xAI Grok models in the fast-agent application"""
+
     openrouter: OpenRouterSettings | None = None
     """Settings for using OpenRouter models in the fast-agent application"""
 
@@ -445,51 +510,36 @@ def get_settings(config_path: str | None = None) -> Settings:
             resolved_path = Path.cwd() / config_file.name
             if resolved_path.exists():
                 config_file = resolved_path
+
+        # When config path is explicitly provided, find secrets using standardized logic
+        secrets_file = None
+        if config_file.exists():
+            _, secrets_file = find_fastagent_config_files(config_file.parent)
     else:
-        config_file = Settings.find_config()
+        # Use standardized discovery for both config and secrets
+        config_file, secrets_file = find_fastagent_config_files(Path.cwd())
 
     merged_settings = {}
 
-    if config_file:
-        if not config_file.exists():
-            print(f"Warning: Specified config file does not exist: {config_file}")
-        else:
-            import yaml  # pylint: disable=C0415
-
-            # Load main config
-            with open(config_file, "r", encoding="utf-8") as f:
-                yaml_settings = yaml.safe_load(f) or {}
-                # Resolve environment variables in the loaded YAML settings
-                resolved_yaml_settings = resolve_env_vars(yaml_settings)
-                merged_settings = resolved_yaml_settings
-            # Look for secrets files recursively up the directory tree
-            # but stop after finding the first one
-            current_dir = config_file.parent
-            found_secrets = False
-            # Start with the absolute path of the config file\'s directory
-            current_dir = config_file.parent.resolve()
-
-            while current_dir != current_dir.parent and not found_secrets:
-                for secrets_filename in [
-                    "fastagent.secrets.yaml",
-                ]:
-                    secrets_file = current_dir / secrets_filename
-                    if secrets_file.exists():
-                        with open(secrets_file, "r", encoding="utf-8") as f:
-                            yaml_secrets = yaml.safe_load(f) or {}
-                            # Resolve environment variables in the loaded secrets YAML
-                            resolved_secrets_yaml = resolve_env_vars(yaml_secrets)
-                            merged_settings = deep_merge(merged_settings, resolved_secrets_yaml)
-                            found_secrets = True
-                            break
-                if not found_secrets:
-                    # Get the absolute path of the parent directory
-                    current_dir = current_dir.parent.resolve()
-
-            _settings = Settings(**merged_settings)
-            return _settings
-    else:
-        pass
-
-    _settings = Settings()
+    import yaml  # pylint: disable=C0415
+
+    # Load main config if it exists
+    if config_file and config_file.exists():
+        with open(config_file, "r", encoding="utf-8") as f:
+            yaml_settings = yaml.safe_load(f) or {}
+            # Resolve environment variables in the loaded YAML settings
+            resolved_yaml_settings = resolve_env_vars(yaml_settings)
+            merged_settings = resolved_yaml_settings
+    elif config_file and not config_file.exists():
+        print(f"Warning: Specified config file does not exist: {config_file}")
+
+    # Load secrets file if found (regardless of whether config file exists)
+    if secrets_file and secrets_file.exists():
+        with open(secrets_file, "r", encoding="utf-8") as f:
+            yaml_secrets = yaml.safe_load(f) or {}
+            # Resolve environment variables in the loaded secrets YAML
+            resolved_secrets_yaml = resolve_env_vars(yaml_secrets)
+            merged_settings = deep_merge(merged_settings, resolved_secrets_yaml)
+
+    _settings = Settings(**merged_settings)
     return _settings