bareagent-cli 0.1.0__py3-none-any.whl

bareagent/mcp/__init__.py

@@ -0,0 +1,69 @@
+"""MCP (Model Context Protocol) client subpackage.
+
+PR1 delivered the transport + protocol scaffolding. PR2 adds the client
+lifecycle (``MCPClient``), multi-server orchestration (``MCPManager``), and
+the BareAgent tool registry shims (``build_mcp_tool_schemas`` /
+``build_mcp_handlers``). Resources / prompts / multimodal passthrough /
+REPL plumbing / atexit cleanup arrive in subsequent PRs.
+"""
+
+from __future__ import annotations
+
+from .client import MCPClient
+from .config import MCPConfig, MCPServerConfig, parse_mcp_config
+from .errors import (
+    MCPCallError,
+    MCPError,
+    MCPHandshakeError,
+    MCPProtocolError,
+    MCPTransportError,
+)
+from .manager import MCPManager, ServerStatus
+from .protocol import (
+    ErrorObject,
+    Notification,
+    Request,
+    Response,
+    decode_message,
+    encode_message,
+    new_request_id,
+)
+from .registry import (
+    build_mcp_handlers,
+    build_mcp_tool_schemas,
+    mcp_tool_name,
+)
+from .transport import (
+    HttpLegacyTransport,
+    HttpStreamableTransport,
+    StdioTransport,
+    Transport,
+)
+
+__all__ = [
+    "ErrorObject",
+    "HttpLegacyTransport",
+    "HttpStreamableTransport",
+    "MCPCallError",
+    "MCPClient",
+    "MCPConfig",
+    "MCPError",
+    "MCPHandshakeError",
+    "MCPManager",
+    "MCPProtocolError",
+    "MCPServerConfig",
+    "MCPTransportError",
+    "Notification",
+    "Request",
+    "Response",
+    "ServerStatus",
+    "StdioTransport",
+    "Transport",
+    "build_mcp_handlers",
+    "build_mcp_tool_schemas",
+    "decode_message",
+    "encode_message",
+    "mcp_tool_name",
+    "new_request_id",
+    "parse_mcp_config",
+]

bareagent/mcp/_sse.py

@@ -0,0 +1,69 @@
+"""Minimal Server-Sent Events parser per WHATWG.
+
+Used by both HTTP transports. Pure-functional: takes an iterable of already-
+split lines (no trailing newlines) and yields event dicts. Last-Event-ID
+reconnect is deferred to a later PR.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from typing import TypedDict
+
+_BOM = ""
+
+
+class SSEEvent(TypedDict):
+    event: str
+    data: str
+    id: str
+    retry: int | None
+
+
+def parse_sse_stream(lines: Iterable[str]) -> Iterator[SSEEvent]:
+    """Yield SSE events from already-split lines.
+
+    Caller must split on `\\r?\\n` and not include trailing line terminators
+    (httpx `iter_lines()` already does this). Empty line dispatches an event.
+    """
+    event_type = ""
+    data: list[str] = []
+    last_id = ""
+    retry: int | None = None
+    first = True
+
+    for raw in lines:
+        if first:
+            first = False
+            if raw.startswith(_BOM):
+                raw = raw[1:]
+        if raw == "":
+            if data:
+                yield SSEEvent(
+                    event=event_type or "message",
+                    data="\n".join(data),
+                    id=last_id,
+                    retry=retry,
+                )
+            event_type = ""
+            data = []
+            retry = None
+            continue
+        if raw.startswith(":"):
+            continue  # comment / heartbeat
+        field, sep, value = raw.partition(":")
+        if not sep:
+            # No colon means the whole line is the field name with empty value.
+            field, value = raw, ""
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "event":
+            event_type = value
+        elif field == "data":
+            data.append(value)
+        elif field == "id":
+            if "\x00" not in value:
+                last_id = value
+        elif field == "retry" and value.isdigit():
+            retry = int(value)
+        # unknown fields are silently ignored per spec

bareagent/mcp/client.py

@@ -0,0 +1,341 @@
+"""Single-server MCP client: initialize handshake + tools / resources / prompts.
+
+The client owns the JSON-RPC dialogue but not the connection: a constructed
+``Transport`` is passed in by the manager so unit tests can substitute a fake.
+PR3 adds resources (``resources/list`` + ``resources/read``) and prompts
+(``prompts/list`` cached at handshake time + ``prompts/get`` on demand). Tools
+remain lazy, as in PR2.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from threading import Lock
+from typing import Any
+
+from .config import MCPServerConfig
+from .errors import MCPCallError, MCPHandshakeError, MCPProtocolError, MCPTransportError
+from .protocol import Notification, Request, new_request_id
+from .transport.base import Transport
+
+_log = logging.getLogger(__name__)
+
+# Latest MCP version BareAgent understands. Servers may negotiate down.
+_CLIENT_PROTOCOL_VERSION = "2025-06-18"
+_CLIENT_INFO = {"name": "BareAgent", "version": "0.1.0"}
+
+# PRD: only ``[a-zA-Z0-9_-]`` survive — prompt names with other characters can't
+# safely round-trip through the ``/mcp:<server>:<prompt>`` REPL syntax, so the
+# client drops them at catalog time and warns.
+_PROMPT_NAME_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
+
+
+class MCPClient:
+    """One MCP server connection.
+
+    Lifecycle: ``start()`` runs the initialize handshake; ``list_tools()`` and
+    ``call_tool()`` are the operational surface; ``close()`` shuts down the
+    transport. Methods are threadsafe — the underlying transport already
+    serializes writes, and the tool cache is guarded by a local lock.
+    """
+
+    def __init__(self, config: MCPServerConfig, transport: Transport) -> None:
+        self._config = config
+        self._transport = transport
+        self._cache_lock = Lock()
+        self._tools_cache: list[dict[str, Any]] | None = None
+        self._prompts: list[dict[str, Any]] | None = None
+        self._server_info: dict[str, Any] = {}
+        self._server_capabilities: dict[str, Any] = {}
+        self._negotiated_version: str | None = None
+        self._started = False
+
+    @property
+    def name(self) -> str:
+        return self._config.name
+
+    @property
+    def server_info(self) -> dict[str, Any]:
+        return dict(self._server_info)
+
+    @property
+    def server_capabilities(self) -> dict[str, Any]:
+        return dict(self._server_capabilities)
+
+    def start(self, timeout: float) -> None:
+        """Open the transport and run the initialize handshake.
+
+        Raises ``MCPHandshakeError`` on timeout, JSON-RPC error, or any
+        transport-level failure during handshake. Successful return guarantees
+        the server has acknowledged ``notifications/initialized``.
+        """
+        if self._started:
+            raise MCPHandshakeError(f"client {self._config.name!r} already started")
+        try:
+            self._transport.start()
+        except MCPTransportError as exc:
+            raise MCPHandshakeError(f"transport start failed: {exc}") from exc
+
+        init_request = Request(
+            id=new_request_id(),
+            method="initialize",
+            params={
+                "protocolVersion": _CLIENT_PROTOCOL_VERSION,
+                "capabilities": {},  # PR2: client offers no capabilities
+                "clientInfo": _CLIENT_INFO,
+            },
+        )
+        try:
+            response = self._transport.request(init_request, timeout=timeout)
+        except (MCPTransportError, MCPProtocolError) as exc:
+            self._safe_close()
+            raise MCPHandshakeError(f"initialize failed: {exc}") from exc
+
+        if response.error is not None:
+            self._safe_close()
+            raise MCPHandshakeError(
+                f"initialize returned error: {response.error.code} {response.error.message}"
+            )
+
+        result = response.result if isinstance(response.result, dict) else {}
+        self._negotiated_version = result.get("protocolVersion")
+        info = result.get("serverInfo")
+        if isinstance(info, dict):
+            self._server_info = info
+        caps = result.get("capabilities")
+        if isinstance(caps, dict):
+            self._server_capabilities = caps
+
+        try:
+            self._transport.notify(Notification(method="notifications/initialized"))
+        except MCPTransportError as exc:
+            self._safe_close()
+            raise MCPHandshakeError(
+                f"failed to send initialized notification: {exc}"
+            ) from exc
+
+        self._started = True
+
+        # Eagerly cache the prompts catalog if the server declared the capability.
+        # Failures here must not undo the handshake — log + fall back to empty.
+        if self.has_capability("prompts"):
+            try:
+                self._prompts = self._fetch_prompts(timeout=timeout)
+            except (MCPCallError, MCPProtocolError, MCPTransportError) as exc:
+                _log.warning(
+                    "MCP server %r prompts/list failed during start: %s",
+                    self._config.name,
+                    exc,
+                )
+                self._prompts = []
+
+    def list_tools(self, *, timeout: float = 30.0) -> list[dict[str, Any]]:
+        """Return cached or freshly fetched ``tools/list`` entries.
+
+        Each entry preserves the raw ``name`` / ``description`` / ``inputSchema``
+        from the server (the registry layer adds the ``mcp__<server>__`` prefix
+        when assembling BareAgent schemas).
+        """
+        with self._cache_lock:
+            if self._tools_cache is not None:
+                return list(self._tools_cache)
+
+        if "tools" not in self._server_capabilities:
+            # Server didn't declare tools capability — skip the call, cache empty.
+            # Note: an empty dict ``{}`` still means "supported, no sub-capabilities",
+            # so presence (not truthiness) is the right check.
+            with self._cache_lock:
+                self._tools_cache = []
+                return []
+
+        request = Request(id=new_request_id(), method="tools/list")
+        response = self._transport.request(request, timeout=timeout)
+        if response.error is not None:
+            raise MCPCallError(
+                f"MCP Error: {response.error.code} {response.error.message}"
+            )
+        result = response.result if isinstance(response.result, dict) else {}
+        tools = result.get("tools")
+        if not isinstance(tools, list):
+            tools = []
+        # Filter out anything missing the required fields.
+        cleaned: list[dict[str, Any]] = []
+        for tool in tools:
+            if not isinstance(tool, dict):
+                continue
+            name = tool.get("name")
+            if not isinstance(name, str) or not name:
+                continue
+            cleaned.append(tool)
+        with self._cache_lock:
+            self._tools_cache = cleaned
+        return list(cleaned)
+
+    def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        timeout: float = 60.0,
+    ) -> dict[str, Any]:
+        """Invoke a tool on the server and return the raw ``result`` object.
+
+        ``isError: true`` is intentionally NOT raised — the registry layer
+        formats it into a plain ``Error: ...`` string so the LLM sees the
+        failure as data and can retry. JSON-RPC protocol errors do raise
+        (``MCPCallError`` with the ``MCP Error: <code> <message>`` prefix).
+        """
+        request = Request(
+            id=new_request_id(),
+            method="tools/call",
+            params={"name": name, "arguments": arguments or {}},
+        )
+        response = self._transport.request(request, timeout=timeout)
+        if response.error is not None:
+            raise MCPCallError(
+                f"MCP Error: {response.error.code} {response.error.message}"
+            )
+        result = response.result
+        if not isinstance(result, dict):
+            return {"content": [], "isError": False}
+        return result
+
+    def has_capability(self, name: str) -> bool:
+        """Return True if the server declared the named top-level capability.
+
+        Per MCP 2025-06-18, ``capabilities`` is a flat object whose keys (``tools``,
+        ``resources``, ``prompts``, ``logging``, …) signal *presence*; sub-flags
+        like ``{"prompts": {"listChanged": true}}`` are advisory. PR3 only checks
+        key presence.
+        """
+        return name in self._server_capabilities
+
+    def list_prompts(self) -> list[dict[str, Any]]:
+        """Return the prompts catalog cached during ``start()``.
+
+        Never re-fetches: the catalog is populated at handshake time, and if the
+        server didn't declare the prompts capability the result is the empty
+        list. (Prompts can change via ``notifications/prompts/list_changed`` —
+        that subscription is deferred to a later PR.)
+        """
+        return list(self._prompts or [])
+
+    def get_prompt(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        timeout: float = 30.0,
+    ) -> dict[str, Any]:
+        """Invoke ``prompts/get`` and return the raw result.
+
+        The result typically contains a ``messages`` array shaped for the LLM
+        ({role, content}). JSON-RPC errors raise ``MCPCallError`` so the REPL
+        dispatcher can render the message verbatim; per-message field validation
+        is left to the caller (the spec allows server-specific extensions).
+        """
+        request = Request(
+            id=new_request_id(),
+            method="prompts/get",
+            params={"name": name, "arguments": arguments or {}},
+        )
+        response = self._transport.request(request, timeout=timeout)
+        if response.error is not None:
+            raise MCPCallError(
+                f"MCP Error: {response.error.code} {response.error.message}"
+            )
+        result = response.result
+        if not isinstance(result, dict):
+            return {"messages": []}
+        return result
+
+    def list_resources(self, *, timeout: float = 30.0) -> list[dict[str, Any]]:
+        """Fetch ``resources/list`` fresh — not cached because resources are dynamic.
+
+        Returns the raw ``resources`` array (entries typically have ``uri`` /
+        ``name`` / ``description`` / ``mimeType``). Servers that omit the
+        capability still get the call attempted by the registry handler; the
+        handler is expected to guard the call site.
+        """
+        request = Request(id=new_request_id(), method="resources/list")
+        response = self._transport.request(request, timeout=timeout)
+        if response.error is not None:
+            raise MCPCallError(
+                f"MCP Error: {response.error.code} {response.error.message}"
+            )
+        result = response.result if isinstance(response.result, dict) else {}
+        resources = result.get("resources")
+        if not isinstance(resources, list):
+            return []
+        return [item for item in resources if isinstance(item, dict)]
+
+    def read_resource(self, uri: str, *, timeout: float = 60.0) -> dict[str, Any]:
+        """Invoke ``resources/read`` and return the raw result.
+
+        ``contents`` is preserved verbatim (each block has ``type`` /
+        ``text`` / ``blob`` / ``uri`` / ``mimeType`` depending on the source);
+        ``isError: true`` is intentionally not raised — the registry layer
+        flattens it into a ``Error: ...`` string for the LLM, mirroring the
+        ``call_tool`` convention.
+        """
+        request = Request(
+            id=new_request_id(),
+            method="resources/read",
+            params={"uri": uri},
+        )
+        response = self._transport.request(request, timeout=timeout)
+        if response.error is not None:
+            raise MCPCallError(
+                f"MCP Error: {response.error.code} {response.error.message}"
+            )
+        result = response.result
+        if not isinstance(result, dict):
+            return {"contents": [], "isError": False}
+        return result
+
+    def close(self) -> None:
+        """Tear down the transport. Idempotent."""
+        self._safe_close()
+
+    def is_alive(self) -> bool:
+        return self._started and self._transport.is_alive()
+
+    def _fetch_prompts(self, *, timeout: float) -> list[dict[str, Any]]:
+        request = Request(id=new_request_id(), method="prompts/list")
+        response = self._transport.request(request, timeout=timeout)
+        if response.error is not None:
+            raise MCPCallError(
+                f"MCP Error: {response.error.code} {response.error.message}"
+            )
+        result = response.result if isinstance(response.result, dict) else {}
+        prompts = result.get("prompts")
+        if not isinstance(prompts, list):
+            return []
+        cleaned: list[dict[str, Any]] = []
+        for prompt in prompts:
+            if not isinstance(prompt, dict):
+                continue
+            name = prompt.get("name")
+            if not isinstance(name, str) or not name:
+                continue
+            if not _PROMPT_NAME_RE.match(name):
+                # Names outside [a-zA-Z0-9_-] would collide with the
+                # ``/mcp:<server>:<prompt>`` REPL syntax. Skip + warn rather
+                # than silently surface unusable entries.
+                _log.warning(
+                    "MCP server %r prompt %r contains characters outside "
+                    "[a-zA-Z0-9_-]; skipping",
+                    self._config.name,
+                    name,
+                )
+                continue
+            cleaned.append(prompt)
+        return cleaned
+
+    def _safe_close(self) -> None:
+        try:
+            self._transport.close()
+        except Exception:
+            # Closing must never raise — keeps manager shutdown loops simple.
+            pass

bareagent/mcp/config.py

@@ -0,0 +1,169 @@
+"""MCP server configuration parsing.
+
+Reads a `[mcp]` block (plus `[[mcp.servers]]` array) from a TOML-derived dict
+and returns typed dataclasses. The transport field selects which server-side
+fields are required.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import MCPError
+
+_VALID_TRANSPORTS = ("stdio", "http_legacy", "http_streamable")
+
+# 256 KiB. The text result of a single MCP tool call lands directly in the
+# next LLM turn; anything significantly larger blows past the typical
+# context window before the model even sees the rest of the turn.
+_DEFAULT_MAX_TEXT_BYTES = 262_144  # 256 KiB
+_DEFAULT_MAX_BINARY_BYTES = 5_242_880  # 5 MiB
+_DEFAULT_START_TIMEOUT = 10.0
+
+
+@dataclass(slots=True)
+class MCPServerConfig:
+    """One MCP server entry. Required fields depend on transport."""
+
+    name: str
+    transport: str
+    # stdio fields:
+    command: list[str] = field(default_factory=list)
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    cwd: str | None = None
+    # http_* fields:
+    url: str | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+    # shared:
+    start_timeout: float = _DEFAULT_START_TIMEOUT
+
+
+@dataclass(slots=True)
+class MCPConfig:
+    """Top-level MCP configuration."""
+
+    servers: list[MCPServerConfig] = field(default_factory=list)
+    max_result_text_bytes: int = _DEFAULT_MAX_TEXT_BYTES
+    max_result_binary_bytes: int = _DEFAULT_MAX_BINARY_BYTES
+    start_timeout: float = _DEFAULT_START_TIMEOUT
+
+
+def parse_mcp_config(raw: dict[str, Any]) -> MCPConfig:
+    """Parse a TOML-derived dict (the `[mcp]` section) into MCPConfig.
+
+    Accepts either the full document (where `mcp` is a key) or the `[mcp]`
+    block itself. Unknown keys are silently ignored to stay forward-compatible.
+    """
+    if not isinstance(raw, dict):
+        raise MCPError(f"mcp config must be a table, got {type(raw).__name__}")
+
+    block = raw.get("mcp", raw)
+    if not isinstance(block, dict):
+        raise MCPError("'mcp' must be a table")
+
+    cfg = MCPConfig(
+        max_result_text_bytes=_int(
+            block, "max_result_text_bytes", _DEFAULT_MAX_TEXT_BYTES
+        ),
+        max_result_binary_bytes=_int(
+            block, "max_result_binary_bytes", _DEFAULT_MAX_BINARY_BYTES
+        ),
+        start_timeout=_float(block, "start_timeout", _DEFAULT_START_TIMEOUT),
+    )
+
+    servers_raw = block.get("servers", [])
+    if not isinstance(servers_raw, list):
+        raise MCPError("'mcp.servers' must be an array of tables")
+
+    seen: set[str] = set()
+    for index, entry in enumerate(servers_raw):
+        if not isinstance(entry, dict):
+            raise MCPError(f"mcp.servers[{index}] must be a table")
+        server = _parse_server(entry, index, default_start_timeout=cfg.start_timeout)
+        if server.name in seen:
+            raise MCPError(f"duplicate mcp server name: {server.name!r}")
+        seen.add(server.name)
+        cfg.servers.append(server)
+    return cfg
+
+
+def _parse_server(
+    entry: dict[str, Any], index: int, *, default_start_timeout: float
+) -> MCPServerConfig:
+    name = entry.get("name")
+    if not isinstance(name, str) or not name:
+        raise MCPError(
+            f"mcp.servers[{index}].name is required and must be a non-empty string"
+        )
+
+    transport = entry.get("transport")
+    if transport not in _VALID_TRANSPORTS:
+        raise MCPError(
+            f"mcp.servers[{name}].transport must be one of {_VALID_TRANSPORTS}, got {transport!r}"
+        )
+
+    server = MCPServerConfig(
+        name=name,
+        transport=transport,
+        start_timeout=_float(entry, "start_timeout", default_start_timeout),
+    )
+
+    if transport == "stdio":
+        command = entry.get("command")
+        if isinstance(command, str):
+            server.command = [command]
+        elif isinstance(command, list) and all(isinstance(s, str) for s in command):
+            server.command = list(command)
+        else:
+            raise MCPError(
+                f"mcp.servers[{name}].command is required for stdio transport"
+            )
+        if not server.command:
+            raise MCPError(f"mcp.servers[{name}].command must not be empty")
+        args = entry.get("args", [])
+        if not isinstance(args, list) or not all(isinstance(s, str) for s in args):
+            raise MCPError(f"mcp.servers[{name}].args must be a list of strings")
+        server.args = list(args)
+        env = entry.get("env", {})
+        if not isinstance(env, dict) or not all(
+            isinstance(k, str) and isinstance(v, str) for k, v in env.items()
+        ):
+            raise MCPError(f"mcp.servers[{name}].env must be a string->string table")
+        server.env = dict(env)
+        cwd = entry.get("cwd")
+        if cwd is not None and not isinstance(cwd, str):
+            raise MCPError(f"mcp.servers[{name}].cwd must be a string if provided")
+        server.cwd = cwd
+    else:
+        url = entry.get("url")
+        if not isinstance(url, str) or not url:
+            raise MCPError(
+                f"mcp.servers[{name}].url is required for transport {transport!r}"
+            )
+        server.url = url
+        headers = entry.get("headers", {})
+        if not isinstance(headers, dict) or not all(
+            isinstance(k, str) and isinstance(v, str) for k, v in headers.items()
+        ):
+            raise MCPError(
+                f"mcp.servers[{name}].headers must be a string->string table"
+            )
+        server.headers = dict(headers)
+
+    return server
+
+
+def _int(block: dict[str, Any], key: str, default: int) -> int:
+    value = block.get(key, default)
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise MCPError(f"mcp.{key} must be an integer, got {value!r}")
+    return value
+
+
+def _float(block: dict[str, Any], key: str, default: float) -> float:
+    value = block.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise MCPError(f"mcp.{key} must be a number, got {value!r}")
+    return float(value)

bareagent/mcp/errors.py

@@ -0,0 +1,32 @@
+"""MCP error hierarchy.
+
+Layered failure types: transport (subprocess / socket), protocol (JSON-RPC
+framing / id routing), handshake (initialize lifecycle), and call (tools/call
+returning a JSON-RPC error). Tool execution errors (``result.isError: true``)
+are NOT exceptions — they flow back to the LLM as text via the registry layer.
+"""
+
+from __future__ import annotations
+
+
+class MCPError(Exception):
+    """Base class for all MCP-related failures."""
+
+
+class MCPTransportError(MCPError):
+    """Transport-layer failure: connection dropped, framing error, subprocess died."""
+
+
+class MCPProtocolError(MCPError):
+    """JSON-RPC protocol failure: timeout, unknown response id, malformed envelope."""
+
+
+class MCPHandshakeError(MCPError):
+    """Initialize lifecycle failed: timeout, server returned error, or
+    incompatible protocol version negotiation."""
+
+
+class MCPCallError(MCPError):
+    """``tools/call`` (or any other request) came back with a JSON-RPC error
+    object. The exception message is pre-formatted as ``MCP Error: <code> <message>``
+    so registry handlers can return ``str(exc)`` directly to the LLM."""