fast-agent-mcp 0.3.17__py3-none-any.whl → 0.3.18__py3-none-any.whl

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/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/cli/constants.py

@@ -28,6 +28,7 @@ GO_SPECIFIC_OPTIONS = {
 # Known subcommands that should not trigger auto-routing
 KNOWN_SUBCOMMANDS = {
     "go",
+    "serve",
     "setup",
     "check",
     "auth",

fast_agent/cli/main.py

@@ -3,7 +3,7 @@
 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
 
@@ -14,6 +14,7 @@ app = typer.Typer(
 
 # 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/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

fast_agent/mcp/server/agent_server.py

@@ -3,17 +3,19 @@ Enhanced AgentMCPServer with robust shutdown handling for SSE transport.
 """
 
 import asyncio
+import logging
 import os
 import signal
+import time
 from contextlib import AsyncExitStack, asynccontextmanager
-from typing import Set
+from typing import Awaitable, Callable, Set
 
 from mcp.server.fastmcp import Context as MCPContext
 from mcp.server.fastmcp import FastMCP
 
 import fast_agent.core
 import fast_agent.core.prompt
-from fast_agent.core.agent_app import AgentApp
+from fast_agent.core.fastagent import AgentInstance
 from fast_agent.core.logging.logger import get_logger
 
 logger = get_logger(__name__)
@@ -24,17 +26,29 @@ class AgentMCPServer:
 
     def __init__(
         self,
-        agent_app: AgentApp,
+        primary_instance: AgentInstance,
+        create_instance: Callable[[], Awaitable[AgentInstance]],
+        dispose_instance: Callable[[AgentInstance], Awaitable[None]],
+        instance_scope: str,
         server_name: str = "FastAgent-MCP-Server",
         server_description: str | None = None,
+        tool_description: str | None = None,
     ) -> None:
         """Initialize the server with the provided agent app."""
-        self.agent_app = agent_app
+        self.primary_instance = primary_instance
+        self._create_instance_task = create_instance
+        self._dispose_instance_task = dispose_instance
+        self._instance_scope = instance_scope
         self.mcp_server: FastMCP = FastMCP(
             name=server_name,
             instructions=server_description
-            or f"This server provides access to {len(agent_app._agents)} agents",
+            or f"This server provides access to {len(primary_instance.agents)} agents",
         )
+        if self._instance_scope == "request":
+            # Ensure FastMCP does not attempt to maintain sessions for stateless mode
+            self.mcp_server.settings.stateless_http = True
+        self._tool_description = tool_description
+        self._shared_instance_active = True
         # Shutdown coordination
         self._graceful_shutdown_event = asyncio.Event()
         self._force_shutdown_event = asyncio.Event()
@@ -47,59 +61,187 @@ class AgentMCPServer:
         # Server state
         self._server_task = None
 
+        # Standard logging channel so we appear alongside Uvicorn/logging output
+        self.std_logger = logging.getLogger("fast_agent.server")
+
+        # Connection-scoped instance tracking
+        self._connection_instances: dict[int, AgentInstance] = {}
+        self._connection_cleanup_tasks: dict[int, Callable[[], Awaitable[None]]] = {}
+        self._connection_lock = asyncio.Lock()
+
         # Set up agent tools
         self.setup_tools()
 
-        logger.info(f"AgentMCPServer initialized with {len(agent_app._agents)} agents")
+        logger.info(
+            f"AgentMCPServer initialized with {len(primary_instance.agents)} agents",
+            name="mcp_server_initialized",
+            agent_count=len(primary_instance.agents),
+            instance_scope=instance_scope,
+        )
 
     def setup_tools(self) -> None:
         """Register all agents as MCP tools."""
-        for agent_name, agent in self.agent_app._agents.items():
-            self.register_agent_tools(agent_name, agent)
+        for agent_name in self.primary_instance.agents.keys():
+            self.register_agent_tools(agent_name)
 
-    def register_agent_tools(self, agent_name: str, agent) -> None:
+    def register_agent_tools(self, agent_name: str) -> None:
         """Register tools for a specific agent."""
 
         # Basic send message tool
+        tool_description = (
+            self._tool_description.format(agent=agent_name)
+            if self._tool_description and "{agent}" in self._tool_description
+            else self._tool_description
+        )
+
         @self.mcp_server.tool(
             name=f"{agent_name}_send",
-            description=f"Send a message to the {agent_name} agent",
+            description=tool_description or f"Send a message to the {agent_name} agent",
             structured_output=False,
             # MCP 1.10.1 turns every tool in to a structured output
         )
         async def send_message(message: str, ctx: MCPContext) -> str:
             """Send a message to the agent and return its response."""
-            # Get the agent's context
+            instance = await self._acquire_instance(ctx)
+            agent = instance.app[agent_name]
             agent_context = getattr(agent, "context", None)
 
             # Define the function to execute
             async def execute_send():
-                return await agent.send(message)
+                start = time.perf_counter()
+                logger.info(
+                    f"MCP request received for agent '{agent_name}'",
+                    name="mcp_request_start",
+                    agent=agent_name,
+                    session=self._session_identifier(ctx),
+                )
+                self.std_logger.info(
+                    "MCP request received for agent '%s' (scope=%s)",
+                    agent_name,
+                    self._instance_scope,
+                )
+
+                response = await agent.send(message)
+                duration = time.perf_counter() - start
+
+                logger.info(
+                    f"Agent '{agent_name}' completed MCP request",
+                    name="mcp_request_complete",
+                    agent=agent_name,
+                    duration=duration,
+                    session=self._session_identifier(ctx),
+                )
+                self.std_logger.info(
+                    "Agent '%s' completed MCP request in %.2fs (scope=%s)",
+                    agent_name,
+                    duration,
+                    self._instance_scope,
+                )
+                return response
 
-            # Execute with bridged context
-            if agent_context and ctx:
-                return await self.with_bridged_context(agent_context, ctx, execute_send)
-            else:
+            try:
+                # Execute with bridged context
+                if agent_context and ctx:
+                    return await self.with_bridged_context(agent_context, ctx, execute_send)
                 return await execute_send()
+            finally:
+                await self._release_instance(ctx, instance)
 
         # Register a history prompt for this agent
         @self.mcp_server.prompt(
             name=f"{agent_name}_history",
             description=f"Conversation history for the {agent_name} agent",
         )
-        async def get_history_prompt() -> list:
+        async def get_history_prompt(ctx: MCPContext) -> list:
             """Return the conversation history as MCP messages."""
-            # Get the conversation history from the agent's LLM
-            if not hasattr(agent, "_llm") or agent._llm is None:
-                return []
+            instance = await self._acquire_instance(ctx)
+            agent = instance.app[agent_name]
+            try:
+                if not hasattr(agent, "_llm") or agent._llm is None:
+                    return []
 
-            # Convert the multipart message history to standard PromptMessages
-            multipart_history = agent._llm.message_history
-            prompt_messages = fast_agent.core.prompt.Prompt.from_multipart(multipart_history)
+                # Convert the multipart message history to standard PromptMessages
+                multipart_history = agent._llm.message_history
+                prompt_messages = fast_agent.core.prompt.Prompt.from_multipart(multipart_history)
 
-            # In FastMCP, we need to return the raw list of messages
-            # that matches the structure that FastMCP expects (list of dicts with role/content)
-            return [{"role": msg.role, "content": msg.content} for msg in prompt_messages]
+                # In FastMCP, we need to return the raw list of messages
+                return [{"role": msg.role, "content": msg.content} for msg in prompt_messages]
+            finally:
+                await self._release_instance(ctx, instance, reuse_connection=True)
+
+    async def _acquire_instance(self, ctx: MCPContext | None) -> AgentInstance:
+        if self._instance_scope == "shared":
+            return self.primary_instance
+
+        if self._instance_scope == "request":
+            return await self._create_instance_task()
+
+        # Connection scope
+        assert ctx is not None, "Context is required for connection-scoped instances"
+        session_key = self._connection_key(ctx)
+        async with self._connection_lock:
+            instance = self._connection_instances.get(session_key)
+            if instance is None:
+                instance = await self._create_instance_task()
+                self._connection_instances[session_key] = instance
+                self._register_session_cleanup(ctx, session_key)
+            return instance
+
+    async def _release_instance(
+        self,
+        ctx: MCPContext | None,
+        instance: AgentInstance,
+        *,
+        reuse_connection: bool = False,
+    ) -> None:
+        if self._instance_scope == "request":
+            await self._dispose_instance_task(instance)
+        elif self._instance_scope == "connection" and reuse_connection is False:
+            # Connection-scoped instances persist until session cleanup
+            pass
+
+    def _connection_key(self, ctx: MCPContext) -> int:
+        return id(ctx.session)
+
+    def _register_session_cleanup(self, ctx: MCPContext, session_key: int) -> None:
+        async def cleanup() -> None:
+            instance = self._connection_instances.pop(session_key, None)
+            if instance is not None:
+                await self._dispose_instance_task(instance)
+
+        exit_stack = getattr(ctx.session, "_exit_stack", None)
+        if exit_stack is not None:
+            exit_stack.push_async_callback(cleanup)
+        else:
+            self._connection_cleanup_tasks[session_key] = cleanup
+
+    def _session_identifier(self, ctx: MCPContext | None) -> str | None:
+        if ctx is None:
+            return None
+        request = getattr(ctx.request_context, "request", None)
+        if request is not None:
+            return request.headers.get("mcp-session-id")
+        return None
+
+    async def _dispose_primary_instance(self) -> None:
+        if self._shared_instance_active:
+            try:
+                await self._dispose_instance_task(self.primary_instance)
+            finally:
+                self._shared_instance_active = False
+
+    async def _dispose_all_connection_instances(self) -> None:
+        pending_cleanups = list(self._connection_cleanup_tasks.values())
+        self._connection_cleanup_tasks.clear()
+        for cleanup in pending_cleanups:
+            await cleanup()
+
+        async with self._connection_lock:
+            instances = list(self._connection_instances.values())
+            self._connection_instances.clear()
+
+        for instance in instances:
+            await self._dispose_instance_task(instance)
 
     def _setup_signal_handlers(self):
         """Set up signal handlers for graceful and forced shutdown."""
@@ -414,14 +556,8 @@ class AgentMCPServer:
         """Minimal cleanup for STDIO transport to avoid keeping process alive."""
         logger.info("Performing minimal STDIO cleanup")
 
-        # Just clean up agent resources directly without the full shutdown sequence
-        # This preserves the natural exit process for STDIO
-        for agent_name, agent in self.agent_app._agents.items():
-            try:
-                if hasattr(agent, "shutdown"):
-                    await agent.shutdown()
-            except Exception as e:
-                logger.error(f"Error shutting down agent {agent_name}: {e}")
+        await self._dispose_primary_instance()
+        await self._dispose_all_connection_instances()
 
         logger.info("STDIO cleanup complete")
 
@@ -443,13 +579,11 @@ class AgentMCPServer:
             # Close any resources in the exit stack
             await self._exit_stack.aclose()
 
-            # Shutdown any agent resources
-            for agent_name, agent in self.agent_app._agents.items():
-                try:
-                    if hasattr(agent, "shutdown"):
-                        await agent.shutdown()
-                except Exception as e:
-                    logger.error(f"Error shutting down agent {agent_name}: {e}")
+            # Dispose connection-scoped instances
+            await self._dispose_all_connection_instances()
+
+            # Dispose shared instance if still active
+            await self._dispose_primary_instance()
         except Exception as e:
             # Log any errors but don't let them prevent shutdown
             logger.error(f"Error during shutdown: {e}", exc_info=True)

{fast_agent_mcp-0.3.17.dist-info → fast_agent_mcp-0.3.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.3.17
+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.17.dist-info → fast_agent_mcp-0.3.18.dist-info}/RECORD

@@ -22,13 +22,14 @@ fast_agent/agents/workflow/parallel_agent.py,sha256=DlJXDURAfx-WBF297tKBLfH93gDF
 fast_agent/agents/workflow/router_agent.py,sha256=gugcp0a-3Ldn42JbPJZ7AbO2G6FvqE0A3tsWcLorwSY,11400
 fast_agent/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fast_agent/cli/__main__.py,sha256=OWuKPFEeZRco6j5VA3IvtwTvZ351pDGxuO6rAiOTFNI,2588
-fast_agent/cli/constants.py,sha256=9XaMlY8hy7PuwDFmUg_22vGGVKYRfNpODL5pub1Wem4,659
-fast_agent/cli/main.py,sha256=8wBh605HLcxyr11T_I8c5_LjHHGB2UcfiY2-3F8kRnY,4493
+fast_agent/cli/constants.py,sha256=xLxQKuQzbv3Qkd6CB5wNwyDqyHBvdx97PZfsoK7-b4o,672
+fast_agent/cli/main.py,sha256=yXglgZuQrThhqK3EgVstwpU3YRUf2-RWIDXDb6rQ66s,4650
 fast_agent/cli/terminal.py,sha256=tDN1fJ91Nc_wZJTNafkQuD7Z7gFscvo1PHh-t7Wl-5s,1066
 fast_agent/cli/commands/auth.py,sha256=nJEC7zrz5UXYUz5O6AgGZnfJPHIrgHk68CUwGo-7Nyg,15063
 fast_agent/cli/commands/check_config.py,sha256=Iy5MHsRXqRcFLN-0Gs20jA3DqT-gN1VE9WtKuWlxJ9M,32597
-fast_agent/cli/commands/go.py,sha256=nNlFZ9dNPkm4VTkFmv1hDvWu8qbWsyTY5BEX32HJfmA,17580
+fast_agent/cli/commands/go.py,sha256=f0CrNkjzuIWWewUnCGeMWcO-93PdhyOqq5n3a-8cWVM,19005
 fast_agent/cli/commands/quickstart.py,sha256=UOTqAbaVGLECHkTvpUNQ41PWXssqCijVvrqh30YUqnM,20624
+fast_agent/cli/commands/serve.py,sha256=KU9QsP9MQVKV5eOrt8eBGi9gyx_Y20oaEwurDuWAc0k,4427
 fast_agent/cli/commands/server_helpers.py,sha256=Nuded8sZb4Rybwoq5LbXXUgwtJZg-OO04xhmPUp6e98,4073
 fast_agent/cli/commands/setup.py,sha256=n5hVjXkKTmuiW8-0ezItVcMHJ92W6NlE2JOGCYiKw0A,6388
 fast_agent/cli/commands/url_parser.py,sha256=v9KoprPBEEST5Fo7qXgbW50GC5vMpxFteKqAT6mFkdI,5991
@@ -39,7 +40,7 @@ fast_agent/core/direct_decorators.py,sha256=Z8zM1Ep9THEiuNzlxW-WmQDm7x4JF0wn4xO2
 fast_agent/core/direct_factory.py,sha256=SYYVtEqPQh7ElvAVC_445a5pZkKstM0RhKNGZ2CJQT8,18338
 fast_agent/core/error_handling.py,sha256=tZkO8LnXO-qf6jD8a12Pv5fD4NhnN1Ag5_tJ6DwbXjg,631
 fast_agent/core/exceptions.py,sha256=ENAD_qGG67foxy6vDkIvc-lgopIUQy6O7zvNPpPXaQg,2289
-fast_agent/core/fastagent.py,sha256=4rsKQVuK3GRW9ejT7oSfqsrNsfYb2rPpBT0wJxk_-mM,35372
+fast_agent/core/fastagent.py,sha256=u9TBdQxBlyV3OhZ5gfOB2TucdI3xI2xsEObW-c1WTdA,39865
 fast_agent/core/prompt.py,sha256=qNUFlK3KtU7leYysYUglzBYQnEYiXu__iR_T8189zc0,203
 fast_agent/core/validation.py,sha256=cesQeT8jfLlPqew6S9bq8ZJqde7ViVQXHF9fhAnyOHI,11950
 fast_agent/core/executor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -135,7 +136,7 @@ fast_agent/mcp/prompts/prompt_load.py,sha256=1KixVXpkML3_kY3vC59AlMfcBXQVESrII24
 fast_agent/mcp/prompts/prompt_server.py,sha256=ZuUFqYfiYYE8yTXw0qagGWkZkelQgETGBpzUIdIhLXc,20174
 fast_agent/mcp/prompts/prompt_template.py,sha256=SAklXs9wujYqqEWv5vzRI_cdjSmGnWlDmPLZ5qkXZO4,15695
 fast_agent/mcp/server/__init__.py,sha256=AJFNzdmuHPRL3jqFhDVDJste_zYE_KJ3gGYDsbghvl0,156
-fast_agent/mcp/server/agent_server.py,sha256=zJMFnPfXPsbLt5ZyGMTN90YzIzwV7TaSQ4WYs9lnB2Q,20194
+fast_agent/mcp/server/agent_server.py,sha256=svO0_RwJX1thRRfciLXkbLUFLokkzw5VspGIs5Ias40,25555
 fast_agent/resources/examples/data-analysis/analysis-campaign.py,sha256=SnDQm_e_cm0IZEKdWizUedXxpIWWj-5K70wmcM1Tw2Y,7277
 fast_agent/resources/examples/data-analysis/analysis.py,sha256=0W1dN3SAx-RxEKoH3shAq42HxglEz9hc8BadGYmnwAk,2653
 fast_agent/resources/examples/data-analysis/fastagent.config.yaml,sha256=ini94PHyJCfgpjcjHKMMbGuHs6LIj46F1NwY0ll5HVk,1609
@@ -218,8 +219,8 @@ fast_agent/ui/streaming.py,sha256=SNLGx6s8xuRikxi6vNxnDCgQQKqFJ5rbTKU9ixnzmY0,22
 fast_agent/ui/streaming_buffer.py,sha256=e-zwVUVBOQ_mKyHgLiTXFmShGs4DNQRZ9BZZwWgXoWM,16648
 fast_agent/ui/tool_display.py,sha256=DK6kA8MBjxq8qpK1WLv7kFKAfOtEOfY5rtQ8t4XeM0s,16111
 fast_agent/ui/usage_display.py,sha256=ltJpn_sDzo8PDNSXWx-QdEUbQWUnhmajCItNt5mA5rM,7285
-fast_agent_mcp-0.3.17.dist-info/METADATA,sha256=DyQQDnwC9okrklDtQ5MDxTxCrnRV_Z07SUQFJImJZ88,32083
-fast_agent_mcp-0.3.17.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-fast_agent_mcp-0.3.17.dist-info/entry_points.txt,sha256=i6Ujja9J-hRxttOKqTYdbYP_tyaS4gLHg53vupoCSsg,199
-fast_agent_mcp-0.3.17.dist-info/licenses/LICENSE,sha256=Gx1L3axA4PnuK4FxsbX87jQ1opoOkSFfHHSytW6wLUU,10935
-fast_agent_mcp-0.3.17.dist-info/RECORD,,
+fast_agent_mcp-0.3.18.dist-info/METADATA,sha256=UluPke36Pp1VhO8z8hmPIlC-MjqN94xO6N02HF3EWbU,32259
+fast_agent_mcp-0.3.18.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fast_agent_mcp-0.3.18.dist-info/entry_points.txt,sha256=i6Ujja9J-hRxttOKqTYdbYP_tyaS4gLHg53vupoCSsg,199
+fast_agent_mcp-0.3.18.dist-info/licenses/LICENSE,sha256=Gx1L3axA4PnuK4FxsbX87jQ1opoOkSFfHHSytW6wLUU,10935
+fast_agent_mcp-0.3.18.dist-info/RECORD,,