agentkernel-cli 0.1.0__py3-none-any.whl

agentkernel/mcp/client.py

@@ -0,0 +1,181 @@
+"""A minimal MCP client over JSON-RPC 2.0 stdio (Phase 2).
+
+Messages are newline-delimited JSON objects exchanged with the server
+subprocess's stdin/stdout. A background reader thread drains stdout into a
+queue so requests can wait with a timeout (a misbehaving server must never hang
+the agent loop).
+
+This client supports exactly what tool discovery and invocation need:
+``initialize`` → ``notifications/initialized`` → ``tools/list`` / ``tools/call``.
+Server-initiated requests (sampling, roots) are ignored in v1.
+
+When ``log_dir`` is provided, each server's stderr is captured to a file
+``<log_dir>/<server-name>.log`` for post-mortem debugging.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import subprocess
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from agentkernel import __version__
+from agentkernel.mcp.config import MCPServerConfig
+
+PROTOCOL_VERSION = "2024-11-05"
+
+
+class MCPError(RuntimeError):
+    """An MCP transport or protocol fault (connection, timeout, JSON-RPC error)."""
+
+
+class MCPClient:
+    """Connects to one MCP server over stdio and issues JSON-RPC requests."""
+
+    def __init__(
+        self,
+        config: MCPServerConfig,
+        *,
+        timeout: float = 30.0,
+        log_dir: str | None = None,
+    ) -> None:
+        self._config = config
+        self._timeout = timeout
+        self._log_dir = log_dir
+        self._proc: subprocess.Popen | None = None
+        self._reader: threading.Thread | None = None
+        self._stderr_reader: threading.Thread | None = None
+        self._incoming: queue.Queue[dict[str, Any]] = queue.Queue()
+        self._next_id = 0
+        self.server_info: dict[str, Any] | None = None
+        self.stderr_log_path: str | None = None
+
+    # --- lifecycle ---------------------------------------------------------
+
+    def connect(self) -> MCPClient:
+        if self._proc is not None:
+            raise MCPError(f"MCP client {self._config.name!r} is already connected")
+        env = {**os.environ, **(self._config.env or {})}
+
+        stderr_target: int = subprocess.DEVNULL
+        if self._log_dir:
+            log_path = Path(self._log_dir)
+            log_path.mkdir(parents=True, exist_ok=True)
+            self.stderr_log_path = str(log_path / f"{self._config.name}.log")
+            stderr_target = subprocess.PIPE
+
+        try:
+            self._proc = subprocess.Popen(
+                [self._config.command, *self._config.args],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=stderr_target,
+                text=True,
+                bufsize=1,
+                env=env,
+                cwd=self._config.cwd,
+            )
+        except (OSError, ValueError) as exc:
+            raise MCPError(f"failed to launch MCP server {self._config.name!r}: {exc}")
+
+        self._reader = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader.start()
+
+        if self.stderr_log_path is not None and self._proc.stderr is not None:
+            self._stderr_reader = threading.Thread(
+                target=self._read_loop_stderr,
+                args=(self.stderr_log_path, self._proc.stderr),
+                daemon=True,
+            )
+            self._stderr_reader.start()
+
+        result = self._request(
+            "initialize",
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": {"name": "agentkernel", "version": __version__},
+            },
+        )
+        self.server_info = result.get("serverInfo")
+        self._notify("notifications/initialized", {})
+        return self
+
+    def close(self) -> None:
+        proc, self._proc = self._proc, None
+        if proc is None or proc.poll() is not None:
+            return
+        try:
+            proc.terminate()
+            proc.wait(timeout=5)
+        except Exception:  # noqa: BLE001 - best effort shutdown
+            proc.kill()
+        # Give the stderr logger a moment to drain and flush.
+        if self._stderr_reader is not None:
+            self._stderr_reader.join(timeout=1.0)
+
+    # --- MCP operations ----------------------------------------------------
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        return self._request("tools/list", {}).get("tools", [])
+
+    def call_tool(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        return self._request("tools/call", {"name": name, "arguments": arguments})
+
+    # --- JSON-RPC plumbing -------------------------------------------------
+
+    def _read_loop(self) -> None:
+        assert self._proc is not None and self._proc.stdout is not None
+        for line in self._proc.stdout:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                self._incoming.put(json.loads(line))
+            except json.JSONDecodeError:
+                continue  # ignore non-JSON noise on stdout
+
+    def _read_loop_stderr(self, log_path: str, stream) -> None:
+        with open(log_path, "a", encoding="utf-8") as fh:
+            for line in stream:
+                fh.write(line)
+                fh.flush()
+
+    def _send(self, message: dict[str, Any]) -> None:
+        if self._proc is None or self._proc.poll() is not None:
+            raise MCPError(f"MCP server {self._config.name!r} is not running")
+        assert self._proc.stdin is not None
+        self._proc.stdin.write(json.dumps(message) + "\n")
+        self._proc.stdin.flush()
+
+    def _notify(self, method: str, params: dict[str, Any]) -> None:
+        self._send({"jsonrpc": "2.0", "method": method, "params": params})
+
+    def _request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        request_id = self._next_id
+        self._next_id += 1
+        self._send({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params})
+
+        deadline = time.monotonic() + self._timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise MCPError(f"timed out waiting for response to {method!r}")
+            try:
+                msg = self._incoming.get(timeout=remaining)
+            except queue.Empty:
+                raise MCPError(f"timed out waiting for response to {method!r}")
+            # Skip server-initiated requests/notifications and stale responses.
+            if msg.get("method") is not None or msg.get("id") != request_id:
+                continue
+            if "error" in msg:
+                err = msg["error"]
+                raise MCPError(
+                    f"{method!r} failed: {err.get('message')} (code {err.get('code')})"
+                )
+            return msg.get("result", {})

agentkernel/mcp/config.py

@@ -0,0 +1,59 @@
+"""MCP server declarations (Phase 2).
+
+Servers are declared in the config TOML as an array of tables:
+
+    [[mcp_servers]]
+    name = "filesystem"
+    command = "npx"
+    args = ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    timeout = 60
+
+    [[mcp_servers]]
+    name = "git"
+    command = "uvx"
+    args = ["mcp-server-git"]
+    env = { GIT_AUTHOR_NAME = "agent" }
+
+This loader is kept separate from ``Config`` because the scalar config loader
+(``config.py``) only handles flat values, while server definitions are nested.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class MCPServerConfig:
+    """How to launch and connect to one MCP server over stdio."""
+
+    name: str
+    command: str
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] | None = None
+    cwd: str | None = None
+    timeout: float | None = None  # seconds; falls back to MCPClient default (30)
+
+
+def load_mcp_servers(config_file: str | Path) -> list[MCPServerConfig]:
+    """Read ``[[mcp_servers]]`` from the config TOML. Missing file → no servers."""
+    path = Path(config_file)
+    if not path.is_file():
+        return []
+    with path.open("rb") as fh:
+        data = tomllib.load(fh)
+    servers: list[MCPServerConfig] = []
+    for entry in data.get("mcp_servers", []):
+        servers.append(
+            MCPServerConfig(
+                name=entry["name"],
+                command=entry["command"],
+                args=list(entry.get("args", [])),
+                env=entry.get("env"),
+                cwd=entry.get("cwd"),
+                timeout=entry.get("timeout"),
+            )
+        )
+    return servers

agentkernel/mcp/tools.py

@@ -0,0 +1,96 @@
+"""Adapt MCP tools into the kernel's ``ToolSpec`` (Phase 2, design §13).
+
+Each discovered MCP tool becomes a ``ToolSpec`` whose handler issues a
+``tools/call`` and maps the MCP result back to a canonical ``ToolResult``. The
+registry and loop are untouched — this module is the entire MCP seam.
+
+Gating: MCP tools can do anything, so they default to ``requires_approval``.
+A tool that advertises ``annotations.readOnlyHint`` is treated as read-only and
+left ungated.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from agentkernel.mcp.client import MCPClient, MCPError
+from agentkernel.tools.base import ToolSpec
+from agentkernel.types import ToolResult
+
+if TYPE_CHECKING:
+    from agentkernel.mcp.config import MCPServerConfig
+    from agentkernel.tools import ToolRegistry
+
+
+def _result_to_tool_result(result: dict[str, Any]) -> ToolResult:
+    """Flatten an MCP call result's content blocks into a ToolResult."""
+    text_parts = [
+        block.get("text", "")
+        for block in result.get("content", [])
+        if block.get("type") == "text"
+    ]
+    content = "\n".join(p for p in text_parts if p) or "(no text content)"
+    return ToolResult(
+        "",
+        content,
+        is_error=bool(result.get("isError", False)),
+        data={"mcp_result": result},
+    )
+
+
+def _make_handler(client: MCPClient, name: str):
+    def handler(arguments: dict[str, Any]) -> ToolResult:
+        try:
+            result = client.call_tool(name, arguments)
+        except MCPError as exc:
+            # Transport/protocol faults become error results, not raises, so the
+            # model can recover (design §8.3).
+            return ToolResult("", f"MCP error: {exc}", is_error=True)
+        return _result_to_tool_result(result)
+
+    return handler
+
+
+def mcp_tool_specs(client: MCPClient) -> list[ToolSpec]:
+    """Discover the client's tools and wrap each as a ToolSpec."""
+    specs: list[ToolSpec] = []
+    for tool in client.list_tools():
+        annotations = tool.get("annotations") or {}
+        read_only = bool(annotations.get("readOnlyHint", False))
+        specs.append(
+            ToolSpec(
+                name=tool["name"],
+                description=tool.get("description", ""),
+                parameters=tool.get("inputSchema") or {"type": "object"},
+                handler=_make_handler(client, tool["name"]),
+                requires_approval=not read_only,
+                mutates=not read_only,
+                category="mcp",
+            )
+        )
+    return specs
+
+
+def register_mcp_servers(
+    registry: ToolRegistry, servers: list[MCPServerConfig], log_dir: str | None = None
+) -> list[MCPClient]:
+    """Connect each server and register its tools. Returns the open clients so
+    the caller can close them. On any failure, already-opened clients are
+    closed before the error propagates.
+
+    ``log_dir`` optionally captures each server's stderr to
+    ``<log_dir>/<server-name>.log``."""
+    clients: list[MCPClient] = []
+    try:
+        for server in servers:
+            client = MCPClient(
+                server, timeout=server.timeout or 30.0, log_dir=log_dir
+            ).connect()
+            clients.append(client)
+            for spec in mcp_tool_specs(client):
+                registry.register(spec)
+    except Exception:
+        for client in clients:
+            client.close()
+        raise
+    return clients