Add .env file support for MCP server configuration

- Centralize configuration management in new config.ts module
- Load environment variables from .env file (default) or custom path via --env flag
- Support CLI argument overrides for all configuration options (--umbraco-*)
- Track configuration sources (CLI vs ENV) for transparency
- Add comprehensive validation and error reporting for missing credentials
- Update documentation with .env usage examples and .mcp.json configuration
- Refactor tests to use centralized config system
- Remove deprecated env.ts helper
- Improve multi-culture document test with proper setup and cleanup

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: Phil Whittaker

README.md

@@ -80,6 +80,34 @@ claude mcp list
 
 This will add umbraco-mcp to the existing project in the claude.json config file.
 
+#### Configuration via .mcp.json (Project-specific)
+
+For project-specific Claude Code configuration, create a `.mcp.json` file in your project root that references environment variables for sensitive data:
+
+```json
+{
+  "mcpServers": {
+    "umbraco-mcp": {
+      "command": "npx",
+      "args": ["@umbraco-cms/mcp-dev@beta"],
+      "env": {
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
+        "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp",
+        "UMBRACO_CLIENT_SECRET": "your-client-secret-here",
+        "UMBRACO_BASE_URL": "https://localhost:44391",
+        "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "culture,document,media",
+        "UMBRACO_EXCLUDE_TOOLS": "delete-document,empty-recycle-bin"
+      }
+    }
+  }
+}
+```
+
+Using the `.mcp.json` file allows you to:
+- Configure MCP servers per project
+- Share configuration with team members (commit to version control)
+- Override global Claude Code MCP settings for specific projects
+- Move the environment varaibles to a .env file to prevent leaking of secrets to your code repo
 
 </details>
 
@@ -142,6 +170,7 @@ Add the following to the config file and update the env variables.
 ```
 </details>
 
+
 #### Authentication Configuration Keys
 
 - `UMBRACO_CLIENT_ID`
@@ -156,6 +185,40 @@ Umbraco API User client secert
 
 Url of the Umbraco site, it only needs to be the scheme and domain e.g https://<nolink/>example.com
 
+### Environment Configuration Options
+
+The Umbraco MCP server supports environment configuration via:
+1. **Environment variables in MCP client config as above** (Claude Desktop, VS Code, etc.)
+2. **Local `.env` file** for development (see `.env.example`)
+3. **CLI arguments** when running directly
+
+**Configuration precedence:** CLI arguments > Environment variables > `.env` file
+
+#### Using a `.env` file (Development)
+
+For local development, you can create a `.env` file in the project root:
+
+```bash
+# Edit with your values
+UMBRACO_CLIENT_ID=your-api-user-id
+UMBRACO_CLIENT_SECRET=your-api-secret
+UMBRACO_BASE_URL=http://localhost:56472
+```
+
+The `.env` file is gitignored to keep your secrets secure.
+
+#### CLI Arguments
+
+You can also pass configuration via CLI arguments:
+
+```bash
+npx @umbraco-cms/mcp-dev@beta \
+  --umbraco-client-id="your-id" \
+  --umbraco-client-secret="your-secret" \
+  --umbraco-base-url="http://localhost:56472" \
+  --env="/path/to/custom/.env"
+```
+
 ## API Coverage
 
 This MCP server provides **comprehensive coverage** of the Umbraco Management API. We have achieved **full parity** with all applicable endpoints, implementing tools for every operational endpoint suitable for AI-assisted content management.

docs/tool-collection-filtering.md

@@ -89,16 +89,16 @@ Some collections have dependencies that are automatically resolved:
 
 ### Configuration Loading
 
-Configuration is loaded from environment variables with automatic parsing:
+Configuration is loaded from the server config object:
 
 ```typescript
 export class CollectionConfigLoader {
-  static loadFromEnv(): CollectionConfiguration {
+  static loadFromConfig(config: UmbracoServerConfig): CollectionConfiguration {
     return {
-      enabledCollections: env.UMBRACO_INCLUDE_TOOL_COLLECTIONS ?? DEFAULT_COLLECTION_CONFIG.enabledCollections,
-      disabledCollections: env.UMBRACO_EXCLUDE_TOOL_COLLECTIONS ?? DEFAULT_COLLECTION_CONFIG.disabledCollections,
-      enabledTools: env.UMBRACO_INCLUDE_TOOLS ?? DEFAULT_COLLECTION_CONFIG.enabledTools,
-      disabledTools: env.UMBRACO_EXCLUDE_TOOLS ?? DEFAULT_COLLECTION_CONFIG.disabledTools,
+      enabledCollections: config.includeToolCollections ?? DEFAULT_COLLECTION_CONFIG.enabledCollections,
+      disabledCollections: config.excludeToolCollections ?? DEFAULT_COLLECTION_CONFIG.disabledCollections,
+      enabledTools: config.includeTools ?? DEFAULT_COLLECTION_CONFIG.enabledTools,
+      disabledTools: config.excludeTools ?? DEFAULT_COLLECTION_CONFIG.disabledTools,
     };
   }
 }
@@ -108,7 +108,7 @@ export class CollectionConfigLoader {
 
 The `UmbracoToolFactory` processes configuration and loads tools:
 
-1. Load configuration from environment variables
+1. Load configuration from server config
 2. Validate collection names and dependencies
 3. Resolve collection dependencies automatically
 4. Filter collections based on configuration

jest.setup.ts

@@ -1,4 +1,12 @@
 import dotenv from 'dotenv';
+import { initializeUmbracoAxios } from './src/orval/client/umbraco-axios.js';
 
-// Load environment variables from .env.test
-dotenv.config({ path: '.env' });
+// Load environment variables from .env
+dotenv.config({ path: '.env' });
+
+// Initialize Umbraco Axios client with environment variables
+initializeUmbracoAxios({
+  clientId: process.env.UMBRACO_CLIENT_ID || '',
+  clientSecret: process.env.UMBRACO_CLIENT_SECRET || '',
+  baseUrl: process.env.UMBRACO_BASE_URL || ''
+});