hx-cli 0.1.0__py3-none-any.whl

hx/mcp/client.py

@@ -0,0 +1,319 @@
+"""MCP client - stdio and streamable HTTP transports.
+
+Implements the subset HX needs: ``initialize``, ``tools/list``, ``tools/call``.
+JSON-RPC 2.0 over either transport.
+"""
+
+from __future__ import annotations
+
+import abc
+import asyncio
+import contextlib
+import json
+import logging
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from hx import __version__
+
+PROTOCOL_VERSION = "2025-06-18"
+CLIENT_INFO = {"name": "hx", "version": __version__}
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class MCPToolDef:
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+
+
+@dataclass(slots=True)
+class ServerCapabilities:
+    tools: bool = False
+    prompts: bool = False
+    resources: bool = False
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+class Transport(abc.ABC):
+    @abc.abstractmethod
+    async def connect(self) -> None: ...
+
+    @abc.abstractmethod
+    async def send(self, message: dict[str, Any]) -> None: ...
+
+    @abc.abstractmethod
+    def receive(self) -> AsyncIterator[dict[str, Any]]: ...
+
+    @abc.abstractmethod
+    async def close(self) -> None: ...
+
+
+class StdioTransport(Transport):
+    """Newline-delimited JSON-RPC over a subprocess's stdio.
+
+    The server's stderr is drained to the log rather than the terminal; a chatty
+    server would otherwise corrupt the TUI render.
+    """
+
+    def __init__(
+        self,
+        command: str,
+        args: list[str],
+        env: dict[str, str] | None = None,
+        cwd: Path | None = None,
+    ) -> None:
+        self.command = command
+        self.args = list(args)
+        self.env = env
+        self.cwd = cwd
+        self._process: asyncio.subprocess.Process | None = None
+        self._stderr_task: asyncio.Task[None] | None = None
+
+    async def connect(self) -> None:
+        import os
+
+        self._process = await asyncio.create_subprocess_exec(
+            self.command,
+            *self.args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env={**os.environ, **(self.env or {})},
+            cwd=str(self.cwd) if self.cwd else None,
+        )
+        self._stderr_task = asyncio.create_task(self._drain_stderr())
+
+    async def _drain_stderr(self) -> None:
+        assert self._process is not None
+        if self._process.stderr is None:
+            return
+        async for line in self._process.stderr:
+            log.debug("mcp[%s] %s", self.command, line.decode(errors="replace").rstrip())
+
+    async def send(self, message: dict[str, Any]) -> None:
+        if self._process is None or self._process.stdin is None:
+            raise MCPError("transport is not connected")
+        self._process.stdin.write((json.dumps(message) + "\n").encode())
+        await self._process.stdin.drain()
+
+    async def receive(self) -> AsyncIterator[dict[str, Any]]:
+        if self._process is None or self._process.stdout is None:
+            raise MCPError("transport is not connected")
+        async for raw in self._process.stdout:
+            line = raw.decode(errors="replace").strip()
+            if not line:
+                continue
+            try:
+                yield json.loads(line)
+            except json.JSONDecodeError:
+                # A server printing plain text on stdout is a server bug, not a
+                # reason to tear down the session.
+                log.warning("mcp[%s] non-JSON on stdout: %s", self.command, line[:200])
+
+    async def close(self) -> None:
+        if self._stderr_task is not None:
+            self._stderr_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._stderr_task
+        if self._process is None:
+            return
+        with contextlib.suppress(ProcessLookupError):
+            self._process.terminate()
+        with contextlib.suppress(TimeoutError, ProcessLookupError):
+            await asyncio.wait_for(self._process.wait(), timeout=5)
+        self._process = None
+
+
+class HTTPTransport(Transport):
+    """Streamable HTTP transport. Responses arrive as JSON or as an SSE stream."""
+
+    def __init__(self, url: str, headers: dict[str, str] | None = None) -> None:
+        self.url = url
+        self.headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            **(headers or {}),
+        }
+        self._client: httpx.AsyncClient | None = None
+        self._session_id: str | None = None
+        self._inbox: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+
+    async def connect(self) -> None:
+        self._client = httpx.AsyncClient(timeout=httpx.Timeout(120.0, connect=15.0))
+
+    async def send(self, message: dict[str, Any]) -> None:
+        if self._client is None:
+            raise MCPError("transport is not connected")
+        headers = dict(self.headers)
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+
+        response = await self._client.post(self.url, json=message, headers=headers)
+        if response.status_code >= 400:
+            raise MCPError(f"{self.url} returned {response.status_code}: {response.text[:200]}")
+        if session_id := response.headers.get("Mcp-Session-Id"):
+            self._session_id = session_id
+
+        if response.status_code == 202 or not response.content:
+            return
+        for payload in _decode_http_body(response):
+            await self._inbox.put(payload)
+
+    async def receive(self) -> AsyncIterator[dict[str, Any]]:
+        while True:
+            yield await self._inbox.get()
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+
+def _decode_http_body(response: httpx.Response) -> list[dict[str, Any]]:
+    content_type = response.headers.get("content-type", "")
+    if "text/event-stream" in content_type:
+        payloads = []
+        for line in response.text.splitlines():
+            if line.startswith("data:"):
+                with contextlib.suppress(json.JSONDecodeError):
+                    payloads.append(json.loads(line[5:].strip()))
+        return payloads
+    try:
+        body = response.json()
+    except ValueError as exc:
+        raise MCPError(f"invalid JSON from {response.url}: {exc}") from exc
+    return body if isinstance(body, list) else [body]
+
+
+class MCPClient:
+    """One connected server."""
+
+    def __init__(self, name: str, transport: Transport, timeout: float = 30.0) -> None:
+        self.name = name
+        self.transport = transport
+        self.timeout = timeout
+        self.capabilities = ServerCapabilities()
+        self._next_id = 0
+        self._pending: dict[int, asyncio.Future[dict[str, Any]]] = {}
+        self._reader: asyncio.Task[None] | None = None
+
+    async def initialize(self) -> ServerCapabilities:
+        await self.transport.connect()
+        self._reader = asyncio.create_task(self._read_loop())
+
+        result = await self._request(
+            "initialize",
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": CLIENT_INFO,
+            },
+        )
+        raw = result.get("capabilities") or {}
+        self.capabilities = ServerCapabilities(
+            tools="tools" in raw,
+            prompts="prompts" in raw,
+            resources="resources" in raw,
+            raw=raw,
+        )
+        await self._notify("notifications/initialized", {})
+        return self.capabilities
+
+    async def list_tools(self) -> list[MCPToolDef]:
+        if not self.capabilities.tools:
+            return []
+        result = await self._request("tools/list", {})
+        return [
+            MCPToolDef(
+                name=str(item["name"]),
+                description=str(item.get("description") or ""),
+                input_schema=item.get("inputSchema") or {"type": "object", "properties": {}},
+            )
+            for item in result.get("tools", [])
+        ]
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> str:
+        """Call a tool and flatten the content blocks to text.
+
+        Tool results are data from a third-party server. They are returned to the
+        model as tool output and must never be treated as instructions to HX.
+        """
+        result = await self._request("tools/call", {"name": name, "arguments": arguments})
+        parts = [
+            str(block.get("text", ""))
+            for block in result.get("content", [])
+            if block.get("type") == "text"
+        ]
+        text = "\n".join(part for part in parts if part)
+        if result.get("isError"):
+            raise MCPToolError(text or f"{name} failed")
+        return text or "(no content)"
+
+    async def _request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        self._next_id += 1
+        request_id = self._next_id
+        future: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+        self._pending[request_id] = future
+
+        await self.transport.send(
+            {"jsonrpc": "2.0", "id": request_id, "method": method, "params": params}
+        )
+        try:
+            message = await asyncio.wait_for(future, timeout=self.timeout)
+        except TimeoutError as exc:
+            raise MCPError(f"{self.name}: {method} timed out after {self.timeout:.0f}s") from exc
+        finally:
+            self._pending.pop(request_id, None)
+
+        if error := message.get("error"):
+            raise MCPError(f"{self.name}: {error.get('message', error)}")
+        result = message.get("result")
+        return result if isinstance(result, dict) else {}
+
+    async def _notify(self, method: str, params: dict[str, Any]) -> None:
+        await self.transport.send({"jsonrpc": "2.0", "method": method, "params": params})
+
+    async def _read_loop(self) -> None:
+        try:
+            async for message in self.transport.receive():
+                request_id = message.get("id")
+                future = self._pending.get(request_id) if request_id is not None else None
+                if future is not None and not future.done():
+                    future.set_result(message)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            self._fail_pending(f"transport failed: {exc}")
+            return
+
+        # The stream ended: the server exited. Fail the waiters now rather than
+        # letting each one burn its full timeout against a process that is gone.
+        self._fail_pending("the server exited")
+
+    def _fail_pending(self, reason: str) -> None:
+        for future in self._pending.values():
+            if not future.done():
+                future.set_exception(MCPError(f"{self.name}: {reason}"))
+
+    async def close(self) -> None:
+        if self._reader is not None:
+            self._reader.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._reader
+            self._reader = None
+        await self.transport.close()
+
+
+class MCPError(Exception):
+    pass
+
+
+class MCPToolError(MCPError):
+    """The server ran the tool and it failed - distinct from a protocol failure."""

hx/mcp/manager.py

@@ -0,0 +1,265 @@
+"""MCP server lifecycle and tool registration.
+
+Config lives in ``<cwd>/.hx/mcp.json`` and ``~/.hx/mcp.json``, project last.
+Servers connect concurrently at startup with a per-server timeout; a failure
+logs a warning and drops that server, never kills the session.
+
+Tools are namespaced ``mcp__<server>__<tool>`` and registered into the same
+:class:`~hx.tools.registry.ToolRegistry` as builtins, sorted deterministically -
+a server whose tool order varies between runs would invalidate the cache prefix.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from hx.mcp.client import MCPClient, MCPError, MCPToolDef, StdioTransport
+from hx.tools.base import Tool, ToolContext, ToolError, ToolResult
+from hx.tools.output import cap_output, summarize_for_ui
+
+NAMESPACE_TEMPLATE = "mcp__{server}__{tool}"
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class MCPServerConfig:
+    name: str
+    transport: str
+    """``stdio`` or ``http``."""
+    command: str | None = None
+    args: tuple[str, ...] = ()
+    env: dict[str, str] = field(default_factory=dict)
+    url: str | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+    enabled: bool = True
+    timeout: float = 30.0
+
+
+@dataclass(slots=True)
+class ServerStatus:
+    name: str
+    connected: bool
+    tool_count: int
+    error: str | None = None
+
+
+class MCPTool(Tool):
+    """Adapter presenting an MCP tool through the normal :class:`Tool` interface."""
+
+    #: MCP servers are third-party code; assume a call can have side effects
+    #: unless the schema says otherwise. Concurrency and prompting follow from
+    #: this, so guessing "read-only" would be the unsafe guess.
+    mutating = True
+
+    def __init__(self, client: MCPClient, server: str, definition: MCPToolDef) -> None:
+        self.client = client
+        self.server = server
+        self.definition = definition
+        self.name = NAMESPACE_TEMPLATE.format(server=server, tool=definition.name)
+        self.description = definition.description or f"{definition.name} (from {server})"
+
+    def schema(self) -> dict[str, Any]:
+        return self.definition.input_schema
+
+    def permission_specifier(self, params: dict[str, Any]) -> str | None:
+        return self.definition.name
+
+    async def run(self, params: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        try:
+            output = await self.client.call_tool(self.definition.name, params)
+        except MCPError as exc:
+            raise ToolError(str(exc)) from exc
+
+        capped = cap_output(
+            output,
+            session_id=ctx.session_id,
+            tool_use_id=ctx.tool_use_id,
+            char_cap=ctx.settings.context.tool_output_char_cap,
+            line_cap=ctx.settings.context.tool_output_line_cap,
+        )
+        return ToolResult(
+            content=capped.text,
+            spilled_path=capped.spilled_path,
+            summary=summarize_for_ui(output),
+        )
+
+
+class MCPManager:
+    def __init__(self, configs: list[MCPServerConfig]) -> None:
+        self.configs = [config for config in configs if config.enabled]
+        self.clients: dict[str, MCPClient] = {}
+        self._status: dict[str, ServerStatus] = {}
+        self._tools: dict[str, list[MCPToolDef]] = {}
+
+    async def connect_all(self) -> list[ServerStatus]:
+        """Connect concurrently. Never raises for a single server's failure."""
+        results = await asyncio.gather(
+            *(self._connect(config) for config in self.configs),
+            return_exceptions=True,
+        )
+        for config, result in zip(self.configs, results, strict=True):
+            if isinstance(result, BaseException):
+                self._status[config.name] = ServerStatus(config.name, False, 0, str(result))
+                log.warning("mcp server %s failed to start: %s", config.name, result)
+        return self.status()
+
+    async def _connect(self, config: MCPServerConfig) -> None:
+        client = MCPClient(config.name, _build_transport(config), timeout=config.timeout)
+        try:
+            await asyncio.wait_for(client.initialize(), timeout=config.timeout)
+            definitions = await client.list_tools()
+        except (TimeoutError, MCPError, OSError) as exc:
+            await client.close()
+            # One bad server must not cost the user their whole session.
+            # asyncio.TimeoutError stringifies to nothing, so say what happened.
+            reason = (
+                f"did not respond within {config.timeout:.0f}s"
+                if isinstance(exc, TimeoutError)
+                else str(exc) or type(exc).__name__
+            )
+            self._status[config.name] = ServerStatus(config.name, False, 0, reason)
+            log.warning("mcp server %s unavailable: %s", config.name, reason)
+            return
+
+        self.clients[config.name] = client
+        self._tools[config.name] = definitions
+        self._status[config.name] = ServerStatus(config.name, True, len(definitions))
+
+    async def register_tools(self, registry: Any) -> None:
+        """Register every connected server's tools under its namespace.
+
+        Servers are visited in sorted order and their tools sorted by name, so
+        the schema block is byte-identical between runs even if a server
+        returns its tools in a different order.
+        """
+        for server in sorted(self.clients):
+            client = self.clients[server]
+            for definition in sorted(self._tools[server], key=lambda item: item.name):
+                tool = MCPTool(client, server, definition)
+                if registry.has(tool.name):
+                    log.warning("mcp tool %s already registered; skipping", tool.name)
+                    continue
+                registry.register(tool)
+
+    def status(self) -> list[ServerStatus]:
+        """Backs ``/mcp`` and ``hx mcp list``."""
+        return [
+            self._status.get(config.name, ServerStatus(config.name, False, 0, "not started"))
+            for config in self.configs
+        ]
+
+    async def close_all(self) -> None:
+        await asyncio.gather(
+            *(client.close() for client in self.clients.values()), return_exceptions=True
+        )
+        self.clients.clear()
+
+
+def _build_transport(config: MCPServerConfig) -> Any:
+    if config.transport == "stdio":
+        if not config.command:
+            raise MCPError(f"{config.name}: stdio transport needs a command")
+        return StdioTransport(config.command, list(config.args), config.env)
+    if config.transport in {"http", "sse"}:
+        from hx.mcp.client import HTTPTransport
+
+        if not config.url:
+            raise MCPError(f"{config.name}: http transport needs a url")
+        return HTTPTransport(config.url, config.headers)
+    raise MCPError(f"{config.name}: unknown transport {config.transport!r}")
+
+
+def load_configs(cwd: Path) -> list[MCPServerConfig]:
+    """Read and merge user and project ``mcp.json``. Project entries win by name."""
+    from hx.paths import project_mcp_file, user_home
+
+    merged: dict[str, MCPServerConfig] = {}
+    for path in (user_home() / "mcp.json", project_mcp_file(cwd)):
+        for config in _read_file(path):
+            merged[config.name] = config
+    return [merged[name] for name in sorted(merged)]
+
+
+def _read_file(path: Path) -> list[MCPServerConfig]:
+    if not path.is_file():
+        return []
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        log.warning("ignoring %s: %s", path, exc)
+        return []
+
+    servers = data.get("mcpServers") or data.get("servers") or {}
+    configs: list[MCPServerConfig] = []
+    for name, raw in servers.items():
+        if not isinstance(raw, dict):
+            continue
+        transport = str(raw.get("type") or ("http" if raw.get("url") else "stdio"))
+        configs.append(
+            MCPServerConfig(
+                name=str(name),
+                transport=transport,
+                command=raw.get("command"),
+                args=tuple(str(arg) for arg in raw.get("args") or ()),
+                env={str(k): str(v) for k, v in (raw.get("env") or {}).items()},
+                url=raw.get("url"),
+                headers={str(k): str(v) for k, v in (raw.get("headers") or {}).items()},
+                enabled=bool(raw.get("enabled", True)),
+                timeout=float(raw.get("timeout", 30.0)),
+            )
+        )
+    return configs
+
+
+def save_config(config: MCPServerConfig, cwd: Path, user_level: bool = False) -> Path:
+    """Backs ``hx mcp add``."""
+    from hx.paths import project_mcp_file, user_home
+
+    path = (user_home() / "mcp.json") if user_level else project_mcp_file(cwd)
+    data: dict[str, Any] = {}
+    if path.is_file():
+        try:
+            data = json.loads(path.read_text())
+        except (OSError, json.JSONDecodeError):
+            data = {}
+
+    servers = data.setdefault("mcpServers", {})
+    entry: dict[str, Any] = {"type": config.transport}
+    if config.command:
+        entry["command"] = config.command
+    if config.args:
+        entry["args"] = list(config.args)
+    if config.env:
+        entry["env"] = config.env
+    if config.url:
+        entry["url"] = config.url
+    servers[config.name] = entry
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+    return path
+
+
+def remove_config(name: str, cwd: Path, user_level: bool = False) -> bool:
+    from hx.paths import project_mcp_file, user_home
+
+    path = (user_home() / "mcp.json") if user_level else project_mcp_file(cwd)
+    if not path.is_file():
+        return False
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return False
+
+    servers = data.get("mcpServers") or {}
+    if name not in servers:
+        return False
+    del servers[name]
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+    return True

hx/paths.py

@@ -0,0 +1,90 @@
+"""Filesystem layout for HX state and configuration.
+
+User-level state lives under ``$HX_HOME`` (default ``~/.hx``). Project-level
+overrides live in ``<cwd>/.hx``. Nothing here touches the network or mutates
+state on import; call :func:`ensure_user_dirs` explicitly at startup.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+HX_HOME_ENV = "HX_HOME"
+PROJECT_DIR_NAME = ".hx"
+
+
+def user_home() -> Path:
+    """Root of user-level HX state (``$HX_HOME`` or ``~/.hx``)."""
+    override = os.environ.get(HX_HOME_ENV)
+    return Path(override).expanduser() if override else Path.home() / ".hx"
+
+
+def user_settings_file() -> Path:
+    return user_home() / "settings.json"
+
+
+def auth_file() -> Path:
+    """Credential store. Created with mode 0600 by the auth layer."""
+    return user_home() / "auth.json"
+
+
+def models_cache_file() -> Path:
+    """Cached OpenRouter model catalogue."""
+    return user_home() / "models.json"
+
+
+def sessions_dir() -> Path:
+    return user_home() / "sessions"
+
+
+def session_dir(session_id: str) -> Path:
+    return sessions_dir() / session_id
+
+
+def session_transcript_file(session_id: str) -> Path:
+    return session_dir(session_id) / "transcript.jsonl"
+
+
+def session_outputs_dir(session_id: str) -> Path:
+    """Where oversized tool outputs are spilled (see ``hx.tools.output``)."""
+    return session_dir(session_id) / "outputs"
+
+
+def user_skills_dir() -> Path:
+    return user_home() / "skills"
+
+
+def user_agents_dir() -> Path:
+    return user_home() / "agents"
+
+
+def logs_dir() -> Path:
+    return user_home() / "logs"
+
+
+def project_dir(cwd: Path | None = None) -> Path:
+    """Project-level config directory (``<cwd>/.hx``)."""
+    return (cwd or Path.cwd()) / PROJECT_DIR_NAME
+
+
+def project_settings_file(cwd: Path | None = None) -> Path:
+    return project_dir(cwd) / "settings.json"
+
+
+def project_mcp_file(cwd: Path | None = None) -> Path:
+    return project_dir(cwd) / "mcp.json"
+
+
+def project_skills_dir(cwd: Path | None = None) -> Path:
+    return project_dir(cwd) / "skills"
+
+
+def project_agents_dir(cwd: Path | None = None) -> Path:
+    return project_dir(cwd) / "agents"
+
+
+def ensure_user_dirs() -> None:
+    """Create the user-level directory skeleton if it does not exist."""
+    for path in (user_home(), sessions_dir(), user_skills_dir(), user_agents_dir(), logs_dir()):
+        path.mkdir(parents=True, exist_ok=True)

hx/permissions/__init__.py

@@ -0,0 +1,7 @@
+"""Two independent safety layers: a rule engine and an OS sandbox.
+
+Both must pass. The rule engine decides intent (may this be attempted?); the
+sandbox enforces reality (what can the process actually touch?). Neither is
+trusted to be sufficient alone - a mis-parsed command escapes the engine, and a
+sandbox cannot tell a wanted `rm` from an unwanted one.
+"""