fast-agent-mcp 0.3.12__py3-none-any.whl → 0.3.14__py3-none-any.whl

fast_agent/mcp/mcp_connection_manager.py

@@ -17,7 +17,6 @@ from anyio import Event, Lock, create_task_group
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from httpx import HTTPStatusError
 from mcp import ClientSession
-from mcp.client.sse import sse_client
 from mcp.client.stdio import (
     StdioServerParameters,
     get_default_environment,
@@ -33,11 +32,14 @@ from fast_agent.event_progress import ProgressAction
 from fast_agent.mcp.logger_textio import get_stderr_handler
 from fast_agent.mcp.mcp_agent_client_session import MCPAgentClientSession
 from fast_agent.mcp.oauth_client import build_oauth_provider
+from fast_agent.mcp.sse_tracking import tracking_sse_client
 from fast_agent.mcp.stdio_tracking_simple import tracking_stdio_client
 from fast_agent.mcp.streamable_http_tracking import tracking_streamablehttp_client
 from fast_agent.mcp.transport_tracking import TransportChannelMetrics
 
 if TYPE_CHECKING:
+    from mcp.client.auth import OAuthClientProvider
+
     from fast_agent.context import Context
     from fast_agent.mcp_server_registry import ServerRegistry
 
@@ -65,6 +67,38 @@ def _add_none_to_context(context_manager):
     return StreamingContextAdapter(context_manager)
 
 
+def _prepare_headers_and_auth(
+    server_config: MCPServerSettings,
+) -> tuple[dict[str, str], Optional["OAuthClientProvider"], set[str]]:
+    """
+    Prepare request headers and determine if OAuth authentication should be used.
+
+    Returns a copy of the headers, an OAuth auth provider when applicable, and the set
+    of user-supplied authorization header keys.
+    """
+    headers: dict[str, str] = dict(server_config.headers or {})
+    auth_header_keys = {"authorization", "x-hf-authorization"}
+    user_provided_auth_keys = {key for key in headers if key.lower() in auth_header_keys}
+
+    # OAuth is only relevant for SSE/HTTP transports and should be skipped when the
+    # user has already supplied explicit Authorization headers.
+    if server_config.transport not in ("sse", "http") or user_provided_auth_keys:
+        return headers, None, user_provided_auth_keys
+
+    oauth_auth = build_oauth_provider(server_config)
+    if oauth_auth is not None:
+        # Scrub Authorization headers so OAuth-managed credentials are the only ones sent.
+        for header_name in (
+            "Authorization",
+            "authorization",
+            "X-HF-Authorization",
+            "x-hf-authorization",
+        ):
+            headers.pop(header_name, None)
+
+    return headers, oauth_auth, user_provided_auth_keys
+
+
 class ServerConnection:
     """
     Represents a long-lived MCP server connection, including:
@@ -113,7 +147,9 @@ class ServerConnection:
         self.server_implementation: Implementation | None = None
         self.client_capabilities: dict | None = None
         self.server_instructions_available: bool = False
-        self.server_instructions_enabled: bool = server_config.include_instructions if server_config else True
+        self.server_instructions_enabled: bool = (
+            server_config.include_instructions if server_config else True
+        )
         self.session_id: str | None = None
         self._get_session_id_cb: GetSessionIdCallback | None = None
         self.transport_metrics: TransportChannelMetrics | None = None
@@ -404,7 +440,27 @@ class MCPConnectionManager(ContextDependent):
 
         logger.debug(f"{server_name}: Found server configuration=", data=config.model_dump())
 
-        transport_metrics = TransportChannelMetrics() if config.transport in ("http", "stdio") else None
+        timeline_steps = 20
+        timeline_seconds = 30
+        try:
+            ctx = self.context
+        except RuntimeError:
+            ctx = None
+
+        config_obj = getattr(ctx, "config", None)
+        timeline_config = getattr(config_obj, "mcp_timeline", None)
+        if timeline_config:
+            timeline_steps = getattr(timeline_config, "steps", timeline_steps)
+            timeline_seconds = getattr(timeline_config, "step_seconds", timeline_seconds)
+
+        transport_metrics = (
+            TransportChannelMetrics(
+                bucket_seconds=timeline_seconds,
+                bucket_count=timeline_steps,
+            )
+            if config.transport in ("http", "sse", "stdio")
+            else None
+        )
 
         def transport_context_factory():
             if config.transport == "stdio":
@@ -425,7 +481,9 @@ class MCPConnectionManager(ContextDependent):
 
                 channel_hook = transport_metrics.record_event if transport_metrics else None
                 return _add_none_to_context(
-                    tracking_stdio_client(server_params, channel_hook=channel_hook, errlog=error_handler)
+                    tracking_stdio_client(
+                        server_params, channel_hook=channel_hook, errlog=error_handler
+                    )
                 )
             elif config.transport == "sse":
                 if not config.url:
@@ -434,38 +492,53 @@ class MCPConnectionManager(ContextDependent):
                     )
                 # Suppress MCP library error spam
                 self._suppress_mcp_sse_errors()
-                oauth_auth = build_oauth_provider(config)
-                # If using OAuth, strip any pre-existing Authorization headers to avoid conflicts
-                headers = dict(config.headers or {})
-                if oauth_auth is not None:
-                    headers.pop("Authorization", None)
-                    headers.pop("X-HF-Authorization", None)
-                return _add_none_to_context(
-                    sse_client(
-                        config.url,
-                        headers,
-                        sse_read_timeout=config.read_transport_sse_timeout_seconds,
-                        auth=oauth_auth,
+                headers, oauth_auth, user_auth_keys = _prepare_headers_and_auth(config)
+                if user_auth_keys:
+                    logger.debug(
+                        f"{server_name}: Using user-specified auth header(s); skipping OAuth provider.",
+                        user_auth_headers=sorted(user_auth_keys),
                     )
+                channel_hook = None
+                if transport_metrics is not None:
+
+                    def channel_hook(event):
+                        try:
+                            transport_metrics.record_event(event)
+                        except Exception:  # pragma: no cover - defensive guard
+                            logger.debug(
+                                "%s: transport metrics hook failed",
+                                server_name,
+                                exc_info=True,
+                            )
+
+                return tracking_sse_client(
+                    config.url,
+                    headers,
+                    sse_read_timeout=config.read_transport_sse_timeout_seconds,
+                    auth=oauth_auth,
+                    channel_hook=channel_hook,
                 )
             elif config.transport == "http":
                 if not config.url:
                     raise ValueError(
                         f"Server '{server_name}' uses http transport but no url is specified"
                     )
-                oauth_auth = build_oauth_provider(config)
-                headers = dict(config.headers or {})
-                if oauth_auth is not None:
-                    headers.pop("Authorization", None)
-                    headers.pop("X-HF-Authorization", None)
+                headers, oauth_auth, user_auth_keys = _prepare_headers_and_auth(config)
+                if user_auth_keys:
+                    logger.debug(
+                        f"{server_name}: Using user-specified auth header(s); skipping OAuth provider.",
+                        user_auth_headers=sorted(user_auth_keys),
+                    )
                 channel_hook = None
                 if transport_metrics is not None:
+
                     def channel_hook(event):
                         try:
                             transport_metrics.record_event(event)
                         except Exception:  # pragma: no cover - defensive guard
                             logger.debug(
-                                "%s: transport metrics hook failed", server_name,
+                                "%s: transport metrics hook failed",
+                                server_name,
                                 exc_info=True,
                             )
 

fast_agent/mcp/skybridge.py

@@ -0,0 +1,45 @@
+from typing import List
+
+from pydantic import AnyUrl, BaseModel, Field
+
+SKYBRIDGE_MIME_TYPE = "text/html+skybridge"
+
+
+class SkybridgeResourceConfig(BaseModel):
+    """Represents a Skybridge (apps SDK) resource exposed by an MCP server."""
+
+    uri: AnyUrl
+    mime_type: str | None = None
+    is_skybridge: bool = False
+    warning: str | None = None
+
+
+class SkybridgeToolConfig(BaseModel):
+    """Represents Skybridge metadata discovered for a tool."""
+
+    tool_name: str
+    namespaced_tool_name: str
+    template_uri: AnyUrl | None = None
+    resource_uri: AnyUrl | None = None
+    is_valid: bool = False
+    warning: str | None = None
+
+    @property
+    def display_name(self) -> str:
+        return self.namespaced_tool_name or self.tool_name
+
+
+class SkybridgeServerConfig(BaseModel):
+    """Skybridge configuration discovered for a specific MCP server."""
+
+    server_name: str
+    supports_resources: bool = False
+    ui_resources: List[SkybridgeResourceConfig] = Field(default_factory=list)
+    warnings: List[str] = Field(default_factory=list)
+    tools: List[SkybridgeToolConfig] = Field(default_factory=list)
+
+    @property
+    def enabled(self) -> bool:
+        """Return True when at least one resource advertises the Skybridge MIME type."""
+        return any(resource.is_skybridge for resource in self.ui_resources)
+

fast_agent/mcp/sse_tracking.py

@@ -0,0 +1,287 @@
+"""SSE transport wrapper that emits channel events for UI display."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable
+from urllib.parse import parse_qs, urljoin, urlparse
+
+import anyio
+import httpx
+import mcp.types as types
+from httpx_sse import aconnect_sse
+from httpx_sse._exceptions import SSEError
+from mcp.shared._httpx_utils import McpHttpClientFactory, create_mcp_http_client
+from mcp.shared.message import SessionMessage
+
+from fast_agent.mcp.transport_tracking import ChannelEvent, ChannelName
+
+if TYPE_CHECKING:
+    from anyio.abc import TaskStatus
+    from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+
+logger = logging.getLogger(__name__)
+
+ChannelHook = Callable[[ChannelEvent], None]
+
+
+def _extract_session_id(endpoint_url: str) -> str | None:
+    parsed = urlparse(endpoint_url)
+    query_params = parse_qs(parsed.query)
+    for key in ("sessionId", "session_id", "session"):
+        values = query_params.get(key)
+        if values:
+            return values[0]
+    return None
+
+
+def _emit_channel_event(
+    channel_hook: ChannelHook | None,
+    channel: ChannelName,
+    event_type: str,
+    *,
+    message: types.JSONRPCMessage | None = None,
+    raw_event: str | None = None,
+    detail: str | None = None,
+    status_code: int | None = None,
+) -> None:
+    if channel_hook is None:
+        return
+    try:
+        channel_hook(
+            ChannelEvent(
+                channel=channel,
+                event_type=event_type,  # type: ignore[arg-type]
+                message=message,
+                raw_event=raw_event,
+                detail=detail,
+                status_code=status_code,
+            )
+        )
+    except Exception:
+        logger.debug("Channel hook raised an exception", exc_info=True)
+
+
+def _format_http_error(exc: httpx.HTTPStatusError) -> tuple[int | None, str]:
+    status_code: int | None = None
+    detail = str(exc)
+    if exc.response is not None:
+        status_code = exc.response.status_code
+        reason = exc.response.reason_phrase or ""
+        if not reason:
+            try:
+                reason = (exc.response.text or "").strip()
+            except Exception:
+                reason = ""
+        detail = f"HTTP {status_code}: {reason or 'response'}"
+    return status_code, detail
+
+
+@asynccontextmanager
+async def tracking_sse_client(
+    url: str,
+    headers: dict[str, Any] | None = None,
+    timeout: float = 5,
+    sse_read_timeout: float = 60 * 5,
+    httpx_client_factory: McpHttpClientFactory = create_mcp_http_client,
+    auth: httpx.Auth | None = None,
+    channel_hook: ChannelHook | None = None,
+) -> AsyncGenerator[
+    tuple[
+        MemoryObjectReceiveStream[SessionMessage | Exception],
+        MemoryObjectSendStream[SessionMessage],
+        Callable[[], str | None],
+    ],
+    None,
+]:
+    """
+    Client transport for SSE with channel activity tracking.
+    """
+
+    read_stream_writer, read_stream = anyio.create_memory_object_stream[SessionMessage | Exception](
+        0
+    )
+    write_stream, write_stream_reader = anyio.create_memory_object_stream[SessionMessage](0)
+
+    session_id: str | None = None
+
+    def get_session_id() -> str | None:
+        return session_id
+
+    async with anyio.create_task_group() as tg:
+        try:
+            logger.debug("Connecting to SSE endpoint: %s", url)
+            async with httpx_client_factory(
+                headers=headers,
+                auth=auth,
+                timeout=httpx.Timeout(timeout, read=sse_read_timeout),
+            ) as client:
+                connected = False
+                post_connected = False
+
+                async def sse_reader(
+                    task_status: TaskStatus[str] = anyio.TASK_STATUS_IGNORED,
+                ):
+                    try:
+                        async for sse in event_source.aiter_sse():
+                            if sse.event == "endpoint":
+                                endpoint_url = urljoin(url, sse.data)
+                                logger.debug("Received SSE endpoint URL: %s", endpoint_url)
+
+                                url_parsed = urlparse(url)
+                                endpoint_parsed = urlparse(endpoint_url)
+                                if (
+                                    url_parsed.scheme != endpoint_parsed.scheme
+                                    or url_parsed.netloc != endpoint_parsed.netloc
+                                ):
+                                    error_msg = (
+                                        "Endpoint origin does not match connection origin: "
+                                        f"{endpoint_url}"
+                                    )
+                                    logger.error(error_msg)
+                                    _emit_channel_event(
+                                        channel_hook,
+                                        "get",
+                                        "error",
+                                        detail=error_msg,
+                                    )
+                                    raise ValueError(error_msg)
+
+                                nonlocal session_id
+                                session_id = _extract_session_id(endpoint_url)
+                                task_status.started(endpoint_url)
+                            elif sse.event == "message":
+                                try:
+                                    message = types.JSONRPCMessage.model_validate_json(sse.data)
+                                except Exception as exc:
+                                    logger.exception("Error parsing server message")
+                                    _emit_channel_event(
+                                        channel_hook,
+                                        "get",
+                                        "error",
+                                        detail="Error parsing server message",
+                                    )
+                                    await read_stream_writer.send(exc)
+                                    continue
+
+                                _emit_channel_event(channel_hook, "get", "message", message=message)
+                                await read_stream_writer.send(SessionMessage(message))
+                            else:
+                                _emit_channel_event(
+                                    channel_hook,
+                                    "get",
+                                    "keepalive",
+                                    raw_event=sse.event or "keepalive",
+                                )
+                    except SSEError as sse_exc:
+                        logger.exception("Encountered SSE exception")
+                        _emit_channel_event(
+                            channel_hook,
+                            "get",
+                            "error",
+                            detail=str(sse_exc),
+                        )
+                        raise
+                    except Exception as exc:
+                        logger.exception("Error in sse_reader")
+                        _emit_channel_event(
+                            channel_hook,
+                            "get",
+                            "error",
+                            detail=str(exc),
+                        )
+                        await read_stream_writer.send(exc)
+                    finally:
+                        await read_stream_writer.aclose()
+
+                async def post_writer(endpoint_url: str):
+                    try:
+                        async with write_stream_reader:
+                            async for session_message in write_stream_reader:
+                                try:
+                                    payload = session_message.message.model_dump(
+                                        by_alias=True,
+                                        mode="json",
+                                        exclude_none=True,
+                                    )
+                                except Exception:
+                                    logger.exception("Invalid session message payload")
+                                    continue
+
+                                _emit_channel_event(
+                                    channel_hook,
+                                    "post-sse",
+                                    "message",
+                                    message=session_message.message,
+                                )
+
+                                try:
+                                    response = await client.post(endpoint_url, json=payload)
+                                    response.raise_for_status()
+                                except httpx.HTTPStatusError as exc:
+                                    status_code, detail = _format_http_error(exc)
+                                    _emit_channel_event(
+                                        channel_hook,
+                                        "post-sse",
+                                        "error",
+                                        detail=detail,
+                                        status_code=status_code,
+                                    )
+                                    raise
+                    except httpx.HTTPStatusError:
+                        logger.exception("HTTP error in post_writer")
+                    except Exception:
+                        logger.exception("Error in post_writer")
+                        _emit_channel_event(
+                            channel_hook,
+                            "post-sse",
+                            "error",
+                            detail="Error sending client message",
+                        )
+                    finally:
+                        await write_stream.aclose()
+
+                try:
+                    async with aconnect_sse(
+                        client,
+                        "GET",
+                        url,
+                    ) as event_source:
+                        try:
+                            event_source.response.raise_for_status()
+                        except httpx.HTTPStatusError as exc:
+                            status_code, detail = _format_http_error(exc)
+                            _emit_channel_event(
+                                channel_hook,
+                                "get",
+                                "error",
+                                detail=detail,
+                                status_code=status_code,
+                            )
+                            raise
+
+                        _emit_channel_event(channel_hook, "get", "connect")
+                        connected = True
+
+                        endpoint_url = await tg.start(sse_reader)
+                        _emit_channel_event(channel_hook, "post-sse", "connect")
+                        post_connected = True
+                        tg.start_soon(post_writer, endpoint_url)
+
+                        try:
+                            yield read_stream, write_stream, get_session_id
+                        finally:
+                            tg.cancel_scope.cancel()
+                except Exception:
+                    raise
+                finally:
+                    if connected:
+                        _emit_channel_event(channel_hook, "get", "disconnect")
+                    if post_connected:
+                        _emit_channel_event(channel_hook, "post-sse", "disconnect")
+        finally:
+            await read_stream_writer.aclose()
+            await read_stream.aclose()
+            await write_stream_reader.aclose()
+            await write_stream.aclose()

fast_agent/mcp/transport_tracking.py

@@ -82,6 +82,8 @@ class ChannelSnapshot(BaseModel):
     response_count: int = 0
     notification_count: int = 0
     activity_buckets: list[str] | None = None
+    activity_bucket_seconds: int | None = None
+    activity_bucket_count: int | None = None
 
 
 class TransportSnapshot(BaseModel):
@@ -95,12 +97,18 @@ class TransportSnapshot(BaseModel):
     get: ChannelSnapshot | None = None
     resumption: ChannelSnapshot | None = None
     stdio: ChannelSnapshot | None = None
+    activity_bucket_seconds: int | None = None
+    activity_bucket_count: int | None = None
 
 
 class TransportChannelMetrics:
     """Aggregates low-level channel events into user-visible metrics."""
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        bucket_seconds: int | None = None,
+        bucket_count: int | None = None,
+    ) -> None:
         self._lock = Lock()
 
         self._post_modes: set[str] = set()
@@ -155,8 +163,22 @@ class TransportChannelMetrics:
 
         self._response_channel_by_id: dict[RequestId, ChannelName] = {}
 
-        self._history_bucket_seconds = 30
-        self._history_bucket_count = 20
+        try:
+            seconds = 30 if bucket_seconds is None else int(bucket_seconds)
+        except (TypeError, ValueError):
+            seconds = 30
+        if seconds <= 0:
+            seconds = 30
+
+        try:
+            count = 20 if bucket_count is None else int(bucket_count)
+        except (TypeError, ValueError):
+            count = 20
+        if count <= 0:
+            count = 20
+
+        self._history_bucket_seconds = seconds
+        self._history_bucket_count = count
         self._history_priority = {
             "error": 5,
             "disabled": 4,
@@ -463,6 +485,8 @@ class TransportChannelMetrics:
             last_message_summary=stats.last_summary,
             last_message_at=stats.last_at,
             activity_buckets=self._build_activity_buckets(f"post-{mode}", now),
+            activity_bucket_seconds=self._history_bucket_seconds,
+            activity_bucket_count=self._history_bucket_count,
         )
 
     def snapshot(self) -> TransportSnapshot:
@@ -503,6 +527,8 @@ class TransportChannelMetrics:
                     response_count=self._post_response_count,
                     notification_count=self._post_notification_count,
                     activity_buckets=self._merge_activity_buckets(["post-json", "post-sse"], now),
+                    activity_bucket_seconds=self._history_bucket_seconds,
+                    activity_bucket_count=self._history_bucket_count,
                 )
 
             post_json_snapshot = self._build_post_mode_snapshot("json", now)
@@ -543,6 +569,8 @@ class TransportChannelMetrics:
                     response_count=self._get_response_count,
                     notification_count=self._get_notification_count,
                     activity_buckets=self._build_activity_buckets("get", now),
+                    activity_bucket_seconds=self._history_bucket_seconds,
+                    activity_bucket_count=self._history_bucket_count,
                 )
 
             resumption_snapshot = None
@@ -555,6 +583,8 @@ class TransportChannelMetrics:
                     response_count=self._resumption_response_count,
                     notification_count=self._resumption_notification_count,
                     activity_buckets=self._build_activity_buckets("resumption", now),
+                    activity_bucket_seconds=self._history_bucket_seconds,
+                    activity_bucket_count=self._history_bucket_count,
                 )
 
             stdio_snapshot = None
@@ -588,6 +618,8 @@ class TransportChannelMetrics:
                     response_count=self._stdio_response_count,
                     notification_count=self._stdio_notification_count,
                     activity_buckets=self._build_activity_buckets("stdio", now),
+                    activity_bucket_seconds=self._history_bucket_seconds,
+                    activity_bucket_count=self._history_bucket_count,
                 )
 
             return TransportSnapshot(
@@ -597,4 +629,6 @@ class TransportChannelMetrics:
                 get=get_snapshot,
                 resumption=resumption_snapshot,
                 stdio=stdio_snapshot,
+                activity_bucket_seconds=self._history_bucket_seconds,
+                activity_bucket_count=self._history_bucket_count,
             )

fast_agent/mcp/types.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from fast_agent.interfaces import AgentProtocol
+
+if TYPE_CHECKING:
+    from fast_agent.context import Context
+    from fast_agent.mcp.mcp_aggregator import MCPAggregator
+    from fast_agent.ui.console_display import ConsoleDisplay
+
+
+@runtime_checkable
+class McpAgentProtocol(AgentProtocol, Protocol):
+    """Agent protocol with MCP-specific surface area."""
+
+    @property
+    def aggregator(self) -> MCPAggregator: ...
+
+    @property
+    def display(self) -> "ConsoleDisplay": ...
+
+    @property
+    def context(self) -> "Context | None": ...

fast_agent/resources/examples/workflows/router.py

@@ -60,6 +60,7 @@ async def main() -> None:
         await agent.interactive(agent_name="route")
         for request in SAMPLE_REQUESTS:
             await agent.route(request)
+        await agent.interactive()
 
 
 if __name__ == "__main__":

fast_agent/resources/setup/fastagent.config.yaml

@@ -15,6 +15,11 @@ default_model: gpt-5-mini.low
 # mcp_ui_output_dir: ".fast-agent/ui"  # Where to write MCP-UI HTML files (relative to CWD if not absolute)
 # mcp_ui_mode: enabled
 
+# MCP timeline display (adjust activity window/intervals in MCP UI + fast-agent check)
+#mcp_timeline:
+#  steps: 20         # number of timeline buckets to render
+#  step_seconds: 30  # seconds per bucket (accepts values like "45s", "2m")
+
 # Logging and Console Configuration:
 logger:
   # level: "debug" | "info" | "warning" | "error"