variables_create
Create new variables in Piwik PRO Tag Manager by specifying attributes like name and type. Supports data layer, custom JavaScript, and other variable templates for analytics configuration.
Instructions
Create a new variable in Piwik PRO Tag Manager using JSON attributes.
Only variable types listed by `templates_list_variables()` are supported. Any other type will be refused.
This tool uses a simplified interface with 2 parameters: app_id and attributes.
Use tools_parameters_get("variables_create") to get the complete JSON schema
with all available fields, types, and validation rules.
💡 TIP: Use these tools to discover available templates and their requirements:
- templates_list_variables() - List all available variable templates
- templates_get_variable(template_name='data_layer') - Get complete template info with field mutability
Args:
app_id: UUID of the app
attributes: Dictionary containing variable attributes for creation. Required fields are
'name' and 'variable_type'. Field 'is_active' is optional.
Returns:
Dictionary containing created variable information including:
- data: Created variable object with id, name, template, and attributes
- Variable configuration and value settings
Parameter Discovery:
Use tools_parameters_get("variables_create") to get the complete JSON schema
for all available fields. This returns validation rules, field types, and examples.
Template Discovery:
Use piwik_get_available_variable_templates() to see all available templates, then
use piwik_get_variable_template(template_name) for detailed template information.
Examples:
# Get available parameters first
schema = tools_parameters_get("variables_create")
# Discover available templates
templates = templates_list_variables()
template_info = templates_get_variable(template_name='data_layer')
# Create data layer variable
attributes = {
"name": "Order Total",
"variable_type": "data_layer",
"data_layer_variable_name": "ecommerce.purchase.value",
"default_value": "0"
}
# Create custom JavaScript variable
attributes = {
"name": "User Status",
"variable_type": "custom_javascript",
"value": "return localStorage.getItem('userId') ? 'logged_in' : 'guest';"
}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app_id | Yes | ||
| attributes | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes |
Implementation Reference
- MCP tool handler for 'variables_create': decorated with @mcp.tool and delegates to the create_variable helper function.
@mcp.tool(annotations={"title": "Piwik PRO: Create Variable"}) def variables_create(app_id: str, attributes: dict) -> TagManagerSingleResponse: """Create a new variable in Piwik PRO Tag Manager using JSON attributes. Only variable types listed by `templates_list_variables()` are supported. Any other type will be refused. This tool uses a simplified interface with 2 parameters: app_id and attributes. Use tools_parameters_get("variables_create") to get the complete JSON schema with all available fields, types, and validation rules. 💡 TIP: Use these tools to discover available templates and their requirements: - templates_list_variables() - List all available variable templates - templates_get_variable(template_name='data_layer') - Get complete template info with field mutability Args: app_id: UUID of the app attributes: Dictionary containing variable attributes for creation. Required fields are 'name' and 'variable_type'. Field 'is_active' is optional. Returns: Dictionary containing created variable information including: - data: Created variable object with id, name, template, and attributes - Variable configuration and value settings Parameter Discovery: Use tools_parameters_get("variables_create") to get the complete JSON schema for all available fields. This returns validation rules, field types, and examples. Template Discovery: Use piwik_get_available_variable_templates() to see all available templates, then use piwik_get_variable_template(template_name) for detailed template information. Examples: # Get available parameters first schema = tools_parameters_get("variables_create") # Discover available templates templates = templates_list_variables() template_info = templates_get_variable(template_name='data_layer') # Create data layer variable attributes = { "name": "Order Total", "variable_type": "data_layer", "data_layer_variable_name": "ecommerce.purchase.value", "default_value": "0" } # Create custom JavaScript variable attributes = { "name": "User Status", "variable_type": "custom_javascript", "value": "return localStorage.getItem('userId') ? 'logged_in' : 'guest';" } """ return create_variable(app_id, attributes) - Helper function that handles validation with VariableCreateAttributes schema, type checking, and API call to create the variable.
def create_variable(app_id: str, attributes: dict) -> TagManagerSingleResponse: try: client = create_piwik_client() # Validate attributes directly against the variable create model validated_attrs = validate_data_against_model(attributes, VariableCreateAttributes) # Convert to dictionary and filter out None values create_kwargs = {k: v for k, v in validated_attrs.model_dump(exclude_none=True).items()} # Extract required fields name = create_kwargs.pop("name") variable_type = create_kwargs.pop("variable_type") # Enforce assets-driven allowlist via model validation (retained as a safety check) allowed_variable_types = set(list_template_names("tag_manager/variables")) if variable_type not in allowed_variable_types: raise RuntimeError( f"Unsupported variable type '{variable_type}'. Use templates_list_variables() to discover options." ) response = client.tag_manager.create_variable( app_id=app_id, name=name, variable_type=variable_type, **create_kwargs ) return TagManagerSingleResponse(**response) except BadRequestError as e: raise RuntimeError( f"Failed to create variable: API request failed (HTTP {e.status_code}): {e.message}. " f"Full response: {e.response_data}" ) except Exception as e: raise RuntimeError(f"Failed to create variable: {str(e)}") - Pydantic model used for input validation of 'variables_create' tool parameters, enforcing structure and template-based variable_type validation.
class VariableCreateAttributes(BaseModel): """Attributes for creating variables with template-specific fields.""" model_config = {"extra": "allow"} # Allow additional fields for template-specific attributes name: str = Field(..., description="Variable name") variable_type: str = Field(..., description="Variable type") is_active: Optional[bool] = Field(None, description="Whether variable is active") # Data Layer variable fields data_layer_variable_name: Optional[str] = Field(None, description="Data layer property name to access") data_layer_version: Optional[str] = Field(None, description="Data layer version (1 or 2)") default_value: Optional[str] = Field(None, description="Fallback value when property is undefined") decode_uri_component: Optional[bool] = Field(None, description="Whether to decode URI components") # Custom JavaScript variable fields code: Optional[str] = Field(None, description="JavaScript code to execute") # Constant variable fields value: Optional[str] = Field(None, description="Constant value for constant variables") # URL variable fields url_component: Optional[str] = Field(None, description="URL component to extract (host, path, query, etc.)") # Cookie variable fields cookie_name: Optional[str] = Field(None, description="Name of cookie to read") # Random number variable fields min_value: Optional[int] = Field(None, description="Minimum value for random number") max_value: Optional[int] = Field(None, description="Maximum value for random number") @field_validator("variable_type") @classmethod def _validate_variable_type(cls, v: str) -> str: allowed = set(list_template_names("tag_manager/variables")) if v not in allowed: raise ValueError(f"Unsupported variable type '{v}'. Use templates_list_variables() to discover options.") return v - src/piwik_pro_mcp/tools/__init__.py:37-37 (registration)Registration call to register_variable_tools(mcp), which defines and registers the 'variables_create' handler with the MCP server.
register_variable_tools(mcp) - Mapping of 'variables_create' tool name to its VariableCreateAttributes schema model for dynamic schema retrieval.
"variables_create": VariableCreateAttributes,