superqode 0.1.5__py3-none-any.whl

superqode/mcp/config.py

@@ -0,0 +1,319 @@
+"""MCP server configuration for SuperQode.
+
+This module handles loading, saving, and managing MCP server configurations.
+Supports stdio (local process), HTTP, and SSE transport types.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+import json
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+# Default MCP config file locations
+MCP_CONFIG_FILENAME = "mcp.json"
+MCP_CONFIG_DIRS = [
+    Path.cwd() / ".superqode",
+    Path.home() / ".superqode",
+    Path.home() / ".config" / "superqode",
+]
+
+
+@dataclass
+class MCPStdioConfig:
+    """Configuration for stdio-based MCP server (local process).
+
+    Attributes:
+        command: The executable command to run
+        args: Command line arguments
+        env: Environment variables to set
+        cwd: Working directory for the process
+        timeout: Connection timeout in seconds
+    """
+
+    transport: Literal["stdio"] = "stdio"
+    command: str = ""
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    cwd: str | None = None
+    timeout: float = 30.0
+
+
+@dataclass
+class MCPHttpConfig:
+    """Configuration for HTTP-based MCP server (streamable HTTP).
+
+    Attributes:
+        url: The HTTP endpoint URL
+        headers: HTTP headers to include in requests
+        timeout: Request timeout in seconds
+        sse_read_timeout: SSE read timeout in seconds
+    """
+
+    transport: Literal["http"] = "http"
+    url: str = ""
+    headers: dict[str, str] = field(default_factory=dict)
+    timeout: float = 30.0
+    sse_read_timeout: float = 300.0
+
+
+@dataclass
+class MCPSSEConfig:
+    """Configuration for SSE-based MCP server.
+
+    Attributes:
+        url: The SSE endpoint URL
+        headers: HTTP headers to include in requests
+        timeout: Request timeout in seconds
+        sse_read_timeout: SSE read timeout in seconds
+    """
+
+    transport: Literal["sse"] = "sse"
+    url: str = ""
+    headers: dict[str, str] = field(default_factory=dict)
+    timeout: float = 5.0
+    sse_read_timeout: float = 300.0
+
+
+@dataclass
+class MCPServerConfig:
+    """Complete configuration for an MCP server.
+
+    Attributes:
+        id: Unique identifier for this server
+        name: Human-readable name
+        description: Optional description
+        enabled: Whether the server is enabled
+        auto_connect: Whether to connect automatically on startup
+        config: Transport-specific configuration
+    """
+
+    id: str
+    name: str
+    description: str = ""
+    enabled: bool = True
+    auto_connect: bool = True
+    config: MCPStdioConfig | MCPHttpConfig | MCPSSEConfig = field(default_factory=MCPStdioConfig)
+
+
+def find_mcp_config_file() -> Path | None:
+    """Find the MCP configuration file.
+
+    Searches in order:
+    1. .superqode/mcp.json in current directory
+    2. ~/.superqode/mcp.json
+    3. ~/.config/superqode/mcp.json
+
+    Returns:
+        Path to config file if found, None otherwise
+    """
+    for config_dir in MCP_CONFIG_DIRS:
+        config_path = config_dir / MCP_CONFIG_FILENAME
+        if config_path.exists():
+            return config_path
+    return None
+
+
+def load_mcp_config(config_path: Path | None = None) -> dict[str, MCPServerConfig]:
+    """Load MCP server configurations from file.
+
+    Args:
+        config_path: Optional explicit path to config file
+
+    Returns:
+        Dictionary mapping server IDs to their configurations
+    """
+    if config_path is None:
+        config_path = find_mcp_config_file()
+
+    if config_path is None or not config_path.exists():
+        return {}
+
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        logger.error(f"Failed to load MCP config from {config_path}: {e}")
+        return {}
+
+    servers: dict[str, MCPServerConfig] = {}
+
+    # Handle both formats: {"mcpServers": {...}} and {"servers": {...}}
+    servers_data = data.get("mcpServers", data.get("servers", {}))
+
+    for server_id, server_data in servers_data.items():
+        try:
+            server_config = _parse_server_config(server_id, server_data)
+            servers[server_id] = server_config
+        except Exception as e:
+            logger.warning(f"Failed to parse MCP server config '{server_id}': {e}")
+
+    return servers
+
+
+def _parse_server_config(server_id: str, data: dict[str, Any]) -> MCPServerConfig:
+    """Parse a single server configuration from JSON data."""
+    # Determine transport type
+    transport = data.get("transport", "stdio")
+
+    # Handle legacy format (command at top level = stdio)
+    if "command" in data and "transport" not in data:
+        transport = "stdio"
+    elif "url" in data and "transport" not in data:
+        # Determine if HTTP or SSE based on URL or other hints
+        transport = data.get("transport", "http")
+
+    # Parse transport-specific config
+    if transport == "stdio":
+        config = MCPStdioConfig(
+            command=data.get("command", ""),
+            args=data.get("args", []),
+            env=_resolve_env_vars(data.get("env", {})),
+            cwd=data.get("cwd"),
+            timeout=data.get("timeout", 30.0),
+        )
+    elif transport == "sse":
+        config = MCPSSEConfig(
+            url=data.get("url", ""),
+            headers=data.get("headers", {}),
+            timeout=data.get("timeout", 5.0),
+            sse_read_timeout=data.get("sse_read_timeout", 300.0),
+        )
+    else:  # http (streamable)
+        config = MCPHttpConfig(
+            url=data.get("url", ""),
+            headers=data.get("headers", {}),
+            timeout=data.get("timeout", 30.0),
+            sse_read_timeout=data.get("sse_read_timeout", 300.0),
+        )
+
+    return MCPServerConfig(
+        id=server_id,
+        name=data.get("name", server_id),
+        description=data.get("description", ""),
+        enabled=data.get("enabled", not data.get("disabled", False)),
+        auto_connect=data.get("autoConnect", data.get("auto_connect", True)),
+        config=config,
+    )
+
+
+def _resolve_env_vars(env: dict[str, str]) -> dict[str, str]:
+    """Resolve environment variable references in env dict.
+
+    Supports ${VAR} syntax for referencing environment variables.
+    """
+    resolved = {}
+    for key, value in env.items():
+        if isinstance(value, str) and value.startswith("${") and value.endswith("}"):
+            var_name = value[2:-1]
+            resolved[key] = os.environ.get(var_name, "")
+        else:
+            resolved[key] = value
+    return resolved
+
+
+def save_mcp_config(
+    servers: dict[str, MCPServerConfig],
+    config_path: Path | None = None,
+) -> None:
+    """Save MCP server configurations to file.
+
+    Args:
+        servers: Dictionary mapping server IDs to configurations
+        config_path: Optional explicit path to config file
+    """
+    if config_path is None:
+        # Default to .superqode/mcp.json in current directory
+        config_path = MCP_CONFIG_DIRS[0] / MCP_CONFIG_FILENAME
+
+    # Ensure directory exists
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Convert to JSON-serializable format
+    data = {"mcpServers": {}}
+
+    for server_id, server_config in servers.items():
+        server_data: dict[str, Any] = {
+            "name": server_config.name,
+            "enabled": server_config.enabled,
+            "autoConnect": server_config.auto_connect,
+        }
+
+        if server_config.description:
+            server_data["description"] = server_config.description
+
+        config = server_config.config
+        if isinstance(config, MCPStdioConfig):
+            server_data["transport"] = "stdio"
+            server_data["command"] = config.command
+            if config.args:
+                server_data["args"] = config.args
+            if config.env:
+                server_data["env"] = config.env
+            if config.cwd:
+                server_data["cwd"] = config.cwd
+            if config.timeout != 30.0:
+                server_data["timeout"] = config.timeout
+        elif isinstance(config, MCPSSEConfig):
+            server_data["transport"] = "sse"
+            server_data["url"] = config.url
+            if config.headers:
+                server_data["headers"] = config.headers
+            if config.timeout != 5.0:
+                server_data["timeout"] = config.timeout
+            if config.sse_read_timeout != 300.0:
+                server_data["sse_read_timeout"] = config.sse_read_timeout
+        else:  # MCPHttpConfig
+            server_data["transport"] = "http"
+            server_data["url"] = config.url
+            if config.headers:
+                server_data["headers"] = config.headers
+            if config.timeout != 30.0:
+                server_data["timeout"] = config.timeout
+            if config.sse_read_timeout != 300.0:
+                server_data["sse_read_timeout"] = config.sse_read_timeout
+
+        data["mcpServers"][server_id] = server_data
+
+    try:
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        logger.info(f"Saved MCP config to {config_path}")
+    except OSError as e:
+        logger.error(f"Failed to save MCP config to {config_path}: {e}")
+        raise
+
+
+def create_default_mcp_config() -> dict[str, MCPServerConfig]:
+    """Create a default MCP configuration with example servers.
+
+    Returns:
+        Dictionary with example MCP server configurations
+    """
+    return {
+        "filesystem": MCPServerConfig(
+            id="filesystem",
+            name="Filesystem",
+            description="Access to local filesystem",
+            enabled=False,  # Disabled by default for security
+            auto_connect=False,
+            config=MCPStdioConfig(
+                command="uvx",
+                args=["mcp-server-filesystem", "--root", "."],
+            ),
+        ),
+        "fetch": MCPServerConfig(
+            id="fetch",
+            name="Fetch",
+            description="HTTP fetch capabilities",
+            enabled=False,
+            auto_connect=False,
+            config=MCPStdioConfig(
+                command="uvx",
+                args=["mcp-server-fetch"],
+            ),
+        ),
+    }

superqode/mcp/integration.py

@@ -0,0 +1,337 @@
+"""MCP integration utilities for SuperQode.
+
+This module provides high-level integration functions for using MCP
+within SuperQode' agent system.
+"""
+
+import asyncio
+import logging
+from typing import Any
+
+from superqode.mcp.client import MCPClientManager, MCPConnectionState
+from superqode.mcp.config import (
+    MCPServerConfig,
+    MCPStdioConfig,
+    MCPHttpConfig,
+    MCPSSEConfig,
+    load_mcp_config,
+    save_mcp_config,
+    create_default_mcp_config,
+)
+from superqode.mcp.types import (
+    MCPTool,
+    MCPToolResult,
+    MCPResource,
+    MCPPrompt,
+    ServerCapability,
+    LoggingLevel,
+)
+
+logger = logging.getLogger(__name__)
+
+# Global MCP client manager instance
+_mcp_manager: MCPClientManager | None = None
+
+
+async def get_mcp_manager() -> MCPClientManager:
+    """Get or create the global MCP client manager."""
+    global _mcp_manager
+    if _mcp_manager is None:
+        _mcp_manager = MCPClientManager()
+        await _mcp_manager.__aenter__()
+        _mcp_manager.load_config()
+    return _mcp_manager
+
+
+async def shutdown_mcp_manager() -> None:
+    """Shutdown the global MCP client manager."""
+    global _mcp_manager
+    if _mcp_manager is not None:
+        await _mcp_manager.__aexit__(None, None, None)
+        _mcp_manager = None
+
+
+async def initialize_mcp(auto_connect: bool = True) -> dict[str, bool]:
+    """Initialize MCP support and optionally connect to servers."""
+    manager = await get_mcp_manager()
+    if auto_connect:
+        return await manager.connect_all()
+    return {}
+
+
+def get_mcp_tools_for_agent() -> list[dict[str, Any]]:
+    """Get MCP tools formatted for agent tool use.
+
+    Returns tools in a format suitable for LLM function calling.
+    """
+    if _mcp_manager is None:
+        return []
+
+    tools = _mcp_manager.list_all_tools()
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": f"mcp_{tool.server_id}_{tool.name}",
+                "description": f"[MCP:{tool.server_id}] {tool.description}",
+                "parameters": tool.input_schema,
+            },
+        }
+        for tool in tools
+    ]
+
+
+async def execute_mcp_tool(
+    tool_name: str,
+    arguments: dict[str, Any],
+) -> MCPToolResult:
+    """Execute an MCP tool by name.
+
+    Handles the mcp_{server_id}_{tool_name} format used by agents.
+    """
+    if _mcp_manager is None:
+        return MCPToolResult(
+            content=[],
+            is_error=True,
+            error_message="MCP not initialized",
+        )
+
+    # Parse tool name: mcp_{server_id}_{tool_name}
+    if tool_name.startswith("mcp_"):
+        parts = tool_name[4:].split("_", 1)
+        if len(parts) == 2:
+            server_id, actual_tool_name = parts
+            return await _mcp_manager.call_tool(server_id, actual_tool_name, arguments)
+
+    # Try to find tool across all servers
+    result = _mcp_manager.find_tool(tool_name)
+    if result:
+        server_id, tool = result
+        return await _mcp_manager.call_tool(server_id, tool.name, arguments)
+
+    return MCPToolResult(
+        content=[],
+        is_error=True,
+        error_message=f"Tool not found: {tool_name}",
+    )
+
+
+def format_tool_result_for_agent(result: MCPToolResult) -> str:
+    """Format an MCP tool result for agent consumption."""
+    if result.is_error:
+        return f"Error: {result.error_message}"
+
+    output_parts = []
+    for item in result.content:
+        if item.get("type") == "text":
+            output_parts.append(item.get("text", ""))
+        elif item.get("type") == "image":
+            output_parts.append(f"[Image: {item.get('mimeType', 'image')}]")
+        elif item.get("type") == "audio":
+            output_parts.append(f"[Audio: {item.get('mimeType', 'audio')}]")
+        elif item.get("type") == "resource":
+            output_parts.append(f"[Resource: {item.get('uri', 'unknown')}]")
+        else:
+            output_parts.append(str(item))
+
+    return "\n".join(output_parts)
+
+
+class MCPToolHandler:
+    """Handler for MCP tools within SuperQode' agent system."""
+
+    def __init__(self, manager: MCPClientManager | None = None):
+        self._manager = manager
+
+    @property
+    def manager(self) -> MCPClientManager | None:
+        return self._manager or _mcp_manager
+
+    def is_mcp_tool(self, tool_name: str) -> bool:
+        """Check if a tool name refers to an MCP tool."""
+        if tool_name.startswith("mcp_"):
+            return True
+        if self.manager:
+            return self.manager.find_tool(tool_name) is not None
+        return False
+
+    async def execute(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Execute an MCP tool."""
+        result = await execute_mcp_tool(tool_name, arguments)
+        return {
+            "success": not result.is_error,
+            "content": result.content,
+            "error": result.error_message,
+            "formatted": format_tool_result_for_agent(result),
+        }
+
+    def get_tool_definitions(self) -> list[dict[str, Any]]:
+        """Get tool definitions for agent use."""
+        return get_mcp_tools_for_agent()
+
+
+# Convenience functions for common operations
+
+
+async def add_mcp_server(
+    server_id: str,
+    name: str,
+    command: str | None = None,
+    args: list[str] | None = None,
+    url: str | None = None,
+    transport: str = "stdio",
+    enabled: bool = True,
+    auto_connect: bool = True,
+    **kwargs: Any,
+) -> MCPServerConfig:
+    """Add a new MCP server configuration."""
+    if transport == "stdio":
+        config = MCPStdioConfig(
+            command=command or "",
+            args=args or [],
+            env=kwargs.get("env", {}),
+            cwd=kwargs.get("cwd"),
+            timeout=kwargs.get("timeout", 30.0),
+        )
+    elif transport == "sse":
+        config = MCPSSEConfig(
+            url=url or "",
+            headers=kwargs.get("headers", {}),
+            timeout=kwargs.get("timeout", 5.0),
+            sse_read_timeout=kwargs.get("sse_read_timeout", 300.0),
+        )
+    else:  # http
+        config = MCPHttpConfig(
+            url=url or "",
+            headers=kwargs.get("headers", {}),
+            timeout=kwargs.get("timeout", 30.0),
+            sse_read_timeout=kwargs.get("sse_read_timeout", 300.0),
+        )
+
+    server_config = MCPServerConfig(
+        id=server_id,
+        name=name,
+        description=kwargs.get("description", ""),
+        enabled=enabled,
+        auto_connect=auto_connect,
+        config=config,
+    )
+
+    manager = await get_mcp_manager()
+    manager.add_server(server_config)
+
+    return server_config
+
+
+async def connect_mcp_server(server_id: str) -> bool:
+    """Connect to a specific MCP server."""
+    manager = await get_mcp_manager()
+    return await manager.connect(server_id)
+
+
+async def disconnect_mcp_server(server_id: str) -> None:
+    """Disconnect from a specific MCP server."""
+    manager = await get_mcp_manager()
+    await manager.disconnect(server_id)
+
+
+async def restart_mcp_server(server_id: str) -> bool:
+    """Restart a specific MCP server."""
+    manager = await get_mcp_manager()
+    return await manager.restart_server(server_id)
+
+
+def get_mcp_status() -> dict[str, Any]:
+    """Get current MCP status summary."""
+    if _mcp_manager is None:
+        return {
+            "initialized": False,
+            "total_servers": 0,
+            "connected": 0,
+            "total_tools": 0,
+        }
+
+    return {
+        "initialized": True,
+        **_mcp_manager.get_status_summary(),
+    }
+
+
+def has_mcp_capability(server_id: str, capability: ServerCapability) -> bool:
+    """Check if a server has a specific capability."""
+    if _mcp_manager is None:
+        return False
+    return _mcp_manager.has_capability(server_id, capability)
+
+
+async def set_mcp_logging_level(server_id: str, level: LoggingLevel) -> bool:
+    """Set logging level for an MCP server."""
+    if _mcp_manager is None:
+        return False
+    return await _mcp_manager.set_logging_level(server_id, level)
+
+
+async def read_mcp_resource(server_id: str, uri: str) -> dict[str, Any] | None:
+    """Read a resource from an MCP server."""
+    if _mcp_manager is None:
+        return None
+
+    content = await _mcp_manager.read_resource(server_id, uri)
+    if content is None:
+        return None
+
+    return {
+        "uri": content.uri,
+        "mime_type": content.mime_type,
+        "text": content.text,
+        "blob": content.blob,
+    }
+
+
+async def get_mcp_prompt(
+    server_id: str,
+    prompt_name: str,
+    arguments: dict[str, str] | None = None,
+) -> dict[str, Any] | None:
+    """Get a prompt from an MCP server."""
+    if _mcp_manager is None:
+        return None
+
+    result = await _mcp_manager.get_prompt(server_id, prompt_name, arguments)
+    if result is None:
+        return None
+
+    return {
+        "description": result.description,
+        "messages": [{"role": msg.role, "content": msg.content} for msg in result.messages],
+    }
+
+
+def list_mcp_servers() -> list[dict[str, Any]]:
+    """List all configured MCP servers with their status."""
+    if _mcp_manager is None:
+        return []
+
+    servers = []
+    for server_id, config in _mcp_manager.get_server_configs().items():
+        conn = _mcp_manager.get_connection(server_id)
+        servers.append(
+            {
+                "id": server_id,
+                "name": config.name,
+                "description": config.description,
+                "enabled": config.enabled,
+                "auto_connect": config.auto_connect,
+                "transport": type(config.config)
+                .__name__.replace("MCP", "")
+                .replace("Config", "")
+                .lower(),
+                "state": conn.state.value if conn else "disconnected",
+                "error": conn.error_message if conn else None,
+            }
+        )
+    return servers