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

fast_agent/cli/commands/serve.py

@@ -0,0 +1,143 @@
+"""Run FastAgent as an MCP server from the command line."""
+
+from enum import Enum
+from pathlib import Path
+
+import typer
+
+from fast_agent.cli.commands.go import (
+    collect_stdio_commands,
+    resolve_instruction_option,
+    run_async_agent,
+)
+
+
+class ServeTransport(str, Enum):
+    HTTP = "http"
+    SSE = "sse"
+    STDIO = "stdio"
+    ACP = "acp"
+
+
+class InstanceScope(str, Enum):
+    SHARED = "shared"
+    CONNECTION = "connection"
+    REQUEST = "request"
+
+
+app = typer.Typer(
+    help="Run FastAgent as an MCP server without writing an agent.py file",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+
+
+@app.callback(invoke_without_command=True, no_args_is_help=False)
+def serve(
+    ctx: typer.Context,
+    name: str = typer.Option("fast-agent", "--name", help="Name for the MCP server"),
+    instruction: str | None = typer.Option(
+        None, "--instruction", "-i", help="Path to file or URL containing instruction for the agent"
+    ),
+    config_path: str | None = typer.Option(None, "--config-path", "-c", help="Path to config file"),
+    servers: str | None = typer.Option(
+        None, "--servers", help="Comma-separated list of server names to enable from config"
+    ),
+    urls: str | None = typer.Option(
+        None, "--url", help="Comma-separated list of HTTP/SSE URLs to connect to"
+    ),
+    auth: str | None = typer.Option(
+        None, "--auth", help="Bearer token for authorization with URL-based servers"
+    ),
+    model: str | None = typer.Option(
+        None, "--model", "--models", help="Override the default model (e.g., haiku, sonnet, gpt-4)"
+    ),
+    skills_dir: Path | None = typer.Option(
+        None,
+        "--skills-dir",
+        "--skills",
+        help="Override the default skills directory",
+    ),
+    npx: str | None = typer.Option(
+        None, "--npx", help="NPX package and args to run as MCP server (quoted)"
+    ),
+    uvx: str | None = typer.Option(
+        None, "--uvx", help="UVX package and args to run as MCP server (quoted)"
+    ),
+    stdio: str | None = typer.Option(
+        None, "--stdio", help="Command to run as STDIO MCP server (quoted)"
+    ),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        "-d",
+        help="Description used for the exposed send tool (use {agent} to reference the agent name)",
+    ),
+    transport: ServeTransport = typer.Option(
+        ServeTransport.HTTP,
+        "--transport",
+        help="Transport protocol to expose (http, sse, stdio, acp)",
+    ),
+    host: str = typer.Option(
+        "0.0.0.0",
+        "--host",
+        help="Host address to bind when using HTTP or SSE transport",
+    ),
+    port: int = typer.Option(
+        8000,
+        "--port",
+        help="Port to use when running as a server with HTTP or SSE transport",
+    ),
+    shell: bool = typer.Option(
+        False,
+        "--shell",
+        "-x",
+        help="Enable a local shell runtime and expose the execute tool (bash or pwsh).",
+    ),
+    instance_scope: InstanceScope = typer.Option(
+        InstanceScope.SHARED,
+        "--instance-scope",
+        help="Control how MCP clients receive isolated agent instances (shared, connection, request)",
+    ),
+    no_permissions: bool = typer.Option(
+        False,
+        "--no-permissions",
+        help="Disable tool permission requests (allow all tool executions without asking) - ACP only",
+    ),
+) -> None:
+    """
+    Run FastAgent as an MCP server.
+
+    Examples:
+        fast-agent serve --model=haiku --instruction=./instruction.md --transport=http --port=8000
+        fast-agent serve --url=http://localhost:8001/mcp --auth=YOUR_API_TOKEN
+        fast-agent serve --stdio "python my_server.py --debug"
+        fast-agent serve --npx "@modelcontextprotocol/server-filesystem /path/to/data"
+        fast-agent serve --description "Interact with the {agent} assistant"
+    """
+    stdio_commands = collect_stdio_commands(npx, uvx, stdio)
+    shell_enabled = shell
+
+    resolved_instruction, agent_name = resolve_instruction_option(instruction)
+
+    run_async_agent(
+        name=name,
+        instruction=resolved_instruction,
+        config_path=config_path,
+        servers=servers,
+        urls=urls,
+        auth=auth,
+        model=model,
+        message=None,
+        prompt_file=None,
+        stdio_commands=stdio_commands,
+        agent_name=agent_name,
+        skills_directory=skills_dir,
+        shell_enabled=shell_enabled,
+        mode="serve",
+        transport=transport.value,
+        host=host,
+        port=port,
+        tool_description=description,
+        instance_scope=instance_scope.value,
+        permissions_enabled=not no_permissions,
+    )

fast_agent/cli/commands/server_helpers.py

@@ -0,0 +1,114 @@
+"""Helper functions for server configuration and naming."""
+
+from typing import Any
+
+
+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 fast_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 (and keep the runtime registry in sync)
+    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"]
+
+        mcp_server = MCPServerSettings(**server_settings)
+        # Update config model
+        fast_app.app.context.config.mcp.servers[server_name] = mcp_server
+        # Ensure ServerRegistry sees dynamic additions even when no config file exists
+        if (
+            hasattr(fast_app.app.context, "server_registry")
+            and fast_app.app.context.server_registry is not None
+        ):
+            fast_app.app.context.server_registry.registry[server_name] = mcp_server

fast_agent/cli/commands/setup.py

@@ -0,0 +1,174 @@
+from pathlib import Path
+
+import typer
+from rich.prompt import Confirm
+
+from fast_agent.ui.console import console as shared_console
+
+app = typer.Typer()
+console = shared_console
+
+
+def load_template_text(filename: str) -> str:
+    """Load template text from packaged resources only.
+
+    Special-case: when requesting 'fastagent.secrets.yaml', read the
+    'fastagent.secrets.yaml.example' template from resources, but still
+    return its contents so we can write out the real secrets file name
+    in the destination project.
+    """
+    from importlib.resources import files
+
+    # Map requested filenames to resource templates
+    if filename == "fastagent.secrets.yaml":
+        res_name = "fastagent.secrets.yaml.example"
+    elif filename == "pyproject.toml":
+        res_name = "pyproject.toml.tmpl"
+    else:
+        res_name = filename
+    resource_path = files("fast_agent").joinpath("resources").joinpath("setup").joinpath(res_name)
+    if resource_path.is_file():
+        return resource_path.read_text()
+
+    raise RuntimeError(
+        f"Setup template missing: '{filename}'.\n"
+        f"Expected packaged resource at: {resource_path}.\n"
+        "This indicates a packaging issue. Please rebuild/reinstall fast-agent."
+    )
+
+
+# (No embedded template defaults; templates are the single source of truth.)
+
+
+def find_gitignore(path: Path) -> bool:
+    """Check if a .gitignore file exists in this directory or any parent."""
+    current = path
+    while current != current.parent:  # Stop at root directory
+        if (current / ".gitignore").exists():
+            return True
+        current = current.parent
+    return False
+
+
+def create_file(path: Path, content: str, force: bool = False) -> bool:
+    """Create a file with given content if it doesn't exist or force is True."""
+    if path.exists() and not force:
+        should_overwrite = Confirm.ask(
+            f"[yellow]Warning:[/yellow] {path} already exists. Overwrite?",
+            default=False,
+        )
+        if not should_overwrite:
+            console.print(f"Skipping {path}")
+            return False
+
+    path.write_text(content.strip() + "\n")
+    console.print(f"[green]Created[/green] {path}")
+    return True
+
+
+@app.callback(invoke_without_command=True)
+def init(
+    config_dir: str = typer.Option(
+        ".",
+        "--config-dir",
+        "-c",
+        help="Directory where configuration files will be created",
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Force overwrite existing files"),
+) -> None:
+    """Initialize a new FastAgent project with configuration files and example agent."""
+
+    config_path = Path(config_dir).resolve()
+    if not config_path.exists():
+        should_create = Confirm.ask(
+            f"Directory {config_path} does not exist. Create it?", default=True
+        )
+        if should_create:
+            config_path.mkdir(parents=True)
+        else:
+            raise typer.Abort()
+
+    # Check for existing .gitignore
+    needs_gitignore = not find_gitignore(config_path)
+
+    console.print("\n[bold]fast-agent setup[/bold]\n")
+    console.print("This will create the following files:")
+    console.print(f"  - {config_path}/fastagent.config.yaml")
+    console.print(f"  - {config_path}/fastagent.secrets.yaml")
+    console.print(f"  - {config_path}/agent.py")
+    console.print(f"  - {config_path}/pyproject.toml")
+    if needs_gitignore:
+        console.print(f"  - {config_path}/.gitignore")
+
+    if not Confirm.ask("\nContinue?", default=True):
+        raise typer.Abort()
+
+    # Create configuration files
+    created = []
+    if create_file(
+        config_path / "fastagent.config.yaml", load_template_text("fastagent.config.yaml"), force
+    ):
+        created.append("fastagent.yaml")
+
+    if create_file(
+        config_path / "fastagent.secrets.yaml", load_template_text("fastagent.secrets.yaml"), force
+    ):
+        created.append("fastagent.secrets.yaml")
+
+    if create_file(config_path / "agent.py", load_template_text("agent.py"), force):
+        created.append("agent.py")
+
+    # Create a minimal pyproject.toml so `uv run` installs dependencies
+    def _render_pyproject(template_text: str) -> str:
+        # Determine Python requirement from installed fast-agent-mcp metadata, fall back if missing
+        py_req = ">=3.13.7"
+        try:
+            from importlib.metadata import metadata
+
+            md = metadata("fast-agent-mcp")
+            req = md.get("Requires-Python")
+            if req:
+                py_req = req
+        except Exception:
+            pass
+
+        # Always use latest fast-agent-mcp (no version pin)
+        fast_agent_dep = '"fast-agent-mcp"'
+
+        return template_text.replace("{{python_requires}}", py_req).replace(
+            "{{fast_agent_dep}}", fast_agent_dep
+        )
+
+    pyproject_template = load_template_text("pyproject.toml")
+    pyproject_text = _render_pyproject(pyproject_template)
+    if create_file(config_path / "pyproject.toml", pyproject_text, force):
+        created.append("pyproject.toml")
+
+    # Only create .gitignore if none exists in parent directories
+    if needs_gitignore and create_file(
+        config_path / ".gitignore", load_template_text(".gitignore"), force
+    ):
+        created.append(".gitignore")
+
+    if created:
+        console.print("\n[green]Setup completed successfully![/green]")
+        if not needs_gitignore:
+            console.print(
+                "[yellow]Note:[/yellow] Found an existing .gitignore in this or a parent directory. "
+                "Ensure it ignores 'fastagent.secrets.yaml' to avoid committing secrets."
+            )
+        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, or set environment variables. Use [cyan]fast-agent check[/cyan] to verify."
+            )
+            console.print(
+                "2. Keep fastagent.secrets.yaml secure and never commit it to version control"
+            )
+            console.print(
+                "3. Update fastagent.config.yaml to set a default model (currently system default is 'gpt-5-mini.low')"
+            )
+        console.print("\nTo get started, run:")
+        console.print("  uv run agent.py")
+    else:
+        console.print("\n[yellow]No files were created or modified.[/yellow]")

fast_agent/cli/commands/url_parser.py

@@ -0,0 +1,190 @@
+"""
+URL parsing utility for the fast-agent CLI.
+Provides functions to parse URLs and determine MCP server configurations.
+"""
+
+import hashlib
+import re
+from typing import Literal
+from urllib.parse import urlparse
+
+from fast_agent.mcp.hf_auth import add_hf_auth_header
+
+
+def parse_server_url(
+    url: str,
+) -> tuple[str, Literal["http", "sse"], str]:
+    """
+    Parse a server URL and determine the transport type and server name.
+
+    Args:
+        url: The URL to parse
+
+    Returns:
+        Tuple containing:
+        - server_name: A generated name for the server
+        - transport_type: Either "http" or "sse" based on URL
+        - url: The parsed and validated URL
+
+    Raises:
+        ValueError: If the URL is invalid or unsupported
+    """
+    # Basic URL validation
+    if not url:
+        raise ValueError("URL cannot be empty")
+
+    # Parse the URL
+    parsed_url = urlparse(url)
+
+    # Ensure scheme is present and is either http or https
+    if not parsed_url.scheme or parsed_url.scheme not in ("http", "https"):
+        raise ValueError(f"URL must have http or https scheme: {url}")
+
+    # Ensure netloc (hostname) is present
+    if not parsed_url.netloc:
+        raise ValueError(f"URL must include a hostname: {url}")
+
+    # Determine transport type based on URL path
+    transport_type: Literal["http", "sse"] = "http"
+    path = parsed_url.path or ""
+    normalized_path = path.rstrip("/")
+    if normalized_path.endswith("/sse"):
+        transport_type = "sse"
+    elif not normalized_path.endswith("/mcp"):
+        # If path doesn't end with /mcp or /sse (handling trailing slash), append /mcp once
+        url = f"{url.rstrip('/')}" + "/mcp"
+
+    # Generate a server name based on hostname and port
+    server_name = generate_server_name(url)
+
+    return server_name, transport_type, url
+
+
+def generate_server_name(url: str) -> str:
+    """
+    Generate a unique and readable server name from a URL.
+
+    Args:
+        url: The URL to generate a name for
+
+    Returns:
+        A server name string
+    """
+    parsed_url = urlparse(url)
+
+    # Extract hostname and port
+    hostname, _, port_str = parsed_url.netloc.partition(":")
+
+    # Clean the hostname for use in a server name
+    # Replace non-alphanumeric characters with underscores
+    clean_hostname = re.sub(r"[^a-zA-Z0-9]", "_", hostname)
+
+    if len(clean_hostname) > 15:
+        clean_hostname = clean_hostname[:9] + clean_hostname[-5:]
+
+    # If it's localhost or an IP, add a more unique identifier
+    if clean_hostname in ("localhost", "127_0_0_1") or re.match(r"^(\d+_){3}\d+$", clean_hostname):
+        # Use the path as part of the name for uniqueness
+        path = parsed_url.path.strip("/")
+        path = re.sub(r"[^a-zA-Z0-9]", "_", path)
+
+        # Include port if specified
+        port = f"_{port_str}" if port_str else ""
+
+        if path:
+            return f"{clean_hostname}{port}_{path[:20]}"  # Limit path length
+        else:
+            # Use a hash if no path for uniqueness
+            url_hash = hashlib.md5(url.encode()).hexdigest()[:8]
+            return f"{clean_hostname}{port}_{url_hash}"
+
+    return clean_hostname
+
+
+def parse_server_urls(
+    urls_param: str, auth_token: str | None = None
+) -> list[tuple[str, Literal["http", "sse"], str, dict[str, str] | None]]:
+    """
+    Parse a comma-separated list of URLs into server configurations.
+
+    Args:
+        urls_param: Comma-separated list of URLs
+        auth_token: Optional bearer token for authorization
+
+    Returns:
+        List of tuples containing (server_name, transport_type, url, headers)
+
+    Raises:
+        ValueError: If any URL is invalid
+    """
+    if not urls_param:
+        return []
+
+    # Split by comma and strip whitespace
+    url_list = [url.strip() for url in urls_param.split(",")]
+
+    # Prepare headers if auth token is provided
+    headers = None
+    if auth_token:
+        headers = {"Authorization": f"Bearer {auth_token}"}
+
+    # Parse each URL
+    result = []
+    for url in url_list:
+        server_name, transport_type, parsed_url = parse_server_url(url)
+
+        # Apply HuggingFace authentication if appropriate
+        final_headers = add_hf_auth_header(parsed_url, headers)
+
+        result.append((server_name, transport_type, parsed_url, final_headers))
+
+    return result
+
+
+def generate_server_configs(
+    parsed_urls: list[tuple[str, Literal["http", "sse"], str, dict[str, str] | None]],
+) -> dict[str, dict[str, str | dict[str, str]]]:
+    """
+    Generate server configurations from parsed URLs.
+
+    Args:
+        parsed_urls: List of tuples containing (server_name, transport_type, url, headers)
+
+    Returns:
+        Dictionary of server configurations
+    """
+    server_configs: dict[str, dict[str, str | dict[str, str]]] = {}
+    # Keep track of server name occurrences to handle collisions
+    name_counts = {}
+
+    for server_name, transport_type, url, headers in parsed_urls:
+        # Handle name collisions by adding a suffix
+        final_name = server_name
+        if server_name in server_configs:
+            # Initialize counter if we haven't seen this name yet
+            if server_name not in name_counts:
+                name_counts[server_name] = 1
+
+            # Generate a new name with suffix
+            suffix = name_counts[server_name]
+            final_name = f"{server_name}_{suffix}"
+            name_counts[server_name] += 1
+
+            # Ensure the new name is also unique
+            while final_name in server_configs:
+                suffix = name_counts[server_name]
+                final_name = f"{server_name}_{suffix}"
+                name_counts[server_name] += 1
+
+        config: dict[str, str | dict[str, str]] = {
+            "transport": transport_type,
+            "url": url,
+        }
+
+        # Add headers if provided
+        if headers:
+            config["headers"] = headers
+
+        server_configs[final_name] = config
+
+    return server_configs

fast_agent/cli/constants.py

@@ -0,0 +1,40 @@
+"""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",
+    "--shell",
+    "-x",
+    "--skills",
+    "--skills-dir",
+}
+
+# Known subcommands that should not trigger auto-routing
+KNOWN_SUBCOMMANDS = {
+    "go",
+    "serve",
+    "setup",
+    "check",
+    "auth",
+    "bootstrap",
+    "quickstart",
+    "--help",
+    "-h",
+    "--version",
+}