moai-adk 0.25.4__py3-none-any.whl → 0.32.8__py3-none-any.whl

moai_adk/core/template/processor.py

@@ -12,6 +12,7 @@ Enhanced with:
 
 from __future__ import annotations
 
+import json
 import logging
 import re
 import shutil
@@ -61,23 +62,13 @@ class TemplateProcessorConfig:
         return cls(
             version_cache_ttl_seconds=config_dict.get("version_cache_ttl_seconds", 120),
             version_fallback=config_dict.get("version_fallback", "unknown"),
-            version_format_regex=config_dict.get(
-                "version_format_regex", r"^v?(\d+\.\d+\.\d+(-[a-zA-Z0-9]+)?)$"
-            ),
-            enable_version_validation=config_dict.get(
-                "enable_version_validation", True
-            ),
+            version_format_regex=config_dict.get("version_format_regex", r"^v?(\d+\.\d+\.\d+(-[a-zA-Z0-9]+)?)$"),
+            enable_version_validation=config_dict.get("enable_version_validation", True),
             preserve_user_version=config_dict.get("preserve_user_version", True),
-            validate_template_variables=config_dict.get(
-                "validate_template_variables", True
-            ),
+            validate_template_variables=config_dict.get("validate_template_variables", True),
             max_variable_length=config_dict.get("max_variable_length", 50),
-            allowed_variable_pattern=config_dict.get(
-                "allowed_variable_pattern", r"^[A-Z_]+$"
-            ),
-            enable_substitution_warnings=config_dict.get(
-                "enable_substitution_warnings", True
-            ),
+            allowed_variable_pattern=config_dict.get("allowed_variable_pattern", r"^[A-Z_]+$"),
+            enable_substitution_warnings=config_dict.get("enable_substitution_warnings", True),
             enable_caching=config_dict.get("enable_caching", True),
             cache_size=config_dict.get("cache_size", 100),
             async_operations=config_dict.get("async_operations", False),
@@ -95,7 +86,7 @@ class TemplateProcessor:
         ".moai/reports/",  # User reports
         ".moai/project/",  # User project documents (product/structure/tech.md)
         # config.json is now FORCE OVERWRITTEN (backup in .moai-backups/)
-        # Merge via /alfred:0-project when optimized=false
+        # Merge via /moai:0-project when optimized=false
     ]
 
     # Paths excluded from backups
@@ -103,11 +94,10 @@ class TemplateProcessor:
 
     # Common template variables with validation hints
     COMMON_TEMPLATE_VARIABLES = {
-        "PROJECT_DIR": "Cross-platform project path (run /alfred:0-project to set)",
-        "HOOK_PROJECT_DIR": "Cross-platform hook path (deprecated, use PROJECT_DIR instead)",
-        "PROJECT_NAME": "Project name (run /alfred:0-project to set)",
-        "AUTHOR": "Project author (run /alfred:0-project to set)",
-        "CONVERSATION_LANGUAGE": "Interface language (run /alfred:0-project to set)",
+        "PROJECT_DIR": "Cross-platform project path (run /moai:0-project to set)",
+        "PROJECT_NAME": "Project name (run /moai:0-project to set)",
+        "AUTHOR": "Project author (run /moai:0-project to set)",
+        "CONVERSATION_LANGUAGE": "Interface language (run /moai:0-project to set)",
         "MOAI_VERSION": "MoAI-ADK version (should be set automatically)",
         "MOAI_VERSION_SHORT": "Short MoAI-ADK version (without 'v' prefix)",
         "MOAI_VERSION_DISPLAY": "Display version with proper formatting",
@@ -119,9 +109,7 @@ class TemplateProcessor:
         "CREATION_TIMESTAMP": "Project creation timestamp",
     }
 
-    def __init__(
-        self, target_path: Path, config: Optional[TemplateProcessorConfig] = None
-    ) -> None:
+    def __init__(self, target_path: Path, config: Optional[TemplateProcessorConfig] = None) -> None:
         """Initialize the processor with enhanced configuration.
 
         Args:
@@ -135,16 +123,14 @@ class TemplateProcessor:
         self.context: dict[str, str] = {}  # Template variable substitution context
         self._version_reader: VersionReader | None = None
         self.config = config or TemplateProcessorConfig()
-        self._substitution_cache: Dict[str, str] = {}  # Cache for substitution results
-        self._variable_validation_cache: Dict[str, bool] = (
-            {}
-        )  # Cache for variable validation
+        self._substitution_cache: Dict[
+            int, tuple[str, list[str]]
+        ] = {}  # Cache for substitution results (key: hash, value: (content, warnings))
+        self._variable_validation_cache: Dict[str, bool] = {}  # Cache for variable validation
         self.logger = logging.getLogger(__name__)
 
         if self.config.verbose_logging:
-            self.logger.info(
-                f"TemplateProcessor initialized with config: {self.config}"
-            )
+            self.logger.info(f"TemplateProcessor initialized with config: {self.config}")
 
     def set_context(self, context: dict[str, str]) -> None:
         """Set variable substitution context with enhanced validation.
@@ -213,21 +199,15 @@ class TemplateProcessor:
 
             # Check variable length
             if len(var_name) > self.config.max_variable_length:
-                warning_messages.append(
-                    f"Variable name '{var_name}' exceeds maximum length"
-                )
+                warning_messages.append(f"Variable name '{var_name}' exceeds maximum length")
 
             # Check variable value length
             if len(var_value) > self.config.max_variable_length * 2:
-                warning_messages.append(
-                    f"Variable value '{var_value[:20]}...' is very long"
-                )
+                warning_messages.append(f"Variable value '{var_value[:20]}...' is very long")
 
             # Check for potentially dangerous values
             if "{{" in var_value or "}}" in var_value:
-                warning_messages.append(
-                    f"Variable '{var_name}' contains placeholder patterns"
-                )
+                warning_messages.append(f"Variable '{var_name}' contains placeholder patterns")
 
         # Check for common variables that should be present
         missing_common_vars = []
@@ -236,28 +216,20 @@ class TemplateProcessor:
                 missing_common_vars.append(common_var)
 
         if missing_common_vars and self.config.enable_substitution_warnings:
-            warning_messages.append(
-                f"Common variables missing: {', '.join(missing_common_vars[:3])}"
-            )
+            warning_messages.append(f"Common variables missing: {', '.join(missing_common_vars[:3])}")
 
         # Report validation results
         if validation_errors and not self.config.graceful_degradation:
-            raise ValueError(
-                f"Template variable validation failed: {validation_errors}"
-            )
+            raise ValueError(f"Template variable validation failed: {validation_errors}")
 
         if validation_errors and self.config.graceful_degradation:
-            self.logger.warning(
-                f"Template variable validation warnings: {validation_errors}"
-            )
+            self.logger.warning(f"Template variable validation warnings: {validation_errors}")
 
         if warning_messages and self.config.enable_substitution_warnings:
             self.logger.warning(f"Template variable warnings: {warning_messages}")
 
         if self.config.verbose_logging:
-            self.logger.debug(
-                f"Template variables validated: {len(context)} variables checked"
-            )
+            self.logger.debug(f"Template variables validated: {len(context)} variables checked")
 
     def get_enhanced_version_context(self) -> dict[str, str]:
         """
@@ -278,28 +250,16 @@ class TemplateProcessor:
 
             # Basic version information
             version_context["MOAI_VERSION"] = moai_version
-            version_context["MOAI_VERSION_SHORT"] = self._format_short_version(
-                moai_version
-            )
-            version_context["MOAI_VERSION_DISPLAY"] = self._format_display_version(
-                moai_version
-            )
+            version_context["MOAI_VERSION_SHORT"] = self._format_short_version(moai_version)
+            version_context["MOAI_VERSION_DISPLAY"] = self._format_display_version(moai_version)
 
             # Enhanced formatting options
-            version_context["MOAI_VERSION_TRIMMED"] = self._format_trimmed_version(
-                moai_version, max_length=10
-            )
-            version_context["MOAI_VERSION_SEMVER"] = self._format_semver_version(
-                moai_version
-            )
+            version_context["MOAI_VERSION_TRIMMED"] = self._format_trimmed_version(moai_version, max_length=10)
+            version_context["MOAI_VERSION_SEMVER"] = self._format_semver_version(moai_version)
 
             # Validation and source information
-            version_context["MOAI_VERSION_VALID"] = (
-                "true" if moai_version != "unknown" else "false"
-            )
-            version_context["MOAI_VERSION_SOURCE"] = self._get_version_source(
-                version_reader
-            )
+            version_context["MOAI_VERSION_VALID"] = "true" if moai_version != "unknown" else "false"
+            version_context["MOAI_VERSION_SOURCE"] = self._get_version_source(version_reader)
 
             # Performance metrics
             cache_age = version_reader.get_cache_age_seconds()
@@ -311,9 +271,7 @@ class TemplateProcessor:
             # Additional metadata
             if self.config.enable_version_validation:
                 is_valid = self._is_valid_version_format(moai_version)
-                version_context["MOAI_VERSION_FORMAT_VALID"] = (
-                    "true" if is_valid else "false"
-                )
+                version_context["MOAI_VERSION_FORMAT_VALID"] = "true" if is_valid else "false"
 
             if self.config.verbose_logging:
                 logger.debug(f"Enhanced version context generated: {version_context}")
@@ -323,21 +281,11 @@ class TemplateProcessor:
             # Use fallback version with comprehensive formatting
             fallback_version = self.config.version_fallback
             version_context["MOAI_VERSION"] = fallback_version
-            version_context["MOAI_VERSION_SHORT"] = self._format_short_version(
-                fallback_version
-            )
-            version_context["MOAI_VERSION_DISPLAY"] = self._format_display_version(
-                fallback_version
-            )
-            version_context["MOAI_VERSION_TRIMMED"] = self._format_trimmed_version(
-                fallback_version, max_length=10
-            )
-            version_context["MOAI_VERSION_SEMVER"] = self._format_semver_version(
-                fallback_version
-            )
-            version_context["MOAI_VERSION_VALID"] = (
-                "false" if fallback_version == "unknown" else "true"
-            )
+            version_context["MOAI_VERSION_SHORT"] = self._format_short_version(fallback_version)
+            version_context["MOAI_VERSION_DISPLAY"] = self._format_display_version(fallback_version)
+            version_context["MOAI_VERSION_TRIMMED"] = self._format_trimmed_version(fallback_version, max_length=10)
+            version_context["MOAI_VERSION_SEMVER"] = self._format_semver_version(fallback_version)
+            version_context["MOAI_VERSION_VALID"] = "false" if fallback_version == "unknown" else "true"
             version_context["MOAI_VERSION_SOURCE"] = "fallback_config"
             version_context["MOAI_VERSION_CACHE_AGE"] = "unavailable"
             version_context["MOAI_VERSION_FORMAT_VALID"] = "false"
@@ -466,14 +414,6 @@ class TemplateProcessor:
         package_root = current_file.parent.parent.parent
         return package_root / "templates"
 
-    def set_context(self, context: dict[str, str]) -> None:
-        """Set variable substitution context.
-
-        Args:
-            context: Dictionary of template variables.
-        """
-        self.context = context
-
     def _substitute_variables(self, content: str) -> tuple[str, list[str]]:
         """
         Substitute template variables in content with enhanced validation and caching.
@@ -503,9 +443,7 @@ class TemplateProcessor:
                 if self.config.validate_template_variables:
                     # Validate variable before substitution
                     if not self._is_valid_template_variable(key, value):
-                        warnings.append(
-                            f"Invalid variable {key} - skipped substitution"
-                        )
+                        warnings.append(f"Invalid variable {key} - skipped substitution")
                         continue
 
                 safe_value = self._sanitize_value(value)
@@ -527,17 +465,13 @@ class TemplateProcessor:
                     suggestion = self.COMMON_TEMPLATE_VARIABLES[var]
                     warning_parts.append(f"{{{{{var}}}}} → {suggestion}")
                 else:
-                    warning_parts.append(
-                        f"{{{{{var}}}}} → Unknown variable (check template)"
-                    )
+                    warning_parts.append(f"{{{{{var}}}}} → Unknown variable (check template)")
 
             warnings.append("Template variables not substituted:")
             warnings.extend(f"  • {part}" for part in warning_parts)
 
             if self.config.enable_substitution_warnings:
-                warnings.append(
-                    "💡 Run 'uv run moai-adk update' to fix template variables"
-                )
+                warnings.append("💡 Run 'uv run moai-adk update' to fix template variables")
 
         # Add performance information if verbose logging is enabled
         if self.config.verbose_logging:
@@ -668,7 +602,7 @@ class TemplateProcessor:
         Returns:
             Content with localized descriptions.
         """
-        import yaml
+        import yaml  # type: ignore[import-untyped]
 
         # Pattern to match YAML frontmatter
         frontmatter_pattern = r"^---\n(.*?)\n---"
@@ -712,6 +646,8 @@ class TemplateProcessor:
         Returns:
             List of warnings.
         """
+        import stat
+
         warnings = []
 
         # Text files: read, substitute, write
@@ -721,9 +657,7 @@ class TemplateProcessor:
                 content, file_warnings = self._substitute_variables(content)
 
                 # Apply description localization for command/output-style files
-                if src.suffix == ".md" and (
-                    "commands/alfred" in str(src) or "output-styles/alfred" in str(src)
-                ):
+                if src.suffix == ".md" and ("commands/alfred" in str(src) or "output-styles/alfred" in str(src)):
                     lang = self.context.get("CONVERSATION_LANGUAGE", "en")
                     content = self._localize_yaml_description(content, lang)
 
@@ -736,6 +670,12 @@ class TemplateProcessor:
             # Binary file or no context: simple copy
             shutil.copy2(src, dst)
 
+        # Ensure executable permission for shell scripts
+        if src.suffix == ".sh":
+            # Always make shell scripts executable regardless of source permissions
+            dst_mode = dst.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+            dst.chmod(dst_mode)
+
         return warnings
 
     def _copy_dir_with_substitution(self, src: Path, dst: Path) -> None:
@@ -781,6 +721,7 @@ class TemplateProcessor:
         self._copy_github(silent)
         self._copy_claude_md(silent)
         self._copy_gitignore(silent)
+        self._copy_mcp_json(silent)
 
         if not silent:
             console.print("✅ Templates copied successfully")
@@ -849,16 +790,21 @@ class TemplateProcessor:
         # Create .claude directory if not exists
         dst.mkdir(parents=True, exist_ok=True)
 
-        # Alfred folders to copy wholesale (overwrite)
-        alfred_folders = [
+        # Alfred and Moai folders to copy wholesale (overwrite)
+        # Including both legacy alfred/ and new moai/ structure
+        alfred_moai_folders = [
             "hooks/alfred",
+            "hooks/moai",
             "commands/alfred",  # Contains 0-project.md, 1-plan.md, 2-run.md, 3-sync.md
-            "output-styles/alfred",
+            "commands/moai",
+            "output-styles/moai",
             "agents/alfred",
+            "agents/moai",
+            "skills",  # NEW: Complete replacement for skills folder
         ]
 
-        # 1. Copy Alfred folders wholesale (backup before delete & overwrite)
-        for folder in alfred_folders:
+        # 1. Copy Alfred and Moai folders wholesale (backup before delete & overwrite)
+        for folder in alfred_moai_folders:
             src_folder = src / folder
             dst_folder = dst / folder
 
@@ -873,7 +819,35 @@ class TemplateProcessor:
                 if not silent:
                     console.print(f"   ✅ .claude/{folder}/ overwritten")
 
-        # 2. Copy other files/folders individually (smart merge for settings.json)
+        # 1.5 Copy other subdirectories in parent folders (e.g., output-styles/moai, hooks/shared)
+        # This ensures non-alfred subdirectories are also copied
+        parent_folders_with_subdirs = ["output-styles", "hooks", "commands", "agents"]
+        for parent_name in parent_folders_with_subdirs:
+            src_parent = src / parent_name
+            if not src_parent.exists():
+                continue
+
+            for subdir in src_parent.iterdir():
+                if not subdir.is_dir():
+                    continue
+
+                # Skip alfred subdirectories (already handled above)
+                if subdir.name == "alfred":
+                    continue
+
+                rel_subdir = f"{parent_name}/{subdir.name}"
+                dst_subdir = dst / parent_name / subdir.name
+
+                if dst_subdir.exists():
+                    # For non-alfred directories, overwrite with merge if necessary
+                    shutil.rmtree(dst_subdir)
+
+                # Copy the subdirectory
+                shutil.copytree(subdir, dst_subdir)
+                if not silent:
+                    console.print(f"   ✅ .claude/{rel_subdir}/ copied")
+
+        # 2. Copy other files/folders individually (smart merge for settings.json and config.json)
         all_warnings = []
         for item in src.iterdir():
             rel_path = item.relative_to(src)
@@ -899,9 +873,12 @@ class TemplateProcessor:
                         dst_item.write_text(content, encoding="utf-8")
                         all_warnings.extend(file_warnings)
                     if not silent:
-                        console.print(
-                            "   🔄 settings.json merged (Hook paths configured for your OS)"
-                        )
+                        console.print("   🔄 settings.json merged (Hook paths configured for your OS)")
+                # Smart merge for config.json
+                elif item.name == "config.json":
+                    self._merge_config_json(item, dst_item)
+                    if not silent:
+                        console.print("   🔄 config.json merged (user preferences preserved)")
                 else:
                     # FORCE OVERWRITE: Always copy other files (no skip)
                     warnings = self._copy_file_with_substitution(item, dst_item)
@@ -984,12 +961,10 @@ class TemplateProcessor:
             self._copy_dir_with_substitution(src, dst)
 
         if not silent:
-            console.print(
-                "   🔄 .github/ merged (user workflows preserved, variables substituted)"
-            )
+            console.print("   🔄 .github/ merged (user workflows preserved, variables substituted)")
 
     def _copy_claude_md(self, silent: bool = False) -> None:
-        """Copy CLAUDE.md with smart merge (preserves \"## Project Information\" section)."""
+        """Copy CLAUDE.md with complete replacement (no merge)."""
         src = self.template_root / "CLAUDE.md"
         dst = self.target_path / "CLAUDE.md"
 
@@ -998,27 +973,11 @@ class TemplateProcessor:
                 console.print("⚠️ CLAUDE.md template not found")
             return
 
-        # Smart merge: preserve existing "## Project Information" section
-        if dst.exists():
-            self._merge_claude_md(src, dst)
-            # Substitute variables in the merged content
-            if self.context:
-                content = dst.read_text(encoding="utf-8")
-                content, warnings = self._substitute_variables(content)
-                dst.write_text(content, encoding="utf-8")
-                if warnings and not silent:
-                    console.print("[yellow]⚠️ Template warnings:[/yellow]")
-                    for warning in set(warnings):
-                        console.print(f"   {warning}")
-            if not silent:
-                console.print(
-                    "   🔄 CLAUDE.md merged (project information preserved, variables substituted)"
-                )
-        else:
-            # First time: just copy
-            self._copy_file_with_substitution(src, dst)
-            if not silent:
-                console.print("   ✅ CLAUDE.md created")
+        # Simple copy with substitution (no merge)
+        self._copy_file_with_substitution(src, dst)
+
+        if not silent:
+            console.print("   ✅ CLAUDE.md replaced (use CLAUDE.local.md for personal instructions)")
 
     def _merge_claude_md(self, src: Path, dst: Path) -> None:
         """Delegate the smart merge for CLAUDE.md.
@@ -1047,15 +1006,119 @@ class TemplateProcessor:
         """
         # Find the latest backup for user settings extraction
         backup_path = None
-        if self.backup.backup_dir.exists():
-            backups = sorted(self.backup.backup_dir.iterdir(), reverse=True)
-            if backups:
-                backup_settings = backups[0] / ".claude" / "settings.json"
-                if backup_settings.exists():
-                    backup_path = backup_settings
+        latest_backup = self.backup.get_latest_backup()
+        if latest_backup:
+            backup_settings = latest_backup / ".claude" / "settings.json"
+            if backup_settings.exists():
+                backup_path = backup_settings
 
         self.merger.merge_settings_json(src, dst, backup_path)
 
+    def _merge_config_json(self, src: Path, dst: Path) -> None:
+        """Smart merge for config.json using LanguageConfigResolver priority system.
+
+        Args:
+            src: Template config.json.
+            dst: Project config.json.
+        """
+        import json
+
+        # Load template config
+        try:
+            template_config = json.loads(src.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, FileNotFoundError) as e:
+            console.print(f"⚠️ Warning: Could not read template config.json: {e}")
+            return
+
+        # Find latest backup config.json
+        latest_backup = self.backup.get_latest_backup()
+        if latest_backup:
+            backup_config_path = latest_backup / ".moai" / "config" / "config.json"
+            if backup_config_path.exists():
+                try:
+                    json.loads(backup_config_path.read_text(encoding="utf-8"))
+                except json.JSONDecodeError as e:
+                    console.print(f"⚠️ Warning: Could not read backup config.json: {e}")
+
+        # Load existing project config.json
+        existing_config = {}
+        if dst.exists():
+            try:
+                existing_config = json.loads(dst.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as e:
+                console.print(f"⚠️ Warning: Could not read existing config.json: {e}")
+
+        # Merge with priority system: Environment > Existing User > Template
+        # We'll use LanguageConfigResolver to handle this properly
+        try:
+            # Import LanguageConfigResolver for priority-based merging
+            from moai_adk.core.language_config_resolver import LanguageConfigResolver
+
+            # Create temporary resolver to handle merging
+            temp_project_path = self.target_path / ".moai" / "config"
+            temp_project_path.mkdir(parents=True, exist_ok=True)
+
+            # Start with template config as base
+            merged_config = template_config.copy()
+
+            # Apply existing user config (higher priority than template)
+            for key, value in existing_config.items():
+                if key not in ["config_source"]:  # Skip metadata
+                    if key in merged_config and isinstance(merged_config[key], dict) and isinstance(value, dict):
+                        # Deep merge for nested objects
+                        merged_config[key].update(value)
+                    else:
+                        merged_config[key] = value
+
+            # Apply environment variables (highest priority)
+            import os
+
+            env_mappings = {
+                "MOAI_USER_NAME": ("user", "name"),
+                "MOAI_CONVERSATION_LANG": ("language", "conversation_language"),
+                "MOAI_AGENT_PROMPT_LANG": ("language", "agent_prompt_language"),
+                "MOAI_CONVERSATION_LANG_NAME": (
+                    "language",
+                    "conversation_language_name",
+                ),
+                "MOAI_GIT_COMMIT_MESSAGES_LANG": ("language", "git_commit_messages"),
+                "MOAI_CODE_COMMENTS_LANG": ("language", "code_comments"),
+                "MOAI_DOCUMENTATION_LANG": ("language", "documentation"),
+                "MOAI_ERROR_MESSAGES_LANG": ("language", "error_messages"),
+            }
+
+            for env_var, (section, key) in env_mappings.items():
+                env_value = os.getenv(env_var)
+                if env_value:
+                    if section not in merged_config:
+                        merged_config[section] = {}
+                    merged_config[section][key] = env_value
+
+            # Ensure consistency
+            resolver = LanguageConfigResolver(str(self.target_path))
+            merged_config = resolver._ensure_consistency(merged_config)
+
+            # Write merged config
+            dst.write_text(
+                json.dumps(merged_config, indent=2, ensure_ascii=False) + "\n",
+                encoding="utf-8",
+            )
+
+        except ImportError:
+            # Fallback: simple merge without LanguageConfigResolver
+            merged_config = template_config.copy()
+
+            # Apply existing config
+            for key, value in existing_config.items():
+                if key not in ["config_source"]:
+                    merged_config[key] = value
+
+            dst.write_text(
+                json.dumps(merged_config, indent=2, ensure_ascii=False) + "\n",
+                encoding="utf-8",
+            )
+            console.print("   ⚠️ Warning: Using simple merge (LanguageConfigResolver not available)")
+
     def _copy_gitignore(self, silent: bool = False) -> None:
         """.gitignore copy (optional)."""
         src = self.template_root / ".gitignore"
@@ -1083,6 +1146,47 @@ class TemplateProcessor:
         """
         self.merger.merge_gitignore(src, dst)
 
+    def _copy_mcp_json(self, silent: bool = False) -> None:
+        """.mcp.json copy (smart merge with existing MCP server configuration)."""
+        src = self.template_root / ".mcp.json"
+        dst = self.target_path / ".mcp.json"
+
+        if not src.exists():
+            return
+
+        # Merge with existing .mcp.json when present (preserve user-added MCP servers)
+        if dst.exists():
+            self._merge_mcp_json(src, dst)
+            if not silent:
+                console.print("   🔄 .mcp.json merged (user MCP servers preserved)")
+        else:
+            shutil.copy2(src, dst)
+            if not silent:
+                console.print("   ✅ .mcp.json copy complete")
+
+    def _merge_mcp_json(self, src: Path, dst: Path) -> None:
+        """Smart merge for .mcp.json (preserve user-added MCP servers).
+
+        Args:
+            src: Template .mcp.json.
+            dst: Project .mcp.json.
+        """
+        try:
+            src_data = json.loads(src.read_text(encoding="utf-8"))
+            dst_data = json.loads(dst.read_text(encoding="utf-8"))
+
+            # Merge mcpServers: preserve user servers, update template servers
+            if "mcpServers" in src_data:
+                if "mcpServers" not in dst_data:
+                    dst_data["mcpServers"] = {}
+                # Update with template servers (preserves existing user servers)
+                dst_data["mcpServers"].update(src_data["mcpServers"])
+
+            # Write merged result back
+            dst.write_text(json.dumps(dst_data, indent=2, ensure_ascii=False), encoding="utf-8")
+        except json.JSONDecodeError as e:
+            console.print(f"[yellow]⚠️ Failed to merge .mcp.json: {e}[/yellow]")
+
     def merge_config(self, detected_language: str | None = None) -> dict[str, str]:
         """Delegate the smart merge for config.json.