From 93ce6987b6e7d8678ffa5ac51f5106a7a21ce67b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B0=A2=E6=A0=8B=E6=A2=81?= <xiedlc@montnets.com>
Date: Tue, 2 Sep 2025 08:35:06 +0800
Subject: [PATCH] feat: add configurable environment variable override system

Add ZEN_MCP_FORCE_ENV_OVERRIDE configuration to control whether .env file values
override system environment variables. This prevents conflicts when multiple AI
tools pass different cached environment variables to the MCP server.

- Use dotenv_values() to read configuration from .env file only
- Apply conditional override based on configuration setting
- Add appropriate logging for transparency
- Update .env.example with detailed configuration documentation
- Maintains backward compatibility with default behavior (false)
---
 .env.example | 25 +++++++++++++++++++++++++
 server.py    | 22 +++++++++++++++++++++-
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/.env.example b/.env.example
index 58d0037..81cb082 100644
--- a/.env.example
+++ b/.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
 # ===========================================
diff --git a/server.py b/server.py
index ee924fb..5cda526 100644
--- a/server.py
+++ b/server.py
@@ -37,7 +37,27 @@ try:
     # 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():
+        from dotenv import dotenv_values
+        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)
+    
+    # Log the configuration choice
+    logger = logging.getLogger(__name__)
+    if 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 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