bareagent-cli 0.1.0__py3-none-any.whl

bareagent/mcp/transport/base.py

@@ -0,0 +1,149 @@
+"""Transport ABC + shared id-routing machinery."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from concurrent.futures import Future
+
+from ..errors import MCPProtocolError, MCPTransportError
+from ..protocol import Notification, Request, Response, encode_message
+
+NotificationCallback = Callable[[Notification], None]
+DisconnectCallback = Callable[[str], None]
+
+_log = logging.getLogger(__name__)
+
+
+class Transport(ABC):
+    """Abstract bidirectional message channel for one MCP server.
+
+    Concrete subclasses (stdio, http_legacy, http_streamable) implement
+    `start` / `send` / `close` / `is_alive`. The shared `request` / `notify`
+    helpers plus the pending-future routing live here so all transports route
+    server responses identically.
+
+    Subclasses must distinguish ``graceful close`` (user called ``close()``)
+    from ``unexpected disconnect`` (subprocess EOF, broken pipe, SSE stream
+    error) and only invoke the registered disconnect handler in the
+    unexpected case. See :meth:`_invoke_disconnect`.
+    """
+
+    def __init__(self) -> None:
+        self._pending: dict[int, Future[Response]] = {}
+        self._pending_lock = threading.Lock()
+        self._notification_callbacks: list[NotificationCallback] = []
+        self._callbacks_lock = threading.Lock()
+        self._disconnect_handler: DisconnectCallback | None = None
+        self._disconnect_invoked = False
+
+    @abstractmethod
+    def start(self) -> None:
+        """Open the underlying connection / launch the subprocess."""
+
+    @abstractmethod
+    def send(self, message: str) -> None:
+        """Write a single already-encoded JSON-RPC message."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release all resources (subprocess, sockets, threads)."""
+
+    @abstractmethod
+    def is_alive(self) -> bool:
+        """Return True while the underlying transport is healthy."""
+
+    def request(self, request: Request, *, timeout: float) -> Response:
+        """Send a request and block until the matching response arrives."""
+        future: Future[Response] = Future()
+        with self._pending_lock:
+            if request.id in self._pending:
+                raise MCPProtocolError(f"request id {request.id} already in flight")
+            self._pending[request.id] = future
+        try:
+            self.send(encode_message(request))
+        except BaseException:
+            with self._pending_lock:
+                self._pending.pop(request.id, None)
+            raise
+        try:
+            return future.result(timeout=timeout)
+        except TimeoutError as exc:
+            raise MCPProtocolError(
+                f"request {request.id} timed out after {timeout}s"
+            ) from exc
+        finally:
+            with self._pending_lock:
+                self._pending.pop(request.id, None)
+
+    def notify(self, notification: Notification) -> None:
+        """Send a notification (no response expected)."""
+        self.send(encode_message(notification))
+
+    def on_notification(self, callback: NotificationCallback) -> None:
+        """Register a server->client notification callback."""
+        with self._callbacks_lock:
+            self._notification_callbacks.append(callback)
+
+    def set_disconnect_handler(self, callback: DisconnectCallback | None) -> None:
+        """Register a one-shot callback for unexpected transport disconnects.
+
+        Called by subclass reader threads when they detect EOF / broken pipe /
+        unexpected stream termination — never on user-initiated ``close()``.
+        Passing ``None`` clears the handler.
+        """
+        self._disconnect_handler = callback
+
+    # --- internal hooks used by subclass readers ---
+
+    def _route_response(self, response: Response) -> None:
+        """Deliver a response to its waiting future, or drop it if abandoned."""
+        if response.id is None:
+            return  # parse-error responses with null id have no waiter
+        with self._pending_lock:
+            future = self._pending.get(response.id)
+        if future is None or future.done():
+            return  # orphan / late response — ignore per JSON-RPC convention
+        future.set_result(response)
+
+    def _route_notification(self, notification: Notification) -> None:
+        """Fan out a server->client notification to registered callbacks."""
+        with self._callbacks_lock:
+            callbacks = list(self._notification_callbacks)
+        for cb in callbacks:
+            try:
+                cb(notification)
+            except Exception:
+                # Callbacks must not break the reader thread.
+                pass
+
+    def _fail_all_pending(self, message: str) -> None:
+        """Signal connection loss to every in-flight request."""
+        with self._pending_lock:
+            pending = list(self._pending.items())
+            self._pending.clear()
+        for _, future in pending:
+            if not future.done():
+                future.set_exception(MCPTransportError(message))
+
+    def _invoke_disconnect(self, reason: str) -> None:
+        """Fire the disconnect handler exactly once on unexpected termination.
+
+        Subclasses call this from their reader thread when they detect an
+        unexpected disconnect (EOF, broken pipe, SSE stream broken, subprocess
+        died). Calls after the first one are no-ops so a reader that detects
+        the same condition twice does not double-notify the manager. A
+        graceful ``close()`` must not call this.
+        """
+        if self._disconnect_invoked:
+            return
+        self._disconnect_invoked = True
+        handler = self._disconnect_handler
+        if handler is None:
+            return
+        try:
+            handler(reason)
+        except Exception as exc:  # pragma: no cover — handler must never crash reader
+            _log.warning("MCP transport disconnect handler raised: %s", exc)

bareagent/mcp/transport/http_legacy.py

@@ -0,0 +1,192 @@
+"""MCP 2024-11-05 HTTP+SSE transport (two endpoints).
+
+Connection lifecycle:
+
+1. `start()` opens a long-lived SSE GET to `url`. The first SSE event MUST be
+   `event: endpoint`, with `data` = the POST endpoint URL (a plain string,
+   not JSON). That URL becomes the write target.
+2. `send()` POSTs each JSON-RPC envelope to the captured endpoint.
+3. All server -> client traffic (responses + notifications) arrives as
+   `event: message` SSE events whose data field is one JSON-RPC envelope.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from urllib.parse import urljoin
+
+import httpx
+
+from .._sse import parse_sse_stream
+from ..errors import MCPProtocolError, MCPTransportError
+from ..protocol import Notification, Request, Response, decode_message
+from .base import Transport
+
+_log = logging.getLogger(__name__)
+
+_PROTOCOL_VERSION = "2024-11-05"
+_PROTOCOL_HEADERS_GET = {
+    "Accept": "text/event-stream",
+    "MCP-Protocol-Version": _PROTOCOL_VERSION,
+}
+_PROTOCOL_HEADERS_POST = {
+    "Content-Type": "application/json",
+    "Accept": "application/json, text/event-stream",
+    "MCP-Protocol-Version": _PROTOCOL_VERSION,
+}
+
+
+class HttpLegacyTransport(Transport):
+    """Two-endpoint MCP HTTP transport (GET SSE + POST writes)."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        start_timeout: float = 10.0,
+    ) -> None:
+        super().__init__()
+        self._url = url
+        self._user_headers = dict(headers or {})
+        self._start_timeout = start_timeout
+        self._client: httpx.Client | None = None
+        self._response: httpx.Response | None = None
+        self._stream_cm = None  # type: ignore[var-annotated]
+        self._reader: threading.Thread | None = None
+        self._endpoint_url: str | None = None
+        self._endpoint_event = threading.Event()
+        self._closed = False
+        # Reader uses ``_closing`` to skip the disconnect handler when shutdown
+        # is user-initiated. Set by ``close()`` before tearing down the stream.
+        self._closing = False
+
+    def start(self) -> None:
+        if self._client is not None:
+            raise RuntimeError("HttpLegacyTransport already started")
+        timeout = httpx.Timeout(
+            connect=self._start_timeout, read=None, write=10.0, pool=10.0
+        )
+        self._client = httpx.Client(timeout=timeout)
+        headers = self._merge_headers(_PROTOCOL_HEADERS_GET)
+        try:
+            self._stream_cm = self._client.stream("GET", self._url, headers=headers)
+            self._response = self._stream_cm.__enter__()
+            self._response.raise_for_status()
+        except httpx.HTTPError as exc:
+            self._cleanup()
+            raise MCPTransportError(f"failed to open SSE stream: {exc}") from exc
+
+        self._reader = threading.Thread(
+            target=self._read_loop, name="mcp-http-legacy-reader", daemon=True
+        )
+        self._reader.start()
+
+        if not self._endpoint_event.wait(timeout=self._start_timeout):
+            self.close()
+            raise MCPTransportError(
+                "did not receive endpoint event within start timeout"
+            )
+
+    def send(self, message: str) -> None:
+        if self._closed:
+            raise MCPTransportError("transport is closed")
+        if self._client is None or self._endpoint_url is None:
+            raise MCPTransportError("transport not started")
+        headers = self._merge_headers(_PROTOCOL_HEADERS_POST)
+        try:
+            resp = self._client.post(
+                self._endpoint_url, headers=headers, content=message.encode("utf-8")
+            )
+            resp.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise MCPTransportError(f"POST failed: {exc}") from exc
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._closing = True
+        self._cleanup()
+        self._fail_all_pending("HTTP legacy transport closed")
+
+    def is_alive(self) -> bool:
+        return (
+            not self._closed
+            and self._client is not None
+            and self._endpoint_url is not None
+        )
+
+    # --- internals ---
+
+    def _merge_headers(self, base: dict[str, str]) -> dict[str, str]:
+        # User-supplied headers must not override protocol-mandated ones.
+        merged = dict(self._user_headers)
+        merged.update(base)
+        return merged
+
+    def _cleanup(self) -> None:
+        if self._stream_cm is not None:
+            try:
+                self._stream_cm.__exit__(None, None, None)
+            except Exception:
+                pass
+            self._stream_cm = None
+        if self._client is not None:
+            try:
+                self._client.close()
+            except Exception:
+                pass
+
+    def _read_loop(self) -> None:
+        assert self._response is not None
+        disconnect_reason: str | None = None
+        try:
+            for event in parse_sse_stream(self._response.iter_lines()):
+                if event["event"] == "endpoint":
+                    self._on_endpoint(event["data"])
+                elif event["event"] == "message":
+                    self._on_message(event["data"])
+                else:
+                    _log.warning(
+                        "MCP http_legacy: unknown SSE event %r", event["event"]
+                    )
+        except httpx.HTTPError as exc:
+            disconnect_reason = f"SSE stream broken: {exc}"
+            _log.warning("MCP http_legacy: SSE stream broken: %s", exc)
+        except Exception as exc:  # pragma: no cover — defensive
+            disconnect_reason = f"reader crashed: {exc}"
+            _log.warning("MCP http_legacy reader crashed: %s", exc)
+        finally:
+            if not self._closing:
+                self._invoke_disconnect(
+                    disconnect_reason or "SSE stream ended unexpectedly"
+                )
+            self._fail_all_pending("SSE stream closed (server disconnect or error)")
+
+    def _on_endpoint(self, data: str) -> None:
+        # data is a relative or absolute URL string; resolve against the base URL.
+        endpoint = data.strip()
+        if not endpoint:
+            _log.warning("MCP http_legacy: empty endpoint event")
+            return
+        self._endpoint_url = urljoin(self._url, endpoint)
+        self._endpoint_event.set()
+
+    def _on_message(self, data: str) -> None:
+        try:
+            msg = decode_message(data)
+        except MCPProtocolError as exc:
+            _log.warning("MCP http_legacy: bad message event: %s", exc)
+            return
+        if isinstance(msg, Response):
+            self._route_response(msg)
+        elif isinstance(msg, Notification):
+            self._route_notification(msg)
+        else:
+            # Server-to-client Request: not handled in PR1.
+            assert isinstance(msg, Request)
+            _log.warning(
+                "MCP http_legacy: ignoring server-to-client request %r", msg.method
+            )

bareagent/mcp/transport/http_streamable.py

@@ -0,0 +1,217 @@
+"""MCP 2025-03-26 Streamable HTTP transport (single endpoint).
+
+Key differences vs HTTP legacy:
+
+- One URL handles both directions. POST writes go to `url`; the server
+  responds with either `application/json` (a single envelope) or
+  `text/event-stream` (one or more `event: message` envelopes then closes).
+- An optional long-lived GET stream is opened for server -> client
+  notifications. If the server returns 405 / 404 for the GET we silently
+  fall back to POST-only mode.
+- Session continuity uses the `Mcp-Session-Id` response header echoed on
+  every subsequent request.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+
+import httpx
+
+from .._sse import parse_sse_stream
+from ..errors import MCPProtocolError, MCPTransportError
+from ..protocol import Notification, Request, Response, decode_message
+from .base import Transport
+
+_log = logging.getLogger(__name__)
+
+_PROTOCOL_VERSION = "2025-06-18"
+_SESSION_HEADER = "Mcp-Session-Id"
+_PROTOCOL_HEADERS_BASE = {
+    "Accept": "application/json, text/event-stream",
+    "MCP-Protocol-Version": _PROTOCOL_VERSION,
+}
+_PROTOCOL_HEADERS_POST = {**_PROTOCOL_HEADERS_BASE, "Content-Type": "application/json"}
+
+
+class HttpStreamableTransport(Transport):
+    """Single-endpoint MCP HTTP transport per the 2025-03-26 spec."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        start_timeout: float = 10.0,
+    ) -> None:
+        super().__init__()
+        self._url = url
+        self._user_headers = dict(headers or {})
+        self._start_timeout = start_timeout
+        self._client: httpx.Client | None = None
+        self._listen_response: httpx.Response | None = None
+        self._listen_cm = None  # type: ignore[var-annotated]
+        self._listen_thread: threading.Thread | None = None
+        self._session_id: str | None = None
+        self._session_lock = threading.Lock()
+        self._closed = False
+        # Distinguishes ``close()``-initiated shutdown from real disconnects so
+        # the reader thread does not fire the disconnect handler on a normal
+        # exit.
+        self._closing = False
+
+    def start(self) -> None:
+        if self._client is not None:
+            raise RuntimeError("HttpStreamableTransport already started")
+        timeout = httpx.Timeout(
+            connect=self._start_timeout, read=None, write=10.0, pool=10.0
+        )
+        self._client = httpx.Client(timeout=timeout)
+
+        # Best-effort GET for server-push notifications. Servers may refuse.
+        try:
+            headers = self._merge_headers(_PROTOCOL_HEADERS_BASE)
+            self._listen_cm = self._client.stream("GET", self._url, headers=headers)
+            response = self._listen_cm.__enter__()
+            if response.status_code >= 400:
+                # Server doesn't offer a listening stream; that's fine for POST-only.
+                self._listen_cm.__exit__(None, None, None)
+                self._listen_cm = None
+                self._listen_response = None
+            else:
+                self._capture_session(response)
+                self._listen_response = response
+                self._listen_thread = threading.Thread(
+                    target=self._listen_loop, name="mcp-http-stream-reader", daemon=True
+                )
+                self._listen_thread.start()
+        except httpx.HTTPError as exc:
+            # Listening stream is optional — log and continue with POST-only mode.
+            _log.warning("MCP http_streamable: GET listen stream unavailable: %s", exc)
+            if self._listen_cm is not None:
+                try:
+                    self._listen_cm.__exit__(None, None, None)
+                except Exception:
+                    pass
+                self._listen_cm = None
+
+    def send(self, message: str) -> None:
+        if self._closed:
+            raise MCPTransportError("transport is closed")
+        if self._client is None:
+            raise MCPTransportError("transport not started")
+        headers = self._merge_headers(_PROTOCOL_HEADERS_POST)
+        try:
+            resp = self._client.post(
+                self._url, headers=headers, content=message.encode("utf-8")
+            )
+            resp.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise MCPTransportError(f"POST failed: {exc}") from exc
+
+        self._capture_session(resp)
+        self._handle_response_body(resp)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._closing = True
+        if self._listen_cm is not None:
+            try:
+                self._listen_cm.__exit__(None, None, None)
+            except Exception:
+                pass
+            self._listen_cm = None
+        if self._client is not None:
+            try:
+                self._client.close()
+            except Exception:
+                pass
+        self._fail_all_pending("HTTP streamable transport closed")
+
+    def is_alive(self) -> bool:
+        return not self._closed and self._client is not None
+
+    # --- internals ---
+
+    def _merge_headers(self, base: dict[str, str]) -> dict[str, str]:
+        merged = dict(self._user_headers)
+        merged.update(base)
+        with self._session_lock:
+            if self._session_id is not None:
+                merged[_SESSION_HEADER] = self._session_id
+        return merged
+
+    def _capture_session(self, response: httpx.Response) -> None:
+        session = response.headers.get(_SESSION_HEADER)
+        if session:
+            with self._session_lock:
+                self._session_id = session
+
+    def _handle_response_body(self, response: httpx.Response) -> None:
+        # POST body can be either a single JSON envelope or an SSE stream.
+        content_type = response.headers.get("Content-Type", "").lower()
+        if "text/event-stream" in content_type:
+            try:
+                for event in parse_sse_stream(response.iter_lines()):
+                    if event["event"] == "message":
+                        self._on_message(event["data"])
+                    else:
+                        _log.warning(
+                            "MCP http_streamable: unknown SSE event %r in POST response",
+                            event["event"],
+                        )
+            except httpx.HTTPError as exc:
+                _log.warning("MCP http_streamable: POST SSE stream broken: %s", exc)
+            return
+        if not response.content:
+            return  # 202 Accepted with empty body — response will arrive on listen stream
+        if "application/json" in content_type or response.content.lstrip().startswith(
+            b"{"
+        ):
+            self._on_message(response.text)
+            return
+        _log.warning("MCP http_streamable: unexpected Content-Type %r", content_type)
+
+    def _listen_loop(self) -> None:
+        assert self._listen_response is not None
+        disconnect_reason: str | None = None
+        try:
+            for event in parse_sse_stream(self._listen_response.iter_lines()):
+                if event["event"] == "message":
+                    self._on_message(event["data"])
+                else:
+                    _log.warning(
+                        "MCP http_streamable: unknown SSE event %r on listen stream",
+                        event["event"],
+                    )
+        except httpx.HTTPError as exc:
+            disconnect_reason = f"listen stream broken: {exc}"
+            _log.warning("MCP http_streamable: listen stream broken: %s", exc)
+        except Exception as exc:  # pragma: no cover — defensive
+            disconnect_reason = f"listener crashed: {exc}"
+            _log.warning("MCP http_streamable listener crashed: %s", exc)
+        finally:
+            if not self._closing:
+                self._invoke_disconnect(
+                    disconnect_reason or "HTTP streamable listen stream ended"
+                )
+            self._fail_all_pending("HTTP streamable listen stream closed")
+
+    def _on_message(self, data: str) -> None:
+        try:
+            msg = decode_message(data)
+        except MCPProtocolError as exc:
+            _log.warning("MCP http_streamable: bad message: %s", exc)
+            return
+        if isinstance(msg, Response):
+            self._route_response(msg)
+        elif isinstance(msg, Notification):
+            self._route_notification(msg)
+        else:
+            assert isinstance(msg, Request)
+            _log.warning(
+                "MCP http_streamable: ignoring server-to-client request %r", msg.method
+            )