Piwik PRO MCP Server

Instructions

    This tool provides comprehensive guidance for using variable templates with both create_variable
    and update_variable operations. It includes complete field mutability information to help you
    understand which fields can be modified after creation.

    Args:
        template_name: Name of the variable template to get details for
                      Available templates include: 'data_layer', 'custom_javascript', 'constant'

    Returns:
        Dictionary containing complete variable template information including:
        - template_name and display_name
        - description and ai_usage_guide
        - mcp_usage: Separate guidance for create_variable and update_variable
        - required_attributes, optional_attributes, read_only_attributes
        - field_mutability_guide: Detailed explanation of field editability
        - complete_examples: Working examples for both create and update operations
        - troubleshooting and best practices

    Examples:
        # Get dataLayer variable template info
        template = templates_get_variable(template_name='data_layer')

        # Get custom JavaScript variable template info
        template = templates_get_variable(template_name='custom_javascript')

    Field Mutability Overview:
        ✅ Editable: name, is_active, template-specific options (can be updated anytime)
        ⚠️ Create-only: variable_type (set during creation, immutable after)
        🚫 Read-only: created_at, updated_at (auto-generated, never user-modifiable)

    Workflow:
        1. Use templates_list_variables() to see all available templates
        2. Use this tool to get specific requirements and mutability info for your chosen template
        3. Use variables_create() with the template information to create variables
        4. Use variables_update() with editable fields only to update variables
    

Implementation Reference

• src/piwik_pro_mcp/tools/tag_manager/templates.py:334-375 (handler)

  MCP tool handler and registration for templates_get_variable. Decorated with @mcp.tool, defines the input schema via type hints (template_name: str -> dict), and delegates logic to helper function get_variable_template.

  @mcp.tool(annotations={"title": "Piwik PRO: Get Variable Template", "readOnlyHint": True})
  def templates_get_variable(template_name: str) -> dict:
      """Get detailed information about a specific Piwik PRO Tag Manager variable template.
  
      This tool provides comprehensive guidance for using variable templates with both create_variable
      and update_variable operations. It includes complete field mutability information to help you
      understand which fields can be modified after creation.
  
      Args:
          template_name: Name of the variable template to get details for
                        Available templates include: 'data_layer', 'custom_javascript', 'constant'
  
      Returns:
          Dictionary containing complete variable template information including:
          - template_name and display_name
          - description and ai_usage_guide
          - mcp_usage: Separate guidance for create_variable and update_variable
          - required_attributes, optional_attributes, read_only_attributes
          - field_mutability_guide: Detailed explanation of field editability
          - complete_examples: Working examples for both create and update operations
          - troubleshooting and best practices
  
      Examples:
          # Get dataLayer variable template info
          template = templates_get_variable(template_name='data_layer')
  
          # Get custom JavaScript variable template info
          template = templates_get_variable(template_name='custom_javascript')
  
      Field Mutability Overview:
          ✅ Editable: name, is_active, template-specific options (can be updated anytime)
          ⚠️ Create-only: variable_type (set during creation, immutable after)
          🚫 Read-only: created_at, updated_at (auto-generated, never user-modifiable)
  
      Workflow:
          1. Use templates_list_variables() to see all available templates
          2. Use this tool to get specific requirements and mutability info for your chosen template
          3. Use variables_create() with the template information to create variables
          4. Use variables_update() with editable fields only to update variables
      """
      return get_variable_template(template_name)

• src/piwik_pro_mcp/tools/tag_manager/templates.py:110-126 (helper)

  Core helper function that implements the logic for retrieving the variable template by loading the corresponding JSON asset file and handling errors with available templates list.

  def get_variable_template(template_name: str) -> Dict[str, Any]:
      try:
          assets_dir: Path = get_assets_base_path() / "tag_manager" / "variables"
          template_file: Path = assets_dir / f"{template_name}.json"
  
          if not template_file.exists():
              available_templates = list_template_names(assets_dir)
              available_msg = (
                  f" Available variable templates: {', '.join(available_templates)}" if available_templates else ""
              )
              raise RuntimeError(f"Variable template '{template_name}' not found.{available_msg}")
  
          return load_template_asset(template_file)
  
      except Exception as e:
          raise RuntimeError(f"Failed to get variable template information: {str(e)}")