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

hatch/mcp_host_config/adapters/kiro.py

@@ -0,0 +1,78 @@
+"""Kiro adapter for MCP host configuration.
+
+Kiro has specific features:
+- No 'type' field support
+- Server enable/disable via 'disabled' field
+- Tool management: autoApprove, disabledTools
+"""
+
+from typing import Any, Dict, FrozenSet
+
+from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter
+from hatch.mcp_host_config.fields import KIRO_FIELDS
+from hatch.mcp_host_config.models import MCPServerConfig
+
+
+class KiroAdapter(BaseAdapter):
+    """Adapter for Kiro MCP host.
+    
+    Kiro is similar to Claude but without the 'type' field:
+    - Requires exactly one transport (command XOR url)
+    - Has 'disabled' field for toggling server
+    - Has 'autoApprove' for auto-approved tools
+    - Has 'disabledTools' for disabled tools
+    """
+    
+    @property
+    def host_name(self) -> str:
+        """Return the host identifier."""
+        return "kiro"
+    
+    def get_supported_fields(self) -> FrozenSet[str]:
+        """Return fields supported by Kiro."""
+        return KIRO_FIELDS
+    
+    def validate(self, config: MCPServerConfig) -> None:
+        """Validate configuration for Kiro.
+        
+        Like Claude, requires exactly one transport.
+        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
+        
+        # Kiro 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 Kiro
+        if config.type is not None:
+            raise AdapterValidationError(
+                "'type' field is not supported by Kiro",
+                field="type",
+                host_name=self.host_name
+            )
+    
+    def serialize(self, config: MCPServerConfig) -> Dict[str, Any]:
+        """Serialize configuration for Kiro format."""
+        self.validate(config)
+        return self.filter_fields(config)
+

hatch/mcp_host_config/adapters/lmstudio.py

@@ -0,0 +1,79 @@
+"""LM Studio adapter for MCP host configuration.
+
+LM Studio follows the Cursor/Claude format with the same field set.
+"""
+
+from typing import Any, Dict, FrozenSet
+
+from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter
+from hatch.mcp_host_config.fields import LMSTUDIO_FIELDS
+from hatch.mcp_host_config.models import MCPServerConfig
+
+
+class LMStudioAdapter(BaseAdapter):
+    """Adapter for LM Studio MCP host.
+    
+    LM Studio uses the same configuration format as Claude/Cursor:
+    - Supports 'type' field for transport discrimination
+    - Requires exactly one transport (command XOR url)
+    """
+    
+    @property
+    def host_name(self) -> str:
+        """Return the host identifier."""
+        return "lmstudio"
+    
+    def get_supported_fields(self) -> FrozenSet[str]:
+        """Return fields supported by LM Studio."""
+        return LMSTUDIO_FIELDS
+    
+    def validate(self, config: MCPServerConfig) -> None:
+        """Validate configuration for LM Studio.
+        
+        Same rules as Claude: exactly one transport required.
+        """
+        has_command = config.command is not None
+        has_url = config.url is not None
+        has_http_url = config.httpUrl is not None
+        
+        # LM Studio 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 LM Studio format."""
+        self.validate(config)
+        return self.filter_fields(config)
+

hatch/mcp_host_config/adapters/registry.py

@@ -0,0 +1,149 @@
+"""Adapter registry for MCP host configurations.
+
+This module provides a centralized registry for host-specific adapters.
+The registry maps host names to adapter instances and provides factory methods.
+"""
+
+from typing import Dict, List, Optional, Type
+
+from hatch.mcp_host_config.adapters.base import 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.vscode import VSCodeAdapter
+
+
+class AdapterRegistry:
+    """Registry for MCP host configuration adapters.
+
+    The registry provides:
+    - Host name to adapter mapping
+    - Factory method to get adapters by host name
+    - Registration of custom adapters
+    - List of all supported hosts
+
+    Example:
+        >>> registry = AdapterRegistry()
+        >>> adapter = registry.get_adapter("claude-desktop")
+        >>> adapter.host_name
+        'claude-desktop'
+
+        >>> registry.get_supported_hosts()
+        ['claude-code', 'claude-desktop', 'codex', 'cursor', 'gemini', 'kiro', 'lmstudio', 'vscode']
+    """
+
+    def __init__(self):
+        """Initialize the registry with default adapters."""
+        self._adapters: Dict[str, BaseAdapter] = {}
+        self._register_defaults()
+
+    def _register_defaults(self) -> None:
+        """Register all built-in adapters."""
+        # Claude variants
+        self.register(ClaudeAdapter(variant="desktop"))
+        self.register(ClaudeAdapter(variant="code"))
+
+        # Other hosts
+        self.register(VSCodeAdapter())
+        self.register(CursorAdapter())
+        self.register(LMStudioAdapter())
+        self.register(GeminiAdapter())
+        self.register(KiroAdapter())
+        self.register(CodexAdapter())
+    
+    def register(self, adapter: BaseAdapter) -> None:
+        """Register an adapter instance.
+        
+        Args:
+            adapter: The adapter instance to register
+            
+        Raises:
+            ValueError: If an adapter with the same host name is already registered
+        """
+        host_name = adapter.host_name
+        if host_name in self._adapters:
+            raise ValueError(f"Adapter for '{host_name}' is already registered")
+        self._adapters[host_name] = adapter
+    
+    def get_adapter(self, host_name: str) -> BaseAdapter:
+        """Get an adapter by host name.
+        
+        Args:
+            host_name: The host identifier (e.g., "claude-desktop", "gemini")
+            
+        Returns:
+            The adapter instance for the specified host
+            
+        Raises:
+            KeyError: If no adapter is registered for the host name
+        """
+        if host_name not in self._adapters:
+            supported = ", ".join(sorted(self._adapters.keys()))
+            raise KeyError(f"No adapter registered for '{host_name}'. Supported hosts: {supported}")
+        return self._adapters[host_name]
+    
+    def has_adapter(self, host_name: str) -> bool:
+        """Check if an adapter is registered for a host name.
+        
+        Args:
+            host_name: The host identifier to check
+            
+        Returns:
+            True if an adapter is registered, False otherwise
+        """
+        return host_name in self._adapters
+    
+    def get_supported_hosts(self) -> List[str]:
+        """Get a sorted list of all supported host names.
+        
+        Returns:
+            Sorted list of host name strings
+        """
+        return sorted(self._adapters.keys())
+    
+    def unregister(self, host_name: str) -> None:
+        """Unregister an adapter by host name.
+        
+        Args:
+            host_name: The host identifier to unregister
+            
+        Raises:
+            KeyError: If no adapter is registered for the host name
+        """
+        if host_name not in self._adapters:
+            raise KeyError(f"No adapter registered for '{host_name}'")
+        del self._adapters[host_name]
+
+
+# Global registry instance for convenience
+_default_registry: Optional[AdapterRegistry] = None
+
+
+def get_default_registry() -> AdapterRegistry:
+    """Get the default global adapter registry.
+    
+    Returns:
+        The singleton AdapterRegistry instance
+    """
+    global _default_registry
+    if _default_registry is None:
+        _default_registry = AdapterRegistry()
+    return _default_registry
+
+
+def get_adapter(host_name: str) -> BaseAdapter:
+    """Get an adapter from the default registry.
+    
+    This is a convenience function that uses the global registry.
+    
+    Args:
+        host_name: The host identifier (e.g., "claude-desktop", "gemini")
+        
+    Returns:
+        The adapter instance for the specified host
+    """
+    return get_default_registry().get_adapter(host_name)
+

hatch/mcp_host_config/adapters/vscode.py

@@ -0,0 +1,83 @@
+"""VSCode adapter for MCP host configuration.
+
+VSCode extends Claude's format with:
+- envFile: Path to environment file
+- inputs: Input variable definitions (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 VSCODE_FIELDS
+from hatch.mcp_host_config.models import MCPServerConfig
+
+
+class VSCodeAdapter(BaseAdapter):
+    """Adapter for Visual Studio Code MCP host.
+    
+    VSCode supports the same base configuration as Claude, plus:
+    - envFile: Path to a .env file for environment variables
+    - inputs: Array of input variable definitions for prompts
+    
+    Like Claude, it requires exactly one transport (command XOR url).
+    """
+    
+    @property
+    def host_name(self) -> str:
+        """Return the host identifier."""
+        return "vscode"
+    
+    def get_supported_fields(self) -> FrozenSet[str]:
+        """Return fields supported by VSCode."""
+        return VSCODE_FIELDS
+    
+    def validate(self, config: MCPServerConfig) -> None:
+        """Validate configuration for VSCode.
+        
+        Same rules as Claude: exactly one transport required.
+        """
+        has_command = config.command is not None
+        has_url = config.url is not None
+        has_http_url = config.httpUrl is not None
+        
+        # VSCode 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 VSCode format."""
+        self.validate(config)
+        return self.filter_fields(config)
+

hatch/mcp_host_config/backup.py

@@ -355,10 +355,12 @@ class MCPHostConfigBackupManager:
         
         backups = []
 
-        # Search for both correct format and legacy incorrect format for backward compatibility
+        # Search for backups with flexible filename matching
+        # Different hosts use different config filenames (mcp.json, settings.json, config.toml)
+        # Backup format: {original_filename}.{hostname}.{timestamp}
         patterns = [
-            f"mcp.json.{hostname}.*",  # Correct format: mcp.json.gemini.*
-            f"mcp.json.MCPHostType.{hostname.upper()}.*"  # Legacy incorrect format: mcp.json.MCPHostType.GEMINI.*
+            f"*.{hostname}.*",  # Flexible: settings.json.gemini.*, mcp.json.claude-desktop.*, etc.
+            f"mcp.json.MCPHostType.{hostname.upper()}.*"  # Legacy incorrect format for backward compatibility
         ]
 
         for pattern in patterns:

hatch/mcp_host_config/fields.py

@@ -0,0 +1,126 @@
+"""
+Field constants for MCP host configuration adapter architecture.
+
+This module defines the source of truth for field support across MCP hosts.
+All adapters reference these constants to determine field filtering and mapping.
+"""
+
+from typing import FrozenSet
+from enum import Enum
+
+
+# ============================================================================
+# Universal Fields (supported by ALL hosts)
+# ============================================================================
+
+UNIVERSAL_FIELDS: FrozenSet[str] = frozenset({
+    "command",  # Executable path/name for local servers
+    "args",     # Command arguments for local servers
+    "env",      # Environment variables (all transports)
+    "url",      # Server endpoint URL for remote servers (SSE transport)
+    "headers",  # HTTP headers for remote servers
+})
+
+
+# ============================================================================
+# Type Field Support
+# ============================================================================
+
+# Hosts that support the 'type' discriminator field (stdio/sse/http)
+# Note: Gemini, Kiro, Codex do NOT support this field
+TYPE_SUPPORTING_HOSTS: FrozenSet[str] = frozenset({
+    "claude-desktop",
+    "claude-code",
+    "vscode",
+    "cursor",
+})
+
+
+# ============================================================================
+# Host-Specific Field Sets
+# ============================================================================
+
+# Fields supported by Claude Desktop/Code (universal + type)
+CLAUDE_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset({
+    "type",  # Transport discriminator
+})
+
+# Fields supported by VSCode (Claude fields + envFile + inputs)
+VSCODE_FIELDS: FrozenSet[str] = CLAUDE_FIELDS | frozenset({
+    "envFile",  # Path to environment file
+    "inputs",   # Input variable definitions (VSCode only)
+})
+
+# Fields supported by Cursor (Claude fields + envFile, no inputs)
+CURSOR_FIELDS: FrozenSet[str] = CLAUDE_FIELDS | frozenset({
+    "envFile",  # Path to environment file
+})
+
+# Fields supported by LMStudio (universal + type)
+LMSTUDIO_FIELDS: FrozenSet[str] = CLAUDE_FIELDS
+
+# Fields supported by Gemini (no type field, but has httpUrl and others)
+GEMINI_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset({
+    "httpUrl",       # HTTP streaming endpoint URL
+    "timeout",       # Request timeout in milliseconds
+    "trust",         # Bypass tool call confirmations
+    "cwd",           # Working directory for stdio transport
+    "includeTools",  # Tools to include (allowlist)
+    "excludeTools",  # Tools to exclude (blocklist)
+    # OAuth configuration
+    "oauth_enabled",
+    "oauth_clientId",
+    "oauth_clientSecret",
+    "oauth_authorizationUrl",
+    "oauth_tokenUrl",
+    "oauth_scopes",
+    "oauth_redirectUri",
+    "oauth_tokenParamName",
+    "oauth_audiences",
+    "authProviderType",
+})
+
+# Fields supported by Kiro (no type field)
+KIRO_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset({
+    "disabled",       # Whether server is disabled
+    "autoApprove",    # Auto-approved tool names
+    "disabledTools",  # Disabled tool names
+})
+
+# Fields supported by Codex (no type field, has field mappings)
+CODEX_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset({
+    "cwd",                 # Working directory
+    "env_vars",            # Environment variables to whitelist/forward
+    "startup_timeout_sec", # Server startup timeout
+    "tool_timeout_sec",    # Tool execution timeout
+    "enabled",             # Enable/disable server
+    "enabled_tools",       # Allow-list of tools
+    "disabled_tools",      # Deny-list of tools
+    "bearer_token_env_var",# Env var containing bearer token
+    "http_headers",        # HTTP headers (Codex naming)
+    "env_http_headers",    # Header names to env var names mapping
+})
+
+
+# ============================================================================
+# Field Mappings (universal name → host-specific name)
+# ============================================================================
+
+# Codex uses different field names for some universal/shared fields
+CODEX_FIELD_MAPPINGS: dict[str, str] = {
+    "args": "arguments",          # Codex uses 'arguments' instead of 'args'
+    "headers": "http_headers",    # Codex uses 'http_headers' instead of 'headers'
+    "includeTools": "enabled_tools",   # Gemini naming → Codex naming
+    "excludeTools": "disabled_tools",  # Gemini naming → Codex naming
+}
+
+
+# ============================================================================
+# Metadata Fields (never serialized to host config files)
+# ============================================================================
+
+# Fields that are Hatch metadata and should NEVER appear in serialized output
+EXCLUDED_ALWAYS: FrozenSet[str] = frozenset({
+    "name",  # Server name is key in the config dict, not a field value
+})
+