nexus-dev 3.3.1__py3-none-any.whl

nexus_dev/mcp_client.py

@@ -0,0 +1,281 @@
+"""MCP Client for connecting to backend MCP servers."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from mcp.client.stdio import StdioServerParameters, stdio_client
+
+
+@dataclass
+class MCPToolSchema:
+    """Schema for an MCP tool."""
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+
+
+@dataclass
+class MCPServerConnection:
+    """Connection to an MCP server."""
+
+    name: str
+    command: str
+    args: list[str]
+    env: dict[str, str] | None = None
+    transport: str = "stdio"
+    url: str | None = None
+    headers: dict[str, str] | None = None
+    timeout: float = 30.0
+
+
+class MCPClientManager:
+    """Manages connections to multiple MCP servers."""
+
+    async def get_tools(self, server: MCPServerConnection) -> list[MCPToolSchema]:
+        """Get all tools from an MCP server.
+
+        Args:
+            server: Server connection config
+
+        Returns:
+            List of tool schemas
+        """
+        if server.transport == "http":
+            if not server.url:
+                raise ValueError(f"URL required for HTTP transport: {server.name}")
+
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    server.url,
+                    headers=server.headers,
+                    json={
+                        "jsonrpc": "2.0",
+                        "id": 1,
+                        "method": "tools/list",
+                        "params": {},
+                    },
+                    timeout=server.timeout,
+                )
+                response.raise_for_status()
+                try:
+                    data = response.json()
+                except Exception:
+                    # Check for SSE-wrapped JSON (Github quirk)
+                    text = response.text
+                    if "data: " in text:
+                        # Extract JSON from data lines
+                        json_lines = []
+                        for line in text.splitlines():
+                            if line.startswith("data: "):
+                                json_lines.append(line.replace("data: ", "", 1))
+
+                        try:
+                            data = json.loads("".join(json_lines))
+                        except Exception as e:
+                            raise RuntimeError(
+                                f"Failed to parse SSE-wrapped JSON from {server.url}. "
+                                f"Status: {response.status_code}. Body: {response.text[:200]}..."
+                            ) from e
+                    else:
+                        raise RuntimeError(
+                            f"Failed to decode JSON response from {server.url}. "
+                            f"Status: {response.status_code}. Body: {response.text[:200]}..."
+                        ) from None
+
+                if "error" in data:
+                    raise RuntimeError(f"JSON-RPC error: {data['error']}")
+
+                schemas = []
+                # Result structure: {"result": {"tools": [...]}}
+                tools_data = data.get("result", {}).get("tools", [])
+                for tool in tools_data:
+                    schemas.append(
+                        MCPToolSchema(
+                            name=tool.get("name"),
+                            description=tool.get("description", ""),
+                            input_schema=tool.get("inputSchema", {}),
+                        )
+                    )
+                return schemas
+
+        elif server.transport == "sse":
+            if not server.url:
+                raise ValueError(f"URL required for SSE transport: {server.name}")
+
+            transport_cm = sse_client(
+                url=server.url,
+                headers=server.headers or {},
+            )
+        else:
+            # Expand environment variables if needed
+            env = expand_env_vars(server.env) if server.env else None
+
+            # Create server parameters
+            server_params = StdioServerParameters(command=server.command, args=server.args, env=env)
+            transport_cm = stdio_client(server_params)
+
+        async with (
+            transport_cm as (read, write),
+            ClientSession(read, write) as session,
+        ):
+            await session.initialize()
+
+            # List tools
+            tools_result = await session.list_tools()
+
+            schemas = []
+            for tool in tools_result.tools:
+                schemas.append(
+                    MCPToolSchema(
+                        name=tool.name,
+                        description=tool.description or "",
+                        input_schema=tool.inputSchema or {},
+                    )
+                )
+
+            return schemas
+
+    async def get_tool_schema(
+        self, server: MCPServerConnection, tool_name: str
+    ) -> MCPToolSchema | None:
+        """Get schema for a specific tool.
+
+        Note: The MCP protocol doesn't support fetching individual tool schemas,
+        so this method fetches all tools and filters locally. For servers with
+        many tools, consider calling get_tools() once and caching the results.
+
+        Args:
+            server: Server connection config
+            tool_name: Name of the tool to get schema for
+
+        Returns:
+            Tool schema if found, None otherwise
+        """
+        tools = await self.get_tools(server)
+        for tool in tools:
+            if tool.name == tool_name:
+                return tool
+        return None
+
+    async def call_tool(
+        self,
+        server: MCPServerConnection,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        """Call a tool on an MCP server.
+
+        Args:
+            server: Server connection config
+            tool_name: Name of the tool to call
+            arguments: Tool arguments
+
+        Returns:
+            Tool execution result
+        """
+        if server.transport == "http":
+            if not server.url:
+                raise ValueError(f"URL required for HTTP transport: {server.name}")
+
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    server.url,
+                    headers=server.headers,
+                    json={
+                        "jsonrpc": "2.0",
+                        "id": 1,
+                        "method": "tools/call",
+                        "params": {
+                            "name": tool_name,
+                            "arguments": arguments or {},
+                        },
+                    },
+                    timeout=server.timeout,
+                )
+                response.raise_for_status()
+
+                try:
+                    data = response.json()
+                except Exception:
+                    # Check for SSE-wrapped JSON (Github quirk)
+                    text = response.text
+                    if "data: " in text:
+                        # Extract JSON from data lines
+                        json_lines = []
+                        for line in text.splitlines():
+                            if line.startswith("data: "):
+                                json_lines.append(line.replace("data: ", "", 1))
+
+                        try:
+                            data = json.loads("".join(json_lines))
+                        except Exception as e:
+                            # print(f"ERROR: Failed to parse SSE JSON. Body: {response.text}")
+                            raise RuntimeError(
+                                f"Failed to parse SSE-wrapped JSON from {server.url}. "
+                                f"Status: {response.status_code}. Body: {response.text[:200]}..."
+                            ) from e
+                    else:
+                        # print(f"ERROR: Failed to parse JSON. Body: {response.text}")
+                        raise RuntimeError(
+                            f"Failed to decode JSON response from {server.url}. "
+                            f"Status: {response.status_code}. Body: {response.text[:200]}..."
+                        ) from None
+
+                if "error" in data:
+                    raise RuntimeError(f"JSON-RPC error: {data['error']}")
+
+                return data.get("result", {})
+
+        elif server.transport == "sse":
+            if not server.url:
+                raise ValueError(f"URL required for SSE transport: {server.name}")
+
+            transport_cm = sse_client(
+                url=server.url,
+                headers=server.headers or {},
+            )
+        else:
+            # Expand environment variables if needed
+            env = expand_env_vars(server.env) if server.env else None
+
+            # Create server parameters
+            server_params = StdioServerParameters(command=server.command, args=server.args, env=env)
+            transport_cm = stdio_client(server_params)
+
+        async with (
+            transport_cm as (read, write),
+            ClientSession(read, write) as session,
+        ):
+            await session.initialize()
+            return await session.call_tool(tool_name, arguments or {})
+
+
+def expand_env_vars(env: dict[str, str]) -> dict[str, str]:
+    """Expand ${VAR} patterns in environment dict.
+
+    Args:
+        env: Dictionary of environment variables with potential ${VAR} patterns
+
+    Returns:
+        Dictionary with expanded environment variables
+    """
+    result = {}
+    pattern = re.compile(r"\$\{(\w+)\}")
+
+    def replacer(match: re.Match[str]) -> str:
+        var_name = match.group(1)
+        return os.environ.get(var_name, "")
+
+    for key, value in env.items():
+        result[key] = pattern.sub(replacer, value)
+
+    return result

nexus_dev/mcp_config.py

@@ -0,0 +1,184 @@
+"""MCP Configuration management for Nexus-Dev."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+import jsonschema  # type: ignore[import-untyped]
+
+
+@dataclass
+class MCPServerConfig:
+    """Individual MCP server configuration."""
+
+    command: str | None = None
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    enabled: bool = True
+    transport: Literal["stdio", "sse", "http"] = "stdio"
+    url: str | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+    timeout: float = 30.0  # Tool execution timeout
+    connect_timeout: float = 10.0  # Connection timeout
+
+
+@dataclass
+class GatewaySettings:
+    """Global gateway configuration settings."""
+
+    default_timeout: float = 30.0
+    max_concurrent_connections: int = 5
+
+
+@dataclass
+class MCPConfig:
+    """Nexus-Dev MCP project configuration."""
+
+    version: str
+    servers: dict[str, MCPServerConfig]
+    profiles: dict[str, list[str]] = field(default_factory=dict)
+    active_profile: str = "default"
+    gateway: GatewaySettings = field(default_factory=GatewaySettings)
+
+    @classmethod
+    def load(cls, path: str | Path) -> MCPConfig:
+        """Load and validate configuration from a JSON file.
+
+        Args:
+            path: Path to the configuration file.
+
+        Returns:
+            Validated MCPConfig instance.
+
+        Raises:
+            FileNotFoundError: If configuration file doesn't exist.
+            ValueError: If configuration is invalid against the schema.
+        """
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f"MCP configuration file not found: {path}")
+
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+
+        cls.validate(data)
+
+        servers = {
+            name: MCPServerConfig(
+                command=cfg.get("command"),
+                args=cfg.get("args", []),
+                env=cfg.get("env", {}),
+                enabled=cfg.get("enabled", True),
+                transport=cfg.get("transport", "stdio"),
+                url=cfg.get("url"),
+                headers=cfg.get("headers", {}),
+                timeout=cfg.get("timeout", 30.0),
+                connect_timeout=cfg.get("connect_timeout", 10.0),
+            )
+            for name, cfg in data["servers"].items()
+        }
+
+        profiles = data.get("profiles", {})
+        active_profile = data.get("active_profile", "default")
+
+        gateway_data = data.get("gateway", {})
+        gateway = GatewaySettings(
+            default_timeout=gateway_data.get("default_timeout", 30.0),
+            max_concurrent_connections=gateway_data.get("max_concurrent_connections", 5),
+        )
+
+        return cls(
+            version=data["version"],
+            servers=servers,
+            profiles=profiles,
+            active_profile=active_profile,
+            gateway=gateway,
+        )
+
+    def get_active_servers(self) -> list[MCPServerConfig]:
+        """Get a list of enabled MCP server configurations in the active profile.
+
+        Returns:
+            List of enabled MCPServerConfig instances from the active profile.
+        """
+        # If active profile doesn't exist or is empty, return all enabled servers
+        if self.active_profile not in self.profiles:
+            return [s for s in self.servers.values() if s.enabled]
+
+        # Get servers in active profile
+        profile_server_names = self.profiles[self.active_profile]
+        active_servers = []
+
+        for name in profile_server_names:
+            if name in self.servers:
+                server = self.servers[name]
+                if server.enabled:
+                    active_servers.append(server)
+
+        return active_servers
+
+    def save(self, path: str | Path) -> None:
+        """Save configuration to a JSON file.
+
+        Args:
+            path: Path to save the configuration file.
+        """
+        path = Path(path)
+
+        # Convert to dictionary format
+        data = {
+            "version": self.version,
+            "servers": {
+                name: {
+                    k: v
+                    for k, v in {
+                        "command": server.command,
+                        "args": server.args,
+                        "env": server.env,
+                        "enabled": server.enabled,
+                        "transport": server.transport,
+                        "url": server.url,
+                        "headers": server.headers,
+                        "timeout": server.timeout,
+                        "connect_timeout": server.connect_timeout,
+                    }.items()
+                    if v is not None
+                }
+                for name, server in self.servers.items()
+            },
+            "profiles": self.profiles,
+            "active_profile": self.active_profile,
+            "gateway": {
+                "default_timeout": self.gateway.default_timeout,
+                "max_concurrent_connections": self.gateway.max_concurrent_connections,
+            },
+        }
+
+        # Validate before saving
+        self.validate(data)
+
+        # Write to file
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+    @staticmethod
+    def validate(data: dict[str, Any]) -> None:
+        """Validate configuration data against the JSON schema.
+
+        Args:
+            data: Configuration data dictionary.
+
+        Raises:
+            ValueError: If configuration is invalid.
+        """
+        schema_path = Path(__file__).parent / "schemas" / "mcp_config_schema.json"
+        with open(schema_path, encoding="utf-8") as f:
+            schema = json.load(f)
+
+        try:
+            jsonschema.validate(instance=data, schema=schema)
+        except jsonschema.ValidationError as e:
+            raise ValueError(f"Invalid MCP configuration: {e.message}") from e

nexus_dev/schemas/mcp_config_schema.json

@@ -0,0 +1,166 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Nexus-Dev MCP Configuration",
+    "type": "object",
+    "properties": {
+        "version": {
+            "type": "string",
+            "description": "Schema version",
+            "const": "1.0"
+        },
+        "servers": {
+            "type": "object",
+            "description": "MCP server configurations",
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "enabled": {
+                        "type": "boolean",
+                        "default": true
+                    },
+                    "transport": {
+                        "type": "string",
+                        "enum": [
+                            "stdio",
+                            "sse",
+                            "http"
+                        ],
+                        "default": "stdio",
+                        "description": "Transport type: stdio (local process) or sse (HTTP remote)"
+                    },
+                    "command": {
+                        "type": "string",
+                        "description": "Command to start the MCP server (required for stdio)"
+                    },
+                    "args": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        },
+                        "default": []
+                    },
+                    "env": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string"
+                        },
+                        "default": {}
+                    },
+                    "url": {
+                        "type": "string",
+                        "format": "uri",
+                        "description": "Server URL (required for sse)"
+                    },
+                    "headers": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string"
+                        },
+                        "default": {},
+                        "description": "HTTP headers for SSE connection"
+                    },
+                    "timeout": {
+                        "type": "number",
+                        "description": "Tool execution timeout in seconds",
+                        "default": 30,
+                        "minimum": 1
+                    },
+                    "connect_timeout": {
+                        "type": "number",
+                        "description": "Connection timeout in seconds",
+                        "default": 10,
+                        "minimum": 1
+                    }
+                },
+                "allOf": [
+                    {
+                        "if": {
+                            "properties": {
+                                "transport": {
+                                    "const": "stdio"
+                                }
+                            }
+                        },
+                        "then": {
+                            "required": [
+                                "command"
+                            ]
+                        }
+                    },
+                    {
+                        "if": {
+                            "properties": {
+                                "transport": {
+                                    "const": "sse"
+                                }
+                            },
+                            "required": [
+                                "transport"
+                            ]
+                        },
+                        "then": {
+                            "required": [
+                                "url"
+                            ]
+                        }
+                    },
+                    {
+                        "if": {
+                            "properties": {
+                                "transport": {
+                                    "const": "http"
+                                }
+                            },
+                            "required": [
+                                "transport"
+                            ]
+                        },
+                        "then": {
+                            "required": [
+                                "url"
+                            ]
+                        }
+                    }
+                ]
+            }
+        },
+        "profiles": {
+            "type": "object",
+            "description": "Named profiles mapping to server lists",
+            "additionalProperties": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
+            },
+            "default": {}
+        },
+        "gateway": {
+            "type": "object",
+            "description": "Global gateway settings",
+            "properties": {
+                "default_timeout": {
+                    "type": "number",
+                    "description": "Default tool execution timeout",
+                    "default": 30,
+                    "minimum": 1
+                },
+                "max_concurrent_connections": {
+                    "type": "integer",
+                    "description": "Maximum concurrent connections to backend servers",
+                    "default": 5,
+                    "minimum": 1
+                }
+            }
+        },
+        "active_profile": {
+            "type": "string",
+            "description": "The currently active profile",
+            "default": "default"
+        }
+    },
+    "required": [
+        "version",
+        "servers"
+    ]
+}