# Configuration System

Stata-MCP uses a hierarchical configuration system with three levels of priority:

1. **Environment Variables** (highest priority)
2. **Configuration File** (`~/.statamcp/config.toml`)
3. **Default Values** (lowest priority)

## Configuration File

### Location

The configuration file is located at:
```
~/.statamcp/config.toml
```

On different platforms:
- **macOS/Linux**: `/home/username/.statamcp/config.toml`
- **Windows**: `C:\Users\Username\.statamcp\config.toml`

### Example Configuration

```toml
[DEBUG]
IS_DEBUG = false

[DEBUG.logging]
LOGGING_ON = true
LOGGING_CONSOLE_HANDLER_ON = false
LOGGING_FILE_HANDLER_ON = true
LOG_FILE = "~/"

MAX_BYTES = 10_000_000
BACKUP_COUNT = 5

[SECURITY]
IS_GUARD = true

[PROJECT]
WORKING_DIR = ""

[MONITOR]
IS_MONITOR = false
MAX_RAM_MB = -1

[STATA]
# Optional: Override automatic Stata detection
# STATA_CLI = "/path/to/stata-mp"
```

## Configuration Sections

### DEBUG Section

Controls debugging and logging behavior.

#### `DEBUG.IS_DEBUG`

Enable debug mode for verbose output.

- **Type**: Boolean
- **Default**: `false`
- **Environment Variable**: `STATA_MCP__IS_DEBUG`
- **Example**:
  ```bash
  export STATA_MCP__IS_DEBUG=true
  ```

#### `DEBUG.logging.LOGGING_ON`

Enable or disable all logging.

- **Type**: Boolean
- **Default**: `true`
- **Environment Variable**: `STATA_MCP__LOGGING_ON`
- **Example**:
  ```bash
  export STATA_MCP__LOGGING_ON=false
  ```

#### `DEBUG.logging.LOGGING_CONSOLE_HANDLER_ON`

Enable console output for logs.

- **Type**: Boolean
- **Default**: `false`
- **Environment Variable**: `STATA_MCP__LOGGING_CONSOLE_HANDLER_ON`
- **Example**:
  ```bash
  export STATA_MCP__LOGGING_CONSOLE_HANDLER_ON=true
  ```

#### `DEBUG.logging.LOGGING_FILE_HANDLER_ON`

Enable file logging.

- **Type**: Boolean
- **Default**: `true`
- **Environment Variable**: `STATA_MCP__LOGGING_FILE_HANDLER_ON`
- **Example**:
  ```bash
  export STATA_MCP__LOGGING_FILE_HANDLER_ON=true
  ```

#### `DEBUG.logging.LOG_FILE`

Specify the log file location.

- **Type**: Path (string)
- **Default**: `~/.statamcp/stata_mcp_debug.log`
- **Environment Variable**: `STATA_MCP__LOG_FILE`
- **Example**:
  ```bash
  export STATA_MCP__LOG_FILE="/var/log/stata-mcp/debug.log"
  ```

#### `DEBUG.logging.MAX_BYTES`

Maximum size of a single log file before rotation.

- **Type**: Integer (bytes)
- **Default**: `10_000_000` (10 MB)
- **Environment Variable**: `STATA_MCP__LOGGING__MAX_BYTES`
- **Example**:
  ```bash
  export STATA_MCP__LOGGING__MAX_BYTES=50_000_000
  ```

#### `DEBUG.logging.BACKUP_COUNT`

Number of backup log files to keep.

- **Type**: Integer
- **Default**: `5`
- **Environment Variable**: `STATA_MCP__LOGGING__BACKUP_COUNT`
- **Example**:
  ```bash
  export STATA_MCP__LOGGING__BACKUP_COUNT=10
  ```

### SECURITY Section

Controls security features.

#### `SECURITY.IS_GUARD`

Enable security guard validation for Stata dofiles.

- **Type**: Boolean
- **Default**: `true`
- **Environment Variable**: `STATA_MCP__IS_GUARD`
- **Description**: When enabled, validates all dofile code against dangerous commands and patterns before execution
- **Example**:
  ```bash
  export STATA_MCP__IS_GUARD=true
  ```

For more details, see [Security Guard Documentation](security.md).

### PROJECT Section

Controls project-specific settings.

#### `PROJECT.WORKING_DIR`

Set the working directory for Stata-MCP operations.

- **Type**: Path (string)
- **Default**: Current directory (if writable) or `~/Documents`
- **Environment Variable**: `STATA_MCP__CWD` (double underscore)
- **Description**:
  - If set and writable, all output files will be organized under `<WORKING_DIR>/stata-mcp-folder/`
  - If not set or not writable, falls back to current directory or `~/Documents`
  - **Legacy support**: `STATA_MCP_CWD` (single underscore) is still supported but deprecated
- **Example**:
  ```bash
  export STATA_MCP__CWD="/projects/my-research"
  ```

The working directory structure:
```
<WORKING_DIR>/stata-mcp-folder/
├── stata-mcp-log/      # Stata execution logs
├── stata-mcp-dofile/   # Generated do-files
├── stata-mcp-result/   # Analysis results
└── stata-mcp-tmp/      # Temporary files
```

### MONITOR Section

Controls performance monitoring features.

#### `MONITOR.IS_MONITOR`

Enable RAM monitoring for Stata processes.

- **Type**: Boolean
- **Default**: `false`
- **Environment Variable**: `STATA_MCP__IS_MONITOR`
- **Description**: When enabled, monitors Stata subprocess RAM usage during execution
- **Example**:
  ```bash
  export STATA_MCP__IS_MONITOR=true
  ```

For more details, see [Monitoring Documentation](monitoring.md).

#### `MONITOR.MAX_RAM_MB`

Maximum RAM limit in megabytes.

- **Type**: Integer
- **Default**: `-1` (no limit)
- **Environment Variable**: `STATA_MCP__RAM_LIMIT`
- **Description**:
  - `-1` means no limit (default)
  - When set to a positive value, Stata processes exceeding this limit will be terminated
- **Example**:
  ```bash
  export STATA_MCP__RAM_LIMIT=8192  # 8 GB limit
  ```

### STATA Section

Controls Stata executable detection.

#### `STATA.STATA_CLI`

Override automatic Stata detection.

- **Type**: Path (string)
- **Default**: Auto-detected based on platform
- **Description**:
  - **macOS**: `/Applications/Stata/StataMP.app/Contents/MacOS/stata-mp`
  - **Windows**: `C:\Program Files\Stata18\StataMP-64.exe`
  - **Linux**: `stata-mp` (from PATH)
- **Example**:
  ```toml
  [STATA]
  STATA_CLI = "/usr/local/stata17/stata-mp"
  ```

## Using Environment Variables

### Quick Setup

```bash
# Enable debug mode
export STATA_MCP__IS_DEBUG=true

# Set working directory
export STATA_MCP__CWD="/projects/my-analysis"

# Enable monitoring with 8GB RAM limit
export STATA_MCP__IS_MONITOR=true
export STATA_MCP__RAM_LIMIT=8192

# Disable security guard (not recommended)
export STATA_MCP__IS_GUARD=false

# Enable console logging
export STATA_MCP__LOGGING_CONSOLE_HANDLER_ON=true
```

### Priority Example

If you set the same option in multiple places:

```bash
# Config file: IS_GUARD = true
# Environment variable: STATA_MCP__IS_GUARD=false
export STATA_MCP__IS_GUARD=false

# Result: Security guard is disabled (environment variable wins)
```

## Configuration Validation

The configuration system includes built-in validation:

- **Boolean values**: Must be `true` or `false` (case-insensitive)
- **Integer values**: Must be valid integers
- **Path values**: Automatically expanded for `~` (home directory)
- **Invalid values**: Fall back to defaults automatically

## Common Configuration Patterns

### Development Setup

```toml
[DEBUG]
IS_DEBUG = true

[DEBUG.logging]
LOGGING_ON = true
LOGGING_CONSOLE_HANDLER_ON = true
LOGGING_FILE_HANDLER_ON = false
```

### Production Setup

```toml
[DEBUG]
IS_DEBUG = false

[DEBUG.logging]
LOGGING_ON = true
LOGGING_CONSOLE_HANDLER_ON = false
LOGGING_FILE_HANDLER_ON = true
MAX_BYTES = 50_000_000
BACKUP_COUNT = 10

[SECURITY]
IS_GUARD = true

[MONITOR]
IS_MONITOR = true
MAX_RAM_MB = 16384
```

### High-Performance Computing

```toml
[DEBUG]
IS_DEBUG = false

[DEBUG.logging]
LOGGING_ON = false

[MONITOR]
IS_MONITOR = true
MAX_RAM_MB = 65536  # 64 GB
```

## Troubleshooting

### Configuration Not Loading

1. Check if config file exists:
   ```bash
   ls ~/.statamcp/config.toml
   ```

2. Verify TOML syntax:
   ```bash
   python3 -c "import tomllib; tomllib.load(open('~/.statamcp/config.toml', 'rb'))"
   ```

3. Check for environment variable conflicts:
   ```bash
   env | grep STATA_MCP
   ```

### Working Directory Issues

If the working directory is not writable, Stata-MCP will fall back to `~/Documents`. To fix:

1. Check directory permissions:
   ```bash
   ls -la /your/working/directory
   ```

2. Create directory with proper permissions:
   ```bash
   mkdir -p /your/working/directory
   chmod u+w /your/working/directory
   ```

### Log Files Not Created

1. Check if logging is enabled:
   ```bash
   echo $STATA_MCP__LOGGING_ON
   ```

2. Verify log file path is writable:
   ```bash
   touch ~/.statamcp/stata_mcp_debug.log
   ```

3. Check disk space:
   ```bash
   df -h
   ```
