hatch-xclam 0.7.1.dev3__py3-none-any.whl → 0.8.0.dev1__py3-none-any.whl

hatch/mcp_host_config/__init__.py

@@ -3,17 +3,17 @@
 This module provides MCP host configuration management functionality,
 including backup and restore capabilities for MCP server configurations,
 decorator-based strategy registration, and consolidated Pydantic models.
+
+Architecture Notes (v2.0 - Unified Adapter Architecture):
+- MCPServerConfig is the single unified model for all MCP configurations
+- Host-specific serialization is handled by adapters in hatch/mcp_host_config/adapters/
+- Legacy host-specific models (MCPServerConfigGemini, etc.) have been removed
 """
 
 from .backup import MCPHostConfigBackupManager
 from .models import (
     MCPHostType, MCPServerConfig, HostConfiguration, EnvironmentData,
     PackageHostConfiguration, EnvironmentPackageEntry, ConfigurationResult, SyncResult,
-    # Host-specific configuration models
-    MCPServerConfigBase, MCPServerConfigGemini, MCPServerConfigVSCode,
-    MCPServerConfigCursor, MCPServerConfigClaude, MCPServerConfigKiro,
-    MCPServerConfigCodex, MCPServerConfigOmni,
-    HOST_MODEL_REGISTRY
 )
 from .host_management import (
     MCPHostRegistry, MCPHostStrategy, MCPHostConfigurationManager, register_host_strategy
@@ -21,20 +21,20 @@ from .host_management import (
 from .reporting import (
     FieldOperation, ConversionReport, generate_conversion_report, display_report
 )
+from .adapters import AdapterRegistry, get_adapter, get_default_registry
 
 # Import strategies to trigger decorator registration
 from . import strategies
 
 __all__ = [
     'MCPHostConfigBackupManager',
+    # Core models
     'MCPHostType', 'MCPServerConfig', 'HostConfiguration', 'EnvironmentData',
     'PackageHostConfiguration', 'EnvironmentPackageEntry', 'ConfigurationResult', 'SyncResult',
-    # Host-specific configuration models
-    'MCPServerConfigBase', 'MCPServerConfigGemini', 'MCPServerConfigVSCode',
-    'MCPServerConfigCursor', 'MCPServerConfigClaude', 'MCPServerConfigKiro',
-    'MCPServerConfigCodex', 'MCPServerConfigOmni',
-    'HOST_MODEL_REGISTRY',
+    # Adapter architecture
+    'AdapterRegistry', 'get_adapter', 'get_default_registry',
     # User feedback reporting
     'FieldOperation', 'ConversionReport', 'generate_conversion_report', 'display_report',
+    # Host management
     'MCPHostRegistry', 'MCPHostStrategy', 'MCPHostConfigurationManager', 'register_host_strategy'
 ]

hatch/mcp_host_config/adapters/__init__.py

@@ -0,0 +1,34 @@
+"""MCP Host Config Adapters.
+
+This module provides host-specific adapters for the Unified Adapter Architecture.
+Each adapter handles validation and serialization for a specific MCP host.
+"""
+
+from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter
+from hatch.mcp_host_config.adapters.claude import ClaudeAdapter
+from hatch.mcp_host_config.adapters.codex import CodexAdapter
+from hatch.mcp_host_config.adapters.cursor import CursorAdapter
+from hatch.mcp_host_config.adapters.gemini import GeminiAdapter
+from hatch.mcp_host_config.adapters.kiro import KiroAdapter
+from hatch.mcp_host_config.adapters.lmstudio import LMStudioAdapter
+from hatch.mcp_host_config.adapters.registry import AdapterRegistry, get_adapter, get_default_registry
+from hatch.mcp_host_config.adapters.vscode import VSCodeAdapter
+
+__all__ = [
+    # Base classes and exceptions
+    "AdapterValidationError",
+    "BaseAdapter",
+    # Registry
+    "AdapterRegistry",
+    "get_adapter",
+    "get_default_registry",
+    # Host-specific adapters
+    "ClaudeAdapter",
+    "CodexAdapter",
+    "CursorAdapter",
+    "GeminiAdapter",
+    "KiroAdapter",
+    "LMStudioAdapter",
+    "VSCodeAdapter",
+]
+

hatch/mcp_host_config/adapters/base.py

@@ -0,0 +1,170 @@
+"""Base adapter class for MCP host configurations.
+
+This module defines the abstract BaseAdapter class that all host-specific
+adapters must implement. The adapter pattern allows for:
+- Host-specific validation rules
+- Host-specific serialization format
+- Unified interface across all hosts
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, FrozenSet, List, Optional
+
+from hatch.mcp_host_config.models import MCPServerConfig
+from hatch.mcp_host_config.fields import EXCLUDED_ALWAYS
+
+
+class AdapterValidationError(Exception):
+    """Raised when adapter validation fails.
+    
+    Attributes:
+        message: Human-readable error message
+        field: The field that caused the error (if applicable)
+        host_name: The host adapter that raised the error
+    """
+    
+    def __init__(
+        self, 
+        message: str, 
+        field: Optional[str] = None, 
+        host_name: Optional[str] = None
+    ):
+        self.message = message
+        self.field = field
+        self.host_name = host_name
+        super().__init__(self._format_message())
+    
+    def _format_message(self) -> str:
+        """Format the error message with optional context."""
+        parts = []
+        if self.host_name:
+            parts.append(f"[{self.host_name}]")
+        if self.field:
+            parts.append(f"Field '{self.field}':")
+        parts.append(self.message)
+        return " ".join(parts)
+
+
+class BaseAdapter(ABC):
+    """Abstract base class for host-specific MCP configuration adapters.
+    
+    Each host (Claude Desktop, VSCode, Gemini, etc.) has different requirements
+    for MCP server configuration. Adapters handle:
+    
+    1. **Validation**: Host-specific rules (e.g., "command and url are mutually
+       exclusive" for Claude, but not for Gemini which supports triple transport)
+       
+    2. **Serialization**: Converting MCPServerConfig to the host's expected format
+       (field names, structure, excluded fields)
+       
+    3. **Field Support**: Declaring which fields the host supports
+    
+    Subclasses must implement:
+        - host_name: The identifier for this host
+        - get_supported_fields(): Fields this host accepts
+        - validate(): Host-specific validation logic
+        - serialize(): Convert config to host format
+    
+    Example:
+        >>> class ClaudeAdapter(BaseAdapter):
+        ...     @property
+        ...     def host_name(self) -> str:
+        ...         return "claude-desktop"
+        ...     
+        ...     def get_supported_fields(self) -> FrozenSet[str]:
+        ...         return frozenset({"command", "args", "env", "url", "headers", "type"})
+        ...     
+        ...     def validate(self, config: MCPServerConfig) -> None:
+        ...         if config.command and config.url:
+        ...             raise AdapterValidationError("Cannot have both command and url")
+        ...     
+        ...     def serialize(self, config: MCPServerConfig) -> Dict[str, Any]:
+        ...         return {k: v for k, v in config.model_dump().items() if v is not None}
+    """
+    
+    @property
+    @abstractmethod
+    def host_name(self) -> str:
+        """Return the identifier for this host.
+        
+        Returns:
+            Host identifier string (e.g., "claude-desktop", "vscode", "gemini")
+        """
+        ...
+    
+    @abstractmethod
+    def get_supported_fields(self) -> FrozenSet[str]:
+        """Return the set of fields supported by this host.
+        
+        Returns:
+            FrozenSet of field names that this host accepts.
+            Fields not in this set will be filtered during serialization.
+        """
+        ...
+    
+    @abstractmethod
+    def validate(self, config: MCPServerConfig) -> None:
+        """Validate the configuration for this host.
+        
+        This method should check host-specific rules and raise
+        AdapterValidationError if the configuration is invalid.
+        
+        Args:
+            config: The MCPServerConfig to validate
+            
+        Raises:
+            AdapterValidationError: If validation fails
+        """
+        ...
+    
+    @abstractmethod
+    def serialize(self, config: MCPServerConfig) -> Dict[str, Any]:
+        """Serialize the configuration for this host.
+        
+        This method should convert the MCPServerConfig to the format
+        expected by the host's configuration file.
+        
+        Args:
+            config: The MCPServerConfig to serialize
+            
+        Returns:
+            Dictionary in the host's expected format
+        """
+        ...
+    
+    def get_excluded_fields(self) -> FrozenSet[str]:
+        """Return fields that should always be excluded from serialization.
+        
+        By default, returns EXCLUDED_ALWAYS (e.g., 'name' which is Hatch metadata).
+        Subclasses can override to add host-specific exclusions.
+        
+        Returns:
+            FrozenSet of field names to exclude
+        """
+        return EXCLUDED_ALWAYS
+    
+    def filter_fields(self, config: MCPServerConfig) -> Dict[str, Any]:
+        """Filter config to only include supported, non-excluded, non-None fields.
+        
+        This is a helper method for serialization that:
+        1. Gets all fields from the config
+        2. Filters to only supported fields
+        3. Removes excluded fields
+        4. Removes None values
+        
+        Args:
+            config: The MCPServerConfig to filter
+            
+        Returns:
+            Dictionary with only valid fields for this host
+        """
+        supported = self.get_supported_fields()
+        excluded = self.get_excluded_fields()
+        
+        result = {}
+        for field, value in config.model_dump(exclude_none=True).items():
+            if field in supported and field not in excluded:
+                result[field] = value
+        
+        return result
+

hatch/mcp_host_config/adapters/claude.py

@@ -0,0 +1,105 @@
+"""Claude Desktop/Code adapter for MCP host configuration.
+
+Claude Desktop and Claude Code share the same configuration format:
+- Supports 'type' field for transport discrimination
+- Mutually exclusive: command XOR url (never both)
+- Standard field set: command, args, env, url, headers, type
+"""
+
+from typing import Any, Dict, FrozenSet
+
+from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter
+from hatch.mcp_host_config.fields import CLAUDE_FIELDS
+from hatch.mcp_host_config.models import MCPServerConfig
+
+
+class ClaudeAdapter(BaseAdapter):
+    """Adapter for Claude Desktop and Claude Code hosts.
+    
+    Claude uses a strict validation model:
+    - Local servers: command (required), args, env
+    - Remote servers: url (required), headers, env
+    - Never both command and url
+    
+    Supports the 'type' field for explicit transport discrimination.
+    """
+    
+    def __init__(self, variant: str = "desktop"):
+        """Initialize Claude adapter.
+        
+        Args:
+            variant: Either "desktop" or "code" to specify the Claude variant.
+        """
+        if variant not in ("desktop", "code"):
+            raise ValueError(f"Invalid Claude variant: {variant}. Must be 'desktop' or 'code'")
+        self._variant = variant
+    
+    @property
+    def host_name(self) -> str:
+        """Return the host identifier."""
+        return f"claude-{self._variant}"
+    
+    def get_supported_fields(self) -> FrozenSet[str]:
+        """Return fields supported by Claude."""
+        return CLAUDE_FIELDS
+    
+    def validate(self, config: MCPServerConfig) -> None:
+        """Validate configuration for Claude.
+        
+        Claude requires exactly one transport:
+        - stdio (command)
+        - sse (url)
+        
+        Having both command and url is invalid.
+        """
+        has_command = config.command is not None
+        has_url = config.url is not None
+        has_http_url = config.httpUrl is not None
+        
+        # Claude doesn't support httpUrl
+        if has_http_url:
+            raise AdapterValidationError(
+                "httpUrl is not supported (use 'url' for remote servers)",
+                field="httpUrl",
+                host_name=self.host_name
+            )
+        
+        # Must have exactly one transport
+        if not has_command and not has_url:
+            raise AdapterValidationError(
+                "Either 'command' (local) or 'url' (remote) must be specified",
+                host_name=self.host_name
+            )
+        
+        if has_command and has_url:
+            raise AdapterValidationError(
+                "Cannot specify both 'command' and 'url' - choose one transport",
+                host_name=self.host_name
+            )
+        
+        # Validate type consistency if specified
+        if config.type is not None:
+            if config.type == "stdio" and not has_command:
+                raise AdapterValidationError(
+                    "type='stdio' requires 'command' field",
+                    field="type",
+                    host_name=self.host_name
+                )
+            if config.type in ("sse", "http") and not has_url:
+                raise AdapterValidationError(
+                    f"type='{config.type}' requires 'url' field",
+                    field="type",
+                    host_name=self.host_name
+                )
+    
+    def serialize(self, config: MCPServerConfig) -> Dict[str, Any]:
+        """Serialize configuration for Claude format.
+        
+        Returns a dictionary suitable for Claude's config.json format.
+        """
+        # Validate before serializing
+        self.validate(config)
+        
+        # Filter to supported fields
+        return self.filter_fields(config)
+

hatch/mcp_host_config/adapters/codex.py

@@ -0,0 +1,104 @@
+"""Codex CLI adapter for MCP host configuration.
+
+Codex CLI has unique features:
+- No 'type' field support
+- Field name mappings: args→arguments, headers→http_headers
+- Rich configuration: timeouts, env_vars, tool management, bearer tokens
+"""
+
+from typing import Any, Dict, FrozenSet
+
+from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter
+from hatch.mcp_host_config.fields import CODEX_FIELDS, CODEX_FIELD_MAPPINGS
+from hatch.mcp_host_config.models import MCPServerConfig
+
+
+class CodexAdapter(BaseAdapter):
+    """Adapter for Codex CLI MCP host.
+    
+    Codex uses different field names than other hosts:
+    - 'args' → 'arguments'
+    - 'headers' → 'http_headers'
+    
+    Codex also has:
+    - Working directory support (cwd)
+    - Timeout configuration (startup_timeout_sec, tool_timeout_sec)
+    - Server enable/disable (enabled)
+    - Tool filtering (enabled_tools, disabled_tools)
+    - Bearer token support (bearer_token_env_var)
+    """
+    
+    @property
+    def host_name(self) -> str:
+        """Return the host identifier."""
+        return "codex"
+    
+    def get_supported_fields(self) -> FrozenSet[str]:
+        """Return fields supported by Codex."""
+        return CODEX_FIELDS
+    
+    def validate(self, config: MCPServerConfig) -> None:
+        """Validate configuration for Codex.
+        
+        Codex requires exactly one transport (command XOR url).
+        Does not support 'type' field.
+        """
+        has_command = config.command is not None
+        has_url = config.url is not None
+        has_http_url = config.httpUrl is not None
+        
+        # Codex doesn't support httpUrl
+        if has_http_url:
+            raise AdapterValidationError(
+                "httpUrl is not supported (use 'url' for remote servers)",
+                field="httpUrl",
+                host_name=self.host_name
+            )
+        
+        # Must have exactly one transport
+        if not has_command and not has_url:
+            raise AdapterValidationError(
+                "Either 'command' (local) or 'url' (remote) must be specified",
+                host_name=self.host_name
+            )
+        
+        if has_command and has_url:
+            raise AdapterValidationError(
+                "Cannot specify both 'command' and 'url' - choose one transport",
+                host_name=self.host_name
+            )
+        
+        # 'type' field is not supported by Codex
+        if config.type is not None:
+            raise AdapterValidationError(
+                "'type' field is not supported by Codex CLI",
+                field="type",
+                host_name=self.host_name
+            )
+        
+        # Validate enabled_tools and disabled_tools mutual exclusion
+        if config.enabled_tools is not None and config.disabled_tools is not None:
+            raise AdapterValidationError(
+                "Cannot specify both 'enabled_tools' and 'disabled_tools'",
+                host_name=self.host_name
+            )
+    
+    def serialize(self, config: MCPServerConfig) -> Dict[str, Any]:
+        """Serialize configuration for Codex format.
+        
+        Applies field mappings:
+        - args → arguments
+        - headers → http_headers
+        """
+        self.validate(config)
+        
+        # Get base filtered fields
+        result = self.filter_fields(config)
+        
+        # Apply field mappings
+        for universal_name, codex_name in CODEX_FIELD_MAPPINGS.items():
+            if universal_name in result:
+                result[codex_name] = result.pop(universal_name)
+        
+        return result
+

hatch/mcp_host_config/adapters/cursor.py

@@ -0,0 +1,83 @@
+"""Cursor adapter for MCP host configuration.
+
+Cursor is similar to VSCode but with limited additional fields:
+- envFile: Path to environment file (like VSCode)
+- No 'inputs' field support (VSCode only)
+"""
+
+from typing import Any, Dict, FrozenSet
+
+from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter
+from hatch.mcp_host_config.fields import CURSOR_FIELDS
+from hatch.mcp_host_config.models import MCPServerConfig
+
+
+class CursorAdapter(BaseAdapter):
+    """Adapter for Cursor MCP host.
+    
+    Cursor is like a simplified VSCode:
+    - Supports Claude base fields + envFile
+    - Does NOT support inputs (VSCode-only feature)
+    - Requires exactly one transport (command XOR url)
+    """
+    
+    @property
+    def host_name(self) -> str:
+        """Return the host identifier."""
+        return "cursor"
+    
+    def get_supported_fields(self) -> FrozenSet[str]:
+        """Return fields supported by Cursor."""
+        return CURSOR_FIELDS
+    
+    def validate(self, config: MCPServerConfig) -> None:
+        """Validate configuration for Cursor.
+        
+        Same rules as Claude: exactly one transport required.
+        Warns if 'inputs' is specified (not supported).
+        """
+        has_command = config.command is not None
+        has_url = config.url is not None
+        has_http_url = config.httpUrl is not None
+        
+        # Cursor doesn't support httpUrl
+        if has_http_url:
+            raise AdapterValidationError(
+                "httpUrl is not supported (use 'url' for remote servers)",
+                field="httpUrl",
+                host_name=self.host_name
+            )
+        
+        # Must have exactly one transport
+        if not has_command and not has_url:
+            raise AdapterValidationError(
+                "Either 'command' (local) or 'url' (remote) must be specified",
+                host_name=self.host_name
+            )
+        
+        if has_command and has_url:
+            raise AdapterValidationError(
+                "Cannot specify both 'command' and 'url' - choose one transport",
+                host_name=self.host_name
+            )
+        
+        # Validate type consistency if specified
+        if config.type is not None:
+            if config.type == "stdio" and not has_command:
+                raise AdapterValidationError(
+                    "type='stdio' requires 'command' field",
+                    field="type",
+                    host_name=self.host_name
+                )
+            if config.type in ("sse", "http") and not has_url:
+                raise AdapterValidationError(
+                    f"type='{config.type}' requires 'url' field",
+                    field="type",
+                    host_name=self.host_name
+                )
+    
+    def serialize(self, config: MCPServerConfig) -> Dict[str, Any]:
+        """Serialize configuration for Cursor format."""
+        self.validate(config)
+        return self.filter_fields(config)
+

hatch/mcp_host_config/adapters/gemini.py

@@ -0,0 +1,75 @@
+"""Gemini CLI adapter for MCP host configuration.
+
+Gemini has unique features:
+- Triple transport: command (stdio), url (SSE), httpUrl (HTTP streaming)
+- Multiple transports can coexist (not mutually exclusive)
+- No 'type' field support
+- Rich OAuth configuration
+- Working directory, timeout, trust settings
+"""
+
+from typing import Any, Dict, FrozenSet
+
+from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter
+from hatch.mcp_host_config.fields import GEMINI_FIELDS
+from hatch.mcp_host_config.models import MCPServerConfig
+
+
+class GeminiAdapter(BaseAdapter):
+    """Adapter for Gemini CLI MCP host.
+    
+    Gemini is unique among MCP hosts:
+    - Supports THREE transport types (stdio, SSE, HTTP streaming)
+    - Transports are NOT mutually exclusive (can have multiple)
+    - Does NOT support 'type' field
+    - Has rich configuration: OAuth, timeout, trust, tool filtering
+    """
+    
+    @property
+    def host_name(self) -> str:
+        """Return the host identifier."""
+        return "gemini"
+    
+    def get_supported_fields(self) -> FrozenSet[str]:
+        """Return fields supported by Gemini."""
+        return GEMINI_FIELDS
+    
+    def validate(self, config: MCPServerConfig) -> None:
+        """Validate configuration for Gemini.
+        
+        Gemini is flexible:
+        - At least one transport is required (command, url, or httpUrl)
+        - Multiple transports are allowed
+        - 'type' field is not supported
+        """
+        has_command = config.command is not None
+        has_url = config.url is not None
+        has_http_url = config.httpUrl is not None
+        
+        # Must have at least one transport
+        if not has_command and not has_url and not has_http_url:
+            raise AdapterValidationError(
+                "At least one transport must be specified: 'command', 'url', or 'httpUrl'",
+                host_name=self.host_name
+            )
+        
+        # 'type' field is not supported by Gemini
+        if config.type is not None:
+            raise AdapterValidationError(
+                "'type' field is not supported by Gemini CLI",
+                field="type",
+                host_name=self.host_name
+            )
+        
+        # Validate includeTools and excludeTools are mutually exclusive
+        if config.includeTools is not None and config.excludeTools is not None:
+            raise AdapterValidationError(
+                "Cannot specify both 'includeTools' and 'excludeTools'",
+                host_name=self.host_name
+            )
+    
+    def serialize(self, config: MCPServerConfig) -> Dict[str, Any]:
+        """Serialize configuration for Gemini format."""
+        self.validate(config)
+        return self.filter_fields(config)
+