Cline rules

1---
2description: Guidelines for managing environment variables and configuration in MCP servers
3author: Community
4version: 1.0
5category: "MCP Development"
6tags: ["mcp", "environment", "configuration", "best-practices"]
7globs: ["**/*.env", "**/.env.example", "**/mcp-server/**/*"]
8---
9 
10# Environment Configuration in MCP Servers
11 
12## Overview
13Model Context Protocol (MCP) servers often require access to API keys and configuration values that should not be committed to version control. This document outlines the recommended approach for managing environment variables in MCP servers.
14 
15## Recommended Implementation
16 
17### 1. Project Structure
18Place your `.env` file in the root directory of your MCP server project:
19 
20```
21your-mcp-server/
22├── .env              # Environment variables (not committed to git)
23├── .env.example      # Example template (committed to git)
24├── package.json
25└── src/
26    └── ...
27```
28 
29### 2. Path Resolution
30When loading the `.env` file, use a reliable path resolution method that works both in development and production:
31 
32```typescript
33import * as dotenv from 'dotenv';
34import { fileURLToPath } from 'url';
35import { dirname, resolve } from 'path';
36import * as fs from 'fs';
37 
38// Get the directory path for loading the .env file
39const __filename = fileURLToPath(import.meta.url);
40const __dirname = dirname(__filename);
41const rootDir = resolve(__dirname, '../..'); // Adjust based on file location
42 
43// Load environment variables from .env file
44dotenv.config({ path: resolve(rootDir, '.env') });
45 
46// Validate the configuration
47if (fs.existsSync(resolve(rootDir, '.env'))) {
48  console.debug('Environment file loaded successfully');
49} else {
50  console.warn('No .env file found at', resolve(rootDir, '.env'));
51}
52```
53 
54### 3. Variable Access
55Use a helper function to safely access required environment variables:
56 
57```typescript
58const getRequiredEnv = (key: string): string => {
59  const value = process.env[key];
60  if (!value) {
61    throw new Error(`${key} environment variable is required. Please set it in your configuration.`);
62  }
63  return value;
64};
65 
66// Usage
67const apiKey = getRequiredEnv('API_KEY');
68```
69 
70### 4. MCP Server Configuration
71When configuring the MCP server in a desktop application like Claude Desktop, provide the environment variables directly:
72 
73```json
74{
75  "mcpServers": {
76    "your-mcp-server": {
77      "command": "/path/to/your-mcp-server/build/index.js",
78      "env": {
79        "API_KEY": "your-api-key-here",
80        "OTHER_CONFIG": "other-value"
81      }
82    }
83  }
84}
85```
86 
87## Common Issues
88 
89### Path Resolution
90- **Issue**: The `.env` file can't be found at runtime
91- **Solution**: Ensure the path is correctly calculated relative to the file location
92- **Debugging**: Add path logging to verify the correct paths are being used
93 
94### ES Modules vs CommonJS
95- **Issue**: `require('fs')` not working in ES modules
96- **Solution**: Use `import * as fs from 'fs'` with ES modules
97- **Verification**: Check your `package.json` for `"type": "module"`
98 
99### Environment Precedence
100Environment variables from the system take precedence over those in the `.env` file. When debugging, check both sources.
101 
102## Best Practices
103 
1041. **Never commit** `.env` files to version control
1052. **Always provide** an `.env.example` template
1063. **Validate** required environment variables at startup
1074. **Use path resolution** that works in all environments
1085. **Document** all required environment variables in your README
109