fast-agent-mcp 0.3.16__tar.gz → 0.3.18__tar.gz

{fast_agent_mcp-0.3.16 → fast_agent_mcp-0.3.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.3.16
+Version: 0.3.18
 Summary: Define, Prompt and Test MCP enabled Agents and Workflows
 Author-email: Shaun Smith <fastagent@llmindset.co.uk>
 License:                                  Apache License
@@ -261,6 +261,14 @@ The simple declarative syntax lets you concentrate on composing your Prompts and
 
 Model support is comprehensive with native support for Anthropic, OpenAI and Google providers as well as Azure, Ollama, Deepseek and dozens of others via TensorZero. Structured Outputs, PDF and Vision support is simple to use and well tested. Passthrough and Playback LLMs enable rapid development and test of Python glue-code for your applications.
 
+Recent features include:
+ - Agent Skills (SKILL.md)
+ - MCP-UI Support |
+ - OpenAI Apps SDK (Skybridge)
+ - Shell Mode
+ - Advanced MCP Transport Diagnsotics
+ - MCP Elicitations
+
 <img width="800"  alt="MCP Transport Diagnostics" src="https://github.com/user-attachments/assets/e26472de-58d9-4726-8bdd-01eb407414cf" />
 
 

{fast_agent_mcp-0.3.16 → fast_agent_mcp-0.3.18}/README.md

@@ -20,6 +20,14 @@ The simple declarative syntax lets you concentrate on composing your Prompts and
 
 Model support is comprehensive with native support for Anthropic, OpenAI and Google providers as well as Azure, Ollama, Deepseek and dozens of others via TensorZero. Structured Outputs, PDF and Vision support is simple to use and well tested. Passthrough and Playback LLMs enable rapid development and test of Python glue-code for your applications.
 
+Recent features include:
+ - Agent Skills (SKILL.md)
+ - MCP-UI Support |
+ - OpenAI Apps SDK (Skybridge)
+ - Shell Mode
+ - Advanced MCP Transport Diagnsotics
+ - MCP Elicitations
+
 <img width="800"  alt="MCP Transport Diagnostics" src="https://github.com/user-attachments/assets/e26472de-58d9-4726-8bdd-01eb407414cf" />
 
 

{fast_agent_mcp-0.3.16 → fast_agent_mcp-0.3.18}/examples/new-api/textual_markdown_demo.py

@@ -20,12 +20,9 @@ from fast_agent import FastAgent
 from fast_agent.constants import REASONING
 from fast_agent.mcp.helpers.content_helpers import get_text
 from fast_agent.types import PromptMessageExtended
-from fast_agent.ui.console_display import (
-    MESSAGE_CONFIGS,
-    ConsoleDisplay,
-    MessageType,
-    _prepare_markdown_content,
-)
+from fast_agent.ui.console_display import ConsoleDisplay
+from fast_agent.ui.markdown_helpers import prepare_markdown_content
+from fast_agent.ui.message_primitives import MESSAGE_CONFIGS, MessageType
 
 if TYPE_CHECKING:
     from mcp.types import CallToolResult
@@ -208,7 +205,7 @@ class ChatDisplay(RichLog):
             if formatted:
                 segments.append(Markdown(formatted))
         else:
-            prepared = _prepare_markdown_content(content, True) if content else ""
+            prepared = prepare_markdown_content(content, True) if content else ""
             if prepared:
                 segments.append(Markdown(prepared))
 

{fast_agent_mcp-0.3.16 → fast_agent_mcp-0.3.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fast-agent-mcp"
-version = "0.3.16"
+version = "0.3.18"
 description = "Define, Prompt and Test MCP enabled Agents and Workflows"
 readme = "README.md"
 license = { file = "LICENSE" }

{fast_agent_mcp-0.3.16 → fast_agent_mcp-0.3.18}/src/fast_agent/agents/mcp_agent.py

@@ -157,7 +157,7 @@ class McpAgent(ABC, ToolAgent):
             if skills_configured:
                 modes.append("skills")
             if shell_flag_requested:
-                modes.append("command switch")
+                modes.append("switch")
             self._shell_access_modes = tuple(modes)
         self._bash_tool = self._shell_runtime.tool
         if self._shell_runtime_enabled:

{fast_agent_mcp-0.3.16 → fast_agent_mcp-0.3.18}/src/fast_agent/cli/commands/go.py

@@ -5,6 +5,7 @@ import logging
 import shlex
 import sys
 from pathlib import Path
+from typing import Literal
 
 import typer
 
@@ -23,6 +24,50 @@ app = typer.Typer(
 default_instruction = DEFAULT_AGENT_INSTRUCTION
 
 
+def resolve_instruction_option(instruction: str | None) -> tuple[str, str]:
+    """
+    Resolve the instruction option (file or URL) to the instruction string and agent name.
+    Returns (resolved_instruction, agent_name).
+    """
+    resolved_instruction = default_instruction
+    agent_name = "agent"
+
+    if instruction:
+        try:
+            from pathlib import Path
+
+            from pydantic import AnyUrl
+
+            from fast_agent.core.direct_decorators import _resolve_instruction
+
+            if instruction.startswith(("http://", "https://")):
+                resolved_instruction = _resolve_instruction(AnyUrl(instruction))
+            else:
+                resolved_instruction = _resolve_instruction(Path(instruction))
+                instruction_path = Path(instruction)
+                if instruction_path.exists() and instruction_path.is_file():
+                    agent_name = instruction_path.stem
+        except Exception as e:
+            typer.echo(f"Error loading instruction from {instruction}: {e}", err=True)
+            raise typer.Exit(1)
+
+    return resolved_instruction, agent_name
+
+
+def collect_stdio_commands(npx: str | None, uvx: str | None, stdio: str | None) -> list[str]:
+    """Collect STDIO command definitions from convenience options."""
+    stdio_commands: list[str] = []
+
+    if npx:
+        stdio_commands.append(f"npx {npx}")
+    if uvx:
+        stdio_commands.append(f"uvx {uvx}")
+    if stdio:
+        stdio_commands.append(stdio)
+
+    return stdio_commands
+
+
 def _set_asyncio_exception_handler(loop: asyncio.AbstractEventLoop) -> None:
     """Attach a detailed exception handler to the provided event loop."""
 
@@ -72,6 +117,12 @@ async def _run_agent(
     agent_name: str | None = "agent",
     skills_directory: Path | None = None,
     shell_runtime: bool = False,
+    mode: Literal["interactive", "serve"] = "interactive",
+    transport: str = "http",
+    host: str = "0.0.0.0",
+    port: int = 8000,
+    tool_description: str | None = None,
+    instance_scope: str = "shared",
 ) -> None:
     """Async implementation to run an interactive agent."""
     from fast_agent.mcp.prompts.prompt_load import load_prompt
@@ -84,6 +135,8 @@ async def _run_agent(
         "ignore_unknown_args": True,
         "parse_cli_args": False,  # Don't parse CLI args, we're handling it ourselves
     }
+    if mode == "serve":
+        fast_kwargs["quiet"] = True
     if skills_directory is not None:
         fast_kwargs["skills_directory"] = skills_directory
 
@@ -183,7 +236,16 @@ async def _run_agent(
                     await agent.interactive()
 
     # Run the agent
-    await cli_agent()
+    if mode == "serve":
+        await fast.start_server(
+            transport=transport,
+            host=host,
+            port=port,
+            tool_description=tool_description,
+            instance_scope=instance_scope,
+        )
+    else:
+        await cli_agent()
 
 
 def run_async_agent(
@@ -200,6 +262,12 @@ def run_async_agent(
     agent_name: str | None = None,
     skills_directory: Path | None = None,
     shell_enabled: bool = False,
+    mode: Literal["interactive", "serve"] = "interactive",
+    transport: str = "http",
+    host: str = "0.0.0.0",
+    port: int = 8000,
+    tool_description: str | None = None,
+    instance_scope: str = "shared",
 ):
     """Run the async agent function with proper loop handling."""
     server_list = servers.split(",") if servers else None
@@ -304,6 +372,12 @@ def run_async_agent(
                 agent_name=agent_name,
                 skills_directory=skills_directory,
                 shell_runtime=shell_enabled,
+                mode=mode,
+                transport=transport,
+                host=host,
+                port=port,
+                tool_description=tool_description,
+                instance_scope=instance_scope,
             )
         )
     finally:
@@ -405,46 +479,13 @@ def go(
         --stdio               Command to run as STDIO MCP server (quoted)
     """
     # Collect all stdio commands from convenience options
-    stdio_commands = []
+    stdio_commands = collect_stdio_commands(npx, uvx, stdio)
     shell_enabled = shell
 
-    if npx:
-        stdio_commands.append(f"npx {npx}")
-
-    if uvx:
-        stdio_commands.append(f"uvx {uvx}")
-
-    if stdio:
-        stdio_commands.append(stdio)
-
     # When shell is enabled we don't add an MCP stdio server; handled inside the agent
 
     # Resolve instruction from file/URL or use default
-    resolved_instruction = default_instruction  # Default
-    agent_name = "agent"
-
-    if instruction:
-        try:
-            from pathlib import Path
-
-            from pydantic import AnyUrl
-
-            from fast_agent.core.direct_decorators import _resolve_instruction
-
-            # Check if it's a URL
-            if instruction.startswith(("http://", "https://")):
-                resolved_instruction = _resolve_instruction(AnyUrl(instruction))
-            else:
-                # Treat as file path
-                resolved_instruction = _resolve_instruction(Path(instruction))
-                # Extract filename without extension to use as agent name
-                instruction_path = Path(instruction)
-                if instruction_path.exists() and instruction_path.is_file():
-                    # Get filename without extension
-                    agent_name = instruction_path.stem
-        except Exception as e:
-            typer.echo(f"Error loading instruction from {instruction}: {e}", err=True)
-            raise typer.Exit(1)
+    resolved_instruction, agent_name = resolve_instruction_option(instruction)
 
     run_async_agent(
         name=name,
@@ -460,4 +501,5 @@ def go(
         agent_name=agent_name,
         skills_directory=skills_dir,
         shell_enabled=shell_enabled,
+        instance_scope="shared",
     )

fast_agent_mcp-0.3.18/src/fast_agent/cli/commands/serve.py

@@ -0,0 +1,136 @@
+"""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"
+
+
+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)",
+    ),
+    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)",
+    ),
+) -> 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,
+    )

{fast_agent_mcp-0.3.16 → fast_agent_mcp-0.3.18}/src/fast_agent/cli/constants.py

@@ -21,11 +21,14 @@ GO_SPECIFIC_OPTIONS = {
     "-c",
     "--shell",
     "-x",
+    "--skills",
+    "--skills-dir",
 }
 
 # Known subcommands that should not trigger auto-routing
 KNOWN_SUBCOMMANDS = {
     "go",
+    "serve",
     "setup",
     "check",
     "auth",

{fast_agent_mcp-0.3.16 → fast_agent_mcp-0.3.18}/src/fast_agent/cli/main.py

@@ -3,17 +3,18 @@
 import typer
 from rich.table import Table
 
-from fast_agent.cli.commands import auth, check_config, go, quickstart, setup
+from fast_agent.cli.commands import auth, check_config, go, quickstart, serve, setup
 from fast_agent.cli.terminal import Application
 from fast_agent.ui.console import console as shared_console
 
 app = typer.Typer(
-    help="fast-agent - Build effective agents using Model Context Protocol",
+    help="Use `fast-agent go --help` for interactive shell arguments and options.",
     add_completion=False,  # We'll add this later when we have more commands
 )
 
 # Subcommands
 app.add_typer(go.app, name="go", help="Run an interactive agent directly from the command line")
+app.add_typer(serve.app, name="serve", help="Run FastAgent as an MCP server")
 app.add_typer(setup.app, name="setup", help="Set up a new agent project")
 app.add_typer(check_config.app, name="check", help="Show or diagnose fast-agent configuration")
 app.add_typer(auth.app, name="auth", help="Manage OAuth authentication for MCP servers")
@@ -62,7 +63,8 @@ def show_welcome() -> None:
     table.add_column("Description", header_style="bold bright_white")
 
     table.add_row("[bold]go[/bold]", "Start an interactive session")
-    table.add_row("go --shell", "Start an interactive session with a local shell tool")
+    table.add_row("go -x", "Start an interactive session with a local shell tool")
+    table.add_row("[bold]serve[/bold]", "Start fast-agent as an MCP server")
     table.add_row("check", "Show current configuration")
     table.add_row("auth", "Manage OAuth tokens and keyring")
     table.add_row("setup", "Create agent template and configuration")

{fast_agent_mcp-0.3.16 → fast_agent_mcp-0.3.18}/src/fast_agent/core/fastagent.py

@@ -6,9 +6,11 @@ directly creates Agent instances without proxies.
 
 import argparse
 import asyncio
+import inspect
 import pathlib
 import sys
 from contextlib import asynccontextmanager
+from dataclasses import dataclass
 from importlib.metadata import version as get_version
 from pathlib import Path
 from typing import (
@@ -127,6 +129,9 @@ class FastAgent:
             Path(skills_directory).expanduser() if skills_directory else None
         )
         self._default_skill_manifests: List[SkillManifest] = []
+        self._server_instance_factory = None
+        self._server_instance_dispose = None
+        self._server_managed_instances: List[AgentInstance] = []
 
         # --- Wrap argument parsing logic ---
         if parse_cli_args:
@@ -181,6 +186,12 @@ class FastAgent:
                 default="0.0.0.0",
                 help="Host address to bind to when running as a server with SSE transport",
             )
+            parser.add_argument(
+                "--instance-scope",
+                choices=["shared", "connection", "request"],
+                default="shared",
+                help="Control MCP agent instancing behaviour (shared, connection, request)",
+            )
             parser.add_argument(
                 "--skills",
                 help="Path to skills directory to use instead of default .claude/skills",
@@ -500,18 +511,34 @@ class FastAgent:
                             cli_model=cli_model_override,  # Use the variable defined above
                         )
 
-                    # Create all agents in dependency order
-                    active_agents = await create_agents_in_dependency_order(
-                        self.app,
-                        self.agents,
-                        model_factory_func,
-                    )
+                    managed_instances: list[AgentInstance] = []
+                    instance_lock = asyncio.Lock()
+
+                    async def instantiate_agent_instance() -> AgentInstance:
+                        async with instance_lock:
+                            agents_map = await create_agents_in_dependency_order(
+                                self.app,
+                                self.agents,
+                                model_factory_func,
+                            )
+                            validate_provider_keys_post_creation(agents_map)
+                            instance = AgentInstance(AgentApp(agents_map), agents_map)
+                            managed_instances.append(instance)
+                            return instance
+
+                    async def dispose_agent_instance(instance: AgentInstance) -> None:
+                        async with instance_lock:
+                            if instance in managed_instances:
+                                managed_instances.remove(instance)
+                        await instance.shutdown()
 
-                    # Validate API keys after agent creation
-                    validate_provider_keys_post_creation(active_agents)
+                    primary_instance = await instantiate_agent_instance()
+                    wrapper = primary_instance.app
+                    active_agents = primary_instance.agents
 
-                    # Create a wrapper with all agents for simplified access
-                    wrapper = AgentApp(active_agents)
+                    self._server_instance_factory = instantiate_agent_instance
+                    self._server_instance_dispose = dispose_agent_instance
+                    self._server_managed_instances = managed_instances
 
                     # Disable streaming if parallel agents are present
                     from fast_agent.agents.agent_types import AgentType
@@ -541,9 +568,18 @@ class FastAgent:
                             # Create the MCP server
                             from fast_agent.mcp.server import AgentMCPServer
 
+                            tool_description = getattr(self.args, "tool_description", None)
+                            server_description = getattr(self.args, "server_description", None)
+                            server_name = getattr(self.args, "server_name", None)
+                            instance_scope = getattr(self.args, "instance_scope", "shared")
                             mcp_server = AgentMCPServer(
-                                agent_app=wrapper,
-                                server_name=f"{self.name}-MCP-Server",
+                                primary_instance=primary_instance,
+                                create_instance=self._server_instance_factory,
+                                dispose_instance=self._server_instance_dispose,
+                                instance_scope=instance_scope,
+                                server_name=server_name or f"{self.name}-MCP-Server",
+                                server_description=server_description,
+                                tool_description=tool_description,
                             )
 
                             # Run the server directly (this is a blocking call)
@@ -647,11 +683,32 @@ class FastAgent:
                     pass
 
                 # Print usage report before cleanup (show for user exits too)
-                if active_agents and not had_error and not quiet_mode:
+                if (
+                    getattr(self, "_server_managed_instances", None)
+                    and not had_error
+                    and not quiet_mode
+                    and getattr(self.args, "server", False) is False
+                ):
+                    # Only show usage report for non-server interactive runs
+                    if managed_instances:
+                        instance = managed_instances[0]
+                        self._print_usage_report(instance.agents)
+                elif active_agents and not had_error and not quiet_mode:
                     self._print_usage_report(active_agents)
 
                 # Clean up any active agents (always cleanup, even on errors)
-                if active_agents:
+                if getattr(self, "_server_managed_instances", None) and getattr(
+                    self, "_server_instance_dispose", None
+                ):
+                    # Dispose any remaining instances
+                    remaining_instances = list(self._server_managed_instances)
+                    for instance in remaining_instances:
+                        try:
+                            await self._server_instance_dispose(instance)
+                        except Exception:
+                            pass
+                    self._server_managed_instances.clear()
+                elif active_agents:
                     for agent in active_agents.values():
                         try:
                             await agent.shutdown()
@@ -790,6 +847,8 @@ class FastAgent:
         port: int = 8000,
         server_name: Optional[str] = None,
         server_description: Optional[str] = None,
+        tool_description: Optional[str] = None,
+        instance_scope: str = "shared",
     ) -> None:
         """
         Start the application as an MCP server.
@@ -801,7 +860,9 @@ class FastAgent:
             host: Host address for the server when using SSE
             port: Port for the server when using SSE
             server_name: Optional custom name for the MCP server
-            server_description: Optional description for the MCP server
+            server_description: Optional description/instructions for the MCP server
+            tool_description: Optional description template for the exposed send tool.
+                              Use {agent} to reference the agent name.
         """
         # This method simply updates the command line arguments and uses run()
         # to ensure we follow the same initialization path for all operations
@@ -819,6 +880,10 @@ class FastAgent:
         self.args.transport = transport
         self.args.host = host
         self.args.port = port
+        self.args.tool_description = tool_description
+        self.args.server_description = server_description
+        self.args.server_name = server_name
+        self.args.instance_scope = instance_scope
         self.args.quiet = (
             original_args.quiet if original_args and hasattr(original_args, "quiet") else False
         )
@@ -842,6 +907,8 @@ class FastAgent:
         port: int = 8000,
         server_name: Optional[str] = None,
         server_description: Optional[str] = None,
+        tool_description: Optional[str] = None,
+        instance_scope: str = "shared",
     ) -> None:
         """
         Run the application and expose agents through an MCP server.
@@ -853,7 +920,8 @@ class FastAgent:
             host: Host address for the server when using SSE
             port: Port for the server when using SSE
             server_name: Optional custom name for the MCP server
-            server_description: Optional description for the MCP server
+            server_description: Optional description/instructions for the MCP server
+            tool_description: Optional description template for the exposed send tool.
         """
         await self.start_server(
             transport=transport,
@@ -861,6 +929,8 @@ class FastAgent:
             port=port,
             server_name=server_name,
             server_description=server_description,
+            tool_description=tool_description,
+            instance_scope=instance_scope,
         )
 
     async def main(self):
@@ -892,3 +962,19 @@ class FastAgent:
         # Just check if the flag is set, no action here
         # The actual server code will be handled by run()
         return hasattr(self, "args") and self.args.server
+@dataclass
+class AgentInstance:
+    app: AgentApp
+    agents: Dict[str, "AgentProtocol"]
+
+    async def shutdown(self) -> None:
+        for agent in self.agents.values():
+            try:
+                shutdown = getattr(agent, "shutdown", None)
+                if shutdown is None:
+                    continue
+                result = shutdown()
+                if inspect.isawaitable(result):
+                    await result
+            except Exception:
+                pass