voidx 1.0.0__py3-none-any.whl

voidx/mcp/manager.py

@@ -0,0 +1,267 @@
+"""MCP manager — lifecycle orchestrator for all MCP server connections.
+
+Responsibilities:
+  - Reads server configs from Settings
+  - Spawns McpClient per server
+  - Discovers tools and registers them in ToolRegistry
+  - Exposes status for UI
+  - Clean shutdown on graph exit
+
+Design: all servers start in parallel, a single failure doesn't block others.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from voidx.config import McpServerConfig, Settings
+from voidx.mcp.client import McpClient, McpConnectionError
+from voidx.mcp.schema import McpCallResult, McpRuntimeStatus, McpToolDef
+from voidx.mcp.tool import McpToolWrapper, mcp_tool_id
+from voidx.permission.service import PermissionService
+from voidx.tools.registry import ToolRegistry
+
+log = logging.getLogger(__name__)
+
+
+class McpManager:
+    """Manages all MCP server connections for a session."""
+
+    def __init__(self, settings: Settings | None, registry: ToolRegistry, permission: PermissionService) -> None:
+        self._settings = settings
+        self._registry = registry
+        self._permission = permission
+        self._clients: dict[str, McpClient] = {}
+        self._started = False
+        self._tool_counts: dict[str, int] = {}
+        self._errors: dict[str, str] = {}
+
+    @property
+    def started(self) -> bool:
+        return self._started
+
+    # ── lifecycle ───────────────────────────────────────────────────────
+
+    async def start_all(self) -> None:
+        """Start all configured MCP servers and register their tools.
+
+        Servers start in parallel. A failed server doesn't block others.
+        """
+        if self._started:
+            return
+        self._started = True
+        self._registry.unregister_prefix("mcp__")
+        self._tool_counts.clear()
+
+        if self._settings is None:
+            return
+
+        servers = self._settings.list_mcp_servers()
+        if not servers:
+            return
+
+        enabled = [s for s in servers if not s.disabled]
+        if not enabled:
+            return
+
+        log.info("Starting %d MCP server(s)...", len(enabled))
+
+        # Start all servers concurrently
+        results = await self._start_servers(enabled)
+
+        # Register tools from successfully started servers
+        for server_name, client in results:
+            try:
+                tool_defs = await client.list_tools()
+            except Exception as e:
+                log.warning("Could not list tools from MCP server '%s': %s", server_name, e)
+                self._errors[server_name] = f"Could not list tools: {e}"
+                self._tool_counts[server_name] = 0
+                continue
+            self._errors.pop(server_name, None)
+
+            allowed = self._resolve_tool_filter(
+                next((s for s in servers if s.name == server_name), None)
+            )
+
+            registered = 0
+            for td in tool_defs:
+                if allowed is not None and td.name not in allowed:
+                    continue
+                wrapper = McpToolWrapper(client, td, server_name)
+                self._registry.register(
+                    wrapper.id,
+                    wrapper,
+                    wrapper.description,
+                    wrapper.parameters_schema(),
+                )
+                registered += 1
+
+            # Pre-deny tools that are in deny filter (user explicitly wants them blocked)
+            disallowed = self._resolve_tool_filter(
+                next((s for s in servers if s.name == server_name), None),
+                allow_mode=False,
+            )
+            if disallowed:
+                for tool_name in disallowed:
+                    tool_id = mcp_tool_id(server_name, tool_name)
+                    self._permission.deny_silent(tool_id)
+
+            log.info(
+                "MCP server '%s': %d tools registered",
+                server_name, registered,
+            )
+            self._tool_counts[server_name] = registered
+
+    async def stop_all(self) -> None:
+        """Gracefully stop all MCP server connections."""
+        self._started = False
+        self._registry.unregister_prefix("mcp__")
+        self._tool_counts.clear()
+        if not self._clients:
+            return
+
+        log.info("Stopping %d MCP server(s)...", len(self._clients))
+        await self._stop_servers(list(self._clients.values()))
+        self._clients.clear()
+
+    async def reconnect(self, server_name: str) -> bool:
+        """Attempt to reconnect a specific server."""
+        client = self._clients.get(server_name)
+        if client is None:
+            return False
+        return await client.reconnect()
+
+    async def restart_all(self) -> None:
+        """Restart all configured server connections and re-register tools."""
+        await self.stop_all()
+        await self.start_all()
+
+    async def list_tools_for_server(self, server_name: str) -> list[McpToolDef]:
+        """List tools from a connected server."""
+        client = self._clients.get(server_name)
+        if client is None:
+            raise McpConnectionError(f"MCP server '{server_name}' is not connected")
+        return await client.list_tools()
+
+    async def call_tool(
+        self,
+        server_name: str,
+        tool_name: str,
+        arguments: dict,
+    ) -> McpCallResult:
+        """Call a tool on a connected MCP server."""
+        client = self._clients.get(server_name)
+        if client is None:
+            raise McpConnectionError(f"MCP server '{server_name}' is not connected")
+        if not client.healthy:
+            ok = await client.reconnect()
+            if not ok:
+                raise McpConnectionError(
+                    f"MCP server '{server_name}' is unavailable: {client.error_message}"
+                )
+        return await client.call_tool(tool_name, arguments)
+
+    def statuses(self) -> list[McpRuntimeStatus]:
+        """Return runtime status of all configured servers (for UI)."""
+        if self._settings is None:
+            return []
+
+        servers = self._settings.list_mcp_servers()
+        result: list[McpRuntimeStatus] = []
+        for sc in servers:
+            if sc.disabled:
+                result.append(McpRuntimeStatus(
+                    name=sc.name,
+                    status="disabled",
+                ))
+                continue
+
+            client = self._clients.get(sc.name)
+            if client is None:
+                error = self._errors.get(sc.name, "")
+                result.append(McpRuntimeStatus(
+                    name=sc.name,
+                    status="error" if error else "disconnected",
+                    error_message=error,
+                ))
+            else:
+                error = self._errors.get(sc.name, "")
+                result.append(McpRuntimeStatus(
+                    name=sc.name,
+                    status="error" if error else client.status,
+                    tool_count=self._tool_counts.get(sc.name, 0),
+                    error_message=error or client.error_message,
+                ))
+        return result
+
+    # ── internal ────────────────────────────────────────────────────────
+
+    async def _start_servers(self, configs: list[McpServerConfig]) -> list[tuple[str, McpClient]]:
+        """Start multiple servers in parallel, collect successes."""
+        async def try_start(sc: McpServerConfig) -> tuple[str, McpClient] | None:
+            if sc.name in self._clients:
+                return sc.name, self._clients[sc.name]
+            client = McpClient(sc)
+            try:
+                await client.start()
+                self._clients[sc.name] = client
+                self._errors.pop(sc.name, None)
+                return sc.name, client
+            except McpConnectionError as e:
+                log.warning("MCP server '%s' failed to start: %s", sc.name, e)
+                self._errors[sc.name] = str(e)
+                return None
+
+        tasks = [try_start(sc) for sc in configs]
+        results = await self._gather_safe(tasks)
+
+        successes: list[tuple[str, McpClient]] = []
+        for entry in results:
+            if entry is not None and not isinstance(entry, BaseException):
+                successes.append(entry)
+        return successes
+
+    async def _stop_servers(self, clients: list[McpClient]) -> None:
+        """Stop multiple servers in parallel."""
+        async def safe_stop(client: McpClient) -> None:
+            try:
+                await client.stop()
+            except Exception:
+                log.exception("Error stopping MCP server '%s'", client.server_name)
+
+        await self._gather_safe([safe_stop(c) for c in clients])
+
+    @staticmethod
+    async def _gather_safe(tasks: list) -> list:
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        return [None if isinstance(r, BaseException) else r for r in results]
+
+    @staticmethod
+    def _resolve_tool_filter(
+        server_config: McpServerConfig | None, allow_mode: bool = True,
+    ) -> set[str] | None:
+        """Resolve the tools filter from server config.
+
+        If allow_mode=True: returns the set of tool names that ARE allowed.
+        If allow_mode=False: returns the set of tool names that are DENIED.
+        """
+        if server_config is None:
+            return None
+        tools_field = getattr(server_config, "tools", None)
+        if tools_field is None:
+            return None
+        if isinstance(tools_field, list):
+            # List of tool names that are allowed
+            if len(tools_field) == 0:
+                return set() if allow_mode else None
+            return set(tools_field) if allow_mode else None
+        if isinstance(tools_field, dict):
+            if allow_mode:
+                allowed = {k for k, v in tools_field.items() if v}
+                return allowed if allowed else None
+            else:
+                denied = {k for k, v in tools_field.items() if not v}
+                return denied if denied else None
+        return None

voidx/mcp/schema.py

@@ -0,0 +1,112 @@
+"""MCP protocol types — JSON-RPC wire format, tool definitions, call results.
+
+Based on the Model Context Protocol specification:
+  https://spec.modelcontextprotocol.io/
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# ── JSON-RPC 2.0 ──────────────────────────────────────────────────────────
+
+
+@dataclass
+class JsonRpcRequest:
+    """A JSON-RPC 2.0 request message."""
+    jsonrpc: str = "2.0"
+    id: int = 0
+    method: str = ""
+    params: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "id": self.id,
+            "method": self.method,
+        }
+        if self.params:
+            d["params"] = self.params
+        return d
+
+
+@dataclass
+class JsonRpcResponse:
+    """A JSON-RPC 2.0 response message."""
+    id: int = 0
+    result: Any = None
+    error: dict[str, Any] | None = None
+
+
+@dataclass
+class JsonRpcNotification:
+    """A JSON-RPC 2.0 notification (no id, no response expected)."""
+    jsonrpc: str = "2.0"
+    method: str = ""
+    params: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "method": self.method,
+        }
+        if self.params:
+            d["params"] = self.params
+        return d
+
+
+# ── MCP protocol messages ─────────────────────────────────────────────────
+
+
+MCP_PROTOCOL_VERSION = "2025-03-26"
+
+
+@dataclass
+class McpInitializeParams:
+    """Parameters for the initialize request."""
+    protocol_version: str = MCP_PROTOCOL_VERSION
+    capabilities: dict[str, Any] = field(default_factory=lambda: {
+        "roots": {"listChanged": False},
+        "sampling": {},
+    })
+    client_info: dict[str, str] = field(default_factory=lambda: {
+        "name": "voidx",
+        "version": "1.0.0",
+    })
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "protocolVersion": self.protocol_version,
+            "capabilities": self.capabilities,
+            "clientInfo": self.client_info,
+        }
+
+
+@dataclass
+class McpToolDef:
+    """A tool exposed by an MCP server."""
+    name: str
+    description: str = ""
+    inputSchema: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class McpCallResult:
+    """Result from a tools/call request."""
+    content: list[dict[str, Any]] = field(default_factory=list)
+    isError: bool = False
+    structured_content: Any = None
+
+
+# ── Server status (for UI consumption) ────────────────────────────────────
+
+
+@dataclass
+class McpRuntimeStatus:
+    """Runtime status of a single MCP server connection."""
+    name: str
+    status: str  # "connected" | "disconnected" | "error"
+    tool_count: int = 0
+    error_message: str = ""

voidx/mcp/tool.py

@@ -0,0 +1,122 @@
+"""MCP tool wrapper — adapts MCP server tools into voidx's BaseTool interface.
+
+Each discovered MCP tool becomes a McpToolWrapper registered in ToolRegistry
+with an LLM-safe id derived from the server and tool name.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any
+
+from voidx.mcp.client import McpClient, McpConnectionError, McpProtocolError, McpTimeoutError
+from voidx.mcp.schema import McpCallResult, McpToolDef
+from voidx.tools.base import BaseTool, ToolResult, ToolContext
+
+
+_LLM_TOOL_NAME_MAX = 64
+_INVALID_TOOL_NAME_CHARS = re.compile(r"[^A-Za-z0-9_-]+")
+
+
+def mcp_tool_id(server_name: str, tool_name: str) -> str:
+    raw = f"mcp__{server_name}__{tool_name}"
+    readable = _INVALID_TOOL_NAME_CHARS.sub("_", raw).strip("_") or "mcp_tool"
+    digest = hashlib.sha1(f"{server_name}\0{tool_name}".encode("utf-8")).hexdigest()[:8]
+    suffix = f"_{digest}"
+    if len(readable) + len(suffix) > _LLM_TOOL_NAME_MAX:
+        readable = readable[: _LLM_TOOL_NAME_MAX - len(suffix)].rstrip("_-") or "mcp_tool"
+    return f"{readable}{suffix}"
+
+
+class McpToolWrapper(BaseTool):
+    """Wraps an MCP server tool as a voidx BaseTool."""
+
+    def __init__(self, client: McpClient, tool_def: McpToolDef, server_name: str) -> None:
+        self._client = client
+        self._tool_def = tool_def
+        self._server = server_name
+
+    @property
+    def id(self) -> str:
+        return mcp_tool_id(self._server, self._tool_def.name)
+
+    @property
+    def description(self) -> str:
+        desc = self._tool_def.description or f"MCP tool from {self._server}"
+        return f"[MCP:{self._server}] {desc}"
+
+    def parameters_schema(self) -> dict[str, Any]:
+        return self._tool_def.inputSchema or {"type": "object", "properties": {}}
+
+    async def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        if not self._client.healthy:
+            return ToolResult(
+                output=f"MCP server '{self._server}' is not connected. "
+                       f"Status: {self._client.status}."
+                       f"{' ' + self._client.error_message if self._client.error_message else ''}",
+                metadata={"error": True, "server": self._server},
+            )
+        try:
+            result: McpCallResult = await self._client.call_tool(self._tool_def.name, args)
+        except (McpConnectionError, McpTimeoutError, McpProtocolError) as e:
+            return ToolResult(
+                output=f"MCP server '{self._server}' is unavailable: {e}",
+                metadata={"error": True, "server": self._server, "error_type": type(e).__name__},
+            )
+        except Exception as e:
+            return ToolResult(
+                output=f"MCP tool '{self._tool_def.name}' error: {e}",
+                metadata={"error": True, "server": self._server, "error_type": type(e).__name__},
+            )
+
+        output = format_mcp_call_result(result)
+        meta: dict[str, Any] = {"server": self._server}
+        if result.isError:
+            meta["error"] = True
+
+        return ToolResult(output=output, metadata=meta)
+
+
+def format_mcp_call_result(result: McpCallResult) -> str:
+    parts = [_format_content_block(block) for block in result.content]
+    if result.structured_content is not None:
+        parts.append(
+            "Structured content:\n"
+            + json.dumps(result.structured_content, ensure_ascii=False, indent=2, default=str)
+        )
+    rendered = [part for part in parts if part]
+    return "\n".join(rendered) if rendered else "(empty response)"
+
+
+def _format_content_block(block: Any) -> str:
+    if not isinstance(block, dict):
+        return str(block) if block is not None else ""
+
+    block_type = block.get("type", "")
+    if block_type == "text":
+        text = block.get("text", "")
+        return text if isinstance(text, str) else str(text)
+
+    if block_type == "image":
+        mime = block.get("mimeType") or block.get("mime_type") or "unknown"
+        data = block.get("data", "")
+        size = len(data) if isinstance(data, str) else 0
+        return f"[image {mime}, {size} base64 chars]"
+
+    if block_type == "resource":
+        resource = block.get("resource")
+        if isinstance(resource, dict):
+            uri = resource.get("uri", "resource")
+            mime = resource.get("mimeType") or resource.get("mime_type") or ""
+            header = f"[resource {uri}{f' ({mime})' if mime else ''}]"
+            text = resource.get("text")
+            if isinstance(text, str):
+                return f"{header}\n{text}"
+            blob = resource.get("blob")
+            if isinstance(blob, str):
+                return f"{header}\n[{len(blob)} base64 chars]"
+            return header
+
+    return json.dumps(block, ensure_ascii=False, sort_keys=True, default=str)

voidx/mcp_servers/__init__.py

@@ -0,0 +1 @@
+"""Built-in MCP servers shipped with voidx."""

voidx/mcp_servers/web.py

@@ -0,0 +1,104 @@
+"""Built-in line-delimited JSON-RPC MCP server for web tools."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from typing import Any
+
+from voidx.mcp.schema import MCP_PROTOCOL_VERSION
+from voidx.tools.base import BaseTool, ToolContext
+from voidx.tools.webfetch import WebFetchTool
+from voidx.tools.websearch import WebSearchTool
+
+
+def _tools() -> dict[str, BaseTool]:
+    return {
+        "web_search": WebSearchTool(settings=None),
+        "web_fetch": WebFetchTool(settings=None),
+    }
+
+
+async def _handle(message: dict[str, Any], tools: dict[str, BaseTool]) -> dict[str, Any] | None:
+    method = message.get("method")
+    msg_id = message.get("id")
+
+    if method == "initialize":
+        params = message.get("params", {})
+        protocol_version = params.get("protocolVersion") or MCP_PROTOCOL_VERSION
+        return _result(msg_id, {
+            "protocolVersion": protocol_version,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "voidx-web", "version": "1.0.0"},
+        })
+
+    if method == "notifications/initialized":
+        return None
+
+    if method == "tools/list":
+        return _result(msg_id, {
+            "tools": [
+                {
+                    "name": name,
+                    "description": tool.description,
+                    "inputSchema": tool.parameters_schema(),
+                }
+                for name, tool in tools.items()
+            ]
+        })
+
+    if method == "tools/call":
+        params = message.get("params", {})
+        name = params.get("name", "")
+        args = params.get("arguments", {})
+        tool = tools.get(name)
+        if tool is None:
+            return _error(msg_id, -32602, f"Unknown tool: {name}")
+        result = await tool.execute(args if isinstance(args, dict) else {}, ToolContext(workspace="."))
+        is_error = bool(result.metadata.get("error"))
+        return _result(msg_id, {
+            "content": [{"type": "text", "text": result.output}],
+            "isError": is_error,
+            "structuredContent": result.metadata,
+        })
+
+    if method == "shutdown":
+        return None
+
+    if msg_id is None:
+        return None
+    return _error(msg_id, -32601, f"Method not found: {method}")
+
+
+def _result(msg_id: Any, result: Any) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": msg_id, "result": result}
+
+
+def _error(msg_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": msg_id, "error": {"code": code, "message": message}}
+
+
+async def amain() -> None:
+    tools = _tools()
+    while True:
+        raw = await asyncio.to_thread(sys.stdin.readline)
+        if not raw:
+            break
+        try:
+            message = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        if message.get("method") == "shutdown":
+            break
+        response = await _handle(message, tools)
+        if response is not None:
+            print(json.dumps(response, ensure_ascii=False), flush=True)
+
+
+def main() -> None:
+    asyncio.run(amain())
+
+
+if __name__ == "__main__":
+    main()