Merge pull request #31 from Model-Context-Interface/copilot/auto-parse-env-files

Auto-parse .env and .env.mci files from project root and ./mci directory using python-dotenv

Author: MaestroError

README.md

@@ -580,9 +580,136 @@ MCI supports environment variable templating in tool definitions:
 }
 ```
 
+### Automatic .env File Loading
+
+MCI automatically loads environment variables from `.env` and `.env.mci` files when loading your MCI schema. This provides a convenient way to manage environment-specific configuration without manually setting variables.
+
+**Automatic Detection:**
+- When you run any MCI command (`run`, `list`, `validate`, etc.), MCI looks for environment files in:
+  1. The project root directory (same location as your `mci.json` or `mci.yaml`)
+  2. The `./mci` directory
+
+**File Priority:**
+- MCI prioritizes `.env.mci` files (MCI-specific configs) over `.env` files (general configs)
+- **Important:** When `.env.mci` files exist, `.env` files are **not loaded** at all
+- This allows you to keep MCI-specific environment variables separate from general project variables
+
+**Loading Behavior:**
+- **If `.env.mci` files exist:** Only `.env.mci` files are loaded
+  1. `./mci/.env.mci` - Library MCI-specific configs
+  2. Project root `.env.mci` - Project MCI-specific configs (higher priority)
+- **If no `.env.mci` files exist:** `.env` files are loaded instead
+  1. `./mci/.env` - Library general defaults
+  2. Project root `.env` - Project-level configs (higher priority)
+- **Then:** System environment variables and explicit env_vars override all file-based configs
+
+**Full Precedence Order (lowest to highest):**
+1. File-based configs (`.env.mci` files if they exist, otherwise `.env` files)
+   - From `./mci/` directory first
+   - Then from project root
+2. System environment variables (set via `export` or shell config)
+3. Environment variables passed via CLI or code (highest priority)
+
+**Example .env file:**
+```bash
+# .env or .env.mci file in project root
+API_KEY=your-api-key-here
+BASE_URL=https://api.example.com
+DEBUG=false
+
+# Comments are supported
+# Blank lines are ignored
+
+# Export keyword is optional (automatically stripped)
+export OPTIONAL_VAR=value
+```
+
+**Example directory structure:**
+```
+my-project/
+├── .env.mci               # MCI-specific variables (if present, .env ignored)
+├── .env                   # General project variables (only if .env.mci absent)
+├── mci.json               # Your MCI schema
+└── mci/
+    ├── .env.mci           # Library MCI-specific (if present, ./mci/.env ignored)
+    ├── .env               # Library defaults (only if ./mci/.env.mci absent)
+    └── weather.mci.json   # Your toolsets
+```
+
+**Example: Using .env.mci files**
+```bash
+# Scenario 1: Only .env.mci files present
+# ./mci/.env.mci
+API_KEY=mci-library-key
+LIBRARY_VAR=lib-value
+
+# .env.mci (project root)
+API_KEY=mci-project-key    # Overrides ./mci/.env.mci
+MCI_SPECIFIC=mci-value
+
+# Result: MCI will use:
+# API_KEY=mci-project-key (from root .env.mci)
+# LIBRARY_VAR=lib-value (from ./mci/.env.mci)
+# MCI_SPECIFIC=mci-value (from root .env.mci)
+```
+
+**Example: Using .env files (no .env.mci)**
+```bash
+# Scenario 2: Only .env files present
+# ./mci/.env
+API_KEY=default-key
+LIBRARY_VAR=lib-value
+
+# .env (project root)
+API_KEY=project-key        # Overrides ./mci/.env
+PROJECT_VAR=proj-value
+
+# Result: MCI will use:
+# API_KEY=project-key (from root .env)
+# LIBRARY_VAR=lib-value (from ./mci/.env)
+# PROJECT_VAR=proj-value (from root .env)
+```
+
+**Notes:**
+- .env files are completely optional - MCI works fine without them
+- No error if .env files are missing
+- Use `.env.mci` for MCI-specific configurations to keep them completely separate from general project configs
+- When `.env.mci` exists, `.env` is ignored (not merged)
+- You can disable auto-loading by setting `auto_load_dotenv=False` when using the MCI library programmatically
+- .env files should NOT be committed to version control if they contain secrets
+
 ### Setting Environment Variables for MCP Clients
 
-When running MCI as an MCP server from clients like Claude Desktop or VS Code, configure environment variables in the client's settings:
+When running MCI as an MCP server from clients like Claude Desktop or VS Code, you have two options for environment variables:
+
+1. **Use .env files** (recommended): Create a `.env` file in your project root, and MCI will automatically load it
+2. **Configure in client settings**: Explicitly set environment variables in the MCP client configuration
+
+**Option 1: Using .env files (Recommended)**
+
+Create a `.env` file in your project root:
+```bash
+# .env
+API_KEY=your-api-key
+BASE_URL=https://api.example.com
+```
+
+Then configure your MCP client with minimal settings:
+```json
+{
+  "mcpServers": {
+    "mci-tools": {
+      "command": "uvx",
+      "args": ["mcix", "run"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+MCI will automatically load the `.env` file when it starts.
+
+**Option 2: Configure in Client Settings**
 
 **Claude Desktop Example** (`claude_desktop_config.json`):
 ```json
@@ -622,14 +749,23 @@ When running MCI as an MCP server from clients like Claude Desktop or VS Code, c
 
 **Running Standalone** (without MCP client):
 
-If you're running the MCP server directly in a terminal, set environment variables first:
+MCI automatically loads `.env` files from your project root and `./mci` directory:
+
+```bash
+# Create .env file
+echo "API_KEY=your-api-key" > .env
+echo "BASE_URL=https://api.example.com" >> .env
 
+# Run MCI - it will automatically load .env
+uvx mcix run
+```
+
+You can also set environment variables manually if needed:
 ```bash
 export API_KEY=your-api-key
 export BASE_URL=https://api.example.com
 uvx mcix run
 ```
-```
 
 ## Integration with MCP Clients
 

pyproject.toml

@@ -42,6 +42,7 @@ dependencies = [
     "mci-py>=1.1.4",
     "mcp>=1.19.0",
     "pytest-cov>=7.0.0",
+    "python-dotenv>=1.2.1",
     "pyyaml>=6.0.3",
     "rich>=14.2.0",
 ]

src/mci/core/config.py

@@ -3,11 +3,16 @@
 
 This module provides functionality to load and validate MCI configuration files
 using the MCIClient from mci-py. It handles schema validation, error handling,
-and provides user-friendly error messages.
+and provides user-friendly error messages. It also automatically loads environment
+variables from .env files in the project root and ./mci directory.
 """
 
+from pathlib import Path
+
 from mcipy import MCIClient, MCIClientError
 
+from mci.utils.dotenv import get_env_with_dotenv
+
 
 class MCIConfig:
     """
@@ -17,19 +22,40 @@ class MCIConfig:
     MCIClient from mci-py, which performs built-in schema validation.
     It also provides utilities for validating schemas and extracting
     user-friendly error messages.
+
+    The class automatically loads environment variables from .env files in:
+    - The project root directory (same location as the MCI schema file)
+    - The ./mci directory
+
+    Variables are merged with project root taking precedence over ./mci/.env.
     """
 
     @staticmethod
-    def load(file_path: str, env_vars: dict[str, str] | None = None) -> MCIClient:
+    def load(
+        file_path: str, env_vars: dict[str, str] | None = None, auto_load_dotenv: bool = True
+    ) -> MCIClient:
         """
         Load and parse an MCI configuration file using MCIClient.
 
         This method uses MCIClient from mci-py to load and validate the schema.
         The MCIClient performs comprehensive schema validation during initialization.
 
+        If auto_load_dotenv is True (default), automatically loads environment variables
+        from .env and .env.mci files. Priority order:
+        - If .env.mci files exist:
+          1. ./mci/.env.mci (library MCI-specific)
+          2. Project root .env.mci (project MCI-specific)
+        - If no .env.mci files exist:
+          1. ./mci/.env (library defaults)
+          2. Project root .env (project-level)
+        - Then:
+          3. System environment variables
+          4. env_vars argument (highest priority)
+
         Args:
             file_path: Path to the MCI schema file (.json, .yaml, or .yml)
-            env_vars: Optional environment variables for template substitution
+            env_vars: Optional environment variables for template substitution (highest priority)
+            auto_load_dotenv: Whether to automatically load .env files (default: True)
 
         Returns:
             An initialized MCIClient instance
@@ -41,20 +67,33 @@ def load(file_path: str, env_vars: dict[str, str] | None = None) -> MCIClient:
         Example:
             >>> config = MCIConfig()
             >>> try:
+            ...     # Auto-loads .env files from project root and ./mci
             ...     client = config.load("mci.json")
             ...     tools = client.tools()
             ... except MCIClientError as e:
             ...     print(f"Schema invalid: {e}")
         """
         try:
-            client = MCIClient(schema_file_path=file_path, env_vars=env_vars or {})
+            # Determine project root from schema file location
+            project_root = Path(file_path).parent.resolve()
+
+            # Load environment variables with proper precedence
+            if auto_load_dotenv:
+                merged_env = get_env_with_dotenv(project_root, env_vars)
+            else:
+                # If auto-loading is disabled, just use provided env_vars
+                merged_env = env_vars or {}
+
+            client = MCIClient(schema_file_path=file_path, env_vars=merged_env)
             return client
         except MCIClientError:
             # Re-raise with the original error message from mci-py
             raise
 
     @staticmethod
-    def validate_schema(file_path: str, env_vars: dict[str, str] | None = None) -> tuple[bool, str]:
+    def validate_schema(
+        file_path: str, env_vars: dict[str, str] | None = None, auto_load_dotenv: bool = True
+    ) -> tuple[bool, str]:
         """
         Validate an MCI schema file using MCIClient.
 
@@ -63,9 +102,13 @@ def validate_schema(file_path: str, env_vars: dict[str, str] | None = None) -> t
         MCIClient performs comprehensive validation including schema structure,
         required fields, and data types.
 
+        If auto_load_dotenv is True (default), automatically loads environment variables
+        from .env files in the project root and ./mci directory.
+
         Args:
             file_path: Path to the MCI schema file to validate
             env_vars: Optional environment variables for template substitution
+            auto_load_dotenv: Whether to automatically load .env files (default: True)
 
         Returns:
             A tuple of (is_valid, error_message) where:
@@ -79,9 +122,19 @@ def validate_schema(file_path: str, env_vars: dict[str, str] | None = None) -> t
             ...     print(f"Validation failed: {error}")
         """
         try:
+            # Determine project root from schema file location
+            project_root = Path(file_path).parent.resolve()
+
+            # Load environment variables with proper precedence
+            if auto_load_dotenv:
+                merged_env = get_env_with_dotenv(project_root, env_vars)
+            else:
+                # If auto-loading is disabled, just use provided env_vars
+                merged_env = env_vars or {}
+
             # Use validating=True to skip template resolution for MCP servers
             # This allows validation without requiring all env_vars at validation time
-            MCIClient(schema_file_path=file_path, env_vars=env_vars or {}, validating=True)
+            MCIClient(schema_file_path=file_path, env_vars=merged_env, validating=True)
             return (True, "")
         except MCIClientError as e:
             return (False, str(e))

src/mci/core/mci_client.py

@@ -3,12 +3,17 @@
 
 This module provides a CLI-friendly wrapper around the MCIClient class from mci-py.
 It delegates all schema parsing, validation, tool loading, and filtering to MCIClient,
-while providing CLI-specific error handling and output formatting.
+while providing CLI-specific error handling and output formatting. It also supports
+automatic loading of environment variables from .env files.
 """
 
+from pathlib import Path
+
 from mcipy import MCIClient
 from mcipy.models import Tool
 
+from mci.utils.dotenv import get_env_with_dotenv
+
 
 class MCIClientWrapper:
     """
@@ -17,20 +22,49 @@ class MCIClientWrapper:
     This class provides a CLI-friendly interface to MCIClient, delegating all
     tool loading, filtering, and schema operations to the upstream mci-py library.
     It focuses on error handling and formatting for CLI usability.
+
+    The wrapper automatically loads environment variables from .env files in:
+    - The project root directory (same location as the MCI schema file)
+    - The ./mci directory
     """
 
-    def __init__(self, file_path: str, env_vars: dict[str, str] | None = None):
+    def __init__(
+        self, file_path: str, env_vars: dict[str, str] | None = None, auto_load_dotenv: bool = True
+    ):
         """
         Initialize the wrapper with an MCIClient instance.
 
+        If auto_load_dotenv is True (default), automatically loads environment variables
+        from .env and .env.mci files. Priority order:
+        - If .env.mci files exist:
+          1. ./mci/.env.mci (library MCI-specific)
+          2. Project root .env.mci (project MCI-specific)
+        - If no .env.mci files exist:
+          1. ./mci/.env (library defaults)
+          2. Project root .env (project-level)
+        - Then:
+          3. System environment variables
+          4. env_vars argument (highest priority)
+
         Args:
             file_path: Path to the MCI schema file (.json, .yaml, or .yml)
-            env_vars: Optional environment variables for template substitution
+            env_vars: Optional environment variables for template substitution (highest priority)
+            auto_load_dotenv: Whether to automatically load .env files (default: True)
 
         Raises:
             MCIClientError: If the schema file cannot be loaded or parsed
         """
-        self._client: MCIClient = MCIClient(schema_file_path=file_path, env_vars=env_vars or {})
+        # Determine project root from schema file location
+        project_root = Path(file_path).parent.resolve()
+
+        # Load environment variables with proper precedence
+        if auto_load_dotenv:
+            merged_env = get_env_with_dotenv(project_root, env_vars)
+        else:
+            # If auto-loading is disabled, just use provided env_vars
+            merged_env = env_vars or {}
+
+        self._client: MCIClient = MCIClient(schema_file_path=file_path, env_vars=merged_env)
         self._file_path: str = file_path
 
     @property