agent-brain-cli 10.2.0__tar.gz → 10.3.0__tar.gz

{agent_brain_cli-10.2.0 → agent_brain_cli-10.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: agent-brain-cli
-Version: 10.2.0
+Version: 10.3.0
 Summary: Agent Brain CLI - Command-line interface for managing AI agent memory and knowledge retrieval
 Home-page: https://github.com/SpillwaveSolutions/agent-brain
 License: MIT
@@ -15,10 +15,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: agent-brain-rag (>=10.2.0,<11.0.0)
-Requires-Dist: agent-brain-uds (>=10.2.0,<11.0.0)
+Requires-Dist: agent-brain-rag (>=10.3.0,<11.0.0)
+Requires-Dist: agent-brain-uds (>=10.3.0,<11.0.0)
 Requires-Dist: click (>=8.1.0,<9.0.0)
 Requires-Dist: httpx (>=0.28.0,<0.29.0)
+Requires-Dist: psutil (>=6.0,<7.0)
 Requires-Dist: pydantic (>=2.10.0,<3.0.0)
 Requires-Dist: pyyaml (>=6.0.0,<7.0.0)
 Requires-Dist: rich (>=13.9.0,<14.0.0)

{agent_brain_cli-10.2.0 → agent_brain_cli-10.3.0}/agent_brain_cli/__init__.py

@@ -1,3 +1,3 @@
 """Doc-Serve CLI - Command-line interface for managing Doc-Serve server."""
 
-__version__ = "10.2.0"
+__version__ = "10.3.0"

agent_brain_cli-10.3.0/agent_brain_cli/__main__.py

@@ -0,0 +1,14 @@
+"""Entry point for ``python -m agent_brain_cli``.
+
+Defers to the Click ``cli`` group. Added in Phase 57 Plan 02 so the
+byte-equivalence contract test can invoke the CLI without depending
+on the ``agent-brain`` console-script being installed on ``PATH``
+in every test environment.
+"""
+
+from __future__ import annotations
+
+from agent_brain_cli.cli import cli
+
+if __name__ == "__main__":
+    cli()

{agent_brain_cli-10.2.0 → agent_brain_cli-10.3.0}/agent_brain_cli/cli.py

@@ -18,8 +18,11 @@ from .commands import (
     install_agent_command,
     jobs_command,
     list_command,
+    mcp_group,
+    prompt_command,
     query_command,
     reset_command,
+    resources_group,
     start_command,
     status_command,
     stop_command,
@@ -33,11 +36,11 @@ from .commands import (
 @click.option(
     "--transport",
     "transport",
-    type=click.Choice(["auto", "http", "uds"], case_sensitive=False),
+    type=click.Choice(["auto", "http", "uds", "mcp"], case_sensitive=False),
     default=None,
     help=(
-        "Transport to use: auto (default — UDS if available, HTTP "
-        "otherwise), http, or uds. Honors AGENT_BRAIN_TRANSPORT env."
+        "Transport: auto (UDS if available, HTTP otherwise), http, uds, "
+        "or mcp (CLI talks to agent-brain-mcp). Honors AGENT_BRAIN_TRANSPORT env."
     ),
 )
 @click.option(
@@ -51,6 +54,28 @@ from .commands import (
     default=None,
     help="Override server base URL (only used with --transport=http|auto).",
 )
+@click.option(
+    "--mcp-transport",
+    "mcp_transport",
+    type=click.Choice(["stdio", "http"], case_sensitive=False),
+    default=None,
+    help=(
+        "MCP listen transport for --transport mcp: stdio (default) "
+        "or http. Honors AGENT_BRAIN_MCP_TRANSPORT env. Ignored "
+        "when --transport != mcp."
+    ),
+)
+@click.option(
+    "--mcp-url",
+    "mcp_url",
+    default=None,
+    help=(
+        "MCP HTTP listener URL for --transport mcp --mcp-transport "
+        "http (e.g. http://127.0.0.1:9999/mcp). Honors "
+        "AGENT_BRAIN_MCP_URL env. mcp.runtime.json discovery "
+        "lands in Phase 58."
+    ),
+)
 @click.option(
     "--debug-transport",
     is_flag=True,
@@ -63,6 +88,8 @@ def cli(
     transport: str | None,
     socket_path: str | None,
     base_url: str | None,
+    mcp_transport: str | None,
+    mcp_url: str | None,
     debug_transport: bool,
 ) -> None:
     """Agent Brain CLI - Manage and query the Agent Brain RAG server.
@@ -124,6 +151,8 @@ def cli(
     ctx.obj["base_url_override"] = base_url
     ctx.obj["socket_path_override"] = socket_path
     ctx.obj["debug_transport"] = debug_transport
+    ctx.obj["mcp_transport_hint"] = mcp_transport
+    ctx.obj["mcp_url_override"] = mcp_url
 
 
 # Register project management commands
@@ -131,6 +160,9 @@ cli.add_command(init_command, name="init")
 cli.add_command(start_command, name="start")
 cli.add_command(stop_command, name="stop")
 cli.add_command(list_command, name="list")
+cli.add_command(mcp_group, name="mcp")
+cli.add_command(prompt_command, name="prompt")
+cli.add_command(resources_group, name="resources")
 
 # Register server interaction commands
 cli.add_command(status_command, name="status")

{agent_brain_cli-10.2.0 → agent_brain_cli-10.3.0}/agent_brain_cli/client/__init__.py

@@ -7,8 +7,10 @@ from .api_client import (
     FolderInfo,
     ServerError,
 )
+from .protocol import BackendClient
 
 __all__ = [
+    "BackendClient",
     "DocServeClient",
     "DocServeError",
     "ConnectionError",

{agent_brain_cli-10.2.0 → agent_brain_cli-10.3.0}/agent_brain_cli/client/api_client.py

@@ -159,6 +159,7 @@ class DocServeClient:
         self,
         base_url: str = "http://127.0.0.1:8000",
         timeout: float = 30.0,
+        api_key: str | None = None,
     ):
         """
         Initialize the client.
@@ -166,23 +167,37 @@ class DocServeClient:
         Args:
             base_url: Server base URL.
             timeout: Request timeout in seconds.
+            api_key: Optional bearer token (Issues #179, #199). When supplied,
+                every outbound request carries an ``Authorization: Bearer``
+                header per RFC 6750. ``None`` means no auth header (server
+                must be in ``INSECURE_NO_AUTH=true`` mode to accept the
+                request).
         """
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
-        self._client = httpx.Client(timeout=timeout)
+        headers = {"Authorization": f"Bearer {api_key}"} if api_key else None
+        self._client = httpx.Client(timeout=timeout, headers=headers)
 
     @classmethod
-    def from_httpx(cls, client: httpx.Client) -> "DocServeClient":
+    def from_httpx(
+        cls,
+        client: httpx.Client,
+        api_key: str | None = None,
+    ) -> "DocServeClient":
         """Build a DocServeClient that uses a pre-constructed httpx.Client.
 
         Used by the transport selector to inject a UDS-backed client
-        (see ``agent_brain_cli.client.transport.open_client``). The
+        (see ``agent_brain_cli.client.transport.open_backend``). The
         inner client's ``base_url`` is preserved; this wrapper sends
         relative paths only.
 
         Args:
             client: An already-configured ``httpx.Client``. The wrapper
                 takes ownership and will close it on ``__exit__``.
+            api_key: Optional bearer token to merge into the client's
+                default headers as ``Authorization: Bearer <token>``
+                (Issues #179, #199). Caller may also have set the
+                header on ``client`` directly; both paths work.
 
         Returns:
             A DocServeClient backed by ``client``.
@@ -191,6 +206,8 @@ class DocServeClient:
         instance.base_url = ""  # inner client carries the real base_url
         timeout = client.timeout
         instance.timeout = timeout.read or 30.0
+        if api_key:
+            client.headers["Authorization"] = f"Bearer {api_key}"
         instance._client = client
         return instance
 

agent_brain_cli-10.3.0/agent_brain_cli/client/protocol.py

@@ -0,0 +1,173 @@
+"""BackendClient — the structural Protocol every CLI backend satisfies.
+
+The shape lives in code so:
+
+1. mypy strict verifies callers can swap DocServeClient (HTTP/UDS) for
+   McpStdioBackend / McpHttpBackend (v3, Phase 56 Plan 03) without
+   editing a single Click command in :mod:`agent_brain_cli.commands`.
+2. Tests can assert ``isinstance(backend, BackendClient)`` at runtime
+   via :pep:`544`'s ``@runtime_checkable`` decorator.
+
+Surface mirrors :class:`agent_brain_cli.client.api_client.DocServeClient`
+verbatim — 12 public methods + 3 context-manager methods. The decision
+to keep the Protocol sync-only (no async variant) is committed in the
+v3 design doc at ``docs/plans/2026-06-05-mcp-v3-cli-via-mcp.md`` §3.2.
+A future ``AsyncBackendClient`` is deferred to v10.4+ per the design
+doc's §6.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    # TYPE_CHECKING import avoids a runtime cycle once Phase 56 Plan 03
+    # backends start importing the Protocol from this module.
+    from .api_client import (
+        FolderInfo,
+        HealthStatus,
+        IndexingStatus,
+        IndexResponse,
+        QueryResponse,
+    )
+
+
+@runtime_checkable
+class BackendClient(Protocol):
+    """Structural contract for CLI-side backends.
+
+    DocServeClient satisfies this Protocol without inheritance.
+    McpStdioBackend + McpHttpBackend (Plan 56-03) will declare it
+    explicitly via ``class McpStdioBackend(BackendClient): ...`` so
+    mypy emits a clean error if a method ever drifts.
+
+    All methods are synchronous. The v3 backends wrap async MCP SDK
+    calls via ``asyncio.run(...)`` or a persistent ``_loop`` attribute
+    — see the design doc §3.2. From the caller's perspective the
+    facade is identical to DocServeClient's.
+    """
+
+    # --- Context manager surface ---------------------------------------
+
+    def __enter__(self) -> BackendClient: ...
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None: ...
+
+    def close(self) -> None: ...
+
+    # --- Health + status ----------------------------------------------
+
+    def health(self) -> HealthStatus: ...
+
+    def status(self) -> IndexingStatus: ...
+
+    # --- Query (maps to MCP `search_documents` tool for v3 backends) ---
+
+    def query(
+        self,
+        query_text: str,
+        top_k: int = 5,
+        similarity_threshold: float = 0.7,
+        mode: str = "hybrid",
+        alpha: float = 0.5,
+        source_types: list[str] | None = None,
+        languages: list[str] | None = None,
+        file_paths: list[str] | None = None,
+        explain: bool = False,
+    ) -> QueryResponse: ...
+
+    # --- Indexing -----------------------------------------------------
+
+    def index(
+        self,
+        folder_path: str,
+        chunk_size: int = 512,
+        chunk_overlap: int = 50,
+        recursive: bool = True,
+        include_code: bool = False,
+        supported_languages: list[str] | None = None,
+        code_chunk_strategy: str = "ast_aware",
+        include_patterns: list[str] | None = None,
+        exclude_patterns: list[str] | None = None,
+        include_types: list[str] | None = None,
+        generate_summaries: bool = False,
+        force: bool = False,
+        injector_script: str | None = None,
+        folder_metadata_file: str | None = None,
+        dry_run: bool = False,
+        watch_mode: str | None = None,
+        watch_debounce_seconds: int | None = None,
+    ) -> IndexResponse: ...
+
+    # --- Folder management --------------------------------------------
+
+    def list_folders(self) -> list[FolderInfo]: ...
+
+    def delete_folder(self, folder_path: str) -> dict[str, Any]: ...
+
+    def reset(self) -> IndexResponse: ...
+
+    # --- Job queue ----------------------------------------------------
+
+    def list_jobs(self, limit: int = 20) -> list[dict[str, Any]]: ...
+
+    def get_job(self, job_id: str) -> dict[str, Any]: ...
+
+    def cancel_job(self, job_id: str) -> dict[str, Any]: ...
+
+    # --- Embedding cache ----------------------------------------------
+
+    def cache_status(self) -> dict[str, Any]: ...
+
+    def clear_cache(self) -> dict[str, Any]: ...
+
+
+@runtime_checkable
+class McpBackend(Protocol):
+    """Structural contract for MCP-only CLI backends (Phase 59).
+
+    Exposes the ``prompts/get`` + ``prompts/list`` +
+    ``resources/list`` + ``resources/templates/list`` +
+    ``resources/read`` MCP surface that the v3 ``agent-brain prompt``
+    and ``agent-brain resources *`` commands speak. Intentionally
+    SEPARATE from :class:`BackendClient` — DocServeClient (UDS/HTTP)
+    does NOT satisfy this Protocol because those transports do not
+    speak MCP prompts/resources. The negative-case pinning test in
+    ``agent-brain-mcp/tests/test_mcp_backend_protocol_skeleton.py``
+    (``test_doc_serve_client_does_not_satisfy_mcp_backend``) makes the
+    architectural boundary explicit and lasting.
+
+    All methods are synchronous (sync-facade Pattern A confirmed by
+    Plan 57-02; see design doc §3.2). The v3 MCP backends wrap async
+    MCP SDK calls via ``asyncio.run(...)`` per call — from the
+    caller's perspective the facade is identical to
+    :class:`BackendClient`'s.
+
+    Return shapes are deliberately ``dict[str, Any]`` /
+    ``list[dict[str, Any]]`` (NOT typed dataclasses) — the MCP wire
+    payloads for ``prompts/get`` and ``resources/read`` differ enough
+    that the Phase 59 Plan 02 / Plan 03 command layer handles per-
+    method coercion (mirrors the existing
+    :func:`api_client._unwrap_payload` shape). Phase 60+ may revisit.
+    """
+
+    def get_prompt(
+        self, name: str, arguments: dict[str, str] | None = None
+    ) -> dict[str, Any]: ...
+
+    def list_prompts(self) -> list[dict[str, Any]]: ...
+
+    def list_resources(self) -> list[dict[str, Any]]: ...
+
+    def list_resource_templates(self) -> list[dict[str, Any]]: ...
+
+    def read_resource(self, uri: str) -> dict[str, Any]: ...
+
+
+__all__: list[str] = ["BackendClient", "McpBackend"]

agent_brain_cli-10.3.0/agent_brain_cli/client/transport.py

@@ -0,0 +1,255 @@
+"""Transport selector — builds a BackendClient over HTTP, UDS, or MCP.
+
+Renamed in Phase 57 (Plan 57-01) from ``open_client`` to
+``open_backend``. Return type widened from ``DocServeClient`` to
+:class:`agent_brain_cli.client.protocol.BackendClient` so the
+transport-dispatching factory can return any of:
+
+  - ``DocServeClient`` (HTTP or UDS — the existing v1/v2 path)
+  - ``McpStdioBackend`` (v3 stdio MCP — agent-brain-mcp subprocess)
+  - ``McpHttpBackend`` (v3 streamable HTTP MCP — loopback listener)
+
+The MCP backends are imported lazily inside the ``transport == "mcp"``
+branch so HTTP/UDS-only invocations do NOT pay the MCP SDK import
+cost AND so the CLI runs cleanly without ``agent-brain-mcp``
+installed when the user never asks for it (CONTEXT decision: soft
+dep on agent-brain-mcp).
+
+Three §3.5 design-doc misuse cases surface as ``click.UsageError``
+(exit code 2 — v10.2 HTTP-03 no-silent-fallback contract):
+
+  1. ``--transport mcp`` + ``agent-brain-mcp`` package not installed
+     → "install agent-brain-mcp to use --transport mcp"
+  2. ``--mcp-transport http`` without ``--mcp-url`` (and no
+     ``AGENT_BRAIN_MCP_URL`` env) AND no ``mcp.runtime.json``
+     discovery file → raised by ``resolve_mcp_transport`` with the
+     verbatim v3 §3.5 wording (Phase 58 CLI-MCP-08)
+  3. ``--mcp-transport stdio`` + ``agent-brain-mcp`` not reachable
+     on ``PATH`` (``shutil.which`` returns ``None``)
+     → "agent-brain-mcp not found on PATH; install agent-brain-mcp
+        into the same Python environment"
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import cast
+
+import click
+
+from ..config import resolve_api_key, resolve_mcp_transport, resolve_transport
+from .api_client import DocServeClient
+from .protocol import BackendClient, McpBackend
+
+
+def _resolve_state_dir_for_discovery() -> Path | None:
+    """Resolve state_dir for mcp.runtime.json discovery (Phase 58 CLI-MCP-08).
+
+    Mirrors the chain used by ``agent-brain mcp start``. Returns None on
+    any failure — callers treat that as "no discovery possible" and
+    fall through to the explicit-url-or-error path inside
+    ``resolve_mcp_transport``.
+    """
+    try:
+        from agent_brain_cli.config import resolve_project_root
+        from agent_brain_cli.migration import resolve_state_dir_with_fallback
+        from agent_brain_cli.xdg_paths import migrate_legacy_paths
+
+        migrate_legacy_paths()
+        project_root = resolve_project_root()
+        return resolve_state_dir_with_fallback(project_root)
+    except Exception:
+        return None
+
+
+def open_backend(ctx: click.Context, *, timeout: float = 30.0) -> BackendClient:
+    """Construct a ``BackendClient`` over the transport selected by ``ctx``.
+
+    Reads from ``ctx.obj`` (set by the top-level Click group in
+    ``cli.py``):
+
+      - ``transport_hint`` (``"auto"`` / ``"http"`` / ``"uds"`` /
+        ``"mcp"`` / ``None``)
+      - ``base_url_override``, ``socket_path_override``
+      - ``mcp_transport_hint`` (``"stdio"`` / ``"http"`` / ``None``)
+      - ``mcp_url_override`` (URL string or ``None``)
+      - ``debug_transport`` (bool)
+
+    Dispatch (in order):
+
+      1. ``transport == "mcp"`` and ``mcp_transport == "stdio"`` →
+         :class:`McpStdioBackend(command="agent-brain-mcp")` (precheck:
+         ``shutil.which("agent-brain-mcp")`` must be non-None or
+         raises with §3.5 case 3 wording)
+      2. ``transport == "mcp"`` and ``mcp_transport == "http"`` →
+         :class:`McpHttpBackend(url=resolved_mcp_url, timeout=timeout)`
+      3. ``transport == "http"`` → :class:`DocServeClient`
+      4. ``transport == "uds"`` → :class:`DocServeClient.from_httpx`
+
+    Raises:
+        click.UsageError: With exit code 2 when any of the three
+            §3.5 design-doc misuse cases hit. NO silent fallback to
+            UDS or HTTP — the operator's choice is honored or the
+            CLI exits non-zero (v10.2 HTTP-03 contract).
+    """
+    obj = ctx.obj or {}
+    transport_hint = obj.get("transport_hint")
+    api_key = resolve_api_key()
+
+    # --- MCP branch (v3) -----------------------------------------
+    if (transport_hint or "").lower() == "mcp":
+        state_dir = _resolve_state_dir_for_discovery()
+        mcp_transport, mcp_target = resolve_mcp_transport(
+            mcp_transport_hint=obj.get("mcp_transport_hint"),
+            mcp_url_override=obj.get("mcp_url_override"),
+            state_dir=state_dir,
+        )
+        if obj.get("debug_transport"):
+            auth_marker = "with Bearer token" if api_key else "no auth"
+            target_label = mcp_target if mcp_target else "subprocess: agent-brain-mcp"
+            click.echo(
+                f"[debug-transport] mcp ({mcp_transport}) -> "
+                f"{target_label} ({auth_marker})",
+                err=True,
+            )
+        try:
+            from agent_brain_mcp.client import (  # noqa: F401
+                McpHttpBackend,
+                McpStdioBackend,
+            )
+        except ImportError as exc:
+            raise click.UsageError(
+                "install agent-brain-mcp to use --transport mcp"
+            ) from exc
+
+        if mcp_transport == "stdio":
+            # §3.5 case 3 precheck — agent-brain-mcp must be on PATH
+            # before we hand off to the subprocess-spawning backend.
+            # Verbatim §3.5 wording — DO NOT paraphrase.
+            if shutil.which("agent-brain-mcp") is None:
+                raise click.UsageError(
+                    "agent-brain-mcp not found on PATH; install "
+                    "agent-brain-mcp into the same Python environment"
+                )
+            # cast(): agent_brain_mcp ships with ignore_missing_imports=true
+            # so mypy treats McpStdioBackend as Any. The runtime
+            # @runtime_checkable Protocol contract is pinned by the
+            # Phase 56-03 isinstance test in agent-brain-mcp/tests/.
+            return cast(BackendClient, McpStdioBackend(command="agent-brain-mcp"))
+        # mcp_transport == "http" — resolve_mcp_transport guarantees
+        # mcp_target is not None for the http branch.
+        assert mcp_target is not None  # noqa: S101
+        return cast(BackendClient, McpHttpBackend(url=mcp_target, timeout=timeout))
+
+    # --- HTTP / UDS branch (existing v1/v2 path) -----------------
+    transport, target = resolve_transport(
+        transport_hint=transport_hint,
+        base_url_override=obj.get("base_url_override"),
+        socket_path_override=obj.get("socket_path_override"),
+    )
+    if obj.get("debug_transport"):
+        auth_marker = "with X-API-Key" if api_key else "no auth"
+        click.echo(
+            f"[debug-transport] {transport} -> {target} ({auth_marker})",
+            err=True,
+        )
+
+    if transport == "http":
+        return DocServeClient(base_url=target, timeout=timeout, api_key=api_key)
+
+    # UDS: lazy import so HTTP-only invocations don't pay the cost.
+    from agent_brain_uds import make_client
+
+    inner = make_client(socket_path=Path(target), timeout=timeout)
+    return DocServeClient.from_httpx(inner, api_key=api_key)
+
+
+def open_mcp_backend(ctx: click.Context, *, timeout: float = 30.0) -> McpBackend:
+    """Construct an ``McpBackend`` for MCP-only CLI commands (Phase 59).
+
+    Sibling to :func:`open_backend`: that dispatcher returns a
+    :class:`BackendClient` (the tools surface — health/query/index/etc.)
+    over any of HTTP/UDS/MCP; this factory returns an
+    :class:`McpBackend` (the prompts + resources surface — get_prompt /
+    list_resources / read_resource) exclusively over MCP. Every Phase 59
+    MCP-only command (``agent-brain prompt``, ``agent-brain resources
+    *``) calls this instead of :func:`open_backend` so the
+    ``--transport mcp`` check lives at a single point of contract.
+
+    Reads from ``ctx.obj`` (set by the top-level Click group in
+    ``cli.py``):
+
+      - ``transport_hint`` — MUST be ``"mcp"`` (case-insensitive); any
+        other value raises :class:`click.UsageError` per the Phase 57
+        §3.5 no-silent-fallback contract.
+      - ``mcp_transport_hint`` (``"stdio"`` / ``"http"`` / ``None``)
+      - ``mcp_url_override`` (URL string or ``None``)
+      - ``debug_transport`` (bool)
+
+    Dispatch:
+
+      1. ``mcp_transport == "stdio"`` →
+         :class:`McpStdioBackend(command="agent-brain-mcp")` (precheck:
+         ``shutil.which("agent-brain-mcp")`` must be non-None; same
+         §3.5 case-3 wording as :func:`open_backend`).
+      2. ``mcp_transport == "http"`` →
+         :class:`McpHttpBackend(url=resolved_mcp_url, timeout=timeout)`.
+
+    Raises:
+        click.UsageError: Exit code 2 when (1) ``transport_hint`` is
+            not ``"mcp"``, (2) ``agent-brain-mcp`` is not installed,
+            (3) stdio binary not on PATH. Carries the Phase 57 §3.5
+            verbatim wording — no silent fallback.
+    """
+    obj = ctx.obj or {}
+    transport_hint = (obj.get("transport_hint") or "").lower()
+    if transport_hint != "mcp":
+        # Generic per-factory wording. Each MCP-only command may wrap
+        # this and replace the trailing ``<command>`` placeholder with
+        # its own name (``prompt``, ``resources list``, etc.) — the
+        # default is sufficient for Plan 59-01's contract test and for
+        # the rare case where a future command forgets the wrapper.
+        raise click.UsageError(
+            "This command requires --transport mcp; example: "
+            "agent-brain --transport mcp --mcp-transport stdio <command>"
+        )
+
+    state_dir = _resolve_state_dir_for_discovery()
+    mcp_transport, mcp_target = resolve_mcp_transport(
+        mcp_transport_hint=obj.get("mcp_transport_hint"),
+        mcp_url_override=obj.get("mcp_url_override"),
+        state_dir=state_dir,
+    )
+    if obj.get("debug_transport"):
+        target_label = mcp_target if mcp_target else "subprocess: agent-brain-mcp"
+        click.echo(
+            f"[debug-transport] mcp-only ({mcp_transport}) -> {target_label}",
+            err=True,
+        )
+    try:
+        from agent_brain_mcp.client import (  # noqa: F401
+            McpHttpBackend,
+            McpStdioBackend,
+        )
+    except ImportError as exc:
+        raise click.UsageError(
+            "install agent-brain-mcp to use --transport mcp"
+        ) from exc
+
+    if mcp_transport == "stdio":
+        # §3.5 case 3 precheck — verbatim wording, same as open_backend.
+        if shutil.which("agent-brain-mcp") is None:
+            raise click.UsageError(
+                "agent-brain-mcp not found on PATH; install "
+                "agent-brain-mcp into the same Python environment"
+            )
+        # cast(): mirrors open_backend's pattern. The runtime
+        # @runtime_checkable Protocol contract is pinned by the
+        # Plan 59-01 isinstance test in agent-brain-mcp/tests/
+        # test_mcp_backend_protocol_skeleton.py.
+        return cast(McpBackend, McpStdioBackend(command="agent-brain-mcp"))
+    # mcp_transport == "http" — resolve_mcp_transport guarantees
+    # mcp_target is not None for the http branch.
+    assert mcp_target is not None  # noqa: S101
+    return cast(McpBackend, McpHttpBackend(url=mcp_target, timeout=timeout))

{agent_brain_cli-10.2.0 → agent_brain_cli-10.3.0}/agent_brain_cli/commands/__init__.py

@@ -10,8 +10,11 @@ from .inject import inject_command
 from .install_agent import install_agent_command
 from .jobs import jobs_command
 from .list_cmd import list_command
+from .mcp import mcp_group
+from .prompt import prompt_command
 from .query import query_command
 from .reset import reset_command
+from .resources import resources_group
 from .start import start_command
 from .status import status_command
 from .stop import stop_command
@@ -29,8 +32,11 @@ __all__ = [
     "install_agent_command",
     "jobs_command",
     "list_command",
+    "mcp_group",
+    "prompt_command",
     "query_command",
     "reset_command",
+    "resources_group",
     "start_command",
     "status_command",
     "stop_command",

{agent_brain_cli-10.2.0 → agent_brain_cli-10.3.0}/agent_brain_cli/commands/cache.py

@@ -6,7 +6,7 @@ from rich.prompt import Confirm
 from rich.table import Table
 
 from ..client import ConnectionError, ServerError
-from ..client.transport import open_client
+from ..client.transport import open_backend
 
 console = Console()
 
@@ -33,7 +33,7 @@ def cache_status(ctx: click.Context, url: str | None, json_output: bool) -> None
         ctx.obj["base_url_override"] = url
         ctx.obj["transport_hint"] = "http"
     try:
-        with open_client(ctx) as client:
+        with open_backend(ctx) as client:
             data = client.cache_status()
 
             if json_output:
@@ -106,7 +106,7 @@ def cache_clear(ctx: click.Context, url: str | None, yes: bool) -> None:
         ctx.obj["base_url_override"] = url
         ctx.obj["transport_hint"] = "http"
     try:
-        with open_client(ctx) as client:
+        with open_backend(ctx) as client:
             if not yes:
                 # Get current count before asking
                 try: