Merge pull request #259 from DragonFSKY/feature/force-override-env-config

feat: add configurable environment variable override system

.env.example

@@ -167,6 +167,31 @@ DISABLED_TOOLS=analyze,refactor,testgen,secaudit,docgen,tracer
 # Leave empty for default language (English)
 # LOCALE=fr-FR
 
+# ===========================================
+# Zen MCP Server Configuration  
+# ===========================================
+
+# Force .env file values to override system environment variables
+# This prevents issues where different AI tools (Claude Code, etc.) pass 
+# conflicting or cached environment variables that override each other
+# 
+# When enabled (true):
+#   - .env file values take absolute precedence
+#   - Prevents MCP clients from passing outdated/cached API keys
+#   - Ensures consistent configuration across different AI tool integrations
+#   - Solves environment variable conflicts between multiple AI applications
+#
+# When disabled (false):
+#   - System environment variables take precedence (standard behavior)  
+#   - Suitable for production deployments with secure environment injection
+#   - Respects container orchestrator and CI/CD pipeline configurations
+#
+# Recommended settings:
+#   Development with multiple AI tools: true (prevents tool conflicts)
+#   Production/Container deployments: false (preserves security practices)
+#   CI/CD environments: false (respects pipeline secrets)
+ZEN_MCP_FORCE_ENV_OVERRIDE=false
+
 # ===========================================
 # Docker Configuration
 # ===========================================

server.py

@@ -31,13 +31,27 @@ from typing import Any, Optional
 # Try to load environment variables from .env file if dotenv is available
 # This is optional - environment variables can still be passed directly
 try:
-    from dotenv import load_dotenv
+    from dotenv import dotenv_values, load_dotenv
 
     # Load environment variables from .env file in the script's directory
     # This ensures .env is loaded regardless of the current working directory
     script_dir = Path(__file__).parent
     env_file = script_dir / ".env"
-    load_dotenv(dotenv_path=env_file)
+
+    # First load only to read ZEN_MCP_FORCE_ENV_OVERRIDE, then reload with proper override setting
+    # Use a temporary environment to read just this configuration variable
+    temp_env = {}
+    if env_file.exists():
+        temp_env = dotenv_values(env_file)
+
+    # Check if we should force override based on .env file content (not system env)
+    force_override = temp_env.get("ZEN_MCP_FORCE_ENV_OVERRIDE", "false").lower() == "true"
+
+    # Load .env file with appropriate override setting
+    load_dotenv(dotenv_path=env_file, override=force_override)
+
+    # Store override setting for logging after logger is configured
+    _zen_mcp_force_override = force_override
 except ImportError:
     # dotenv not available - this is fine, environment variables can still be passed directly
     # This commonly happens when running via uvx or in minimal environments
@@ -163,6 +177,20 @@ except Exception as e:
 
 logger = logging.getLogger(__name__)
 
+# Log ZEN_MCP_FORCE_ENV_OVERRIDE configuration if it was set during dotenv loading
+try:
+    if "_zen_mcp_force_override" in globals():
+        if _zen_mcp_force_override:
+            logger.info(
+                "ZEN_MCP_FORCE_ENV_OVERRIDE enabled - .env file values will override system environment variables"
+            )
+            logger.debug("Environment override prevents conflicts between different AI tools passing cached API keys")
+        else:
+            logger.debug("ZEN_MCP_FORCE_ENV_OVERRIDE disabled - system environment variables take precedence")
+except NameError:
+    # _zen_mcp_force_override not defined, which means dotenv wasn't available or no .env file
+    pass
+
 
 # Create the MCP server instance with a unique name identifier
 # This name is used by MCP clients to identify and connect to this specific server