> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyleeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables

> Understanding variables in Pylee and how to use them effectively

# Variables

Variables in Pylee provide a flexible way to store and manage dynamic values across your MCP server configurations. They enable you to parameterize server settings, handle environment-specific configurations, and manage sensitive data securely.

## What are Variables?

Variables are named placeholders that can store values and be referenced throughout your Pylee configuration. They help you:

* **Avoid repetition**: Define values once and reuse them across multiple servers
* **Environment flexibility**: Use different values for development, staging, and production
* **Dynamic configuration**: Change server behavior without modifying configuration files
* **Template reusability**: Create configuration templates that can be customized

## Variable Types

### Environment Variables

System-level variables that are available to all processes:

```json theme={null}
{
  "mcpServers": {
    "api-server": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "API_BASE_URL": "${API_BASE_URL}",
        "API_VERSION": "${API_VERSION}"
      }
    }
  }
}
```

### Configuration Variables

Variables defined within your Pylee configuration for internal use:

```json theme={null}
{
  "variables": {
    "workspace_path": "/Users/dev/projects",
    "default_timeout": "30"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspace_path}"
      ]
    }
  }
}
```

### Runtime Variables

Variables that are computed or set during Pylee execution:

* Current timestamp
* User home directory
* System information
* Dynamic paths

## Variable Syntax

### Basic Substitution

Use `${VARIABLE_NAME}` syntax to reference variables:

```json theme={null}
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}
```

### Default Values

Provide fallback values when variables might be undefined:

```json theme={null}
{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": [
        "-m", "db_server",
        "--host", "${DB_HOST:-localhost}",
        "--port", "${DB_PORT:-5432}"
      ]
    }
  }
}
```

### Nested Variables

Variables can reference other variables:

```json theme={null}
{
  "variables": {
    "project_root": "/opt/myapp",
    "data_dir": "${project_root}/data",
    "logs_dir": "${project_root}/logs"
  }
}
```

## Built-in Variables

Pylee provides several built-in variables that are automatically available:

### System Variables

* `${HOME}`: User's home directory
* `${USER}`: Current username
* `${PWD}`: Current working directory
* `${TMPDIR}`: Temporary directory path

### Pylee Variables

* `${PYLEE_CONFIG_DIR}`: Pylee configuration directory
* `${PYLEE_VERSION}`: Current Pylee version
* `${PYLEE_ENV}`: Environment (development, production, etc.)

### Example Usage

```json theme={null}
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${HOME}/Documents"
      ]
    },
    "logs": {
      "command": "python",
      "args": ["-m", "log_server", "${PYLEE_CONFIG_DIR}/logs"]
    }
  }
}
```

## Configuration Examples

### Development Environment

```json theme={null}
{
  "variables": {
    "env": "development",
    "debug_mode": "true",
    "workspace": "${HOME}/dev/workspace"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspace}"
      ]
    },
    "api": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "ENVIRONMENT": "${env}",
        "DEBUG": "${debug_mode}",
        "API_URL": "http://localhost:3000"
      }
    }
  }
}
```

### Production Environment

```json theme={null}
{
  "variables": {
    "env": "production",
    "debug_mode": "false",
    "data_path": "/opt/app/data"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${data_path}"
      ]
    },
    "api": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "ENVIRONMENT": "${env}",
        "DEBUG": "${debug_mode}",
        "API_URL": "${PRODUCTION_API_URL}"
      }
    }
  }
}
```

### Multi-Server Configuration

```json theme={null}
{
  "variables": {
    "base_path": "/opt/services",
    "common_timeout": "60",
    "log_level": "info"
  },
  "mcpServers": {
    "service-a": {
      "command": "python",
      "args": ["-m", "service_a", "--path", "${base_path}/service-a"],
      "env": {
        "TIMEOUT": "${common_timeout}",
        "LOG_LEVEL": "${log_level}"
      }
    },
    "service-b": {
      "command": "python",
      "args": ["-m", "service_b", "--path", "${base_path}/service-b"],
      "env": {
        "TIMEOUT": "${common_timeout}",
        "LOG_LEVEL": "${log_level}"
      }
    }
  }
}
```

## Variable Precedence

Variables are resolved in the following order (highest to lowest precedence):

1. **Command-line arguments**: Variables passed via CLI flags
2. **Environment variables**: System environment variables
3. **Configuration file variables**: Variables defined in configuration files
4. **Built-in variables**: Pylee's predefined variables
5. **Default values**: Fallback values specified in variable references

## Advanced Usage

### Conditional Variables

Use different values based on conditions:

```json theme={null}
{
  "variables": {
    "database_url": "${NODE_ENV:-development}" === "production" 
      ? "${PROD_DATABASE_URL}" 
      : "postgresql://localhost:5432/dev"
  }
}
```

### Array Variables

Variables can contain arrays for multiple values:

```json theme={null}
{
  "variables": {
    "allowed_dirs": [
      "${HOME}/Documents",
      "${HOME}/Projects",
      "/tmp"
    ]
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem"
      ].concat("${allowed_dirs}")
    }
  }
}
```

### Template Variables

Create reusable server templates:

```json theme={null}
{
  "templates": {
    "python_server": {
      "command": "python",
      "args": ["-m", "${module_name}"],
      "env": {
        "PYTHONPATH": "${python_path:-/opt/app}",
        "LOG_LEVEL": "${log_level:-info}"
      }
    }
  },
  "mcpServers": {
    "data_processor": {
      "template": "python_server",
      "variables": {
        "module_name": "data_processor",
        "python_path": "/opt/data-tools"
      }
    }
  }
}
```

## Variable Validation

### Type Validation

Ensure variables have the correct type:

```json theme={null}
{
  "variables": {
    "port": {
      "type": "number",
      "value": "${PORT:-8080}",
      "min": 1,
      "max": 65535
    },
    "enabled": {
      "type": "boolean",
      "value": "${FEATURE_ENABLED:-false}"
    }
  }
}
```

### Required Variables

Mark variables as required:

```json theme={null}
{
  "variables": {
    "api_key": {
      "required": true,
      "description": "API key for external service"
    },
    "database_url": {
      "required": true,
      "description": "Database connection string"
    }
  }
}
```

## Best Practices

### Naming Conventions

* Use descriptive names: `database_connection_string` instead of `db_conn`
* Use consistent casing: `snake_case` for configuration variables
* Group related variables: `api_base_url`, `api_timeout`, `api_version`

### Organization

* Group variables by purpose or service
* Use comments to document variable usage
* Keep sensitive variables separate from configuration

### Documentation

* Document required variables and their purposes
* Provide example values
* Explain variable relationships and dependencies

### Security

* Never commit sensitive variables to version control
* Use environment variables for secrets
* Implement proper access controls for configuration files

## Troubleshooting

### Common Issues

#### Undefined Variables

```
Error: Variable 'API_KEY' is not defined
```

**Solution**: Ensure the variable is set in environment or configuration

#### Circular References

```
Error: Circular reference detected in variable 'var_a'
```

**Solution**: Remove circular dependencies between variables

#### Type Mismatches

```
Error: Expected number for 'port', got string
```

**Solution**: Ensure variable values match expected types

### Debugging Variables

Enable variable debugging to see resolution process:

```json theme={null}
{
  "debug": {
    "variables": true
  }
}
```

## Integration with Secrets

Variables work seamlessly with Pylee's secrets management:

```json theme={null}
{
  "variables": {
    "api_endpoint": "https://api.example.com/v1"
  },
  "mcpServers": {
    "api-client": {
      "command": "python",
      "args": ["-m", "api_client"],
      "env": {
        "API_ENDPOINT": "${api_endpoint}",
        "API_KEY": "${secret:api_key}"
      }
    }
  }
}
```

## Next Steps

* Learn about [Secrets](/understanding-pylee/secrets) for sensitive data management
* Explore [Server configuration](/understanding-pylee/servers) for advanced server setup
* Check the [Troubleshooting](/support/troubleshooting) guide for common variable issues